让AI写架构文档：一场工程师"离线"实验

我们总以为代码写得够好，就不需要文档。但一个让工程师去做俯卧撑的实验，彻底推翻了这个假设。

当AI代理在无人看管的情况下，自动生成完整微服务架构文档时，静态分析工具突然"看懂"了系统——从抓拼写错误，升级为拦截系统性安全漏洞。

代码能跑，不等于能被理解

软件工程里有个顽固的迷思：结构良好的代码是自解释的。干净的函数、清晰的变量名、Pylint满分——这还不够吗？

不够。代码描述的是"系统如何执行"，架构文档描述的是"系统为何存在"以及"它如何与周围一切交互"。

没有这个上下文层，每个自动化分析工具都在黑暗中摸索。它看到一个函数，但不知道它在服务网格中的角色。它看到一个API调用，但不清楚它应该执行的安全边界。

当你把AI工具引入工程工作流时，这种区别变得至关重要。没有架构上下文，大语言模型（LLM）分析原始代码，就像让资深工程师在没有系统设计文档的情况下做安全审查。

实验背景：一个真实的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文件。

工程师在大部分过程中的主要活动？做俯卧撑。

三级文档体系：从全局到细节

输出不是随手笔记，而是严谨的多层级文档结构：

platform-root
┣ ARCHITECTURE.md ← 第0级：全局服务网格、拓扑、生命周期状态
┗ services
┣ core-ai-gateway
┃ ┗ ARCHITECTURE.md ← 第1级：安全策略引擎、FinOps治理
┗ ...

每个服务获得三层深度：

Level 0 - 平台全局：服务网格拓扑、生命周期状态、跨域依赖图。这是系统的"地图"。

Level 1 - 服务级：安全策略引擎、FinOps（云成本管理）治理规则、数据流边界。定义"这个服务做什么"和"它承诺什么"。

Level 2 - 实现级：代码结构、API契约、配置与文档的偏差检测。连接"承诺"与"现实"。

关键设计：文档与代码同仓。不是外部Wiki，不是Confluence页面，而是.gitignore里的永久居民。版本控制、代码审查、CI/CD（持续集成/持续部署）——文档享受与代码同等的工程纪律。

AI质量门禁的质变

文档就位后，被喂入AI驱动的质量管道。变化立竿见影。

传统静态分析工具在代码层面操作：未使用的导入、可能的空指针、类型不匹配。有用，但局部。

有了架构文档，AI质量门禁获得系统级视角。它能提出全新类别的问题：

「这个服务声称自己处理PII（个人身份信息），但它的数据流图显示敏感数据流向了标记为'public'的存储桶。」

「API网关的文档规定所有AI调用必须经过速率限制中间件，但代码显示某条路径绕过了它。」

「FinOps策略要求冷数据归档到Nearline存储，而实际配置使用的是Standard。」

这些不是代码bug，是架构漂移（architecture drift）——文档承诺与实现之间的系统性偏差。人类代码审查很难持续捕捉，传统工具完全看不见。

代理执行的关键：人在回路，但不在路径上

实验的核心方法论值得拆解。"引导式自主"不是放任不管，而是精心设计的人机分工。

工程师的职责：

定义文档标准（什么必须记录、什么格式、什么深度）
设定边界条件（哪些文件不能碰、哪些依赖需要人工确认）
建立验证机制（如何检查生成质量）

AI代理的职责：

遍历代码库，提取结构信息
追踪跨服务调用，构建依赖图
识别实现与标准的偏差
迭代生成文档，处理冲突和模糊性

这种分工利用了双方的优势：人类擅长抽象标准和价值判断，AI擅长大规模信息整合和一致性检查。

工程师"离线"期间，代理遇到模糊情况会标记待决（如"此服务的SLA（服务等级协议）承诺在代码中未找到明确对应"），而非猜测。回来后，人类做批量裁决，代理继续执行。

为什么是现在：LLM能力曲线的拐点

这个实验在两年前不可能成功。关键变量是上下文窗口和工具使用能力的跃升。

Gemini 3 Flash和Claude Sonnet 4.6能够：

