Debugging, review, and refactoring | Codex principles and daily practice

The reviewed guide body for this track is currently maintained in Chinese.

预计阅读时间: 17 分钟

Codex 在调试和重构中的价值，来自它能快速连接错误现象、代码路径、测试结果和最小修改。但这类任务风险也高：如果没有证据，它可能改掉症状而不是根因；如果没有边界，重构可能变成无关大改。

这一篇讨论三类高频工作：修 bug、做 review、做重构。

调试：先建立证据链

不要一上来让 Codex “猜哪里错了”。更好的指令是：

请先基于错误日志和相关代码建立根因假设，列出你要验证的证据，再开始修改。

调试证据一般来自：

Codex 应该先把这些证据串起来，再选择修复点。

1. 复现问题：确认错误能稳定出现。
2. 缩小范围：找到入口、调用链和状态变化点。
3. 建立假设：说明为什么这里可能是根因。
4. 最小修改：只改根因相关位置。
5. 防回归：补测试或至少补可重复检查。
6. 复测：确认原问题消失，附近行为不退化。
7. 汇报：说明根因、修复、验证和残余风险。

如果无法复现，Codex 应该说“没有复现成功”，而不是直接给一个看起来合理的修复。

让 Codex review 时，提示应该更像代码审查任务，而不是让它夸改动：

请按代码审查方式检查当前 diff。
优先找 bug、回归、遗漏测试、边界条件和安全风险。
先列发现，按严重程度排序，附文件和行号。

好的 review 输出应该包含：

不要把格式、偏好和命名小事放在严重逻辑问题前面。真正有价值的 review 是保护行为。

重构的第一原则是行为不变。你可以这样要求 Codex：

请先写出这个重构必须保持不变的行为，再提出小步计划。
每一步完成后运行相关测试或类型检查。

常见不变性包括：

如果无法证明行为不变，重构就应该缩小。

这些信号说明需要停下来重新规划：

Codex 很擅长做机械重构，但机械重构必须有边界。

如果已有测试不足，可以让 Codex 先补一条 characterization test，也就是先记录当前行为：

请先补一个描述当前行为的测试，不改变生产代码。测试通过后再做重构。

这样重构前后可以对比。对于没有测试框架的项目，也可以用构建、快照、curl、截图或脚本输出来建立轻量保护。

Codex 完成一轮修改后，最好让它自己进入 review 模式：

请检查你刚才的修改，重点看：
- 是否有未同步的英文/中文路由。
- 是否破坏 sitemap/canonical。
- 是否遗漏移动端。
- 是否误改无关文件。
- 是否需要文档记录。

这一步常常能发现“实现完成但产品契约漏掉”的问题。

现象：
<错误或截图>

复现：
<步骤>

约束：
- 先定位根因，不要直接猜修复。
- 只做最小改动。
- 补能防回归的测试或检查。
- 解释验证结果。

请 review 当前未提交修改。
优先级：
1. 行为回归。
2. 数据、权限、安全和部署风险。
3. 缺失测试或验证。
4. 可维护性问题。

请用文件/行号给发现；如果没有发现，也说明剩余风险。

请重构 <模块>，目标是 <目标>。
要求：
- 先列出必须保持不变的行为。
- 拆成小步。
- 不改无关视觉/文案/API。
- 每一步后运行相关检查。