用途：在功能完成、架构决策做出、API 新增或修改、发现项目约定时，产出可引用的文档与 ADR 文件，文档完成后回到 ship-workflow-ship 或 verify-workflow-review。不适合仅做代码实现或修 bug、决策仍在 brainstorm/refine 阶段、或只需口头解释的场景。
核心原则：记录决策，不只是记录代码；代码显示 WHAT，文档说明 WHY；不删除旧 ADR。
文档分层：Root docs（README.md、AGENTS.md、CHANGELOG.md、DESIGN.md）；Project docs（docs/architecture/.md）；Feature docs（docs/features/YYYYMMDD-<name>/）；Bug docs（docs/bugs/<name>/*）。默认 feature 工作只更新 feature docs，长期真相变化时才同步 root 或 project docs。
主要能力：
- ADR：生命周期为提议→讨论中、接受、取代（旧的保留）、废弃（保留作历史）。
- 内联文档：写 WHY（不明显的业务规则）、GOTCHA（非显而易见副作用）、INTENT（不匹配模式的原因）；不写重复代码的注释、TODO、注释掉的代码。
- API 文档：每个公共函数/端点有描述，参数与返回类型、抛出的异常文档化，含使用示例，不重复类型签名。
- README 与项目文档：README 面向首次接触者，含项目是什么、快速开始、开发命令、项目结构、关键约定、部署；项目级最小集合包括 README.md、AGENTS.md、CHANGELOG.md、DESIGN.md、docs/architecture/system-overview.md、module-boundaries.md、deployment-and-runtime.md、observability-and-runbook.md；按需扩展 api-contracts.md、data-model.md、security-boundaries.md。
- 面向 AI Agent 的文档：AI 需要 AGENTS.md/CLAUDE.md、Spec、ADR、代码注释中的 WHY/GOTCHA/INTENT；不需要 README 长段历史、Git 工作流教程、重复 JSDoc 类型注释；新项目约定写入 AGENTS.md。
- Changelog 维护：面向用户，分 Added/Changed/Fixed/Deprecated/Security，不写内部重构细节。
限制与红旗：注释掉的代码块应删除；超过 3 个月的 TODO 应转 issue；函数逻辑改动后需同步注释文档；公共 API 无文档、新架构决策无 ADR、README 快速开始在新 checkout 失败均属问题。验证清单包括公共 API 文档覆盖、ADR 完整性（背景+选项+理由+后果）、README 可执行、Changelog 更新、清理注释代码与 TODO。