一次性处理整个服务的代码库（数万token上下文）
调用外部工具验证假设（如查询Cloud Run的实际部署配置）
在长时间运行中保持任务连贯性（多轮迭代不丢失目标）

更重要的是多代理协作。实验中使用两种模型：Gemini处理大规模代码遍历，Claude处理需要精细推理的架构推断。它们通过共享的文档标准和工作记忆协调，而非简单串联。

Antigravity作为执行框架，提供了关键的沙箱和审计能力——每次文件操作、每个API调用、每轮推理都有日志。这不是黑箱自动化，是可追溯的工程过程。

从文档到资产：重新定义架构知识的形态

传统上，架构文档是消耗品。项目启动时写一份，逐渐腐烂，最后被遗忘。

这个实验指向另一种可能：架构文档作为活的基础设施。它与代码同步演进，被机器消费，驱动自动化决策。

具体形态上，实验采用结构化Markdown而非专用格式。这是刻意选择：

人类可读：工程师可以直接打开审查
机器可解析：LLM能可靠提取字段
版本控制友好：diff（差异对比）有意义，合并冲突可解决
工具链无关：不绑定特定平台

文档中的关键字段被设计为查询接口。例如，每个服务的ARCHITECTURE.md包含明确的依赖声明：

```yaml
dependencies:
- service: user-profile-store
type: data-persistence
criticality: high
sla: 99.99%
```

AI质量门禁可以解析这些声明，与实际的网络调用、错误处理代码、熔断器配置交叉验证。

未解决的张力：生成与维护的平衡

实验也暴露了硬边界。

首次生成文档相对容易——代理有完整的代码状态作为ground truth（事实基准）。但持续维护是另一回事。

当工程师修改代码时，文档如何同步？实验测试了三种模式：

纯生成模式：每次重大变更后重新生成整份文档。简单，但丢失人工编辑（如架构决策记录）。

补丁模式：代理只更新与变更相关的章节。高效，但需要精确的变更影响分析。

混合模式：机器生成基础结构，人类维护决策记录，代理检测两者偏差。实验最终采用此模式。

另一个张力：文档应该"描述现实"还是"规定理想"？实验发现代理倾向于前者（代码实际做了什么），而工程团队需要后者（系统应该做什么）。解决方法是双轨文档：ARCHITECTURE.md描述承诺，ARCHITECTURE.impl.md描述实现，代理持续报告两者差距。

行业映射：谁需要这种能力

这种架构文档即代码的模式，对特定场景价值最高：

微服务规模临界点：服务数量超过团队能口头同步的规模（通常20+），依赖图复杂度超过人类工作记忆容量。

合规驱动行业：金融、医疗、政务——需要证明系统符合设计规范，而不仅是"看起来没问题"。

高频变更环境：快速迭代导致文档迅速腐烂，传统"写文档"流程成为瓶颈。

多团队联邦架构：没有单一架构师掌握全局，需要机器可消费的接口契约。

反过来说，单体应用、小团队、变更缓慢的项目，投入产出比可能不成立。

技术栈选择的启示

实验的技术选型有明确逻辑，可供参考：

Google Cloud作为平台：托管服务（Cloud Run、Cloud Storage、Vertex AI）提供了可查询的API表面，代理能验证实际配置与文档声明。自建Kubernetes集群会更难。

多模型策略：没有单一LLM擅长所有任务。Gemini 3 Flash的长上下文适合代码遍历，Claude Sonnet 4.6的推理深度适合架构推断。成本也分层：Flash处理 bulk（批量）工作，Sonnet处理关键决策。

Antigravity作为框架：相比裸调API，它提供了任务分解、状态管理、审计日志。自主代理不是"写一个prompt（提示词）然后祈祷"，而是可工程化的系统。

质量管道的范式转移

最深远的影响可能是对"质量"本身的定义。

传统CI管道：代码提交 → 单元测试 → 集成测试 → 部署

实验中的AI质量管道：代码提交 → 架构一致性检查 → 安全边界验证 → FinOps策略审计 → 传统测试 → 部署

