Codex 实践指南：从任务说明到测试验收的完整工程工作流

先把任务写成可验证的工程合同

高质量任务说明不需要很长，但必须让执行者知道什么结果才算完成。一个实用结构是目标、上下文、约束、完成条件四部分。目标描述最终变化；上下文指出相关文件、错误日志或现有实现；约束规定兼容性、安全边界和不可修改范围；完成条件则给出测试命令与可观察结果。

• 目标：用户最终能看到或调用什么新能力
• 上下文：入口文件、相关模块、报错与复现步骤
• 约束：兼容版本、接口不变、禁止触碰的配置
• 完成条件：必须通过的测试、构建和人工检查

复杂任务先计划，再进入修改

当任务涉及多个文件、未知依赖或需要先调查时，先让 Codex列出短计划。计划的价值不是增加文字，而是暴露假设：它会修改哪些区域、按什么顺序验证、哪里可能需要回退。计划确认后再实现，可以减少做到一半才发现方向错误的情况。

对于范围很小且路径明确的修复，可以直接执行；对于架构调整、迁移和跨模块功能，则应把调查、实现、验证拆成独立阶段，并让每一步都有可检查的产物。

• 先定位真实调用链，不凭文件名猜测
• 先读取仓库规则与测试命令
• 把高风险改动拆成可独立验证的小步
• 出现新证据时更新计划，而不是机械照旧执行

修改过程中控制范围和噪声

工程任务最常见的隐患不是功能没写出来，而是顺手改动过多。要求 Codex 保持现有风格、复用已有抽象、避免无关格式化，能够让代码差异更容易审查。若工作区已经存在人工修改，也要明确这些变化属于现有状态，不能覆盖或回滚。

可以让 Codex 先说明准备修改的文件，再查看差异。如果一个小需求产生大面积改动，应暂停并重新判断是否存在更小的实现路径。

用测试、构建和差异审查完成闭环

“代码已经写完”不等于任务已经完成。验证应从最接近改动的测试开始，再逐步扩展到类型检查、构建和更广的回归测试。最后查看代码差异，确认没有调试输出、临时文件、凭据或意外生成物。

如果测试失败，应记录失败命令、关键错误和判断结果。不能运行某项测试时，也要说明缺少什么条件，而不是把未验证的状态当作成功。

• 运行与改动直接相关的单元或集成测试
• 执行类型检查、lint 或生产构建
• 检查 git diff 与工作区状态
• 汇总已验证内容、残余风险与后续动作

把重复经验沉淀成仓库规则

当同一种提示反复出现，例如固定测试命令、目录约定或发布检查，应把它写入仓库的 AGENTS.md 或项目文档。这样下次任务不必重新解释，也能让团队成员与 Codex 使用同一套完成标准。持续沉淀规则，比每次临时补充长提示更稳定。