documentation-and-adrs

文档与 ADR

概述

记录决策，而不只是代码。最有价值的文档会说明原因——做出决策时的背景、约束和权衡。代码展示了构建了什么；文档解释了为什么这样构建以及考虑过哪些替代方案。这些背景信息对未来在代码库中工作的人员和 Agent 至关重要。

适用场景

• 做出重要的架构决策
• 在多个竞争方案中做出选择
• 添加或更改公共 API
• 发布会改变用户可见行为的功能
• 帮助新团队成员（或 Agent）熟悉项目
• 发现自己在反复解释同一件事

不适用场景： 不要记录一目了然的代码。不要添加复述代码已有内容的注释。不要为一次性原型编写文档。

架构决策记录（ADR）

ADR 记录重要技术决策背后的理由。它们是最有价值的文档。

何时编写 ADR

• 选择框架、库或主要依赖项
• 设计数据模型或数据库架构
• 选择身份验证策略
• 决定 API 架构（REST、GraphQL 还是 tRPC）
• 在构建工具、托管平台或基础设施之间做出选择
• 做出任何难以撤销的决策

首先遵循现有约定

创建 ADR 之前，请检查可用的代码库上下文，确认是否已有成熟约定——例如现有 ADR、项目说明以及 ADR 相关配置或工具（如 .adr-dir 文件）。已有约定优先于以下默认做法。请遵循：

• 位置和格式 — 例如 docs/adr/*.md、Documentation/Decisions/*.rst、MADR 布局或 adr-tools 配置。遵循现有目录、文件扩展名和标记格式（Markdown 或 reStructuredText）。
• 编号和命名 — 延续现有序列和文件名模式（ADR-004-Title.rst、0004-title.md、……）；不要从 001 重新开始，也不要引入第二套编号规则。
• 章节标题 — 沿用项目现有的标题集合，而不是强行套用此模板。

如果现有证据相互矛盾，请指出矛盾，不要悄然引入另一套规则。只有在无法确定任何约定时，才采用以下默认做法。

ADR 模板

将 ADR 存储在 docs/decisions/ 中，并按顺序编号（除非项目已采用其他位置——见上文）：

# ADR-001: Use PostgreSQL for primary database

## Status
Proposed | Accepted | Superseded by ADR-XXX | Deprecated

## Date
2025-01-15

## Context
We need a primary database for the task management application. Key requirements:
- Relational data model (users, tasks, teams with relationships)
- ACID transactions for task state changes
- Support for full-text search on task content
- Managed hosting available (for small team, limited ops capacity)

## Decision
Use PostgreSQL with Prisma ORM.

## Alternatives Considered

### MongoDB
- Pros: Flexible schema, easy to start with
- Cons: Our data is inherently relational; would need to manage relationships manually
- Rejected: Relational data in a document store leads to complex joins or data duplication

### SQLite
- Pros: Zero configuration, embedded, fast for reads
- Cons: Limited concurrent write support, no managed hosting for production
- Rejected: Not suitable for multi-user web application in production

### MySQL
- Pros: Mature, widely supported
- Cons: PostgreSQL has better JSON support, full-text search, and ecosystem tooling
- Rejected: PostgreSQL is the better fit for our feature requirements

## Consequences
- Prisma provides type-safe database access and migration management
- We can use PostgreSQL's full-text search instead of adding Elasticsearch
- Team needs PostgreSQL knowledge (standard skill, low risk)
- Hosting on managed service (Supabase, Neon, or RDS)

ADR 生命周期

PROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED)

• 不要删除旧 ADR。 它们记录了历史背景。
• 决策发生变化时，编写一份新的 ADR，并引用和取代旧 ADR。

行内文档

何时添加注释

注释应说明原因，而不是内容：

// BAD: Restates the code
// Increment counter by 1
counter += 1;

// GOOD: Explains non-obvious intent
// Rate limit uses a sliding window — reset counter at window boundary,
// not on a fixed schedule, to prevent burst attacks at window edges
if (now - windowStart > WINDOW_SIZE_MS) {
  counter = 0;
  windowStart = now;
}

何时不添加注释

// Don't comment self-explanatory code
function calculateTotal(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

// Don't leave TODO comments for things you should just do now
// TODO: add error handling  ← Just add it

// Don't leave commented-out code
// const oldImplementation = () => { ... }  ← Delete it, git has history

记录已知的注意事项

/**
 * IMPORTANT: This function must be called before the first render.
 * If called after hydration, it causes a flash of unstyled content
 * because the theme context isn't available during SSR.
 *
 * See ADR-003 for the full design rationale.
 */
