Codex 编程实战教程：把 Coding Agent 用成可验证的工程队友

> 来源基础：本文基于 Towards Data Science 文章《How to Maximize OpenAI’s Codex》的 Gemini 摘要整理，并加入面向实战落地的补充模板。原文核心观点是：Codex 的优势在于严格执行明确指令、速度快、适合窄范围任务；但它可能漏掉关联修改，因此必须配合计划、隔离、测试和验收闭环。

适合谁

一句话原则

把 Codex 当成“严格执行型工程代理”，不要只给目标；要同时给边界、上下文、验证命令和停止条件。

0. Codex 更适合做什么

Codex 的强项不是“猜出你所有意图”，而是“按清楚的任务合同执行”。

更适合：

不适合直接裸跑：

1. 最小可用工作流

每次让 Codex 编程，都按这 6 步走：

1. 隔离工作区：新建 git branch 或 worktree。 2. 给任务合同：目标、范围、禁止事项、相关文件、验收命令。 3. 先让它读代码和计划：复杂任务先计划，别直接改。 4. 执行最小修改：只改必要文件。 5. 让它自测：运行测试、lint、类型检查、浏览器验证。 6. 人工复核 diff：看它是否越界、漏改、硬编码、删测试。

推荐心智模型：

不是：帮我把这个功能做了
而是：在这些边界内完成这个变更，并用这些命令证明它可用

2. 项目准备：让 Codex 有稳定上下文

在项目根目录放一个 AGENTS.md，告诉 Codex 项目规则。

示例：

# AGENTS.md

## 项目

这是一个 Python/FastAPI 项目。

## 常用命令

uv sync uv run pytest -q uv run ruff check . uv run ty check .


## 编码规则

- 新增函数必须有类型注解。
- 禁止硬编码 token、密码、IP。
- 禁止修改 migrations，除非任务明确要求。
- 修 bug 必须补回归测试。

## 完成标准

任务完成前必须：

1. 说明改了哪些文件。
2. 运行相关测试。
3. 汇报失败项和未验证项。

预期效果：

失败处理：

3. Worktree：并发任务要隔离

文章提到 Codex 没有 Claude Code 那种内置 worktree 体验，可以用 shell alias 补足。

示例 alias：

# 放到 ~/.bashrc 或 ~/.zshrc
codex-wt() {
  if [ -z "$1" ]; then
    echo "usage: codex-wt <worktree-name>"
    return 1
  fi

  current_repo=$(basename "$(git rev-parse --show-toplevel)")
  branch="codex/$1"
  target="../${current_repo}-$1"

  git fetch --all --prune
  git worktree add -b "$branch" "$target"
  cd "$target" || return 1
  codex
}

使用方式：

cd ~/code/my-api
codex-wt fix-login-timeout

预期结果：

../my-api-fix-login-timeout 被创建
新分支 codex/fix-login-timeout 被创建
Codex 在隔离工作区启动

适用场景：

失败处理：

4. Prompt 模板：把任务说成合同

通用模板

你是这个仓库的编码代理。先读取 AGENTS.md、README.md 和相关文件，再行动。

目标：
- <一句话说明要完成什么>

范围：
- 允许修改：<文件/目录>
- 不允许修改：<文件/目录/行为>

上下文：
- 相关错误：<报错/日志/截图>
- 相关文件：<路径列表>

执行要求：
1. 先给出 3-5 步计划。
2. 只做最小必要改动。
3. 如果发现需求会影响范围外文件，先停下来说明。
4. 不要新增依赖，除非我明确批准。
5. 不要修改测试来掩盖问题。

验证：
- 运行：<测试命令>
- 运行：<lint/type 命令>
- 如果命令失败，汇报失败原因和下一步，不要假装完成。

完成汇报：
- 改动文件
- 验证命令和结果
- 剩余风险

为什么这样写

Codex 很擅长执行明确指令，但不一定会主动补足上下文。这个模板把“目标、边界、验证、停止条件”一次性写清楚，减少越界和漏验收。

5. 三个可直接复制的实战案例

案例 A：精准修 bug

场景：登录接口偶发超时，怀疑是外部请求没有 timeout。

给 Codex 的 prompt：

先读取 AGENTS.md、README.md，以及 src/auth/ 下的登录相关代码。

目标：
修复登录接口调用外部用户服务时可能无限等待的问题。

范围：
- 允许修改 src/auth/ 和 tests/auth/。
- 不允许改数据库 schema。
- 不允许新增依赖。

上下文：
生产日志里出现：
TimeoutError: login request exceeded gateway timeout

执行要求：
1. 先找出外部 HTTP 调用位置。
2. 为外部调用设置明确 timeout。
3. 补一个回归测试，模拟外部服务超时。
4. 不要修改与登录无关的业务逻辑。

验证：
- uv run pytest tests/auth -q
- uv run ruff check src/auth tests/auth

预期输出：

修改 src/auth/client.py：为 HTTP 请求增加 timeout
新增 tests/auth/test_login_timeout.py：覆盖超时路径
pytest 通过
ruff 通过

人工复核重点：

失败处理：

案例 B：前端小功能 + 浏览器自测

场景：给设置页增加“复制 API Key”按钮。

给 Codex 的 prompt：

先读取 AGENTS.md、前端 README，以及 settings 页面相关组件。

目标：
在设置页 API Key 字段旁边增加复制按钮。

范围：
- 允许修改 src/pages/settings/ 和对应测试。
- 不允许改认证逻辑。
- 不允许把真实 API Key 写入测试或源码。

执行要求：
1. 增加复制按钮。
2. 点击后调用浏览器 Clipboard API。
3. 成功后显示“已复制”，2 秒后恢复。
4. 为按钮行为补测试。
5. 如果项目支持 Playwright，启动页面并实际点击验证。

