前几天，团队里有同事问我：“你怎么用 Codex 一天能干完我一周的活？你是不是偷偷加了什么外挂？”

说实话，我一开始也觉得 Codex 就是个"高级版的 Copilot"。

直到我花了整整 30 天深度使用，踩了无数坑之后，才发现——大多数人只用了 Codex 不到 20% 的能力。

你可能会遇到这些情况：每次让 Codex 写代码都要反复纠正风格，改了半天还不如自己写；明明是个简单任务，它却生成了一堆不必要的复杂代码；让它跑测试，结果把不相关的测试也改了；更离谱的是，有时候它会"自作主张"地创建 git 分支、提交代码，搞得一团糟。

但其实，这些问题全都是因为——你不会"教" Codex。

本文将分享我在 30 天高强度使用中总结出的 12 个实战技巧，从入门配置到高级玩法，每一个都经过真实项目验证。

---

📊 先看看效果

在我优化完所有配置之后：

指标	优化前	优化后	提升
首次生成正确率	~40%	~85%	2 倍+
平均任务完成时间	15-30 分钟	3-8 分钟	3-5 倍
不必要的文件修改	频繁	几乎为零	95% ↓
代码风格一致性	每次都要纠正	自动遵守	100%
无效 token 消耗	高	低	60% ↓

💡 核心结论：Codex 的能力上限，取决于你给它的"上下文质量"。

---

技巧 1：AGENTS.md — 你的项目"说明书"

这是 最被低估 的功能，没有之一。

AGENTS.md 是放在项目根目录的一个文件，Codex 每次启动时都会自动读取它。你可以在里面写项目的编码规范、架构说明、常用命令等等。

创建你的第一个 AGENTS.md：

# 项目规范

## 技术栈
- 语言：TypeScript 5.4
- 框架：Next.js 14 (App Router)
- 数据库：PostgreSQL + Prisma ORM
- 测试：Vitest + Testing Library

## 编码规范
- 使用函数式组件，禁止 class 组件
- 变量命名：camelCase
- 组件命名：PascalCase
- 常量命名：UPPER_SNAKE_CASE
- 每个函数不超过 50 行

## 常用命令
- 启动开发服务器：`pnpm dev`
- 运行测试：`pnpm test`
- 运行单个测试文件：`pnpm test -- path/to/file.test.ts`
- 类型检查：`pnpm typecheck`
- Lint 检查：`pnpm lint`

## 目录结构
- `src/app/` — 页面路由
- `src/components/` — 共享组件
- `src/lib/` — 工具函数
- `src/server/` — 服务端逻辑
- `prisma/` — 数据库 schema

为什么这么重要？

没有 AGENTS.md 的时候，Codex 每次都要"猜"你的项目规范，猜错了你还得纠正它。有了这个文件，一次配置，永久生效。

⚠️ 注意： AGENTS.md 支持嵌套放置。子目录中的 AGENTS.md 会覆盖父目录的同名配置。比如你可以在 src/components/ 下放一个专门针对组件开发的规范。

---

技巧 2：用"角色 + 约束"模式写提示词

大多数人给 Codex 的提示词是这样的：

❌ 反面示例：

“帮我写一个用户注册功能”

这种提示词太模糊了，Codex 会按自己的理解随意发挥。

✅ 正确姿势：

"你是一个资深 Next.js 全栈工程师。请基于现有的 Prisma schema，实现用户注册的 API 路由。要求：

1. 使用 src/app/api/auth/register/route.ts 路径
2. 输入验证使用 zod
3. 密码使用 bcrypt 哈希
4. 返回标准 JSON 响应格式
5. 添加对应的 Vitest 单元测试"

公式： 角色定义 + 具体任务 + 技术约束 + 输出要求

为什么有效？

• 🎯 角色定义：让 Codex 进入"专家模式"，生成更专业的代码
• 📋 具体任务：明确要做什么，避免发散
• 🔒 技术约束：限制技术选型，和项目保持一致
• ✅ 输出要求：确保结果可验证

---

技巧 3：善用"不要做"指令

很多人只告诉 Codex “要做什么”，却忘了告诉它"不要做什么"。

这其实更重要。

在 AGENTS.md 或者提示词中加上这些约束：

