Decepticon 架构决策记录(ADR)体系:把"为什么代码长这样"沉淀为可检索、可追溯的工程资产

原创2026-10-12 10:10:461,835 阅读

Decepticon 架构决策记录(ADR)体系:把"为什么代码长这样"沉淀为可检索、可追溯的工程资产

导读

本文剖析 Decepticon 开源仓库中"架构决策记录(Architecture Decision Records, ADR)"机制的来龙去脉:从 ADR-0001 这一元决策("用 ADR 记录决策"这一决策本身)出发,说明 Decepticon 为何在 AI 辅助贡献加速、单人维护带宽吃紧的背景下放弃"就地改写叙事文档"的做法,转而采用 Michael Nygard 提出的 ADR 格式,在 docs/adr/ 下建立一份顺序编号、append-only、带日期、可被引用的决策史。读完本文,你将掌握 ADR 的六要素写作格式、何时该写与不该写的判定标准、编号与生命周期的管理约定,并能对照 template.md 与仓库中 0002~0018 的真实实例,独立为 Decepticon 或其他项目开启一篇可评审、可追溯的 ADR。


背景:为什么 Decepticon 需要把"决策的理由"写下来

ADR-0001 的 Context 部分交代了问题的根源:Decepticon 的架构已经历多次方向性转向——从 Purple Team AI 演进到 RL、GAN,再到当前的 LLM agents;单体 agent 转向规划中的多 agent 分解;沙箱从 Docker-socket-exec 改为 HTTP-daemon 形态。每一次转向都是深思熟虑的结果,但转向背后的 reasoning 只存在于 PR 描述、issue 讨论串,以及做出决策者的隐性记忆中。

仓库中其实已有几份文档在部分承担"决策记录"职责,例如 docs/security/sandbox-isolation.md、docs/security/neo4j-hardening.md、docs/security/prompt-injection-defense.md 与 docs/COWORK.md。这些是优秀的叙事型(narrative)文档,但它们在系统变化时会被就地编辑,于是读者无法区分"当前设计是什么"与"我们是如何一路走到这里的"。对一个以进攻性 AI(offensive AI)为使命、且 AI 辅助贡献速度已超过单人维护者评审带宽的项目来说,隐性架构知识的成本被急剧放大:一个评审者(无论是人还是贡献 AI agent)需要能在稳定、带日期、append-only 的地方查询"为什么中间件顺序是 SafeCommand → Skills → Filesystem → … 而不是反过来",而不是在一份被静默改写的文档里寻找答案。

从源码可以印证这一点:Decepticon 的中间件并非随意拼接,packages/decepticon/decepticon/agents/middleware_slots.py 明确写道 "Slot order is the canonical assembly order"(slot 顺序即规范组装顺序),16 个 agent 工厂按声明顺序遍历 MiddlewareSlot,其中就包括 FilesystemMiddleware、SkillsMiddleware 等关键槽位。正因为顺序本身是"被依赖但不显而易见"的架构约束,它正是 ADR 该记录的那类决策。

决策:采用 Nygard ADR 格式,落地于 docs/adr/

