【系统架构设计】架构即 AI 上下文：让 AI 读懂你的系统

101 约束破坏半径，102 用流水线兜底变更。两者都假设 Agent 或模型 知道系统长什么样——服务边界、既有决策、禁止事项、当前拓扑。若这些知识只存在于某人脑中或过期 Wiki，生成物会在局部自洽的同时系统性违反架构意图。

本文讨论：如何把架构工件变成 AI 可读、可检索、可版本化的上下文，而不是会话里一段随时过期的粘贴。ADR 与 C4 的基础写法见 03 与 06；向量检索算法与 Milvus 内核见 vector-engine；RAG 工程见 llm-infra。本文不写 embedding 怎么训，只写 权威源与新鲜度。

系列导航： ← AI 时代工程基础设施 · 系统架构设计索引 · AI 原生开发流程 →

相关专题： 架构决策与 ADR · C4 与架构文档 · 复杂性管理 · lakehouse 湖上向量边界

一、问题：上下文失败比模型失败更常见

1.1 失败模式

Lewis 等人提出的 RAG（Retrieval-Augmented Generation）范式，核心是用检索到的外部知识约束生成[1]。工程上常被简化成「挂个向量库」；架构师要关心的是：检索命中的是不是当前权威，以及 权威如何更新。

1.2 本文核心问题

1. 哪些架构工件适合作为 Agent 上下文？机器可读性要求是什么？
2. 单一真相源（SSOT）如何与多视图（C4 多层、运行时拓扑）共存？
3. 与 RAG/向量引擎的分工边界在哪？
4. 「文档即上下文」是否制造新的单点故障？

二、谱系：从 ADR/C4 到可检索上下文

2.1 ADR 作为决策记忆

Michael Nygard 提出的 Architecture Decision Records 用轻量文本记录背景、决策与后果，并随代码版本管理[2]。站内展开见 03。对 AI 而言，ADR 的价值是：

• 可检索的「为什么」：避免模型重复提议已被否决的方案；
• 可绑定的范围：Accepted / Deprecated / Superseded 状态机让过期决策可标记；
• 低噪声：相对幻灯片与会议纪要，格式稳定，利于分块检索。

2.2 C4 作为结构视图

Simon Brown 的 C4 模型提供 Context / Container / Component / Code 分层视图[3]。站内见 06。对 Agent：

• Context/Container 层适合回答「系统边界与主容器」；
• Component 层适合回答「仓内模块职责」；
• Code 层通常应直接读源码，而不是维护第二份过时描述。

C4 图若只存在于绘图工具专有格式且无导出，对 Agent 几乎无用。优先 文本化（Structurizr DSL、Mermaid、纯 Markdown 列表）并进仓。

2.3 OpenAPI 与事件 schema 作为接口真相

相对散文架构文档，OpenAPI / AsyncAPI / JSON Schema 是 可执行的接口真相。它们既服务 101 的契约闸门，也服务检索：「这个 RPC 的字段是什么」应命中 spec，而不是命中某次聊天总结。

2.4 运行时拓扑

静态 C4 描述意图；运行时拓扑描述现状（服务发现、网格、副本数）。二者冲突时，事故排查以运行时为准，架构演进以决策+目标拓扑为准。自动导出（从 Kubernetes API、服务目录）可降低过期，但必须标注 观测时刻 与 信任边界（导出管道被污染则上下文被污染）。

flowchart TB
  ADR["ADR repo"] --> Idx["Versioned index"]
  C4["C4 text / DSL"] --> Idx
  Spec["OpenAPI / schemas"] --> Idx
  Topo["Topology export"] --> Idx
  Idx --> Ret["Retriever"]
  Code["Source code"] --> Ret
  Ret --> Agent["Coding / ops Agent"]

三、工件清单与机器可读要求

3.1 推荐纳入上下文索引的工件

3.2 不宜作为权威上下文的材料

• 无日期的幻灯片导出 PDF；
• 聊天摘要（除非人工晋升为 ADR）；
• 「全部代码的向量化」而无路径/模块过滤——噪声主导；
• 营销版架构图（省略失败模式与租户隔离）。

3.3 分块与引用纪律

检索命中应带回 路径 + 版本（commit）+ 章节锚点，生成回答或补丁时应能引用。无法引用到仓库路径的「架构事实」，默认视为不可靠——与本站证据等级精神一致。

四、新鲜度与单一真相源

4.1 SSOT 不是「只准有一份文档」

SSOT 指 每个事实有一个权威出处：

• 接口形状 → OpenAPI 文件；
• 决策理由 → ADR；
• 当前副本与路由 → 拓扑导出或控制面 API；
• 模块意图 → 代码 + 短 Component 说明（代码优先）。

C4 与 ADR 可以同时存在：一个描述结构，一个描述决策；冲突时用 ADR 状态与 PR 审查解决，而不是让检索「平均」两份矛盾文本。

4.2 新鲜度策略

4.3 与 RAG / 向量引擎的分工

把「架构文档丢进向量库」当成架构完成，是范畴错误：向量库解决相似检索，不解决 谁有权声明真相。

五、争论：文档即上下文是否制造新 SPOF

5.1 双方

5.2 机制层结论

双方都有工程事实支撑：文档过期是经典问题（03 开篇即讨论口头传统失败）；纯代码检索在缺少跨仓契约时也会系统性犯错。

可辩护的折中不是「都要一点」，而是：

1. 可执行契约（schema、测试、策略）优先于散文；
2. 散文限用于决策与边界（ADR、C4 上层），并强制与变更同 PR；
3. 检索默认附带 commit 与路径；无法落地文件的命中降权；
4. 拓扑导出带时间戳，不得默认为目标架构。

这样「文档 SPOF」被弱化为「受门禁约束的版本化输入」；风险转移到与代码相同的评审流程——见 102/104。

六、开放问题

1. 运行时拓扑自动导出的信任边界
   控制面被攻破或错误标注时，Agent 会「正确引用」错误拓扑。如何对导出签名/认证仍缺通行实践。

2. 多仓上下文一致性
   单仓 ADR 完善不等于平台级上下文一致。跨仓索引的权限与租户隔离（尤其面向外部 Agent）仍开放。

3. 何时允许 Agent 写回文档
   自动更新 C4/ADR 可降新鲜度成本，也可能把幻觉写进权威源。写回是否必须人审晋升，尚无标准协议。

七、落地检查清单

1. ADR 是否在仓内、有状态、可被路径引用？
2. C4 上层是否文本化进仓，而非只在专有绘图工具？
3. OpenAPI 是否与实现同 PR 更新并有 CI 校验？
4. Agent 检索结果是否带 commit/路径？
5. 拓扑快照是否标注时间，是否与意图图区分？
6. 过期/废弃文档是否有降权或删除策略？

参考资料

论文

• Lewis, P. et al., “Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks,” NeurIPS 2020.（A 级）[1]

经典与官方

• Nygard, M., “Documenting Architecture Decisions,” 2011 — ADR。（B 级，行业标准实践来源）[2]
• Brown, S., C4 model documentation, c4model.com。（B 级）[3]
• OpenAPI Specification 3.1.（A 级）

站内交叉

• 03 ADR
• 06 C4
• 102 工程基础设施
• vector-engine 索引
• llm-infra

核心文献（本主题）

实验与数据

• 本篇无向量检索 benchmark；不报告未跑的召回率数字。

系列导航： ← AI 时代工程基础设施 · 系统架构设计索引 · AI 原生开发流程 →