arch-adr

arch-adr 是一项关于撰写架构决策记录（ADR）的技能。其核心用途是：在做出架构决策的那一刻，用一份简短、结构化的文档把决策固定下来，使未来的维护者能够理解“为什么这样选”，而不是只能面对一个无从追溯的结果。

适用场景

当某项架构选择在缺乏理由说明时会被未来维护者质疑，就应使用本技能。资料给出的例子包括：选择数据库、选择消息系统、在六边形架构与分层架构之间取舍、选择微服务而非单体。

当决策的备选方案确实被认真考虑并否决时，记录价值最高——因为“为什么否决 X”往往是最有价值的信息。

此外，ADR 集合也可用于新成员入职：新加入者可以通过阅读 ADR 集合，理解架构是如何一步步演变成当前状态的。

不适用场景

资料明确列出三类不适用情况：

战术性的代码级决策（例如使用 data class 还是 class、文件如何组织）——过于细粒度，撰写成本超过收益。
没有真正备选方案的决策（例如在只有 Python 团队的背景下讨论 Java 与 Python 之争，并不构成一个决策）。
事后补写：为两年前做出、且已不记得理由的决策补写 ADR。资料指出 ADR 的价值在于时间戳，倒填日期价值较低。

标准结构

资料给出的是 Michael Nygard 的原始 ADR 模板，包含以下部分：

标题（Title）：简短的名称性短语，例如 “Use PostgreSQL as the primary store” 或 “Adopt hexagonal architecture for the order service”。
状态（Status）：proposed / accepted / deprecated / superseded by ADR-NNN。
背景（Context）：当前情况、各种作用力与约束是什么？为什么现在需要这个决策？
决策（Decision）：我们决定了什么。用肯定断言表述（“We will…”），而非讨论式表述（“We're thinking about…”）。
后果（Consequences）：该决策带来什么，包括好的与坏的；它迫使我们接受什么；它新产生了哪些问题。
备选方案（Alternatives considered，可选）：当时还有哪些选项，各自为何被拒绝。

文件布局与编号

资料给出的目录结构示例为：

docs/adr/ ├── 0001-use-postgresql.md ├── 0002-adopt-hexagonal-architecture.md ├── 0003-event-bus-via-rabbitmq.md ├── 0004-replace-rabbitmq-with-kafka.md (supersedes 0003) └── README.md ← index of ADRs

编号是顺序的，且从不重复使用。当一个 ADR 被取代时，新 ADR 引用旧 ADR，旧 ADR 的状态变为 superseded by ADR-NNN。旧 ADR 保留在目录树中——历史本身就是意义所在。

篇幅与工具

篇幅上，ADR 应为单页。资料指出，如果一个 ADR 有两页，它很可能是在记录两个决策，应当拆分。

工具方面，资料提到 adr-tools（shell）、adr-manager、MADR 模板、Log4brains，它们都能生成/索引 ADR。资料认为这些工具在规模较大时有用，而小团队手写 markdown 也完全可以。

活文档与决策日志的区别

资料强调：ADR 是决策日志——一旦被接受即不可变。所谓“活文档”是另一回事（例如 README、架构图）。不要更新 ADR 的决策正文，而应通过新的 ADR 来取代它。

决策启发式

资料给出的若干实践原则：

在实现决策之前写 ADR，这会迫使思路清晰。
即使决策看起来显而易见也要写 ADR——“显而易见”往往意味着“我没有认真思考它”。
备选方案保持简短但具体，例如：“We considered Kafka but rejected it because we don't have streaming use cases yet.”
编号顺序且不可变，不要重新编号，不要复用一个已删除的编号。
ADR 存放在代码仓库中，而不是 wiki 中：它们应被版本化、被评审，并随代码一起流转。

反模式

资料列出的反面做法包括：

架构 wiki 页面：会立即偏离实际，无法在团队人员更替后存活，评审者也不会去读。
事后补写、为没人记得的决策写 ADR：时间戳很重要，补写的价值有限。
隐藏备选方案部分的 ADR：大部分价值在于“为什么拒绝了 X”；没有这一部分，ADR 只是一个声明。
更新旧 ADR 的决策正文：破坏历史记录，应改用取代方式。
为战术性决策写出成百上千个 ADR：ADR 是架构层面的，不是每个文件组织选择都值得写；门槛要足够高，使这组文档保持可读。

技能介绍