document

文档编写 - 文档阶段

不变要求

• 仅在验证通过且用户批准任务后运行。
• 根据任务文档、测试报告和实际变更的文件编写文档。
• 更新 LEARNINGS.md，记录可复用的经验。
• 仅在需要记录稳定的项目级说明时更新 AGENTS.md。
• 交接前，确保 TASKS.md 中的任务状态为 Approved。如果前一阶段遗漏了状态变更，请在此处将该行调整为 Approved，并重新读取跟踪文件以确认。

运行时适配器可以将此阶段作为斜杠命令、菜单操作或自然语言技能调用提供。可移植的阶段名称为 document。

工作流

1. 读取 AGENTS.md。
2. 确定任务 ID。
3. 读取任务文档和测试报告。
4. 查看 git diff --name-only，确定实际变更的文件。
5. 如需面向开发者的文档，则在 docs/features/ 中创建或更新功能文档。
6. 如果面向用户的行为发生变化，则在 docs/guides/ 中创建或更新用户指南。
7. 在 docs/learnings/{ID}-{task-name}.md 中撰写回顾。
8. 将可复用的经验追加到 LEARNINGS.md，避免重复现有条目。
9. 仅当任务确立了持久有效的项目级行为时，才更新 AGENTS.md。
10. 将 TASKS.md 中的任务状态改为 Approved（如果 test 阶段已完成变更，则无需操作；否则从之前的任一部分调整）。
11. 重新读取 TASKS.md，并确认任务行处于 Approved 中，且不在 Planned、In Progress 或 Testing 中。如果任务行不在预期部分，说明状态变更遗漏了——交接前立即完成修改。

文档触发条件

变更	文档
新增面向用户的功能	功能文档和用户指南
具有用户可见行为变化的错误修复	故障排除或指南更新
API 或 CLI 行为	开发者文档或参考说明
新增持久有效的项目约定	AGENTS.md
可复用的经验或注意事项	LEARNINGS.md
测试设置经验	LEARNINGS.md 和测试报告备注

回顾模板

# Task {ID} Retrospective

## Plan Vs Reality
- {What matched or changed}

## Quality Gate Findings
- {What simplify caught}

## Verification Findings
- {What test found}

## Reusable Lessons
- {Actionable lesson}

交接

Documentation complete for task {ID}
Task status: Approved
Next stage: ship {ID}