深度 · 小互解读

Cloudflare 编码工程实践：统一编码「规则库」让 Codex 监工，四个月拦下 1.6 万次代码合并

规矩先改写成机器能读的结构，再让 Agent 去查；批准了只提示，显式提升到强制才真拦人
一分钟速览
  • Cloudflare 把散在文档、聊天记录和老员工脑子里的工程规矩，重做成了 Agent 能直接读的结构化数据。
  • 四个月，AI 代码审查器标出近 25 万处违规、拦下 1.6 万次合并；另一个 Agent 在动工前审了近 600 份设计文档。
  • 最值得抄的是那个两级开关：规矩批准了只提示，得再显式提升一次才真的拦人。
  • 60 多份规范全塞给模型会把上下文撑爆，他们的解法是先派个 Agent 把规矩压成 JSON。
⚑ 立场提示：这篇是 Cloudflare 官方博客写自家做法的实践复盘，文中的违规数、拦截数、采纳率都是他们自评口径，没有第三方核验。为了把机制讲透，我另外抓了 Cloudflare 之前两篇相关博文（AI 代码审查器、内部 AI 工程栈）来补背景，这部分内容逐处标注了出处。
起点

Codex 之前，Cloudflare 的工程规范散在四个地方

Cloudflare 8 月 4 日发了一篇工程实践复盘，讲他们怎么把工程规范交给 AI 来执行，过去四个月，他们的 AI 代码审查器标出了近 25 万处违规、拦下 1.6 万次代码合并，另一个 Agent 在动工之前审过近 600 份技术设计。这篇值得读的地方，是它把「文档里的规矩怎么变成合并时真能拦住你的闸门」这条路的每一段都写了出来，其中有一个可以直接抄的设计：规矩批准了先只提示，要再显式提升一次才真的拦人。

先看没有 Codex 的时候是什么样。开发指引散在四个地方：正式文档、仓库里的文件、聊天记录，还有工程师自己脑子里攒的经验。

这带来两层不同的麻烦。

第一层 · 找不着

工程师花在翻规矩上的时间，比花在真正要解决的那个问题上还多。

第二层 · 找着了也不敢信

就算翻到一条答案，你也说不准它是不是最新的、是不是权威的、适不适用于眼下这个情况。

公司一大，这套模式就撑不住了。三个具体后果：没有哪个工程师能读完所有规范；审查者也没法可靠地逐条核对每个要求；人一换团队，攒下来的经验就找不回来了。规矩没人持续提醒、也没人强制执行，项目之间就开始各走各的，出现所谓的漂移（drift）：同一套规矩下，不同项目的做法越差越远。

改造前 正式文档 仓库文件 聊天记录 某人脑子里 找规矩 四处来回跑，找着了还得判断能不能信 改造后 一份 Codex 有域主治理，有状态 审代码 审设计 审事故报告 Agent 在干活现场取用 人的时间花在处理它报出来的结果上
本站示意图，据原文对改造前后的描述绘制。
组织方式

Codex 按域划分，每个域有一个负责人

Codex 是一套有人治理的工程规范集合，Agent 可以在需要的时候取出来、用在当下这件事上。同一份规范，现在能同时喂给代码审查、技术设计审查、事故报告审查这些场景。

它按域切开，每个域覆盖一块工程领域：架构类的（比如前端、控制平面）、横切各处的（安全、可靠性）、具体语言的（TypeScript、Rust），还有其他若干块。每个域有一个域主，对自己那批文档的内容、一致性和整体质量负责。

规矩怎么写：RFC 格式，用 SHOULD 和 MUST 分轻重

Codex 的规范用 RFC 格式写。RFC 是从互联网标准圈来的一种写法：一份提案公开征求意见、多轮修改、最后定稿成为大家遵守的东西。

要求只用两个关键词：SHOULD 和 MUST，定义直接沿用 RFC 2119，这是一份真实存在的互联网标准文档，专门规定这几个词在技术规范里的严格含义。

这两个词的分量差在哪

MUST 是必须做到，没有商量余地。SHOULD 是应该做到，但在特定情况下，如果你完全理解后果并权衡过，可以不做。后面你会看到，这两个词的区别直接决定了 Agent 是给个建议、还是把你的代码拦下来。

文档开头还要有一段 front matter 元信息，就是最前面一小段用来描述这份文档本身的内容，写清它属于哪个域、当前是什么状态，这段是给机器读的。

谁能提规矩？任何一个有兴趣、在这个领域有能力的 Cloudflare 员工，都可以按规定的结构提一个 merge request。提案要过好几轮反馈，参与评审的人越来越多，最后由域主拍板批准，这份 RFC 才进 Codex，并发布到一个用 Astro 搭的内部站点上。

Cloudflare Codex 架构类 前端 · 控制平面 域主 1 人 横切关注点 安全 · 可靠性 域主 1 人 具体语言 TypeScript · Rust 域主 1 人 还有其他若干域 共 60+ 份 RFC 每份 RFC 里的要求只用两个词：MUST（必须） 和 SHOULD（应该） 员工提案 → 多轮评审 → 域主拍板 → 进 Codex
本站示意图。域的分类和 60+ 份 RFC 来自原文；每域「1 人」是示意，原文只说每个域有一位域主，未给人数明细。
机制 · 重点

规范从提案到能拦下代码合并的五个步骤

规矩写好了不等于就能拦人。从一份提案到真的能挡住别人的代码，中间有五步。

Cloudflare Codex 工作流图：从 RFC 提案到强制执行的五个阶段

Cloudflare 官方工作流图。五个阶段从左到右：撰写、自动检查、治理、已批准、已强制。图的副标题点出了这套设计的关键，「RFC 和它的机器可读规则走同一个评审流程」。来源：blog.cloudflare.com。

第一步 · 撰写作者写一份新 RFC 或者更新一份旧的，开一个 merge request。
第二步 · 自动检查两件事并行：CI 校验文档的结构、元数据和签署是否合规；同时一个 Agent 把里面的 SHOULD 和 MUST 语句提取出来，产出一份 JSON diff。
第三步 · 治理人来评审，注意评审的是 RFC 和 JSON 两样，然后由域主批准。不合格就打回去改。
第四步 · 已批准RFC 和 JSON 一起合进 Codex，发布到内部站点。客户端和 Agent 立刻开始标记违规，但只提示，不阻断。
第五步 · 已强制RFC 状态被显式提升到 enforced 之后，客户端才可以拦下 MUST 违规。
撰写 写 RFC · 开 MR 自动检查 CI 校验结构 Agent 抽 JSON 治理 评审 RFC + JSON 域主批准 已批准 合入 · 发布 已强制 显式提升一次 标记违规，但不拦 拦下 MUST 违规 同一条规矩，第四步和第五步之间隔着一次人为的显式提升
本站示意图，据官方工作流图重绘。