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.