Build Cognitive Decision Record

Decision Record — 架构决策记录 (ADR)

入口/出口

• 入口: build 中面临技术选型、方案取舍、架构决策
• 出口: docs/features/<name>/adr/<num>.md — 可追溯的决策文件
• 指向: 决策记录后继续 build
• 前置加载: CANON.md
• 输出路径: 决策记录后继续 build-workflow-execute

何时不使用

• 只是变量命名、局部文件拆分或框架惯例内的实现细节
• 方案没有真实取舍，只有一个显然符合现有模式的做法
• 已有 ADR 覆盖当前决策，只需要引用而不是新建

何时写 ADR

必须写: 选择技术方案（X vs Y）、改变架构模式、引入新依赖、选择数据存储方案、采用新通信模式、决定废弃某个系统

不必写: 选择变量名、文件拆分方式、单行实现细节、框架惯例（如 Next.js 的文件路由已经是框架决策）

Iron Law

每个重要设计决策必须记录。
"代码即文档"说明 WHAT，"ADR 即文档"说明 WHY。
没有 WHY 的决策在复盘时等于没做决策。

ADR 模板

优先使用 templates/feature/adr/template.md。ADR 必须记录 WHY，而不是把实现细节复制一遍；没有驱动因素、约束、选项对比、后果和可逆性，就不是可维护的决策记录。

# ADR-<NNN>: <简短标题>

## Status
- Status: proposed / accepted / rejected / superseded / deprecated
- Date: YYYY-MM-DD
- Owner:
- Feature: `<feature-name>`
- Supersedes: `ADR-<NNN>` / none
- Superseded By: `ADR-<NNN>` / none

## Decision Summary
- Decision:
- One-line rationale:
- Scope affected:

## Context
- Current situation:
- Problem or opportunity:
- Why this decision is needed now:
- What happens if we do nothing:

## Decision Drivers
| Driver | Priority | Notes |
|--------|----------|-------|
| | must / should / could | |

## Constraints
| Constraint | Source | Impact |
|------------|--------|--------|
| | spec / plan / code / external | |

## Options Considered
| Option | Description | Pros | Cons | Fit Against Drivers | Reversibility |
|--------|-------------|------|------|---------------------|---------------|
| A | | | | high / medium / low | reversible / costly / hard |
| B | | | | high / medium / low | reversible / costly / hard |

## Decision
- Selected option:
- Rejected options:
- Decision owner:
- Decision time:

## Rationale
- Why selected option wins:
- Why rejected options lose:
- Evidence that changed the decision:

## Consequences
### Positive
- <positive consequence>

### Negative
- <negative consequence>

### Neutral / Operational
- <operational consequence>

## Reversibility
- Reversal cost: low / medium / high
- Reversal trigger:
- Reversal steps:
- Migration / data impact:

## Follow-up
| Action | Owner | Due | Tracking |
|--------|-------|-----|----------|
| | | YYYY-MM-DD / n/a | |

## Evidence Links
- Spec:
- Plan:
- Code / PR:
- External references:
- Related ADRs:

决策生命周期

提议 ──→ 接受 ──→ (可能) 取代 ──→ (可能) 废弃
  │                           │
  └── 讨论后拒绝              └── 新 ADR 引用旧 ADR

不删除旧 ADR。 Git 有历史，ADR 也有历史。旧 ADR 被"取代"或"废弃"仍然留存——说明为什么当时做了那个决定、以及为什么后来改变了。

何时不算 ADR

不是所有选择都值得 ADR。阈值检查：

• 影响 > 1 个模块/服务的架构 → ADR
• 未来不可轻易改变的（数据模型、外部依赖、通信协议）→ ADR
• 只有一个人理解的隐式选择 → ADR
• 单文件实现细节 → 代码注释
• 框架的默认做法 → 不需要 ADR

示例

# ADR-001: 选择 Prisma 作为 ORM

## Status
- Status: accepted
- Date: 2026-04-24
- Owner: backend lead
- Feature: `task-data-model`
- Supersedes: none
- Superseded By: none

## Decision Summary
- Decision: 使用 Prisma 作为 PostgreSQL ORM
- One-line rationale: 类型安全、迁移工具和团队经验比 raw SQL 控制力更重要
- Scope affected: data access layer, migrations, generated types

## Context
- Current situation: 项目需要管理用户、任务和评论数据。
- Problem or opportunity: 手写 SQL 缺少类型生成和迁移约束。
- Why this decision is needed now: 数据模型进入实现前必须固定访问层。
- What happens if we do nothing: 查询风格会分散，migration 责任不清。

## Decision Drivers
| Driver | Priority | Notes |
|--------|----------|-------|
| TypeScript 类型安全 | must | DTO 和查询结果需要稳定类型 |
| 迁移可审计 | must | schema 变更必须可追踪 |
| 复杂查询控制 | should | 少量路径可用 raw SQL 逃生 |

