软件技术分享

关于电子游戏的方方面面

Codex：用测试驱动让 Agent 改 bug 的工作流

作者

先写会失败的回归测试并展示失败输出，再最小修复、再跑验证；AGENTS.md 写清红绿重构纪律，Review→Repair→Validate 闭环，禁止为过测而弱化测试。

要点

  • OpenAI Cookbook Iterating development workflows with Codex：用 AGENTS.md 作持久指引；phase／PROMPTS 约定里反复出现 red → green → refactor → verification（红＝先见失败；绿＝最小实现过测；重构保持行为；验证要有观察证据）。
  • Cookbook Build iterative repair loops with Codex：把代理改动拆成 Review（只找问题不改）→ Repair（按发现做小改）→ Validate（跑检查，失败变下一轮输入）；结构化交接，避免“改完就算完”。
  • 可抄 AGENTS.md 纪律：任何 bug 先写／补回归测试并展示失败输出，再最小修复，再跑相关＋必要全量；勿改／跳过／弱化失败测试除非用户明确同意。
  • 可抄提示词链：复现 → 隔离 → 诊断（可单独一轮）→ 最小修复 → 验证（含必要时 revert 证明测试真测到该 bug）。
  • 社区二手（developertoolkit／codexskills 等 TDD 说法）：一次只盯一个失败测试；勿开 watch mode 干扰；勿写成 OpenAI 官方产品功能名。--worktree／/worktree 等 CLI 开关以你本机 codex --help 为准（待核；已打开的 cookbook 页未写死）。
  • 证据强度：红绿重构与 Review／Repair／Validate＝Cookbook 官方（高）；社区 TDD skill 细节＝二手（中）；具体 CLI 开关名＝待核（低）。

正文

场景

你对 Codex 说“这个 bug 修一下”。它改了三处文件，自称好了——你一跑，原复现还在，或测试被删／被跳过／断言被改松。测试驱动（TDD：先有失败测试再写刚好够用的修复）不是仪式，而是给 Agent 一条可验证的完成定义：没看到红，就不许宣称绿。

下文以 Codex CLI／本地仓库 Agent 为主，步骤可复现；演示级“口头说测过了”不算量产完成。

可跟做步骤／可抄工作流

证据强度：高（两篇 OpenAI Cookbook，核验日 2026-10-31）；社区 CLI 开关标待核。

  1. 把 TDD 写进 AGENTS.md（持久，少靠临场叮嘱）

可抄片段（按项目测试命令改括号内容）：

## Bugfix (test-first)

When fixing any bug:

1. Reproduce first. Quote the failing command and the exact failure output.
2. Add or extend a regression test that fails for the right reason **before**
   changing production code. Show the red output.
3. Make the **smallest** production change that turns that test green.
4. Re-run the focused test, then the agreed broader suite
   (e.g. `npm test` / `pytest` / project script). Record observed results.
5. Do **not** delete, skip, `@ignore`, or weaken failing tests to get a green
   bar unless the user explicitly approves and the reason is documented.
6. Prefer one failing test at a time. Do not start the next bug mid-fix.

Cookbook 强调：AGENTS.md 可选但会被 Codex 当作持久仓库指引；把测试标准、边界、验证命令写清楚，比每次聊天重复更稳（亦见本室《Codex 项目规则》系列）。

  1. 单 bug 提示词链（可抄，建议分轮）

轮 A｜复现与隔离（只读优先）

Read AGENTS.md and the relevant tests. Do not edit production code yet.

Bug report:
【现象／复现步骤／环境】

Tasks:
1) Reproduce with an exact command.
2) Isolate the smallest failing surface (file／function／input).
3) Stop with: repro command, failure excerpt, suspected locus, and
   whether a regression test already exists.

轮 B｜诊断（仍可不改生产代码）

Using the repro above, explain the likely root cause in ≤10 lines.
List 1–3 fix options ranked by blast radius. Do not implement yet.

轮 C｜红→绿（允许改测试＋最小生产修复）

