adr-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ADR Skill

ADR技能

Philosophy

设计理念

ADRs created with this skill are executable specifications for coding agents. A human approves the decision; an agent implements it. The ADR must contain everything the agent needs to write correct code without asking follow-up questions.

This means:

Constraints must be explicit and measurable, not vibes
Decisions must be specific enough to act on ("use PostgreSQL 16 with pgvector" not "use a database")
Consequences must map to concrete follow-up tasks
Non-goals must be stated to prevent scope creep
The ADR must be self-contained — no tribal knowledge assumptions
The ADR must include an implementation plan — which files to touch, which patterns to follow, which tests to write, and how to verify the decision was implemented correctly
When architecture shape is important, capture visual artifacts (diagrams/review pages) and link them from the ADR

使用本技能创建的ADRs是面向编码Agent的可执行规范。由人类审批决策，再由Agent负责实现。ADR必须包含Agent编写正确代码所需的全部信息，无需后续追问。

这意味着：

约束条件必须明确且可衡量，不能模糊不清
决策必须具体到可执行的程度（例如“使用PostgreSQL 16搭配pgvector”而非“使用数据库”）
决策后果必须映射到具体的后续任务
必须明确非目标范围，防止需求蔓延
ADR必须自包含——不能假设依赖团队内部隐性知识
ADR必须包含实现计划——涉及哪些文件、遵循哪些模式、编写哪些测试，以及如何验证决策是否正确落地
当架构形态很重要时，需捕获可视化工件（图表/评审页面）并在ADR中添加链接

When to Write an ADR

何时编写ADR

Write an ADR when a decision:

Changes how the system is built or operated (new dependency, architecture pattern, infrastructure choice, API design)
Is hard to reverse once code is written against it
Affects other people or agents who will work in this codebase later
Has real alternatives that were considered and rejected

Do NOT write an ADR for:

Routine implementation choices within an established pattern
Bug fixes or typo corrections
Decisions already captured in an existing ADR (update it instead)
Style preferences already covered by linters or formatters

When in doubt: if a future agent working in this codebase would benefit from knowing why this choice was made, write the ADR.

当决策满足以下条件时，需要编写ADR：

改变系统的构建或运维方式（新增依赖、架构模式、基础设施选择、API设计）
一旦基于该决策编写代码后就难以逆转
会影响后续在该代码库工作的其他人员或Agent
存在经过评估后被否决的替代方案

以下情况无需编写ADR：

既定模式内的常规实现选择
Bug修复或拼写错误修正
已有ADR覆盖的决策（应更新现有ADR）
已被代码检查工具或格式化工具覆盖的风格偏好

拿不定主意时：如果未来在该代码库工作的Agent会受益于了解“为什么做出这个选择”，那就编写ADR。

Proactive ADR Triggers (For Agents)

主动触发ADR的场景（面向Agent）

If you are an agent coding in a repo and you encounter any of these situations, stop and propose an ADR before continuing:

You are about to introduce a new dependency that doesn't already exist in the project
You are about to create a new architectural pattern (new way of handling errors, new data access layer, new API convention) that other code will need to follow
You are about to make a choice between two or more real alternatives and the tradeoffs are non-obvious
You are about to change something that contradicts an existing accepted ADR
You realize you're writing a long code comment explaining "why" — that reasoning belongs in an ADR

How to propose: Tell the human what decision you've hit, why it matters, and ask if they want to capture it as an ADR. If yes, run the full four-phase workflow. If no, note the decision in a code comment and move on.

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

准备引入项目中尚未存在的新依赖
准备创建新的架构模式（新的错误处理方式、新的数据访问层、新的API规范），且其他代码需要遵循该模式
准备在两个或多个替代方案中做选择，且权衡取舍不明显
准备做出与现有已通过ADR相矛盾的变更
意识到自己正在编写冗长的代码注释来解释“为什么”——这些理由应该放在ADR中

提议方式：告知人类你遇到的决策点、该决策的重要性，并询问是否需要将其记录为ADR。如果同意，则执行完整的四阶段工作流；如果不同意，则在代码注释中记录该决策并继续工作。

Creating an ADR: Four-Phase Workflow

创建ADR：四阶段工作流

Every ADR goes through four phases. Do not skip phases.

