# Doc Coauthoring

> 引导用户通过结构化工作流共同撰写文档。当用户想要编写文档、提案、技术规范、决策文档或类似的结构化内容时使用。此工作流帮助用户高效传递上下文、通过迭代精炼内容，并验证文档对读者是否有效。当用户提到编写文档、创建提案、起草规范或类似文档任务时触发。

- Skill: `majiayu000/doc-coauthoring-4` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/doc-coauthoring-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/doc-coauthoring-4/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/doc-coauthoring-4

---


# 文档共同撰写工作流

此技能提供结构化工作流，引导用户完成协作文档创建。作为主动向导，带领用户完成三个阶段：上下文收集、精炼与结构化、读者测试。

## 何时提供此工作流

**触发条件：**
- 用户提到编写文档："写个文档"、"起草提案"、"创建规范"、"写一下"
- 用户提到特定文档类型："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 个部分。

询问此结构是否可行，或是否要调整。

**一旦结构达成一致：**

创建带有所有部分占位符文本的初始文档结构。

**如果可以访问工件：**
使用 `create_file` 创建工件。这为 Claude 和用户提供了一个脚手架。

告知他们将创建所有部分的占位符的初始结构。

创建包含所有部分标题和简短占位符文本（如"[待编写]"或"[此处内容]"）的工件。

提供脚手架链接并指示是时候填充每个部分了。

**如果无法访问工件：**
在工作目录中创建 markdown 文件。适当命名（例如，`决策文档.md`、`技术规范.md`）。

告知他们将创建所有部分的占位符的初始结构。

创建包含所有部分标题和占位符文本的文件。

确认已创建文件名并指示是时候填充每个部分了。

**对于每个部分：**

### 步骤 1：澄清问题

宣布将开始处理 [部分名称] 部分。询问 5-10 个关于应包含什么的澄清问题：

基于上下文和部分目的生成 5-10 个具体问题。

告知他们可以简短回答或只指出重要覆盖的内容。

### 步骤 2：头脑风暴

对于 [部分名称] 部分，根据部分的复杂性头脑风暴 [5-20] 个可能包含的内容。寻找：
- 可能被遗忘的共享上下文
- 尚未提及的角度或考虑因素

基于部分复杂性生成 5-20 个编号选项。最后，如果他们想要更多选项，提供头脑风暴更多选项。

### 步骤 3：筛选

询问应保留、删除或合并哪些要点。请求简短的理由以帮助学习下一节的优先级。

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

**如果用户给出自由形式的反馈**（例如，"看起来不错"或"我喜欢大部分，但..."）而不是编号选择，提取他们的偏好并继续。解析他们想要保留/删除/更改的内容并应用它。

### 步骤 4：空白检查

根据他们选择的内容，询问 [部分名称] 部分是否缺少任何重要内容。

### 步骤 5：起草

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

宣布现在将根据他们选择的内容起草 [部分名称] 部分。

**如果使用工件：**
起草后，提供工件链接。

要求他们通读并指出要更改的内容。注意具体说明有助于学习下一节。

**如果使用文件（无工件）：**
起草后，确认完成。

告知他们已在 [文件名] 中起草 [部分名称] 部分。要求他们通读并指出要更改的内容。注意具体说明有助于学习下一节。

**对用户的关键指示（起草第一部分时包含）：**
提供注释：不要直接编辑文档，而是要求他们指出要更改的内容。这有助于学习他们的风格以用于未来部分。例如："删除 X 项 - 已由 Y 覆盖"或"使第三段更简洁"。

### 步骤 6：迭代精炼

当用户提供反馈时：
- 使用 `str_replace` 进行编辑（永不重印整个文档）
- **如果使用工件：** 每次编辑后提供工件链接
- **如果使用文件：** 只确认编辑完成
- 如果用户直接编辑文档并要求阅读：在心中记下他们所做的更改并在未来部分中记住（这显示了他们的偏好）

**继续迭代** 直到用户对该部分满意。

### 质量检查

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

部分完成后，确认 [部分名称] 已完成。询问是否准备好移至下一部分。

**对所有部分重复。**

### 接近完成

