参考资料

• OpenAI Codex 文档
• AGENTS.md 规范

Codex（01） - Codex 是什么

读完后，你应能完成以下任务：

• 绘制“Codex（01） - Codex 是什么 / 概念解释”的关键对象与数据流，解释“Codex 和普通聊天模型最大的差别，是它能围绕一个工作目录持续行动。”，并用源码位置、日志或 Trace 标注证据。
• 为“Codex（01） - Codex 是什么 / 你应该怎么使用它”设计正常与异常输入，验证“这比“帮我改一下登录页”好很多，因为 Codex 不需要猜你的边界。”，输出首个偏差位置与回归测试结果。
• 实现“Codex（01） - Codex 是什么 / 第一次使用建议”的最小代码或配置，检验“如果你刚开始，不要直接让 Codex 重构整个项目。”，输出命令、结果与 Diff，并说明不适用边界。

Codex 是 OpenAI 面向软件开发的编码智能体。 它不只是聊天窗口里的“代码问答助手”， 更像一个可以读项目、理解任务、编辑文件、运行命令、检查结果的协作者。

你可以把它类比成一个前端团队里的高级同事：你给它需求、项目上下文和验收标准， 它会自己看代码、提出修改方案、落地补丁， 并尽量通过测试或命令验证结果。

一、概念解释

Codex 常见能力可以分成 5 类：

能力	它在做什么	适合场景
解释	阅读代码或文档后讲清楚	接手旧项目、理解报错
修改	直接编辑文件	修 bug、加功能、改样式
执行	调用终端命令	跑测试、查日志、生成文件
审查	从风险角度看改动	PR review、上线前检查
沉淀	把经验写进规范或工作流	AGENTS、Skill、插件

Codex 和普通聊天模型最大的差别，是它能围绕一个工作目录持续行动。 普通聊天更像“你问一句，它答一句”； Codex 更像“你交代一个任务，它在项目里推进到完成”。

二、你应该怎么使用它

一个好任务通常包含 4 个部分：

目标：你要完成什么
范围：在哪些文件、模块、目录内完成
约束：不要动什么、必须遵守什么
验收：怎样算完成

例如：

帮我给这个 React 项目的登录页增加邮箱格式校验。

范围：
- 只改 src/pages/Login.tsx 和相关测试
- 不引入新的表单库

要求：
- 邮箱为空时提示“请输入邮箱”
- 邮箱格式错误时提示“邮箱格式不正确”
- 保持现有样式风格

验收：
- 补充或更新测试
- 跑一遍现有测试

这比“帮我改一下登录页”好很多，因为 Codex 不需要猜你的边界。

三、第一次使用建议

如果你刚开始，不要直接让 Codex 重构整个项目。先从小任务开始：

• 解释一个文件。
• 修一个明确报错。
• 给一个函数补测试。
• 把一段重复代码抽成工具函数。
• 根据一篇笔记生成 README。

这样你能观察它的工作方式，也能逐步建立信任。

四、常见错误

4.1 错误 1：只给一句模糊需求

这个项目帮我优化一下。

问题是“优化”没有方向。 是性能、结构、可读性、包体积、交互体验，还是构建速度？

更好的说法：

请审查 src/components/Table.tsx 的性能问题，重点看重复渲染、列表 key、memo 使用是否合理。先给发现，再决定是否修改。

4.2 错误 2：让 Codex 一次做太多

帮我重构项目、补测试、修所有 bug、顺便写文档。

这种任务跨度太大，容易出现目标漂移。更适合拆成多轮：

1. 先审查结构问题。
2. 再选一个模块重构。
3. 然后补测试。
4. 最后更新文档。

4.3 错误 3：不说明禁止事项

如果你不想引入依赖、不想改 API、不想动数据库结构，要明确写出来。 Codex 很擅长解决问题，但它不知道你团队里的隐性红线。

五、最佳实践

• 小步提交：每次让 Codex 完成一个清晰任务。
• 明确验收：告诉它要跑什么命令、产出什么文件、检查什么效果。
• 先读后改：复杂任务先让 Codex 总结现状和方案，再允许修改。
• 留下规范：重复出现的要求写进 AGENTS.md，而不是每次复制粘贴。
• 保持审查意识：Codex 的产出要像同事代码一样 review，尤其是权限、数据、安全相关改动。

六、本章小结

Codex 的核心价值不是“替你写几行代码”， 而是把一个开发任务从理解、修改、验证到总结串起来。 你越能给出清晰目标和边界，它越像一个可靠的协作者。

七、动手实践：01 hello Codex

这个 demo 用来练习“给 Codex 一个清晰小任务”。

7.1 目录内容

• sample-task.md：一份可以直接复制给 Codex 的任务。
• buggy-counter.js：一个带小 bug 的示例文件。

7.2 使用方式

在本目录运行：

codex "请阅读 sample-task.md，并按里面的要求处理 buggy-counter.js"

如果只想让 Codex 解释，不修改：

codex exec --sandbox read-only --ask-for-approval never "请解释 buggy-counter.js 的问题，不要修改文件"

7.3 练习目标

你要观察 Codex 是否能：

• 读懂任务目标。
• 找到 bug。
• 给出最小修改。
• 说明如何验证。

7.4 配套实践材料

以下材料已并入正文，便于阅读时直接对照和练习。

sample-task.md

# 示例任务

请修复 `buggy-counter.js` 里的计数逻辑。

## 背景

这个函数用于统计购物车里的商品总数。每个 item 有：

- `name`：商品名称。
- `quantity`：商品数量。

## 要求

- `quantity` 为数字时，累加到总数。
- `quantity` 缺失时，当作 0。
- `quantity` 小于 0 时，忽略该项。
- 不引入第三方依赖。

## 验收

- 请说明你修改了什么。
- 请给出至少 3 个手动测试样例。

八、总结

• 概念解释：| 能力 | 它在做什么 | 适合场景 |
• 你应该怎么使用它：一个好任务通常包含 4 个部分：
• 最佳实践：留下规范：重复出现的要求写进 AGENTS.md，而不是每次复制粘贴。
• 工程边界：| 审查 | 从风险角度看改动 | PR review、上线前检查 |
• 验证方式：它不只是聊天窗口里的“代码问答助手”，更像一个可以读项目、理解任务、编辑文件、运行命令、检查结果的协作者。
• 实现机制：你可以把它类比成一个前端团队里的高级同事：你给它需求、项目上下文和验收标准，它会自己看代码、提出修改方案、落地补丁，并尽量通过测试或命令验证结果。