软件技术分享

关于电子游戏的方方面面

Codex：多文件重构时如何写清“完成定义”

作者

多文件重构先写完成定义：改哪些路径、测什么命令、禁止事项与验收清单；计划批准后再改，未观察证据不算完成。

要点

  • 完成定义＝可观察合同：Cookbook 要求每个 phase 写清验收标准、验证命令与必须记录的证据；计划中的命令不得写成“已经通过”（Iterating development workflows with Codex）。
  • 持久规则 vs 单次任务：仓库惯例、测试命令写进 AGENTS.md；本次目标、允许路径、非目标、验收清单写进提示或 phase 文件（AGENTS.md、Codex AGENTS 文档）。
  • Cursor 同向：复杂多文件改动先 Plan，列文件路径与步骤，你批准后再写；可存 .cursor/plans/（Agent best practices）。
  • 可抄六段式完成定义：目标｜允许改｜禁止改｜行为不变承诺｜验证命令｜停／升级条件。缺任一段，Agent 容易扩 scope。
  • 衔接本室《先读再改开工清单》《测试驱动改 bug》：开工管顺序，TDD 管单 bug 红绿；本稿管重构批次的“怎样算做完”。
  • 证据强度：Cookbook／AGENTS／Cursor Plan＝官方（高）；六段模板为编译可跟做（中高）；具体 CLI 菜单文案＝待核。

正文

场景

你对 Codex／Cursor Agent 说：“把认证模块重构一下，顺便整理相关文件。”它改了十几处：公共 API 形状变了、测试被跳过、锁文件也被动了，最后回一句“重构完成”。多文件场景最贵的不是模型不够聪明，而是你没有写清完成定义（Definition of Done）：改哪些文件、什么行为必须保持、跑哪条命令才算绿、什么情况下必须停下来问你。

下文给可粘贴的完成定义写法，适用于 Codex CLI 与 Cursor 里的 Agent／Codex；演示级“口头说重构好了”不算量产完成。

可跟做步骤／可抄工作流

证据强度：高（Cookbook＋AGENTS.md＋Cursor Blog）；UI 文案标待核。

1. 把“完成”拆成六段（单次任务提示里写全）

【目标】一句话：本次重构要达成的可观察结果（例：把支付重试逻辑抽到 shared/retry.ts，调用方行为不变）

【允许修改的路径】
- src/payments/**
- src/shared/retry.ts（可新建）
- tests/payments/**

【禁止修改／创建】
- package-lock.json／pnpm-lock.yaml
- .github/workflows/**
- 无关包目录；任何 major 依赖升级
- 未经询问扩大到【允许列表】之外

【行为不变承诺】
- 对外 API／CLI 参数／环境变量名保持不变
- 既有测试用例不得删除、skip、弱化断言（除非我书面同意并写明原因）

【验证命令（必须真实跑过并贴结果）】
1) 【包级】例如：pnpm test --filter payments
2) 【类型】例如：pnpm typecheck --filter payments
3) （可选）更广：pnpm test（仅当包级全绿后）

【完成时你必须交付】
1) 实际改动文件列表＋每文件一句话理由
2) 上述命令的观察输出（通过／失败摘录），禁止把计划里的命令抄成“已通过”
3) 若需扩 scope：先停，列出拟增路径与理由，等我回复“按计划执行”

Cookbook 的 phase 文件同样强调：In-scope／Non-goals／Acceptance criteria／Evidence that must be recorded／Approval gate——六段是消费端压缩版。

2. 持久层：AGENTS.md 只写“每次重构都成立”的纪律

根目录可抄短片段（按项目改命令）：

## Multi-file changes

- Prefer a written plan with paths before editing more than 3 files.
- Never mark work complete without running the verification commands
  listed by the user or in this file; record observed results.
- Do not delete, skip, or weaken tests to get green unless the user
  explicitly approves with a reason.
- Do not upgrade major dependencies or edit lockfiles unless asked.
- If scope must expand, stop and ask before editing new paths.

agents.md 说明：测试相关指令写进文件后，Agent 会尝试执行并修到绿；Codex 文档补充就近 AGENTS.override.md 覆盖与体积上限——规则宜短，细节放仓库内范例文件。

3. 多文件重构的推荐节拍（可日复）

  1. 只读摸底（见《先读再改》模板 A）：列出将受影响的文件与共享依赖，先不改。
  2. 写入完成定义：把六段贴进同一条提示，或写入 harness/build/phase-xx.md／Cursor Plan。
  3. 批准后再改：Cursor 用 Plan Mode（Shift+Tab，快捷键以界面为准）；Codex 先要“实施计划，等我说按计划执行”。
  4. 小批次：一次一个结构目标（抽模块／改名／移目录）；Cookbook 建议 phase 小到可独立验证。
  5. 验证门禁：包级测试 → 类型检查 → 必要时再全量；失败走 Review→Repair→Validate（《测试驱动改 bug》）。
  6. 收尾报告：diff 路径 ⊆ 允许列表；证据是观察结果不是计划原文。

4. 验收清单（Agent 自称完成后你点这七下）

1) 目标一句话是否仍然成立？

2) git diff --stat 是否落在允许路径内？

3) 禁止项（锁文件、CI、弱化测试）有无被碰？

4) 是否贴出真实测试／类型命令输出？

5) 对外行为承诺是否被破坏（API／旗标／配置名）？

6) 有无“顺手”的格式化全仓／重命名风暴？

7) 若中途扩 scope，是否经过你的二次批准？

任一项否 → 不合并，开新对话或回到计划改完成定义后再跑。

5. 可抄：从“模糊重构”改写成完成定义（对照）

模糊说法写成完成定义
重构认证模块允许 src/auth/**＋对应测试；抽出 session.ts；登录／刷新对外行为不变；pnpm test --filter auth 与 pnpm typecheck 须观察通过
整理一下目录仅移动 src/legacy/foo→src/foo；更新 import；禁止改逻辑；全量测试可后置，先跑 foo 包测
优化性能先定指标与基准命令；无基准则非本次完成定义，改为“增加基准测试文件且旧行为测试仍绿”

真实用户诀窍／反例

  • 诀窍：完成定义与允许路径写在同一条提示。 分两条发，后半常被模型“忘”。
  • 诀窍：禁止事项要写具体文件类型。 只写“别乱改”等于没写；点名锁文件／workflows／生成目录更有效。
  • 诀窍：证据＝观察。 Cookbook 写明：未跑过的验证不能当完成证据。
  • 诀窍：扩 scope 必须停。 重构时发现“顺便改类型基建”往往是事故起点。
  • 反例：一句话“重构整个项目／统一风格”。 无路径、无验证、无非目标＝默许全仓写入。
  • 反例：用全仓 format／全仓 lint 当第一完成定义。 格式交给本地工具与 CI；完成定义优先绑行为与测试。
  • 反例：为了绿而 skip 测试。 直接违反可抄 AGENTS 纪律与 TDD 篇。

适用边界

  • 本稿覆盖：本地仓库用 Codex／Cursor Agent 做多文件重构时的完成定义写法；不替代路径合同篇、终端审批篇、TDD 篇的专项流程。
  • Plan 快捷键、Cloud Agents 是否同等加载本地 AGENTS、某 CLI 子命令名：以当前产品界面与文档为准（待核）。
  • 超大 monorepo：在包级目录放就近 AGENTS.md／AGENTS.override.md，完成定义里写清工作目录与包级测试，避免只读了根 README。
  • 生产热修、数据迁移、密钥与部署：完成定义之外仍须独立审批；本稿不授权自动 push／发布。

【来源与编译】