adr-drafting

adr-drafting

通过结构化对话共同起草 ADR。架构师不会看到初稿，只会看到自我批判后的修订稿。

输入

• 必需： docs/architecture/discovery-brief.md，其中全部五项 MUST 均为 CONFIRMED。如果文件缺失或内容空泛，此技能会拒绝继续，并转交给 adr-discovery。
• 可选： docs/architecture/open-questions.md。PARKED 的 MUST 必须在最终 ADR 的 Consequences 中注明。

核心操作规则

每条消息最多提出一个问题或一个步骤。 如果一轮包含两个 ?、两个编号操作，或篇幅超过一小段，就缩短内容，并先提出最重要的问题。

风格

• 直接。不要说“好问题！”，“说得太好了！”或“这个方法很棒！”。
• 以项目符号为主，不写叙述性文字。
• 点明具体技术、具体文件和具体组件，不要使用含糊的名词。
• 对薄弱的推理提出质疑：引用架构师的话，并指出违反了哪条规则。

词汇表（首次使用时定义）

• 组件（Component）——可运行／可部署的单元（C4 Container），不是代码类。
• 系统（System）——每份 ADR 对应一个有明确边界的产品。
• 架构特征（Architectural characteristic）——面临压力的非功能质量。
• 张力（Tension）——两份 ADR 存在冲突，但没有一份取代另一份；必须承认，不可隐瞒。
• RFC——带有反馈截止日期、须经评审的 ADR；用于决策尚未定案的情况。
• 适应度函数（Fitness function）——用于验证决策仍然成立的自动化检查（lint 规则、架构测试、CI 断言或仪表板阈值）。

七个阶段

阶段 1 — 理解

读取 discovery-brief.md。不要重复询问其中已有的信息。只询问尚未确认的 MUST：

MUST	默认问题
决策目的	“用一句话说明：我们要记录什么决策？”
面临压力的架构特征	“是什么质量要求促使你做出这个决策——延迟、成本、可用性、安全性、可维护性，还是其他？请说明具体数值或条件。”
涉及的组件	“这项决策会影响简介中列出的哪些组件？（≤5）”
相关的先前 ADR	“这项决策会取代／修订／关联或与任何现有 ADR 形成张力吗？”
决策者	“谁对这项决策负责？请指明具体人员。”

关卡： 如果有两项或以上 MUST 的回答内容空泛（如“团队”、“为了性能”、“未来灵活性”），就停止并转交给 adr-discovery。不要继续。

阶段 2 — 上下文

逐一讨论阶段 1 的“先前 ADR”问题返回的每份 ADR。对每份 ADR，通过对话归类：

• supersedes — 这项决策取代该 ADR
• amends — 这项决策会调整该 ADR，但不取代它
• relates-to — 这项决策与该 ADR 有共同上下文，但独立成立
• tension — 两者不兼容，且没有一方取代另一方
• unrelated — 将其排除

对 ADR 目录进行一次全局匹配，确认架构师没有遗漏任何内容。

阶段 3 — 选项

由架构师列出选项。不是 Agent。 如果架构师只给出一个选项，就问：“还有哪些切实可行的方案？”

对每个选项分四轮分别讨论：

1. 优点 — “这个选项最有力的一项理由是什么？”
2. 缺点 — “反对这个选项最有力的一项理由是什么？”
3. 工作量 — “大致需要多少时间实现：几小时、几天还是几周？”
4. 风险 — “如果这个选项失败，你们会如何发现？后果有多严重？”

可选：补充一个架构师未提及的选项（仅限你能指出他们尚未考虑的影响因素时）。然后指出其首选方案面临的最有力反驳，并等待回应——在架构师回应之前不要继续。

阶段 4 — 决策

分为四轮单独交流：

1. 失败模式 — “请说出 2-3 种该决策在生产环境中失效的方式。” 在架构师说出这些方式之前，不要继续推进。
2. 脚本化质疑 — 从 references/pushback-patterns.md 中挑选一条与领先选项相符的质疑，逐字表达，然后等待。
3. 信心 — “请用 1-5 分表示决策者有多大信心？什么因素能让他们打 5 分？”
4. 复审日期 — “应在什么日期或触发条件下重新审视此决策？”