新前置步骤不是可选增强，是结构性变化。它们捕获的是"系统级属性"，无法通过测试单个组件验证。

例如，实验中发现的一个真实问题：某服务文档声明"所有用户数据加密存储"，但代理追踪数据流发现，日志系统接收了明文用户ID。单元测试全部通过——日志功能正常——但架构承诺被违反。

这种检测需要同时理解：文档中的声明、代码中的实现、运行时的实际配置。三者的交叉验证，只有机器可消费的架构文档才能支撑。

成本与收益的诚实计算

实验没有回避成本问题。

初始投入：工程师约8小时设定标准、边界和验证机制；代理运行约4小时（含人工裁决暂停）；生成约15000行结构化文档。

持续成本：每次代码变更的架构影响分析约5-15分钟代理时间；每周全量一致性检查约1小时。

收益：架构漂移检测从"季度人工审计"变为"每次提交自动检查"；某类安全漏洞（如数据流边界违反）的检测前置到开发阶段，而非生产事故后。

关键洞察：收益不是"省了写文档的时间"（工程师仍需审阅和裁决），而是"文档成为可计算资产"后的衍生价值。没有这一步，AI工具在系统工程中永远停留在"智能代码补全"层面。

下一步：从快照到活体

实验的局限也很清楚。当前实现是"快照生成"：代理在特定时间点扫描代码库，产出文档。

更激进的愿景是"活体文档"：代理持续监控代码变更、基础设施漂移、外部依赖变化，实时更新架构知识库。这不是科幻——Antigravity的架构支持长时运行的代理任务——但需要更精细的变更检测和冲突解决机制。

另一个方向是多模态扩展。当前文档是文本，但架构知识也存在于：监控仪表板的配置、告警规则、运行时的实际流量模式。将这些纳入"可计算架构"的范畴，是自然的演进。

给实践者的行动框架

如果你考虑类似实验，建议的切入路径：

第一周：选一个边界清晰的服务（5-10个文件），手动编写ARCHITECTURE.md模板，定义必须字段。目标是验证"人类编写标准文档"的成本和格式。

第二周：用现有LLM工具（Claude Code、Cursor、或API直接调用）尝试生成同一服务的文档，对比质量差距。识别代理的系统性弱点（如依赖推断错误）。

第三周：引入代理框架（如Antigravity、或自研简单循环），实现"生成-验证-修正"的迭代流程。设定明确的退出条件（如"连续两轮无变更"或"人工裁决队列超过5项"）。

第四周：将文档接入现有质量门禁，测试一项架构级检测（如"验证所有外部API调用都有超时配置"）。测量误报率和漏报率。

关键原则：不要追求一次性完美。文档质量的标准是"比没有好，且能改进"，而非"替代架构师"。

另一个建议：公开你的文档标准。实验中的模板已开源，社区反馈帮助发现了最初遗漏的字段（如"灾难恢复RTO/RPO"）。架构知识有网络效应。

为什么这件事值得兴奋

软件工程长期困于一个悖论：我们建造越来越复杂的系统，却依赖越来越脆弱的知识传递方式。口头传统、离职员工的记忆、过时的Wiki页面——这些是人类文明的史前技术。

架构文档作为一等工程资产，意味着系统知识变得可计算、可验证、可演进。AI代理不是替代工程师思考，而是将工程师从"人形文档同步器"的重复劳动中解放，专注于真正的架构决策。

实验中最具象征意义的画面：工程师在做俯卧撑时，代理在生成文档。这不是偷懒，是分工——人类负责定义价值，机器负责维护一致性。

这个模式的可扩展性令人期待。当每个提交都自动验证架构承诺，当每次重构都有机器辅助的依赖影响分析，当每个新成员都能用自然语言查询系统设计的任何层面——软件工程的认知负荷将发生质变。

技术已经就绪。剩下的问题是：多少团队愿意重新定义"文档"在工程 workflow（工作流）中的位置？

如果你正在Google Cloud上运行微服务，如果你已经被"代码改了但文档没改"的债务困扰，如果你相信AI工具应该有系统级视角而非仅代码级——这个实验的代码和模板是公开的。开始你的俯卧撑吧。