# 文档协作撰写

> 通过结构化工作流协作撰写文档、提案、规格与决策文档。三阶段：收集上下文、迭代精修与读者测试。



Tags: 写作, 协作, 文档


## Example Prompts

- 用结构化反馈循环协作撰写技术设计文档
- 通过引导迭代起草产品需求文档
- 撰写并对 RFC 或决策文档做读者测试

URL: https://rakenne.app/zh-cn/skills/doc-coauthoring/index.md

Try this skill: https://rakenne.app/a/?skill=doc-coauthoring



## 概述

通过结构化工作流协作撰写文档、提案、规格与决策文档。三阶段：收集上下文、迭代精修与读者测试。

## 开始使用

将您的资料来源放入项目工作区，然后激活*文档协作撰写*技能。代理将逐步引导您完成流程。

## 示例对话

> **您：** 我想写一页决策文档，关于把我们的认证迁移到 OAuth2。可以用结构化工作流吗？
>
> **代理：** 可以。我们分三阶段：(1) 收集上下文 — 我会问受众、期望效果和是否有模板；(2) 精修 — 用头脑风暴和修改逐节构建；(3) 读者测试 — 看新读者能否从文档中回答关键问题。先确认：主要受众是谁？他们读完后应该做什么？有没有现成模板或格式？
>
> **您：** 受众是工程负责人和安全。目标是得到 go/no-go。没有模板，只要结构清晰的章节。
>
> **代理：** 建议结构：背景与问题、考虑的方案、建议、风险与缓解、下一步。我们从「考虑的方案」和「建议」开始，因为未知最多。请把您掌握的所有上下文发给我（约束、过往讨论、为何不用其他方案）；我会追问，然后我们按节头脑风暴和起草。准备好发上下文了吗？
>
> **您：** [提供上下文。]
>
> **代理：** 已创建 `decision-doc-auth-oauth2.md` 并填入占位符。从「建议」一节开始：根据您提供的内容整理了 8 个可能要点。您希望保留、删除或合并哪些？[列出选项。] 您选定后我会起草该节并一起迭代。

## 示例输出摘录

以下为通过协作撰写工作流产出的决策文档代表性摘录。

---

# 决策：将认证迁移至 OAuth2

## 背景与问题

当前基于 cookie 的认证不支持移动端与第三方集成。我们需要一个适用于 Web、移动端和 API 的标准、可维护认证层。

## 考虑的方案

| 方案 | 优点 | 缺点 |
|------|------|------|
| 维持现有系统 | 无迁移成本 | 不满足移动/API 需求 |
| OAuth2 + OIDC | 行业标准、库支持、与现有技术栈匹配 | 迁移与密钥管理投入 |
| 自建 token 层 | 完全可控 | 非标准、长期成本更高 |

## 建议

采用 OAuth2 与 OpenID Connect 作为身份方案。使用 [Provider X] 负责签发，沿用现有用户存储。第一阶段：Web 与 API；第二阶段：移动端。时间：8 周至试点，12 周至全面上线。

## 风险与缓解

- **风险：** Token 撤销与会话失效。**缓解：** 短期有效的 access token、refresh 轮换及在第二阶段前提供撤销端点。
- **风险：** 密钥轮换。**缓解：** 自动化轮换与交接期双密钥支持。

## 下一步

1. 安全对供应商与流程的签字（第 1 周）。
2. 实现签发端并接入 Web 应用（第 2–6 周）。
3. 与内部 API 使用方试点（第 7–8 周）。


---

Back to [Skill Library](https://rakenne.app/zh-cn/skills/index.md)