每个ADR都需经历四个阶段，不得跳过任何阶段。

Phase 0: Scan the Codebase

阶段0：扫描代码库

Before asking any questions, gather context from the repo:

Find existing ADRs. Check
```
docs/decisions/
```
,
```
adr/
```
,
```
docs/adr/
```
,
```
decisions/
```
for existing records. Read them. Note:
- Existing conventions (directory, naming, template style)
- Decisions that relate to or constrain the current one
- Any ADRs this new decision might supersede
Check the tech stack. Read
```
package.json
```
,
```
go.mod
```
,
```
requirements.txt
```
,
```
Cargo.toml
```
, or equivalent. Note relevant dependencies and versions.
Find related code patterns. If the decision involves a specific area (e.g., "how we handle auth"), scan for existing implementations. Identify the specific files, directories, and patterns that will be affected by the decision.
Check for ADR references in code. Look for
```
ADR-NNNN
```
references in comments and docs (see "Code ↔ ADR Linking" below). This reveals which existing decisions govern which parts of the codebase.
Note what you found. Carry this context into Phase 1 — it will sharpen your questions and prevent the ADR from contradicting existing decisions.
Capture a visual baseline when helpful. If
```
visual-explainer
```
is available, run
```
/project-recap
```
for unfamiliar systems or
```
/generate-web-diagram
```
for current architecture. Use this as pre-decision context, not as a replacement for written reasoning.

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

查找现有ADRs：检查
```
docs/decisions/
```
、
```
adr/
```
、
```
docs/adr/
```
、
```
decisions/
```
目录下的现有记录并阅读。注意：
- 现有规范（目录、命名、模板风格）
- 与当前决策相关或对其有约束的现有决策
- 新决策可能替代的任何ADRs
检查技术栈：阅读
```
package.json
```
、
```
go.mod
```
、
```
requirements.txt
```
、
```
Cargo.toml
```
或等效文件，记录相关依赖及其版本。
查找相关代码模式：如果决策涉及特定领域（例如“我们如何处理认证”），扫描现有实现，确定会受决策影响的具体文件、目录和模式。
检查代码中的ADR引用：查找注释和文档中的
```
ADR-NNNN
```
引用（见下文“代码↔ADR关联”），这能揭示哪些现有决策管控着代码库的哪些部分。
记录发现的信息：将这些上下文带入阶段1——这会让你的提问更有针对性，避免ADR与现有决策冲突。
必要时捕获可视化基线：如果
```
visual-explainer
```
可用，对不熟悉的系统运行
```
/project-recap
```
，或对当前架构运行
```
/generate-web-diagram
```
。将其作为决策前的上下文，而非书面理由的替代。

Phase 1: Capture Intent (Socratic)

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

Interview the human to understand the decision space. Ask questions one at a time, building on previous answers. Do not dump a list of questions.