## 禁止事项
- 不要修改我没有提到的文件
- 不要添加 inline 注释，除非我明确要求
- 不要创建 git commit
- 不要使用 any 类型
- 不要引入新的依赖包，除非我同意
- 不要使用 one-letter 变量名
- 不要添加 copyright 头
- 不要重构我没有提到的代码

效果对比：

场景	没有"不要做"约束	有"不要做"约束
修改一个函数	顺手重构了整个文件	只改目标函数
添加新功能	自动创建 git 分支并提交	只修改代码
修复一个 bug	引入了 3 个新的 import	最小化修改

🔴 这条技巧的 ROI 是最高的。 一个"不要做"的约束，可以帮你省下 80% 的返工时间。

---

技巧 4：分阶段提需求，而不是一次性甩大需求

❌ 反面示例：

“帮我做一个完整的电商系统，包括用户管理、商品管理、购物车、订单、支付”

这种大需求，Codex 大概率会生成一堆臃肿的、不符合你预期的代码。

✅ 正确姿势：分步执行

第一步：

“先设计电商系统的数据库 schema，包括用户、商品、购物车、订单四个表”

第二步：

“基于刚才的 schema，实现商品 CRUD 的 API 路由”

第三步：

“给商品 API 添加分页和搜索功能”

第四步：

“实现购物车功能，支持添加、删除、修改数量”

为什么分步更好？

• ✅ 每一步都可以 review 和调整
• ✅ 避免一次性生成大量难以维护的代码
• ✅ 上下文更聚焦，生成质量更高
• ✅ 发现问题可以及时纠正，不会"跑偏"

💡 经验法则： 每次给 Codex 的任务，控制在 15-30 分钟人工工作量 的范围内。太小了没效率，太大了容易失控。

---

技巧 5：用 TODO 计划让 Codex 先想再做

当你给 Codex 一个稍微复杂的任务时，可以要求它先生成一个执行计划：

“先不要写代码。先分析一下实现这个功能需要哪些步骤，列出你的计划。”

Codex 会生成一个结构化的 TODO 列表，类似这样：

1. [ ] 创建 API 路由文件
2. [ ] 定义请求/响应类型
3. [ ] 实现输入验证 (zod)
4. [ ] 实现业务逻辑
5. [ ] 添加错误处理
6. [ ] 编写单元测试
7. [ ] 运行测试验证

你可以：

• ✅ 确认计划合理后再让它执行
• ✅ 调整步骤顺序或增删步骤
• ✅ 在每个步骤完成后 review

进阶用法：

“按你的计划一步步来，每完成一步就停下来告诉我进展。”

这样 Codex 会进入"分步执行"模式，你可以在每一步之后介入和调整。

---

技巧 6：利用 Git 历史给 Codex 提供上下文

当你要修改或重构一段代码时，让 Codex 先看看 Git 历史：

“请先用 git log 和 git blame 查看 src/lib/auth.ts 的历史，了解这段代码为什么是这样的，然后再做修改。”

为什么有用？

• 📖 了解代码演变的背景和原因
• 🐛 发现之前修复过的相关 bug
• 🤝 尊重之前开发者的设计意图
• ⚠️ 避免重新引入已经修复过的问题

同样，你也可以让 Codex 查看相关的 PR 和 commit message：

“看一下最近 10 个 commit，了解项目最近的改动方向，然后基于这个上下文来实现新功能。”

---

技巧 7：测试驱动开发（TDD）的正确姿势

Codex 非常适合做 TDD，但你得用对方法。

方式一：先写测试，再让 Codex 实现

“我已经写好了测试文件 src/lib/__tests__/cache.test.ts，里面有 8 个测试用例。请实现 src/lib/cache.ts 让所有测试通过。不要修改测试文件。”

方式二：让 Codex 同时写实现和测试

"实现 src/lib/cache.ts 的 LRU 缓存功能，同时编写对应的测试。要求：

• 至少覆盖：基本存取、过期淘汰、容量淘汰、并发安全
• 测试文件放在 src/lib/__tests__/cache.test.ts
• 实现完成后运行 pnpm test -- cache 确认全部通过"

方式三：用测试验证修改

“修改 src/lib/auth.ts 的 token 过期逻辑，从固定 24 小时改为可配置。修改完成后运行 pnpm test -- auth 确保现有测试全部通过。”

