《AI Agent 技术原理与架构·运行时、协议与系统架构》13.3 架构决策记录与参考架构

架构决策要写下来,让后来者不用考古。ADR 记录一条决策的背景、结论与后果,新决策通过 supersedes 指回旧记录,形成可追溯的决策链。实验演示缓存从进程内升级到共享、工具权限从白名单到黑名单的两次演进,说明 ADR 是治理的地基——没有记录,架构就只剩当下的代码。

以下 ADR 议题与演进均为教学假设,不构成对任何真实系统、供应商或生产环境的承诺。“决策要记录、取代要指回旧记录、当前决策要能查到"这三条不变,具体议题按真实架构演进记录。

13.2 搭好了防线,这一节讲治理的最后一环:架构决策怎么被记住。ADR(架构决策记录)把"为什么这么定"写下来,让后来者不用考古。没有记录,架构就只剩当下的代码——没人知道为什么,也就没人敢改。

ADR 记录什么

一条 ADR 记四件事:

字段内容
背景当时面对什么问题
决策最终怎么定的
后果带来什么代价与收益
状态有效 / 被取代 / 废弃

决策是最少的部分,背景与后果才是价值。 决策一句话说完,但为什么这么定、定了要付什么代价,才是后来者需要的。一个只有"用了 Redis"的 ADR 是没用的,要有"多实例后进程内缓存不一致,所以改用共享 Redis”。

supersedes:决策链

架构会演进,决策会被取代。新决策通过 supersedes 指回旧记录,形成一条决策链——从当前有效的决策一路回溯到最初。链回答"怎么一步步走到这里的"。

ADR议题状态supersedes
adr-001缓存被取代—
adr-002缓存有效adr-001
adr-003工具权限被取代—
adr-004工具权限有效adr-003

最小实验:ADR 登记、查询与回溯

实验提供 ADR 与 ADRLog:add 登记,current_for 查当前有效决策,chain 回溯完整决策链。

# file: agp_lab/adr.py | write
# tier: 3
# verify: python3 -m unittest tests.test_adr
"""架构决策记录:把"为什么这么定"写下来,让后来者不用考古。

ADR 记录一条决策的背景、结论与后果;同一议题被新决策取代时
新记录通过 supersedes 指回旧记录,形成一条可追溯的决策链。
本模块演示如何登记、查询当前有效决策并回溯整条链。
"""
from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any

ACTIVE_STATUSES = ("accepted", "proposed")


@dataclass
class ADR:
    id: str
    topic: str
    title: str
    status: str
    context: str
    decision: str
    supersedes: str | None = None


class ADRLog:
    def __init__(self) -> None:
        self.adrs: list[ADR] = []

    def add(self, adr: ADR) -> None:
        self.adrs.append(adr)

    def _find(self, adr_id: str) -> ADR | None:
        for adr in self.adrs:
            if adr.id == adr_id:
                return adr
        return None

    def current_for(self, topic: str) -> ADR | None:
        for adr in reversed(self.adrs):
            if adr.topic == topic and adr.status in ACTIVE_STATUSES:
                return adr
        return None

    def chain(self, topic: str) -> list[str]:
        current = self.current_for(topic)
        if current is None:
            return []
        ids = [current.id]
        while current.supersedes:
            current = self._find(current.supersedes)
            if current is None:
                break
            ids.append(current.id)
        return ids


def demo() -> dict[str, Any]:
    log = ADRLog()
    log.add(ADR(
        "adr-001", "cache", "进程内缓存承载状态",
        "superseded", "单机场景要快", "用进程内 LRU 缓存", None,
    ))
    log.add(ADR(
        "adr-002", "cache", "共享缓存支撑多实例",
        "accepted", "扩容到多实例后状态不一致", "改用共享 Redis", "adr-001",
    ))
    log.add(ADR(
        "adr-003", "tool_permission", "工具白名单",
        "superseded", "内部工具少", "只放行已知工具", None,
    ))
    log.add(ADR(
        "adr-004", "tool_permission", "工具黑名单 + 灰度",
        "accepted", "工具增长到上百个", "默认拒绝、黑名单放行", "adr-003",
    ))
    return {
        "current_cache": log.current_for("cache").id,
        "current_tool_permission": log.current_for("tool_permission").id,
        "chain_cache": log.chain("cache"),
        "chain_tool_permission": log.chain("tool_permission"),
        "chain_unknown": log.chain("billing"),
    }


if __name__ == "__main__":
    for key, value in demo().items():
        print(f"{key}: {value}")

运行:

cd private/labs/agp-lab
python3 -m agp_lab.adr

输出:

current_cache: adr-002
current_tool_permission: adr-004
chain_cache: ['adr-002', 'adr-001']
chain_tool_permission: ['adr-004', 'adr-003']
chain_unknown: []

