来源：Claude Blog — How CodeRabbit used Claude to build an agent orchestration system（2026.05.27）
一句话：代码生成越便宜，方向错误的代价就越高——CodeRabbit 的答案是在 Claude Code 之前加一层规划系统，让所有隐式假设在第一行代码写出之前就被暴露。
引言：AI 编码的真正瓶颈不是能力，是方向
CodeRabbit 成立于 2023 年，目前每周审查超过 200 万个 Pull Request，服务 15,000+ 客户。当他们大规模分析 AI 生成的 PR 时，发现了一个反直觉的事实：
最常见的失败模式不是代码无法编译或测试失败，而是——代码能编译、能通过测试，但并没有解决它本该解决的问题。
这不是模型能力不足，而是信息传递出了问题。
问题定义：隐性知识鸿沟
经验丰富的开发者会内化大量上下文知识——架构决策的历史原因、团队约定的边界、业务规则的隐含前提。当他们给 AI 下达指令时，往往假设对方和团队成员一样理解这些"不言自明"的背景。
AI 不理解暗示，它用自认为"合理"的内容填补空白。
CodeRabbit AI 副总裁 David Loker 分享了一个切身经历：他在副项目中构建内存系统，花了数小时与编码 Agent 迭代直到一切运行正常。当他查看使用说明时，被告知需要传入用户令牌。问题是——系统中没有登录页面。他指定了系统需要用户，但从未明确说"用户需要一种登录方式"。
“你在上面继续构建更多功能，很久以后才发现根基有问题。在 AI 工作流中，延迟验证的代价非常昂贵。”
这个案例精准概括了问题本质：隐性假设 + 延迟验证 = 累积的方向偏移。
架构设计：在代码生成之前插入规划层
CodeRabbit 的解决方案不是让模型更聪明，而是在架构上做文章——在代码生成之前插入一个编排层/规划系统，协调多个 Claude 模型来分析需求、暴露假设，生成结构化执行计划。
核心流程：
开发者需求 → [编排层：需求分析 → 假设暴露 → 上下文补全 → 结构化 PRD] → Claude Code → 代码实现
关键设计决策：
- 这不是 Claude Code Plan Mode 的替代品。Plan Mode 是 Claude Code 内部的规划；编排层是更高层级的系统，在 Claude Code 之前运行，目的是"将其引导到一个非常狭窄且正确的方向"。
- 输出物是协作式 PRD——一份在完整上下文下创建、经利益相关者验证、在实施开始前审查的计划。它是一个共享工件，记录了做出的决策及其原因。
这份 PRD 的价值不仅在于指导当次代码生成，更在于：
- 避免返工（假设在前期暴露）
- 验证输出（PRD 是对照基准）
- 知识沉淀（新工程师可直接查阅决策上下文）
跨模型路由：按复杂度分配模型层级
CodeRabbit 并不是用单一模型跑完全流程，而是根据任务复杂度在 Claude 模型家族内做智能路由：
| 模型 | 角色 | 典型任务 |
|---|---|---|
| Opus | 编排循环 · 战略层 | 理解问题本质、设定整体方向与约束、质量门禁判断 |
| Sonnet | 结构化规划层 | 将 Opus 输出排列为步骤、生成 PRD、需求细化 |
| Haiku | 窄范围执行层 | 上下文蒸馏、针对性工具调用、格式化提取 |
路由原则很务实：
“如果 Haiku 在某个任务上表现和 Sonnet 一样好，我们就用 Haiku。如果评估工具告诉我们给 Opus 更多空间能提升计划质量，我们就给它更多空间。我们不靠猜测。”
可迁移的启示：多模型路由不是奢侈品，而是工程必需。Agent 系统中大量中间步骤（上下文压缩、格式化、简单分类）完全不需要旗舰模型，用小模型处理可以在不损失质量的前提下大幅降低延迟和成本。关键是——需要一套评估体系来验证路由决策是否正确。
评估体系：让规划质量可度量
CodeRabbit 拥有成熟的代码审查评估系统，但在引入规划层时面临一个新挑战：没有评估规划输出质量的基础设施。
他们的解法分为四步：
1. 冷启动：手动调优
从手工示例和人工检查开始，建立初始质量基线。
2. LLM 评判库（LLM Judges）
开发了一套自动化评判器，对计划质量的多个维度评分——完整性、一致性、可执行性。
3. 端到端验证
由于计划最终会产生代码，可以闭环度量：
- 生成的代码是否有效（编译/测试）
- 是否包含额外范围（scope creep）
- 花费了多少 tokens
- 输出是否匹配原始意图
4. A/B 对比隔离
对同一任务分别运行有/无规划步骤，隔离规划本身的增量价值。
关键发现：抽象层级的平衡
“我们没有意识到计划的正确详细程度应该是什么。”
- 计划过于细粒度 → 代码库一变动就过时，维护成本高
- 计划过于高层 → 给 Agent 留下了填补假设的空间，回到了原始问题
找到合适的抽象层级需要反复迭代——而评估体系使这种迭代成为可能。没有度量，就无法知道某次抽象层级的调整是改善还是退化。
最佳实践：四个关键问题
CodeRabbit 团队将经验提炼为四条行动建议：
| # | 在编码之前问自己 | 行动 |
|---|---|---|
| 1 | 你实际想创造什么结果？如何衡量？ | 明确规格说明，定义最大可能产品（MPP） |
| 2 | 哪些假设仍然是隐式的？ | 让 AI 帮你识别：计划中哪些部分作为隐式假设而非显式规格存在？ |
| 3 | 哪些工作流或边缘情况容易被遗忘？ | 让 AI 帮助枚举可能未考虑到的场景 |
| 4 | 如何在上线前确认输出符合意图？ | 创建工作记录：保存和复用规划工件的编年史 |
这四条本质上是在说同一件事：把验证前移。不是等代码写完再审查，而是在计划阶段就把方向锁死。
总结：代码生成越便宜，规划越重要
CodeRabbit 的案例揭示了一个 Agent 工程化的核心悖论：
- 代码生成的边际成本趋近于零
- 但方向错误的代码产生的下游成本（返工、调试、级联错误）并未降低
- 因此：规划层的 ROI 随着生成能力增强而不断提升
“计划本身成为了一个质量门禁。如果我们能确保计划的质量在前期就足够好，下游效果会非常显著——最终你会得到更好的代码。”
对于正在构建 Agent 系统的工程师，三条可直接迁移的经验：
- 在 Agent 执行链前加规划层——不是让模型在 system prompt 里"先思考再回答"，而是一个独立的编排系统，输出结构化 PRD。
- 按复杂度路由模型——战略决策用旗舰、结构化输出用中端、窄操作用轻量模型，用评估数据而非直觉决定路由边界。
- 为规划输出建评估闭环——如果你无法度量计划质量，就无法迭代改进它。从 LLM 评判 + 端到端验证 + A/B 对比三板斧开始。
规划不是开销，规划是 Agent 系统中 ROI 最高的投资。
「真诚赞赏，手留余香」
爱折腾的工程师
真诚赞赏，手留余香
使用微信扫描二维码完成支付
