adr-skill

ADR 技能

理念

使用此技能创建的 ADR 是面向编码 Agent 的可执行规范。由人类批准决策，由 Agent 实施。ADR 必须包含 Agent 编写正确代码所需的一切信息，无需追问。

这意味着：

• 约束必须明确且可衡量，而不是凭感觉
• 决策必须具体到可执行（“使用 PostgreSQL 16 和 pgvector”，而不是“使用数据库”）
• 后续影响必须对应到具体的后续任务
• 必须说明非目标，以防范围蔓延
• ADR 必须自成一体，不得假设存在只有内部人员才知道的信息
• ADR 必须包含实施计划——要修改哪些文件、要遵循哪些模式、要编写哪些测试，以及如何验证决策是否得到正确实施

何时编写 ADR

在决策符合以下任一情况时编写 ADR：

• 会改变系统的构建或运行方式（新增依赖、架构模式、基础设施选择、API 设计）
• 一旦代码基于该决策编写完成，就难以逆转
• 会影响之后在此代码库中工作的其他人员或 Agent
• 存在经过考虑并被否决的实际替代方案

以下情况不要编写 ADR：

• 在既定模式内进行常规实现选择
• 修复 Bug 或更正拼写错误
• 已在现有 ADR 中记录的决策（应更新现有 ADR）
• 已由代码检查工具或格式化工具涵盖的风格偏好

如有疑问：如果未来在此代码库中工作的 Agent 能从了解“为何做出此选择”中受益，就编写 ADR。

主动触发 ADR 的情形（适用于 Agent）

如果你是在代码库中编写代码的 Agent，并遇到以下任一情况，请停下来，先提议编写 ADR：

• 你即将引入项目中尚不存在的新依赖
• 你即将创建新的架构模式（新的错误处理方式、新的数据访问层、新的 API 约定），其他代码也需要遵循该模式
• 你即将在两个或多个实际替代方案之间做出选择，且其权衡并非显而易见
• 你即将更改与现有已接受的 ADR 相矛盾的内容
• 你发现自己正在编写冗长的代码注释来解释“原因”——这类推理应记录在 ADR 中

提议方式：告诉人类你遇到了什么决策、为何重要，并询问他们是否要将其记录为 ADR。如果同意，请执行完整的四阶段工作流。如果不同意，请在代码注释中记录该决策，然后继续。

创建 ADR：四阶段工作流

每个 ADR 都必须经过四个阶段。不要跳过任何阶段。

阶段 0：扫描代码库

在提问之前，先从代码库中收集上下文：

1. 查找现有 ADR。 检查 docs/decisions/、adr/、docs/adr/、decisions/ 中是否存在已有记录。阅读这些记录，并记下：

   • 现有约定（目录、命名、模板风格）
   • 与当前决策相关或对其有所约束的决策
   • 此新决策可能取代的任何 ADR

2. 检查技术栈。 阅读 package.json、go.mod、requirements.txt、Cargo.toml 或同类文件。记下相关依赖及其版本。

3. 查找相关代码模式。 如果决策涉及特定领域（例如“如何处理身份验证”），请扫描现有实现。确定会受该决策影响的具体文件、目录和模式。

4. 检查代码中的 ADR 引用。 查找注释和文档中的 ADR-NNNN 引用（参见下文“代码 ↔ ADR 链接”）。这有助于了解哪些现有决策约束着代码库的哪些部分。

5. 记录发现。 将这些上下文带入阶段 1，以便完善问题，避免 ADR 与现有决策相矛盾。

阶段 1：捕捉意图（苏格拉底式提问）

采访用户，了解决策空间。每次只问一个问题，并根据之前的回答逐步深入。不要一次性列出一串问题。

核心问题（大致按以下顺序提问；对于上下文或阶段 0 已明确的内容可跳过）：

1. 你要做什么决策？——拟定一个简短、具体的标题。尽量使用动词短语（“选择 X”“采用 Y”“用 W 替换 Z”）。
2. 为什么是现在？——出了什么问题、有什么变化，或者如果什么都不做会出什么问题？这就是触发因素。
3. 有哪些约束？——技术栈、时间线、预算、团队规模、现有代码、合规要求。尽量具体。结合阶段 0 的发现进行询问（“我看到你们已经在使用 X——这会对决策构成约束吗？”）。
4. 成功是什么样的？——可衡量的结果。不要停留在“能用”，应进一步明确具体指标（延迟、吞吐量、开发体验、维护负担）。
5. 你考虑过哪些选项？——至少两个。每个选项的核心权衡是什么？如果只有一个选项，帮用户说明为何排除了其他方案。
6. 你目前倾向于哪种方案？——尽早了解直觉倾向。这往往能揭示尚未明说的优先事项。
7. 哪些人需要知情或批准？——决策者、受咨询的专家、需要获知情况的利益相关者。
8. Agent 需要做些什么才能实现这一方案？——会影响哪些文件／目录？应遵循哪些现有模式？应避免什么？哪些测试可以证明方案有效？这些内容会直接用于实施计划。

自适应追问：根据回答，在决策不够明确的地方深入追问。常见追问包括：

