8.0
热点
AI SCORE
编程提效2026-09-08 14:15
让AI编程代理提交可审查PR的实战指南
dev.to · AI#AI编程#Prompt技巧#工程实践
Editor brief · 编辑速览
通过提供清晰的问题描述、仓库说明和验收标准，结合测试要求和分支运行规范，可显著提升AI编程代理的PR质量。
简短回答：给 Agent 一个有边界的 issue、仓库级指令和明确的验收标准，然后要求它写测试、在打开 PR 之前跑通分支、对着清单审查 diff。
当任务看起来像一张正经的工程工单而不是模糊的请求时，Agent 的表现会更好。GitHub 的 Copilot 云端 Agent 指南指出，高质量的任务应包含清晰的问题描述、完整的验收标准，以及关于哪些文件可能需要改动的指引。指南还建议先在分支上研究和迭代，再打开 PR，而不是直接跳到 PR。
首先，按照你希望人类工程师阅读的方式撰写 issue。把问题陈述放在前面，然后列出你想要的行为、所涉及的文件或子系统，以及证明工作完成的验收标准。验收标准要足够具体，让另一个人无需追问就能验证。如果测试是完成定义的一部分，要说明需要哪种级别的测试，比如单元测试、集成测试还是端到端测试。
用仓库指令消除猜测。GitHub 文档中提到了 .github/copilot-instructions.md 文件用于仓库级指引，还有路径特定的指令文件以及 AGENTS.md 用于 Agent 工作流。把构建命令、测试命令、lint 规则、目录约定和任何合并要求放在那里。这样 Agent 就不会自己发明结构，也不会跳过项目正常的变更验证方式。
一个实用的 prompt 包含四个部分：改什么、不改什么、如何验证、输出应该包含什么。例如："给 API client 添加重试处理。不要改动 auth 流程。添加网络失败和超时的测试。用一个 commit message 打开分支来总结这个修复。"这个结构给 Agent 设定了边界，减少了无关改动，让审查更快。
把测试作为任务的一部分，而不是事后的期望。如果改动涉及业务逻辑，要要求在改动前会失败、改动后会通过的测试。如果改动涉及 UI 流程，要要求覆盖用户路径的测试和覆盖边界情况的测试。如果 Agent 无法干净地创建测试，这说明验收标准太松散，或者这个特性太大不适合放在一个 PR 里。
人们常犯的错误是要一个功能，然后只检查代码是否写出来了。那样的 PR 看起来完整但无法证明行为。一个可以审查的 PR 在一个地方同时展示实现、测试和验证步骤。GitHub 的文档指出，Copilot 在 PR 上的工作仍然应该被当作来自人类开发者的工作来对待，这意味着在合并之前通常需要评论、迭代和第二轮检查。
使用两步工作流。首先，让 Agent 研究代码库并在分支上提出实现计划。其次，让它做改动并添加测试，然后在打开 PR 之前运行测试套件。在这个节点上，隐藏的复杂性会暴露出来，比如一个共享的辅助函数、一个脆弱的 fixture 或者一个缺失的 mock。在 PR 之前捕获这些会让审查更短、diff 更小。
保持分支小。一个 PR 应该只做一件事，因为"可以审查"意味着审查者能在几分钟内理解意图，无需扫描无关代码就能验证结果。如果 Agent 试图同时解决两个功能，把工作拆成两个 ticket。这对 AI Agent 更重要，因为人类工程师会停下来开一个单独的分支，而 AI Agent 则很乐意一直做下去。
让验收标准可检查。一套好的标准应包含用户可见的行为、边界情况，以及验证方法。例如："当请求失败一次时，client 重试一次然后抛出原始错误。单元测试覆盖成功、重试和最终失败。npm test 通过。"这给了 Agent 一个终点线，也给了审查者一个快速确认改动完成的方式。
写下 Agent 应该运行的命令。如果仓库有构建步骤、格式化工具或特定的测试目标，把这些放在指令文件里，并在 issue 中重复最低验证要求。GitHub 特别建议告诉 Copilot 如何构建和测试项目，以及应该遵循什么标准。这不是多余的仪式，它是"一个 diff"和"一个可用的 PR"之间的区别。
一个好的审查循环很简单。让 Agent 总结它改了什么、添加了哪些测试，并指出哪些文件还需要人工关注。然后对照验收标准审查 diff，而不是只对着代码审查。如果分支测试通过但漏掉了一个标准，发回去做针对性的修复，而不是接受一次大面积重写。
如果希望这件事能持续稳定地运作，就要标准化模板。每个任务都应该包含标题、上下文、验收标准、测试期望、在范围内的文件，以及关于不在范围内的说明。每个仓库都应该包含 Agent 指令，解释如何构建、lint 和测试。每个 PR 都要链接回原始 issue 并提及验证步骤。这样就把 Agent 变成了一个可重复的贡献者，而不是随机 diff 的来源。
对于使用 GitHub Copilot 云端 Agent 的团队，当 issue 读起来像一个 prompt 时，工作流特别清晰。GitHub 说你可以把 issue 分配给 Copilot，让它研究仓库、创建实现计划，然后在打开 PR 之前在分支上进行迭代式的代码更改。这是输出可审查内容的正确顺序：先计划、再实现、第三验证、最后 PR。
如果需要一条一句话规则，用这个：不要问 AI coding agent 要代码，要它提供一个满足命名验收标准的已测试分支。代码是输出，但分支、测试和标准才是让输出可审查的东西。这三样任何一样缺失，PR 就没有完成。
在 DevConnect 上，当人们用测试帮助换取应用质量时，同样的纪律也很重要，而且平台本身在每个步骤都是免费使用的。你可以在这里阅读项目上下文：https://devconnectplatform.com?ref=devto
如果 Agent 仍然产生弱的 PR，通常的原因不是模型。常见的原因是任务太宽泛、指令缺失，或者验收标准描述的是意图而不是证据。先把工单形状修正，然后再要代码。
目标： 给 API client 添加指数退避。
范围： src/api/client.ts 和 src/api/client.test.ts 中的测试。
验收标准： client 在瞬时网络故障时重试一次，在最终尝试后抛出原始错误，并记录一次重试事件。
验证： 添加成功、一次重试和最终失败的测试。在打开 PR 之前运行项目测试命令。
读 diff，不只是总结。确认测试实际执行了改动的路径。确认没有编辑无关文件。确认分支在 PR 描述或清单中包含了项目的常规命令。如果这些都有了，PR 通常就可以进行人工审查了。
常见的失败模式是 PR 改了代码但验证很模糊。另一种失败是测试只证明了新分支的代码执行过一次，而真实行为在边界情况下仍然会出问题。第三种失败是大型的混合 PR，把重构、功能工作和清理混在一起。在进入审查之前就把这些拆开。
告诉 Agent 成功长什么样，告诉它如何证明成功，在分支证明成功之前不要打开 PR。这是最短的通往可审查工作的路径。
不应该。先让它研究、计划和做改动在分支上，等分支测试通过且 diff 干净之后再打开 PR。
用行为、边界情况和证据来说。说明应该发生什么、不应该发生什么，以及哪些测试或命令必须通过。
把仓库级指引放在 .github/copilot-instructions.md，路径特定规则放在 .github/instructions/*.instructions.md，共享的 Agent 工作流规则放在 AGENTS.md。
缩小工单范围，命名范围内的文件，说明不在范围内的内容。小分支更容易审查，也更容易修正。
最初发表于 devconnectplatform.com，并在那里保持更新。