How Cloudflare enforces engineering standards using AICloudflare 如何利用 AI 执行工程标准

Over the past four months, our AI code reviewer has flagged nearly a quarter of a million deviations from Cloudflare engineering standards (what we’ll call “violations” in this post) and blocked 16,000 merges. Our spec reviewer agent has evaluated close to 600 technical designs against the same standards before implementation began. Both systems draw from the Cloudflare Codex, a shared source of engineering guidance built for people and agents. This post explains why we built the Codex, how it supports the engineering lifecycle, and what we plan to do next.在过去四个月里，我们的 AI 代码审查员标记了近 25 万处偏离 Cloudflare 工程标准的行为（我们在本文中称之为“违规”），并拦截了 16,000 次合并请求。我们的规范审查代理在实施开始前，已根据相同标准评估了近 600 项技术设计。这两个系统都源自 Cloudflare Codex，这是一个为人类和代理共同构建的共享工程指南库。本文将阐述我们构建 Codex 的原因、它如何支持工程生命周期，以及我们接下来的计划。

Before the Codex (which we briefly introduced in a previous post about our AI engineering stack), developer guidance at Cloudflare lived in many places: formal documentation, repository files, chat threads, and the accumulated knowledge of individual engineers. Engineers often spent too much time searching for guidance instead of working on the problem they were trying to solve. Even after finding an answer, they could not always tell whether it was current, authoritative, or applicable to their situation.在 Codex（我们在之前关于 AI 工程技术栈的文章中曾简要介绍过）出现之前，Cloudflare 的开发者指南分散在各处：正式文档、仓库文件、聊天记录以及工程师个人的积累经验中。工程师往往花费过多时间在寻找指南上，而不是解决他们试图处理的问题。即使找到了答案，他们也无法总是确定这些信息是否是最新的、权威的，或者是否适用于当前情况。

As Cloudflare grew, that model became increasingly difficult to sustain. No engineer could read every standard, and reviewers could not reliably check every requirement. Institutional knowledge became harder to recover when people moved between teams, and guidance that was not consistently surfaced or enforced led to drift between projects.随着 Cloudflare 的发展，这种模式变得越来越难以维持。没有哪位工程师能读完每一项标准，审查员也无法可靠地检查每一项要求。当人员在团队间调动时，机构知识变得难以传承；而那些未能被持续呈现或强制执行的指南，则导致了项目之间的标准偏差。

We rebuilt this body of knowledge as the Cloudflare Codex: a governed set of engineering standards that agents can retrieve and apply at the point of work. The same guidance can now inform code review, technical design review, incident report review, and many other use cases, while engineers focus their time and judgment on the resulting findings.我们将这些知识体系重构为 Cloudflare Codex：一套受治理的工程标准，代理可以在工作时即时检索并应用。现在，同一套指南可以为代码审查、技术设计审查、事故报告审查以及许多其他用例提供参考，而工程师则可以将时间和精力集中在审查结果的判断上。

Copy linkCodex organization and workflow复制链接 Codex 的组织结构与工作流

A dedicated Codex governance model divides the Codex into distinct domains covering the engineering areas we care about. These include architectural matters (for example, frontend and control plane), cross-cutting concerns (security and reliability), specific languages (TypeScript and Rust), and several other areas. Each domain is led by an owner who is responsible for the content, consistency, and overall quality of the documents they oversee.专门的 Codex 治理模型将 Codex 分为不同的领域，涵盖了我们关注的工程范畴。这些领域包括架构事务（例如前端和控制平面）、跨领域关注点（安全性和可靠性）、特定语言（TypeScript 和 Rust）以及其他几个方面。每个领域都由一位负责人领导，负责其所辖文档的内容、一致性和整体质量。

Codex standards use a Request for Comments (RFC) format. Requirements use the SHOULD and MUST keywords defined by RFC 2119. We also expect a front matter header to hold metadata such as the domain and RFC status. Any Cloudflare employee with a key interest and domain competency can propose an RFC through a merge request that follows the prescribed structure. The proposal then passes through several rounds of feedback from an increasingly broad group of reviewers. Once the domain owner gives final approval, the RFC becomes part of the Codex and is published to an Astro-powered internal site.Codex 标准采用“征求意见稿”（RFC）格式。要求使用 RFC 2119 中定义的 SHOULD（建议）和 MUST（必须）关键字。我们还要求在文档头部添加元数据，例如领域和 RFC 状态。任何有相关兴趣和领域能力的 Cloudflare 员工都可以通过遵循规定结构的合并请求来提议 RFC。该提案随后会经过多轮来自更广泛审查组的反馈。一旦领域负责人给予最终批准，该 RFC 就会成为 Codex 的一部分，并发布到内部基于 Astro 构建的站点上。

