doc-coauthoring

文档协作撰写工作流

此技能提供了一套结构化工作流，引导用户协作创建文档。请积极引导用户，带领他们完成三个阶段：收集背景信息、完善与组织结构，以及读者测试。

运行时约定

在提供连接器、工件或读者测试子 Agent 之前，请使用 references/RUNTIME-MATRIX.md 确定当前环境中有哪些可用项。

如果没有可用的类工件界面，默认使用用户指定路径中的普通 Markdown 文件，或明确命名的工作文件。不要假定工件可用。

何时提供此工作流

触发条件：

• 用户提到撰写文档：“写一份文档”“起草一份提案”“创建一份规范”“整理成文档”
• 用户提到特定文档类型：“PRD”“设计文档”“决策文档”“RFC”
• 用户似乎要开始一项重要的写作任务

初次提供： 向用户提供一个用于共同撰写文档的结构化工作流。说明以下三个阶段：

1. 收集背景信息：用户提供所有相关背景信息，Claude 提出澄清问题
2. 完善与组织结构：通过头脑风暴和编辑，逐步构建各个章节
3. 读者测试：让一个没有上下文的新 Claude 测试文档，在其他人阅读之前找出盲点

说明这种方法有助于确保文档对其他读者而言清晰易懂（包括他们将文档粘贴到 Claude 中时）。询问用户想尝试这种工作流，还是更倾向于自由撰写。

如果用户拒绝，就按自由方式协作。如果用户接受，就进入第 1 阶段。

阶段 1：收集背景信息

目标： 缩小用户所知与 Claude 所知之间的差距，以便之后提供有针对性的指导。

初始问题

先询问用户有关文档的背景信息：

1. 这是什么类型的文档？（例如：技术规范、决策文档、提案）
2. 主要受众是谁？
3. 你希望读者读完后产生什么影响？
4. 是否有需要遵循的模板或特定格式？
5. 还有哪些限制或背景信息需要了解？

告知用户可以简要回答，也可以用任何方便的方式提供信息。

如果用户提供了模板或提到文档类型：

• 询问他们是否有可供分享的模板文档
• 如果他们提供共享文档的链接，请使用适当的集成来获取内容
• 如果他们提供了文件，请读取文件

如果用户提到要编辑现有的共享文档：

• 使用适当的集成读取当前内容
• 检查图片是否缺少替代文本
• 如果有图片缺少替代文本，请说明其他人使用 Claude 理解文档时，Claude 将无法查看这些图片。询问他们是否希望生成替代文本。如果希望，请让他们将每张图片粘贴到聊天中，以便生成描述性替代文本。

信息倾倒

初步问题回答完毕后，鼓励用户尽可能多地提供背景信息。请他们提供以下内容：

• 项目或问题的背景
• 相关的团队讨论或共享文档
• 为什么不采用其他替代方案
• 组织背景（团队关系、过往事故、内部政治）
• 时间压力或约束条件
• 技术架构或依赖关系
• 利益相关方的关注点

告知用户无需整理，直接全部说出来即可。提供背景信息的方式有多种：

• 随想式地倾倒信息
• 指向团队频道或讨论串，供阅读
• 提供共享文档链接

如果有可用的集成（例如 Slack、Teams、Google Drive、SharePoint 或其他 MCP 服务），说明可以用它们直接拉取背景信息。

如果未检测到集成，且处于 Claude.ai 或 Claude 应用中： 建议用户在 Claude 设置中启用连接器，以便直接从即时通讯应用和文档存储中拉取背景信息。

告知用户，待其完成初步信息倾倒后，将提出澄清问题。

收集背景信息期间：

• 如果用户提到团队频道或共享文档：

  • 如果有可用集成：告知用户将立即读取内容，然后使用相应的集成
  • 如果没有可用集成：说明无法访问。建议用户在 Claude 设置中启用连接器，或直接粘贴相关内容

• 如果用户提到未知的实体或项目：

  • 询问是否应搜索已连接的工具以了解更多信息
  • 等待用户确认后再进行搜索

• 随着用户提供背景信息，持续记录已了解的内容和仍不清楚的内容

提出澄清问题：

当用户表示已完成初步信息倾倒（或提供了大量背景信息之后），提出澄清问题，以确保理解准确：

根据背景信息中的缺口，生成 5 到 10 个编号问题。

告知用户，他们可以用简写方式回答（例如“1：是，2：见 #频道，3：否，因为需要向后兼容”），也可以链接更多文档、指向需要阅读的频道，或继续倾倒信息。采用最高效的方式即可。

结束条件： 当问题表明用户已理解背景，即可就边界情况和权衡取舍提问，无需再解释基础概念时，说明已收集到足够的背景信息。

过渡： 询问用户此时是否还有其他背景信息要补充，或者是否可以进入起草文档的阶段。

