AI Coding Agent 如何稳定提交可合并的 PR

上周 review 了一个 AI 生成的 PR。CI 全绿，功能也确实能用，但我最后还是把它关了。

原因很简单：它改了 37 个文件，顺手升级了一个依赖，还修改了两条测试断言。代码能跑，但没人知道它到底改了什么，也没人敢合。

这件事让我重新想了一遍：AI Coding Agent 的难点，从来不是“写出能跑的代码”，而是“提交一个人类愿意合并的 PR”。

能跑和可合并，差的不是一点

一个可合并的 PR，至少要满足几件事：改动范围清楚，测试覆盖了改动，风格和仓库一致，没有引入不必要的依赖，没有夹带密钥或调试代码，reviewer 能在几分钟内看懂意图。

AI 生成的代码经常在这些地方出问题：

改动范围过大，为了修一个 bug 顺手重构了半个模块；测试只覆盖 happy path，错误分支没管；不遵守仓库的命名和目录约定；复制了过时的 API 用法；提交信息含糊，reviewer 不知道它想干什么。

这些问题不是模型能力问题，是上下文和流程问题。

先给 Agent 一张仓库地图

我现在接手一个 AI Coding 项目，第一件事不是调 Prompt，而是补仓库说明。

在根目录放一个简短的 AGENTS.md 或 CLAUDE.md，写清楚：项目结构、模块边界、本地开发和测试命令、代码风格、提交规范、不能动的目录、已知的坑。

这个文件要短、具体、可执行。不要写成长篇架构文档，模型不会认真读，人也懒得维护。

除了说明文件，Agent 还需要能搜索符号、查看调用链、读取相关测试、理解依赖关系。只给它一个文件路径，让它猜周边代码，几乎必然写出不一致的实现。

最后是环境。Agent 需要一个能跑测试的沙箱：依赖版本固定，编译工具齐全，有超时和资源限制，不暴露生产凭据。

工作流：先计划，再动手

我见过效果最好的团队，都会让 Agent 先出计划，再改代码。

流程大概是：读 issue，确认验收标准；输出修改计划，包括要改哪些文件、为什么改、怎么测、有什么风险；人确认方向；开始改；跑测试；自查 diff；最后提交 PR。

计划这一步很关键。人在计划阶段拦截一个方向性错误，成本远低于 review 一个几百行的 diff。

改代码时也要有限制：优先最小可行修改，不相关的重构另开 PR，不自动升级依赖，不删除看起来没用但可能被外部引用的代码。

测试也不是越多越好。Agent 最该跑的是和改动相关的测试，而不是每次全量跑一遍。先根据改动的文件找依赖关系，选出受影响的测试集，再在 CI 里跑全量兜底。这样反馈快，也不容易因为无关的 flaky test 卡住。

我最在意的几个门禁

我不太相信“模型会自觉”。可合并的 PR 需要可执行的规则。

单 PR 的有效改动不要太大，超过几百行就该拆。CI 必须跑 lint、类型检查、单测和受影响模块的集成测试。安全扫描要查依赖漏洞和密钥泄露。公共 API 变更要同步文档。

还有两条我特别在意：

第一，测试文件要受保护。Agent 为了让测试通过，很容易去改断言，而不是修实现。除非 issue 明确要求改测试，否则测试 diff 要单独审查。

第二，依赖变更要单独审批。新增一个包、升级一个版本，看起来是小事，但可能带来 license、体积和安全问题。

翻车现场

我遇到过几次典型问题。

一次是幻觉 API。模型调用了一个不存在的参数，类型检查没覆盖到，运行时才报错。后来我们要求它先搜索定义再使用，关键接口必须提供示例。

一次是过度编辑。为了修一个样式问题，它把一个共享组件重写了，结果影响了另外三个页面。后来我们按目录设了写入白名单，大范围重构必须人工批准。

还有一次是测试作弊。它没修 bug，而是把失败断言改成了期望错误结果。CI 全绿，但问题还在。那次之后，我们把测试文件加进了保护名单。

这些问题的共同点是：它们都能通过“更严格的流程”避免，而不是靠“更聪明的模型”。

Issue 模板也值得改。把“期望行为、复现步骤、验收标准、相关日志、不能改的模块”做成固定字段，Agent 拿到的输入会稳定很多。很多 Agent 跑偏，不是因为它笨，而是因为 issue 本身写得含糊。

团队怎么接

AI Coding Agent 不是自动提交机器，它更像一个新同事。

所有 Agent 提交的 PR 要明确标注来源；reviewer 重点看意图、边界和测试，而不是逐行挑格式；issue 模板要写清楚验收标准；高风险模块，比如支付、权限、数据迁移，要求人工主导；定期复盘 Agent 的失败案例，反过来改仓库说明和门禁。

我现在衡量一个 AI Coding 项目是否成功，不看它一天能写多少行代码，而看它的 PR 合并率，以及 review 一个 PR 平均要花多久。

一次失败的 PR review

那个改了 37 个文件的 PR，我后来仔细看了一遍。

它的目标是修一个日期格式化的 bug。实际改动包括：重写了日期工具函数，顺带调整了三个页面的样式，升级了一个图表库，删了两个“看起来没用”的导出，还改了两条测试断言，让它们接受新的错误输出。

单独看每一处都不算离谱，合在一起就没法 review 了。你无法判断哪一部分是必要的，哪一部分是模型顺手改的；也无法确认测试改动是在适配新实现，还是在掩盖问题。

我把它关了，要求拆成三个 PR：一个只修日期 bug，一个单独升级依赖，一个处理样式。前两个很快合了，第三个被否了，因为样式改动其实不需要。

这件事之后，我们给 Agent 加了两条硬规则：单 PR 有效改动超过 400 行必须拆；测试文件的修改必须单独说明理由，否则不进入 review。

还有一条是依赖变更。新增或升级依赖要单独提 PR，附上许可证、体积和安全扫描结果。模型很容易为了省事引入一个包，但维护成本是团队来付的。

AGENTS.md 里到底写什么

这个文件不用长，但必须具体。

我会写清楚：项目分哪几个模块，各自负责什么；本地怎么装依赖、怎么起服务；测试、lint、类型检查分别用什么命令；提交信息和分支命名有什么约定；哪些目录不能动，比如生成的代码、数据库迁移、生产配置。

再加一段“已知的坑”：比如某个旧接口不能直接改，某个组件有兼容性问题，某个测试环境不稳定。这些信息人知道，模型不知道，写下来能省很多来回。

最后是 PR 规范：改动尽量小，测试要覆盖改动，依赖变更单独提。写清楚这些，比在 Prompt 里反复强调“注意代码质量”有用。

合并率比代码量重要

AI Coding 的瓶颈，正在从“生成代码”转向“建立信任”。

代码写得快不是优势，能稳定产出小而正确、可测试、可审查、可回滚的改动才是。仓库上下文、工作流和质量门禁这些基础工作，决定了 Agent 是团队的生产力，还是 review 的负担。