Approved RFCs can be consumed by Codex clients and agents, which may then start to flag Codex violations in code, configuration, or documentation immediately. However, they block based on Codex statements only after an RFC moves from the approved to the enforced lifecycle state. This separate promotion step gives teams time to absorb new requirements and accommodates cases where enforcement needs additional work.经批准的 RFC 可被 Codex 客户端和代理调用，从而立即开始标记代码、配置或文档中的 Codex 违规行为。然而，只有在 RFC 从“已批准”状态转变为“已强制执行”生命周期状态后，它们才会基于 Codex 声明进行拦截。这一独立的推广步骤为团队留出了吸收新要求的时间，并适应了某些需要额外工作才能实现强制执行的情况。

The following diagram illustrates the steps in the Codex workflow:下图展示了 Codex 工作流的各个步骤：

A naive process could stop here and feed the entire Codex to a large language model (LLM) as is. Given the increasing number of RFCs we have already (60+ and counting), however, the corpus volume would put a lot of stress on the context window and impact LLM results negatively. To help guide models to the most relevant RFCs, we invoke a purpose-built agent to automatically extract and compact the SHOULD and MUST statements into a dedicated JSON structure and enrich it with metadata that supports lazy discovery and progressive disclosure. The following abridged excerpt shows the result for our control plane services RFC:一个简单的流程可能到此为止，直接将整个 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"
    }
  ]
}

Each statement receives a stable slug identifier that remains unchanged during the extraction process even when its RFC is updated. The identifier lets us track the same statement across different systems over time, which is essential for monitoring, analysis, and exception handling.每个声明都会获得一个稳定的标识符（slug），即使在 RFC 更新时，该标识符在提取过程中也会保持不变。该标识符使我们能够跨不同系统长期跟踪同一声明，这对于监控、分析和异常处理至关重要。

Initially, we extracted the statements into another, more concise Markdown file rather than JSON. Over time, we moved to a richer structured format so that agents could filter the content they needed more accurately. We plan to include additional metadata for even tighter scoping, such as indicators for the software development life cycle (SDLC) stage a statement applies to (e.g., design, implementation, runtime).最初，我们将声明提取到另一个更简洁的 Markdown 文件中，而不是 JSON。随着时间的推移，我们转向了更丰富的结构化格式，以便代理能够更精确地过滤所需内容。我们计划包含更多元数据以实现更细致的范围界定，例如指示声明适用的软件开发生命周期 (SDLC) 阶段（如设计、实施、运行时）。

Copy linkCodex consumers复制链接 Codex 使用者

Several systems already use the Codex in day-to-day engineering work. Three agents show how the Codex works in practice: our AI code reviewer, spec reviewer, and incident report reviewer.目前已有多个系统在日常工程工作中使用 Codex。三个代理展示了 Codex 的实际应用：我们的 AI 代码审查员、规范审查员和事故报告审查员。

Copy linkAI code reviewer复制链接 AI 代码审查员

Our AI code reviewer agent, covered in a separate blog post, evaluates merge requests across several dimensions, including Codex compliance.我们的 AI 代码审查代理（在另一篇博文中介绍过）会从多个维度评估合并请求，包括 Codex 合规性。

For each review, the agent retrieves the RFCs and parses the Codex statements. It loads full RFC bodies only when the model or coordinator needs additional context. In most cases, the statements provide enough information to explain a reported violation.对于每次审查，代理都会检索 RFC 并解析 Codex 声明。只有在模型或协调器需要额外上下文时，它才会加载完整的 RFC 正文。在大多数情况下，这些声明已足以解释所报告的违规行为。

The distinction between SHOULD and MUST, together with an RFC’s status, determines how the reviewer responds. Findings from approved RFCs are non-blocking recommendations. Once an RFC is enforced, an unsatisfied MUST requirement causes the reviewer to withhold approval or block a merge request, depending on the severity. SHOULD 和 MUST 之间的区别，连同 RFC 的状态，决定了审查员的响应方式。来自“已批准”RFC 的发现是建议性的，不会拦截代码。一旦 RFC 进入“已强制执行”状态，如果存在未满足的 MUST 要求，审查员将根据严重程度拒绝批准或拦截合并请求。