如果用户想要补充，则允许其继续。准备就绪后，进入阶段 2。

阶段 2：完善与结构

目标： 通过头脑风暴、筛选和迭代完善，逐节构建文档。

向用户说明： 告知用户文档将逐节构建。对于每一节：

1. 将询问需要包含哪些内容的澄清问题
2. 头脑风暴出 5-20 个选项
3. 用户指出保留、删除或合并哪些选项
4. 起草该节
5. 通过精准编辑对其进行完善

优先从未知信息最多的部分开始（通常是核心决策或提案），然后依次完成其余部分。

章节顺序：

如果文档结构已经明确： 询问用户想从哪一节开始。

建议从未知信息最多的部分开始。对于决策文档，通常是核心提案；对于规范文档，通常是技术方案。摘要部分最好留到最后。

如果用户不确定需要哪些章节： 根据文档类型和模板，建议 3-5 个适合该文档类型的章节。

询问该结构是否可行，或用户是否希望调整。

结构确定后：

创建包含所有章节占位文本的初始文档结构。

如果可以使用 artifact： 使用 create_file 创建一个 artifact，为 Claude 和用户提供一个可供协作的骨架。

告知用户将创建包含所有章节标题和占位文本的初始结构。

创建包含所有章节标题及简短占位文本的 artifact，例如“[待撰写]”或“[此处填写内容]”。

提供骨架链接，并说明现在可以开始填写各个章节。

如果无法使用 artifact： 在工作目录中创建一个 Markdown 文件。为其取一个合适的名称，例如 decision-doc.md 或 technical-spec.md。

告知用户将创建包含所有章节标题和占位文本的初始结构。

创建包含所有章节标题和占位文本的文件。

确认文件名已创建，并说明现在可以开始填写各个章节。

对每个章节：

第 1 步：澄清问题

宣布开始撰写 [SECTION NAME] 章节。提出 5-10 个关于应包含哪些内容的澄清问题：

根据上下文和章节用途，生成 5-10 个具体问题。

告知用户可以简短回答，或只需指出哪些内容是重点。

第 2 步：头脑风暴

针对 [SECTION NAME] 章节，头脑风暴出可能包含的 [5-20] 项内容，具体数量取决于该章节的复杂程度。重点关注：

• 可能被遗忘的已共享上下文
• 尚未提及的角度或考虑因素

根据章节复杂度生成 5-20 个编号选项。最后，询问用户是否需要更多选项。

第 3 步：筛选

询问哪些要点应保留、删除或合并。请用户简要说明理由，以便为后续章节确定优先级。

提供示例：

• “保留 1、4、7、9”
• “删除 3（与 1 重复）”
• “删除 6（读者已了解该内容）”
• “合并 11 和 12”

如果用户给出自由形式的反馈（例如“看起来不错”或“大部分都可以，但……”），而不是编号选择，则提取其偏好并继续推进。梳理用户希望保留、删除或修改的内容，并据此执行。

第 4 步：遗漏检查

根据用户已选择的内容，询问 [SECTION NAME] 章节是否还遗漏了重要内容。

第 5 步：起草

使用 str_replace 将本部分的占位文本替换为实际起草的内容。

宣布现在将根据用户所选内容起草 [SECTION NAME] 部分。

如果使用 artifacts： 起草完成后，提供该 artifact 的链接。

请用户通读并指出需要修改的地方。说明具体的反馈有助于后续章节的学习。

如果使用文件（不使用 artifacts）： 起草完成后，确认完成。

告知用户 [SECTION NAME] 部分已起草到 [filename] 中。请用户通读并指出需要修改的地方。说明具体的反馈有助于后续章节的学习。

给用户的关键说明（在起草第一个部分时包含）： 提供说明：不要直接编辑文档，而是告诉我需要修改的内容。这有助于我学习你的风格，用于后续章节。例如："删除 X 要点，已被 Y 涵盖"或"让第三段更简洁"。

第 6 步：迭代优化

在用户提出反馈时：

• 使用 str_replace 进行编辑（切勿重新输出整个文档）
• 如果使用 artifacts： 每次编辑后提供 artifact 链接
• 如果使用文件： 仅确认编辑已完成
• 如果用户直接编辑了文档并要求阅读：记下他们所做的更改，并在后续章节中加以考虑（这体现了他们的偏好）

持续迭代，直到用户对该部分满意为止。

质量检查

连续 3 次迭代没有实质性变化后，询问是否有可以删除而不会损失重要信息的内容。

该部分完成后，确认 [SECTION NAME] 已完成，并询问是否准备进入下一部分。

对所有部分重复上述过程。

接近完成

当进度接近完成（已完成 80% 以上的部分）时，宣布打算重新通读整个文档，检查：

• 各部分之间的流畅性与一致性
• 冗余或矛盾之处
• 任何像"slop"或泛泛填充的内容
• 每个句子是否都有价值

