Cloudflare用AI治理工程标准：Codex体系让代码审查规范化

Cloudflare用AI治理工程标准：Codex体系让代码审查规范化 | 前端进阶之旅

Full translation

完整中文译文

过去四个月，我们的 AI 代码审查工具标记了近 25 万处违反 Cloudflare 工程规范的行为（以下称"违规"），并拦截了 1.6 万次合并。规范审查智能体在实施前评估了近 600 份技术设计，同样依据这些标准。两个系统都依托于 Cloudflare Codex——一个面向开发者和智能体共享的工程指南来源库。本文将介绍我们为何构建 Codex、它如何支撑工程生命周期，以及后续规划。

在 Codex 诞生之前（我们曾在介绍 AI 工程栈的博文中简要提过），Cloudflare 的开发者指南散布在多个地方：正式文档、代码库文件、聊天记录，以及各位工程师积累的经验知识。工程师们常常花费大量时间搜索指南，而非专注于要解决的问题。即便找到了答案，也往往无法判断它是否最新、是否具有权威性、是否适用于当前场景。

随着 Cloudflare 规模扩大，这种模式越来越难以为继。没有哪位工程师能读完所有规范，审查人员也无法可靠地检查每一条要求。当人员在不同团队之间流动时，机构知识变得难以找回，而那些未能一致呈现或执行的指南则导致了项目之间的差异。

我们将这些知识体系重建为 Cloudflare Codex：一套治理化的工程标准集，智能体能够在工作现场检索和应用。同样的指南现在可以支撑代码审查、技术设计审查、事故报告审查等多种用例，而工程师则能将时间和判断力集中在最终的发现上。

Codex 组织与工作流程

专门的 Codex 治理模型将 Codex 划分为不同的领域，覆盖我们关心的工程领域。包括架构事项（如前端和控制平面）、横切关注点（安全和可靠性）、特定语言（TypeScript 和 Rust）以及其他若干领域。每个领域由一位负责人领导，他们对所辖文档的内容、一致性和整体质量负责。

Codex 标准采用征求意见（RFC）格式。需求使用 RFC 2119 定义的 SHOULD 和 MUST 关键字。我们还期望有 front matter 头元数据来存放领域和 RFC 状态等信息。任何对该领域有核心兴趣和能力的 Cloudflare 员工都可以通过遵循规定结构的合并请求来提出 RFC 建议。随后，建议会经过多轮来自范围逐渐扩大的审查者群体的反馈。领域负责人最终批准后，RFC 即成为 Codex 的一部分，并发布到由 Astro 驱动的内部站点。

已批准的 RFC 可被 Codex 客户端和智能体消费，此后可能立即开始标记代码、配置或文档中的 Codex 违规。然而，只有当 RFC 从 approved 状态晋升到 enforced 生命周期状态后，才会基于 Codex 语句进行拦截。这一独立的晋升步骤让团队有时间吸收新要求，也照顾到需要额外工作才能执行的情况。

下图展示了 Codex 工作流程中的各个步骤：

已批准的 RFC 产生非阻塞性发现；晋升为强制执行后，被执行的 RFC 会阻塞 MUST 要求的违规

一个朴素的做法是直接将整个 Codex 喂给大语言模型（LLM）。然而，考虑到我们已有的 RFC 数量不断增加（60+ 且持续增长），语料库体积会给上下文窗口带来巨大压力，并对 LLM 结果产生负面影响。为了引导模型找到最相关的 RFC，我们调用了一个专用智能体来自动提取 SHOULD 和 MUST 语句，并压缩成专用的 JSON 结构，同时补充支持延迟发现和渐进式披露的元数据。以下节选展示了我们控制平面服务 RFC 的结果：

{
  "rfc": 14,
  "title": "Control Plane Services",
  "status": "approved",
  "domain": "control-plane",
  "statements": [
    {
      "slug": "use-quicksilver-for-edge-configuration-propagation",
      "section": ["Proposal", "Infrastructure"],
      "level": "SHOULD",
      "text": "If you need to propagate system or customer configuration to the edge, use Quicksilver via the outbox pattern",
      "href": "/rfcs/014-control-plane-services/#infrastructure"
    },
    {
      "slug": "api-schemas-must-be-documented-in-openapi-spec",
      "section": ["Proposal", "API Gateway"],
      "level": "MUST",
      "text": "API request and response schemas MUST be documented using an OpenAPI spec",
      "href": "/rfcs/014-control-plane-services/#api-gateway"
    }
  ]
}

每个语句获得一个稳定的 slug 标识符，在提取过程中即使 RFC 更新也保持不变。该标识符使我们能够跨不同系统追踪同一语句随时间的变化，这对监控、分析和异常处理至关重要。

最初，我们将语句提取到另一个更简洁的 Markdown 文件中而非 JSON。随着时间推移，我们转向了更丰富的结构化格式，使智能体能够更精确地过滤所需内容。我们计划加入额外的元数据以实现更紧密的域限定，例如标注语句适用的软件开发生命周期（SDLC）阶段（如设计、实现、运行时）。

多个系统已在日常工程工作中使用 Codex。以下三个智能体展示了 Codex 在实践中的运作方式：AI 代码审查工具、规范审查工具，以及事故报告审查工具。