五条输出对应五件事:

  1. current_cache:缓存的当前决策是 adr-002。查当前决策不靠翻历史,current_for 直接给出有效的那条。
  2. current_tool_permission:工具权限当前是 adr-004。每个议题都有当前有效决策,议题与决策一一对应。
  3. chain_cache:回溯链 ['adr-002', 'adr-001']——从共享缓存回溯到进程内缓存。演进路径一次看清:单机先进程内、多实例再共享。
  4. chain_tool_permission:['adr-004', 'adr-003']——从黑名单回溯到白名单。两条演进线各有各的链。
  5. chain_unknown:未知议题返回空。查不到就是查不到,不伪造记录。

一个值得点破的细节:chain_cache 是 ['adr-002', 'adr-001']——链的头部是当前决策,尾部是最初决策。回溯的方向是"从现在到过去":新决策在链头,旧决策在链尾,演进顺序一目了然。而 chain_unknown 返回空列表——ADR 日志的诚实性在于"没有记录就说不没有",而不是模糊带过。这与 8.3 审计的"碰没碰过比拿没拿到更重要"是同一原则:记录要如实。

决策链的价值

决策链的回报在变更时兑现。要改架构,先读链——知道现状怎么来的,知道当初为什么这么定,才知道这次改要尊重什么、推翻什么。链是变更前的考古工具:没有链,改架构要么靠猜要么推倒重来。

变更场景决策链提供的
改缓存方案为什么从进程内到共享
调工具权限为什么从白名单到黑名单
复盘历史问题当时权衡了什么

治理的落地

ADR 是治理的地基,但它要配套机制才有效。决策要有负责人(10.1 的责任链同样适用——每条 ADR 有决策者);决策要可审计(8.3 的审计记录谁在何时查了哪条 ADR);决策链要可追踪(12.1 的追踪把"这次变更基于哪条 ADR"记下来)。ADR 不是文档,是治理结构的证据——责任、审计、追踪三套机制都消费它。

与参考架构的关系

ADR 与参考架构相辅相成。参考架构是当前的静态快照——现在的系统长什么样;ADR 是演进的时间线——怎么一步步长成这样的。两者互为补充:参考架构告诉后来者"现在是这样",ADR 告诉后来者"为什么是这样"。一个完整的治理,既要快照也要时间线。

ADR 的模板

ADR 要有固定模板,记录才整齐。背景、决策、后果、状态之外,加决策人与日期——决策人是 10.1 责任链在治理层的对应,日期让决策链有时间坐标。模板统一,跨团队可读。

字段必填
议题是
背景是
决策是
后果是
状态是
决策人是

模板的统一是治理效率的基础。 每张 ADR 字段一致,查询(current_for)与回溯(chain)才有稳定输入。没有模板,ADR 各写各的,治理工具就无从下手。

ADR 与代码的对应

ADR 要指回代码。每条 ADR 的决策,代码里要能找到对应物——改缓存方案,缓存实现里注释指向 adr-002;改工具权限,权限模块引用 adr-004。ADR 与代码双向可查:从 ADR 找到实现,从实现找到 ADR。

方向手段
ADR → 代码注释 / 文档链接
代码 → ADR变更记录关联

双向对应让架构有据可查。 读代码遇到"为什么这样写",注释指向 ADR;评审 ADR 落地情况,从 ADR 找代码核对。没有对应,ADR 是孤岛,代码是孤岛,两者接不上治理就空转。

ADR 的评审节奏

ADR 要评审,不是写完就完。新 ADR 过评审(谁同意、后果认不认);旧 ADR 定期复核(决策是否还成立、要不要 supersedes)。评审节奏让决策链保持新鲜——过期的 ADR 挂着"有效"状态,等于治理里埋着过时的权威。

时机动作
新决策评审 + 登记
定期复核有效性
架构变更触发新 ADR

评审与 13.1 威胁建模共享节奏。 架构变更触发 ADR,同时触发威胁模型重评——两个治理动作绑在一起,变更一次、评审一轮,别各走各的。

架构判据

ADR 是否合格,用五条判据检查:

判据合格的样子不合格的样子
决策有记录每条决策有 ADR决策只有代码
背景后果俱全记下为什么与代价只有结论
当前可查current_for 有答案现状靠考古
取代指回旧记录supersedes 成链新决策覆盖旧的
链可回溯演进路径可查历史断链

判据第一条是"决策必须记录",判据第三条才是关键:当前决策要能直接查到,而不是翻历史。判据第五条是治理的完整闭环——决策链断在中间,演进就讲不清。

小结

  • ADR 记四件事:背景、决策、后果、状态。
  • 背景与后果才是价值,决策只是一句话。
  • supersedes 把新决策指回旧记录,形成决策链。
  • 决策链是变更前的考古工具。
  • ADR 与责任、审计、追踪配套,才是完整的治理。

阅读导航:上一节:13.2 纵深防御:分层防护 · 下一节:目录与学习路径 。

常见错误与边界

  1. 决策只有代码。 没有 ADR,后来者只能考古,不敢改。
  2. 只有结论没背景。 “用了 Redis"没有"为什么”,等于没记。
  3. 现状靠翻历史。 没有 current_for,查当前决策要靠人肉。
  4. 新决策覆盖旧的。 不 supersedes,演进路径断链。
  5. ADR 悬空。 记了不配套责任/审计/追踪,治理空转。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图