---

name: architecture-decision-records description: 在Claude Code会话期间捕获架构决策并记录为结构化ADR。自动检测决策时刻，记录上下文、考虑的替代方案和理由。维护ADR日志，让未来的开发者理解代码库为何如此设计。 origin: ECC

架构决策记录

在编码会话中实时捕获架构决策。与其让决策只存在于Slack线程、PR评论或某人的记忆中，此技能生成结构化的ADR文档，与代码一起存放。

何时激活

• 用户明确说"让我们记录这个决策"或"ADR这个"
• 用户在重要替代方案之间做选择（框架、库、模式、数据库、API设计）
• 用户说"我们决定..."或"我们做X而不是Y的原因是..."
• 用户问"我们为什么选择X？"（读取现有ADR）
• 在讨论架构权衡的规划阶段

ADR格式

使用Michael Nygard提出的轻量级ADR格式，适配AI辅助开发：

# ADR-NNNN: [Decision Title]

**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
**Deciders**: [who was involved]

## Context

What is the issue that we're seeing that is motivating this decision or change?

[2-5 sentences describing the situation, constraints, and forces at play]

## Decision

What is the change that we're proposing and/or doing?

[1-3 sentences stating the decision clearly]

## Alternatives Considered

### Alternative 1: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific reason this was rejected]

### Alternative 2: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific reason this was rejected]

## Consequences

What becomes easier or more difficult to do because of this change?

### Positive
- [benefit 1]
- [benefit 2]

### Negative
- [trade-off 1]
- [trade-off 2]

### Risks
- [risk and mitigation]

工作流程

捕获新ADR

当检测到决策时刻时：

1. 初始化（仅首次） — 如果 docs/adr/ 不存在，在创建目录前征求用户确认，创建带有索引表头的 README.md（见下方ADR索引格式）和空白 template.md 供手动使用。未经明确同意不创建文件。
2. 识别决策 — 提取正在做出的核心架构选择
3. 收集上下文 — 什么问题促成了这个决策？存在什么约束？
4. 记录替代方案 — 考虑了哪些其他选项？为什么被拒绝？
5. 陈述后果 — 权衡是什么？什么变得更容易/更难？
6. 分配编号 — 扫描 docs/adr/ 中现有ADR并递增
7. 确认并写入 — 向用户展示ADR草稿供审查。仅在明确批准后写入 docs/adr/NNNN-decision-title.md。如果用户拒绝，丢弃草稿不写入任何文件。
8. 更新索引 — 追加到 docs/adr/README.md

读取现有ADR

当用户问"我们为什么选择X？"时：

1. 检查 docs/adr/ 是否存在 — 如果不存在，回复："此项目中未找到ADR。你想开始记录架构决策吗？"
2. 如果存在，扫描 docs/adr/README.md 索引查找相关条目
3. 读取匹配的ADR文件并展示上下文和决策部分
4. 如果未找到匹配，回复："未找到该决策的ADR。你想现在记录一个吗？"

ADR目录结构

docs/
└── adr/
    ├── README.md              ← index of all ADRs
    ├── 0001-use-nextjs.md
    ├── 0002-postgres-over-mongo.md
    ├── 0003-rest-over-graphql.md
    └── template.md            ← blank template for manual use

ADR索引格式

# Architecture Decision Records

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [0001](0001-use-nextjs.md) | Use Next.js as frontend framework | accepted | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | PostgreSQL over MongoDB for primary datastore | accepted | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | REST API over GraphQL | accepted | 2026-02-01 |

决策检测信号

在对话中观察这些表明架构决策的模式：

显式信号

• "让我们用X"
• "我们应该用X而不是Y"
• "这个权衡值得因为..."
• "记录这个为ADR"

隐式信号（建议记录ADR——未经用户确认不自动创建）

• 比较两个框架或库并得出结论
• 做出有明确理由的数据库模式设计选择
• 在架构模式之间选择（单体vs微服务、REST vs GraphQL）
• 决定认证/授权策略
• 在评估替代方案后选择部署基础设施

什么是好的ADR

应该

• 具体 — "使用Prisma ORM"而非"使用ORM"
• 记录上下文 — 未来的读者需要理解当时的约束
• 诚实对待权衡 — 每个决策都有缺点，记录它们
• 保持简短 — 一个ADR应该在5分钟内可读完