Codex 使用指南：从入门到高效开发

1. Codex 是什么？

Codex 是 OpenAI 提供的 AI 编程 Agent。它不仅可以“回答代码问题”，还可以直接围绕一个真实项目完成开发任务，例如：

阅读和理解整个代码仓库查找 Bug 并修改代码新增功能重构代码编写单元测试执行测试、Lint、类型检查和构建命令分析报错日志Review 代码和 Pull Request修改多个文件并保持上下文一致使用终端、IDE 或云端环境完成较长的开发任务

与普通聊天式代码助手相比，Codex 更接近一个可以操作开发环境的“AI 软件工程师”。官方目前将 Codex 定位为一套编程 Agent 产品，包括本地 CLI、IDE 集成以及云端工作流等。

1. Codex 适合做什么？

Codex 最适合处理“有明确目标、可以通过代码和命令验证结果”的任务。

例如：

分析这个项目的登录流程，并告诉我 JWT 是在哪里生成和验证的。

或者：

修复用户登录后偶尔出现 401 的问题。

要求：

1. 先分析原因，不要直接修改。

2. 找到根因后修改代码。

3. 添加对应测试。

4. 运行测试。

5. 最后总结修改了哪些文件。

又或者：

给当前 Express 项目增加 Redis 缓存。

要求：

• 缓存 GET /api/products

• TTL 10 分钟

• 商品更新后自动清除缓存

• 添加单元测试

• 不改变现有 API 返回格式

这种任务比单纯说：

帮我优化代码。

效果好得多。

1. Codex 的几种主要使用方式

目前可以把 Codex 的常用方式理解为：

Codex / ChatGPT 中的编程 Agent

适合直接把代码项目交给 Agent，让它分析、修改和验证。

Codex CLI

直接在终端中运行 Codex，让它操作当前代码仓库。

IDE 集成

例如在 VS Code 等开发环境里使用 Codex，对当前工程进行分析和修改。

云端任务

将较长的开发任务交给 Codex，在独立环境中执行。

Codex CLI 尤其适合已经习惯 Terminal + Git 工作流的开发者。官方文档明确支持在代码仓库中启动 Codex，让它探索项目、规划修改、编辑文件并运行本地开发工具。

1. Codex CLI 快速入门
   第一步：进入项目目录

例如：

cd my-project

建议先确认当前 Git 状态：

git status

最好在独立分支操作：

git checkout -b codex/test-feature

这样即使 Codex 修改结果不理想，也可以很容易恢复。

第二步：启动 Codex

安装并登录 Codex CLI 后，可以在项目目录启动 Codex。

进入之后，你就可以直接使用自然语言给它任务。

例如：

先阅读这个项目，不要修改任何文件。

告诉我：

1. 项目使用什么技术栈

2. 程序入口在哪里

3. 核心目录分别负责什么

4. 如何启动项目

5. 如何运行测试

这是第一次接触陌生项目时非常推荐的做法。

不要一开始就：

重构整个项目。

让 Codex 先理解项目，再做修改，通常更加稳定。

1. Codex 最重要的使用技巧：任务要具体

Codex 的能力很强，但结果质量非常依赖任务描述。

一个比较好的 Prompt 通常包含：

目标+背景+修改范围+限制条件+验证方式+最终输出格式

例如：

目标：修复订单重复创建的问题。

背景：用户快速点击“提交订单”按钮时，偶尔会生成两个订单。

请：

1. 找到创建订单的调用链。

2. 分析重复订单产生的原因。

3. 不改变现有 API contract。

4. 使用最小修改解决问题。

5. 添加覆盖该问题的测试。

6. 运行相关测试。

7. 最后告诉我：
      - 根因
      - 修改文件
      - 修改方案
      - 测试结果

这样的 Prompt 通常远优于：

修一下订单 Bug。6. 推荐的 Codex 工作模式

一个比较稳定的工作流程是：

Explore↓Plan↓Implement↓Test↓Review

也就是：

第一步：Explore —— 先调查先不要修改代码。

