decision-records

决策记录

此技能负责注册表工具 decisions.py，该工具通过符号链接放在仓库的 scripts/decisions.py 中 （运行 decisions.py install 可设置符号链接并添加 CI 检查）。该工具会从当前工作目录向上查找仓库的 docs/ 目录，因此可以在仓库中的任意位置运行：

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 migrate-layout              # one-shot: old accepted/<type>/ -> flat
python scripts/decisions.py install [repo]              # adopt in a repo: symlink + pre-commit

目录结构

此约定管理的所有内容都位于 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/             # ACCEPTED numbered records — flat; `type` lives in front-matter
    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

阶段	目录	ID	状态
候选（WIP）	drafts/	4 个大写字母组成的助记 ID（CONF）	draft
决策	accepted/	全局计数器（0001…）	accepted
退役	archived/	（保留原计数器）	superseded / deprecated

类型不设限制——type 可以是任意小写 slug（软件类：architecture、product、security； 治理类：policy、legal、finance、people、compliance、operations）。它只存在于 front-matter 中——所有生命周期目录都是扁平的——实际使用的类型以已接受记录中的类型为准；INDEX 会按类型分组。仍使用旧版 accepted/<type>/ 布局的仓库只需运行一次 python scripts/decisions.py migrate-layout：文件名（即标识）在移动后会保留，因此最后运行的 build --relink 会自动修复所有引用；每当 check 发现嵌套记录时，也会指向此处。

