从RFC到ADR：达成决策并保持推理

无人能够重建的决定

新的技术负责人提出了一个合理的问题：为什么每个服务都通过那个队列与计费系统进行通信？有一个ADR — ADR-014，四句话，写于十一个月前。背景：“我们需要可靠的计费集成。”决策：“使用队列。”后果：“增加了一些延迟。”从技术上讲，这是一个记录。它没有回答任何问题。

你在场，所以你知道ADR-014没有提到的事情：在两个Slack频道和一个激烈的PR讨论中持续了三周的争论；因为一个后来提高了的速率限制而失去的同步API选项；一位员工工程师的反对意见，得到了一个现在没人能找到的基准的回应。辩论发生了。记录是在一个星期五，由一个人根据记忆写成的。

这是一个经过文档记录的、几乎普遍存在的良好实践的失败模式。AWS的规范性指导和微软的良好架构文档都推荐使用ADR，并且都提到过这个痛点：保持它们的最新状态需要时间，随着团队和选择的增加，管理变得复杂。根本原因是结构性的问题：辩论和记录存在于不同的地方，因此记录总是一个有损的转录。解决办法是将它们放在同一个地方。这种做法也并非特定于工程，甚至也不是特定于ADR。谷歌要求提供一份设计文档——问题、建议的方法、考虑的替代方案、权衡——在重大技术工作开始之前撰写和审查，这一做法在公司的谷歌软件工程中有明确规定。这与ADR的纪律相同，只是应用在更早的一个步骤：ADR记录了设计文档所论证的选择。这两者因同样的原因以相同的方式失败，并且都可以通过相同的方式修复——在记录存在的地方进行辩论，而不是事后将一个转录到另一个中。请将下面的每一步视为涵盖这两个文档。

为什么ADR会腐烂

ADR社区自身材料中的一句话概括了整个诊断：RFC通常是关于达成一致的；ADR记录达成的一致。 两个工件，两个时刻——而它们之间的一切都在泄漏。那些“显然”错误的替代方案没有被记录（直到它们不再显而易见）。塑造最终设计的反对意见仅以关闭线程上的PR评论形式存活。上下文部分最后被写成，最糟糕的是，由那个在“谁不在”游戏中失败的人来写。应该产生决策的会议却产生了总结，而使决策持久的推理——整个决策质量链所依赖的东西——正是转录所遗漏的。

步骤 1–3：提案、背景、选项

1. 1将提案陈述为根本主张 — 提议的决定，而不是一个问题："我们将通过一个持久队列处理所有账单写入." 这句话是未来ADR的标题。检查点：根本存在，一句话，由提议者撰写。
2. 2作为单独的支持论点的背景。 促使决策必要的每个因素——可靠性要求、计费系统速率限制、审计要求——都是根下的独立论点。一个单一的“背景”段落无法被质疑；三个独立的背景主张可以各自被质疑、确认或驳倒。检查点：≥2个背景论点，每个论点都是一个因素。
3. 3每个选项都有自己的节点。 队列、同步 API、批处理作业——兄弟参数，每个都有自己的优缺点。优缺点是相对于父项而言的，因此一个选项的缺点依附于该选项，而不是决策本身。包括你预期会拒绝的选项：被拒绝的兄弟就是明年“我们为什么不直接…？”的答案。检查点：读者可能会询问的每个选项都存在。

步骤 4–6：留下记录的 RFC 轮次

现在是评审环节——通常是分散在聊天、评论和走廊中的部分。在这里，它以三种结构化交流的形式进行，每种形式都是评审与选项作者之间的四轮对话：

第7步：决定 — 以及评级不是什麼

决策者对选项进行评分：每个选项都有一个标记的评分。这个分布是真实的证据——在电话会议之前，房间内的情况是怎样的，记录在案。但评分并不是决策。仍然是一个具体的人来做决定，如果电话会议的结果与分布相悖，决策节点就是解释这一点的地方。（这个具体的人应该是谁，以及如何在辩论之前而不是之后分配这个角色，是一个独立的学科——请参见决策权教程。）

