AI Agent / 系统课时
评审交付与团队复盘
评审交付与团队复盘
项目结束不等于可以合并。本课把最终差异审查、测试证据、拉取请求说明、Codex 使用成本和团队复盘收束为一套交付门禁,让每次合并既能解释为什么改,也能留下下一轮流程优化依据。
学习目标
- 用差异、测试和 Codex review 形成最终交付证据
- 写出能让评审者快速验收的拉取请求说明
- 用成本、返工与缺陷信号推动团队流程改进
先建立可审计的交付证据
交付前先回答四个问题:改了什么、为什么改、怎么验证、还剩什么风险。代码数量不是证据,能复现的 diff、测试结果和明确的边界才是。建议先冻结目标分支和当前提交,再执行统一的终检命令。
下面示例默认目标分支为 main,也可以把实际基线分支作为第一个参数传入。git diff --check 一旦发现空白错误会直接失败,只有基础差异检查通过后才进入 Codex 评审。
set -euo pipefail
BASE="${1:-main}"
git status --short
git diff --check
git diff --stat "$BASE"...HEAD
git log --oneline "$BASE"..HEAD
codex review --base "$BASE"预期输出
<OPTIONAL_WORKTREE_STATUS>
<DIFF_STAT_AGAINST_BASE>
<COMMITS_SINCE_BASE>
<CODEX_REVIEW_OUTPUT>git diff --check 成功时通常不输出内容;其余结果取决于当前仓库。Codex review 的职责是提供第二视角,不是替代测试或人工批准。对每个发现都要判断是否成立、是否阻塞合并,以及修复后是否需要补测试。

用 Codex 做第二视角审查
最终评审最好同时包含机器检查、Codex 审查和人工判断。机器检查负责格式、类型、测试等确定性规则;Codex 更适合寻找遗漏的边界条件、跨文件影响和不一致;人工评审负责业务取舍、架构约束和是否接受剩余风险。
codex review --base <BRANCH> 适合按目标分支审查整组变更。若只想看尚未提交的工作区,可以使用 --uncommitted;若只审查一个提交则使用 --commit <SHA>。这些目标应单独选择,不要把多个目标参数混在一次 review 中。
评审发现要去重并分级。已经被测试证明不存在的问题不应重复阻塞;真正影响正确性、安全性、兼容性或数据完整性的发现必须在合并前解决。对“暂不修复”的项要留下原因和后续跟踪入口,否则它只是被遗忘,而不是被接受。
把 PR 说明写成验收说明
好的拉取请求说明不是提交日志的复制,而是给评审者一条最短验收路径。正文至少应覆盖“问题与目标”“关键变更”“验证证据”“风险与回滚”四部分;涉及配置、迁移或外部依赖时,再补部署条件和观察指标。
关键变更只写会影响行为的决策,例如替换了哪条数据流、为什么保留兼容层、哪些文件只是机械调整。验证证据应写具体命令和结果范围,而不是笼统写“已测试”。若 Codex review 找到并促成了重要修复,可以在说明中记录该风险已如何关闭,但不必粘贴整段会话。
把成本换算成工程信号
成本复盘不要只看“用了多少”。先从团队实际可用的 Codex 使用记录中取得统一口径,例如任务数、模型或推理设置、token 或 credits、可见的费用、并发任务数,再和交付结果关联。不同计划和计费方式可能不同,因此复盘应使用组织真实记录,而不是把一份固定单价写进流程。
| 指标 | 计算口径 | 用来判断什么 |
|---|---|---|
| 单次有效交付成本 | 周期内 Codex 成本 ÷ 验收并合并的交付数 | 相同任务类型是否越来越高效 |
| 重大返工率 | 需要大幅重做的任务 ÷ 已完成任务 | 提示词、上下文或任务拆分是否有问题 |
| 评审命中率 | 被人工确认的有效发现 ÷ 评审发现总数 | review 是否产生足够高信号 |
| 首次验证通过率 | 首次运行完整验证即通过的任务 ÷ 已完成任务 | 环境、测试和约束是否充分 |
比较成本时尽量保持任务类型、模型、推理强度和速度设置可比。更低的 token 消耗不一定更便宜:如果它带来更多重试、人工修补或线上缺陷,整体工程成本反而更高。团队真正要优化的是单位有效交付的总成本和风险。
把复盘结论写回流程
复盘只产生“下次注意”没有价值。每个高频问题都应落到一个可执行载体:项目约束写入 AGENTS.md,可自动判断的问题变成测试或 CI 门禁,重复操作沉淀为脚本或 Skill,环境差异写入初始化配置,外部工具问题进入 MCP 或插件治理,无法自动化的风险进入 Runbook。
改进清单最好包含触发条件、负责人、完成证据和截止点,并优先处理“高频且高影响”的问题。下一次项目开始时,检查这些改进是否真的改变了 Codex 的输入、权限、验证或评审流程;只有能在后续任务中被复用的复盘结论,才算完成了工程治理闭环。