分析这个 Bug 可能涉及哪些文件，找到调用链和可能的根因。第二步：Plan —— 给方案根据刚才的分析，给我一个最小改动方案。说明需要修改哪些文件，以及为什么。暂时不要修改。第三步：Implement —— 开始修改按照方案实施修改。尽量保持改动最小。不要修改无关代码。第四步：Test —— 验证运行与此次修改相关的测试。

如果测试失败：

1. 判断是代码问题还是测试问题

2. 修复

3. 再运行测试
   第五步：Review —— 最后检查
   Review 你刚才的修改。

重点检查：

• 潜在 Bug

• 边界条件

• 安全问题

• 并发问题

• 是否存在不必要修改

如果发现问题，修复后重新测试。

这种方式通常比一句：

完成这个功能。

更加可靠。

1. 一个非常实用的 Prompt 模板

日常开发可以直接使用：

任务：[描述你想完成的事情]

背景：[项目背景 / Bug 情况 / 功能需求]

要求：

1. 先阅读相关代码。

2. 找出涉及的文件和调用链。

3. 在修改前简要说明方案。

4. 尽量采用最小修改。

5. 不修改无关代码。

6. 保持现有代码风格。

7. 添加或更新必要测试。

8. 修改后运行相关测试和检查。

9. 如果测试失败，继续分析并修复。

限制：

• 不改变现有 API contract

• 不引入不必要依赖

• 不进行大规模重构

完成后告诉我：

• 根因 / 实现思路

• 修改了哪些文件

• 每个文件修改了什么

• 运行了哪些测试

• 是否还有潜在风险

这是一个比较通用的 Codex 开发模板。

1. 如何让 Codex 理解整个项目

如果项目比较复杂，可以先让 Codex制作“项目地图”。

例如：

阅读当前代码仓库。

先不要修改代码。

请输出：

之后继续问：

重点分析 authentication 模块。

告诉我从：

POST /login

开始，到 JWT 返回给客户端为止，完整调用链经过哪些文件和函数。

这种“逐层缩小范围”的方式非常适合大型项目。

1. 使用 AGENTS.md 给 Codex 设置项目规则

Codex 支持通过 AGENTS.md 给 Agent 提供长期项目说明。Codex 会在执行任务前读取这些说明，因此它非常适合存放项目规范。

例如在项目根目录创建：

AGENTS.md

内容：

Project Instructions

Tech Stack

• TypeScript

• Node.js

• Express

• PostgreSQL

• Jest

Code Style

• 使用 TypeScript strict mode

• 优先使用 async/await

• 不使用 any

• 函数保持简短

• 避免重复逻辑

Architecture

Controller:负责 HTTP request/response

Service:负责业务逻辑

Repository:负责数据库访问

禁止 Controller 直接访问数据库。

Testing

任何新增功能必须包含测试。

修改后运行：

npm test

以及：

npm run lint

Rules

不要：

• 修改 package-lock.json，除非新增依赖

• 修改 API response contract

• 删除已有测试

• 大规模重构无关模块

这样以后就不需要每次 Prompt 都重复这些规则。

1. Bug 修复场景

假设程序出现：

TypeError: Cannot read properties of undefined

不要只告诉 Codex：

修这个错误。

更好的方式：

调查这个错误：

TypeError: Cannot read properties of undefined

出现位置：src/services/order.ts:125

请：

1. 找到导致 undefined 的完整数据流。

2. 判断是调用方还是 order service 的问题。

3. 检查是否还有类似代码。

4. 先告诉我根因。

5. 使用最小修改修复。

6. 增加 regression test。

7. 运行测试验证。

重点是让 Codex解决根因，而不仅仅是加：

if (!value) return;

这种表面修补。

1. 新功能开发场景

例如：

给系统增加“忘记密码”功能。

当前技术栈：

• Next.js

• Node.js

• PostgreSQL

要求：

流程：用户输入邮箱→生成一次性 token→发送 reset link→用户设置新密码

安全要求：

• token 30 分钟过期

• token 只能使用一次

• 数据库存储 token hash