第8-9步：您不必写的ADR

这里是结果。记录不是你事后写的文件 — 它是所选选项的节点加上所有已附加的内容：上下文参数（Context）、被拒绝的兄弟选项（Options Considered）、已完成的链（讨论，及其作者）、评分（房间的立场），以及带有其理由的决策论证（Decision）。没有任何内容被转录，因此没有任何内容在转录中丢失。

1. 1记录你所接受的后果。 已知的缺点——增加的延迟、队列的操作负担——作为所选选项的附属后果，得到决策者的认可。将它们写下来使其成为一个决定，而不是一个偏好。检查点：记录上至少有1个接受的后果。
2. 2如果您的组织需要仓库跟踪的ADR，请导出。 很多组织确实需要，这是正确的——代码旁边的markdown ADR仍然是合规性文档。从树中写出四部分摘要（五分钟，不是星期五），链接回讨论以获取完整的辩论。检查点：仓库ADR引用树；树中包含推理。

不同意但承诺，记录在案

亚马逊使之闻名的模式 — 不同意见并承诺 — 存在可读性问题：后来怎么能知道分歧是真实的、被听到的并且得到了回应，而不是被强行压制的？链条机制对此给出了答案。一个完整运行四轮并在没有达成一致的情况下完成的审查链，正是这一过程的证明：异议被提出、回应、施压，并再次回应，所有记录在案，异议者在承诺之前得到了听取。异议者被记录为已被听到 — 这使得事后承诺变得合理，而不仅仅是服从。

步骤 10：替代而不删除

决策的年龄。当导致同步选项被淘汰的速率限制提高时，正确的做法是做出一个新的决策，该决策引用了它所替代的决策——一个与ADR-014的节点相关的新论点，说明了发生了什么变化。旧的决策仍然可读；它的推理正是新决策知道自己推翻了什么的原因。

一个需要明确管理的诚实差距：没有内置的ADR状态字段。提议 / 接受 / 被取代 不是论点的第一类状态——取代是通过链接建模的，维护这个约定由你们来决定。请在你们团队的工作协议中说明，而不是假设产品会强制执行。

诚实的局限性

• ✗这并不替代您仓库中的 ADR，如果您的组织要求它们与代码一起进行版本控制。导出并提交摘要；使用树形结构处理 markdown 不擅长的部分 — 辩论。
• ✗没有ADR状态字段。 提议/接受/取代是您维护的链接约定，而不是产品强制执行的内容。
• ✗一条链是四个回合。 深层的建筑分歧需要一个电话；链条是之前已经尝试过的记录。
• ✗评分是一个单一的标记值，而不是加权的多标准评分。
• ✗这并不会让任何人写出好的内容。 结构降低了良好记录的成本；它并不提供判断。

实用课程

• ✓一个RFC，一个讨论。 抵制覆盖整个季度架构的巨型树 — 超级链接比嵌套更好地连接决策。
• ✓从现有的事物中提取种子。 一个决策密集的记录或你旧的ADR文件夹，提取后使辩论有了一个良好的开端——标记为导入的，因此实时论点保持可区分。
• ✓将评审者的名字放在他们的链条上，并保持不变。 归属就是责任；匿名的建筑异议会演变成民间传说。
• ✓后果部分是决策者的，其他人无权干涉。 被接受的缺点由接受它们的人书写，其分量与评审的警告不同。

ADR-014，回答的版本

回到新技术负责人的问题。在重建版本中，ADR-014 是一个节点：队列决策及其理由，三个上下文力量（其中一个现在已经过时 — 明显可见），一个被拒绝的同步 API 兄弟，其致命的名称指向旧的速率限制，四个完成的审查链，包括员工工程师的，以及作为证据附上的基准。技术负责人阅读了十分钟，看到速率限制已更改，并打开了一个与旧节点相关的替代提案。没有人挖掘 Slack。这就是整个承诺：链条达成一致，树记录了这一点 — 而记录回答了你不知道会被问到的问题。