coauthoring-docs

文档协作撰写工作流

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

概述

核心原则： 用户掌握背景信息；你掌握结构。此工作流旨在高效地将用户的背景信息传递给你，然后逐节构建文档，让用户不必审阅一整篇自己没有参与塑造的长文。

设置三个阶段的原因：

阶段	解决的问题
1. 收集背景信息	你因缺少组织背景而写出听起来合理、实际却错误的内容
2. 完善与构建结构	用户收到完成的初稿后，不得不反向推敲该修改什么
3. 读者测试	文档对作者来说通顺易懂，对其他所有人来说却令人困惑

第 3 阶段最常被跳过，也最能发现问题。文档对撰写者来说读起来毫无问题，却是所有文档最常见的失败模式。

检查清单

为每项创建一个待办事项。各阶段依次进行；第 2 阶段中的各个部分则循环处理。

1. 提出工作流——征得同意，否则自由发挥
2. 第 1 阶段：元问题——类型、受众、期望影响、模板、限制
3. 第 1 阶段：倾倒信息——让用户尽情表达；不要打断他们来整理内容
4. 第 1 阶段：澄清问题——提出 5-10 个编号问题，支持简短作答
5. 第 2 阶段：商定结构——然后创建文件，为每个部分添加占位内容
6. 第 2 阶段：逐个部分处理——提问 → 头脑风暴 5-20 个想法 → 用户筛选 → 检查缺漏 → 起草 → 完善
7. 第 2 阶段：通读全文——检查行文、重复、矛盾和填充内容
8. 第 3 阶段：读者测试——让一个没有背景信息的新 Agent 回答预先设定的读者问题
9. 第 3 阶段：修复缺漏，然后循环，直到文档没有问题
10. 最终审阅——将所有权交还给用户

退出条件

每个阶段都有具体的完成标准。不要仅凭感觉认为已完成就进入下一阶段。

阶段	完成标准
1	你可以询问边缘情况和权衡，而无需用户解释基础信息
2	连续三轮迭代都没有实质性改动
3	一个全新的 Agent 能正确回答预先设定的读者问题，且没有发现新的歧义

何时提供此工作流

触发条件：

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

首次提供： 向用户提供一套用于协作文档撰写的结构化工作流。说明三个阶段：

1. 收集背景信息：用户提供所有相关背景信息，同时 Agent 提出澄清问题
2. 完善与构建结构：通过头脑风暴和编辑，逐步构建每个部分
3. 读者测试：让一个全新的 Agent（没有任何背景信息）测试文档，在其他人阅读前发现盲点

说明这种方法有助于确保文档在其他人阅读时（包括他们将文档粘贴到 Agent 中时）也能发挥作用。询问用户想尝试此工作流，还是更倾向于自由发挥。

如果用户拒绝，就自由发挥。如果用户接受，就进入第 1 阶段。

第 1 阶段：收集背景信息

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

初始问题

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

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

告知他们可以简略回答，或用自己最方便的方式随意提供信息。

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

• 询问他们是否有模板文档可以分享
• 如果他们提供共享文档链接，使用相应的集成来获取文档
• 如果他们提供文件，读取该文件

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

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

提供信息

回答完初始问题后，鼓励用户提供所有背景信息。请他们提供以下信息：

• 项目或问题的背景
• 相关团队讨论或共享文档
• 不采用其他解决方案的原因
• 组织背景（团队动态、过往事件、内部关系）
• 时间安排压力或限制
• 技术架构或依赖项
• 利益相关者的顾虑

建议他们不用费心整理，尽管把信息都说出来即可。提供多种方式来补充背景信息：

• 随想到随说，畅所欲言
• 指出需要阅读的团队频道或讨论串
• 分享共享文档链接

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

如果未检测到集成，且用户使用的是托管式 Agent 界面： 建议他们在 Agent 设置中启用连接器，以便直接从消息应用和文档存储中获取背景信息。

告知用户，在他们完成初步信息补充后，你会提出澄清问题。

收集背景信息期间：

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

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

• 如果用户提到不熟悉的实体或项目：

  • 询问是否应该搜索已连接的工具以了解详情
  • 等待用户确认后再进行搜索

• 随着用户提供背景信息，记录已了解的信息和仍不清楚的部分

提出澄清问题：

当用户表示已完成初步信息补充（或已提供大量背景信息）时，针对背景信息中的空缺提出澄清问题，以确保理解准确：

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

告知他们可以简略回答（例如：“1：是；2：见 #channel；3：不行，因为要保持向后兼容”）、提供更多文档链接、指出需要阅读的频道，或继续随意补充信息。选择对他们来说最高效的方式即可。