Since the Codex’s inception earlier this year, the AI code reviewer has flagged close to 230,000 violations. Among these, almost 16,000 caused approval to be withheld (i.e., they referred to MUST statements on enforced RFCs).自今年早些时候 Codex 启动以来，AI 代码审查员已标记了近 23 万处违规。其中，近 16,000 处导致了审批被拒绝（即它们涉及已强制执行 RFC 中的 MUST 声明）。

Copy linkCode review alternatives复制链接 代码审查替代方案

A single AI code reviewer run usually takes a couple of minutes to complete due to the coordinator framework and sub-agent execution. Although the wait is very often worth the money (or tokens), engineers were calling out the delay and extra round trip involved in remediating the findings. We looked into how we could improve the experience and came up with two additional options:由于涉及协调器框架和子代理执行，单次 AI 代码审查通常需要几分钟才能完成。尽管这种等待通常是值得的，但工程师们还是指出了延迟以及修复发现问题时所需的额外往返开销。我们研究了如何改善这一体验，并提出了两种额外方案：

1. For language-specific Codex requirements that can be verified mechanically, we provide custom linter configuration packages. These are aligned with our Codex specification and make it possible to surface problems in milliseconds. TypeScript was the first language to receive Codex linter support while also standardizing on oxlint (maintained by the VoidZero team who joined Cloudflare recently) for performant linter execution. A linter for Rust projects is currently under development, and Go will eventually follow to complete coverage of Cloudflare’s most commonly used languages.对于可以机械验证的特定语言 Codex 要求，我们提供了自定义的 Lint 配置包。这些配置与我们的 Codex 规范保持一致，可以在几毫秒内发现问题。TypeScript 是首个获得 Codex Lint 支持的语言，同时我们也标准化采用了 oxlint（由近期加入 Cloudflare 的 VoidZero 团队维护）以实现高性能的 Lint 执行。针对 Rust 项目的 Lint 工具目前正在开发中，后续还将支持 Go，以完成对 Cloudflare 最常用语言的覆盖。
2. To cut out the continuous integration (CI) leg from the review cycle, we made it possible to run the AI code reviewer locally through a command-line interface (CLI). It matches the coordinator functionality from CI and runs the same (OpenCode-based) agents against an automatically determined diff set, with results presented in the terminal.为了从审查周期中剔除持续集成 (CI) 环节，我们通过命令行界面 (CLI) 实现了在本地运行 AI 代码审查的功能。它匹配了 CI 中的协调器功能，并针对自动确定的差异集运行相同的（基于 OpenCode 的）代理，结果直接呈现在终端中。

We believe the linters would be useful to almost every developer and codebase, while the CLI remains an optional alternative for engineers who prefer it.我们相信 Lint 工具对几乎所有开发者和代码库都有用，而 CLI 则为偏好此方式的工程师提供了一个可选方案。

Copy linkSpec reviewer复制链接 规范审查员

Engineers at Cloudflare regularly write design documents and technical specifications (or specs in short) before implementation. A significant subset of the Codex pertains to design, architecture, and other themes relevant to technical reviews. To catch architectural mistakes before implementation begins, we built the spec reviewer, an agent that discovers specs and evaluates them against relevant Codex requirements.Cloudflare 的工程师在实施前通常会编写设计文档和技术规范（简称 spec）。Codex 的很大一部分内容与设计、架构以及技术审查相关的其他主题有关。为了在实施开始前发现架构错误，我们构建了规范审查员，这是一个能够发现规范并根据相关 Codex 要求进行评估的代理。

The spec reviewer operates on the Developer Platform: it runs as a Cloudflare Worker, stores its results and state in D1, routes model requests through AI Gateway, and kicks off scanning for new specs via a Cron Trigger. It starts by filtering the Codex by domains and sections relevant to specs (for example, language features and implementation-focused RFCs are disregarded). Several guiding prompts instruct the model on how to run the assessment and frame the results. The findings get rated based on severity (influenced by SHOULD and MUST keywords) and include general quality and architectural advice. On completion of a review run, a note is left on the spec document linking to a custom dashboard where review details can be inspected.规范审查员运行在开发者平台上：它作为 Cloudflare Worker 运行，将结果和状态存储在 D1 中，通过 AI Gateway 路由模型请求，并通过 Cron Trigger 触发对新规范的扫描。它首先按与规范相关的领域和章节对 Codex 进行过滤（例如，忽略语言特性和侧重实施的 RFC）。几条引导性提示词会指导模型如何进行评估并梳理结果。发现的问题会根据严重程度（受 SHOULD 和 MUST 关键字影响）进行评级，并包含通用的质量和架构建议。审查完成后，会在规范文档上留下注释，链接到可查看审查详情的自定义仪表板。

