7.15 Doc Coauthoring Skill - 文档协作

概述

Doc Coauthoring Skill 提供了一个结构化的工作流程，指导用户完成协作式文档创作。它通过三个阶段帮助用户高效地传递上下文、通过迭代优化内容，并验证文档对读者的有效性。

适用场景

当用户提到以下内容时触发此 Skill：

• 撰写文档："写一个 doc"、"起草一个提案"、"创建一个规范"
• 特定文档类型：PRD、设计文档、决策文档、RFC
• 开始重大写作任务

三阶段工作流程

+---------------------+     +---------------------+     +---------------------+
|       Stage 1       | --> |       Stage 2       | --> |       Stage 3       |
|     上下文收集      |     |     优化与结构      |     |     读者测试        |
+---------------------+     +---------------------+     +---------------------+
| 用户提供所有相关    |     | 逐节迭代构建        |     | 用新鲜的 Claude     |
| 上下文，Claude      |     | 通过头脑风暴和      |     | 测试文档            |
| 提出澄清问题        |     | 编辑优化内容        |     | 发现盲点            |
+---------------------+     +---------------------+     +---------------------+

Stage 1: 上下文收集

目标

缩小用户知道的和 Claude 知道的之间的差距，为后续的智能指导打下基础。

初始问题

首先询问用户关于文档的元上下文：

1. 这是什么类型的文档？（如技术规范、决策文档、提案）
2. 主要受众是谁？
3. 当别人读完后，期望产生什么影响？
4. 是否有模板或特定格式要遵循？
5. 还有其他约束或上下文需要了解吗？

告知用户可以用简短方式回答或以任何方便的方式倾倒信息。

信息倾倒

鼓励用户倾倒所有相关上下文：

• 项目/问题的背景
• 相关团队讨论或共享文档
• 为什么不使用替代方案
• 组织上下文（团队动态、过去事件、政治）
• 时间压力或约束
• 技术架构或依赖
• 利益相关者的担忧

澄清问题

当用户完成初始倾倒后，生成 5-10 个基于上下文差距的编号问题。

告知用户可以用简短方式回答（如"1: 是，2: 见 #channel，3: 不行因为向后兼容"）。

退出条件

当问题显示理解——能够询问边缘情况和权衡而不需要解释基础知识时，上下文收集充分。

Stage 2: 优化与结构

目标

通过头脑风暴、筛选和迭代优化，逐节构建文档。

章节排序

如果文档结构清晰，询问用户想从哪个章节开始。建议从未知最多的章节开始：

• 对于决策文档，通常是核心提案
• 对于规范，通常是技术方法
• 摘要章节最好留到最后

如果用户不知道需要什么章节，基于文档类型和模板建议 3-5 个章节。

每个章节的工作流程

+---------------+     +---------------+     +---------------+
|    Step 1     | --> |    Step 2     | --> |    Step 3     |
|   澄清问题    |     |   头脑风暴    |     |     筛选      |
| 5-10个关于    |     | 5-20个可能    |     | 保留/删除/    |
| 章节的问题    |     | 包含的点      |     | 合并选项      |
+---------------+     +---------------+     +---------------+
        |                                           |
        v                                           v
+---------------+     +---------------+     +---------------+
|    Step 6     | <-- |    Step 5     | <-- |    Step 4     |
|  迭代优化     |     |    起草       |     |   差距检查    |
| 直到满意      |     | 用选择的点    |     | 是否遗漏重要  |
|               |     | 写章节        |     | 内容          |
+---------------+     +---------------+     +---------------+

Step 1: 澄清问题

宣布开始 [章节名称] 章节。询问 5-10 个关于应包含什么的具体问题。

Step 2: 头脑风暴

为 [章节名称] 章节头脑风暴 5-20 个可能包含的点（根据章节复杂度）。寻找：

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

Step 3: 筛选

询问用户要保留、删除或合并哪些点。请求简短理由以帮助了解下一章节的优先级。

示例：

• "保留 1,4,7,9"
• "删除 3（与 1 重复）"
• "删除 6（受众已经知道）"
• "合并 11 和 12"

Step 4: 差距检查

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

Step 5: 起草

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

Step 6: 迭代优化

当用户提供反馈时：

• 使用 str_replace 进行编辑（永不重印整个文档）
• 每次编辑后提供 artifact 链接
• 如果用户直接编辑文档，注意他们做的更改以了解偏好

继续迭代直到用户对章节满意。

质量检查

连续 3 次迭代没有实质性更改后，询问是否有任何内容可以删除而不丢失重要信息。

Stage 3: 读者测试

目标

用新鲜的 Claude（无上下文渗透）测试文档，验证它对读者有效。

有子代理访问时（如 Claude Code）

直接执行测试，无需用户参与：

1. 预测读者问题：生成 5-10 个读者可能会问的现实问题
2. 用子代理测试：对每个问题，用只有文档内容和问题的子代理调用
3. 运行额外检查：检查歧义、假设错误、矛盾
4. 报告并修复：如果发现问题，循环回到优化阶段

无子代理访问时（如 claude.ai 网页界面）

用户需要手动执行测试：

1. 打开新的 Claude 对话：https://claude.ai
2. 粘贴或分享文档内容
3. 问 Reader Claude 生成的问题
4. 检查回答是否正确或有误解

同时让 Reader Claude 检查：

• "这个文档中有什么可能对读者模糊或不清楚的？"
• "这个文档假设读者已经具备什么知识或上下文？"
• "有任何内部矛盾或不一致吗？"

退出条件

当 Reader Claude 一致正确回答问题且不再发现新的差距或歧义时，文档准备就绪。

最终审查

当读者测试通过：

1. 建议用户自己做最终阅读——他们对文档质量负责
2. 建议仔细检查任何事实、链接或技术细节
3. 请用户验证文档达到了期望的影响

最终提示：

• 考虑在附录中链接这个对话，让读者看到文档是如何开发的
• 使用附录提供深度而不使主文档膨胀
• 收到真实读者反馈后更新文档

有效指导技巧

语气

• 直接且程序化
• 当影响用户行为时简要解释理由
• 不要试图"推销"方法——只需执行

处理偏离

• 如果用户想跳过阶段：询问是否想跳过并自由写作
• 如果用户看起来沮丧：承认这比预期花费更长时间，建议加速方法
• 始终给用户调整流程的权力

上下文管理

• 全程如果上下文缺失，主动询问
• 不要让差距累积——发现就解决

质量优于速度

• 不要匆忙通过阶段
• 每次迭代应做出有意义的改进
• 目标是文档真正对读者有效

总结

Doc Coauthoring Skill 提供了结构化的文档协作流程：

三阶段工作流程：

1. 上下文收集 - 缩小知识差距
2. 优化与结构 - 逐节迭代构建
3. 读者测试 - 验证文档有效性

每节工作流程： 澄清问题 -> 头脑风暴 -> 筛选 -> 差距检查 -> 起草 -> 迭代优化

核心原则：

• 用户提供上下文，Claude 提供结构
• 通过迭代逐步优化
• 用新鲜视角验证文档

这个 Skill 确保创建的文档不仅对作者有意义，更重要的是对读者也清晰有效。