结束条件： 当问题表明你已理解背景信息时，说明已收集到足够的信息——此时可以询问边界情况和权衡取舍，而不需要用户解释基础信息。

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

如果用户想补充更多信息，就让他们继续补充。准备好后，进入第 2 阶段。

第 2 阶段：完善与结构设计

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

给用户的说明： 说明文档将逐节构建。每一节都会：

1. 询问澄清问题，了解需要包含哪些内容
2. 头脑风暴，提出 5-20 个选项
3. 由用户指出要保留、删除或合并的内容
4. 起草该章节
5. 通过精细编辑进一步完善

从未知因素最多的章节开始（通常是核心决策/提案），然后依次处理其余章节。

章节顺序：

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

建议从未知因素最多的章节开始。对于决策文档，通常是核心提案；对于规格说明，通常是技术方案。摘要类章节最好留到最后。

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

询问用户是否认可此结构，或者是否想进行调整。

结构确定后：

创建初始文档结构，并为所有章节添加占位文本。

如果可以渲染工件： 使用 write 工具创建工件，为 Agent 和用户提供可共同使用的框架。

告知用户将创建包含所有章节及占位内容的初始结构。

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

提供文件路径，并说明现在可以开始逐节补充内容。

如果无法渲染工件： 在工作目录中创建 Markdown 文件，并使用恰当的名称（例如 decision-doc.md、technical-spec.md）。

告知用户将创建包含所有章节及占位内容的初始结构。

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

确认文件已创建，并说明现在可以开始逐节补充内容。

对于每个章节：

步骤 1：澄清问题

宣布将开始处理[章节名称]章节。询问 5-10 个关于应包含哪些内容的澄清问题：

根据上下文和章节目的，提出 5-10 个具体问题。

告知用户可以简要回答，或只指出需要重点涵盖的内容。

步骤 2：头脑风暴

针对[章节名称]章节，根据章节复杂度，头脑风暴 [5-20] 个可能纳入的内容。关注：

• 用户分享过但可能被遗忘的上下文
• 尚未提及的角度或考量

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

步骤 3：筛选

询问用户哪些要点应保留、删除或合并。请用户简要说明理由，以便了解其优先事项，并在后续章节中据此调整。

提供示例：

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

如果用户以自由形式提供反馈（例如“看起来不错”或“我大部分都喜欢，不过……”），而不是选择编号，则提取其偏好并继续。判断用户想保留、删除或修改哪些内容，并据此处理。

步骤 4：检查遗漏

根据用户的选择，询问[章节名称]章节是否还缺少任何重要内容。

步骤 5：起草

使用 edit 工具，将本节的占位文本替换为实际起草的内容。

告知用户现在将根据他们的选择起草 [SECTION NAME] 部分。

如果使用制品渲染： 起草完成后，提供文件路径。

请他们通读内容，并指出需要修改的地方。说明具体的反馈有助于后续章节更贴合他们的风格。

如果使用文件（不进行制品渲染）： 起草完成后，确认文件已写入。

告知他们已在 [filename] 中起草 [SECTION NAME] 部分。请他们通读内容，并指出需要修改的地方。说明具体的反馈有助于后续章节更贴合他们的风格。

给用户的关键说明（起草第一部分时加入）： 请提示用户不要直接编辑文档，而是指出需要修改的地方。这样有助于了解他们的风格，并应用到后续章节中。例如：“删除 X 这个要点——Y 已经涵盖了”或“让第三段更简洁”。

步骤 6：迭代改进

用户提供反馈时：

• 使用 edit 工具进行修改（不要重新打印整个文档）
• 如果使用制品渲染： 每次修改后确认文件路径
• 使用基于文件的渲染： 只需确认修改已完成
• 如果用户直接编辑了文档并要求你阅读：记住他们所做的修改，并在后续章节中考虑这些偏好（这能体现你对其偏好的理解）

持续迭代，直到用户对本节满意。

质量检查

连续 3 次迭代都没有实质性修改后，询问是否有可以删除且不会丢失重要信息的内容。

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

对所有章节重复上述流程。

接近完成时

章节完成度达到 80% 以上时，告知用户你将重新通读整个文档，并检查以下内容：

• 各章节之间的衔接和一致性
• 重复或矛盾之处
• 是否存在“空话”或泛泛而谈的内容
• 每句话是否都有意义

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

所有章节均已起草并完善后： 告知用户所有章节均已起草，并表示你将再对完整文档进行一次审阅。

检查整体连贯性、行文流畅度和内容完整性。

提供最终建议。

询问用户是否准备进入读者测试，或希望继续完善其他内容。

阶段 3：读者测试

目标： 使用一个没有上下文的新 Agent 测试文档，确认它对读者是否有效。

