adr-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ADR Skill

ADR 技能

Overview

概述

Create high-signal ADRs that capture the "why" behind architecture choices, and keep the ADR log tidy as the system evolves.

创建高价值的ADR，捕捉架构选择背后的“原因”，并随着系统的演进保持ADR日志的整洁。

Workflow Decision Tree

工作流决策树

Determine the request type:

Create a new ADR: Follow "New ADR" below.
Update an existing ADR (status change, add learnings, supersede): Follow "Update ADR" below.
Fix or create an ADR index/log: Follow "Index" below.
Adopt ADRs in a repo that has none: Follow "Bootstrap" below.

If the repo already has an ADR convention, follow it:

Directory:
```
adr/
```
,
```
docs/adr/
```
,
```
docs/decisions/
```
, etc.

Filenames:

choose-database.md

0001-choose-database.md

, etc.

Template: simple vs option-heavy.

If the repo has no convention yet, default to:

Directory:
```
adr/
```
Filenames: numbered, then slug (e.g.,
```
0001-choose-database.md
```
)
Template:
```
assets/templates/adr-simple.md
```

确定请求类型:

创建新ADR：遵循下方的“新ADR”流程。
更新现有ADR（状态变更、添加经验、替代）：遵循下方的“更新ADR”流程。
修复或创建ADR索引/日志：遵循下方的“索引”流程。
在无ADR的仓库中引入ADR：遵循下方的“初始化”流程。

若仓库已有ADR规范，请遵循该规范:

目录：
```
adr/
```
、
```
docs/adr/
```
、
```
docs/decisions/
```
等。

文件名：

choose-database.md

或

0001-choose-database.md

等。

模板：简洁型 vs 多选项型。

若仓库尚无规范，则默认采用:

目录：
```
adr/
```
文件名：编号+短标题（例如：
```
0001-choose-database.md
```
）
模板：
```
assets/templates/adr-simple.md
```

New ADR

新ADR

Choose the ADR directory.

If one exists, use it.
If none exists, create
```
adr/
```
(or the user's preferred directory).

Choose a filename strategy.

If existing ADRs use numeric prefixes (e.g.,
```
0001-...
```
), continue that.
Otherwise use slug-only filenames (e.g.,
```
choose-database.md
```
).

Choose a template.

Use
```
assets/templates/adr-simple.md
```
for most decisions.
Use
```
assets/templates/adr-madr.md
```
when you need to document options, pros/cons, and drivers.

Gather inputs (minimum viable ADR).

Title: short, actionable, ideally verb phrase.
Status: usually
```
proposed
```
initially.
Context: the constraint, requirement, and why this matters now.
Decision: the actual choice, not the story.
Consequences: what gets easier/harder, follow-ups, migration costs, risks.

Generate the file.

Preferred: run
```
scripts/new_adr.js
```
(it handles directory, naming strategy, and optional index updates).
If you can't run scripts, copy a template from
```
assets/templates/
```
and fill it manually.

若已有目录，则直接使用。
若无目录，则创建
```
adr/
```
（或用户偏好的目录）。

选择文件名策略。

若现有ADR使用数字前缀（例如：
```
0001-...
```
），则延续该策略。
否则仅使用短标题作为文件名（例如：
```
choose-database.md
```
）。

选择模板。

大多数决策使用
```
assets/templates/adr-simple.md
```
。
当需要记录选项、优缺点及决策动因时，使用
```
assets/templates/adr-madr.md
```
。

收集必要信息（最小可行ADR）。

标题：简短、可执行，优先使用动词短语。
状态：初始状态通常为
```
proposed
```
（提议中）。
背景：约束条件、需求，以及当前为何需要做出该决策。
决策：实际选择的内容，而非过程描述。
影响：哪些操作会变简单/复杂、后续工作、迁移成本、风险。

生成文件。

推荐方式：运行
```
scripts/new_adr.js
```
（该脚本会处理目录、命名策略及可选的索引更新）。
若无法运行脚本，则从
```
assets/templates/
```
复制模板并手动填写内容。

Script: new_adr.js

脚本：new_adr.js

From the target repo root:

bash

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

If you want MADR-style:

bash

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

Notes:

The script tries to auto-detect the ADR directory and filename strategy.
Use
```
--dir
```
and
```
--strategy
```
to override.
Use
```
--json
```
to emit machine-readable output for tooling.

从目标仓库根目录执行：

bash

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

若需要MADR风格的ADR：

bash

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

注意事项：

脚本会尝试自动检测ADR目录及文件名策略。
可使用
```
--dir
```
和
```
--strategy
```
参数自定义配置。
使用
```
--json
```
参数可输出机器可读格式的内容，供工具调用。

Update ADR

更新ADR

Identify the intent:

Accept / reject: change status, and add any final context that made the decision clear.
Deprecate: status becomes
```
deprecated
```
and explain replacement path.
Supersede: create a new ADR and link both ways (old points to new; new references old).
Add learnings: append an "After-action" note with a date stamp rather than rewriting history.

Keep it navigable:

Link to PRs/issues, tickets, docs.
Prefer small edits that explain why reality diverged from the original assumptions.

明确更新意图:

接受/拒绝：修改状态，并添加使决策明确的最终背景信息。
弃用：将状态改为
```
deprecated
```
（已弃用），并说明替代方案。
替代：创建新的ADR，并在新旧ADR之间建立双向链接（旧ADR指向新ADR，新ADR引用旧ADR）。
添加经验总结：在ADR末尾添加带日期戳的“事后总结”，而非修改历史内容。

保持可导航性:

关联PR/议题、工单及文档。
优先采用小幅度修改，说明实际情况与最初假设产生差异的原因。

Index

索引

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

adr/README.md

adr/index.md

), 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 order if numbered; alphabetical or date order if slugs).

