Codex使用手册(九)PR审阅模板

Codex 实战手册 · 第 09 篇 · 场景实操

系列合集：Codex 实战手册 · 第 09 篇 · 场景实操

上一篇：别再每次手动验收——把 Git 检查收进项目级验证 Skill

下一篇：接手陌生仓库：30 分钟完成摸底、计划和第一个低风险修复

图源说明：文内模拟 Pull Request 页面、目录图、终端输出和审阅卡均为 AI派生码农自制示意图，不使用真实仓库或审阅记录。

···

开始前，先看 10 秒任务卡

你将完成：在一个已获授权的 Git 测试仓库中，创建 .github/pull_request_template.md，把 Agent 的证据包整理成任务、改动、验证、风险、未执行动作五段审阅说明。

预计用时：20 分钟。

需要准备：已安装 Git；一个自己拥有或已获授权的 Git 测试仓库；第 08 篇的 verify-change Skill，或一份已有的变更证据包。

本篇边界：只创建模板与模拟说明；不创建真实 Pull Request，不提交、不推送、不合并、不发布、不部署。

场景很常见：Agent 帮你修完一个小 Bug，给出一段已修复，测试通过。你看得懂，但你的同事接手时不知道它改了哪些文件、测了什么、还有什么没做。于是审阅变成来回追问，而不是一次完整的判断。

真正可审的 Pull Request，不需要长文大论。它只需要把证据放到团队最习惯看的位置：为什么改、改了什么、如何验证、风险在哪里、还有什么没有做。模板负责提醒，证据包负责填充，人负责最后决定。

关键判断：第 08 篇的 verify-change Skill 让证据稳定产出；本篇的 Pull Request 模板让证据稳定交接。Skill 不提交代码，模板也不自动批准，两者都把高影响决定留给人。

图 01：Pull Request 模板文件地图

一、先选对位置：模板应该放在仓库里

GitHub 支持把单一 Pull Request 模板放在仓库根目录、docs 目录或 .github 目录。为了让协作配置集中，本文使用 .github/pull_request_template.md。当模板已经进入仓库默认分支后，贡献者创建 Pull Request 时会在正文里自动看到它。

先创建目录。这个动作只会创建一个协作说明目录，不会发起任何网络请求。

mkdir -p .github

然后创建模板文件。

touch .github/pull_request_template.md

你应该看到什么：仓库中出现 .github/pull_request_template.md。它和代码一样可以被团队审阅、版本控制和持续改进。

二、第二步：模板只保留五段，审阅才会真的发生

第一段：任务：用一句话说明要解决什么问题，并关联已知的任务或问题编号；没有编号也要写清业务或技术目标。

第二段：改动：列出关键文件和重要变化，不把完整 diff 再复制一遍。审阅者需要的是哪里变了，为什么变。

第三段：验证：记录证据包里已经跑过的检查、测试和人工验证；如果只做了 diff check，也如实写出来。

第四段：风险与回滚：说明哪些边界没有覆盖，哪些配置或依赖值得额外看；如果没有设计回滚，也应该诚实写明。

第五段：未执行动作：明确本次没有提交、推送、发布或部署；即使准备好了合并，也让审阅者在看完差异和说明之后自行决定。

GitHub 的官方建议中，模板可以要求贡献者提供相关 issue、变更说明与负责审阅的人。审阅者则会围绕提交、文件变更和 diff，提交评论、批准或请求修改。

图 02：可审阅的 Pull Request 五段模板

三、第三步：让 Agent 只填证据，不替你下结论

有了模板后，可以把第 08 篇生成的证据包交给 Agent，让它按五段结构整理说明。提示词要写清边界：只依据已有证据填写，不补造测试结果，不创建 Pull Request，不提交、不推送。

推荐工作说明：读取当前变更证据，将其整理为 Pull Request 五段说明；未知项标记为未验证，不要猜测；最后停下，等待人工审阅。

这一步的价值，是减少转写和遗漏，而不是让 Agent 假装审阅者。它可以汇总范围、质量检查和关键变化，但不能替团队选择批准还是请求修改。

图 03：模拟 Pull Request 页面与人工审阅终点

四、第四步：提交前先做一次模板自检

任务清楚吗：读者能否在十秒内说出这次改动要解决什么？

改动可追吗：关键文件和变化是否能对应到 diff？

验证如实吗：是否只写了实际执行过的检查？

风险露出了吗：有没有计划外目录、未跟踪文件、依赖变化或未覆盖边界？

人还在环吗：模板最后是否明确评论、批准、请求修改由人提交？

这五个问题通过，才说明模板帮助了审阅；如果模板变成一串没有内容的勾选项，反而会给团队制造已经审过的错觉。

五、三种常见错误

错误一：把模板当成自动批准理由。模板填满不代表改动正确，也不代表权限和发布风险已经被接受。

错误二：让 Agent 编写不存在的测试结果。任何没有运行过的验证都应该标记为未验证，而不是被润色成通过。

错误三：把真实密钥、内部地址、客户数据或生产截图写进模板。Pull Request 文本会被协作者看到，应只保留审阅需要的最小信息。

六、保存这张 PR 审阅五问卡

图 04：PR 审阅五问卡

这次解决什么：任务和边界是否清楚？

改了哪些关键点：文件和行为变化是否能对应 diff？

怎么验证：哪些命令、测试或人工检查真实执行过？

还有什么风险：哪些没有验证、需要额外注意或可能回滚？

谁来决定：评论、批准和请求修改是否由有权限的人完成？

今天的最小作业：在一个 Git 测试仓库创建 .github/pull_request_template.md，用普通文字写下任务、改动、验证、风险、未执行动作五段。再把第 08 篇的一份证据包填进去，但不要创建真实 Pull Request。

下一篇预告：当你拿到一个陌生仓库，第一步不是直接让 Agent 改代码。下一篇用 30 分钟完成目录、规则、验证入口和第一个低风险修复的摸底计划。

风险提示：只在你拥有或已获授权的仓库中创建和使用模板。不要把密钥、令牌、内部地址、客户数据、生产配置或真实审阅记录放进模板、截图或提示词；创建、提交、推送、合并、发布和部署均由有权限的人在理解影响后自行决定。

资料来源

GitHub Docs：Creating a pull request template for your repository。

GitHub Docs：Reviewing proposed changes in a pull request。

标签：Codex；GitHub；Pull Request；AI 编程；代码审查；Agent 工作流；开发者工具；Git。