Since the beginning of May 2026, almost 600 unique open specs have been reviewed. Including reruns triggered on demand or by spec changes, we tracked over 3,200 review invocations to this date. The vast majority of findings had a “major” (65%) or “minor” (29%) severity, with “critical” findings being the minority (6%).自 2026 年 5 月初以来，已有近 600 份独特的开放规范接受了审查。包括按需触发或因规范变更触发的重审在内，到目前为止我们已跟踪了超过 3,200 次审查调用。绝大多数发现的问题严重程度为“重大”（65%）或“轻微”（29%），“严重”级别的问题仅占少数（6%）。

The following image gives an impression of what the spec reviewer UI looks like:下图展示了规范审查员 UI 的界面：

We plan to integrate the spec reviewer more tightly by posting comments directly on the spec documents, embedding human-agent conversations that can influence the review assessment, and flagging high-impact proposals for additional human review.我们计划通过直接在规范文档上发表评论、嵌入可影响审查评估的人机对话，以及标记高影响力提案以供额外人工审查，来更紧密地集成规范审查员。

Copy linkIncident report reviewer复制链接 事故报告审查员

The incident report reviewer applies the same approach to incident reports (also known as postmortems). In addition to checking that each report is complete, it evaluates whether the report clearly explains what happened, identifies contributing factors, documents the resolution, and proposes meaningful follow-up actions. These expectations are defined in a dedicated Codex RFC.事故报告审查员将相同的方法应用于事故报告（也称为事后总结）。除了检查每份报告是否完整外，它还会评估报告是否清晰解释了事故经过、识别了促成因素、记录了解决方案，并提出了有意义的后续行动。这些期望定义在专门的 Codex RFC 中。

The incident report reviewer uses the same Developer Platform building blocks as the spec reviewer. This shared architecture is becoming a common pattern for our Codex agents.事故报告审查员使用与规范审查员相同的开发者平台构建模块。这种共享架构正成为我们 Codex 代理的一种通用模式。

Since May 2026, the reviewer has assessed more than 200 incident reports and identified gaps such as missing follow-up action items, incomplete timelines, and omitted detection signals. Among those reports, 93% covered incidents that were low-impact, internal-only, or declared preemptively. For high-severity incidents, we’ve made the reviewer mandatory as part of our comprehensive central review process, and reports are not considered complete until all findings have been addressed.自 2026 年 5 月以来，该审查员已评估了超过 200 份事故报告，并识别出诸如缺少后续行动项、时间线不完整以及遗漏检测信号等问题。在这些报告中，93% 涉及的是低影响、仅限内部或预先声明的事故。对于高严重性事故，我们已将该审查员作为全面中央审查流程的一部分强制执行，在所有发现的问题得到解决之前，报告不被视为完整。

Copy linkFuture work复制链接 未来工作

The Codex already supports agents that review code, technical designs, and incident reports. We plan to extend that model throughout the SDLC, allowing agents to surface issues consistently across design, implementation, and operations. The longer-term goal is for agents to identify issues as well as propose fixes with increasing autonomy, while engineers remain responsible for reviewing and approving those changes.Codex 已经支持审查代码、技术设计和事故报告的代理。我们计划将该模型扩展到整个 SDLC，使代理能够在设计、实施和运营过程中持续发现问题。长期目标是让代理不仅能识别问题，还能以更高的自主性提出修复方案，而工程师则继续负责审查和批准这些变更。

We are also expanding the Codex beyond engineering. Product, security, compliance, and trust and safety teams are beginning to add their own standards, allowing agents to evaluate work against considerations that extend beyond design and implementation alone.我们也在将 Codex 扩展到工程之外。产品、安全、合规以及信任与安全团队正开始添加他们自己的标准，使代理能够根据超出设计和实施本身的考量来评估工作。

Across a number of engineering workflows, Codex-backed agents have helped us surface issues sooner and apply standards more consistently. We have found AI most useful when it brings the right guidance to engineers at the point of work, and plan to keep extending the approach across Cloudflare.在多个工程工作流中，由 Codex 支持的代理帮助我们更早地发现问题并更一致地应用标准。我们发现，当 AI 能在工作现场为工程师提供正确的指南时，它的作用最为显著，我们计划继续在整个 Cloudflare 推广这种方法。

If you’re interested in building systems like these, our engineering teams are hiring.如果您有兴趣构建此类系统，我们的工程团队正在招聘。