2026 ChatGPT Pro + Codex 高阶开发教程：AGENTS.md、Worktree 与自动测试闭环

更新时间：2026 年 7 月 6 日。本文是一篇 Codex 工程实践教程，重点介绍项目指令、任务隔离、GPT 模型分工、自动验证和代码审查。

很多开发者使用 GPT 辅助编程时，工作流仍然是：复制报错、粘贴代码、获取一段建议，再手动把修改搬回项目。

这种方式适合解释语法，却没有充分利用 Codex 的 Agent 能力。Codex 可以进入真实工程环境，读取仓库、搜索调用关系、修改文件、执行命令、运行测试，并根据失败结果继续迭代。

一套可用于真实项目的 Codex 工作流应该是：

项目规则 → 任务定义 → 隔离工作区 → 代码修改 → 自动验证 → diff 审查 → 交付

本文将从零搭建这条流水线，并讨论其中最容易被忽略的工程细节。

---

一、Codex 工程工作流的核心结构

Codex 不是单纯的代码生成器。一次完整任务通常包含七个阶段：

1. 读取项目级指令；
2. 定位与任务相关的文件；
3. 建立根因分析或实现计划；
4. 在受控范围内修改代码；
5. 运行测试、类型检查和 lint；
6. 根据失败结果继续修复；
7. 输出可供人工审查的 diff 与验证证据。

其效果可以粗略表示为：

任务完成质量 = 模型推理能力
             × 上下文准确度
             × 工具执行能力
             × 验证完整度
             × 权限边界

如果仓库没有测试、任务没有边界、项目规则只存在于开发者脑中，模型能力再强也难以稳定交付。

---

二、选择合适的 Codex 入口

Codex 提供 App、CLI、IDE 扩展和 Web 等入口。它们连接的是同一类工程能力，但适合的操作节奏不同。

入口	典型用途
Codex App	多任务管理、Worktree、diff 审查与可视化工作流
Codex CLI	终端优先的本地仓库、构建、测试和脚本任务
IDE 扩展	阅读代码时进行局部分析和修改
Codex Web	连接 GitHub 仓库并委托云端任务

一个任务最好只设置一个主入口。例如：

• 在 IDE 中定位问题后，把完整修复交给 Codex App；
• 构建或迁移任务在 CLI 中完成；
• 可以独立运行的仓库任务交给 Worktree；
• 最终回到本地 IDE 审查和调试。

频繁在多个入口重复同一任务，会导致上下文、分支和修改状态难以追踪。

---

三、使用 AGENTS.md 固化项目规则

提示词适合描述当前任务，AGENTS.md 适合保存长期工程约束。

OpenAI 官方文档说明，Codex 会在开始工作前读取 AGENTS.md。指令可以分为全局、仓库和子目录多个层级；越靠近当前目录的规则越具体，可以覆盖更上层的通用规则。

1. 初始化项目指令

在 Codex App 中可以运行：

/init

该命令会生成 AGENTS.md 脚手架。生成后应根据真实项目补充架构、命令、限制条件和完成标准。

2. 一个可直接修改的 AGENTS.md

# Repository instructions

## Architecture
- `apps/web`：页面、组件与前端状态
- `apps/api`：HTTP 接口、鉴权和参数校验
- `packages/domain`：领域逻辑，不依赖 Web 框架
- `packages/db`：数据库访问与迁移

## Commands
- 安装依赖：`pnpm install`
- 单元测试：`pnpm test`
- 类型检查：`pnpm typecheck`
- 代码检查：`pnpm lint`
- 完整验证：`pnpm verify`

## Change rules
- 保持公开接口向后兼容
- 不修改任务范围之外的文件
- 不删除、跳过或放宽失败测试
- 不提交 `.env`、密钥、日志和构建产物
- 新增生产依赖前必须请求确认
- 数据库变更必须包含可回滚迁移

## Completion criteria
- 解释根因或实现思路
- 列出修改文件及原因
- 报告实际执行的验证命令与结果
- 明确未覆盖风险

3. 为敏感目录设置覆盖规则

例如支付模块可以创建：

services/payments/AGENTS.override.md

# Payments service rules

