文档与架构决策记录

记录决策，而不仅仅是代码。最有价值的文档记录的是背后的原因。

使用场景

• 做出重大架构决策
• 在多种方案之间进行选择
• 新增或修改公开 API
• 发布改变用户行为的功能
• 为新团队成员（或智能体）介绍项目

架构决策记录（ADR）

ADR 记录了重大技术决策背后的推理过程。

何时编写 ADR

• 选择框架、库或主要依赖
• 设计数据模型或数据库架构
• 选择认证策略
• 决定 API 架构（REST vs. GraphQL vs. tRPC）
• 任何撤销成本较高的决策

ADR 模板

将 ADR 存放在 docs/decisions/ 目录中，按顺序编号：

# ADR-001：使用 PostgreSQL 作为主数据库

## 状态
已接受 | 被 ADR-XXX 替代 | 已废弃

## 日期
2025-01-15

## 背景
我们需要为任务管理应用选择主数据库。关键要求：
- 关系型数据模型（用户、任务、团队之间的关联）
- 任务状态变更需要 ACID 事务支持
- 支持任务内容的全文搜索
- 提供托管服务

## 决策
使用 PostgreSQL 搭配 Prisma ORM。

## 考虑过的备选方案

### MongoDB
- 优点：灵活的 Schema，上手容易
- 缺点：我们的数据本质上是关系型的；需要手动管理关联关系
- 否决原因：在文档存储中处理关系型数据会导致复杂的连接或数据重复

### SQLite
- 优点：零配置、嵌入式、读取速度快
- 缺点：并发写入支持有限，无生产环境托管服务
- 否决原因：不适合生产环境中的多用户 Web 应用

## 影响
- Prisma 提供类型安全的数据库访问和迁移管理
- 可以使用 PostgreSQL 的全文搜索，无需额外引入 Elasticsearch
- 团队需要掌握 PostgreSQL 知识（标准技能，风险较低）

ADR 生命周期

已提议 → 已接受 → （已替代 或 已废弃）

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

内联文档

何时添加注释

注释为什么，而不是是什么：

// 不好：复述代码
// 计数器加 1
counter += 1;

// 好：解释非显而易见的意图
// 速率限制使用滑动窗口——在窗口边界重置计数器，
// 而不是在固定时间点，以防止窗口边缘的突发攻击
if (now - windowStart > WINDOW_SIZE_MS) {
  counter = 0;
  windowStart = now;
}

何时不添加注释

// 不要注释自解释的代码
function calculateTotal(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

// 不要为应该立即完成的事情留 TODO 注释
// TODO: 添加错误处理  ← 直接添加即可

// 不要保留被注释掉的代码
// const oldImplementation = () => { ... }  ← 删除它，git 有历史记录

API 文档

内联类型文档（TypeScript 首选）

/**
 * 创建一个新任务。
 *
 * @param input - 任务创建数据（title 必填，description 可选）
 * @returns 创建的任务，包含服务器生成的 ID 和时间戳
 * @throws {ValidationError} 如果 title 为空或超过 200 个字符
 * @throws {AuthenticationError} 如果用户未通过认证
 *
 * @example
 * const task = await createTask({ title: 'Buy groceries' });
 * console.log(task.id); // "task_abc123"
 */
export async function createTask(input: CreateTaskInput): Promise<Task> {
  // ...
}

README 结构

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

# 项目名称

一段话描述本项目的作用。

## 快速开始
1. 克隆仓库
2. 安装依赖：`npm install`
3. 配置环境：`cp .env.example .env`
4. 启动开发服务器：`npm run dev`

## 命令
| 命令 | 说明 |
|------|------|
| `npm run dev` | 启动开发服务器 |
| `npm test` | 运行测试 |
| `npm run build` | 生产构建 |
| `npm run lint` | 运行代码检查 |

## 架构
简要概述项目结构和关键设计决策。
详见 ADR 文档。

## 贡献指南
如何参与贡献、编码规范、PR 流程。

变更日志维护

已发布功能的记录格式：

# 变更日志

## [1.2.0] - 2025-01-20
### 新增
- 任务分享：用户可以将任务分享给团队成员 (#123)
- 任务分配的邮件通知 (#124)

### 修复
- 快速点击创建按钮时出现重复任务的问题 (#125)

### 变更
- 任务列表每页加载数量从 20 条调整为 50 条，提升用户体验 (#126)

面向智能体的文档

针对 AI 智能体的特殊考虑：

• CLAUDE.md / 规则文件 —— 记录项目规范，让智能体遵循
• 规格说明文件 —— 保持规格文档更新，确保智能体构建正确的内容
• ADR —— 帮助智能体理解过去决策的原因
• 内联注意事项 —— 防止智能体落入已知的陷阱

验证

文档编写完成后检查：

• 所有重大架构决策都有对应的 ADR
• README 涵盖了快速开始、命令和架构概览
• API 函数有参数和返回类型的文档
• 已知的注意事项在相关位置有内联记录
• 没有残留的注释掉的代码
• 规则文件（CLAUDE.md 等）是最新的且准确的