若仓库已有ADR索引/日志文件（通常为

adr/README.md

或

adr/index.md

），请保持其内容更新。

推荐方式：使用

scripts/new_adr.js --update-index

自动更新。若无法使用该脚本：

为新ADR添加一个列表项。
保持排序一致（若使用编号则按数字排序；若使用短标题则按字母或日期排序）。

Bootstrap

初始化

When introducing ADRs to a repo that has none:

Preferred: run

scripts/bootstrap_adr.js

, which:

Creates the directory
```
adr/
```
.
Creates an index file
```
adr/README.md
```
.
Creates the first ADR (meta decision): "Adopt architecture decision records".

Example:

bash

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

If you want machine-readable output:

bash

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

当向尚无ADR的仓库引入该机制时：

推荐方式：运行

scripts/bootstrap_adr.js

，该脚本会执行以下操作：

创建目录
```
adr/
```
。
创建索引文件
```
adr/README.md
```
。
创建首个ADR（元决策）：“采用架构决策记录”。

示例：

bash

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

若需要机器可读格式的输出：

bash

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

Resources

资源

Read these when you need more detail or want to align with common ADR conventions:

当需要了解更多细节或与通用ADR规范对齐时，可参考以下内容：

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 (supports the included templates). Use
```
--json
```
for machine output.
```
scripts/bootstrap_adr.js
```
: create
```
adr/README.md
```
plus the initial "Adopt ADRs" decision.

```
scripts/new_adr.js
```
：根据仓库规范，从模板创建新的ADR文件。
```
scripts/set_adr_status.js
```
：就地更新ADR状态（支持内置模板）。使用
```
--json
```
参数可输出机器可读格式内容。
```
scripts/bootstrap_adr.js
```
：创建
```
adr/README.md
```
及初始的“采用ADR”决策文档。

references/

参考文档/

```
references/adr-conventions.md
```
: directory + filename conventions and lifecycle guidance.
```
references/template-variants.md
```
: when to use simple vs MADR-style templates.

```
references/adr-conventions.md
```
：目录及文件名规范，以及ADR生命周期指南。
```
references/template-variants.md
```
：介绍何时使用简洁型模板 vs MADR风格模板。

assets/

资源文件/

```
assets/templates/adr-simple.md
```
: a small template for most ADRs.
```
assets/templates/adr-madr.md
```
: a bigger template for decisions with real options/tradeoffs.

assets/templates/adr-readme.md

: default ADR index scaffold used by

scripts/bootstrap_adr.js

```
assets/templates/adr-simple.md
```
：适用于大多数ADR的简洁模板。
```
assets/templates/adr-madr.md
```
：适用于存在多个选项及权衡的决策的详细模板。

assets/templates/adr-readme.md

：

scripts/bootstrap_adr.js

使用的默认ADR索引模板。