验证：
- npm test -- settings
- npm run lint
- 如可用：npx playwright test settings-copy-api-key.spec.ts

预期验收：

页面出现复制按钮
点击按钮后提示“已复制”
剪贴板写入 mock API key
测试和 lint 通过

失败处理：

案例 C：局部重构但防止越界

场景：把订单金额计算从 controller 移到 service。

给 Codex 的 prompt：

先读取 AGENTS.md、订单模块 README，以及 src/orders/ 相关代码。

目标：
把订单金额计算逻辑从 controller 移到 service，使 controller 只负责请求/响应编排。

范围：
- 允许修改 src/orders/controller.py、src/orders/service.py、tests/orders/。
- 不允许改数据库模型。
- 不允许改 API 响应字段名。
- 不允许重写整个订单模块。

执行要求：
1. 先列出当前金额计算逻辑的位置。
2. 提出最小迁移方案。
3. 保持现有 API 行为不变。
4. 为 service 层金额计算补单元测试。
5. 如发现其他模块依赖旧函数，先说明，不要擅自大范围改。

验证：
- uv run pytest tests/orders -q
- uv run ruff check src/orders tests/orders
- 如项目有类型检查：uv run ty check src/orders

预期验收：

controller 变薄
service 有可单测的金额计算函数
订单相关测试通过
API 字段未变化

失败处理：

6. Plan Mode 与执行模式怎么用

根据文章经验，Codex 的推理等级和模式会影响结果。

推荐规则：

Prompt 示例：

这次先只做计划，不要修改文件。

请输出：
1. 你需要读取哪些文件。
2. 可能影响哪些模块。
3. 最小安全改动路径。
4. 测试和回滚方案。
5. 哪些点需要我确认。

当计划可接受后，再给执行 prompt：

按刚才计划执行第 1 阶段，只修改 <文件列表>。
完成后运行 <命令> 验证。
如果需要扩大范围，先停下来说明原因。

7. YOLO / 高权限模式的安全边界

文章倾向于给 Codex 高权限，以减少交互中断。但在真实工程中，不能把“模型很少犯错”当成安全策略。

开启高权限前至少满足：

安全 prompt：

你可以自动读写当前工作区文件和运行本地测试。

但遇到以下情况必须停止并请求确认：
- 删除文件或批量移动文件。
- 修改 migrations、infra、k8s、terraform、CI/CD。
- 执行数据库写入、DROP、DELETE、TRUNCATE。
- 调用外部生产 API。
- 发送邮件、消息或触发部署。
- 新增或升级依赖。

8. 验证闭环：让 Codex 自测，但不要只信它的总结

最低验证矩阵：

要求 Codex 输出证据：

完成后请贴出：
1. git diff --stat
2. 修改文件列表
3. 每条验证命令的退出状态
4. 失败命令的错误摘要
5. 你没有验证的内容

人工验收命令：

git diff --stat
git diff -- src tests
git status --short

不要接受这种完成汇报：

已完成，应该可以工作。

可以接受这种完成汇报：

已完成。
修改：src/auth/client.py, tests/auth/test_login_timeout.py
验证：uv run pytest tests/auth -q 通过；uv run ruff check src/auth tests/auth 通过
未验证：未运行全量测试，建议合并前跑 uv run pytest -q

9. 常见坑

坑 1：任务太大

症状：Codex 改了很多文件，最后测试跑不起来。

处理：把任务切成阶段。

停止当前实现。请只保留第一个可验证的小步骤：<步骤名>。
其他改动先回滚或列为后续任务。

坑 2：Codex 太听话，漏掉关联点

症状：它只改了你点名的文件，忘了测试、类型、调用方。

处理：在 prompt 里加入关联检查。

完成目标修改后，请搜索所有调用方和相关测试。
如果发现必须同步更新的关联点，先列出来，再修改最小必要部分。

坑 3：Codex 太自由，越界重构

症状：它顺手格式化、重命名、调整架构。

处理：明确非目标。

本任务不是重构任务。不要修改命名、目录结构、公共 API 或无关格式。
如果你认为必须重构，先停止并说明理由。

坑 4：自测不真实

症状：它说测试通过，但只跑了一个不相关命令。

处理：指定命令和验收输出。

必须运行以下命令：...
如果命令不存在，先说明，不要替换成无关命令。

10. 一周落地路线

第 1 天：

第 2 天：

第 3 天：

第 4 天：

第 5 天：

第 6 天：

第 7 天：

11. 最小 Checklist

每次交给 Codex 前：

Codex 完成后：

12. 推荐默认 Prompt

先读取 AGENTS.md、README.md 和相关代码，然后再行动。

目标：<写清楚目标>

范围：
- 允许修改：<路径>
- 禁止修改：<路径/行为>

约束：
- 不新增依赖。
- 不修改无关文件。
- 不跳过或删除测试。
- 不硬编码 secrets/IP/token。
- 遇到数据库、部署、CI/CD、infra、外部写操作时停止并请求确认。

流程：
1. 先输出简短计划。
2. 执行最小必要改动。
3. 补或更新测试。
4. 运行验证命令。
5. 汇报 diff、验证结果和未验证项。

验证命令：
- <命令 1>
- <命令 2>

结论

Codex 的实战价值来自“明确合同 + 自动执行 + 可验证闭环”。它越像一个可审计的工程队友，越能稳定产出；它越像一个没有边界的万能助手，越容易制造不可控 diff。

最简单的起点不是复杂工具链，而是三件事：

1. 写好 AGENTS.md。 2. 每个任务用合同式 prompt。 3. 每次完成都用测试和 diff 验证。