document

/document - 文档 Agent

工作流

/document {ID}
       ↓
1. Resolve task ID → find task document
2. Read task document + test report (pipeline audit)
3. Run git diff — identify pipeline gaps
4. Create/update feature doc (docs/features/{feature}.md)
5. Create/update user guide if user-facing (docs/guides/{feature}.md)
6. Update CLAUDE.md if structural changes detected
7. Write retrospective → update LEARNINGS.md
8. Move task to "Approved" in TASKS.md
       ↓
┌─── Automation Mode? ───┐
│                        │
▼ Manual                 ▼ Auto
Notify user              Output SIGNAL, exit
Ready for /ship

---

自动模式行为

当任务文档中的 Automation: auto 时：

≡ SIGNAL
STAGE: document
STATUS: DONE
TASK: {ID}
SUMMARY: Feature doc created
REFERENCE: docs/features/{feature}.md
≡ END

手动模式： 运行 /clear，然后运行 /ship {ID}。

---

第 1 步：文档编写前检查清单 — 全流程审计

第 1A 步：阅读主要来源

docs/task/{ID}-{task-name}.md        - What was planned + Implementation Notes from /simplify
docs/testing/{ID}-{task-name}.md     - Test results, failures, retry cycles

第 1B 步：获取实际文件差异

git diff --name-only main...HEAD

与任务文档的 ## File Changes 交叉核对。差异中有、但任务文档中没有的内容，是由 /simplify 或 /test 重试添加的——这些属于需要记录的流程缺漏。

第 1C 步：对流程缺漏进行分类

差异中有、但任务文档中没有的文件	可能来源	操作
同一文件经过大幅重构	/simplify 质量修复	如果出现新约定，在 CLAUDE.md 中记录模式变更
提取出新的辅助程序／工具	/simplify 单一职责修复	如果可复用，将其添加到 CLAUDE.md 的 Important File Locations
新的测试固定数据或种子文件	/test 设置	如果体现了测试模式，在 LEARNINGS.md 中记录
重试时更改了其他文件	/test → /implement 重新运行	记录偏差；检查是否需要更新 CLAUDE.md
周期中途添加了迁移文件	任何步骤	始终添加到 CLAUDE.md——迁移是关键背景信息

不要广泛探索代码库。只打开缺漏列表中的文件，或为核实准确性明确需要打开的文件。

第 1D 步：阅读 /simplify 的实现说明

在任务文档的 ## Implementation Notes 中：

• “构建了什么”——可能与原计划不同
• “与计划的偏差”——中等或重大偏差需要体现在文档中
• “规范检查”——修复可能引入值得记录到 CLAUDE.md 中的新模式

第 1E 步：检查 /test 重试次数

在 docs/testing/{ID}-{task-name}.md 中：

• 重试 0 次 → 在 LEARNINGS.md 中记录哪些方面进展顺利
• 重试 1 次或以上 → 失败根因是一个教训；始终记录到 LEARNINGS.md 中
• 同一问题多次重试 → 在 CLAUDE.md 中添加“不要”条目

---

第 2 步：确定文档需求

变更类型	所需文档
新功能	功能文档 + 用户指南
增强功能	更新现有文档
Bug 修复	更新故障排除部分
API 变更	更新 API 参考
流程缺漏（simplify/test 添加的文件）	CLAUDE.md + LEARNINGS.md

---

第 3 步：文档输出

功能文档： docs/features/{FEATURE}.md — 面向开发者的技术实现细节。包括概述、用户使用流程、架构（文件结构、架构、API 端点）、关键组件和技术说明。

用户指南： docs/guides/{feature}.md — 面向最终用户的功能使用说明。包括快速入门、分步说明、提示、常见问题和故障排除。

---

第 4 步：CLAUDE.md — 持续更新的项目大脑

按顺序执行：阅读 → 精简 → 更新。切勿只追加内容。

条目标准： 如果没有该条目，未来的 Agent 就会犯错、浪费时间去发现它，或重新讨论已经做出的决定，那么就值得记录。

完成此任务后需要更新的情况：

发生的情况	更新内容
新建目录	Project Structure
移动或重命名文件	Important File Locations
执行数据库迁移	Stack 部分、架构说明
安装新软件包	Stack 部分
/simplify 发现了重复出现的违规问题	Do Not
解决了架构争议	Architecture Decisions
违反约定后又进行了修复	Key Conventions
用新模式替换旧模式	删除旧条目，添加新条目

以下情况可完全跳过： 纯逻辑修复、文案更改或样式调整，且未新增文件、目录、迁移、路由或软件包。

以下情况绝不可跳过： 添加迁移、新建目录、移动／重命名文件、新增 API 路由、需要新的环境变量或替换模式。

/implement 应该已经记录了这些内容——请核实并补上任何缺漏。

---

步骤 5：回顾与 LEARNINGS.md

任务回顾： docs/learnings/{ID}-{task-name}.md

涵盖整个流程——计划与实际情况、质量门禁发现、测试失败和所做决策。包括：

• 计划与实际情况（计划内容、已提交内容、偏差、计划外文件）
• /simplify 发现的问题（标记并修复的模式）
• /test 揭示的问题（失败及根本原因）
• 关键经验（具体且可执行）

LEARNINGS.md（项目根目录）：提取最具复用价值的经验，并追加到相关章节。

经验来源	LEARNINGS.md 章节
/simplify 发现违反编码模式	常见错误
/simplify 提取出可复用的辅助工具	已确立的编码模式
/test 因计划中未提及的系统行为而失败	技术栈说明
/test 重试发现集成缺口	常见错误
差异中包含计划外文件	技术栈说明或已确立的编码模式
流程中做出的架构决策	架构与决策

LEARNINGS.md 条目规则：

• 一条经验 = 一项可执行的教训
• 注明发现该问题的流程步骤
• 将关键短语加粗，并用一句话说明
• 绝不重复——追加前先检查
• 如果 LEARNINGS.md 不存在，则创建并包含以下章节：架构与决策、已确立的编码模式、常见错误、测试模式、技术栈说明

---

文档检查清单

• 已运行 git diff --name-only main...HEAD——已记录完整文件列表
• 已识别并分类流程缺口
• 已阅读 /simplify 实施说明——已记录偏差
• 已检查 /test 重试次数——已确定失败的根本原因
• 已创建/更新功能文档，且文件路径准确
• 已创建/更新用户指南（如面向用户）
• 已阅读 → 精简 → 更新 CLAUDE.md（或在无结构性变更时跳过）
• 已编写 docs/learnings/{ID}-{task-name}.md
• 已将关键经验追加到 LEARNINGS.md
• LEARNINGS.md 中没有重复条目
• 已将任务移至 TASKS.md 中的“Approved”

---

更新 TASKS.md

将任务移至“Approved”：

ID	任务	任务文档	功能文档	测试报告	已批准

---

交接给 /ship

手动模式： 输出已更新文件的摘要、任务已移至“Approved”的说明，以及下一步 /ship {ID}。 自动模式： 输出 SIGNAL 并退出。由编排器处理路由。不要启动下一个技能。