【系统架构设计】架构即 AI 上下文：让 AI 读懂你的系统
内容提要
本文探讨如何将架构工件（ADR、C4、OpenAPI、拓扑快照）转化为AI可读、可检索、可版本化的上下文，以避免模型因过期或矛盾文档产生幻觉。核心是建立单一真相源，确保每个事实有权威出处，并通过同PR更新、CI校验、检索降权等策略维持新鲜度。同时明确与RAG/向量引擎的分工，强调文档受门禁约束，降低单点故障风险。
延伸解读
架构文档的机器可读性要求
文章强调，架构工件要成为AI上下文，必须满足机器可读、可检索、可版本化的要求。这意味着优先选择文本化格式，如Markdown、Structurizr DSL、Mermaid，而非专有绘图工具格式。同时，每个事实应有权威出处，如接口形状对应OpenAPI文件，决策理由对应ADR。这种结构化方式使AI能准确引用，减少幻觉。
新鲜度维护的实践策略
为保持架构上下文的新鲜度，文章提出多种策略：同PR更新，即API或决策变更时同步更新文档；CI校验，通过检查文档与生成物哈希确保一致性；定时导出拓扑快照并标注时间；对过期文档降权。这些策略各有风险，需结合门禁和流程强制，避免文档成为新的单点故障。
与RAG/向量引擎的分工
文章明确区分了架构上下文与RAG/向量引擎的职责：前者负责选哪些工件、权威与新鲜度、引用纪律，后者负责检索管线、重排、引文。将架构文档丢进向量库并不等于完成架构治理，因为向量库解决相似检索，不解决谁有权声明真相。这种分工有助于避免范畴错误。
Q&A
如何将架构工件转化为AI可读的上下文？
将架构工件如ADR、C4模型、OpenAPI规范和拓扑快照转化为文本化、可检索、可版本化的格式，并纳入版本控制。例如，ADR用Markdown记录，C4用DSL或Mermaid，OpenAPI用规范文件，拓扑快照带时间戳导出。同时确保每个工件有明确的更新触发机制和权威出处。
什么是单一真相源（SSOT）？如何与多视图共存？
单一真相源指每个事实有一个权威出处，例如接口形状以OpenAPI文件为准，决策理由以ADR为准。多视图如C4和ADR可以共存，C4描述结构，ADR描述决策，冲突时通过ADR状态和PR审查解决，而不是让检索平均矛盾文本。
如何保持架构文档的新鲜度？
采用多种策略：同PR更新（API变更必须改spec，决策变更必须加/改ADR）、CI校验（检查文档与stub生成物哈希）、定时导出（拓扑每日快照）、检索降权（对过期标记文档降分）。这些策略需结合门禁强制和元数据质量维护。
架构上下文与RAG/向量引擎的分工是什么？
架构上下文负责选择哪些工件、确保权威与新鲜度、给Agent的引用纪律；RAG/向量引擎负责检索管线、重排、引文grounding；向量引擎内核负责相似检索。将架构文档丢进向量库不等于完成架构，因为向量库不解决谁有权声明真相。
文档即上下文是否制造新的单点故障（SPOF）？
存在争议。文档中心派认为没有稳定文档层Agent无法看到跨服务意图；代码中心派认为文档必过期且是单点。折中方案是：可执行契约优先于散文，散文限用于决策与边界并强制与变更同PR，检索默认带commit与路径，拓扑导出带时间戳。这样将文档SPOF弱化为受门禁约束的版本化输入。
哪些架构工件适合作为Agent上下文？哪些不适合？
适合的包括：ADR（Markdown，状态明确）、C4 Context/Container（DSL或Mermaid）、OpenAPI/事件schema、运行手册中的禁止事项、服务目录元数据、拓扑快照。不适合的包括：无日期的幻灯片PDF、聊天摘要（除非晋升为ADR）、全部代码的向量化（无过滤）、营销版架构图。
如何确保Agent检索到的架构信息是权威且可引用的？
检索命中应带回路径、版本（commit）和章节锚点，生成回答或补丁时能引用。无法引用到仓库路径的架构事实默认不可靠。同时，对过期文档进行降权或删除，确保检索结果优先权威来源。
