AI Agent 自动生成微服务架构文档的实践

捕获那些被 linter 漏掉的系统性故障

自主 AI Agent 如何在你做俯卧撑的同时，为微服务平台生成一份完整的架构快照；以及为什么这份文档会成为 AI 驱动的质量流水线中最强大的输入。

你可以收听根据本文生成的播客（感谢 NotebookLM）：

架构文档不是一项苦差事。当它与源代码放在一起，并被送入 AI 驱动的质量流水线后，就能让静态分析从“捕获拼写错误”升级为“发现系统性安全故障和代价高昂的基础设施资源泄漏”。本文记录了一次真实实验：一个自主 AI Agent 为由多个服务组成的 Google Cloud 平台生成了架构文件，期间人类工程师基本没有参与；而当这些文档让我们的 AI Quality Gate 获得了全新的观察视角后，又发生了什么。

1. “代码自文档化”的问题

软件工程领域一直存在一种根深蒂固的假设：结构良好的代码本身就能说明一切。整洁的函数、恰当的变量名，再加上 10.0/10 的 Pylint 评分——这些肯定已经足够了吧？

代码描述的是系统如何执行。架构文档描述的是系统为何存在，以及它如何与周围的一切交互。如果缺少这一层上下文，所有自动化分析工具都只能在黑暗中摸索。它能看到一个函数，却不知道这个函数在整个服务网格中扮演什么角色；它能看到一次 API 调用，却不知道这次调用本应实施怎样的安全边界。

当你把 AI 驱动的工具引入工程工作流时，这一区别尤为重要。让 LLM 在没有架构上下文的情况下分析原始代码，就像要求一名高级工程师在看不到系统设计的情况下完成安全审查。

2. 一边做俯卧撑，一边生成架构文档

我的平台运行在 Google Cloud 上。它由数十个部署在 Cloud Run 上的微服务组成，这些服务通过 REST API 交互，将资产持久化到 Google Cloud Storage，并通过一个集中式 Vertex AI 网关路由所有 AI 操作。这是一个内容丰富、连接紧密的系统，但仅有的文档却散落在各个 README 文件中。

我决定改变这种状况。目标是：为每个服务生成一份标准化、机器可读的架构快照，并直接提交到代码仓库中。

采用的方法是：由人引导的自主 Agent 执行。

工程师确定方向、建立文档标准，随后退到幕后。AI Agent 接手了后续工作。它由运行在 Antigravity 这一 Agentic AI 编程助手中的 Gemini 3 Flash 和 Claude Sonnet 4.6 驱动，自主检查每个服务、阅读源代码、追踪服务间依赖、依据文档标准交叉核对现有实现，并通过迭代生成结构化的 ARCHITECTURE.md 文件。在这一过程的大部分时间里，工程师的主要活动都是锻炼身体。

最终产出的并不是非正式笔记，而是一套严谨的多层级文档体系：

📦 platform-root
 ┣ 📜 ARCHITECTURE.md           ← Level 0: Global service mesh, topology, lifecycle status
 ┗ 📂 services
    ┣ 📂 core-ai-gateway
    ┃  ┗ 📜 ARCHITECTURE.md     ← Level 1: Security policy engine, FinOps guardrails
    ┣ 📂 orchestration-bot
    ┃  ┗ 📜 ARCHITECTURE.md     ← Level 1: Async task flow, Telegram webhook handling
    ┣ 📂 media-transcriber
    ┃  ┗ 📜 ARCHITECTURE.md     ← Level 1: Speech-to-Text pipeline, GCS asset management
    ┗ 📂 translation-engine
       ┗ 📜 ARCHITECTURE.md     ← Level 1: Structured output, multilingual routing

每份文档都遵循严格的模板：

意图（Intent）：该服务存在的具体业务原因和技术原因。

设计原则（Design Principles）：关键权衡，包括无状态设计、延迟目标和回退策略。

交互图（Interaction Diagram）：一张 Mermaid 图，用于展示服务间的数据流、安全边界以及与 AI 提供商的集成关系。它可以由 Agent 生成，并在 Gitlab 中自动绘制。

LLM 上下文块（LLM Context Block）：一份经过精确提炼的摘要，专门针对自动化 Agent 和 AI Reviewer 的使用场景进行优化。

