让AI写技术文档时，工程师在做俯卧撑

一份机器可读的系统架构文档，能让代码审查从"抓拼写错误"变成"拦截系统性安全漏洞"。这不是假设——有人已经跑通了。

被忽视的上下文层

软件工程里有个顽固的假设：结构良好的代码能自我解释。干净的函数、清晰的命名、10分的代码检查分数——还不够吗？

代码描述系统如何执行。架构文档描述系统为何存在，以及它如何与周围一切交互。没有这个上下文层，每个自动化分析工具都在黑暗中摸索。

它看到一个函数，却看不到它在服务网格中的角色。它看到一个API调用，却看不到它应该执行的安全边界。

当你把AI工具引入工程流程时，这个区别变得极其关键。没有架构上下文的大语言模型分析原始代码，就像让资深工程师在没有系统设计权限的情况下做安全审查。

实验平台：Google Cloud上的微服务迷宫

实验对象是一个真实的生产平台。运行在Google Cloud，包含几十个微服务，部署在Cloud Run（谷歌的容器化无服务器平台）上，通过REST API交互，资产持久化到Google Cloud Storage（谷歌云的对象存储服务），所有AI操作路由经过集中式的Vertex AI（谷歌的统一机器学习平台）网关。

系统丰富且连接紧密——但唯一的文档散落在各处README文件里。

目标是：为每个服务生成标准化、机器可读的架构快照，直接提交到代码仓库。

方法是：引导式自主代理执行。

工程师设定方向，建立文档标准，然后退后。AI代理——由Gemini 3 Flash和Claude Sonnet 4.6驱动，运行在Antigravity（一个代理式AI编程助手）内部——接管任务。

它自主检查每个服务，阅读源代码，追踪服务间依赖，将现有实现与文档标准交叉比对，迭代生成结构化的ARCHITECTURE.md文件。工程师在大部分过程中的主要活动是体育锻炼。

三级文档架构的诞生

输出不是随意笔记，而是有纪律的多层级文档体系：

平台根目录下的ARCHITECTURE.md（Level 0）：全局服务网格、拓扑结构、生命周期状态

每个服务目录下的ARCHITECTURE.md（Level 1）：安全策略引擎、FinOps治理、API契约

关键模块内的ARCHITECTURE.md（Level 2）：数据流、错误处理策略、合规控制

这种结构不是装饰。它让机器能够遍历——从全局拓扑钻取到具体实现细节，再返回。

AI质量门禁的质变

真正的测试在文档生成之后。这些架构文件被输入到AI驱动的质量流水线，结果改变了静态分析的本质。

传统静态分析工具检查代码语法、风格违规、明显的安全反模式。它们对架构层面的风险视而不见：一个服务绕过网关直接调用Vertex AI，破坏了统一的审计和计费策略；一个存储桶配置为公共读取，而架构要求私有；一个API端点暴露给外部，却没有对应的身份验证中间件声明。

有了架构文档作为输入，AI质量门禁获得了系统视角。它不再孤立地审查文件，而是对照ARCHITECTURE.md中声明的意图验证实现。

实际拦截的案例：某次提交中，一个微服务新增了对Cloud Storage的直接写入。代码本身无懈可击——正确的错误处理、适当的日志记录、符合Google Cloud最佳实践。但架构文档明确规定：所有存储操作必须通过核心AI网关，以确保统一的访问审计和成本归因。

AI门禁标记了这次偏离。不是代码错误，是架构违约。

从被动检查到主动治理

这个转变的核心在于文档的位置。架构文件与源代码共存于仓库，意味着它们参与版本控制、代码审查、CI/CD流程。

当架构意图变更时，ARCHITECTURE.md的修改与代码变更一起被审查。当实现偏离文档时，差异在合并请求阶段就被捕获。当新服务加入平台时，代理自动生成其架构快照，确保文档债务不会累积。

更重要的是，这为AI工具提供了可消费的上下文。大语言模型在分析代码时，可以检索相关的架构段落，理解这段代码在更大系统中的契约义务。

实验中的质量流水线使用了检索增强生成（RAG，一种让AI模型访问外部知识库的技术）：代码变更触发对架构文档的向量检索，将相关系统上下文注入分析提示词。结果是诊断精度的显著提升——从"这里有个可疑的API调用"到"这个调用违反了服务网格第3.2节规定的认证流程"。

FinOps与安全的交叉验证

