Codex 处理长任务时，真正影响结果的通常不是提示词长度，而是上下文是否完整、任务能否拆分、每一步是否可验证，以及失败后能否快速恢复。一次性要求它完成整个项目，往往会造成约束遗漏、修改范围过大或测试无法定位。

本文整理一套可重复的工程流程，适用于跨文件修改、依赖迁移、模块重构和测试补全。

一、先做上下文检查

开始修改前，先让 Codex 完成四件事：

1. 读取项目目录与主要依赖；
2. 找出入口文件、配置文件和测试目录；
3. 复述现有约束与不可修改的边界；
4. 列出仍需确认的信息。

这一步的目标不是立即生成代码，而是确认它对项目结构的理解与实际仓库一致。

二、把大任务拆成可验证阶段

一个长任务可以按下面顺序拆分：

阶段	输入	输出	验证方式
需求确认	目标、限制、现状	任务清单	人工核对范围
方案设计	任务清单、代码结构	修改计划	检查依赖关系
小步实现	单一子任务	最小代码变更	单元测试
集成验证	多个已完成子任务	可运行版本	集成测试
收尾检查	差异、日志、测试结果	交付说明	代码审查

每个阶段只处理一个明确目标。前一阶段没有验证完成时，不进入下一阶段。

三、定义清晰的验收标准

“把代码优化一下”无法直接验证，可以改写成：

• 指定函数的圈复杂度下降；
• 新增边界条件测试；
• 保持现有公开接口不变；
• 静态检查无新增警告；
• 全量测试通过；
• 变更文件数量控制在约定范围内。

验收标准越具体，Codex 越容易判断任务何时结束。

四、让测试成为每一步的出口

建议按由小到大的顺序运行：

1. 与当前修改直接相关的单元测试；
2. 当前模块的测试集合；
3. 静态检查与类型检查；
4. 受影响模块的集成测试；
5. 项目全量测试。

如果第一层测试已经失败，应先定位原因，不要继续扩大修改范围。

五、保存可恢复的检查点

长任务中应保留以下信息：

• 当前完成的子任务；
• 已修改文件列表；
• 已运行的命令及结果；
• 尚未解决的错误；
• 下一步计划；
• 需要人工确认的决策。

即使任务被中断，也能从最近检查点继续，不必重新读取全部上下文。

六、并行任务怎样避免冲突

并行执行时，先按目录或模块划分所有权。两个任务不要同时修改同一个核心文件，也不要同时调整公共依赖。

比较稳妥的分工方式是：

• 一个任务处理实现；
• 一个任务补充测试；
• 一个任务检查文档和配置；
• 最后由单独步骤完成集成与审查。

并行的目标是减少等待，不是让修改范围失去边界。

七、API 工具调用要单独设计边界

当 Codex 需要调用外部 API 或内部服务时，应明确：

• 请求参数与返回结构；
• 超时和重试策略；
• 错误码处理；
• 日志中需要脱敏的字段；
• 幂等性要求；
• 测试环境与生产环境的隔离方式。

工具调用失败时，优先保留原始错误和关键上下文，不要用笼统的失败信息覆盖细节。

八、一个可直接复用的任务模板

目标

说明最终需要实现的可观察结果。

范围

列出允许修改和禁止修改的目录、文件与接口。

步骤

要求先分析，再给计划，然后小步实现并逐步验证。

验收

列出必须通过的测试、检查命令和行为结果。

输出

汇总修改文件、关键决策、测试结果与剩余风险。

九、常见失败模式

一次修改过多文件

先缩小到一个模块，验证后再扩大范围。

只生成代码，不运行测试

把测试命令写入验收标准，并要求返回真实结果。

上下文读取不完整

先列出它已读取的文件，再检查关键配置是否遗漏。

失败后从头开始

保留检查点和失败日志，从最近一次成功验证继续。

自动修改公共接口

将公开接口、数据结构和兼容性要求写成明确边界。

十、完成前的最终检查

• 任务目标是否全部满足；
• 是否出现未计划的文件修改；
• 单元测试、集成测试和静态检查是否完成；
• 是否保留临时调试代码；
• 文档与配置是否同步；
• 剩余风险是否明确记录。

这套流程的核心是：先建立共同上下文，再拆分任务，用测试控制每一步，最后通过检查点确保可恢复性。它不仅适用于 Codex，也适用于其他能够执行仓库级任务的编程代理。