decision-records

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Decision records

决策记录

This skill owns the registry tool

decisions.py

, symlinked into the repo at

scripts/decisions.py

(run

decisions.py install

to set up the symlink + a CI check). The tool finds the repo's

docs/

by walking up from the CWD, so run it from anywhere in the repo:

python scripts/decisions.py build [--relink]            # regenerate INDEX.md (+ refresh links)
python scripts/decisions.py check                       # validate (CI-safe; exit 1 if stale)
python scripts/decisions.py promote <name…> [--deref] [--allow-replace]   # draft(s) -> accepted/
python scripts/decisions.py rename-draft-id <name> <NEW>                  # re-ID a draft
python scripts/decisions.py install [repo]              # adopt in a repo: symlink + pre-commit

本Skill提供注册表工具

decisions.py

，通过符号链接关联到仓库的

scripts/decisions.py

路径（运行

decisions.py install

即可设置符号链接并配置CI检查）。该工具会从当前工作目录向上遍历查找仓库的

docs/

目录，因此可在仓库内任意位置运行：

python scripts/decisions.py build [--relink]            # 重新生成INDEX.md（+刷新链接）
python scripts/decisions.py check                       # 验证（CI安全；若内容过时则退出码为1）
python scripts/decisions.py promote <name…> [--deref] [--allow-replace]   # 草稿→已接受状态/
python scripts/decisions.py rename-draft-id <name> <NEW>                  # 重命名草稿ID
python scripts/decisions.py install [repo]              # 在仓库中部署：符号链接+预提交钩子

Layout

目录结构

Everything the convention owns lives under

docs/decisions/

docs/
  decisions/              # the convention's namespace (the umbrella)
    INDEX.md              # GENERATED registry over accepted/ + archived/
    README.md             # human guide to the convention (scaffolded by install)
    AGENTS.md             # agent rules: decisions are binding here (scaffolded by install)
    accepted/<type>/      # ACCEPTED numbered records; <type> = any lowercase slug you define
    archived/             # RETIRED records (superseded | deprecated) — flat
    drafts/               # WIP candidates — flat, 4-UPPERCASE-letter IDs, NOT in INDEX
  threat-model.md         # other repo docs stay siblings — still cross-reference decisions

Stage	Dir	ID	Status
candidate (WIP)	`drafts/`	4 UPPERCASE letters, mnemonic ( `CONF` )	`draft`
decision	`accepted/<type>/`	global counter ( `0001` …)	`accepted`
retired	`archived/`	(keeps its counter)	`superseded` / `deprecated`

Types are open —

<type>

is any lowercase slug, and your

accepted/<type>/

subdirs are the set (software:

architecture

product

security

; governance:

policy

legal

finance

people

compliance

operations

). A new type's directory is created on promotion. The tool enforces that a decision sits in the subdir matching its

type

— not a fixed list.

There is no

proposed

status — "proposing" is the act of opening a PR that promotes a draft. Mint a draft ID yourself (a mnemonic of the topic);

check

enforces format + uniqueness. Cross-reference by writing the bare ID as inline code —

`0006`

(decision) or

`CONF`

(draft); never hand-author a path —

build --relink

generates and self-heals every link across every

