2026 ChatGPT Pro Codex 高阶开发教程AGENTS.md、Worktree 与自动测试闭环更新时间2026 年 7 月 6 日。本文是一篇 Codex 工程实践教程重点介绍项目指令、任务隔离、GPT 模型分工、自动验证和代码审查。很多开发者使用 GPT 辅助编程时工作流仍然是复制报错、粘贴代码、获取一段建议再手动把修改搬回项目。这种方式适合解释语法却没有充分利用 Codex 的 Agent 能力。Codex 可以进入真实工程环境读取仓库、搜索调用关系、修改文件、执行命令、运行测试并根据失败结果继续迭代。一套可用于真实项目的 Codex 工作流应该是项目规则 → 任务定义 → 隔离工作区 → 代码修改 → 自动验证 → diff 审查 → 交付本文将从零搭建这条流水线并讨论其中最容易被忽略的工程细节。一、Codex 工程工作流的核心结构Codex 不是单纯的代码生成器。一次完整任务通常包含七个阶段读取项目级指令定位与任务相关的文件建立根因分析或实现计划在受控范围内修改代码运行测试、类型检查和 lint根据失败结果继续修复输出可供人工审查的 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/apiHTTP 接口、鉴权和参数校验 - 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 neverSummarize 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 中的操作流程新建线程时选择Worktree选择任务的起始 Git 分支提交范围明确的任务Codex 创建隔离 Worktree 并执行在 Worktree 中运行测试和检查使用 Handoff 将任务移回 Local或直接在 Worktree 中创建分支人工审查 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 等较小模型关键结论模型分析后必须通过测试或人工审查验证模型切换的原则不是单纯追求更强而是把推理资源放在真正困难的步骤上。例如一次迁移任务可以拆为强模型分析兼容性和迁移风险编码模型执行跨文件修改较小模型整理日志和失败用例编码模型根据测试结果继续修复人工完成最终架构与安全审查。八、对最终 diff 进行工程审查Codex 报告“完成”不等于可以合并。最终至少检查五类风险。1. 修改范围是否修改了任务之外的文件是否进行了无关格式化是否意外覆盖开发者已有改动。2. 接口兼容性请求与响应字段是否变化数据库迁移是否兼容旧版本公共类型和函数签名是否改变。3. 错误处理是否吞掉异常是否把错误变成默认成功日志是否包含敏感信息。4. 安全边界是否写入密钥或令牌是否放宽鉴权与权限检查是否引入不必要的网络访问或生产依赖。5. 验证证据测试命令是否真实执行测试范围是否与改动匹配是否存在未处理的失败、警告或跳过项。可以使用下面的最终审查提示请只审查当前 diff不再修改文件。 重点检查正确性回归、接口兼容性、并发问题、权限绕过、 异常吞噬、资源泄漏、无关改动和测试缺口。 每个问题必须给出文件位置、触发条件、影响和最小修复建议。 没有足够证据的问题标记为“需验证”。九、常见失败模式与排查方法Codex 读取了错误的规则检查工作目录和AGENTS.override.md。Codex 会从项目根目录向当前目录建立指令链深层覆盖规则可能改变上层约定。修改文件过多在任务中明确允许修改的模块并要求先列出计划。完成后使用 Git diff 检查无关格式化和生成文件。测试一直失败先区分三种情况代码回归、测试环境缺失、仓库原有失败。要求 Codex 提供失败命令、关键错误和修改前后的对照证据。Worktree 中无法构建Worktree 是独立文件目录可能缺少依赖和本地配置。为项目准备可重复的环境初始化脚本不要依赖主目录中未记录的手工状态。长任务逐渐偏离目标把任务拆成“分析、实现、验证”三个检查点。每个检查点都重新核对完成标准不要在同一线程中不断加入无关需求。十、总结Codex 高阶工作流的重点不是生成更多代码而是建立可重复的工程控制面使用AGENTS.md固化仓库规则将需求写成有范围、有约束、有验收条件的任务使用 Worktree 隔离可以并行的工作让 Codex 实际运行测试、类型检查和 lint根据任务难度分配 GPT 模型对最终 diff 进行正确性、安全性和兼容性审查保留人工批准作为最终交付边界。当项目规则、工具反馈和验证标准都清晰时Codex 才能从“代码建议工具”升级为可靠的工程协作者。参考资料OpenAICodex 自定义指令与 AGENTS.mdOpenAICodex App Worktree 工作流OpenAICodex 官方文档OpenAIGPT 模型目录