通读整个文档并提供反馈。

当所有部分都已起草并优化完成时： 宣布所有部分均已起草完成，并说明打算再次完整审阅文档。

审查整体的连贯性、流畅度与完整性。

提供最终建议。

询问是否准备进入读者测试（Reader Testing），或是否还需要进一步优化其他内容。

第 3 阶段：读者测试

目标： 使用一个全新的 Claude（无上下文串扰）测试文档，以验证其对读者是否有效。

给用户的说明： 说明现在将进行测试，以检验文档是否真正对读者有效。这有助于发现盲点，即对作者来说清晰、但可能让其他人困惑的内容。

测试方法

如果可以使用子 Agent（例如在 Claude Code 中）：

直接进行测试，无需用户参与。

第 1 步：预测读者问题

宣布打算预测读者在查找本文档时可能提出的问题。

生成 5 到 10 个读者可能实际会问的问题。

第 2 步：使用子 Agent 测试

宣布这些问题将交由一个全新的 Claude 实例（不含本对话的任何上下文）进行测试。

对每个问题，仅使用文档内容和该问题调用一个子 Agent。

总结读者 Claude 对每个问题的正确与错误之处。

第 3 步：运行额外检查

宣布将进行额外检查。

调用子 Agent 检查歧义、错误假设与矛盾之处。

总结发现的任何问题。

第 4 步：报告并修复

如果发现问题： 报告读者 Claude 在哪些具体问题上遇到困难。

列出具体问题。

说明打算修复这些缺口。

返回对有问题部分的优化流程。

---

如果无法使用子 Agent（例如 claude.ai 网页界面）：

用户需要手动进行测试。

步骤 1：预测读者会提出的问题

思考读者在查找本文档时可能会提出哪些问题。他们会在 Claude.ai 中输入什么？

生成 5-10 个读者可能会实际提出的问题。

步骤 2：设置测试

提供测试说明：

1. 开启一个新的 Claude 对话：https://claude.ai
2. 粘贴或分享文档内容（如果使用启用了连接器的共享文档平台，请提供链接）
3. 向 Reader Claude 提出生成的问题

针对每个问题，要求 Reader Claude 提供：

• 答案
• 是否有任何内容含糊不清
• 文档假定读者已了解哪些知识或上下文

检查 Reader Claude 的回答是否正确，或是否有误解。

步骤 3：其他检查

还要询问 Reader Claude：

• “本文档中有哪些内容可能会让读者感到含糊不清？”
• “本文档假定读者已掌握哪些知识或上下文？”
• “是否存在任何内部矛盾或不一致之处？”

步骤 4：根据结果迭代

询问 Reader Claude 哪些内容回答错了或难以理解。说明你打算弥补这些不足。

针对有问题的部分，返回并继续完善。

---

退出条件（两种方式均适用）

当 Reader Claude 能持续正确回答问题，且不再发现新的不足或歧义时，文档即可就绪。

最终审阅

Reader 测试通过后： 宣布文档已通过 Reader Claude 测试。完成前：

1. 建议他们亲自通读一遍——他们拥有本文档，并对其质量负责
2. 建议再次核查事实、链接或技术细节
3. 请他们确认文档是否实现了预期效果

询问他们是否还想再审阅一次，还是工作已经完成。

如果用户想进行最终审阅，请提供审阅。否则： 宣布文档已完成。提供几条最后的建议：

• 可以考虑在附录中链接本次对话，让读者了解文档的编写过程
• 使用附录补充详细内容，避免主文档过于冗长
• 收到真实读者的反馈后，更新文档

有效指导技巧

语气：

• 直接、按步骤说明
• 简要说明会影响用户操作的原因
• 不要试图“推销”这种方法——直接执行即可

处理偏离流程的情况：

• 如果用户想跳过某个阶段：询问他们是否想跳过该阶段并自由撰写
• 如果用户显得沮丧：承认这比预期耗时更长，并建议加快进度的方法
• 始终让用户有权调整流程

上下文管理：

• 如果提及的内容缺少上下文，请及时主动询问
• 不要让缺口不断累积——发现时就及时处理

工件管理：

• 使用 create_file 起草完整章节
• 所有编辑均使用 str_replace
• 每次更改后提供工件链接
• 不要将工件用于头脑风暴列表——这类内容直接在对话中处理

质量优先于速度：

• 不要仓促跳过各个阶段
• 每次迭代都应带来有意义的改进
• 目标是让文档真正满足读者的需要

参考文件

仅加载所需内容：

• references/RUNTIME-MATRIX.md - 如何将工作流适配到 Claude Code、Claude.ai、连接器丰富和连接器匮乏的环境
• references/DOC-TYPES.md - 常见文档类型的默认章节框架
• references/READER-TEST.md - 读者测试提示词、交接材料和通过/未通过信号