anthropic-doc-coauthoring
结构化文档协作工作流，适合技术方案、PRD、RFC。
评分明细
适用场景
anthropic-doc-coauthoring 快速入门
让 AI 像资深 tech writer 一样,跟你”一起”打磨技术文档。
这是什么?解决什么问题?
anthropic-doc-coauthoring 是 Anthropic 在 anthropics/skills 仓库下提供的一个 Skill,核心目的是让 AI 编程助手在帮你写”正式文档”时,不再一次性吐出长篇大论然后等改稿,而是走一个三阶段结构化流程:
- 收集(Collect):AI 主动问你关键问题(读者是谁?成功标准?约束条件?),不跳过这一步直接开写。
- 大纲(Outline):基于你的回答,先产出文档结构、章节顺序、每章大致要点,你点头后再细化。
- 填充(Expand):在每章内部,按”先论点后论据”的顺序,逐段把内容铺出来。
这个 Skill 解决的问题,是当下 AI 写作最常见的一个痛点:你让 AI “写一份 RFC”,它噼里啪啦给你 5000 字,结果读者画像不对、约束条件没写、改起来比从头写还累。
它适合的场景:
- 写 RFC(Request for Comments)请求团队评审架构方案。
- 写 PRD(Product Requirements Document)向产品/设计同步需求。
- 写技术方案给上级汇报。
- 写对外的技术博客、调研报告。
- 写 Postmortem(事故复盘)报告。
准备工作
- 一个支持 Skill 加载的 AI 编程助手(Claude Code 体验最好,Cursor / Cline 也能用)。
- 一个相对安静的环境,你需要集中回答 AI 的提问。
- Clone 仓库:
git clone https://github.com/anthropics/skills.git - 软链 Skill:
ln -s skills/doc-coauthoring ~/.claude/skills/doc-coauthoring
3 步快速上手
第 1 步:安装 Skill
重启 AI 助手,Skill 生效。
第 2 步:验证安装
向 AI 发送请求:
“我要写一份关于’把单体应用拆成微服务’的 RFC,请按 doc-coauthoring 流程,先问我几个关键问题再开始。”
如果 AI 没有直接开始写 RFC,而是先问”目标读者是谁?成功标准是什么?时间窗?约束条件?“,说明 Skill 加载成功。
第 3 步:用 Skill 跑第一个任务
下面是一段你和 AI 的真实对话流程示例(你的输入 + AI 的输出):
第一轮 你: “我要写一份关于’用户登录从 MD5 升级到 Argon2’的 RFC,请按 doc-coauthoring 走流程。”
第一轮 AI: “好的,在开始之前请先回答以下几个问题:
- 这份 RFC 的主要读者是谁?(后端 / 全员 / 管理层?)
- 升级的紧迫程度?(安全事件驱动 / 计划内优化?)
- 需要兼容老用户的历史密码吗?(强制重置 / 懒升级 / 双重哈希过渡?)
- 期望的灰度策略?(全量 / 白名单 / 百分比?)
- 是否涉及第三方登录(OAuth / 手机号)?需要单独考虑吗?”
第二轮 你: “后端读者为主,这次是有安全团队工单驱动的;老用户必须兼容,采用双重哈希过渡;灰度先 5% 白名单观察一周。第三方登录不受影响。”
第二轮 AI: “好的,根据你的回答,我先拟一份大纲:
# 用户密码哈希升级 RFC
## 1. 背景与目标
- 现有 MD5 哈希的安全风险
- 升级到 Argon2id 的预期收益
## 2. 影响面
- 仅自有账号,第三方登录不受影响
- 老用户透明升级路径
## 3. 方案设计
- 新用户:Argon2id 默认参数
- 老用户:首次登录时,verify(md5) → 重新哈希为 Argon2id
- 数据库 schema 演进(hash_algo, hash_params 字段)
## 4. 灰度与回滚
- 5% 白名单 → 20% → 100%
- 回滚开关
## 5. 监控指标
- 登录失败率、CPU 占用、密码校验 P99
## 6. 时间线
- 第 1 周:代码 + 测试
- 第 2 周:灰度
- 第 3 周:全量
## 7. 风险与未决问题
请确认大纲是否需要调整?”
第三轮 AI 会在你点头后,逐章展开内容,每章写完会问”这一章要不要补充?”。整个流程下来,RFC 不会有”AI 一口气 5000 字然后你无从下口改”的问题。
常见踩坑
- 跳过提问直接写。很多用户嫌 AI 问太多,回一句”你自己定”,结果产出的文档读者画像错位。Skill 强调:回答问题本身就是文档质量的一部分。
- 大纲阶段不仔细看。很多人只看了第一段就点头,导致后面章节结构有问题,最后返工。
- 不指定读者画像。“全员”是最差的回答,一份文档不可能同时让实习生和 VP 都看懂。Skill 建议主读者 1 个,次读者 1-2 个。
- AI 写得太啰嗦。RFC 不是博客,一段说一件事。Skill 提醒:能用列表别用段落,能用表格别用列表。
- 忽略”未决问题”。RFC 写到最后总是漏掉”未决问题”这一节,导致评审会上被反复追问同样的问题。Skill 强制要求最后一节。
- 不标版本和日期。正式文档没有版本号,迭代几次后根本不知道哪一版是最终版。Skill 建议 frontmatter 里带
version和lastUpdated。
初级用法
用法 1:写 PRD 给产品评审。明确标注”目标读者:产品总监 + 研发 leader”,产出的 PRD 重点在”为什么做”和”成功指标”,不会陷入技术细节。
用法 2:写技术调研报告。用”现状 / 候选方案 / 决策 / 后续”四段式,适合做选型决策(比如”我们该用 Postgres 还是 MySQL”)。
用法 3:写事故复盘(Postmortem)。强调”时间线 / 根因 / 改进项 / 责任划分”,避免”甩锅式”复盘。
高级用法
玩法 1:RFC 加决策记录(ADR)。在 RFC 末尾附”决策记录”,把”我们为什么选 A 不选 B”写清楚,半年后回看不用再问。
玩法 2:多读者版本。让 AI 基于同一份事实,产出”给后端看""给产品看""给老板看”三个版本,主版本以外可以精简。
玩法 3:异步协作。把 AI 产出的初稿放到飞书 / Notion,团队成员在文档上 comment,AI 根据 comment 再迭代,形成”AI 起草 + 人工 review”的标准流程。
小技巧
- 回答 AI 提问时尽量具体。“紧迫”不如”安全工单 #1234 提到”;“白名单”不如”5% 内部员工账号”。
- 用 markdown 表格做对比。多个候选方案对比时,表格比段落清晰 10 倍。
- 每个章节控制在 1 屏内。超过 1 屏的章节读者会走神,Skill 建议加二级标题切分。
- 把”未决问题”显式列出来。比假装”我们已经想清楚了”更让人信任,因为评审者知道”这些点我们也没想透,等讨论”。
- 文档完成后跑一遍 spellcheck。
vale或proselint可以检查技术文档的语气一致性,Skill 建议加进 CI。
参考链接
- anthropic-doc-coauthoring Skill 路径:https://github.com/anthropics/skills/tree/main/skills/doc-coauthoring
- Google 工程实践文档:https://google.github.io/eng-practices/
- 微软 RFC 模板:https://github.com/microsoft/rfr
- Vale linter:https://vale.sh/
- Notion 团队 RFC 模板:https://www.notion.so/templates/engineering-rfc
本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。
doc-coauthoring Skill 多维度简评
类别：沟通写作 / 协作 仓库：anthropics/skills 核心价值：让 Claude 成为你的主动引导型写作伙伴，而不是被动响应工具
一、核心定位与价值
普通的”让 AI 帮我写文档”流程是这样：
你："帮我写一份 RFC"
AI：（立刻写 1000 字文档）
你："不对，我想的不是这个..."（叹气）
doc-coauthoring Skill 把这个流程倒过来：
你："帮我写一份 RFC"
AI："好的。我们用 3 阶段工作流：
1. 上下文收集（我问你答）
2. 精炼结构（迭代每段）
3. 读者测试（fresh Claude 检验）
要不要试？"
你："试！"
它的核心创新是**“主动引导 + 3 阶段门禁”**——不是写完给你看，而是陪你一起写。
二、3 阶段工作流详解
阶段 1：上下文收集（Context Gathering）
目标：缩小”你知道 vs Claude 知道”的差距
1.1 触发条件
用户提到以下任一时启用：
- “write a doc”, “draft a proposal”, “create a spec”, “write up”
- “PRD”, “design doc”, “decision doc”, “RFC”
1.2 初始元问题
首先问 4 个元问题：
- 文档类型？（技术规范 / 决策文档 / 提案 / RFC）
- 主要受众？（工程师 / 高管 / 客户 / 跨团队）
- 预期影响？（读了之后读者会做什么决策 / 行动）
- 有模板吗？（公司模板 / 行业标准 / 自由发挥）
1.3 信息倾倒（Info Dumping）
鼓励用户一次性倾倒所有上下文：
- 项目/问题背景
- 团队讨论或共享文档
- 为什么不用替代方案
- 组织背景（团队动态、历史事件、政治因素）
- 已考虑的方案
- 成功指标/标准
关键：鼓励一次性分享，而不是挤牙膏。
1.4 追问（3-5 个一批）
围绕缺失信息追问：
- 不清晰的关键决策
- 缺失的约束
- 受众或目标不明确
1.5 模板处理
- 用户提供模板 → 用 Read 工具读取
- 用户给链接 → 用相应集成拉取
- 用户给文件 → 读取
- 已有共享文档 → 读取当前状态
1.6 图片处理
如果文档中插入图片但没有 alt-text：
- 警告：其他用 Claude 读这文档的人/AI 看不到
- 建议：让用户把图片贴到对话生成 alt-text
阶段 2：精炼与结构（Refinement & Structure）
目标：通过迭代逐段构建文档
2.1 提出大纲
基于文档类型提供常用结构模板：
技术规范（Technical Spec）：
- 摘要 / TL;DR
- 问题陈述
- 目标 / 非目标
- 提议方案
- 备选方案
- 风险与缓解
- 落地计划
- 开放问题
决策文档（Decision Doc / ADR）：
- 背景
- 决策
- 理由
- 备选方案
- 后果
提案（Proposal）：
- 背景
- 提案
- 收益
- 成本
- 风险
- 下一步
2.2 增量起草
不要一次性写完整篇，而是：
- 写一段（或部分段）
- 询问反馈
- 整合修改
- 移至下一段
关键原则：
- ✅ 让用户参与，但不要每句都询问批准
- ✅ 提供具体草稿，让用户能反应
- ❌ 不要在没共识的情况下继续写
2.3 保持一致性
整个起草过程中：
- 术语统一
- 叙事与目标/受众保持一致
- 跟踪开放问题
- 发现不一致时主动指出并建议修复
阶段 3：读者测试（Reader Testing）
目标：确保文档对没有上下文的人也有效
3.1 测试方法
当文档草稿足够好时：
- 让用户把文档粘贴到全新的 Claude 会话（或模拟这个效果）
- 指示这个”新读者”：
- 总结文档
- 指出不清楚的部分
- 列出仍有的问题
- 点出作者似乎在做的假设
3.2 修复盲点
根据读者反馈：
- 补充缺失的上下文
- 澄清混乱的段落
- 让假设显式化
- 改进结构/流程
3.3 重复测试
高风险文档重复测试直到满意。
三、为什么这个 Skill 如此重要
3.1 上下文传递效率
普通模式：作者 → 文档 → 读者 → 多次询问作者 → 最终理解 本 Skill 模式：作者 + Claude 协作 → 文档 → 读者一次理解
节省时间：减少 50% 的来回沟通
3.2 文档质量提升
3 阶段强制覆盖了最常缺失的：
- 受众明确化
- 上下文充分
- 读者测试验证
3.3 审阅者信心
读者读到的不再是”作者自己懂但写不清”的文档，而是经过 fresh reader 测试的可读文档。
四、6 大实战场景
场景 1：技术 RFC
用 doc-coauthoring 帮我写一份"我们从 MongoDB 迁移到 PostgreSQL"的 RFC。
Skill 自动流程：
- 问你 4 个元问题（文档类型、受众、影响、模板）
- 让你倾倒上下文（当前 MongoDB 痛点、团队经验、迁移成本）
- 追问（迁移时间、兼容性、回滚方案）
- 提出 RFC 大纲
- 逐段起草
- 读者测试
- 输出最终版
场景 2：PRD
用 doc-coauthoring 帮我写"用户积分系统"的 PRD。
Skill 关键引导：
- 追问：积分怎么获取 / 消耗？过期规则？防刷机制？
- 决策记录：为什么这套规则？
- 受众：PM / 工程师 / 高管 / 客服
场景 3：决策记录（ADR）
用 doc-coauthoring 帮我做 ADR-001："为什么我们用 PostgreSQL 而不是 MongoDB"。
Skill 重点：
- 备选方案对比
- 决策理由的可信度
- 后果的清晰描述
场景 4：事故复盘（Postmortem）
用 doc-coauthoring 帮我写这次线上事故的 Postmortem。
Skill 强调：
- 时间线
- 根因（不只是症状）
- 影响范围（量化）
- 短期修复 + 长期改进
- 不甩锅文化
场景 5：入职文档
用 doc-coauthoring 帮我写"新成员入职指南"。
Skill 突出：
- 受众：新人（无背景知识）
- 关键决策：为什么这样做
- 工具 / 资源 / 联系人
场景 6：客户提案
用 doc-coauthoring 帮我给 XX 客户写一份技术方案提案。
Skill 关键：
- 客户痛点（而非你的能力）
- 投资回报（ROI）
- 风险与缓解
- 决策路径
五、安装
5.1 命令
# Claude Code
/plugin install example-skills@anthropic-agent-skills
# 通用
npx skills add anthropics/skills --skill doc-coauthoring
5.2 触发示例
用户：用 doc-coauthoring 帮我写份 API 设计文档
用户：我要起草一份关于缓存策略的提案
用户：帮我创建产品 PRD
用户：用 doc-coauthoring 工作流起草一份事故复盘
六、5 大常见错误
错误 1：跳过阶段 1
错误：直接给一堆上下文，让 Claude 开始写
正确：让 Skill 主动引导提问
错误 2：每句都要批准
错误：每写一句就问"这样行吗？"
正确：写完整段才询问反馈
错误 3：忽略受众
错误：不区分读者，让 Claude 写得很"AI 范"
正确：明确受众，调整语言深度
错误 4：不更新就停
错误：写完一段就停
正确：保持一致性，跨段追踪
错误 5：跳过读者测试
错误：写完直接发布
正确：fresh Claude 测试，找出盲点
七、5 条反合理化
| 借口 | 反驳 |
|---|---|
| ”我自己写更快” | 协作的价值是”让读者快”，不是”让作者快" |
| "三阶段太繁琐” | 前期慢，后期快，整体快 2 倍 |
| ”AI 不懂我的业务” | 倾倒上下文 = 给它业务知识 |
| ”读者测试没必要” | 90% 的文档对没读过的人来说难懂 |
| ”我没时间做完整流程” | 高风险文档（RFC/ADR）必须有，低风险可省 |
八、与其他 Skill 配合
| Skill | 何时切换 |
|---|---|
| doc-coauthoring | 起草 RFC / PRD / ADR |
| internal-comms | 写完后的内部通知 |
| mcp-builder | 技术 RFC 涉及 MCP 时 |
| security-and-hardening | 安全相关 RFC |
九、与其他 Skill 对比
| Skill | 区别 |
|---|---|
| doc-coauthoring | 协作式，3 阶段门禁 |
| internal-comms | 单向通知（周报、公告） |
| doc-coauthoring vs 普通 prompt | 主动引导 vs 被动响应 |
十、Q&A
Q: 适合所有文档吗？ A: 高风险、需要审阅的文档（RFC/PRD/ADR）。简短通知用 internal-comms。
Q: 3 阶段可以跳过吗？ A: 紧急场景可压缩阶段 2，但仍要阶段 1 和 3。
Q: 文档要保密怎么办？ A: Claude 不会上传任何内容，但敏感场景请用企业版或本地部署。
Q: 多语言支持？ A: 文档语言由用户决定，Skill 支持任意语言。
Q: 多人协作时呢？ A: 一人主导，其他人审阅。可多人轮流当”读者测试”角色。
Q: 输出格式？ A: Markdown / 任何文本格式。也支持 Word / PDF（链式调用 docx / pdf Skill）。
Q: 需要付费 Claude 吗？ A: 建议 Sonnet 4.6+ 或 Opus 4.6+。
十一、6 条实战技巧
- 明确退出机制：用户可以说”我自己写”，跳过整个流程
- 保持耐心：阶段 1 问得越多，阶段 2 写得越好
- 批量化追问：一次问 3-5 个问题，不要一个一个
- 提供模板：模板能让阶段 2 更快
- 关注”假设”：读者测试找出的最大问题是隐藏假设
- 建立文档库：团队多次使用积累出”文档模式库”
十二、总结
核心价值：
- 把”AI 写文档”升级为”AI 协作写文档”
- 3 阶段门禁确保读者能懂
- 强制结构化降低沟通成本
适用人群：
- 技术负责人（写 RFC / ADR）
- 产品经理（写 PRD）
- 团队领导（写决策文档）
投入产出比：⭐⭐⭐⭐⭐（5/5）—— 高频文档协作场景必装。
配套文档：internal-comms 通知
参考资料
快速安装
git clone https://github.com/anthropics/skills.gitln -s skills/doc-coauthoring ~/.claude/skills/doc-coauthoring