⚡ 关键原则： 给 Codex 明确的测试运行命令，让它能自己验证结果。这比让它"自己觉得写对了"可靠 100 倍。

---

技巧 8：善用 sandbox 模式控制权限

Codex 提供了不同的沙箱模式来控制它的"自由度"。理解并正确使用它们非常关键：

模式	说明	适用场景
full-auto	自动执行，无需确认	信任度高的日常开发
suggest	每个操作都需要确认	生产环境、敏感代码

我的推荐配置：

• 🔴 生产代码 / 数据库操作 / API Key 相关： 使用 suggest 模式，逐个确认
• 🟡 日常功能开发： 使用 full-auto，提升效率
• 🟢 测试代码 / 文档编写： 使用 full-auto，放心让它跑

在提示词中也可以控制：

“这个任务涉及数据库 migration，请在执行每条 SQL 之前先告诉我。”

---

技巧 9：让 Codex 当你的 Code Reviewer

除了写代码，Codex 还是一个非常优秀的 Code Reviewer。

基础用法：

"请 review src/lib/auth.ts 最近的改动，关注以下方面：

1. 安全性（SQL 注入、XSS、认证绕过）
2. 性能（N+1 查询、不必要的内存分配）
3. 错误处理（边界情况、异常捕获）
4. 代码可读性"

进阶用法：对比式 Review

"对比 main 分支和当前分支的差异，像资深工程师一样做 Code Review。重点关注：

• 是否有向后兼容性问题
• 是否有遗漏的错误处理
• 是否有更简洁的实现方式"

让 Codex 做安全审计：

“对 src/app/api/ 下的所有路由做安全审计，列出潜在的安全风险和修复建议。按严重程度排序。”

💡 小技巧： Review 的时候让 Codex 用具体的代码示例来说明问题，而不只是泛泛而谈。

---

技巧 10：复杂重构的"安全网"策略

重构是最容易出事的操作。以下是我的安全重构流程：

第一步：建立基线

“先运行 pnpm test 记录当前所有测试的通过状态，不要修改任何代码。”

第二步：小步重构

“重构 src/lib/auth.ts，把回调风格改为 async/await。每次只改一个函数，改完立即运行相关测试确认没有 regression。”

第三步：全量验证

“所有函数都改完了，运行完整的测试套件 pnpm test，如果有失败的测试，逐个修复。”

第四步：类型检查 + Lint

“运行 pnpm typecheck 和 pnpm lint，确保没有类型错误和代码风格问题。”

为什么这个策略有效？

• ✅ 每一步都有明确的验证标准
• ✅ 出现问题可以精确定位到哪个函数
• ✅ 不会一次性引入大量变更导致难以排查

---

技巧 11：多 Agent 协作模式

Codex 支持同时运行多个 Agent 处理不同任务。这在大型项目中非常有用。

场景：同时开发前后端

Agent 1：

“实现用户管理的后端 API，包括 CRUD 和分页查询。”

Agent 2：

“基于 API 接口文档（如下），实现用户管理的前端页面。API 接口如下：…”

场景：同时写代码和文档

Agent 1：

“实现支付模块的核心逻辑。”

Agent 2：

“基于现有的 src/lib/payment.ts，编写 API 文档和使用示例。”

⚠️ 注意事项：

• 多个 Agent 不要同时修改同一个文件
• 明确划分每个 Agent 的职责边界
• 定期同步进展，避免冲突

---

技巧 12：高级 Prompt 模板库

以下是我在实际项目中反复验证过的高效 Prompt 模板：

🔧 Bug 修复模板

"我在 src/components/UserList.tsx 遇到了一个 bug：当用户列表超过 100 条时页面会卡死。

复现步骤： 打开用户列表页，加载 100+ 条数据
期望行为： 使用虚拟滚动，流畅展示
实际行为： 页面完全卡住，无法滚动

请分析原因并修复，确保修复后不影响现有功能。"

🏗️ 架构设计模板

"我需要设计一个通知系统，要求：

• 支持多渠道（邮件、短信、站内信、Webhook）
• 支持模板化消息内容
• 支持发送重试和失败队列
• 可扩展，方便后续添加新渠道

