doc-coauthoring

文档协作工作流

本 Skill 提供一套结构化工作流，引导用户完成协作式文档创作。请扮演主动的引导者，带领用户完成三个阶段：背景收集、细化与结构梳理，以及读者测试。

何时提供此工作流

触发条件：

• 用户提到撰写文档，例如“写一份文档”“起草一份提案”“创建一份规格说明”“写一份总结”
• 用户提到具体的文档类型，例如“PRD”“设计文档”“决策文档”“RFC”
• 用户似乎正在开始一项篇幅较大的写作任务

初始提议： 向用户提供一套结构化的文档协作工作流，并说明三个阶段：

1. 背景收集：用户提供所有相关背景，Claude 提出澄清性问题
2. 细化与结构梳理：通过头脑风暴和编辑，逐节迭代完善内容
3. 读者测试：使用一个没有任何上下文的全新 Claude 测试文档，在他人阅读之前发现盲点

说明这种方式有助于确保文档在他人阅读时（包括他们将文档粘贴给 Claude 时）效果良好。询问用户是想尝试此工作流，还是更喜欢自由协作。

如果用户拒绝，则自由协作。如果用户接受，则进入第一阶段。

第一阶段：背景收集

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

初始问题

首先向用户询问关于文档的元信息：

1. 这是什么类型的文档？（例如技术规格、决策文档、提案）
2. 主要读者是谁？
3. 读者阅读后，希望产生什么影响？
4. 是否有需要遵循的模板或特定格式？
5. 还有其他约束条件或需要了解的背景吗？

告知用户可以用简短的方式回答，也可以按自己的习惯完整提供信息。

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

• 询问其是否有可以共享的模板文档
• 如果用户提供了共享文档的链接，请使用合适的集成工具获取该文档
• 如果用户提供了文件，请读取该文件

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

• 使用合适的集成工具读取文档当前内容
• 检查是否存在缺少替代文本（alt-text）的图片
• 如果存在缺少替代文本的图片，说明当他人使用 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
• 每次修改后都提供制品链接
• 不要用制品记录头脑风暴清单——直接在对话中列出即可

质量优先于速度：

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

适用场景

当需要根据提供的来源材料，通过与作者反复协作，起草内容详实的提案、规范、RFC 或决策文档时使用。

示例

用户请求：

通过迭代协作的工作流程，将这些粗略笔记整理成结构化文档。

局限性

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为针对特定环境的验证、测试或专家审阅的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请暂停并请求澄清。