• “如果这个决策错了，最坏会有什么后果？”
• “什么情况会让你在 6 个月后重新考虑这个决策？”
• “有没有什么事情是你明确选择不做的？”
• “这与代码库中的哪些先例或现有模式有关？”
• “我找到了 [现有 ADR／模式]——这个新决策会与它产生交互吗？”

何时停止：当你能够填写 ADR 的每个部分（包括实施计划）且无需编造内容时，就收集得足够了。如果任何部分需要猜测，就再问一个问题。

意图摘要确认：进入阶段 2 前，先以结构化摘要的形式呈现你收集到的信息，并请用户确认或更正：

以下是我为 ADR 记录的内容：

• 标题：{title}
• 触发因素：{why now}
• 约束：{list}
• 选项：{option 1} 与 {option 2}［以及其他选项……］
• 倾向：{which option and why}
• 非目标：{what's explicitly out of scope}
• 相关 ADR／代码：{what exists that this interacts with}
• 受影响的文件／区域：{where in the codebase this lands}
• 验证方式：{how we'll know it's implemented correctly}

这准确反映了你的意图吗？有什么需要补充或更正的吗？

用户确认摘要之前，不得进入阶段 2。

第 2 阶段：起草 ADR

1. 选择 ADR 目录。

   • 如果目录已存在（在第 0 阶段找到），就使用它。
   • 如果不存在，则创建 docs/decisions/（MADR 默认目录）或 adr/（更简单的仓库）。

2. 选择文件名策略。

   • 如果现有 ADR 使用数字前缀（0001-...），就沿用该格式。
   • 否则使用仅含 slug 的文件名（choose-database.md）。

3. 选择模板。

   • 对于简单明了的决策（有一个明确的最佳选项，权衡取舍较少），使用 assets/templates/adr-simple.md。
   • 如果需要用结构化的优缺点和驱动因素来记录多个选项，则使用 assets/templates/adr-madr.md。
   • 请参阅 references/template-variants.md 获取指南。

4. 根据已确认的意图摘要填写每个章节。 不要留下占位文本。每个章节都应包含实际内容，或将其删除（仅限可选章节）。

5. 编写实施计划。 这是面向 Agent 的 ADR 中最重要的章节。它要准确告知下一个 Agent 需要做什么。请参阅模板了解结构。

6. 将验证标准写成复选框。 标准必须足够具体，以便 Agent 能够通过程序或手动逐项检查。

7. 生成文件。

   • 首选：运行 scripts/new_adr.js（会处理目录、命名和可选的索引更新）。
   • 如果无法运行脚本，则从 assets/templates/ 复制模板并手动填写。

第 3 阶段：根据检查清单审查

起草完成后，根据 references/review-checklist.md 中面向 Agent 的就绪度检查清单审查 ADR。

以摘要形式呈现审查结果，不要直接照搬检查清单。格式如下：

ADR 审查

✅ 通过项：{列出完善之处，例如：“上下文完整自洽，实施计划涵盖受影响的文件，验证标准可供检查”}

⚠️ 发现的问题：

• {具体问题 1，例如：“实施计划未提及测试文件——应由哪个测试套件覆盖？”}
• {具体问题 2}

建议：{发布 / 先修复问题 / 需要继续第 1 阶段工作}

只指出未通过项和明显的优点，不要逐项复述所有通过的检查项。

如果存在问题，请提出具体的修复方案。不要只指出问题，还要提供解决方案并请人类批准。

除非 ADR 通过检查清单，或人类明确接受这些问题，否则不要定稿。

查阅 ADR（阅读工作流）

在包含 ADR 的代码库中实施更改之前，Agent 应阅读现有 ADR。这不属于创建 ADR 的工作流，而是所有 Agent 都应执行的独立操作。

何时查阅 ADR

• 开始处理涉及架构的功能之前（身份验证、数据层、API 设计、基础设施）
• 在代码中遇到某种模式，并想知道“为什么要这样做？”时
• 提议的更改可能与现有决策冲突之前
• 人类说“检查一下 ADR”或“这里有一项相关决策”时
• 在代码注释中发现 ADR-NNNN 引用时

如何查阅 ADR

1. 查找 ADR 目录。 检查 docs/decisions/、adr/、docs/adr/、decisions/。也要检查是否有索引文件（README.md 或 index.md）。

2. 浏览标题和状态。 阅读索引或查看文件名列表。重点关注 accepted 状态的 ADR——这些是当前有效的决策。

3. 完整阅读相关 ADR。 不要只看标题，还要阅读背景、决策、后果、非目标以及实施计划。实施计划会告诉你应该遵循哪些模式，以及该决策适用于哪些文件。

4. 遵循决策。 如果某个已接受的 ADR 写明“使用 PostgreSQL”，就不要提议改用 MongoDB，除非创建一份取代它的新 ADR。如果发现代码实现与 ADR 内容冲突，请向人工人员指出。

5. 遵循实施计划。 在 ADR 涉及的领域实现代码时，遵循其实施计划中指定的模式。如果计划写明“所有新查询都通过 src/db/ 中的数据访问层”，就照此执行。

6. 在工作中引用 ADR。 在代码注释和 PR 描述中添加 ADR-NNNN 引用（见下文“代码 ↔ ADR 链接”）。

代码 ↔ ADR 链接

ADR 应与其约束的代码双向链接。

ADR → 代码（在实施计划中）

实施计划部分会列出具体文件、目录和模式：

## Implementation Plan
- **Affected paths**: `src/db/`, `src/config/database.ts`, `tests/integration/`
- **Pattern**: all database queries go through `src/db/client.ts`

代码 → ADR（在注释中）

根据 ADR 实现代码时，添加引用该 ADR 的注释：

// ADR-0004: Using better-sqlite3 for test database
// See: docs/decisions/0004-use-sqlite-for-test-database.md
import Database from 'better-sqlite3';

注释应简洁——只在入口点添加一条，不必每行都加。目的是方便查找：未来的 Agent 阅读这段代码时，可以找到背后的原因。

为什么这很重要

• 在 src/db/ 中工作的 Agent 可以找到约束该领域的 ADR
• 阅读 ADR 的 Agent 可以找到实现该决策的代码
• ADR 被取代时，代码中的引用有助于轻松找到所有需要更新的地方

其他操作

更新现有 ADR

1. 明确意图：

   • 接受 / 拒绝：更改状态，补充最终背景信息。
   • 弃用：将状态改为 deprecated，说明替代方案。
   • 取代：创建一份新的 ADR，并双向链接（旧 ADR → 新 ADR，新 ADR → 旧 ADR）。
   • 补充经验：在 ## More Information 后追加内容，并标注日期。不要改写历史。

2. 使用 scripts/set_adr_status.js 更改状态（支持 YAML front matter、项目符号状态和章节状态）。

接受后的生命周期

ADR 被接受后：

1. 创建实施任务。 实施计划中的每项内容以及后果部分中的每项后续工作，都应转化为可跟踪的任务（issue、ticket 或 TODO）。
2. 在 PR 中引用 ADR。 在 PR 描述中链接到 ADR：“实现 ADR-0004。”
3. 添加代码引用。 在关键实现位置添加 ADR-NNNN 注释。
4. 检查验证标准。 实施完成后，逐项检查验证复选框，并在 ## More Information 中更新 ADR，记录结果。
5. 满足触发条件时重新审视。 如果 ADR 指定了重新审视的条件（“如果发生 X，则重新考虑”），请留意这些条件是否出现。

索引

如果仓库有 ADR 索引 / 日志文件（通常是 ADR 目录中的 README.md 或 index.md），请保持更新。

首选方式：使用 scripts/new_adr.js --update-index 完成。否则：

• 为新 ADR 添加项目符号条目。
• 保持排序一致（有编号时按数字排序；slug 则按日期或字母排序）。

初始化

向尚无 ADR 的仓库引入 ADR 时：

node /path/to/adr-skill/scripts/bootstrap_adr.js

此操作会创建目录、索引文件以及一份填写完整的首个 ADR（“采用架构决策记录”），其中会说明团队为何使用 ADR。使用 --json 可生成机器可读的输出。使用 --dir 可指定其他目录名。

分类（大型项目）

对于 ADR 数量较多的仓库，可按子目录组织：

docs/decisions/
  backend/
    0001-use-postgres.md
  frontend/
    0001-use-react.md
  infrastructure/
    0001-use-terraform.md

编号在各分类内独立。尽早选择分类方案（按层级、领域或团队），并在索引中说明。

资源

scripts/

• scripts/new_adr.js — 根据仓库约定，从模板创建新的 ADR 文件。
• scripts/set_adr_status.js — 就地更新 ADR 状态（YAML 前置元数据或行内状态）。使用 --json 输出机器可读内容。
• scripts/bootstrap_adr.js — 创建 ADR 目录、README.md 和初始的“采用 ADR”决策。

references/

• references/review-checklist.md — 用于第 3 阶段评审的 Agent 就绪情况检查清单。
• references/adr-conventions.md — 目录、文件名、状态和生命周期约定。
• references/template-variants.md — 何时使用简单模板，何时使用 MADR 风格模板。
• references/examples.md — 包含实施计划的简短和详细 ADR 示例。

assets/

• assets/templates/adr-simple.md — 用于简单决策的精简模板。
• assets/templates/adr-madr.md — MADR 4.0 模板，适用于存在多个选项且需要结构化权衡的决策。
• assets/templates/adr-readme.md — scripts/bootstrap_adr.js 使用的默认 ADR 索引脚手架。

脚本用法

在目标仓库根目录中：

# Simple ADR
node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --status proposed

# MADR-style with options
node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --template madr --status proposed

# With index update
node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --status proposed --update-index

# Bootstrap a new repo
node /path/to/adr-skill/scripts/bootstrap_adr.js --dir docs/decisions

注意：

• 脚本会自动检测 ADR 目录和文件名策略。
• 使用 --dir 和 --strategy 可覆盖默认设置。
• 使用 --json 可输出机器可读内容。