A shared source of engineering truth
Cloudflare has spent the past four months centralizing its engineering guidance into a single, machine-readable corpus dubbed the Cloudflare Codex. The AI code reviewer, announced earlier this year, has already flagged close to 230,000 deviations from these standards and blocked 16,000 merge requests on the basis of enforced requirements. A separate spec reviewer agent has evaluated almost 600 technical designs against the same guidance before a line of implementation code was written.
Previously, developer guidance lived in scattered formal documentation, repository files, chat threads, and the heads of individual engineers. That fragmentation made it hard to find authoritative, up-to-date answers and led to drift between projects as teams moved on and institutional knowledge faded. The Codex consolidates that knowledge into a governed set of RFCs that both humans and automated agents can retrieve and act on at the point of work.
How the Codex is organized
The Codex is split into domains covering areas such as architecture (frontend, control plane), cross-cutting concerns (security, reliability), and specific languages (TypeScript, Rust). Each domain has an owner accountable for content quality and consistency.
Standards are written in a Request for Comments (RFC) format, using the SHOULD and MUST keywords defined by RFC 2119, plus a front matter header for metadata like domain and RFC status. Any employee can propose a new RFC via a merge request that follows a prescribed structure. After several rounds of increasingly broad feedback, the domain owner grants final approval and the RFC is published to an internal Astro-powered site.
Approved RFCs are immediately consumable by Codex clients and agents, which can flag violations in code, configuration, or documentation. However, an RFC must move from the approved to the enforced lifecycle state before agents will block on its statements. That separate promotion step gives teams time to absorb new requirements and handles cases where enforcement needs extra work. The workflow breaks down as follows:
Rather than feeding the entire corpus — currently 60-plus RFCs and growing — to an LLM, Cloudflare relies on a purpose-built agent to extract and compact SHOULD and MUST statements into a dedicated JSON structure enriched with metadata for lazy discovery and progressive disclosure. The excerpt below shows the result for the control plane services 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 gets a stable slug identifier that persists even when its source RFC is updated. That identifier enables tracking of the same statement across different systems over time for monitoring, analysis, and exception handling. The extraction format itself started as a concise Markdown file but moved to a richer JSON structure so agents can filter content more precisely. Plans call for adding SDLC-stage metadata to enable even tighter scoping.
Consumers of the Codex
Three agents already use the Codex in day-to-day engineering workflows: the AI code reviewer, the spec reviewer, and the incident report reviewer.
AI code reviewer
The AI code reviewer evaluates merge requests across several dimensions, including Codex compliance. For each review, the agent retrieves relevant RFCs and parses their statements. It loads full RFC bodies only when the model or coordinator needs more context; in most cases the statements alone are enough to explain a violation.
The SHOULD-versus-MUST distinction and the RFC's lifecycle state determine how the reviewer responds. Findings from approved RFCs are non-blocking recommendations. Once an RFC is enforced, an unsatisfied MUST statement causes the reviewer to withhold approval or block a merge outright, depending on severity.
A single AI code reviewer run typically takes a couple of minutes because of the coordinator framework and sub-agent execution. Recognizing that delay adds a round trip for engineers, Cloudflare introduced two alternatives:
- Custom linter configuration packages aligned with the Codex specification for language-specific requirements that can be verified mechanically. These surface problems in milliseconds. TypeScript was the first language to receive Codex linter support, standardizing on oxlint for performant execution. A Rust linter is in development; Go will follow to cover the company's most common languages.
- A command-line interface (CLI) that runs the AI code reviewer locally, bypassing the CI leg entirely. It matches the coordinator functionality used in CI and runs the same OpenCode-based agents against an automatically determined diff set, presenting results in the terminal.
Spec reviewer
Cloudflare engineers write design documents and technical specs before implementation. A significant subset of Codex RFCs concerns design and architecture. The spec reviewer agent catches architectural mistakes before code is written by discovering specs and evaluating them against relevant Codex requirements.
The agent runs on the Developer Platform as a Cloudflare Worker. It stores state in D1, routes model requests through AI Gateway, and triggers spec scans via a Cron Trigger. It filters the Codex to domains relevant to specs — language features and implementation-focused RFCs are ignored — and uses guiding prompts to frame the assessment. Findings are rated by severity, influenced by SHOULD and MUST keywords, and include architectural and quality advice. After each run, a note with a link to a custom dashboard is left on the spec document.
Since May 2026, nearly 600 unique open specs have been reviewed. Including reruns triggered on demand or by spec changes, Cloudflare has tracked more than 3,200 review invocations. Among findings, 65% were rated “major” and 29% “minor,” with "critical" findings the minority at 6%.
Future work for the spec reviewer includes posting comments directly on spec documents, embedding human-agent conversations into the review assessment, and flagging high-impact proposals for additional human review.
Incident report reviewer
The incident report reviewer applies the same approach to postmortems. It checks that each report is complete and evaluates whether it clearly explains what happened, identifies contributing factors, documents the resolution, and proposes meaningful follow-up actions — expectations defined in a dedicated Codex RFC.
Built on the same Developer Platform components as the spec reviewer, the incident report reviewer has assessed more than 200 incident reports since May 2026, identifying gaps such as missing follow-up action items, incomplete timelines, and omitted detection signals. Ninety-three percent of those reports covered incidents that were low-impact, internal-only, or declared preemptively. For high-severity incidents, the reviewer is mandatory as part of a central review process, and reports are not considered complete until all findings are addressed.
Extending the model
The Codex currently supports agents for code, technical designs, and incident reports. Cloudflare plans to extend that model across the entire software development life cycle, aiming for agents that surface issues consistently from design through operations. The longer-term goal is for agents to not just flag problems but propose fixes with increasing autonomy, with engineers reviewing and approving the changes.
Expansion beyond engineering is also underway. Product, security, compliance, and trust and safety teams are beginning to add their own standards to the Codex, letting agents evaluate work against considerations that extend beyond design and implementation.
The Codex-backed agents have helped Cloudflare surface issues earlier and apply standards more consistently across engineering workflows. The most useful pattern, according to the company, is bringing the right guidance to engineers at the point of work.