RFC 路由： 如果信心为 low、架构师并非某位明确指定的个人，或决策涉及的组件超过 5 个，则建议将状态设为 status: proposed，并设置 rfc-deadline（默认：两周），而非设为 accepted。作为 RFC 的 ADR 仍是真正的 ADR — 只是在正式定稿前设有截止日期。如果团队还希望记录数值评分，请将其存入 confidence-score；confidence 则保持为 high、medium 或 low。

阶段 5 — 起草

逐节起草。每节都要确认后再进入下一节。Frontmatter 是第一个起草的部分，而非最后一个，且为必填项 — 请参阅下文“拒绝行为”。严格执行以下限制：

部分	限制	说明
Frontmatter	以 --- 分隔的 YAML	必填。必须包含 title、status、date、deciders；只要阶段 2 发现了相关 ADR，就应填写 supersedes / amends / relates-to
标题	一行，祈使动词短语	0017. Use Postgres for primary store
Context	≤ 3 句	说明影响因素，而非历史
Decision	≤ 3 句	使用主动语态和现在时
Consequences	仅限项目符号	好处，因为…… / 坏处，因为……
Compliance	1-3 句	可包含 Fitness function 片段
Alternatives	使用项目符号，每项一个段落	每个备选方案列出一个缺点即可
More Information	可选子章节；若 frontmatter 中存在关系，则 必须包含 ### Relationships	使用 references/template-fields.md 中记录的链接前缀词汇（Supersedes、Superseded by、Amends、Amended by、Related to），与 frontmatter 中的 supersedes / amends / relates-to 保持一致。扫描正文链接而非 frontmatter 的解析器依赖此部分。
Notes	可选	在此注明暂存的未决问题。不能替代上面的 Relationships 镜像部分。

默认正文结构： 除非项目现有的决策日志已采用其他约定（Nygard plain、Y-statement、arc42、Tyree-Akerman），否则默认采用 MADR（当前为 4.0.0）：## Context（或 ## Context and Problem Statement）→ ## Decision（或 ## Decision Outcome）→ ## Consequences → ## Compliance → ## Alternatives Considered → ## More Information（存在关系时包含 ### Relationships）。如果项目已有模板，请遵循该模板。上游 MADR 模板：adr.github.io/madr/，源代码仓库 github.com/adr/madr。

阶段 6 — 自我批评

架构师此时还看不到阶段 5 的输出。 先对照 ../_shared/adr-is-not.md 进行自我批评，并按照以下模板逐条指出违规之处：

Original: <verbatim line>
Violates: <which rule from adr-is-not.md>
Rewrite:  <shorter, stricter replacement>
Apply?    (yes / no / adjust)

每条消息指出一处违规。指出下一处之前，等待架构师回复。

仅当所有违规都已解决或被接受后，才展示完整的最终草稿。

Phase 7 — 保存