## Constraints
| Constraint | Source | Impact |
|------------|--------|--------|
| 团队已有 Prisma 经验 | plan | 降低交付风险 |
| 数据库固定为 PostgreSQL | spec | 不需要跨数据库抽象 |

## Options Considered
| Option | Description | Pros | Cons | Fit Against Drivers | Reversibility |
|--------|-------------|------|------|---------------------|---------------|
| Prisma | schema-first ORM | 类型生成、迁移成熟、团队熟悉 | 复杂查询可能退回 raw SQL | high | costly |
| Drizzle | SQL-like ORM | 更接近 SQL、运行时轻 | 团队经验少、迁移流程需补齐 | medium | costly |
| TypeORM | decorator ORM | 生态成熟 | 装饰器风格和当前代码不匹配 | low | hard |

## Decision
- Selected option: Prisma
- Rejected options: Drizzle, TypeORM
- Decision owner: backend lead
- Decision time: 2026-04-24

## Rationale
- Why selected option wins: Prisma 同时满足类型安全、迁移成熟度和团队熟悉度。
- Why rejected options lose: Drizzle 增加学习和迁移流程风险；TypeORM 和当前架构风格不匹配。
- Evidence that changed the decision: 现有团队经验权重高于 ORM 运行时体积。

## Consequences
### Positive
- schema、migration 和生成类型形成统一数据合同。

### Negative
- 复杂查询可能需要 `$queryRaw`，需要 code review 关注 SQL 安全。

### Neutral / Operational
- CI 需要执行 migration 检查和 client generation。

## Reversibility
- Reversal cost: high
- Reversal trigger: Prisma 阻塞关键查询性能且 raw SQL 无法补救
- Reversal steps: 新建数据访问层 adapter，迁移 schema，逐步替换 repository
- Migration / data impact: schema 语义保持，迁移工具链需要切换

## Follow-up
| Action | Owner | Due | Tracking |
|--------|-------|-----|----------|
| 在 CI 加 prisma generate / migration check | backend lead | 2026-04-30 | plan task |

## Evidence Links
- Spec: `01-spec.md`
- Plan: `03-plan.md`
- Code / PR: pending
- External references: Prisma docs, Drizzle docs
- Related ADRs: none

常见说辞

红旗 — STOP

• 选择了不同方案的项目依赖，没人知道为什么
• "我记得我们讨论过 X，但不记得为什么不选 Y"
• 引入新依赖——没有记录其他竞争方案为什么没选
• 代码走了一条和项目约定不同的路——没有 ADR 解释
• 有人提议替换决策时的方案——没有 ADR 可查"为什么当初选它"

验证失败处理

好坏示例

Good: 有驱动、有对比、有可逆性

## Decision Drivers
| Driver | Priority | Notes |
|--------|----------|-------|
| Type safety | must | 查询结果需要稳定类型 |

## Options Considered
| Option | Pros | Cons | Fit Against Drivers | Reversibility |
|--------|------|------|---------------------|---------------|
| Prisma | 类型生成、迁移成熟 | 复杂查询可能退回 raw SQL | high | costly |
| Drizzle | 更接近 SQL | 团队经验少 | medium | costly |

## Rationale
- Why selected option wins: Prisma 更匹配 must-have 类型安全和迁移可审计。

## Reversibility
- Reversal cost: high
- Reversal trigger: 关键查询性能无法通过 raw SQL 补救

Bad: 无驱动、理由模糊、无可逆性

## Decision
选择 Prisma，因为大家都用。
## Consequences
(无)

输出模板

ADR 完成：

编号: ADR-<NNN>
标题: <简短标题>
状态: <提议/接受/取代/废弃>
路径: docs/features/<name>/adr/<num>.md

驱动因素:
  - <driver> → must/should/could
约束:
  - <constraint> → <source> → <impact>
选项评估:
  - 选项 A: <名称> → 优点/缺点/driver fit/可逆性
  - 选项 B: <名称> → 优点/缺点/driver fit/可逆性
决策: <选择>
理由: <一句话解释>
后果:
  - 正面: <列出>
  - 负面: <列出>
  - 运维: <列出>
可逆性: <low/medium/high + trigger + steps>
证据链接: <spec/plan/PR/external/related ADR>

验证清单

• ADR 包含背景（为什么需要决策）
• ADR 使用 templates/feature/adr/template.md 或保留等价章节
• Decision Drivers 和 Constraints 已记录
• 至少 2 个选项被评估（有"放弃"才有"选择"）
• 每个选项有优点/缺点/driver fit/可逆性
• 决策理由清晰（不是"因为大家都用"）
• 正面和负面后果都列出
• 被放弃的选项被明确列出
• Reversibility 写清撤销成本、触发条件、步骤和数据影响
• Evidence Links 能追到 spec、plan、代码/PR、外部依据或相关 ADR
• Supersedes / Superseded By 状态正确；旧 ADR 不删除
• ADR 文件编号并保存到 docs/features/<name>/adr/