给用户的说明： 说明现在将进行测试，以确认文档是否真正便于读者理解和使用。这有助于发现盲点——即作者觉得理所当然、但可能会让其他人困惑的内容。

测试方法

如果可以使用子 Agent（例如，在 opencode 中使用 task 工具）：

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

步骤 1：预测读者的问题

告知用户，你将预测读者在查找和使用本文档时可能会提出哪些问题。

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

步骤 2：使用子 Agent 进行测试

告知用户，你将使用一个全新的 Agent 实例（不含本次对话的上下文）来测试这些问题。

针对每个问题，只向子 Agent 提供文档内容和该问题。

总结读者 Agent 对每个问题回答正确和错误的地方。

步骤 3：进行其他检查

告知用户，你将进行其他检查。

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

总结发现的问题。

步骤 4：汇报并修复

如果发现问题：

说明读者 Agent 在哪些具体问题上遇到了困难。

列出具体问题。

说明你将修补这些内容。

回到改进流程，完善存在问题的章节。

---

如果无法使用子 Agent：

用户需要手动进行测试。

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

思考读者在查找本文档时可能会提出哪些问题。他们会在搜索框或 AI 助手中输入什么？

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

第 2 步：设置测试

提供测试说明：

1. 开启一个没有先前上下文的全新 Agent 会话
2. 粘贴或分享文档内容（如果使用启用了连接器的共享文档平台，请提供链接）
3. 向 Reader Agent 提出生成的问题

对于每个问题，要求 Reader Agent 提供：

• 答案
• 是否有任何含糊或不清楚之处
• 文档假设读者已经了解哪些知识或背景

检查 Reader Agent 是否回答正确，或是否误解了内容。

第 3 步：额外检查

也向 Reader Agent 提问：

• “本文档中哪些内容可能让读者感到含糊或不清楚？”
• “本文档假设读者已经了解哪些知识或背景？”
• “文档中是否存在内部矛盾或不一致之处？”

第 4 步：根据结果迭代

询问 Reader Agent 哪些内容答错了，或在哪些地方遇到了困难。说明你打算修复这些问题。

对于任何有问题的部分，返回并进行完善。

---

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

当 Reader Agent 能持续正确地回答问题，且没有发现新的问题或含糊之处时，文档就准备好了。

最终审阅

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

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

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

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

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

有效指导的技巧

语气：

• 直接、按步骤说明
• 当理由会影响用户行为时，简要解释
• 不要试图“推销”这种方法——只需照流程执行

处理偏离流程的情况：

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

上下文管理：

• 如果缺少所提及内容的上下文，过程中主动询问
• 不要让问题不断累积——发现后及时处理

成果管理：

• 使用 write 工具起草完整章节
• 所有修改都使用 edit 工具
• 每次修改后都提供文件路径
• 不要使用成果文件来整理头脑风暴清单——这类内容只需在对话中提供

质量优先于速度：

• 不要仓促完成各阶段
• 每次迭代都应带来实质性改进
• 目标是让文档真正满足读者的需要

常见错误

在 Stage 1 完成之前就开始起草。 你写出的内容流畅、自信，却是错的。判断方法：你能描述团队正在做什么，却说不清为什么否决了显而易见的替代方案。这是 Stage 1 的缺口，不是写作问题。

构思的选项太少。 五个稳妥的选项意味着用户只能从一组质量不高的选项中挑选。对于复杂的章节，提出二十个选项并不过分——大多数选项都会被删掉，而删减成本很低。

每次编辑后都重新输出整篇文档。 使用 edit 工具修改发生变化的章节。重新输出整篇文档会掩盖改动，也浪费用户的注意力。

未经请求就替用户编辑文档。 用户说“让第三段更简洁些”时，也是在教你后续每个章节都应遵循他们的风格。与其默默修改，不如询问要改什么——这条指示才是有价值的部分。

跳过 Stage 3。 文档在参与编写的两个人看来完美无缺，但这并不能说明什么，因为还有二十个人会在不了解背景的情况下阅读它。

让受污染的 Agent 测试读者体验。 继承了本次对话上下文的子 Agent 已经知道文档中未写明的所有内容。它只能收到文档和问题。

把“看起来不错”当作认可。 宽泛的正面反馈通常意味着用户已经不再仔细阅读。针对具体章节提出具体问题，以便确认。

相关技能

• brainstorming — 在还没有文档可写之前，用于探索想法
• writing-internal-comms — 用于撰写更新和公告，而非实质性文档
• dispatching-parallel-agents — Stage 3 的读者测试彼此独立，可以并行进行
• verifying-before-completion — 在宣布文档完成前，核实每个事实、链接和数字