• 新密码必须经过现有 password hashing 逻辑

请先：

1. 分析现有 authentication 架构

2. 找出需要修改的文件

3. 给出实现计划

我确认方案之后再修改代码。

复杂功能尤其适合先 Planning。

1. 重构场景

重构时最大的风险是 Codex “顺手改很多东西”。

因此最好明确边界：

重构 src/services/payment.ts。

目标：降低函数复杂度，提高可测试性。

限制：

• 不改变任何外部行为

• 不改变 public API

• 不更换第三方库

• 不修改数据库 schema

• 不修改无关文件

步骤：

1. 分析当前代码的问题。

2. 给出重构方案。

3. 保证现有测试全部通过。

4. 进行重构。

5. 再次运行测试。

6. 对比重构前后的行为。

7. 测试场景

Codex 非常适合帮助补测试。

例如：

分析：

src/services/payment.ts

找出目前测试没有覆盖的重要逻辑。

重点检查：

• 成功路径

• 参数错误

• 网络失败

• timeout

• retry

• duplicate request

• concurrent request

然后：

1. 给出缺失测试列表

2. 编写测试

3. 运行测试

4. 修复失败测试

5. Code Review 场景

可以让 Codex 模拟高级工程师 Review：

Review 当前 branch 相对于 main 的所有修改。

不要直接修改代码。

重点检查：

1. correctness

2. security

3. race condition

4. error handling

5. performance

6. backward compatibility

7. test coverage

8. maintainability

只报告真正值得修改的问题。

每个问题包含：

• severity

• 文件

• 行或函数

• 原因

• 推荐修改方式

之后：

修复 High 和 Medium severity 的问题。

Low severity 暂时不要改。15. 让 Codex 自己验证结果

一个非常重要的原则是：

不要只让 Codex“写代码”，还要让 Codex“证明代码能工作”。

例如：

修改完成后：

1. 运行 unit tests

2. 运行 integration tests

3. 运行 lint

4. 运行 typecheck

5. 运行 build

如果其中任何一步失败，分析原因并修复。

不要因为已有测试失败就直接忽略，先判断失败是否与你的修改有关。

Codex 可以操作开发工具并把执行结果纳入下一轮推理，这正是 Agent 与普通代码生成器之间的重要区别。

1. Git + Codex 推荐工作流

推荐：

git checkout -b feat/user-search

启动 Codex 后：

实现用户搜索功能。

修改完成：

Review 当前 git diff。

检查：

• 是否修改了无关文件

• 是否存在 debug code

• 是否存在 TODO

• 是否存在 hardcoded value

• 是否遗漏测试

之后自己查看：

git diff

测试：

npm test

最后再：

git status

确认无误后才 Commit。

原则是：

Codex 可以写代码，Git 负责给你安全网。17. 不推荐的使用方式

以下 Prompt 往往效果一般：

优化项目。

因为范围太大。

改成：

分析 src/api。

找出三个最明显的性能瓶颈。

先不要改代码，按影响程度排序并说明原因。

另一个问题：

把代码写得更好。

“更好”没有客观标准。

改成：

重构这个模块，目标是：

• 降低重复代码

• 单个函数 < 50 行

• 提高可测试性

• 不改变外部行为

• 不新增依赖

还有一种危险 Prompt：

重构整个项目并修复所有问题。

范围过大会增加：

修改不可控上下文过长错误难以定位Review 困难

更推荐拆成：

分析↓模块 A↓测试↓模块 B↓测试18. Codex 高阶技巧：让它“调查”，而不是“猜”

如果遇到 Bug，可以说：

不要猜原因。

通过以下方式调查：

• 搜索相关代码

• 查看调用方

• 检查数据结构

• 查看测试

• 必要时运行程序或测试

用实际代码证据确定根因。

这是非常有效的一条指令。

1. 高阶技巧：限制修改范围

例如：

允许修改：

src/auth/tests/auth/

除非绝对必要，不要修改其他目录。

如果认为必须修改其他文件，先解释原因。

大型项目里非常实用。

