Cloudflare's Engineering Standards Playbook: A Unified Rulebook, Enforced by Codex, Blocked 16,000 Merges in Four Months
- Cloudflare turned the engineering rules scattered across docs, chat logs, and senior engineers' heads into structured data that Agents can read directly.
- In four months, the AI code reviewer flagged nearly 250,000 violations and blocked 16,000 merges; another Agent reviewed nearly 600 design docs before work even began.
- The most copyable idea is the two-stage switch: a newly approved rule only warns, until someone explicitly promotes it to enforced and it actually blocks people.
- Feeding 60+ specs all at once would blow up the context window. Their fix: have an Agent compress the rules into JSON first.
Before Codex, Cloudflare's engineering rules lived in four places
On August 4, Cloudflare published a deep dive on how it enforces engineering standards with AI. Over the past four months, their AI code reviewer flagged nearly 250,000 violations and blocked 16,000 merges, while another Agent audited nearly 600 technical designs before any code was written. What makes this post worth reading is how it lays out every step of the path from "rules in a doc" to "rules that actually block a merge." And it contains one design you can steal outright: a newly approved rule only warns at first, and only a deliberate, explicit promotion makes it a real gate.
First, let's look at the world before Codex. Development guidance was scattered across four places: official documentation, files in the repo, chat logs, and the accumulated experience living in engineers' heads.
That created two distinct kinds of pain.
Engineers spent more time hunting for the rule than on the actual problem they were trying to solve.
Even when you dug up an answer, you couldn't be sure it was current, authoritative, or even applicable to your specific situation.
This model falls apart as the company grows. Three concrete consequences: no single engineer can read every standard; reviewers can't reliably check every requirement against every rule; and when someone leaves a team, their accumulated knowledge goes with them. Without constant reminders and enforcement, projects start to drift apart — the classic "drift" problem where different teams interpret the same rules in increasingly divergent ways.
Codex is split into domains, each with an owner
Codex is a governed collection of engineering standards that Agents can pull from when they need a rule for the task at hand. The same set of standards now feeds code review, technical design review, and incident report review.
It's organized by domain, each covering an area of engineering: architectural (frontend, control plane), cross-cutting (security, reliability), language-specific (TypeScript, Rust), and a few others. Each domain has a domain owner responsible for the content, consistency, and overall quality of that set of documents.
How rules are written: RFC format, weighted by SHOULD and MUST
Codex rules are written in RFC format. RFC is a style from the internet standards world: a proposal is opened for public comment, iterated on, and eventually ratified as something everyone follows.
Requirements only use two keywords: SHOULD and MUST, with definitions taken directly from RFC 2119 — a real internet standards document that defines the precise meaning of these terms in technical specifications.
MUST leaves no room for negotiation. SHOULD means you ought to, but in specific situations, if you fully understand the consequences and have weighed the trade-offs, you can skip it. As you'll see, this distinction is exactly what decides whether the Agent sends a suggestion or blocks your code.
Each document also opens with a front matter section — a short block that describes the document itself, including its domain and current status. That's for the machines.
Who can propose a rule? Any Cloudflare employee with an interest and some expertise in the area can submit a merge request in the required format. Proposals go through several rounds of feedback, with more people joining the review over time, until the domain owner approves and the RFC enters Codex. It's then published on an internal site built with Astro.
The five steps from proposal to merge-blocker
Writing a rule doesn't mean it can block anyone. There are five steps between a proposal and a rule that actually holds up someone's code.
Cloudflare's official workflow diagram. Five stages, left to right: Author, Automated checks, Governance, Approved, Enforced. The subtitle captures the core design decision: "The RFC and its machine-readable rules go through the same review process." Source: blog.cloudflare.com.
Why add the "explicit promotion" step?
Cloudflare gives two reasons, both pragmatic: teams need time to absorb new requirements, and in some cases, making a rule truly enforceable takes extra engineering work.
Standards usually die one of two ways: they're too soft and nobody cares, or they're too hard and break every merge in the company on day one.
Splitting "this rule is in effect" from "this rule starts blocking" creates a buffer zone: a new rule runs for a while, everyone can see how many violations they have, and teams fix things at their own pace. Only when things have settled does a human deliberately flip the second switch.
One more detail deserves special attention. The diagram's subtitle reads "The RFC and its machine-readable rules go through the same review process" — the human-readable document and the machine-readable JSON are written, reviewed, and merged together. That way they can't drift apart: no rule changes in the doc while the machine still enforces the old version, and no machine blocking people on a rule no human ever reviewed.
How 60+ standards get compressed into model-friendly JSON
Cloudflare already has more than 60 RFCs, and the count keeps growing. The lazy approach would be to feed the entire Codex to the model as-is, but they explicitly spell out the consequences: that volume puts heavy pressure on the context window and drags down output quality.
Their solution is a dedicated Agent that automatically extracts the SHOULD and MUST statements and compresses them into a purpose-built JSON structure, along with metadata that supports both lazy discovery and progressive disclosure.
Don't shove every rule into the model at once. Start with a table-of-contents-style list, one line per rule. Only when the model determines which rules apply to the current task does it load the full text for those few. Like a book that only shows the table of contents until you turn to a specific chapter.
Here's what the extracted output looks like (JSON is a machine-readable data format that uses braces and field names to lay out information clearly):
{
"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"
}
]
}
rfc is the number, status is the rule's current state (here it's approved, so it isn't blocking yet), and domain tells you where it lives. Each item in the statements array is one rule: level marks it MUST or SHOULD, text is the rule itself, section notes where in the original document it lives, and href links back to the source — the Agent can throw this link at you when it flags a violation.Every rule has an ID that never changes
The slug field above is the key: it's a stable identifier that stays the same even when the RFC gets updated.
Why does this matter? Because the same rule gets referenced by multiple systems: the code reviewer flags it, the monitoring tracks how often it fires, a team applies for an exception to it. If the rule's ID changed every time the document was edited, all those references would break. With a stable slug, one rule can be tracked across systems and across time.
One evolution is worth noting: their first attempt produced a simpler Markdown file, and only later did they move to the richer JSON structure. The reason was that Agents needed to filter what they used more precisely. Next up, they want to add more metadata, like which stage of the software lifecycle a rule applies to — design, implementation, or runtime.
Three agents, one Codex: code review, design review, incident review
Once rules become data, they can power all sorts of things. Right now, three Agents use Codex in day-to-day work.
1. The AI code reviewer
On each review, it first fetches the RFCs, parses out the Codex statements, and only loads the full RFC text when the model or orchestrator needs more context. In most cases, the statements alone are enough to explain a violation.
How it reacts depends on two things: whether the requirement is a SHOULD or a MUST, and what state the RFC is in.
| RFC status | SHOULD not met | MUST not met |
|---|---|---|
| Approved | Non-blocking suggestion | Non-blocking suggestion |
| Enforced | Non-blocking suggestion | Hold approval, or block the merge request (depending on severity) |
The numbers: since Codex launched, the AI code reviewer has flagged nearly 230,000 violations, and almost 16,000 of those resulted in held approvals — meaning they ran into a MUST clause from an enforced RFC.
2. The spec reviewer: catching architecture mistakes before any code is written
Before they start implementing, Cloudflare engineers write design docs and technical specs — a proposal for what you're going to build, why, and what trade-offs you're making. A significant portion of Codex is actually about design and architecture.
The spec reviewer automatically discovers new specs and evaluates them against the relevant Codex requirements. What it runs on is interesting: it's all built on products Cloudflare sells to its customers.
Here's the flow: first, it filters Codex by domain and section, keeping only design-relevant rules (so language-specific or implementation-heavy RFCs are skipped). Then a few guided prompt blocks tell the model how to evaluate and how to structure its results. Issues are scored by severity, influenced by SHOULD vs MUST, along with general quality and architecture feedback. Finally, it posts a comment on the spec doc, linking to a custom dashboard for the details.
Nearly 600
unique open specs reviewed (since early May 2026)
3,200+
review invocations, including on-demand triggers and re-runs from spec changes
65 / 29 / 6
severity distribution of flagged issues (%): major / minor / critical
The spec reviewer interface. A row of filters at the top: last reviewed (7 / 30 / 90 days), severity (Critical+ / Major+ / All), search, team, and resolved status. The spec under review is called "Temporal Resiliency for Platform Workflow Automation," ID RM-24741, marked "1 violation / 4 notes," last reviewed July 25, 2026. Feedback is split into two blocks: Architecture Notes (broken into ARCHITECTURE / SCALE / OPEN QUESTIONS) and Codex Violations. Source: blog.cloudflare.com.
This screenshot is worth a second look because it answers a key question: how specific are the Agent's comments, really?
The red critical architecture note says the spec doesn't define a namespace strategy for multi-cluster deployments, then lists four specific questions it needs answered: whether namespaces are replicated across clusters or unique to each; whether workflows in one namespace can run on both clusters; how namespace isolation is maintained during failover; and whether identically named namespaces in two regions are the same logical namespace or independent. It closes by noting the impact on workflow isolation, multi-tenancy, and failover behavior.
Below that, the Codex violation is tied to RFC-013, "Dependency failure behavior undefined," rated MAJOR: the spec says workers can failover between clusters, but doesn't define the architectural behavior when a cluster fails. The five missing points are: whether a worker fails open or closed when its own cluster is down; what triggers the switch (automatic vs manual); how workers discover and connect to the standby cluster; whether the switch is transparent to running workflows or requires a restart; and what happens to in-flight workflows when a cluster goes down. It also cites a colleague's comment in the doc about replication latency as evidence that this really needs an explicit failure-mode design decision.
Each comment also has a "Recurring" tag (this issue keeps coming up) and a "Feedback" button.
Next up for the spec reviewer: tighter integration — posting comments directly on the spec doc, embedding the human-Agent conversation so it can influence review conclusions, and flagging high-impact proposals for extra human review.
3. The incident report reviewer
The same playbook is applied to incident reports (also called postmortems: the write-up after something goes wrong — what happened, why, how it was fixed, and how it'll be prevented next time).
Beyond checking whether the report is complete, it evaluates whether the report actually explains what happened, identifies contributing factors, documents the remediation, and proposes meaningful follow-up actions. These expectations are written into a dedicated Codex RFC — so even "what a good incident report looks like" is itself a rule a machine can check.
It runs on the same developer platform components as the spec reviewer — a shared architecture that's becoming the standard pattern for the Codex family of Agents.
Since May 2026, it has evaluated more than 200 incident reports, finding gaps like missing follow-up action items, incomplete timelines, and missed detection signals. Of those reports, 93% covered low-impact, internal-only, or preventative incidents. For high-severity incidents, the reviewer is mandatory — it's part of the central review process, and the report isn't considered complete until all issues are resolved.
Two Faster Check Paths: Linter and Local CLI
Once this was up and running, engineers started complaining about speed.
A full AI code review typically takes a few minutes, because the orchestrator framework and sub-Agents are running. Cloudflare is candid here: the cost (in tokens, really) is often worth it, but engineers were reporting two things — the latency of waiting, and the round-trip cost of having to re-run after fixing issues.
So they added two other paths.
The language-level rules that can be verified mechanically were packaged into a linter rule pack (a linter is a tool that checks code style automatically; the rules are rigid and run extremely fast), aligned with Codex — it reports issues in milliseconds.
TypeScript got support first, and they standardized on oxlint to run it — the VoidZero team behind oxlint recently joined Cloudflare. A Rust linter is in progress, and Go will follow, covering their three most-used languages.
This one cuts CI out of the review loop entirely. The CLI tool replicates the orchestrator's function from CI, running the same (OpenCode-based) Agents against an automatically computed diff set, with results shown directly in the terminal.
Cloudflare's own take: the linter is useful for almost every developer and codebase, while the CLI is an option for engineers who prefer that workflow.
For the same rule, who should check it depends on whether it requires understanding semantics: things that can be verified mechanically (naming, formatting, what parameters an API must take) go to the linter, with results in milliseconds; things that require reading context (does this design consider failover?) are worth the few minutes for a model.
Mix the two together and you either get something too slow for anyone to use, or something that misses the issues that actually matter.
Cloudflare's Roadmap, and a Few Numbers That Don't Quite Add Up
Their roadmap has three threads:
A few issues I checked with the numbers
Three things, none of which change the main story, but worth knowing when you quote them:
A summary from them, in their own words
In another post about their internal AI engineering stack, Cloudflare has a line that carries more weight than any of the numbers above:
None of these pieces are particularly novel on their own. Many companies have service catalogs, have shipped review bots, have published engineering standards. The difference is in the wiring.
Cloudflare, "Our internal AI engineering stack," translated by this site
The same post also gives adoption data for the whole system: from kickoff to 93% adoption across R&D in under a year; between February 5 and April 15, 2026, 3,683 active users, or 60% of the company.
Three takeaways for developers and engineering leaders
After breaking this whole thing apart, three lessons hold up outside Cloudflare's specific context.
Standards exist for people to read; models can't handle them. Shove 60+ RFCs in as-is and the context window saturates, dragging output quality down with it. You need a structuring step in between: pull out each "what must be done" as a standalone statement, convert it to JSON, and give each one a slug that doesn't change when the document does.
Only after structuring can you feed on demand: the model reads a one-line-per-rule list first, decides which ones apply to this task, and only then loads the full text for those few. Accuracy goes up, tokens go down.
First, levels: SHOULD is a suggestion, MUST is mandatory. This is what tells the machine whether to send a nudge or hold a merge.
Then, a buffer: after a new rule is approved, it warns but doesn't block. Teams can see how many violations they have and fix them at their own pace. Once things have settled, a human deliberately flips the second switch and enforcement begins. Skip the buffer and go straight to enforced, and you'll have a mutiny on your hands.
Cloudflare's real killer move is where they put the checks: the same set of rules is applied at three different points in time, and the earlier the check, the cheaper it is.
In the design phase, the spec reviewer evaluates design docs before anyone writes code — changing an architecture decision at this point is a few lines of text. In local development, the linter reports in milliseconds and the CLI runs a full review locally without waiting for CI. At merge time, finally, comes the full CI review that takes a few minutes.
In engineering this is called "shifting left" — moving quality checks from the end of the process to the beginning. If you wait until the code is written to discover an architecture mistake, the rework costs tens of times more than if you'd caught it in the design phase.
Cloudflare turned its engineering rules into machine-readable data, and now an Agent enforces them at merge time
Cloudflare's official retro: one set of standards feeding three Agents — code, design, and incident review — told in one illustrated page
↓ Read in one page · One animated figure included
Before Codex, Cloudflare's dev guidance lived in four places: official docs, files in the repo, chat logs, and the accumulated knowledge in senior engineers' heads. Two layers of pain: hunting for the rule took longer than solving the problem; and even when you found it, you couldn't be sure it was current, authoritative, or applicable. As the company grew, different projects drifted further and further apart.
Codex is split into domains (frontend, control plane, security, reliability, TypeScript, Rust…), each with a domain owner responsible for content and quality. Rules are written in RFC format, and requirements only use two words: MUST means it's mandatory, SHOULD means you ought to — but can skip with good reason. The definitions come straight from RFC 2119, a real internet standards document.
Scale was the next wall: 60+ RFCs and growing. Feed the whole thing to the model and you saturate its context window (how much it can read at once), tanking output quality. Their fix: a dedicated Agent extracts those statements and compresses them into JSON.
A written rule doesn't mean it can block anyone. There are five steps between a proposal and actually holding up someone's code; the human-readable doc and machine-readable JSON travel together the whole way — written, reviewed, and merged as one — so the two sides can't drift apart.
The same Codex now feeds three Agents, watching code, design docs, and incident reports respectively.
| Who's checking | What, and when | Consequences |
|---|---|---|
| AI code reviewer | Code at merge request time | Rule enforced + MUST not met → hold approval, or block the merge |
| Spec reviewer | Design docs before any code is written | Scores by severity, leaves a comment on the doc, links to a dashboard |
| Incident report reviewer | Postmortems after an outage | Mandatory for high-severity incidents; report isn't complete until issues are resolved |
Once it was running, engineers complained about speed, so the same rules got two faster check paths.
Four months, three Agents, and the volume they produced.
All figures are self-reported by Cloudflare's official blog and haven't been verified by a third party.
- × Official docs
- × Some file in the repo
- × A chat log from 3 months ago
- × A senior engineer's head
but is it even current?
longer than solving the problem
difference?
and growing
but don't block.
what they need to fix
the switch again
Merge doesn't go through
Members can copy or download the full Markdown, and let their AI subscribe and ask.
Found this useful? Leave your email — every new explainer, the moment it's out. Unsubscribe anytime.