export function initializeTheme(theme: Theme): void {
  // ...
}

API 文档

对于公共 API（REST、GraphQL、库接口）：

与类型一同编写（TypeScript 首选）

/**
 * Creates a new task.
 *
 * @param input - Task creation data (title required, description optional)
 * @returns The created task with server-generated ID and timestamps
 * @throws {ValidationError} If title is empty or exceeds 200 characters
 * @throws {AuthenticationError} If the user is not authenticated
 *
 * @example
 * const task = await createTask({ title: 'Buy groceries' });
 * console.log(task.id); // "task_abc123"
 */
export async function createTask(input: CreateTaskInput): Promise<Task> {
  // ...
}

REST API 的 OpenAPI / Swagger

paths:
  /api/tasks:
    post:
      summary: Create a task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskInput'
      responses:
        '201':
          description: Task created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '422':
          description: Validation error

README 结构

每个项目都应有一份涵盖以下内容的 README：

# Project Name

One-paragraph description of what this project does.

## Quick Start
1. Clone the repo
2. Install dependencies: `npm install`
3. Set up environment: `cp .env.example .env`
4. Run the dev server: `npm run dev`

## Commands
| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server |
| `npm test` | Run tests |
| `npm run build` | Production build |
| `npm run lint` | Run linter |

## Architecture
Brief overview of the project structure and key design decisions.
Link to ADRs for details.

## Contributing
How to contribute, coding standards, PR process.

维护变更日志

对于已发布的功能：

# Changelog

## [1.2.0] - 2025-01-20
### Added
- Task sharing: users can share tasks with team members (#123)
- Email notifications for task assignments (#124)

### Fixed
- Duplicate tasks appearing when rapidly clicking create button (#125)

### Changed
- Task list now loads 50 items per page (was 20) for better UX (#126)

面向 Agent 的文档

AI Agent 上下文需要特别考虑：

• CLAUDE.md / 规则文件 — 记录项目约定，帮助 Agent 遵循这些约定
• 规格文件 — 保持规格文件更新，以便 Agent 构建正确的内容
• ADR — 帮助 Agent 理解过去做出决策的原因（避免重复决策）
• 行内注意事项 — 防止 Agent 落入已知陷阱

文案审阅

检查完技术内容后，请为使用文档的读者审阅文案。措辞更清晰不能改变决策或其适用范围。

1. 标记编辑时必须保留的细节：名称、数字和单位、命令、路径、链接、条件、权衡和不确定性。对照现有代码和决策背景检查这些细节；标出无法证实的内容。
2. 用读者需要的具体信息替换套话式开场、宣传性形容词和重复的总结。不要用臆造的示例或更强的保证替换缺乏依据的说法。保留必要的技术重复和项目既定术语。
3. 将编辑后的文档与原文及其来源进行比较。恢复遗漏的限定语或注意事项，并验证命令和代码示例仍与文档所述一致且可用。对于尚未解决的事实问题，应予以说明，而不是润色掉。

常见的自我辩解

自我辩解	实际情况
“代码会自我说明”	代码能说明是什么，却无法说明为什么、否决了哪些替代方案，或适用哪些限制。
“等 API 稳定后再写文档”	编写文档能让 API 更快稳定下来。文档是设计的第一项测试。
“没人看文档”	Agent 会看，未来的工程师会看，三个月后的你也会看。
“ADR 是额外负担”	一份用时 10 分钟的 ADR，可以避免六个月后围绕同一决策争论 2 小时。
“注释会过时”	解释为什么的注释很稳定。解释是什么的注释会过时——所以只写前者。

危险信号

• 没有书面依据的架构决策
• 没有文档或类型说明的公共 API
• 未说明如何运行项目的 README
• 用注释掉的代码代替删除
• 已存在数周的 TODO 注释
• 存在重大架构选择的项目却没有 ADR
• 只是复述代码、没有解释意图的文档

验证

完成文档编写后：

• 所有重大架构决策都有 ADR
• README 涵盖快速入门、命令和架构概览
• API 函数都有参数和返回类型文档
• 在相关位置内联记录已知注意事项
• 不再保留注释掉的代码
• 规则文件（如 CLAUDE.md）是最新且准确的
• 文案编辑保留了来源细节、决策权衡和限定语，且未添加缺乏依据的保证