docs/*.md

(records, drafts, and other docs like

threat-model.md

本规范管理的所有内容都位于

docs/decisions/

下：

docs/
  decisions/              # 本规范的命名空间（根目录）
    INDEX.md              # 自动生成的已接受/已归档记录注册表
    README.md             # 供人类阅读的规范指南（install时自动生成模板）
    AGENTS.md             # Agent规则：决策在此处具有约束力（install时自动生成模板）
    accepted/<type>/      # 已接受的编号记录；<type>为自定义小写短标识
    archived/             # 已废弃记录（被替代 | 已过时）—— 平级目录
    drafts/               # 待完成候选记录——平级目录，4位大写字母ID，不纳入INDEX
  threat-model.md         # 仓库其他文档保持同级——仍可交叉引用决策记录

阶段	目录	ID格式	状态
候选（WIP）	`drafts/`	4个大写字母，助记符（如 `CONF` ）	`draft`
已决策	`accepted/<type>/`	全局计数器（如 `0001` …）	`accepted`
已废弃	`archived/`	保留原计数器编号	`superseded` / `deprecated`

类型开放——

<type>

可为任意小写短标识，

accepted/<type>/

子目录集合即为可用类型（技术类：

architecture

、

product

、

security

；治理类：

policy

、

legal

、

finance

、

people

、

compliance

、

operations

）。推广草稿时会自动创建新类型的目录。工具会强制决策记录存放在与其

type

匹配的子目录中——无固定类型列表。

本规范无

proposed

状态——“提议”即指提交推广草稿的PR。自行生成草稿ID（主题相关的助记符）；

check

命令会强制验证格式与唯一性。交叉引用时只需将ID作为行内代码写入——

`0006`

（已决策记录）或

`CONF`

（草稿）；切勿手动编写路径——

build --relink

命令会生成并自动修复所有

docs/*.md

文件（记录、草稿及

threat-model.md

等其他文档）中的链接。

Promoting drafts

推广草稿

Promotion requires explicit human sign-off. Promoting is a finalizing, semi-irreversible act (accepted records are immutable — supersede, don't edit). Author, edit, and validate drafts freely; but never run

promote

— or its downstream steps (replacing naming placeholders, resolving threads, regenerating

INDEX.md

) — without the user's explicit go-ahead in the current turn. Don't infer approval from an adjacent choice (a scope answer, a cleared checklist); when unsure, ask.

An accepted decision may never reference a draft.

promote

enforces this: it refuses a set that would breach and prints exactly how to fix it (co-promote,

--deref

, or

--allow-replace

) with a copy-paste prompt. Before any promotion the tool refuses — or any supersession — read references/promotion.md for the mechanics.

推广需明确人工签字确认。推广是最终、半不可逆的操作（已接受记录不可修改——如需更新请采用替代方式，而非编辑）。可自由编写、编辑和验证草稿；但在当前操作中，若未获得用户明确许可，切勿执行

promote

命令或其下游步骤（替换命名占位符、解决讨论线程、重新生成

INDEX.md

）。请勿从相邻操作（如范围确认、清单勾选）推断许可；如有疑问，请询问用户。

已接受决策不得引用草稿。

promote

命令会强制执行此规则：若发现违规则拒绝执行，并精确告知修复方式（联合推广、使用

--deref

或

--allow-replace

参数）及可直接复制的提示命令。在执行任何被拒绝的推广操作或替代操作前，请阅读**references/promotion.md**了解具体机制。

Adopting this in a repo

在仓库中部署本规范

Run this skill's

decisions.py install [repo]

from the target repo. (

repo

defaults to the current dir; install sets up there — it does not search upward.) It is idempotent: it fills in only what's missing and regenerates

INDEX.md

. What it does:

Symlinks
```
<repo>/scripts/decisions.py
```
to this skill's copy, and gitignores that path (creating
```
.gitignore
```
if absent) — the symlink is machine-specific, so each clone recreates it with
```
install
```
rather than committing it.
Scaffolds
```
docs/decisions/
```
:
```
accepted/
```
,
```
archived/
```
,
```
drafts/
```
, the two record templates, a human
```
README.md
```
, and an agent-facing
```
AGENTS.md
```
.
Generates
```
INDEX.md
```
(a build artifact, not a starter).
Wires the root entry points — when the repo has no root
```
README.md
```
or
```
AGENTS.md
```
(a fresh or empty repo), creates each as a placeholder linking the scaffold so people and agents discover it. An existing file is left untouched (see below).
In a git repo, adds a
```
pre-commit
```
hook running
```
decisions.py check
```
; run that same command in CI.

If the repo already has these entry points, install leaves them alone — wire the scaffold in yourself so people and agents discover it:

Link the scaffolded
```
docs/decisions/README.md
```
from the repo's contributor-facing docs —
```
CONTRIBUTING.md
```
, or the
```
README.md
```
only if it addresses contributors (skip a user-facing README) — and point contributors at
```
docs/decisions/INDEX.md
```
to browse the accepted decisions.
In the repo's root
```
AGENTS.md
```
/
```
CLAUDE.md
```
, link
```
docs/decisions/AGENTS.md
```
so agents pick up that decisions are binding here.

Keep each link to a one-line note on what it is.

在目标仓库中运行本Skill的

decisions.py install [repo]

命令。（

repo

默认当前目录；安装操作会在目标路径完成——不会向上搜索。）该操作具有幂等性：仅补充缺失内容并重新生成

INDEX.md

。具体操作包括：

创建符号链接：将
```
<repo>/scripts/decisions.py
```
链接到本Skill的工具副本，并添加到.gitignore（若不存在则创建.gitignore）——符号链接与机器相关，因此每个克隆仓库需通过
```
install
```
重新创建，而非提交到仓库。
生成目录模板：创建
```
docs/decisions/
```
下的目录结构：
```
accepted/
```
、
```
archived/
```
、
```
drafts/
```
、两个记录模板、供人类阅读的
```
README.md
```
及面向Agent的
```
AGENTS.md
```
。
生成INDEX.md（构建产物，而非初始模板）。
配置根入口——若仓库无根目录
```
README.md
```
或
```
AGENTS.md
```
（全新或空仓库），则创建占位文件并链接到模板，以便人类和Agent发现规范。现有文件将保持不变（见下文）。
在Git仓库中添加预提交钩子，运行
```
decisions.py check
```
；在CI中也需运行该命令。

若仓库已存在这些入口文件，安装操作将保持其不变——需自行将模板链接到入口，以便人类和Agent发现规范：

在仓库面向贡献者的文档（如
```
CONTRIBUTING.md
```
，若
```
README.md
```
面向贡献者也可）中链接模板化的
```
docs/decisions/README.md
```
，并引导贡献者通过
```
docs/decisions/INDEX.md
```
浏览已接受的决策记录。
在仓库根目录的
```
AGENTS.md
```
/
```
CLAUDE.md
```
中链接
```
docs/decisions/AGENTS.md
```
，以便Agent知晓此处决策具有约束力。

每个链接只需用一行文字说明其用途即可。",