我们的 AI 代码审查智能体在另一篇博文中已有介绍，它从多个维度评估合并请求，其中包括 Codex 合规性。

对于每次审查，智能体检索 RFC 并解析 Codex 语句。只有当模型或协调器需要额外上下文时，才会加载 RFC 全文。在大多数情况下，这些语句提供的信息足以解释所报告的违规。

SHOULD 和 MUST 之间的区别，加上 RFC 的状态，决定了审查者的响应方式。来自已批准 RFC 的发现是非阻塞性建议。一旦 RFC 被强制执行，不满足的 MUST 要求会导致审查者拒绝批准或阻止合并请求，具体取决于严重程度。

自今年 Codex 推出以来，AI 代码审查工具已标记了近 23 万处违规。其中，约 1.6 万处导致批准被保留（即它们涉及已强制执行 RFC 中的 MUST 语句）。

代码审查替代方案

由于协调器框架和子智能体执行，单次 AI 代码审查运行通常需要几分钟才能完成。虽然等待往往物有所值（钱或 token 都值），但工程师们还是对延迟以及修复发现时涉及的额外往返提出了意见。我们研究了如何改善体验，并提出了两种额外选项：

对于可以通过机械方式验证的特定语言 Codex 要求，我们提供了自定义 linter 配置包。这些与我们的 Codex 规范保持一致，使得问题能在毫秒级呈现。TypeScript 是首个获得 Codex linter 支持的语言，同时我们还采用 oxlint（由最近加入 Cloudflare 的 VoidZero 团队维护）来实现高性能 linter 执行。Rust 项目的 linter 目前正在开发中，Go 语言最终也会跟进，以实现 Cloudflare 最常用语言的全面覆盖。

为了削减审查周期中的持续集成（CI）环节，我们实现了通过命令行界面（CLI）在本地运行 AI 代码审查工具。它匹配 CI 中的协调器功能，并对自动确定的 diff 集运行相同的（基于 OpenCode 的）智能体，结果直接展示在终端。

我们相信 linter 对几乎所有开发者和代码库都有价值，而 CLI 则是偏好它的工程师的可选替代方案。

规范审查工具

Cloudflare 的工程师通常在实施前撰写设计文档和技术规范（简称 spec）。Codex 中有相当一部分涉及与技术审查相关的设计、架构和其他主题。为了在实施开始前捕捉架构错误，我们构建了规范审查工具——一个能够发现规范并根据相关 Codex 要求进行评估的智能体。

规范审查工具运行在 Developer Platform 上：它作为 Cloudflare Worker 运行，将结果和状态存储在 D1 中，通过 AI Gateway 路由模型请求，并通过 Cron Trigger 启动对新规范的扫描。它首先按领域和与规范相关的章节（如语言特性和面向实现的 RFC 会被忽略）对 Codex 进行过滤。多个引导 prompt 指导模型如何运行评估以及如何构建结果格式。发现结果按严重程度评级（受 SHOULD 和 MUST 关键字影响），并包含一般性质量和架构建议。审查运行完成后，会在规范文档上留下一条注释，链接到一个自定义仪表板，其中可以查看审查详情。

自 2026 年 5 月初以来，已有近 600 份独特的开放规范接受了审查。算上按需触发或因规范变更而重新运行的，我们追踪到截至该日期已超过 3200 次审查调用。绝大多数发现的严重程度为"主要"（65%）或"次要"（29%），"严重"发现属于少数（6%）。

下图展示了规范审查工具 UI 的外观：

我们计划更紧密地集成规范审查工具：直接在规范文档上发布评论，嵌入可以影响评审评估的人机对话，并标记高影响力提案以进行额外的人工审查。

事故报告审查工具

事故报告审查工具将相同的方法应用于事故报告（也称 postmortem）。除了检查每份报告的完整性外，它还评估报告是否清楚解释了发生了什么、识别了贡献因素、记录了解决方案，并提出了有意义的后续行动。这些期望定义在专门的 Codex RFC 中。

事故报告审查工具使用与规范审查工具相同的 Developer Platform 构建块。这正在成为我们的 Codex 智能体的一种常见模式。

自 2026 年 5 月以来，该审查工具已评估了 200 多份事故报告，识别出了缺失后续行动项、时间线不完整、遗漏检测信号等问题。在这些报告中，93% 涉及低影响、内部或提前声明的事故。对于高严重级别的事故，我们已将审查工具作为全面中心审查流程的强制组成部分，报告在所有发现得到解决之前不被视为完整。

Codex 已支持审查代码、技术设计和事故报告的智能体。我们计划将这一模式扩展到整个 SDLC，使智能体能够在设计、实现和运营中一致地呈现问题。长期目标是让智能体不仅能识别问题，还能以越来越高的自主性提出修复建议，同时工程师保留审查和批准这些变更的责任。

我们还在将 Codex 扩展到工程领域之外。产品、安全、合规以及信任与安全团队开始添加他们自己的标准，使智能体能够根据超越设计和实现本身的考量来评估工作。

在多项工程工作流中，Codex 支撑的智能体帮助我们更快地呈现问题并更一致地应用标准。我们发现 AI 在将正确指导带到工作现场时最为有用，并计划在 Cloudflare 持续扩展这一方法。

如果你对构建此类系统感兴趣，我们的工程团队正在招聘。