Doc Coauthoring Zh

---
name: doc-coauthoring-zh
description: 协作写文档的三阶段工作流、写技术方案、写提案、写 PRD、写设计文档、写决策文档、写 RFC、写立项材料、和 AI 一起把一篇长文档从零磨到能发。当用户说「帮我写一份技术方案」「起草一个提案」「写个设计文档」「写 PRD」「这个决策要写成文档给领导看」「写一篇 RFC」时使用。三阶段：①收集上下文——先问文档类型/读者/期望效果/模板/约束，再让用户倾倒一切背景，最后提 5–10 个编号澄清问题；②逐节精炼——从未知最多的一节开始，每节先问澄清、再头脑风暴 5–20 条候选、用户按编号取舍、查漏、起草、只做外科手术式修改，连续 3 轮无实质改动就问能不能删；③读者测试——用一个没有上下文的全新 Agent 或新对话回答预测的读者问题、找歧义和隐含假设，回炉修改直到读者不再卡住。附给用户的手动测试说明。也覆盖「拆成微服务」「把背景倒给你」「一节一节磨」这类说法。改编自 Anthropic 官方 skills 仓库的 doc-coauthoring（Apache-2.0）。
author: Captain
version: 0.1.1
display_name: "文档协作写作三阶段"
display_name_en: "Doc Co-Authoring Workflow (zh)"
description_zh: "和用户一起写方案、提案、规格、决策文档的结构化流程：先高效转移上下文，再逐节头脑风暴与外科手术式修改，最后用一个没有上下文的读者 Agent 测试文档是否真的能被读懂。"
description_en: "A structured workflow for co-authoring proposals, specs and decision docs: transfer context efficiently, build each section through brainstorming and surgical edits, then test the doc with a context-free reader agent to catch blind spots."
tags:
  - "文档协作"
  - "PRD"
  - "RFC"
  - "技术方案"
  - "设计文档"
  - "co-authoring"
  - "读者测试"
examples_zh:
  - "帮我写一份把单体拆成微服务的技术方案，走一遍协作流程"
  - "起草一个 PRD，我先把背景倒给你"
  - "这个架构决策要写成文档给评审委员会，帮我一节一节磨"
examples_en:
  - "Co-author a tech proposal for splitting the monolith, full workflow"
  - "Draft a PRD, I'll dump the background first"
  - "This architecture decision needs a doc for the review board, section by section"
metadata:
  { "openclaw": { "requires": { "bins": [] }, "os": ["darwin", "linux", "windows"], "emoji": "✍️" } }
---

# 文档协作写作三阶段

作为主动的向导，带用户走三个阶段：**收集上下文 → 逐节精炼 → 读者测试**。

## 何时提议

触发：用户提到写文档（「写个方案」「起草提案」「写规格」「写一篇」）；提到具体文档类型（PRD、设计文档、决策文档、RFC）；看起来要开始一项较大的写作任务。

先简要说明三阶段以及为什么这样做（让文档在别人读时——包括别人把它贴给 AI 读时——真的能用），问用户要走流程还是自由写。拒绝就自由写；接受就进阶段一。

## 阶段一：收集上下文

**目标：** 缩小用户知道的与你知道的之间的差距，为后面的聪明引导打底。

**起手五问：** 1) 文档类型？2) 主要读者？3) 读者读完希望产生什么效果？4) 有模板或固定格式吗？5) 其他约束或背景？告诉用户可以用速记或任何顺手的方式倾倒。

有模板就要来；给的是共享文档链接或文件，就用可用的集成或读取工具拿到。编辑已有的共享文档时，检查没有替代文本的图片：解释别人用 AI 读这份文档时看不到图片，问要不要生成替代文本，需要则请用户逐张贴进对话。

**倾倒背景：** 鼓励用户把所有背景倒出来，不用整理：项目/问题背景、相关讨论或共享文档、为什么不用其他方案、组织语境（团队动态、过往事故、政治）、时间压力、技术架构或依赖、干系人的顾虑。提供多种方式：意识流倾倒、指向可读的频道或帖子、链接共享文档。有集成（聊天工具、文档存储等）就说明可以直接拉取；没有就建议用户开启连接器或直接粘贴。

过程中：用户提到你不认识的实体或项目，问要不要搜连接的工具、等确认再搜；持续记录学到了什么、还有什么不清楚。

**澄清问题：** 用户倾倒完（或给了大量背景）后，根据缺口生成 5–10 个编号问题。告诉用户可以速记回答（「1：是；2：见某频道；3：不行，因为要向后兼容」）、给更多文档、指向频道，或继续倾倒。

**退出条件：** 你的问题已经能触及边界情况和权衡，而不需要别人解释基础——说明上下文够了。问用户还有没有要补的，没有就进阶段二。

## 阶段二：逐节精炼

**目标：** 通过头脑风暴、取舍与迭代，一节一节把文档建起来。向用户说明每节的五步：问澄清 → 头脑风暴 5–20 条 → 用户取舍 → 起草 → 外科手术式修改。