- 金额必须使用整数最小货币单位，禁止浮点数
- 修改状态机后必须执行 `make test-payments`
- 不允许修改生产支付配置或轮换密钥
- 扣款、退款和对账逻辑必须等待人工审查

Codex 会从仓库根目录向当前目录合并指令。这样既能复用全局规范，又能给鉴权、支付、数据库等高风险模块设置更严格的边界。

4. 验证指令加载结果

可以运行只读检查：

codex --ask-for-approval never "Summarize the current instructions."

如果结果不符合预期，检查以下项目：

• Codex 是否从正确的仓库目录启动；
• AGENTS.md 是否为空；
• 上级目录是否存在 AGENTS.override.md；
• 当前 CODEX_HOME 是否指向其他配置目录；
• 指令文件是否过长并被截断。

---

四、把需求转换为可执行任务

下面这种任务缺少工程约束：

帮我优化认证模块。

Codex 需要的是可验证目标。推荐使用五段式结构：

任务：修复刷新令牌并发请求导致重复签发的问题。

现象：同一个 refresh_token 被并发提交时，
服务端可能签发多个有效 access_token。

目标：同一个 refresh_token 只能成功轮换一次，
后续请求保持现有鉴权失败响应。

范围：只修改认证服务、令牌存储层和相关测试。

约束：
- 不改变公开接口字段；
- 不新增生产依赖；
- 不降低安全检查；
- 数据库修改必须向后兼容。

验证：
- 新增并发轮换测试；
- 执行认证模块单元测试；
- 执行类型检查与 lint；
- 报告剩余风险。

推荐的分阶段提示词

第一阶段先不要修改文件。

请定位请求入口、令牌状态存储、并发窗口和现有测试，
输出根因分析、相关文件和最小修改计划。

计划确认后再实现。修改范围保持最小，不处理无关问题。

实现后运行最相关测试。如果测试失败，分析失败原因并继续修复。
最后运行类型检查和 lint。

最终输出：根因、修改文件、验证结果和未解决风险。

“先分析、再实现、后验证”比一句“直接修好”更容易审查，也便于在高风险任务中及时纠正方向。

---

五、使用 Git Worktree 隔离并行任务

Codex App 可以通过 Git worktree 创建隔离工作区。每个 Worktree 都有独立的文件副本，同时共享仓库的 Git 元数据，因此多个任务可以在不同分支上下文中运行。

适合放入 Worktree 的任务

• 修复彼此独立的 Bug；
• 为不同模块补充测试；
• 进行依赖兼容性验证；
• 执行不影响本地开发目录的重构；
• 在后台运行耗时构建。

不适合直接并行的任务

• 多个任务同时修改同一个核心文件；
• 数据库迁移存在严格顺序；
• 多个任务依赖同一个不可并行的本地服务；
• 需求尚未拆分，任务之间存在隐藏依赖。

Codex App 中的操作流程

1. 新建线程时选择 Worktree；
2. 选择任务的起始 Git 分支；
3. 提交范围明确的任务；
4. Codex 创建隔离 Worktree 并执行；
5. 在 Worktree 中运行测试和检查；
6. 使用 Handoff 将任务移回 Local，或直接在 Worktree 中创建分支；
7. 人工审查 diff 后再提交。

Worktree 解决的是文件和分支冲突，并不会自动解决业务依赖冲突。因此并行之前仍需确认任务边界。

---

六、建立自动测试闭环

建议为仓库提供统一验证命令：

{
  "scripts": {
    "verify": "pnpm test && pnpm typecheck && pnpm lint"
  }
}

然后在 AGENTS.md 中增加：

- 修改完成后必须运行 `pnpm verify`
- 完整验证耗时较长时，先运行受影响模块测试
- 不得通过删除测试、降低断言或关闭检查制造通过结果
- 无法运行的检查必须说明阻塞原因和替代证据

标准验证循环

修改代码
  ↓
运行相关测试
  ↓
失败 → 读取错误 → 定位原因 → 最小修复 → 重新测试
  ↓
通过
  ↓
类型检查 + lint + diff 审查
  ↓
人工批准

审查测试结果时要检查什么？