Core questions (ask in roughly this order, skip what's already clear from context or Phase 0):

What are you deciding? — Get a short, specific title. Push for a verb phrase ("Choose X", "Adopt Y", "Replace Z with W").
Why now? — What broke, what's changing, or what will break if you do nothing? This is the trigger.
What constraints exist? — Tech stack, timeline, budget, team size, existing code, compliance. Be concrete. Reference what you found in Phase 0 ("I see you're already using X — does that constrain this?").
What does success look like? — Measurable outcomes. Push past "it works" to specifics (latency, throughput, DX, maintenance burden).
What options have you considered? — At least two. For each: what's the core tradeoff? If they only have one option, help them articulate why alternatives were rejected.
What's your current lean? — Capture gut intuition early. Often reveals unstated priorities.
Who needs to know or approve? — Decision-makers, consulted experts, informed stakeholders.
What would an agent need to implement this? — Which files/directories are affected? What existing patterns should it follow? What should it avoid? What tests would prove it's working? This directly feeds the Implementation Plan.
Would visual artifacts reduce ambiguity? — If yes, decide which outputs are required (
```
/generate-web-diagram
```
,
```
/plan-review
```
,
```
/diff-review
```
) and where links should live.

Adaptive follow-ups: Based on answers, probe deeper where the decision is fuzzy. Common follow-ups:

"What's the worst-case outcome if this decision is wrong?"
"What would make you revisit this in 6 months?"
"Is there anything you're explicitly choosing NOT to do?"
"What prior art or existing patterns in the codebase does this relate to?"
"I found [existing ADR/pattern] — does this new decision interact with it?"

When to stop: You have enough when you can fill every section of the ADR — including the Implementation Plan — without making things up. If you're guessing at any section, ask another question.

Intent Summary Gate: Before moving to Phase 2, present a structured summary of what you captured and ask the human to confirm or correct it:

Here's what I'm capturing for the ADR:

Title: {title}

Trigger: {why now}

Constraints: {list}

Options: {option 1} vs {option 2} [vs ...]

Lean: {which option and why}

Non-goals: {what's explicitly out of scope}

Related ADRs/code: {what exists that this interacts with}

Affected files/areas: {where in the codebase this lands}

Verification: {how we'll know it's implemented correctly}

Visual artifacts: {which diagrams/reviews to generate, if any}

Does this capture your intent? Anything to add or correct?

Do NOT proceed to Phase 2 until the human confirms the summary.

通过与人类对话理解决策范围。一次只问一个问题，基于之前的回答逐步深入，不要一次性抛出所有问题。

核心问题（大致按此顺序提问，跳过从上下文或阶段0中已明确的内容）：

你要做什么决策？——获取简短、具体的标题。尽量使用动词短语（例如“选择X”、“采用Y”、“用W替换Z”）。
为什么现在做这个决策？——是什么出了问题、正在发生什么变化，或者如果不做任何改变会有什么后果？这是触发决策的原因。
存在哪些约束条件？——技术栈、时间线、预算、团队规模、现有代码、合规要求。要具体。可以参考阶段0的发现提问（例如“我看到你们已经在使用X——这会对本次决策造成约束吗？”）。
成功的标准是什么？——可衡量的结果。不要停留在“能运行”，要具体到细节（延迟、吞吐量、开发者体验、维护成本）。
你考虑过哪些选项？——至少两个。每个选项的核心权衡是什么？如果只有一个选项，帮助他们阐明为什么否决了其他替代方案。
你目前倾向于哪个选项？——尽早捕捉直觉判断，这通常能揭示未明确说明的优先级。
哪些人需要知晓或审批该决策？——决策者、咨询专家、需要知情的利益相关者。
Agent实现该决策需要哪些信息？——涉及哪些文件/目录？应遵循哪些现有模式？需要避免什么？编写哪些测试能证明功能正常？这些内容将直接用于实现计划。
可视化工件是否能减少歧义？——如果是，确定需要生成哪些输出（
```
/generate-web-diagram
```
、
```
/plan-review
```
、
```
/diff-review
```
）以及链接的存放位置。

适应性跟进问题：根据回答，对模糊的决策点进一步追问。常见的跟进问题：

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

停止提问的时机：当你能填充ADR的所有部分（包括实现计划）且无需猜测时，就可以停止。如果任何部分需要猜测，就继续提问。

需求意图确认环节：进入阶段2之前，将捕捉到的内容整理成结构化摘要，让人类确认或修正：

我整理的ADR需求意图如下：

标题：{标题}

触发原因：{为什么现在做}

约束条件：{列表}

可选方案：{方案1} vs {方案2} [vs ...]

倾向选项：{哪个选项及原因}

非目标范围：{明确排除的内容}

相关ADR/代码：{与之交互的现有内容}

影响文件/区域：{代码库中的受影响位置}

验证方式：{如何确认实现正确}

可视化工件：{需要生成的图表/评审内容（如有）}

这是否准确捕捉了你的需求？有没有需要补充或修正的地方？

在人类确认摘要之前，不得进入阶段2。

Phase 2: Draft the ADR

阶段2：起草ADR

Choose the ADR directory.
- If one exists (found in Phase 0), use it.
- If none exists, create
```
docs/decisions/
```
  (MADR default) or
```
adr/
```
  (simpler repos).
Choose a filename strategy.
- If existing ADRs use numeric prefixes (
```
0001-...
```
  ), continue that.
- Otherwise use slug-only filenames (
```
choose-database.md
```
  ).
Choose a template.
- Use
```
assets/templates/adr-simple.md
```
  for straightforward decisions (one clear winner, minimal tradeoffs).
- Use
```
assets/templates/adr-madr.md
```
  when you need to document multiple options with structured pros/cons/drivers.
- See
```
references/template-variants.md
```
  for guidance.
Fill every section from the confirmed intent summary. Do not leave placeholder text. Every section should contain real content or be removed (optional sections only).
Write the Implementation Plan. This is the most important section for agent-first ADRs. It tells the next agent exactly what to do. See the template for structure.
Write Verification criteria as checkboxes. These must be specific enough that an agent can programmatically or manually check each one.
Generate visual artifacts (recommended for architecture-impacting ADRs).
- Use
```
/generate-web-diagram
```
  for proposed architecture or flow.
- Use
```
/plan-review <adr-file>
```
  after drafting to validate Implementation Plan coverage.
- If superseding/changing an existing architecture, use
```
/diff-review
```
  for before/after comparison.
- Record output HTML paths and link them in
```
## Visual Artifacts
```
  (or
```
## More Information
```
  if the section is omitted).
Generate the file.
- Preferred: run
```
scripts/new_adr.js
```
  (handles directory, naming, and optional index updates).
- If you can't run scripts, copy a template from
```
assets/templates/
```
  and fill it manually.

选择ADR目录
- 如果阶段0中发现已有ADR目录，直接使用该目录。
- 如果没有，创建
```
docs/decisions/
```
  （MADR默认目录）或
```
adr/
```
  （适用于简单代码库）。
选择文件名命名策略
- 如果现有ADR使用数字前缀（如
```
0001-...
```
  ），延续该策略。
- 否则使用纯短横线命名（如
```
choose-database.md
```
  ）。
选择模板
- 对于简单决策（有明确的最优选项、权衡较少），使用
```
assets/templates/adr-simple.md
```
  。
- 当需要记录多个选项及结构化的优缺点/驱动因素时，使用
```
assets/templates/adr-madr.md
```
  。
- 可参考
```
references/template-variants.md
```
  获取指导。
根据确认后的需求意图摘要填充所有部分。不要留下占位符文本。每个部分都应包含实际内容，或删除该部分（仅针对可选部分）。
编写实现计划：这是面向Agent的ADR中最重要的部分，它会告诉后续Agent具体要做什么。可参考模板中的结构。
将验证标准写成复选框形式：这些标准必须足够具体，让Agent可以通过程序或手动方式逐一检查。
生成可视化工件（对影响架构的ADR推荐使用）
- 对于拟议的架构或流程，使用
```
/generate-web-diagram
```
  。
- 起草完成后，使用
```
/plan-review <adr-file>
```
  验证实现计划的覆盖范围。
- 如果要替代/变更现有架构，使用
```
/diff-review
```
  进行前后对比。
- 记录输出HTML的路径，并在
```
## Visual Artifacts
```
  （如果该部分被省略，则在
```
## More Information
```
  ）中添加链接。
生成文件
- 推荐方式：运行
```
scripts/new_adr.js
```
  （会处理目录、命名和可选的索引更新）。
- 如果无法运行脚本，从
```
assets/templates/
```
  复制模板并手动填充内容。

Phase 3: Review Against Checklist

阶段3：对照检查清单评审

After drafting, review the ADR against the agent-readiness checklist in

references/review-checklist.md

Present the review as a summary, not a raw checklist dump. Format:

ADR Review

✅ Passes: {list what's solid — e.g., "context is self-contained, implementation plan covers affected files, verification criteria are checkable"}

⚠️ Gaps found:

{specific gap 1 — e.g., "Implementation Plan doesn't mention test files — which test suite should cover this?"}

{specific gap 2}

Recommendation: {Ship it / Fix the gaps first / Needs more Phase 1 work}

Only surface failures and notable strengths — do not recite every passing checkbox.

If there are gaps, propose specific fixes. Do not just flag problems — offer solutions and ask the human to approve.

Do not finalize until the ADR passes the checklist or the human explicitly accepts the gaps.

For ADRs with visuals, run

/fact-check <visual-or-adr-output>

if available before final recommendation to verify claims against the codebase.

起草完成后，对照

references/review-checklist.md

中的Agent就绪性检查清单评审ADR。

将评审结果整理为摘要呈现，不要直接输出原始检查清单。格式如下：

ADR评审结果

✅ 通过项：{列出合格的内容——例如“上下文自包含、实现计划覆盖了受影响文件、验证标准可检查”}

⚠️ 发现的差距：

{具体差距1——例如“实现计划未提及测试文件——应使用哪个测试套件覆盖？”}

{具体差距2}

建议：立即发布 / 先修复差距 / 需要回到阶段1补充信息

只列出未通过项和值得注意的优势——无需逐一列举所有通过的检查项。

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

在ADR通过检查清单或人类明确接受差距之前，不要定稿。

对于包含可视化内容的ADR，在给出最终建议前，如果可用，运行

/fact-check <visual-or-adr-output>

验证内容与代码库是否一致。

Consulting ADRs (Read Workflow)

查阅ADRs（阅读工作流）

Agents should read existing ADRs before implementing changes in a codebase that has them. This is not part of the create-an-ADR workflow — it's a standalone operation any agent should do.

在代码库中实施变更之前，Agent应先查阅现有ADRs。这不属于创建ADR的工作流，而是任何Agent都应执行的独立操作。

When to Consult ADRs

何时查阅ADRs

Before starting work on a feature that touches architecture (auth, data layer, API design, infrastructure)
When you encounter a pattern in the code and wonder "why is it done this way?"
Before proposing a change that might contradict an existing decision
When a human says "check the ADRs" or "there's a decision about this"
When you find an
```
ADR-NNNN
```
reference in a code comment

开始处理涉及架构的功能（认证、数据层、API设计、基础设施）之前
遇到代码中的某种模式，想知道“为什么要这么做？”时
提议可能与现有决策相矛盾的变更之前
人类要求“查看ADRs”或“关于这个问题已有决策记录”时
在代码注释中发现
```
ADR-NNNN
```
引用时

How to Consult ADRs

如何查阅ADRs

Find the ADR directory. Check
```
docs/decisions/
```
,
```
adr/
```
,
```
docs/adr/
```
,
```
decisions/
```
. Also check for an index file (
```
README.md
```
or
```
index.md
```
).
Scan titles and statuses. Read the index or list filenames. Focus on
```
accepted
```
ADRs — these are active decisions.
Read relevant ADRs fully. Don't just read the title — read context, decision, consequences, non-goals, AND the Implementation Plan. The Implementation Plan tells you what patterns to follow and what files are governed by this decision.
Respect the decisions. If an accepted ADR says "use PostgreSQL," don't propose switching to MongoDB without creating a new ADR that supersedes it. If you find a conflict between what the code does and what the ADR says, flag it to the human.
Follow the Implementation Plan. When implementing code in an area governed by an ADR, follow the patterns specified in its Implementation Plan. If the plan says "all new queries go through the data-access layer in
```
src/db/
```
," do that.
Reference ADRs in your work. Add
```
ADR-NNNN
```
references in code comments and PR descriptions (see "Code ↔ ADR Linking" below).

找到ADR目录：检查
```
docs/decisions/
```
、
```
adr/
```
、
```
docs/adr/
```
、
```
decisions/
```
目录。同时检查是否有索引文件（
```
README.md
```
或
```
index.md
```
）。
浏览标题和状态：阅读索引或文件名列表，重点关注
```
accepted
```
状态的ADRs——这些是当前生效的决策。
完整阅读相关ADRs：不要只看标题——要阅读上下文、决策内容、后果、非目标范围以及实现计划。实现计划会告诉你应遵循哪些模式，以及哪些文件受该决策管控。
遵循现有决策：如果已通过的ADR规定“使用PostgreSQL”，不要在未创建替代ADR的情况下提议切换到MongoDB。如果发现代码与ADR内容不一致，向人类报告该问题。
遵循实现计划：在ADR管控的区域实现代码时，遵循其实现计划中指定的模式。如果计划规定“所有新查询都必须通过
```
src/db/client.ts
```
中的数据访问层”，就要严格执行。
在工作中引用ADRs：在代码注释和PR描述中添加
```
ADR-NNNN
```
引用（见下文“代码↔ADR关联”）。

Code ↔ ADR Linking

代码↔ADR关联

ADRs should be bidirectionally linked to the code they govern.

ADRs应与它们管控的代码建立双向关联。

ADR → Code (in the Implementation Plan)

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

The Implementation Plan section names specific files, directories, and patterns:

markdown

undefined

实现计划部分要明确指定具体的文件、目录和模式：

markdown

undefined

Implementation Plan

实现计划

Affected paths:

src/db/

src/config/database.ts

tests/integration/

Pattern: all database queries go through
```
src/db/client.ts
```

undefined

受影响路径：

src/db/

、

src/config/database.ts

、

tests/integration/

模式：所有数据库查询都必须通过
```
src/db/client.ts
```
执行

undefined

Code → ADR (in comments)

代码 → ADR（在注释中）

When implementing code guided by an ADR, add a comment referencing it:

typescript

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

Keep these lightweight — one comment at the entry point, not on every line. The goal is discoverability: when a future agent reads this code, they can find the reasoning.

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

typescript

// ADR-0004: 使用better-sqlite3作为测试数据库
// 参见：docs/decisions/0004-use-sqlite-for-test-database.md
import Database from 'better-sqlite3';

注释要简洁——只需在入口点添加一条注释，无需每行都加。目的是提高可发现性：当未来的Agent阅读这段代码时，能找到背后的决策理由。

Why This Matters

双向关联的重要性

An agent working in
```
src/db/
```
can find which ADRs govern that area
An agent reading an ADR can find the code that implements it
When an ADR is superseded, the code references make it easy to find everything that needs updating

在
```
src/db/
```
工作的Agent可以找到管控该区域的ADRs
阅读ADR的Agent可以找到实现该决策的代码
当ADR被替代时，代码中的引用能轻松找到所有需要更新的内容

ADR ↔ Visual Linking

ADR ↔ 可视化内容关联

Architecture-changing ADRs should also link to generated visual artifacts.

影响架构的ADRs还应与生成的可视化工件建立关联。

ADR → Visual

ADR → 可视化内容

Include a

## Visual Artifacts

section (or use

## More Information

) with stable paths to generated HTML, for example:

markdown

undefined

添加

## Visual Artifacts

部分（如果该部分被省略，可使用

## More Information

），包含生成的HTML的稳定路径，例如：

markdown

undefined

Visual Artifacts

Proposed architecture:

docs/decisions/diagrams/0007-auth-flow.html

Plan validation:

docs/decisions/diagrams/0007-plan-review.html

undefined

拟议架构：

docs/decisions/diagrams/0007-auth-flow.html

计划验证：

docs/decisions/diagrams/0007-plan-review.html

undefined

Visual → ADR

可视化内容 → ADR

Name visual files with ADR IDs/slugs where possible (for example

0007-auth-flow.html

) so future agents can map pages back to the decision quickly.

尽可能使用ADR ID/短横线命名可视化文件（例如

0007-auth-flow.html

），这样未来的Agent可以快速将页面与决策关联起来。

Other Operations

其他操作

Update an Existing ADR

更新现有ADR

Identify the intent:
- Accept / reject: change status, add any final context.
- Deprecate: status →
```
deprecated
```
  , explain replacement path.
- Supersede: create a new ADR, link both ways (old → new, new → old).
- Add learnings: append to
```
## More Information
```
  with a date stamp. Do not rewrite history.
Use
```
scripts/set_adr_status.js
```
for status changes (supports YAML front matter, bullet status, and section status).

明确更新意图：
- 接受/拒绝：修改状态，添加最终上下文。
- 弃用：状态改为
```
deprecated
```
  ，说明替代方案。
- 替代：创建新的ADR，并建立双向关联（旧ADR指向新ADR，新ADR指向旧ADR）。
- 添加经验总结：在
```
## More Information
```
  中添加日期戳后追加内容。不得重写历史。
对于状态变更，使用
```
scripts/set_adr_status.js
```
（支持YAML前置元数据、项目符号状态和章节状态）。

Post-Acceptance Lifecycle

接受后的生命周期

After an ADR is accepted:

Create implementation tasks. Each item in the Implementation Plan and each follow-up in Consequences should become a trackable task (issue, ticket, or TODO).
Reference the ADR in PRs. Link to the ADR in PR descriptions: "Implements ADR-0004."
Add code references. Add
```
ADR-NNNN
```
comments at key implementation points.
Check verification criteria. Once implementation is complete, walk through the Verification checkboxes. Update the ADR with results in
```
## More Information
```
.
Revisit when triggers fire. If the ADR specified revisit conditions ("if X happens, reconsider"), monitor for those conditions.
Refresh visual artifacts if architecture drifted. Regenerate diagrams/reviews and keep ADR links current.

ADR被接受后：

创建实现任务：实现计划中的每个条目以及后果中的每个后续任务都应转化为可跟踪的任务（Issue、工单或TODO）。
在PR中引用ADR：在PR描述中链接到ADR，例如：“实现ADR-0004”。
添加代码引用：在关键实现位置添加
```
ADR-NNNN
```
注释。
检查验证标准：实现完成后，逐一检查验证复选框。在
```
## More Information
```
中更新ADR的验证结果。
触发条件满足时重新评估：如果ADR指定了重新评估条件（“如果X发生，重新考虑”），要监控这些条件。
架构漂移时刷新可视化工件：重新生成图表/评审内容，并保持ADR中的链接最新。

Index

索引维护

If the repo has an ADR index/log file (often

README.md

index.md

in the ADR dir), keep it updated.

Preferred: let

scripts/new_adr.js --update-index

do it. Otherwise:

Add a bullet entry for the new ADR.
Keep ordering consistent (numeric if numbered; date or alpha if slugs).

如果代码库中有ADR索引/日志文件（通常是ADR目录中的

README.md

或

index.md

），要保持其更新。

推荐方式：使用

scripts/new_adr.js --update-index

自动更新。否则：

为新ADR添加项目符号条目。
保持排序一致（如果是编号则按数字排序；如果是短横线命名则按日期或字母排序）。

Bootstrap

初始化ADR

When introducing ADRs to a repo that has none:

bash

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

This creates the directory, an index file, and a filled-out first ADR ("Adopt architecture decision records") with real content explaining why the team is using ADRs. Use

--json

for machine-readable output. Use

--dir

to override the directory name.

为尚未使用ADR的代码库引入ADR时：

bash

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

该命令会创建目录、索引文件，以及一份填写完整的初始ADR（“采用架构决策记录”），其中包含解释团队为何使用ADRs的真实内容。使用

--json

参数可输出机器可读格式。使用

--dir

参数可覆盖默认目录名称。

Categories (Large Projects)

分类（大型项目）

For repos with many ADRs, organize by subdirectory:

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

Numbers are local to each category. Choose a categorization scheme early (by layer, by domain, by team) and document it in the index.

对于拥有大量ADRs的代码库，可按子目录分类：

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

编号在每个分类内独立。要尽早选择分类方案（按层级、领域、团队），并在索引中记录该方案。

Resources

资源

Visual Explainer (optional companion)

可视化解释器（可选配套工具）

If visual-explainer is installed as a skill, use it to generate rich HTML visualizations of ADR content.

Install:

bash

pi install https://github.com/nicobailon/visual-explainer

Primary commands:

/diff-review
— before/after architecture diagrams when an ADR changes system design
/plan-review <adr-file>
— cross-reference ADR implementation plan against actual codebase
/project-recap
— architecture snapshot useful when writing new ADRs for unfamiliar areas
/generate-web-diagram
— Mermaid architecture diagrams to embed or reference from ADRs
/fact-check <doc-or-html>
— verify review/plan claims against the current codebase

These produce self-contained HTML pages in

~/.agent/diagrams/

with light/dark themes and interactive Mermaid diagrams.

Recommended ADR flow:

```
Phase 0
```
:
```
/project-recap
```
(optional baseline)
```
Phase 2
```
:
```
/generate-web-diagram
```
(proposed architecture)

Phase 3

/plan-review <adr-file>

and

/fact-check <output>

Save durable artifacts under the repo (for example
```
docs/decisions/diagrams/
```
) and link from the ADR

如果已安装visual-explainer作为技能，可使用它生成ADR内容的富HTML可视化效果。

安装命令：

bash

pi install https://github.com/nicobailon/visual-explainer

主要命令：

/diff-review
：当ADR变更系统设计时，生成前后架构对比图
/plan-review <adr-file>
：将ADR实现计划与实际代码库进行交叉验证
/project-recap
：生成架构快照，适用于为不熟悉的区域编写新ADR时
/generate-web-diagram
：生成Mermaid架构图，可嵌入或从ADR中引用
/fact-check <doc-or-html>
：验证评审/计划内容与当前代码库是否一致

这些命令会在

~/.agent/diagrams/

目录下生成自包含的HTML页面，支持明暗主题和交互式Mermaid图表。

推荐的ADR工作流：

```
阶段0
```
：
```
/project-recap
```
（可选基线）
```
阶段2
```
：
```
/generate-web-diagram
```
（拟议架构）

阶段3

：

/plan-review <adr-file>

和

/fact-check <output>

将持久化工件保存到代码库中（例如
```
docs/decisions/diagrams/
```
），并从ADR中添加链接

scripts/

scripts/目录

```
scripts/new_adr.js
```
— create a new ADR file from a template, using repo conventions.
```
scripts/set_adr_status.js
```
— update an ADR status in-place (YAML front matter or inline). Use
```
--json
```
for machine output.
```
scripts/bootstrap_adr.js
```
— create ADR dir,
```
README.md
```
, and initial "Adopt ADRs" decision.

```
scripts/new_adr.js
```
：根据模板创建新的ADR文件，遵循代码库规范。
```
scripts/set_adr_status.js
```
：原地更新ADR状态（支持YAML前置元数据、项目符号状态和章节状态）。使用
```
--json
```
参数可输出机器可读格式。
```
scripts/bootstrap_adr.js
```
：创建ADR目录、
```
README.md
```
和初始的“采用ADRs”决策记录。

references/

references/目录

```
references/review-checklist.md
```
— agent-readiness checklist for Phase 3 review.
```
references/adr-conventions.md
```
— directory, filename, status, and lifecycle conventions.
```
references/template-variants.md
```
— when to use simple vs MADR-style templates.
```
references/examples.md
```
— filled-out short and long ADR examples with implementation plans.

```
references/review-checklist.md
```
：阶段3评审使用的Agent就绪性检查清单。
```
references/adr-conventions.md
```
：目录、文件名、状态和生命周期规范。
```
references/template-variants.md
```
：指导何时使用简单模板与MADR风格模板。
```
references/examples.md
```
：包含实现计划的简短和完整ADR示例。

assets/

assets/目录

```
assets/templates/adr-simple.md
```
— lean template for straightforward decisions.
```
assets/templates/adr-madr.md
```
— MADR 4.0 template for decisions with multiple options and structured tradeoffs.

assets/templates/adr-readme.md

— default ADR index scaffold used by

scripts/bootstrap_adr.js

```
assets/templates/adr-simple.md
```
：适用于简单决策的精简模板。
```
assets/templates/adr-madr.md
```
：MADR 4.0模板，适用于有多个选项和结构化权衡的决策。

assets/templates/adr-readme.md

：

scripts/bootstrap_adr.js

使用的默认ADR索引模板。

Script Usage

脚本使用方法

From the target repo root:

bash

undefined

在目标代码库根目录执行：

bash

undefined

Simple ADR

创建简单ADR

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

node /path/to/adr-skill/scripts/new_adr.js --title "选择数据库" --status proposed

MADR-style with options

创建带选项的MADR风格ADR

node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --template madr --status proposed

node /path/to/adr-skill/scripts/new_adr.js --title "选择数据库" --template madr --status proposed

With index update

创建ADR并更新索引

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

node /path/to/adr-skill/scripts/new_adr.js --title "选择数据库" --status proposed --update-index

Bootstrap a new repo

初始化新代码库的ADR

node /path/to/adr-skill/scripts/bootstrap_adr.js --dir docs/decisions


Notes:
- Scripts auto-detect ADR directory and filename strategy.
- Use `--dir` and `--strategy` to override.
- Use `--json` to emit machine-readable output.

node /path/to/adr-skill/scripts/bootstrap_adr.js --dir docs/decisions


注意事项：
- 脚本会自动检测ADR目录和文件名命名策略。
- 可使用`--dir`和`--strategy`参数覆盖默认设置。
- 使用`--json`参数可输出机器可读格式。