**章节顺序：** 结构清楚时问从哪节开始，建议从未知最多的那节起（决策文档通常是核心提案，规格通常是技术方案；摘要最后写）。用户不知道要哪些节时，按文档类型与模板建议 3–5 节，问是否可行。

**结构定下后：** 创建带占位文本（「[待写]」）的初始骨架——能用产物就用产物，否则在工作目录建一个命名得当的 Markdown 文件（如 `decision-doc.md`、`technical-spec.md`）。给出路径或链接，开始逐节填。

**每一节：**
1. **澄清**：宣布开始写 [节名]，问 5–10 个针对该节的具体问题；用户可速记或只说重点。
2. **头脑风暴**：按复杂度列 5–20 条可能要写的内容，特别留意用户分享过但可能忘了的背景、以及还没提到的角度；结尾问要不要再多想几条。
3. **取舍**：请用户说保留、删除、合并哪些，附简短理由，帮助你学习优先级（例：「留 1,4,7,9」「删 3（与 1 重复）」「删 6（读者已知）」「合并 11 和 12」）。用户给的是自由反馈（「差不多，但……」）就提取偏好照办。
4. **查漏**：根据选中的内容问这一节还缺什么重要的。
5. **起草**：把该节占位文本替换成正文。请用户通读并说要改什么；提醒具体一些有助于后面几节学习。**首节起草时加一条说明**：不要直接改文档，而是告诉你改什么（「删掉 X 这条，Y 已经覆盖」「第三段更精炼」），这样你能学到风格。
6. **迭代修改**：用精确替换做修改，绝不重印整篇；用产物就每次改完给链接，用文件就确认改完。用户直接改了文档再让你读，记下他们的改法作为偏好。

**质量检查：** 连续 3 轮没有实质改动时，问有没有可以删掉又不丢重要信息的内容。一节完成，确认并问是否进下一节。全部章节重复。

**接近完成（80% 以上）时**，宣布要通读全文，检查跨节的流畅与一致、冗余或矛盾、任何「凑数」的空话、每句是否都有分量。全部起草并精炼后再做一次整体审阅，给最终建议，问是否进入读者测试。

## 阶段三：读者测试

**目标：** 用一个**没有上下文**的全新读者测试文档，抓作者自己看不见的盲点。

**能派子代理时**（如在 Claude Code 里）直接测：
1. **预测读者问题**：生成 5–10 个读者在找这份文档时会真实提出的问题。
2. **子代理测试**：对每个问题，只给子代理文档内容和问题；总结「读者 AI」答对了什么、答错了什么。
3. **额外检查**：让子代理找歧义、错误假设、内部矛盾。
4. **报告并修**：列出读者卡住的具体问题，回到阶段二修对应章节。

**不能派子代理时**，请用户手动测：
1. 一起预测 5–10 个读者问题（他们会在 AI 对话里怎么问？）。
2. 测试步骤：开一个全新的 AI 对话；把文档粘进去（或给可访问的共享链接）；逐个问预测的问题，并要求读者 AI 每题给出答案、哪里模糊不清、文档假设读者已知什么。核对答对还是误读。
3. 再问读者 AI：「这份文档哪里对读者可能含糊？」「它假设读者已有哪些知识或背景？」「有没有内部矛盾或不一致？」
4. 请用户反馈读者 AI 答错或卡住的地方，回炉修改。

**退出条件（两种方式通用）：** 读者 AI 持续答对、不再冒出新的缺口或歧义。

## 最终审阅

读者测试通过后：建议用户自己做最后通读（文档是他们的，质量由他们负责）；建议复核事实、链接、技术细节；请他们确认达到了想要的效果。问要不要再来一轮审阅。收尾提示：可在附录链接这次对话，让读者看到文档是怎么形成的；用附录承载深度而不撑大正文；收到真实读者反馈后持续更新。

## 产出
最终交付是一份读者测试通过的文档：能用产物就发产物，否则在工作目录建一个命名得当的 Markdown 文件（如 `decision-doc.md`）；正文不留「[待写]」占位；可在附录链接本次协作对话。产出前必须走完阶段三的退出条件——读者 AI 持续答对、不再冒出新的缺口或歧义。

```
交付前自检：
- [ ] 每一节都已从占位文本替换成正文
- [ ] 走完读者测试，读者 AI 不再卡在同一个问题上
- [ ] 用户已确认达到了想要的效果
```

## 引导要点

- **语气**：直接、按流程走；理由只在影响用户行为时简述；不推销方法，执行就是。
- **偏离处理**：用户想跳过某阶段就问是否改为自由写；用户显得不耐烦就承认比预期久、提出加速办法；始终让用户有调整流程的权力。
- **上下文管理**：缺什么就当场问，不让缺口累积。
- **产物管理**：起草整节用创建文件；所有修改用精确替换；每次改动后给链接；头脑风暴列表放对话里，不进产物。
- **质量优先**：不赶进度；每轮迭代都要有实质改进；目标是一份真的能被读懂的文档。

---
改编自 [anthropics/skills](https://github.com/anthropics/skills) 的 `doc-coauthoring`（Apache-2.0）。改动见 ATTRIBUTION.md。