# Doc Coauthoring

> 当用户要起草 PRD / 设计文档 / 决策文档 / RFC / 提案等较重的书面文档时使用；以"上下文收集→分节精炼→读者测试"三阶段共创，逐节头脑风暴+精修产出可经受读者检验的成稿；不适用于一句话回复、随手笔记或用户明确要自由写作的场景；触发词：写文档、起草提案、PRD、设计文档、RFC

- Skill: `findscripter/doc-coauthoring` (Agent Skill)
- Install (CLI): `npx skillmds@latest add findscripter/doc-coauthoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/findscripter/doc-coauthoring/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: MIT
- Author: findscripter (https://skillmd.com/u/findscripter)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/findscripter/doc-coauthoring

---

## 何时使用

当用户要创作一篇**有分量的书面文档**时主动提议本工作流，典型信号：

- 提到写文档："写一份文档""起草提案""创建一份 spec""写个材料"。
- 提到具体文档类型：PRD、设计文档、决策文档、RFC。
- 看上去正要开启一项较重的写作任务。

**不该用（负边界）：**

- 一句话答复、随手笔记、聊天式短文本。
- 用户明确表示只想自由发挥、不要流程。
- 仅需机械翻译或格式转换，无需共创打磨。

**提议方式：** 简述三阶段——①上下文收集 ②分节精炼 ③读者测试，说明它能确保文档"换个人（或粘进另一个 Claude）也读得懂"。询问采用本流程还是自由写作。用户拒绝则自由写作；接受则进入阶段一。语气直接、按流程推进，不要推销，给用户随时调整流程的自主权。

## 步骤

### 阶段一 · 上下文收集
目标：缩小"用户已知"与"模型已知"的差距，为后续提供精准指导。

1. 先问元信息（可速记作答）：①文档类型？②主要读者？③希望读者读后产生什么影响？④有无模板/格式要求？⑤其它约束或背景？
2. 若有模板/共享文档：请用户提供。给链接则用对应集成（Slack/Teams/Google Drive/SharePoint/MCP 等）拉取；给文件则 Read 读取。
3. 若是编辑已有共享文档：读取现状，检查**无 alt-text 的图片**——提醒用户"他人用 Claude 理解此文档时看不到这些图"，征询是否生成 alt-text。
4. 信息倾倒：鼓励用户把一切背景一股脑倒出（项目背景、相关讨论、为何不用替代方案、组织/政治背景、时间压力、技术架构与依赖、干系人顾虑），不必整理。提到不认识的实体/项目时，先征得同意再用工具检索。
5. 用户倒完后，基于缺口提 **5-10 个编号问题**。
6. **退出条件**：问题已能触及边界情形与权衡、无需再解释基础概念，即上下文充分。询问是否补充，否则进入阶段二。

### 阶段二 · 分节精炼
目标：逐节通过头脑风暴、筛选、迭代构建文档。

- 先定结构：结构清晰则问从哪节开始；不清晰则按文档类型建议 3-5 个小节。**从未知最多的小节起步**（决策文档通常是核心提案，spec 通常是技术方案），摘要类小节留到最后。
- 结构确定后创建带占位符的初始骨架：有 artifact 能力用 `create_file`；否则在工作目录建 markdown 文件（如 `decision-doc.md`、`technical-spec.md`），各小节填 `[待撰写]`。

**每个小节按 6 步走：**
1. **澄清提问**：就该节提 5-10 个具体问题。
2. **头脑风暴**：按复杂度列 5-20 个编号候选点，留意被遗忘的背景或未提及的角度，末尾可再追加。
3. **筛选**：让用户标 保留/删除/合并 并附简短理由（如"保留 1,4,7""删 3（与 1 重复）""合并 11、12"）；若给自由反馈则解析其意图执行。
4. **查漏**：问还缺什么重要内容。
5. **起草**：用 `str_replace` 把占位符替换为正文，**绝不重印整篇**。
6. **迭代精修**：根据反馈逐处 `str_replace` 修改。**首节起草时务必提示用户**：不要直接改文档，而是**说明要改什么**（如"删掉 X 那条——Y 已覆盖""第三段更精炼些"），以便模型学习其风格用于后续小节。

**质量把关**：连续 3 轮无实质改动时，问"有没有能删掉而不损信息的部分"。完成 80%+ 小节后，通读全文检查：跨节连贯性、冗余/矛盾、是否有"水文/通用废话"、每句是否都有分量。全部完成后再整体复审一次。

### 阶段三 · 读者测试
目标：用一个**全新、无上下文**的 Claude 验证文档对读者是否有效，捕捉作者视而不见的盲点。

- **有子智能体能力（如 Claude Code）**：直接用 Task 起子智能体测试，无需用户介入。①预测读者会问的 5-10 个问题；②对每个问题只给"文档正文 + 该问题"调用子智能体，汇总答对/答错；③再起子智能体专项检查歧义、错误假设、内部矛盾；④发现问题则列出并回到阶段二修复对应小节。
- **无子智能体（如 claude.ai 网页）**：指导用户手动测试——开新对话，粘贴文档，逐一提问，并让"读者 Claude"给出 答案 / 是否有歧义 / 文档默认读者已知的前提；额外追问"哪里可能含糊""假设了哪些背景知识""有无内部矛盾"。据结果回流修复。
- **退出条件**：读者 Claude 持续答对且不再暴露新盲点/歧义，文档即就绪。

### 最终复核
通过读者测试后：①建议用户亲自通读（文档归其所有、质量由其负责）；②核对事实/链接/技术细节；③确认达成预期影响。收尾提示：可在附录链接本次对话以展示成文过程；用附录承载深度而不臃肿正文；收到真实读者反馈后持续更新。

## 指令

- 起草整节内容：`create_file`（有 artifact 时）。
- 所有编辑：`str_replace`，每次只改局部，永不重印全文；有 artifact 时每次编辑后给出 artifact 链接，文件模式下确认完成即可。
- 头脑风暴清单只走对话，**绝不**放进 artifact。
- 用户直接改了文档并让你读：记下其改动，作为风格偏好沿用到后续小节。

## 示例

- 触发："帮我起草一份关于切换数据库的决策文档。" → 提议三阶段工作流 → 用户接受 → 问 5 条元信息 → 信息倾倒 + 8 条澄清问题 → 建议小节"背景/核心提案/替代方案/风险/时间线"，从"核心提案"起 → 逐节 头脑风暴(12 项)→筛选→起草→精修 → 起子智能体读者测试 → 修复 2 处歧义 → 交付。
- 筛选反馈示例："保留 1,4,7,9；删 3（与 1 重复）；删 6（读者已知）；合并 11、12"。

## 注意事项

- **质量优先于速度**：每轮迭代都应带来实质改进，不为赶进度跳步。
- **不让缺口累积**：提到的任何不清楚处即时追问。
- **处理偏离**：用户想跳过某阶段→确认是否改自由写作；用户显露烦躁→承认耗时较长并提供加速办法；始终保留用户调整流程的自主权。
- 集成不可用且在 Claude.ai/App 中时，建议用户在设置里开启 connectors 以便直接拉取消息与文档。
- 不要把本工作流当作环境特定验证、测试或专家评审的替代品；缺少必要输入、权限、安全边界或成功标准时，停下来询问。

## 互见

- 本技能域：文书 / misc。
- 可衔接飞书文档/Markdown 类技能完成成稿落地（如导入在线文档、版本对比）。

---
采编自 sickn33/antigravity-awesome-skills（MIT）。