当接近完成时（80%+ 的部分完成），宣布打算重新阅读整个文档并检查：
- 各部分之间的流畅性和一致性
- 冗余或矛盾
- 任何感觉像"草率"或通用填充物的内容
- 每个句子是否都有分量

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

**当所有部分都起草并精炼后：**
宣布所有部分都已起草。表示打算再次审查完整文档。

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

提供任何最终建议。

询问是否准备好进行读者测试，或是否想精炼其他内容。

## 阶段 3：读者测试

**目标：** 使用全新的 Claude（无上下文渗透）测试文档，以验证它对读者是否有效。

**对用户的说明：**
解释现在将进行测试，看文档对读者是否真的有效。这会发现盲点 - 对作者有意义但可能让其他人困惑的事情。

### 测试方法

**如果可以访问子代理（例如，在 Claude Code 中）：**

在不涉及用户的情况下直接执行测试。

### 步骤 1：预测读者问题

宣布打算预测读者在尝试发现此文档时可能提出的问题。

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

### 步骤 2：使用子代理测试

宣布这些问题将使用全新的 Claude 实例（此对话中无上下文）进行测试。

对于每个问题，仅使用文档内容和问题调用子代理。

总结读者 Claude 对每个问题的正确/错误回答。

### 步骤 3：运行附加检查

宣布将执行附加检查。

调用子代理检查歧义、错误假设、矛盾。

总结发现的任何问题。

### 步骤 4：报告和修复

如果发现问题：
报告读者 Claude 在特定问题上遇到困难。

列出具体问题。

表示打算修复这些空白。

循环回到问题部分的精炼。

---

**如果无法访问子代理（例如，claude.ai 网页界面）：**

用户需要手动进行测试。

### 步骤 1：预测读者问题

询问人们在尝试发现此文档时可能提出什么问题。他们会在 Claude.ai 中输入什么？

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

### 步骤 2：设置测试

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

对于每个问题，指示读者 Claude 提供：
- 答案
- 是否有任何歧义或不清楚的地方
- 文档假设已知的知识/上下文是什么

检查读者 Claude 是否给出正确答案或误解任何内容。

### 步骤 3：附加检查

还要询问读者 Claude：
- "此文档中对读者可能不明确或不清楚的是什么？"
- "此文档假设读者已经拥有什么知识或上下文？"
- "是否有任何内部矛盾或不一致？"

### 步骤 4：根据结果迭代

询问读者 Claude 哪里出错或遇到困难。表示打算修复这些空白。

循环回到任何问题部分的精炼。

---

### 退出条件（两种方法）

当读者 Claude 始终正确回答问题且不浮现新的空白或歧义时，文档已准备就绪。

## 最终审查

当读者测试通过时：
宣布文档已通过读者 Claude 测试。在完成前：

1. 建议他们自己做最终通读 - 他们拥有此文档并对其质量负责
2. 建议仔细检查任何事实、链接或技术细节
3. 要求他们验证它是否达到了他们想要的影响

询问他们是否想要再次审查，或者工作是否完成。

**如果用户想要最终审查，提供它。否则：**
宣布文档完成。提供一些最终提示：
- 考虑在附录中链接此对话，以便读者可以看到文档是如何开发的
- 使用附录提供深度而不会使主文档臃肿
- 从真实读者那里收到反馈时更新文档

## 有效指导技巧

**语气：**
- 直接且程序性
- 当影响用户行为时简要解释理由
- 不要试图"推销"方法 - 只需执行它

**处理偏离：**
- 如果用户想跳过阶段：询问他们是否想跳过此阶段并自由编写
- 如果用户似乎沮丧：承认这比预期花费更长时间。建议加快速度的方法
- 始终赋予用户调整过程的能力

**上下文管理：**
- 在整个过程中，如果提到的内容缺少上下文，主动询问
- 不要让空白累积 - 在出现时解决它们

**工件管理：**
- 使用 `create_file` 起草完整部分
- 使用 `str_replace` 进行所有编辑
- 每次更改后提供工件链接
- 永远不要将工件用于头脑风暴列表 - 那只是对话

**质量重于速度：**
- 不要匆忙完成阶段
- 每次迭代都应该做出有意义的改进
- 目标是一个对读者真正有效的文档