没有 proposed 状态——“提议”指的是通过发起 PR 将草稿提升为决策的行为。自行创建草稿 ID（用主题的助记词）；check 会检查格式和唯一性。交叉引用时，将裸 ID 写为行内代码——`0006`（决策）或 `CONF`（草稿）；切勿手动编写路径——build --relink 会生成并自动修复所有 docs/*.md 中的链接（包括记录、草稿以及 threat-model.md 等其他文档）。

与 origin/main 中的 ID 冲突时会发出警告，但不会阻止操作。 唯一性检查只针对单个树，因此两个分支可以各自创建 0044，在合并之前都不会出错。因此，check 还会读取磁盘上已有的 origin/main，如果其中的某个 ID 对应不同文件，就会打印一行 WARN，并给出下一个可用计数器。它不会获取远程内容，也不会导致运行失败；如果该引用不存在，则完全不会输出任何内容——全新克隆或离线机器上的这种情况不算问题。

promote 会创建大于 origin/main 当前最大计数器的 ID。 创建 ID 是另一种操作：它会写入文件——重命名记录、改写其 H1，并重新生成所有指向该记录的链接——因此 promote 会读取该引用，而不是事后才报告，并会打印它跳过了哪些计数器。由此留下的空缺不算缺号：check 会将 origin/main 中已有的计数器视为已占用，而非缺失；rebase 会补齐序列。两个树中都不存在的编号仍会导致失败；如果磁盘上没有该引用，两种行为都与之前完全相同。

引用已被取代的记录时会发出警告，但不会阻止操作。 记录被取代后会退役，但过去没有任何机制重新检查引用它的文档：即使 0019 已取代 0007，依赖 0007 的规则手册仍会继续依赖它。对于存续文档中的每一处此类引用，check（以及 build）都会打印一条 WARN，指出后继记录。它不会导致运行失败，因为提及某条记录可能是有意保留的历史内容；归档记录属于冻结的历史，引用内容不受限制，而取代旧记录的新记录当然也可以提及它。

撰写

复制 drafts/_template.md——这是唯一的模板。记录创建时处于草稿状态，而 promote 是进入 accepted/ 的唯一入口：它会生成编号、切换状态并重写 H1，因此，已接受记录的模板除了提供绕过签核的途径外，别无用处。

写裁定，不写辩论：

• 引用，不要复述。 完整论证保存在链接的讨论串、备忘录或日志中；记录只保留决定、仍然有效的理由，以及 References 下的指引链接。
• 删掉无话可说的章节。 重复 Decision 的 Rationale、没有论据的备选方案表、凑数的后果列表——删掉胜过填充；模板会标明哪些章节可以删除。check 会读取相同标记：如果草稿缺少模板未标记为可删除的章节，就会检查失败，因为脚本编辑若删除整个章节，就不会留下其他痕迹。模板是你仓库自己的副本，因此可以自行调整这些标记。
• 每句话都要有存在的价值。 用平实的句子陈述事实，胜过用一段话渲染事实；一处修饰是风格，每段都修饰就是刻意为之。
• 每条记录只做一个决定。 一条记录若不断膨胀，通常意味着多个裁定挤在同一个文件里——应将它们拆开。

这里刻意不设长度规则。纯粹的裁定通常几十行就能写完；同时包含规范的记录——在某些仓库中，已接受记录就是已交付内容的规范——合理地可能长达数百行。长度只是需要权衡的迹象，不是需要严格管控的数字；上面各条要去掉的是凑数内容，无论记录长短都可能出现。

提升草稿

提升必须得到明确的人类签核。 提升是最终确认且半不可逆的操作（已接受的记录会保持稳定——若要改变方向，必须通过取代旧记录来实现，绝不能重写；允许进行由决策者批准的维护性编辑，例如改善清晰度、更新过时内容和确保记录间的一致性）。可自由撰写、编辑和验证草稿，但除非用户在当前轮次明确同意，否则绝不能运行 promote 或其后续步骤（替换命名占位符、解决讨论串、重新生成 INDEX.md）。不要根据相邻的选择（范围答复、已勾选的清单）推断用户已批准；不确定时就询问。

已接受的决定绝不能引用草稿。 promote 会强制执行这一规则：若一组记录会违反此规则，它会拒绝执行，并准确说明如何修复（共同提升、使用 --deref 或 --allow-replace），同时提供可复制粘贴的提示词。在运行任何提升或取代操作前，先阅读 references/promotion.md，了解具体机制。

提升会更改记录的 ID 和目录，而 promote 会在整个目录树中同步更新：H1、所有相对链接（drafts/ 和 accepted/ 是同级目录）、正文中的助记符，以及写明草稿文件的任何路径。它不会处理 docs/，也绝不会编辑代码——4 个字母的助记符看起来也像标识符。运行后，docs/ 以外的提及会列出供你手动处理；若标识符只是恰好同名，就保留不动。提交时，mdformat 会重新排版改写后的段落。

在仓库中采用

在目标仓库中运行此技能的 decisions.py install [repo]。（repo 默认为当前目录；install 只会在该目录中设置，不会向上搜索。）此操作具有幂等性：只补齐缺失内容，并重新生成 INDEX.md。具体操作如下：

• 创建符号链接 <repo>/scripts/decisions.py，指向此技能中的副本，并将该路径加入 gitignore（如果不存在，则创建 .gitignore）——符号链接因机器而异，因此每个克隆都应通过 install 重新创建，而不是提交它。
• 搭建 docs/decisions/：包含 accepted/、archived/、drafts/ 及其模板（仅此一个）、面向人类的 README.md 和面向 Agent 的 AGENTS.md。
• 生成 INDEX.md（这是构建产物，而非起始文件）。
• 连接根目录入口文件——如果仓库没有根目录 README.md 或 AGENTS.md（例如全新或空仓库），则会为每个文件创建一个链接到所搭建内容的占位文件，方便人和 Agent 发现它们。已有文件不会修改（见下文）。
• 在 Git 仓库中，添加一个运行 decisions.py check 的 pre-commit 钩子；在 CI 中运行同一命令。

如果仓库已有这些入口文件，install 会保持原样——请自行连接所搭建的内容，方便人和 Agent 发现它们：

• 从仓库中面向贡献者的文档链接到所搭建的 docs/decisions/README.md——可以是 CONTRIBUTING.md；只有在 README.md 面向贡献者时才使用它（跳过面向用户的 README），并引导贡献者查看 docs/decisions/INDEX.md，浏览已接受的决策。
• 在仓库根目录的 AGENTS.md/CLAUDE.md 中，链接到 docs/decisions/AGENTS.md，让 Agent 知道决策在此处具有约束力。

每个链接都配上一行说明，简要介绍其用途。