1. 高阶技巧：要求最小 Diff

可以明确告诉 Codex：

优先选择最小可行修改。

避免：

• 无关 formatting

• 重命名无关变量

• 顺手重构

• 改变目录结构

• 新增不必要 abstraction

这样 Code Review 会轻松很多。

1. 高阶技巧：让 Codex 给出证据

不要只问：

修好了吗？

可以问：

证明这个问题已经解决。

告诉我：

1. 根因是什么

2. 哪段代码解决了它

3. 哪个测试覆盖了这个问题

4. 测试执行结果

5. 是否存在尚未覆盖的边界情况

6. Codex 的上下文管理

Codex 的一次任务并不是简单的一问一答。

Agent 可以：

读取文件↓执行命令↓查看输出↓再次推理↓继续修改↓再次测试

这些操作形成 Agent Loop。随着对话越来越长，历史消息、工具调用和输出都会消耗上下文，因此特别复杂的任务最好拆分成明确阶段，而不是无限延长一个巨大的任务。

1. 一个完整实战示例

假设你的任务是：

给一个 Node.js 项目增加 Rate Limiting。

第一次：

分析当前项目。

找到：

• API 入口

• middleware 架构

• authentication middleware

• Redis 是否已经存在

暂时不要修改代码。

第二次：

设计 Rate Limiting 方案。

要求：

登录接口：5 次 / 分钟 / IP

普通 API：100 次 / 分钟 / 用户

优先复用 Redis。

给出需要修改的文件。

第三次：

按方案实现。

要求：

• 最小修改

• 保持现有架构

• 添加测试

第四次：

运行：

npm testnpm run lintnpm run typecheck

修复与你修改相关的所有失败。

第五次：

Review 当前 git diff。

重点检查：

• 是否可以绕过 rate limit

• Redis failure 时行为

• race condition

• IPv6

• authenticated / unauthenticated user

第六次：

给我最终总结：

修改文件核心设计测试结果潜在风险

这就是比较成熟的 Codex 工作方式。

1. 一套推荐的日常 Codex 工作流

可以把日常开发固定成：

需求↓让 Codex Explore↓让 Codex Plan↓确认修改范围↓Implement↓Test↓Review Diff↓再次 Test↓人工 Review↓Commit

其中最重要的三个习惯是：

先调查，再修改。

让测试参与整个过程。

始终 Review Git Diff。

1. Codex Prompt 速查表
   理解项目
   阅读当前代码仓库，不修改代码。
   解释架构、入口、核心模块和测试方式。
   找 Bug
   调查这个 Bug。
   不要猜。
   找到完整调用链和根因后再提出修改方案。
   修 Bug
   使用最小修改修复该问题，并添加 regression test。
   新功能
   先分析现有架构，给出实现计划。
   不要立即修改代码。
   重构
   重构这个模块，但不改变任何外部行为。
   保证所有测试继续通过。
   测试
   分析该模块缺失的关键测试并补充。
   重点覆盖边界条件和失败路径。
   Review
   Review 当前 branch 相对于 main 的修改。
   重点检查 correctness、security 和 regression。
   验证
   运行测试、lint、typecheck 和 build。
   如果失败，分析并修复。
   最终检查
   Review git diff。
   找出无关修改、debug code、TODO 和潜在风险。

2. 最后的原则

使用 Codex 时，不要把它简单理解成：

“帮我写代码的 AI。”

更有效的理解是：

“可以读取代码、执行工具、修改项目并验证结果的软件工程 Agent。”

因此最理想的合作模式不是：

我描述需求→Codex 输出代码

而是：

我定义目标和边界↓Codex 调查↓Codex 提出方案↓Codex 修改↓Codex 测试↓Codex Review↓我最终确认

官方的最佳实践同样强调：为 Codex 提供明确目标、充分上下文、可验证结果，并让 Agent 使用测试和开发工具来验证工作，通常能明显提高结果质量。

按照这个模式使用，Codex 最适合承担的就不只是“补全几行代码”，而是完整的软件开发任务