整个过程最终生成了一张可导航、相互链接的架构地图，只需要极少的人类认知投入——而且还有可视化图表！

3. Quality Gate 觉醒

文档与源代码一同提交后，我使用 AI 驱动的 Quality Gate 运行了一次标准 CI 质量审查。该服务构建在通过 Vertex AI 调用的 Gemini 之上，旨在对每个 merge request 自动执行架构审查和安全审查。

💡 Quality Gate 究竟是什么？它并不是什么价值 10 万美元的企业级 SaaS 平台，而是一个轻量级、专门构建的微服务。它本身就是所审查平台的一部分，并部署在 Google Cloud Run 上。它只暴露一个 endpoint，从 CI 流水线接收 merge request diff，构建一条由代码仓库架构文档增强的 LLM prompt，调用 Vertex AI（Gemini），最后返回一份结构化的 JSON 审查报告。

由于它运行在 Cloud Run 上，因此只会在触发审查时启动，并在审查完成后立即关闭。对我来说，每月总成本只有几美元，还不到一次人工 code review 一小时成本的零头。这是 Google Cloud serverless 模型的一次实际演示：只为真正使用的计算资源付费，并且只在高智能 AI 能够创造价值时才使用它。

差异立刻显现了出来。

此前由于缺少架构上下文，Quality Gate 只能进行代码层面的分析，例如风格一致性、常见的安全反模式和依赖版本。这些功能很有用，但停留在浅层。

有了 ARCHITECTURE.md 文件提供上下文，模型便能同时看到架构和代码。结果是一次质的飞跃：Quality Gate 从静态分析工具转变成了一个能够在系统设计层面工作的推理系统。

它在几分钟内发现了两个严重问题，而这些问题已经在代码库中潜伏了几个月，始终没有被察觉。

发现 1：分布式追踪中断

我们的一个路由服务中包含一段 middleware，会明确移除传入的 trace header。从表面上看，这似乎是一项合理的安全措施，可以防止外部客户端向内部系统注入 trace identifier。

Quality Gate 将其判定为严重的可观测性违规。

由于架构文档描述了整个服务网格采用的分布式追踪标准，其中包括端到端传播、兼容 Google Cloud Trace 的 X-Trace-ID 这一要求，因此模型理解到：在边界处移除这些 header 并不能隔离威胁，反而会彻底切断追踪链。在任何生产事故中，工程师都将无法在 Cloud Logging 中关联多个服务的日志，使一次常规调试演变成持续数小时的取证调查，而且也无法依靠 Cloud Audit Logs 的关联信息。

安全意图 ✓。系统性后果 ✗。文档让这一矛盾变得清晰可见。

发现 2：悄无声息的存储泄漏

一个媒体处理服务被明确设计为：每次处理任务完成后，故意跳过对 Google Cloud Storage 中临时资产的清理。其隐含的理由是保持简单，同时避免因删除错误而引入故障模式。

Quality Gate 将这一行为与文档中记录的数据最小化和最小权限访问原则进行了交叉核对，并将其标记为同时违反安全要求和 FinOps 原则。

其影响是：可能包含敏感个人信息的用户音频文件会无限期地积累在云存储中。没有 lifecycle policy，没有 deletion trigger，成本会悄无声息地持续叠加增长。每新增一个处理请求，攻击面都会进一步扩大。

无论是 linter，还是孤立地扫描函数的 code reviewer，都不会发现其中任何一个问题。这两个发现都来自代码行为与架构意图的交汇处，而只有在文档存在的情况下，这种交汇才清晰可见。

这次实验在三个维度上产生了可量化的投资回报：

在 Google Cloud 平台的背景下，还有三个因素尤其值得注意：

Vertex AI Token 效率：当 Quality Gate 由 Gemini 模型提供支持时，提供结构化的 ARCHITECTURE.md 可以减少模型为了从原始代码中重建系统意图而消耗的 token。更好的上下文意味着生成成本更低、速度更快、准确性更高，并会直接影响 AI 计算成本。

Vertex AI Token 效率：当 Quality Gate 由 Gemini 模型提供支持时，提供结构化的 ARCHITECTURE.md 可以减少模型为了从原始代码中重建系统意图而消耗的 token。更好的上下文意味着生成成本更低、速度更快、准确性更高，并会直接影响 AI 计算成本。