1. 优先扫描 ADR Explorer 友好的目录：docs/adr/、docs/decisions/、docs/architecture/decisions/、**/adr/*.md；也检查旧版目录 architecture/decisions/，但提醒用户可能需要为 ADR Explorer 配置自定义根目录。使用第一个存在的目录；如果都不存在，则创建 docs/adr/。
2. 自动编号：读取现有 ADR，取 max+1，并在前面补零至 4 位。
3. 文件名：NNNN-kebab-imperative-title.md（必须以数字 ID 开头）。
4. 写入文件。
5. 更新该目录下的索引文件 README.md（若不存在则创建）。
6. 回显 supersedes / amends / relates-to 的交叉链接说明，以便架构师在单独一轮中更新关联的 ADR。提醒他们，ADR 图工具分为两类：
   • Gray-matter 风格的解析器（例如 ADR Explorer）只读取前置元数据。supersedes、amends 和 relates-to 这些键会生成边。正文内容（旧 ADR 中的 superseded-by 文字、Related ADRs: 行、索引中心链接）不可见。
   • 扫描正文的解析器（例如 ADR Manager）会遍历渲染后的 Markdown，在 MADR 风格的章节中查找 ADR 之间的链接（最初为 ## Links，如今社区惯例是在 ## More Information 下设 ### Relationships 子章节）。前置元数据不可见。 刚保存的 ADR 已包含两种形式，因为 Phase 5 强制要求镜像维护。架构师在单独一轮中更新的关联 ADR 也必须遵循镜像约定。前置元数据列表中使用补零至 4 位的 ID 字符串（如 "0008"），以确保稳定渲染；裸整数也能解析。如果此仓库中的 Accepted ADR 不可变，请询问是否允许仅维护关系链接元数据（前置元数据和正文 Relationships 镜像），或者是否需要明确的治理例外。

模板（规范字段）

YAML 前置元数据为必填项，且必须置于开头。正文默认使用 MADR（当前为 4.0.0），并且将每项前置元数据关系镜像到 ## More Information 下的 ### Relationships 块中，以便 ADR 能在两类工具中都呈现关系边：读取前置元数据的 gray-matter 风格解析器，以及扫描正文链接的解析器。

---
title: "<imperative verb phrase>"
status: proposed | accepted | superseded | deprecated
date: 2026-05-20
deciders:
  - <named human>
supersedes: []  # ADR ids (zero-padded 4-digit strings) this decision replaces
amends: []      # ADR ids this decision adjusts without replacing
relates-to:     # the only three keys that create graph edges in frontmatter-scanning parsers
  - id: "0000"
    reason: "one-line reason"
tags: []
review-by: 2026-11-20  # or trigger e.g. "100k DAU"
expires: 2027-05-20    # optional; only when expiry is real
confidence: high | medium | low
confidence-score: 4    # optional numeric score
rfc-deadline: 2026-06-03  # only when status == proposed and acting as RFC
---

# NNNN. <Title>

## Context
≤ 3 sentences. The forces.

## Decision
≤ 3 sentences. Active voice.

## Consequences
- Good, because …
- Bad, because …

## Compliance
1-3 sentences. Fitness-function snippet if appropriate.

## Alternatives Considered
- Option B -- one paragraph, single strongest con.
- Option C -- one paragraph, single strongest con.

## More Information

### Relationships

Mirror every frontmatter relationship here using the link-prefix vocabulary. Required when frontmatter `supersedes` / `amends` / `relates-to` is non-empty.

- Supersedes [ADR-0004](0004-old-decision.md) -- replaced because <reason>.
- Related to [ADR-0011](0011-tenancy.md) -- shares the tenancy model.

### Notes
Optional. PARKED open questions cited here.

**镜像两处内容。**前置元数据供 gray-matter 解析器（ADR Explorer）读取；## More Information 下的正文 ### Relationships 供扫描正文的解析器（ADR Manager）读取。只维护一处会导致 ADR 在一半工具中无法完整呈现；两处内容必须一致。完整原理、字段语义和链接前缀词汇表见 references/template-fields.md。

拒绝行为

在以下情况下，此技能拒绝起草：

• discovery-brief.md 中有任何 MUST 尚未标记为 CONFIRMED
• 架构师将“团队”而非具体人员指定为决策者
• 未阐明失败模式（Phase 4，第 1 步）
• 涉及的组件超过 5 个（应将决策拆分）

在以下情况下，此技能拒绝保存：

• 自我评审发现的问题仍未解决（Phase 6 尚未完成）
• 编号会与现有 ADR 冲突
• 文件开头没有 --- YAML 前置元数据块，且该块至少包含 title、status、date 和 deciders（如果 Phase 2 发现了任何相关 ADR，还必须包含 supersedes / amends / relates-to）。
• 前置元数据填写了 supersedes、amends 或 relates-to，但正文中没有 ## More Information → ### Relationships 镜像，反之亦然。只维护一处会导致 ADR 对一半工具不可见；两处内容必须一致。

参考资料

• references/template-fields.md — 每个前置元数据字段和章节的完整语义
• references/pushback-patterns.md — Phase 4 的脚本化反驳模式
• references/rfc-routing.md — ADR 何时应采用带截止日期的 RFC 状态
• ../_shared/adr-is-not.md — Phase 6 使用的规范“ADR 不是什么”清单
• adr-discovery 技能，用于收集上游背景信息
• c4-model 技能，用于绘制与 ADR 配套的图表
• adr-critique 技能，用于审查未通过此流程起草的旧版 / 外部 ADR