一篇文章，手把手教你使用 Codex
Codex 到底是什么
Codex 是一个 coding agent，也就是面向软件开发的智能代理。
普通聊天机器人通常返回一段代码。Codex 可以在项目目录里读取文件、修改代码、运行命令和测试，然后把结果告诉你。
它的工作范围不只包括“写新代码”，还包括：
解释一个陌生项目； 查找一个 Bug 的原因； 修改已有功能； 补充测试； 做代码审查； 批量执行重复的工程任务。
这意味着，Codex 不是一个代码片段生成器，而是一个可以参与开发循环的工具。
但它仍然需要边界。它看到的是项目文件和你提供的上下文，不会自动知道你的业务规则，也不会因为自己写得很快，就天然理解什么改动最合适。
了解 Codex 的组成
打开 Codex 后，通常可以看到两个主要入口：Chat（对话）和 Project（项目）。
Chat：适合问问题
Chat 和 ChatGPT 网页版比较接近，适合随手提问、讨论方案、解释一段代码。
不同对话之间通常互不相干，也不会自动共享某个本地项目文件夹。你可以在这里讨论一个技术概念，但不要期待它自动记住另一个项目里的目录结构。
Project：适合动本地文件
需要读取或修改本地文件时，使用 Project。
在项目里下达指令后，Codex 可以读取项目目录中的文件，并把修改直接应用到本地文件夹。写代码、改文档、做演示文稿，都可以放在对应项目中完成。
项目模式的关键，不是“它能改文件”，而是它知道自己正在什么目录里工作。目录边界越清楚，后续的权限和验证越容易管理。
对话框功能
Codex 的对话框支持添加上下文、附加文件或截图，也可以切换模型。
此外，还可以控制：
当前任务允许 Codex 做什么； Codex 使用哪个工作目录； 是否允许它运行命令或修改文件； 是否把某些内容交给插件、Skill 或 MCP 工具处理。
插件与 Skills
Codex 还可以通过插件、Skills 和 MCP 扩展能力。
插件可以连接外部工具，也可能包含 Skills、MCP、脚本等能力。常见的插件类型包括浏览器、文档、表格、演示文稿和 GitHub。
Skills 则更像一份可重复使用的工作说明。它可以规定某一类任务应该如何执行，例如怎样创建文档、怎样检查代码、怎样生成配图。
在对话框中输入 $，可以查看和调用可用的 Skills。
AGENTS.md：给 Codex 的项目说明书
每开启一个新的对话窗口，Codex 都会进入一个新的上下文。它不知道这个项目使用什么命令、有哪些目录边界、哪些文件不能改，也不知道团队平时怎么验证结果。
AGENTS.md 正是为了解决这类问题而存在的项目级指令文件。它是一个简单、开放的 Markdown 约定，目标是给 coding agent 提供一个稳定、可预测的项目指令入口，把项目结构、开发命令、测试要求、代码风格和协作边界显式写下来，减少反复解释。
更准确地说，AGENTS.md 是面向 coding agent 的 README。
README 主要给人看，介绍项目是什么、如何上手；AGENTS.md 给 Codex 和其他 coding agent 看，告诉它们改代码前应该遵守哪些项目规则。
AGENTS.md 应该写什么
一份好用的 AGENTS.md 不需要很长，但应该回答 Codex 开始工作前最关心的几个问题：
这个项目的主要目录和入口在哪里？ 本地如何安装、启动和构建？ 使用哪些命令运行测试、Lint 和类型检查？ 哪些文件可以改，哪些文件不应该直接修改？ 完成任务后，必须做哪些验证？ 遇到不确定的需求时，应该暂停还是自行决定？
AGENTS.md 放在哪里
最常见的做法是在项目根目录放一份 AGENTS.md。
如果一个大型仓库包含多个相对独立的子项目，也可以在子目录中放更具体的 AGENTS.md。例如，根目录说明通用工程规则，frontend/AGENTS.md 说明前端命令，backend/AGENTS.md 说明后端测试方式。
原则是：规则应该尽量靠近它适用的代码，同时避免在多个文件里重复维护同一条规则。
创建或完善文件时，可以让 Codex 先分析，而不是直接生成一份看似完整的模板：
请先阅读项目目录、package.json、README 和现有测试配置。
不要修改业务代码。
根据实际项目情况，生成一份简短的 AGENTS.md 草稿，包含目录结构、开发命令、测试命令、边界规则和完成前检查。
所有不确定的内容标记为“待确认”，不要自行猜测。
这样得到的文件通常比直接复 制网上模板更可靠。
任务设计：不要只说“帮我改好”
任务设计决定 Codex 的工作质量。
一个好任务会同时说明：目标、上下文、范围、约束、验证方式和最终交付。
一个坏任务是什么样的
下面是很多人实际会发出的指令：
帮我把登录功能改好，顺便优化一下代码。
这句话的问题不是太短，而是缺少可以执行的判断标准。
“改好”是什么意思？是修复一个报错，还是增加验证码？“优化”可以改哪些文件？是否允许修改数据库？需要兼容旧用户吗？完成之后怎么证明没有破坏原有登录流程？
当任务没有这些信息时，Codex 只能自己补全。它可能给出一个看起来合理、但与你的项目约定不一致的方案。
一个好的任务应该包含六部分
1. 目标：要解决什么问题
目标要尽量具体，最好能用一句话验证。
为登录页增加“显示/隐藏密码”按钮，不改变登录接口和认证流程。
这比“优化登录页体验”更容易执行。
2. 上下文：为什么要做
告诉 Codex 相关页面、组件、接口和已知问题。
登录页位于 `src/pages/Login.tsx`，密码输入使用 `src/components/FormInput.tsx`。
目前用户无法确认自己输入的密码，产品希望减少输错密码的情况。
上下文不需要把所有代码复 制一遍，只需要告诉它从哪里开始查找。
3. 范围：允许修改什么
明确文件范围和不在范围内的内容。
只修改登录页和相关组件。
不要修改后端接口、数据库结构、路由配置和其他页面。
范围越清楚，越不容易出现“顺手重构”。
4. 约束：哪些事情不能做
约束是任务的护栏。
保持现有 TypeScript 类型和组件 API。
不要新增第三方依赖。
不要删除已有测试。
不要改变现有的错误提示文案。
如果约束很重要，可以直接写进任务，也可以写入项目级的 AGENTS.md。
5. 验证：什么叫完成
告诉 Codex 如何检查结果。
补充或更新组件测试，覆盖：默认隐藏密码、点击按钮后显示密码、再次点击后恢复隐藏。
完成后运行 `npm run lint` 和相关测试。
“代码改了”不是完成标准，“测试覆盖了三个状态且命令通过”才是。
6. 交付：最后要告诉我什么
要求 Codex 总结修改内容和剩余风险。
最后列出修改的文件、运行过的命令、测试结果，以及仍然需要人工确认的事项。
一个完整的好任务示例
把上面的六部分组合起来，可以得到这样的任务：
请为登录页增加“显示/隐藏密码”功能。
目标：
在密码输入框右侧增加一个按钮，让用户可以在隐藏和明文之间切换。
不要改变登录接口、认证流程和错误提示文案。
上下文：
- 页面：`src/pages/Login.tsx`
- 输入组件：`src/components/FormInput.tsx`
- 测试目录：`src/pages/__tests__/`
- 当前项目使用 React、TypeScript 和 Vitest
范围：
- 只修改登录页、相关输入组件和对应测试。
- 不修改后端接口、数据库、路由和其他页面。
约束：
- 不新增第三方依赖。
- 保持现有组件 API 和 TypeScript 类型。
- 遵循项目现有的按钮样式和无障碍属性写法。
- 不删除或跳过已有测试。
执行方式：
1. 先阅读相关文件，说明当前密码输入是如何实现的。
2. 提出最小修改计划和预计修改的文件。
3. 等我确认计划后再修改代码。
4. 修改后补充必要测试。
验收标准：
- 默认状态下密码不可见。
- 点击按钮后密码可见。
- 再次点击后恢复隐藏。
- 按钮有可访问名称，不影响表单提交。
- `npm run lint` 和相关 Vitest 测试通过。
交付内容：
最后列出修改的文件、运行过的命令、测试结果和未解决的问题。
这个任务并不长，但它把“做什么、从哪里找、不能动什么、怎么验收”都写清楚了。
什么时候应该拆分任务
如果一个任务同时包含“改数据库、改接口、改前端、补测试、更新文档”，最好不要一次性 交给 Codex。
可以拆成四个相互衔接的任务：
先分析现有实现，输出方案； 修改数据和接口，并运行后端测试； 修改前端页面，并运行前端测试； 检查整体 diff，补充文档和回归测试。
拆分的好处不是让工作变慢，而是让每一步都有清晰的检查点。出现问题时，也更容易知道是哪一步引入的。
让 Codex 先计划，再执行
无论任务大小，都可以先使用下面的通用模板：
先不要修改文件。
请先阅读与任务相关的代码，回答：
1. 当前实现如何工作？
2. 最小修改方案是什么？
3. 预计会修改哪些文件？
4. 有哪些潜在风险？
5. 应该运行哪些验证命令？
如果信息不足，请列出需要我确认的问题。
确认计划之后，再发送：
按确认后的最小方案执行。
不要修改无关文件，不要顺手重构。
每完成一个阶段，说明修改了什么；完成后运行约定的验证命令并汇报结果。
这种方式比“直接生成最终代码”多了一步，却少了很多返工。
一个完整的 Codex 工作循环
把前面的内容合起来，推荐使用下面这套流程：
进入正确的项目目录； 让 Codex 阅读项目，不修改文件； 检查或创建 AGENTS.md；用目标、上下文、范围、约束、验证和交付六部分设计任务； 让 Codex 先提出最小修改计划； 创建 Git 检查点； 确认计划后执行； 查看 git diff和修改文件列表；运行项目测试、Lint 和构建； 必要时让 Codex 做一次只报告问题的代码审查。
可以用下面的命令创建检查点：
git status
git add -A
git commit -m "checkpoint before codex task"
修改完成后，再看：
git diff HEAD~1
不要只看 Codex 的总结。总结是解释，diff 才是事实。
结语
Codex 最适合的角色，不是“替你写完所有代码的人”。
它更像一个会读项目、会改文件、会跑测试的同事。你需要告诉它问题是什么，哪些地方不能动，以及什么结果才算完成。
AGENTS.md 负责提供长期有效的项目规则，任务设计负责说明当前这一次要做什么。前者像项目说明书，后者像一张工作单。
参考资料
Codex CLI 官方文档 Codex IDE 官方文档 OpenAI Codex GitHub 仓库
