Menu
文档工程——记录决策、API、代码约定。当需要写文档、记录架构决策或维护项目知识，或提到"文档""README""API 文档"
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle SOC
结构化脑暴——发散探索 + 收敛评估。当想法模糊、面临开放性问题或需要方案对比，或提到"脑暴""想法""方案对比""怎么办"
恢复保存的工作上下文。当新 session 需要继续之前的工作，或提到"恢复""restore""继续上次"
保存工作上下文。当需要保存当前工作状态供后续 session 恢复，或提到"保存""save""checkpoint""挂起"
架构决策记录（ADR）。当面临技术选型、架构决策、方案取舍需要记录，或提到"ADR""决策记录""为什么这样做"
发布或导出检查 → Go/No-Go → 归档。当审查通过后需要上线或交付最终产物，或提到"发布""上线""ship""Go/No-Go"
合并 PR → 等待 CI → 验证生产。当 PR 已创建需要合并到主分支并验证部署，或提到"合并""merge""PR""land"
| name | reflect-team-documentation |
| description | 文档工程——记录决策、API、代码约定。当需要写文档、记录架构决策或维护项目知识，或提到"文档""README""API 文档" |
build-cognitive-decision-record/SKILL.md（需要写 ADR 时）ship-workflow-ship 或 verify-workflow-review记录决策，不只是记录代码。
最有价值的文档记录的是 WHY。
代码显示 WHAT。文档说明 WHY。
先分槽位，再写模板。Unified 的项目级文档分层固定为：
README.mdAGENTS.mdCHANGELOG.mdDESIGN.mddocs/architecture/*.mddocs/features/YYYYMMDD-<name>/*docs/bugs/<name>/*默认 feature 工作只更新 feature docs。只有长期真相变化时，才同步 root docs 或 project docs。
详见 build-cognitive-decision-record/SKILL.md。此处补充：
ADR 生命周期:
不删除旧 ADR。 旧 ADR 和代码一样有历史价值。
何时写注释:
// 写 WHY: 解释不明显的业务规则
// 折扣必须在税之前计算，因为法规要求（见 REG-2024-0321）
function calculateTotal(items: Item[]): number { ... }
// 写 GOTCHA: 警告非显而易见的副作用
// 注意: 此函数也会更新 user.lastActivity —— 因为计费和活动追踪共享此路径
async function recordUsage(userId: string, amount: number): Promise<void> { ... }
// 写 INTENT: 当实现不匹配模式时的原因
// prisma.$queryRaw 而非 findMany —— 需要 FOR UPDATE 行级锁
何时不写注释:
// Bad: 注释重复代码
// 计算总价
const total = items.reduce((sum, item) => sum + item.price, 0);
// Bad: TODO 是 issue
// TODO: 加错误处理
async function processPayment() { ... }
// Bad: 注释掉的代码
// const oldWay = await legacyApi.fetch();
// git 有历史，删掉注释掉的代码
原则: 写注释解释代码本身表达不了的东西。代码能清晰表达的 → 不写。写不对就改代码让它更清晰。
/**
* 创建新任务。
*
* @param input - 任务创建参数
* @param input.title - 任务标题 (1-200 字符)
* @param input.priority - 优先级等级
* @returns 新创建的任务，包含默认状态 'pending'
* @throws {ValidationError} 当标题为空或超过 200 字符
* @throws {UnauthorizedError} 当用户未认证
*
* @example
* const task = await createTask({ title: '买菜', priority: 'high' });
* console.log(task.status); // 'pending'
*/
async function createTask(input: CreateTaskInput): Promise<Task> { ... }
API 文档标准:
项目 README 应包含:
├── 项目是什么 (1 句)
├── 快速开始 (安装 + 运行 < 5 行)
├── 开发命令 (build/test/lint/dev)
├── 项目结构 (顶层目录 + 说明)
├── 关键约定 (非标准但规则)
└── 部署 (在哪运行、怎么部署)
README 面向首次接触项目的人。 不给专家写文档（专家不需要），给新手写（新手需要）。
项目级文档最小集合：
README.md — 项目入口、启动、命令、结构、部署入口AGENTS.md — 入口合同、激活门、项目约束（运行时详细规则在 docs/contracts/ 按需加载）CHANGELOG.md — 用户可感知变化 / release 记录DESIGN.md — 跨 feature 设计 token 和长期设计约束docs/architecture/system-overview.mddocs/architecture/module-boundaries.mddocs/architecture/deployment-and-runtime.mddocs/architecture/observability-and-runbook.md按需扩展：
docs/architecture/api-contracts.mddocs/architecture/data-model.mddocs/architecture/security-boundaries.md不要把 project docs 当 feature archive。 feature 过程留在 docs/features/；project docs 只保留当前长期真相。
代码库中的文档也被 AI agent 消费。AI 阅读文档的方式和人类不同：
AI 需要的文档:
├── AGENTS.md / CLAUDE.md → 项目命令、测试方法、架构概览
├── Spec → 需求 + 验收条件
├── ADR → 架构决策 + 为什么
└── 代码注释 → WHY、GOTCHA、INTENT（不重复代码）
AI 不需要的:
├── README 里的长段历史
├── CONTRIBUTING 中的 Git 工作流教程（AI 有自己的一套）
├── 重复 JSDoc 类型的注释
项目约定的新发现 → 写入 AGENTS.md。 CLAUDE.md 仅保留 Claude 侧指针或补充提示，不再承载完整项目合同。
## [1.2.0] - 2026-04-24
### Added
- 任务创建支持优先级 (low/medium/high)
- 任务列表分页 (GET /tasks?page=1&pageSize=20)
### Changed
- 任务完成端点返回 completedAt 时间戳（以前不返回）
### Fixed
- 修复逾期任务的 isOverdue 标志未在 UTC 边界正确计算
### Deprecated
- `GET /v1/tasks` 将在 2026-06-01 移除。使用 `GET /v2/tasks`
### Security
- 修复 `npm audit` 报告的 critical CVE-2026-XXXX
Changelog 面向用户。 "重构了 TaskService" = 内部细节、用户不关心。"任务列表支持分页（避免页面崩溃）" = 用户需要知道。
| 说辞 | 现实 | 后果 |
|---|---|---|
| "代码自解释，不需要文档" | 代码告诉你做什么。文档告诉你为什么做、为什么不做另一种做法、什么坑位要注意。 | 新人接手耗时 ×3；WHY 信息丢失 → 误推翻已有决策 → 返工 1-2 周 |
| "文档会过时" | 所以写不重复代码行为的部分（WHY > WHAT）。WHAT 会变，WHY 相对稳定。 | 只写 WHAT → 文档随代码频繁过时 → 每次更新耗时 ×2；写 WHY → 更新频率低 |
| "功能简单不需要 README 更新" | README 是项目入口。新功能不写入=新功能不可发现。 | 新功能不可发现 → 用户不知道存在 → 功能利用率低 → ROI 下降 |
| "TODO 放代码里就行" | TODO 注释 = 不会追踪、不会 assign、不会排期。转成 issue。 | TODO 3 个月未解决 → 变成隐性 bug；转 issue → 可追踪可排期可 assign |
| "文档太费时间" | 一次 5 分钟的注释节省未来每个接手者 30 分钟。"我忘了为什么" = 文档成本的证明。 | 5 分钟文档 vs 30 分钟 × 5 个接手者 = 150 分钟总成本；文档 ROI = 30:1 |
| 验证项 | 失败表现 | 处理方式 |
|---|---|---|
| 公共 API 无文档 | 函数缺少 @param/@returns/@throws | 为每个公共函数补写 JSDoc；参数、返回类型、异常、示例 |
| 新架构决策无 ADR | "每个人都知道为什么" | 写 ADR：背景 + 2+ 选项 + 决策理由 + 后果；保存到 adr/ 目录 |
| README 快速开始不工作 | 新 checkout 执行步骤失败 | 逐步验证每个命令；修正缺失步骤或过时命令 |
| 注释掉的代码存在 | 被注释掉的旧代码块 | 删除注释代码；Git 有历史，不需要注释保留 |
| TODO 超过 3 个月 | 未解决的 TODO 注释 | 转为 issue：可追踪、可 assign、可排期；或删除已不相关的 TODO |
// WHY: 折扣必须在税之前计算，因为法规要求（见 REG-2024-0321）
function calculateTotal(items: Item[]): number { ... }
/**
* 创建新任务。
* @param input.title - 任务标题 (1-200 字符)
* @returns 新创建的任务，包含默认状态 'pending'
* @throws {ValidationError} 当标题为空或超过 200 字符
*/
async function createTask(input: CreateTaskInput): Promise<Task> { ... }
ADR-001: 选择 Prisma 作为 ORM — 有背景、有选项对比、有决策理由、有正面和负面后果
// 计算总价 ← 重复代码的注释，毫无价值
const total = items.reduce((sum, item) => sum + item.price, 0);
// TODO: 加错误处理 ← 不会追踪的 TODO
async function processPayment() { ... }
// const oldWay = await legacyApi.fetch(); ← 注释掉的代码
// 公共 API 无文档 → @param/@returns/@throws 缺失
// 新架构决策无 ADR → "每个人都知道为什么"
文档工程完成：
文档类型:
- ADR: [编号 + 标题 + 状态] (docs/features/<name>/adr/)
- 内联文档: WHY/GOTCHA/INTENT 注释 [N] 处
- API 文档: [N] 个公共函数已补写 JSDoc
- README: 快速开始已验证（全新 checkout 可执行）
Changelog:
- 最新条目已更新 (面向用户，不含内部细节)
清理:
- 注释代码已删除: [N] 处
- TODO 已转 issue: [N] 个 / 已删除: [N] 个
验证:
- 公共 API 文档覆盖率: [N/N]
- ADR 完整性: [背景+选项+理由+后果]
- README 快速开始可执行: [是/否]