Entry/Exit
- Entry: Facing technology selection, trade-offs, or architecture decisions in build
- Exit:
docs/features/<name>/adr/<num>.md— A traceable decision document - Points to: Continue build after the decision is recorded
- Preload: CANON.md
- Output path: Continue after the decision is recorded
build-workflow-execute
When not to use
- It is only variable naming, local file splitting, or an implementation detail within framework conventions
- The option has no real trade-off; there is only one approach that obviously fits the existing pattern
- An existing ADR already covers the current decision; it only needs to be referenced rather than created
When to write an ADR
Must write: Choosing a technology approach (X vs Y), changing an architecture pattern, introducing a new dependency, choosing a data storage approach, adopting a new communication pattern, deciding to deprecate a system
No need to write: Choosing variable names, file splitting approach, single-line implementation details, framework conventions (e.g., Next.js file routing is already a framework decision)
Iron Law
每个重要设计决策必须记录。
"代码即文档"说明 WHAT,"ADR 即文档"说明 WHY。
没有 WHY 的决策在复盘时等于没做决策。
ADR template
Prefer using templates/feature/adr/template.md. An ADR must record the WHY, not copy the implementation details once over; without drivers, constraints, option comparison, consequences, and reversibility, it is not a maintainable decision record.
# 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:
Decision lifecycle
提议 ──→ 接受 ──→ (可能) 取代 ──→ (可能) 废弃
│ │
└── 讨论后拒绝 └── 新 ADR 引用旧 ADR
Do not delete old ADRs. Git has history, and ADRs have history too. Old ADRs that are "superseded" or "deprecated" still remain—explaining why that decision was made at the time, and why it was later changed.
When it is not an ADR
Not every choice deserves an ADR. Threshold check:
- Architecture affecting > 1 module/service → ADR
- Things that cannot easily be changed later (data model, external dependencies, communication protocols) → ADR
- An implicit choice understood by only one person → ADR
- Single-file implementation detail → code comment
- The framework's default approach → no ADR needed
Examples
# 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
Common sayings
| Saying | Reality | Consequence |
|---|---|---|
| "Code is documentation" | Code shows WHAT. Six months later, WHY can only be found in the ADR. | Redoing the decision takes ×3 the time; the same path is repeatedly discussed, wasting the team 2-4 hours each time |
| "The decision is obvious, no need to record it" | Obvious to you ≠ obvious to the next person who takes over. A colleague 12 months later will not share your context. | The successor mistakenly overturns an existing decision → 1-2 weeks of rework; the same pitfall is stepped into repeatedly |
| "Nobody reads it if you write it" | When asked "why choose X"—send the ADR link. By the 5th time it is asked, the value of the ADR shows. | Verbal explanation ×5 times × 15 minutes = 75 minutes; one ADR only takes 10 minutes to write |
| "Record every choice" | ADRs are curated. Only those decisions that affect architecture, cannot easily be changed, or have multiple reasonable options need one. | Too many ADRs → signal-to-noise ratio drops → truly important decisions drown in noise |
Red flag — STOP
- A project dependency chose a different approach, and no one knows why
- "I remember we discussed X, but I don't remember why we didn't choose Y"
- Introducing a new dependency—no record of why other competing options were not chosen
- The code took a path different from the project convention—no ADR explains it
- Someone proposes replacing the approach chosen at decision time—no ADR to check "why it was chosen back then"
Validation Failure Handling
| Validation Item | Failure Symptom | Handling Method |
|---|---|---|
| Missing Context | The ADR only says "choose X" and does not say why a decision was needed | Add context: constraints, drivers, current problems |
| Insufficient Options | Only 1 option was evaluated, with no comparison | Add at least 1 competing option and evaluate its pros and cons |
| Vague Decision Rationale | The rationale is "everyone uses it" or "it feels good" | Replace with concrete evidence: performance data, team experience, constraint fit |
| Missing Consequences | Only positive consequences are listed, not negative ones | Add negative consequences and the value of the abandoned options |
| Missing Reversibility | It is unclear how the decision can be revoked or replaced in the future | Add Reversibility: cost, trigger conditions, rollback steps, data impact |
| Missing Evidence Links | The ADR cannot be traced to a spec, plan, PR, or external basis | Add Evidence Links; if there is no evidence, mark it as requiring verification |
| ADR Not Numbered and Saved | The ADR was written but not placed in docs/features//adr/ | Save it to the correct path by number to ensure it can be referenced |
Good and Bad Examples
Good: has drivers, has comparison, has reversibility
## 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: no drivers, vague rationale, no reversibility
## Decision
选择 Prisma,因为大家都用。
## Consequences
(无)
Output Template
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>
Validation Checklist
- The ADR includes context (why a decision is needed)
- The ADR uses
templates/feature/adr/template.mdor retains equivalent sections - Decision Drivers and Constraints are recorded
- At least 2 options are evaluated (there is only a "choice" if there is something "abandoned")
- Each option has pros/cons/driver fit/reversibility
- The decision rationale is clear (not "because everyone uses it")
- Both positive and negative consequences are listed
- Abandoned options are explicitly listed
- Reversibility clearly states revocation cost, trigger conditions, steps, and data impact
- Evidence Links can be traced to specs, plans, code/PRs, external bases, or related ADRs
- Supersedes / Superseded By status is correct; old ADRs are not deleted
- The ADR file is numbered and saved in
docs/features/<name>/adr/