Cloud Run 可观测性：前面提到的分布式追踪问题，对于基于 Cloud Run 的架构尤其重要，因为其中的服务是无状态且短暂存在的。如果不能持续传播 trace，在 Cloud Run 上调试服务间故障就会困难得多。文档明确揭示了这一风险，从而使其能够被发现。

Cloud Run 可观测性：前面提到的分布式追踪问题，对于基于 Cloud Run 的架构尤其重要，因为其中的服务是无状态且短暂存在的。如果不能持续传播 trace，在 Cloud Run 上调试服务间故障就会困难得多。文档明确揭示了这一风险，从而使其能够被发现。

Serverless 成本模型：由于 Quality Gate 是一项仅在 CI/CD 运行期间调用的 Cloud Run 服务，因此闲置成本为零。对于一个每天有多个 merge request 的典型团队，整套 AI 驱动的审查流水线每月只需几美元，还不到一小时的工程成本。这正是 Google Cloud serverless 模型理想中的工作方式：按需使用高智能计算能力，同时将成本降至最低。

Serverless 成本模型：由于 Quality Gate 是一项仅在 CI/CD 运行期间调用的 Cloud Run 服务，因此闲置成本为零。对于一个每天有多个 merge request 的典型团队，整套 AI 驱动的审查流水线每月只需几美元，还不到一小时的工程成本。这正是 Google Cloud serverless 模型理想中的工作方式：按需使用高智能计算能力，同时将成本降至最低。

5. 给平台工程师的经验

这次实验带来的关键洞察，并不是 AI Agent 编写文档的速度比人类更快——这是意料之中的。真正的关键在于：存放在代码仓库内部的架构文档，能够成倍放大所有读取它的自动化工具的能力。

无论你的自动化工具是 AI 驱动的 code reviewer、合规扫描器、入职辅助工具，还是基础设施规划 Agent，这一点都适用。文档质量越高，构建在文档之上的每个工具所获得的信号质量就越高。

实用建议：

将文档与代码放在一起。单独维护且会逐渐与代码失去同步的 wiki 只是噪声。放在服务目录中，并在修改代码的同一次 commit 中更新的 ARCHITECTURE.md，才是真正有效的信号。

建立文档标准。采用一致的模板——例如意图、原则、交互图——可以让文档不仅便于人类阅读，也能被机器读取。

定义生命周期状态。清楚标记已弃用或不再活跃的服务。自动化 Agent 不应把遗留代码当成当前标准的参考实现。

使用 Agent 生成初稿。从空白页面开始撰写文档所带来的认知负担是真实存在的。Agent 非常擅长先生成一份结构化的初稿，再由工程师进行验证和完善。

将文档提供给 CI 流水线。拥有架构上下文的 AI Quality Reviewer，与缺少这些上下文的工具完全不是同一个级别。

构建自己的 Quality Gate，并让它真正属于你。这是企业 SaaS 无法比拟的关键优势：灵活性。构建一个由 Gemini 支持、以你的合规规则、架构标准和团队约定为依据的自定义 Cloud Run 服务，意味着每位开发者都能拥有一个理解项目确切上下文的专属 Reviewer，而不是只能使用一套为所有可能代码库的平均情况设计的通用规则。

一直以来，架构文档都被视为一种可有可无的额外负担：理论上很有价值，实践中却总是被降低优先级。这次实验表明，当文档与源代码放在一起、遵循一致且机器可读的标准，并借助自主 Agent 保持最新状态时，它就会成为一项关键的基础设施组件。

它让自动化系统能够在平台设计层面进行推理，而不只是检查代码语法。它让 AI 驱动的 Quality Gate 从昂贵的 linter 转变为真正的架构顾问。而且，你完全可以在处理其他事情的同时，为整个平台生成这些文档。

价值 10,000 美元的 ARCHITECTURE.md 并不是一个比喻。它代表的是两种情况之间的预估成本差：一种是在 5 分钟的 CI 审查中发现严重架构缺陷，另一种则是等到生产事故、合规审计，或者收到一张出乎所有人意料的云存储账单时才发现问题。

持续记录你的架构。把文档保存在代码仓库里。让 Agent 维护它。

保持标准化。保持安全。

部分评论可能只有登录后的访问者才能看到。请登录以查看所有评论。

如需采取进一步措施，你可以考虑屏蔽此人和/或举报滥用行为。