reflect-team-documentation

Documentation — Documentation Engineering

Entry/Exit

• Entry: feature complete, architecture decision made, API added/modified, project convention discovered
• Exit: citable documentation + ADR files
• Points to: return to the original flow after documentation is complete
• Preload: CANON.md + build-cognitive-decision-record/SKILL.md(when an ADR needs to be written)
• Output path: return to ship-workflow-ship or verify-workflow-review

When not to use

• Just code implementation or bug fixing, with no change to the documentation contract
• The decision has not yet formed and is still in the brainstorm/refine stage
• Just an oral explanation to the user, with no need to leave a project-level record

Iron Law

记录决策，不只是记录代码。
最有价值的文档记录的是 WHY。
代码显示 WHAT。文档说明 WHY。

Four kinds of documentation

First divide into slots, then write templates. Unified's project-level documentation layering is fixed as:

1. Root docs
   • README.md
   • AGENTS.md
   • CHANGELOG.md
   • DESIGN.md
2. Project docs
   • docs/architecture/*.md
3. Feature docs
   • docs/features/YYYYMMDD-<name>/*
4. Bug docs
   • docs/bugs/<name>/*

By default, feature work only updates feature docs. Only when the long-term truth changes do you also sync root docs or project docs。

1. ADR — Architecture Decision Record

See build-cognitive-decision-record/SKILL.md. Supplemented here:

ADR lifecycle:

• Proposed → under discussion
• Accepted → decided, being implemented
• Superseded → replaced by a new ADR (the old one is retained)
• Deprecated → the decision no longer applies (retained as history)

Do not delete old ADRs. Old ADRs have historical value just like code.

2. Inline documentation

When to write comments:

// 写 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 行级锁

When not to write comments:

// 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 有历史，删掉注释掉的代码

Principle: Write comments to explain things the code itself cannot express. If the code can express it clearly → don't write it. If you can't write it correctly, change the code to make it clearer.

3. API documentation

/**
 * 创建新任务。
 * 
 * @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 documentation standards:

• Every public function/endpoint has a description
• Parameters and return types are documented
• Thrown exceptions are documented
• Includes usage examples
• Do not repeat type signatures (TypeScript types already describe the structure)

4. README and project documentation

项目 README 应包含:
├── 项目是什么 (1 句)
├── 快速开始 (安装 + 运行 < 5 行)
├── 开发命令 (build/test/lint/dev)
├── 项目结构 (顶层目录 + 说明)
├── 关键约定 (非标准但规则)
└── 部署 (在哪运行、怎么部署)

The README is for people encountering the project for the first time. Don't write documentation for experts (experts don't need it), write it for newcomers (newcomers need it).

Minimal set of project-level documentation:

• README.md — project entry, startup, commands, structure, deployment entry
• AGENTS.md — entry contract, activation gates, project constraints (detailed runtime rules are loaded on demand in docs/contracts/ )
• CHANGELOG.md — user-perceivable changes / release records
• DESIGN.md — cross-feature design tokens and long-term design constraints
• docs/architecture/system-overview.md
• docs/architecture/module-boundaries.md
• docs/architecture/deployment-and-runtime.md
• docs/architecture/observability-and-runbook.md

Extend on demand:

• docs/architecture/api-contracts.md
• docs/architecture/data-model.md
• docs/architecture/security-boundaries.md

Do not treat project docs as a feature archive. The feature process stays in docs/features/; project docs only retain the current long-term truth.

Documentation for AI Agents

Documentation in the codebase is also consumed by AI agents. AI reads documentation differently from humans:

AI 需要的文档:
├── AGENTS.md / CLAUDE.md → 项目命令、测试方法、架构概览
├── Spec → 需求 + 验收条件
├── ADR → 架构决策 + 为什么
└── 代码注释 → WHY、GOTCHA、INTENT（不重复代码）

AI 不需要的:
├── README 里的长段历史
├── CONTRIBUTING 中的 Git 工作流教程（AI 有自己的一套）
├── 重复 JSDoc 类型的注释

New discoveries of project conventions → write into AGENTS.md. CLAUDE.md Retain only Claude-side pointers or supplementary hints, and no longer carry the complete project contract.

Changelog Maintenance

## [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

Changelogs are user-facing. "Refactored TaskService" = internal detail, users don't care. "Task list supports pagination (prevents page crashes)" = users need to know.

Common Excuses

Excuse	Reality	Consequence
"Code is self-explanatory, no docs needed"	Code tells you what it does. Docs tell you why it was done, why the alternative wasn't chosen, and what pitfalls to watch out for.	New hire onboarding takes ×3 longer; WHY information is lost → existing decisions get mistakenly overturned → 1-2 weeks of rework
"Docs will go stale"	So write the parts that don't duplicate code behavior (WHY > WHAT). WHAT changes, WHY is relatively stable.	Writing only WHAT → docs frequently go stale as code changes → each update takes ×2 longer; writing WHY → low update frequency
"Simple features don't need README updates"	The README is the project's entry point. Not documenting a new feature = the new feature is undiscoverable.	New feature undiscoverable → users don't know it exists → low feature utilization → ROI drops
"Just put TODOs in the code"	TODO comments = won't be tracked, won't be assigned, won't be scheduled. Convert them to issues.	TODO unresolved for 3 months → becomes a hidden bug; convert to issue → trackable, schedulable, assignable
"Docs take too much time"	A one-time 5-minute comment saves 30 minutes for every future maintainer. "I forgot why" = proof of the cost of missing docs.	5 minutes of docs vs 30 minutes × 5 maintainers = 150 minutes total cost; docs ROI = 30:1

Red Flags — STOP

• Commented-out code blocks (delete them — Git has history)
• TODO comments unresolved for more than 3 months
• Function logic changed but comments/docs not updated (now the docs are false)
• Public API has no docs (at least @param/@returns/@throws)
• README quick start steps don't work in a fresh checkout
• New architecture decisions have no ADR — "everyone knows why" = a year later no one knows why

Validation Failure Handling

Validation Item	Failure Symptom	Handling
Public API has no docs	Functions lack @param/@returns/@throws	Write JSDoc for every public function; parameters, return types, exceptions, examples
New architecture decisions have no ADR	"Everyone knows why"	Write an ADR: context + 2+ options + decision rationale + consequences; save to the adr/ directory
README quick start doesn't work	Steps fail when executed in a fresh checkout	Verify each command step by step; fix missing steps or outdated commands
Commented-out code exists	Old code blocks that have been commented out	Delete commented-out code; Git has history, no need to keep it in comments
TODO older than 3 months	Unresolved TODO comments	Convert to an issue: trackable, assignable, schedulable; or delete TODOs that are no longer relevant

Good and Bad Examples

Good: WHY comments + ADR + complete API docs

// 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: Choose Prisma as the ORM — includes context, options comparison, decision rationale, and positive and negative consequences

Bad: WHAT comments + no ADR + empty documentation

// 计算总价  ← 重复代码的注释，毫无价值
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 → "每个人都知道为什么"

Output Template

文档工程完成：

文档类型:
  - 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 快速开始可执行: [是/否]

Verification Checklist

• Public API is documented (parameters, return types, exceptions, examples)
• New architectural decisions have an ADR
• README quick start can be executed in a fresh checkout
• Changelog has been updated (if the feature has user impact)
• Commented-out code has been removed
• TODO comments have been converted to issues or have become part of an ADR