ADR-0001 的 Decision 很简短,但边界清晰:

  • 采用 Michael Nygard 提出的 ADR 格式,存放于 docs/adr/ 目录下;
  • ADR 顺序编号、append-only、CODEOWNERS 门控(Accepted 状态的 ADR 必须经过 maintainer 按 docs/adr/** 的 CODEOWNERS 规则评审);
  • 任何贡献者都可以开启一个 Proposed ADR;
  • 叙事文档(docs/security/、docs/red-team/ 等)继续存在,负责"当前状态"的解释与新手上路;ADR 只记录产生当前状态的决策事件。两者互补而非竞争。

这里有一个容易误解的点值得展开:引入 ADR 不是为了取代叙事文档。docs/security/sandbox-isolation.md 这类文档的职责是"系统现在长什么样、为什么这样配置",而 ADR 的职责是"某个决策是在何时、由谁、基于什么权衡被做出的"。一份给出 4GB 内存上限、1024 pid 上限与七项 capability 的沙箱隔离文档,和一份记录"沙箱传输从 Docker-socket-exec 迁往 HTTP-daemon"这一决策事件的 ADR,服务于不同的读者与检索场景。

ADR 的六要素格式:以 template.md 为准

docs/adr/template.md 给出了每篇 ADR 的骨架,六个要素缺一不可:

  1. Title(标题)——短、祈使句、现在时,例如 "Record architecture decisions";
  2. Status(状态)——Proposed / Accepted / Deprecated / Superseded by ADR-NNNN;
  3. Context(背景)——当前有哪些力量在起作用?是什么让这个决策不显而易见?用两三段短文字说明,避免重复已链接文档中的背景,改用链接;
  4. Decision(决策)——我们正在做什么?用肯定句、现在时陈述,保持简短:理由放在 Context,权衡放在 Consequences;
  5. Consequences(后果)——按固定四栏展开:Easier(这个决策解锁了什么)、Harder(它约束了什么)、Given up(我们明确放弃的能力或灵活性)、Migration(如有,现有代码/配置需要怎样变更、在什么时间线内);
  6. Alternatives considered(被考虑的替代方案)——列出真正被否决的方案,每个用一句话说明否决原因。模板特别强调:"不要列出你并没有真正考虑过的选项。ADR 是记录,不是文献综述。"

这个结构在仓库中执行得相当严格。例如 ADR-0009(将 HITL 迁移到 LangGraph 原生 interrupt())在 Consequences 里逐条列出"Easier:LangGraph 时间旅行与回放可用、自定义传输层约 150 行代码被删除""Harder:web 仪表盘引入 @langchain/langgraph-sdk 运行时依赖""Given up:文件传输层的审计轨迹(requests.jsonl / decisions.jsonl)""Migration:分五个 Sprint 的原子迁移时间线",并附上五个被否决的方案(M1~M5)及各自的否决理由。

何时写、何时不写:四条正面清单与三条负面清单

docs/adr/README.md 把"何时该写 ADR"归纳为四个场景,判据是:"当'为什么代码长成这样'这个问题的答案,需要提供给一个当时不在场的未来维护者(人或者 AI)时",具体而言:

  • 两个都可行的设计之间存在权衡,且落选者并非明显更差——例如中间件组合顺序、沙箱传输机制、C2 框架选型、prompt-cache 边界放置;
  • 代码依赖但并未被测试所验证的约束——例如"哪些服务共享同一个 Docker 网络"这类不变量;
  • 对先前决策的撤销——旧 ADR 标记为 Superseded,新 ADR 解释原因;
  • 管理项目运作方式的政策——例如存在哪些 merge/release 门禁、AI 辅助贡献章程。

对应地,不要写 ADR 的场景也有三条:

  • 从代码本身就能看出的决策;
  • 不改变架构的 bug 修复;
  • 风格/格式类决策(项目的 lint 配置才是权威),以及功能范围裁剪(这类应开 issue)。

仓库中的实例完全贴合这套清单:ADR-0002(按爆炸半径对 PR 分层)是"管理运作方式的政策",ADR-0007(为知识图谱增加 Technology 节点类型)是"代码依赖的 schema 约束",而 ADR-0012 则是典型"撤销先前决策"的范例——它显式地以 Supersedes: ADR-0002 开头,记录了对 0002 所建 CODEOWNERS 门禁的撤销及撤销依据(门禁从未真正生效、在单 code-owner 规模下自我阻塞、发布环境审批才是真正的人闸)。

生命周期与命名规范

ADR-0001 确立了"顺序编号、append-only"的基调,README 进一步细化了操作约定:

  • 编号:四位数顺序编号,永不重排:0001-...、0002-...。编号在 PR 打开时分配;如果草稿 PR 搁置期间有其他 ADR 先落地,需要重编号(避免空洞);
  • 文件名:kebab-case,取自标题,例如 0007-c2-framework-selection.md(实际仓库中是 0007-ai-surface-technology-node.md);
  • append-only:要改变一个决策,就写一篇新的 ADR 去 supersede 旧的那篇;旧 ADR 只允许把 Status 翻转为 Superseded by ADR-NNNN,其余内容不动;
  • 权限:任何人都可以开启 ADR;将其落到 Status: Accepted 是 maintainer 的决定——按惯例而非分支规则。README 特意指引读者去看 ADR-0012 了解仓库为何不再按路径强制评审;
  • 索引同步:README 中维护一张"编号 / 标题 / 状态"索引表,落地新 ADR 时必须同步更新。

从 docs/adr/README.md 的索引可以看到这套体系已运转到第 18 篇(0001~0014、0018),状态如实标注:既有 Accepted(0001、0003、0004、0005、0007、0008、0012),也有 Superseded(0002),还有一批 Proposed(0006、0009、0010、0011、0013、0014、0018)——"记录"的价值正在于如实保留未决与已决的区分,而不是只留下成功的决策。

代价与权衡:Consequences 四象限

ADR-0001 的 Consequences 用四个条目精确陈述了引入 ADR 的收益与代价,这也奠定了后续所有 ADR 的写作范式:

  • Easier(更易):新贡献者(人或 AI)能在已知位置找到决策理由;与已 Accepted 的 ADR 相矛盾的 PR 很容易被标记;决策撤销是显式的(Superseded by ADR-NNNN),而不是对文档的静默修改;
  • Harder(更难):不显而易见的决策现在需要一点前置写作投入——但这是"一次性成本、永久收益";
  • Given up(放弃):通过改写叙事文档来静默改变架构的能力,这是有意为之;
  • Migration(迁移):已在 docs/security/*.md 与 docs/COWORK.md 中成文的既有决策不会回溯性重写为 ADR;从现在起,新决策(以及对既有决策的撤销)才使用 ADR 格式。可以按个案回填高价值决策,但不做批量转换。

这条"不回溯批量转换"的迁移策略值得注意:它避免了把文档体系变成一次大型搬家,而是让新旧两套格式在过渡期共存,符合单人维护者项目对"决策速度"的诉求。

被否决的替代方案:为什么不是 RFC,也不是只靠 Issue/PR

ADR-0001 的 Alternatives considered 记录了三个被考虑并否决的方案,每个都给出了具体理由:

  • 不引入 ADR、继续就地编辑叙事文档(维持现状)——丢失了对 AI 辅助贡献评审至关重要的审计轨迹;
  • RFC 式的长篇文档——对该项目的决策速度而言过于笨重;RFC 适合跨团队项目,而这是一个小团队、目前只有单一负责人(sole owner)的仓库;
  • 仅在 GitHub issue / PR 中跟踪决策——被否决的原因很具体:issue 会漂移、PR 合并后在常规浏览中不可见,而且这两个载体都没有稳定的 URL 模式,无法被 skill 或 prompt 文件稳定引用。

"可被 skill/prompt 文件引用"这一条是 Decepticon 特有的考量:作为进攻性 AI 项目,agent 的 skill 与 prompt 需要引用架构决策,而 ADR 提供了稳定、append-only、带编号的引用锚点。

仓库中的落地实例:从 0002 到 0018

ADR 机制不是纸面制度,以下实例展示了它在仓库中如何被真实使用(状态以 docs/adr/README.md 索引为准):

  • 0002 PR tiering by blast radius(已被 0012 撤销):按"最坏情况下该文件变更可能造成的损害范围"把贡献分为 Tier-auto / Tier-delegate / Tier-owner 三档,并给出了路径进入 Tier-owner 的两个必要条件(① 可未经用户操作危及下游用户;② 无法被自动化检查完全验证);
  • 0003 AI-assisted contribution self-review charter:应对 AI 贡献的"数量激增、表面自信但根基浅、顺手改动、身份模糊"四类失效模式,确立顶层 CONTRIBUTING_AGENT.md 宪章,并明确拒绝在 PR 模板中加"是否使用 AI"复选框——因为假阴性免费且不可检测;
  • 0004 Zero AI-slop policy:把 100% 质量线显式化——硬性 diff 规模上限(≤ 400 行运行时代码、≤ 10 个文件、每 PR 单一逻辑关注点)、禁用模式清单、AI-slop 特征清单与强制正向模式,并同样适用于人工编写的贡献;
  • 0005 BloodHound via BHCE REST client:放弃在仓库内用 Python/Cypher 重写 BloodHound CE 的 PostProcessedRelationships 逻辑,改用官方 BHCE REST API(HMAC 签名、±1 小时时钟偏移窗口、三段式文件上传),并给出了详尽的源码级事实清单(如 signature.go 的 HMAC 链);
  • 0006 Agent-driven container lifecycle via ops-control:引入持有 Docker socket 的主机侧 ops-control 守护进程,通过 Unix domain socket 暴露最小 HTTP API,让"recon 识别 AD → 编排者决定 spawn ad_operator → 同一决策拉起 BHCE"这一 agentic 生命周期模型成立;
  • 0007 Technology KG node kind:为知识图谱新增 Technology 节点类型以承载 AI 面/技术探测信号,强调节点类型属于 packages/decepticon-core 的公开类型面,故以 ADR 而非顺手改动落地;
  • 0009 HITL LangGraph-native migration:将 packages/decepticon/decepticon/middleware/hitl.py 的 HITLApprovalMiddleware 从正则 tool_pattern + 文件传输迁移到 interrupt() + Command(resume=...) + 显式 frozenset[str] 策略集,明确废除"隐式正则匹配导致新增工具被静默纳入/排除门禁"的脆弱原语;
  • 0012 Retire the CODEOWNERS merge gate:基于对 GitHub 实时 API 的观测数据(150 个已合并 PR 无一上报 REVIEW_REQUIRED),撤销 0002 的 CODEOWNERS 门禁,把两道硬门禁改为仓库配置层面强制:CI OK (required status) 与 pypi-release 环境审批;
  • 0018 Safe uninstall workspace preservation:为 launcher 的卸载流程记录"先收集保留意愿并校验备份目标,再停止服务、做文件系统备份、最后清理卷"的安全顺序,并暴露 decepticon remove --yes --preserve-workspace 参数。

这些 ADR 还体现了相互引用的体系性:例如 0006 与 0009 都显式引用 ADR-0001 中记录的"Docker-socket-exec sandbox → HTTP-daemon sandbox"转向及其"LLM 信任边界之外"原则,作为自己论证的既有决策锚点——这正是 ADR-0001 想要的"被稳定引用"效果。

源码级印证:ADR 与实现的对位关系

ADR 的价值最终要落回代码。仓库中有多处实现与 ADR 记录形成对位:

  • 中间件顺序问题:ADR-0001 用它举例说明"需要稳定可查的决策理由"。实现在 middleware_slots.py:模块 docstring 声明 "Slot order is the canonical assembly order",16 个 agent 工厂按声明顺序遍历 MiddlewareSlot,插件通过 PluginBundle.replaced_middleware 按名替换或禁用槽位。顺序是被代码依赖的架构事实,正是 ADR 该覆盖的对象;
  • HITL 门禁:0009 逐条引用 middleware/hitl.py 中的具体行号(如 ApprovalPolicyRule 的 tool_pattern 用 re.search 求值)来说明"隐式正则匹配"为何脆弱,把文档与代码行级对应;
  • 公开类型面:0007 指出 KG 节点类型属于 decepticon_core.types.kg 公开面,受 packages/decepticon-core/tests/test_public_api_stability.py 等稳定性测试约束,因此 schema 变更必须以 ADR 决策而非顺手改动落地。

实操:如何为 Decepticon(或其他项目)开启一篇 ADR

综合 template.md 与 README 的生命周期约定,写一篇 ADR 的标准流程是:

  1. 确认该写:对照"四个该写 / 三个不该写"清单,确认这是一条架构权衡、一个未测试的约束、一次决策撤销或一项运作政策,而不是显而易见的代码事实或 bug 修复;
  2. 取编号:四位数,从 docs/adr/ 现有最大编号 +1(按 README 约定,编号在 PR 打开时分配;若草稿期间有别的 ADR 先落地则重编号);
  3. 起文件名:kebab-case 取自标题,如 00NN-short-title.md;
  4. 按六要素写作:标题(祈使句现在时)→ 元数据块(Status / Date / Deciders / Related)→ Context(两三段,链接已有背景)→ Decision(肯定句、现在时、简短)→ Consequences(Easier / Harder / Given up / Migration 四栏)→ Alternatives considered(只列真正考虑过的方案,各一句否决理由);
  5. 提交评审:任何人可开 PR 提出;Status: Accepted 需要 maintainer 评审。旧决策被撤销时,只把旧 ADR 的 Status 翻转为 Superseded by ADR-NNNN,正文不改;
  6. 同步索引:更新 docs/adr/README.md 的索引表。

结语

ADR-0001 作为 Decepticon 的"第一号架构决策",本质上是一次元决策:它不改变任何一行运行时逻辑,却为之后 17 篇决策记录(从 PR 分层、AI 贡献宪章、零 AI-slop 质量线,到 BloodHound 集成、HITL 迁移与 CODEOWNERS 门禁撤销)提供了稳定、可引用、append-only 的承载载体。对于任何以 AI 辅助贡献为主、维护者带宽有限的项目,这套"叙事文档讲当前状态、ADR 记录决策事件、两者互补"的机制,是控制架构漂移与隐性知识流失的低成本高回报实践——而 Decepticon 仓库本身就是它最完整的一份运行示例:你随时可以在 docs/adr/ 目录下按编号读到每一篇决策的完整上下文与权衡过程。

登录后查看全文
Decepticon