架构文档的一个意外收益领域是成本治理。Google Cloud平台的FinOps（云成本优化实践）控制分散在多个服务的实现中，缺乏统一视图。

代理生成的文档强制每个服务声明其资源类型、自动扩缩容策略、以及与其他服务的成本归属关系。当AI质量门禁检测到某次提交引入了新的Cloud Run服务实例类型时，它能交叉检查架构文档中的成本层级声明，标记潜在的预算偏离。

安全边界同样受益。实验平台的核心AI网关作为所有Vertex AI调用的单一入口，承担着统一的认证、审计、速率限制职责。架构文档明确记录了这条边界。当代码审查发现某服务尝试直接实例化Vertex AI客户端时，AI门禁立即识别为架构违规——无论该代码在孤立视角下多么"正确"。

人机协作的新边界

实验中最具启示的部分是工程师角色的重新定义。不是消失，而是转移。

工程师的核心贡献发生在前期：定义文档标准（基于C4模型和Arc42的混合结构）、建立代理的自主边界（哪些操作需要人工确认）、设计质量门禁的验证规则。

执行阶段，工程师的干预降至最低。代理在遇到模糊情况时记录待办事项，而非立即中断人类。这些待办事项在批量处理时段由工程师审阅——通常是运动后或会议间隙。

这种异步模式改变了技术文档的生产节奏。传统上，架构文档是项目初期的冲刺产物，随后逐渐腐烂。实验中，文档与代码同步演化，代理持续维护其新鲜度。

可复现的方法论

实验的具体配置值得记录，供类似平台参考：

代理核心采用Gemini 3 Flash处理大规模代码库遍历（其长上下文窗口适合跨文件分析），Claude Sonnet 4.6负责文档生成（在结构化输出和格式遵循上表现稳定）。两者通过Antigravity的代理编排层协调，该层管理工具调用序列和状态持久化。

文档标准融合了C4模型的层级视角（语境图、容器图、组件图）与Arc42的章节结构（引言与目标、架构约束、系统范围与上下文、解决方案策略）。关键创新是强制每个层级包含"机器验证点"——可被静态分析工具检查的声明，如"本服务所有出站流量必须经过core-ai-gateway"。

质量流水线集成在GitHub Actions中，触发条件包括：拉取请求创建、定时全量扫描、架构文档变更。分析引擎使用RAG检索相关架构上下文，生成针对具体变更的诊断报告。

局限与未解问题

实验也暴露了边界。代理在推断隐式依赖时偶尔出错——某服务通过共享库间接调用Cloud Storage，代理最初将其记录为直接依赖。需要人工审查来纠正这类误判。

架构文档的粒度也是持续权衡。过于详细导致维护负担和噪音；过于简略则失去机器验证价值。实验中的Level 2文档（模块级）经历了多次迭代才找到平衡点。

更根本的是，这种方法假设代码仓库是真相的单一来源。对于大量使用基础设施即代码（IaC，通过代码管理云资源）但配置分散在Terraform模块、Kustomize覆盖层、甚至云控制台手动变更的平台，代理的视图必然不完整。

行业信号的解读

这个实验发生在更广泛的工程实践转型背景中。GitHub Copilot、Cursor、Devin等工具正在将AI从代码补全扩展到任务级自主执行。但大多数关注焦点在代码生成本身，而非代码的上下文基础设施。

实验的价值在于指出：AI辅助工程的下一个瓶颈不是代码写得更快，而是代码被理解得更深。而理解需要结构化的、机器可消费的系统知识——这正是传统技术文档的角色，但传统生产模式无法跟上AI驱动的开发速度。

代理生成文档+AI消费文档的闭环，可能是解决这个瓶颈的可行路径。它不是消除人类工程师，而是将人类从重复性的信息搬运中解放，专注于更高阶的架构决策和异常处理。

立即验证的切入点

如果你管理着微服务平台，不需要等待完美方案。选择一个边界清晰的服务子集，定义最小可行的文档标准（即使只是强制包含：服务目的、依赖列表、关键安全边界），部署一个代理实验。

关键不是文档的完美，而是建立"文档作为代码"的管道——版本控制、自动验证、与质量门禁集成。一旦这个管道运转，迭代改进会自然发生。

最便宜的验证方式：在下次代码审查中，手动检查变更是否违背了任何隐含的架构假设。那些被标记的"这看起来不对"的直觉，就是应该被编码进ARCHITECTURE.md的验证点。让代理从那里开始。