• 新测试能否在旧实现上失败；
• 是否真正覆盖任务描述中的触发条件；
• 是否删除或跳过原有测试；
• 是否把严格断言改成宽松判断；
• 是否吞掉异常或关闭类型检查；
• 是否只修改测试数据，而没有修复生产逻辑；
• 测试输出是否来自实际执行，而不是模型推测。

---

七、按照任务类型分配 GPT 模型

不同任务对推理深度、延迟和上下文需求不同。可以采用分层策略：

任务类型	模型策略
架构分析、疑难根因、高风险重构	使用 GPT-5.5 等强推理模型
常规功能、测试修复、跨文件执行	使用 Codex 当前推荐编码模型
文件定位、简单改名、格式整理	使用 GPT-5.4 mini 等较小模型
关键结论	模型分析后必须通过测试或人工审查验证

模型切换的原则不是单纯追求更强，而是把推理资源放在真正困难的步骤上。

例如一次迁移任务可以拆为：

1. 强模型分析兼容性和迁移风险；
2. 编码模型执行跨文件修改；
3. 较小模型整理日志和失败用例；
4. 编码模型根据测试结果继续修复；
5. 人工完成最终架构与安全审查。

---

八、对最终 diff 进行工程审查

Codex 报告“完成”不等于可以合并。最终至少检查五类风险。

1. 修改范围

• 是否修改了任务之外的文件；
• 是否进行了无关格式化；
• 是否意外覆盖开发者已有改动。

2. 接口兼容性

• 请求与响应字段是否变化；
• 数据库迁移是否兼容旧版本；
• 公共类型和函数签名是否改变。

3. 错误处理

• 是否吞掉异常；
• 是否把错误变成默认成功；
• 日志是否包含敏感信息。

4. 安全边界

• 是否写入密钥或令牌；
• 是否放宽鉴权与权限检查；
• 是否引入不必要的网络访问或生产依赖。

5. 验证证据

• 测试命令是否真实执行；
• 测试范围是否与改动匹配；
• 是否存在未处理的失败、警告或跳过项。

可以使用下面的最终审查提示：

请只审查当前 diff，不再修改文件。

重点检查：正确性回归、接口兼容性、并发问题、权限绕过、
异常吞噬、资源泄漏、无关改动和测试缺口。

每个问题必须给出文件位置、触发条件、影响和最小修复建议。
没有足够证据的问题标记为“需验证”。

---

九、常见失败模式与排查方法

Codex 读取了错误的规则

检查工作目录和 AGENTS.override.md。Codex 会从项目根目录向当前目录建立指令链，深层覆盖规则可能改变上层约定。

修改文件过多

在任务中明确允许修改的模块，并要求先列出计划。完成后使用 Git diff 检查无关格式化和生成文件。

测试一直失败

先区分三种情况：代码回归、测试环境缺失、仓库原有失败。要求 Codex 提供失败命令、关键错误和修改前后的对照证据。

Worktree 中无法构建

Worktree 是独立文件目录，可能缺少依赖和本地配置。为项目准备可重复的环境初始化脚本，不要依赖主目录中未记录的手工状态。

长任务逐渐偏离目标

把任务拆成“分析、实现、验证”三个检查点。每个检查点都重新核对完成标准，不要在同一线程中不断加入无关需求。

---

十、总结

Codex 高阶工作流的重点不是生成更多代码，而是建立可重复的工程控制面：

1. 使用 AGENTS.md 固化仓库规则；
2. 将需求写成有范围、有约束、有验收条件的任务；
3. 使用 Worktree 隔离可以并行的工作；
4. 让 Codex 实际运行测试、类型检查和 lint；
5. 根据任务难度分配 GPT 模型；
6. 对最终 diff 进行正确性、安全性和兼容性审查；
7. 保留人工批准作为最终交付边界。

当项目规则、工具反馈和验证标准都清晰时，Codex 才能从“代码建议工具”升级为可靠的工程协作者。

---

参考资料

• OpenAI：Codex 自定义指令与 AGENTS.md
• OpenAI：Codex App Worktree 工作流
• OpenAI：Codex 官方文档
• OpenAI：GPT 模型目录