# Doc Coauthoring

> 引导用户通过结构化工作流程进行文档协作。当用户想要编写文档、提案、技术规范、决策文档或类似结构化内容时使用。此工作流程帮助用户高效传递上下文、通过迭代精炼内容，并验证文档对读者有效。触发词：writing docs、creating proposals、drafting specs 或类似文档任务。

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

---


# 文档协作工作流程

提供结构化工作流程，引导用户进行协作文档创建。作为主动指南，引导用户通过三个阶段：上下文收集、精炼与结构、读者测试。

## 何时提供此工作流程

**触发条件**：用户提到编写文档、特定文档类型（PRD、设计文档、决策文档、RFC）、似乎要开始大量写作任务。  
**初始提供**：向用户提供结构化文档协作工作流程。解释三个阶段：1) 上下文收集：用户提供所有相关上下文，Claude 问澄清问题；2) 精炼与结构：通过头脑风暴与编辑迭代构建每个部分；3) 读者测试：用全新 Claude（无上下文）测试文档，在他人阅读前捕获盲点。  
如果用户拒绝，自由形式工作。如果接受，进行阶段 1。

## 阶段 1：上下文收集

**目标**：缩小用户知道与 Claude 知道之间的差距，使后续能提供智能指导。

### 初始问题

询问文档的元上下文：文档类型、主要受众、期望影响、是否有模板或特定格式、任何其他约束或上下文。  
**如果用户提供模板或提到文档类型**：询问是否有模板文档可分享；如提供共享文档链接，使用适当集成获取；如提供文件，读取它。  
**如果用户提到编辑现有共享文档**：使用适当集成读取当前状态；检查无 alt 文本的图像；如存在无 alt 文本的图像，解释当他人使用 Claude 理解文档时 Claude 无法看到它们，询问是否要生成 alt 文本。

### 信息转储

一旦初始问题回答，鼓励用户转储所有上下文。请求信息如：项目/问题背景、相关团队讨论或共享文档、为何不使用替代方案、组织上下文、时间线压力或约束、技术架构或依赖、利益相关者担忧。  
建议他们不必担心组织—只需全部输出。提供多种提供上下文方式：信息转储意识流、指向团队频道或线程阅读、链接到共享文档。  
**如果集成可用**（如 Slack、Teams、Google Drive、SharePoint 或其他 MCP 服务器），提及这些可用于直接拉入上下文。  
**如果未检测到集成且在 Claude.ai 或 Claude 应用**：建议他们可以在 Claude 设置中启用连接器，以允许直接从消息应用与文档存储拉入上下文。

**上下文收集期间**：如果用户提到团队频道或共享文档，如集成可用则使用适当集成读取；如不可用则解释缺少访问，建议启用连接器或直接粘贴相关内容。如果用户提到未知实体/项目，询问是否应搜索连接工具以了解更多，等待用户确认再搜索。  
**问澄清问题**：当用户表示已完成初始转储（或提供大量上下文后），生成 5-10 个编号问题基于上下文中的差距。告知他们可用简写回答、链接到更多文档、指向要阅读的频道，或继续信息转储。  
**退出条件**：当问题显示理解时—当可以询问边缘情况与权衡而不需要解释基础时，已收集足够上下文。  
**过渡**：询问在此阶段是否还有更多上下文要提供，或是否该继续起草文档。

## 阶段 2：精炼与结构

**目标**：通过头脑风暴、策划与迭代精炼逐部分构建文档。

**给用户的说明**：解释文档将逐部分构建。对每个部分：1) 问澄清问题关于要包含什么；2) 头脑风暴 5-20 个选项；3) 用户指示保留/删除/合并什么；4) 起草部分；5) 通过外科编辑精炼。  
从未知最多的部分开始（通常是核心决策/提案），然后处理其余。

**部分排序**：如果文档结构清晰，询问想从哪个部分开始。建议从未知最多的开始。对于决策文档，通常是核心提案。对于规范，通常是技术方法。摘要部分最好留到最后。  
**如果用户不知道需要什么部分**：基于文档类型与模板，建议 3-5 个适合该文档类型的部分。询问此结构是否有效，或是否要调整。

**一旦结构同意**：创建初始文档结构，所有部分带占位符文本。  
**如果工件访问可用**：使用 `create_file` 创建工件。这给 Claude 与用户一个脚手架。创建工件，所有部分标题与简短占位符文本如「[待写]」或「[内容在此]」。提供脚手架链接并指示是时候填写每个部分。  
**如果无工件访问**：在工作目录创建 markdown 文件。适当命名（如 `decision-doc.md`、`technical-spec.md`）。创建文件，所有部分标题与占位符文本。确认文件名已创建并指示是时候填写每个部分。

**对每个部分**：

### 步骤 1：澄清问题

宣布将开始 [部分名称] 部分。问 5-10 个澄清问题关于应包含什么。生成 5-10 个基于上下文与部分目的的具体问题。告知他们可用简写回答或仅指示要覆盖的重要内容。

### 步骤 2：头脑风暴

为 [部分名称] 部分，头脑风暴 [5-20] 个可能包含的内容，取决于部分复杂度。寻找：可能被遗忘的共享上下文、尚未提到的角度或考虑。生成 5-20 个编号选项。最后，如他们想要更多选项，提供更多头脑风暴。

### 步骤 3：策划

询问哪些点应保留、删除或合并。请求简短理由以帮助学习下一部分的优先级。提供示例：「保留 1,4,7,9」「删除 3（重复 1）」「合并 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 Web 界面）：用户需要手动进行测试。

### 步骤 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` 进行所有编辑；每次更改后提供工件链接；绝不使用工件进行头脑风暴列表—那只是对话。  
**质量优于速度**：不要匆忙通过阶段；每次迭代应做出有意义的改进；目标是实际对读者有效的文档。