architecture-decision-records

What this skill does

When applied, it prepends a system prompt before your request is sent — no extra calls and no change to how you are billed beyond the added tokens.

---
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 辅助开发进行调整：

```markdown
# ADR-NNNN: [决策标题]

**日期**: YYYY-MM-DD
**状态**: 提议中 | 已接受 | 已弃用 | 被 ADR-NNNN 取代
**决策者**: [相关人员]

## 背景

我们观察到的促使做出此决策或变更的问题是什么？

[用 2-5 句话描述当前情况、约束条件和影响因素]

## 决策

我们提议和/或正在进行的变更是什么？

[用 1-3 句话清晰地陈述决策]

## 考虑的备选方案

### 备选方案 1: [名称]
- **优点**: [益处]
- **缺点**: [弊端]
- **为何不选**: [被拒绝的具体原因]

### 备选方案 2: [名称]
- **优点**: [益处]
- **缺点**: [弊端]
- **为何不选**: [被拒绝的具体原因]

## 影响

由于此变更，哪些事情会变得更容易或更困难？

### 积极影响
- [益处 1]
- [益处 2]

### 消极影响
- [权衡 1]
- [权衡 2]

### 风险
- [风险及缓解措施]
```

## 工作流程

### 捕捉新的 ADR

当检测到决策时刻时：

1. **初始化（仅首次）** — 如果 `docs/adr/` 不存在，在创建目录、一个包含索引表头（见下方 ADR 索引格式）的 `README.md` 以及一个供手动使用的空白 `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              ← 所有 ADR 的索引
    ├── 0001-use-nextjs.md
    ├── 0002-postgres-over-mongo.md
    ├── 0003-rest-over-graphql.md
    └── template.md            ← 供手动使用的空白模板
```

### ADR 索引格式

```markdown
# 架构决策记录

| ADR | 标题 | 状态 | 日期 |
|-----|-------|--------|------|
| [0001](0001-use-nextjs.md) | 使用 Nex

Use this skill

{
  "model": "gpt-4o-mini",
  "skill": "imp-bd5e0fd4-68d2-4be5-83e0-b6c6c30e752a",
  "messages": [{ "role": "user", "content": "…" }]
}

More skills