先给出架构设计方案（不需要代码），包括核心模块、数据流和技术选型。"

📊 性能优化模板

"src/lib/search.ts 的搜索接口响应时间超过 2 秒。请：

1. 分析性能瓶颈（是否有 N+1 查询、不必要的全表扫描等）
2. 提出优化方案
3. 实现优化
4. 用 benchmark 对比优化前后的性能数据"

🔄 迁移模板

"将项目从 Jest 迁移到 Vitest。要求：

• 逐个文件迁移，每迁移一个文件就运行确认
• 保持所有测试用例的行为不变
• 更新 package.json 和配置文件
• 迁移完成后删除 Jest 相关依赖"

---

全面对比：新手 vs 老手

维度	新手用法	老手用法
项目配置	没有 AGENTS.md	完善的 AGENTS.md + 嵌套配置
提示词	“帮我写个功能”	角色 + 约束 + 输出要求
任务粒度	一次甩大需求	分阶段执行，每步 review
约束条件	只说"要做什么"	明确"不要做什么"
验证方式	肉眼看代码	测试驱动 + 自动化验证
上下文管理	从零开始描述	利用 Git 历史 + 项目文档
复杂任务	直接开干	先出计划，逐步执行
重构	一次性大改	小步重构 + 持续验证
权限控制	全开或全关	按场景选择 sandbox 模式
代码质量	生成后手动检查	让 Codex 自己 Review

---

常见踩坑与解决方案

Q：Codex 总是修改我不想改的文件怎么办？

A：在 AGENTS.md 中明确写上：

## 禁止修改的文件
- `src/config/database.ts` — 数据库配置，请勿修改
- `prisma/migrations/` — 迁移文件，请勿手动修改

或者在提示词中加上：“只修改 src/lib/auth.ts，不要碰其他文件。”

Q：Codex 生成的代码太复杂了怎么办？

A：加上简洁性约束：

“用最简单的方式实现，不要过度设计。如果标准库能解决，不要引入第三方包。”

Q：Codex 总是忘记之前的上下文怎么办？

A：在新对话开头提供关键上下文：

“当前项目使用 Next.js 14 + TypeScript + Prisma，数据库是 PostgreSQL。请在这个前提下实现…”

Q：如何让 Codex 遵守团队已有的代码规范？

A：把你们的 ESLint 配置、Prettier 配置和编码规范都写进 AGENTS.md，Codex 会自动遵守。

Q：Codex 跑测试把不相关的测试也改了怎么办？

A：在 AGENTS.md 中加上：

## 测试规范
- 只修改与当前任务直接相关的测试文件
- 不要为了通过测试而修改测试用例的预期值
- 运行测试时使用精确路径：`pnpm test -- path/to/specific.test.ts`

---

总结

经过 30 天的深度使用，我的核心感悟是：

✅ AGENTS.md 是 ROI 最高的投资 — 一次配置，永久受益

✅ "不要做"比"要做"更重要 — 约束产生质量

✅ 分步执行永远优于一步到位 — 小步快跑，持续验证

✅ 给 Codex 足够的上下文 — 它不是全知的，但给它信息后它非常强

✅ 让 Codex 自我验证 — 测试驱动 + 自动化检查 > 人工 review

🔴 最后提醒： Codex 是一个强大的工具，但它的能力上限完全取决于你如何"教"它。花 30 分钟写好 AGENTS.md，比花 30 天反复纠正代码风格要有效 100 倍。

---

附录：我的完整 AGENTS.md 模板

# 项目规范

## 技术栈
- [填写你的技术栈]

## 编码规范
- [填写你的编码规范]

## 常用命令
- 启动：`[命令]`
- 测试：`[命令]`
- Lint：`[命令]`
- 构建：`[命令]`

## 禁止事项
- 不要修改未提及的文件
- 不要添加不必要的注释
- 不要创建 git commit
- 不要引入新依赖（除非明确要求）
- 不要重构未提及的代码
- 不要使用 any 类型
- 不要使用单字母变量名

## 测试规范
- 只修改与当前任务相关的测试
- 不要修改测试预期值来"通过"测试
- 运行测试时使用精确文件路径

## 提交规范
- 不要自动 commit
- 如果需要 commit，使用 Conventional Commits 格式