Implement test-first:
1) Add/adjust ONE regression test; run it; paste the red failure.
2) Apply the minimal production fix.
3) Run the same test (must be green) and 【项目约定的更广命令】.
4) Summarize diff paths + observed pass/fail. No commits unless I ask.

轮 D｜验证加固（可选）

Prove the test catches the bug: temporarily revert only the production fix
(keep the new test), show the test fails again, then restore the fix and
re-green. Do not weaken assertions.
  1. 套上 Review → Repair → Validate（多轮修复时）

Cookbook 修复闭环的用法（文档／代码均可类比）：

– Review：只产出结构化问题清单，不改文件。

– Repair：按清单做最小编辑；不宣称已通过验证。

– Validate：跑你信任的检查（单测、类型、脚本）；失败条目变成下一轮 Repair 的输入。

停条件：验证通过／达到最大轮次／delta 不再变化／需要人工决策——四者任一即可停，避免无限空转。

  1. Phase／PROMPTS 里把红绿写进验收（中大型改动）

iterating-development cookbook 要求 phase 计划含：最小有意义的失败检查（red）、刚好够用的实现（green）、行为不变的重构、以及真实跑过的验证命令与证据——计划中的命令不得被写成“已经通过”。

  1. 人工门禁 checklist（Agent 自称完成后你点这五下）

1) 是否贴出过修复前失败输出？

2) 新测试是否针对该 bug 的回归，而不是无关绿条？

3) 生产改动是否明显大于“刚好够用”？（过大就拆）

4) 有没有 skip／删断言／改测试去就实现？

5) 更广测试或约定脚本是否实际跑过并记录？

真实用户诀窍／反例

  • 诀窍：红输出是门票。 没贴失败日志的“已修复”，默认不合并。
  • 诀窍：一次一个失败测试。 社区 TDD 习惯与 cookbook“小 scope 相位”一致；并行多红容易改飞。
  • 诀窍：修复与验证分相。 Review／Repair／Validate 分开，Agent 更难“写到哪算哪”。
  • 诀窍（二手社区）： 避免长时间 watch mode 干扰单次红绿观察；以一次命令一次结果为准（非官方产品名，标二手）。
  • 反例：先改代码再补测试。 常变成“测实现”而非“锁 bug”；回归易假绿。
  • 反例：改断言或删测试换绿。 直接违反可抄 AGENTS 纪律；除非你书面同意并记录原因。
  • 反例：把计划里的验证命令抄进完成报告。 Cookbook 明确：未跑过就不能当证据。

适用边界

  • 本稿覆盖：本地仓库用 Codex 做 bugfix 的测试优先工作流；不保证某一 Codex CLI 版本的子命令／TUI 斜杠指令长期不变。
  • --worktree／/worktree 等：社区文有写，已核 cookbook 页未写死 → 使用前以本机帮助为准（待核）。
  • 无测试基建的遗留项目：先补最小复现测试再修；不要假装“重构完全程”却无可观察验收。
  • 生产热修、涉密、不可逆数据操作：保持审批／沙箱纪律（见《终端命令审批》）；TDD 不替代人工确认。
  • 社区 skill 名（如某 “TDD skill”）不是 OpenAI 官方功能开关，正文仅作二手习惯编译。

【来源与编译】

  • Iterating development workflows with Codex｜OpenAI Cookbook｜https://developers.openai.com/cookbook/examples/codex/iterating-development-workflows-with-codex｜核验日 2026-10-31（AGENTS.md；red/green/refactor/verification；phase 验收与证据）
  • Build iterative repair loops with Codex｜OpenAI Cookbook｜https://developers.openai.com/cookbook/examples/codex/build_iterative_repair_loops_with_codex｜核验日 2026-10-31（Review→Repair→Validate）
  • 本室衔接：《Codex 项目规则文件踩坑》《终端命令审批与危险操作》
  • 社区二手（非官方产品名）：developertoolkit／codexskills 等“先写失败测试再修／一次一红”习惯编译｜核验日 2026-10-31
  • 本文说明：可抄 AGENTS 片段与分轮提示词；未宣称某 CLI 开关为官方写死功能；worktree 文案标待核。