编程助手
Codex 怎样把任务交代清楚
用 OpenAI Codex 改代码时,把任务范围写小,用 AGENTS.md 记下仓库约定,并自己读 diff。命令和界面以官方文档为准,不确定的地方已标出。
本页目录
Codex 是 OpenAI 的编程助手,可以在终端里阅读仓库、修改文件、运行命令。它也可能出现在官方文档描述的其他入口。哪一种入口包含在你的账号里,以你登录后的官方页面为准,本文不列举套餐。安装、登录、第一个任务和报错按顺序收在 Codex 教程。
这篇接着讲怎样把任务写小、怎样自己读 diff。
开始之前,给账号打开两步验证,见 两步验证是什么,怎么绑定和换手机。不要把密钥写进仓库或对话。
把一次任务写小
说不清「做完是什么样」,助手就只能猜。一次只交一件能验证的事,并写明三件事:改哪里、不要改哪里、怎样算做完。
含糊的说法是「把项目优化一下」。能检查的说法是:「给设置页的保存按钮补上失败提示。不要改接口。改完运行现有测试,把失败的输出留在回复里。」
可以先让它用几句话复述将要改的文件和验证方法,你点头之后再改。范围一旦变大,就停下来拆开,不要在同一轮里追加很多新目标。
用 AGENTS.md 记下约定
官方说明:Codex 动手之前会读取名为 AGENTS.md 的说明。仓库里放一份,重复的规矩就不用每次重打。
撰写本文时,官方文档描述的发现顺序大致是:
- 先读 Codex 主目录里的全局说明。文档中的默认位置是
~/.codex/AGENTS.md。如果设置了CODEX_HOME,以那个目录为准。同一层若有AGENTS.override.md,文档写的是优先使用覆盖文件。 - 再从仓库根目录走到你当前的工作目录,把沿途的说明按顺序接在一起。更靠近当前目录的文件出现得更晚,因此更能覆盖前面的说法。
- 空文件会跳过。合并后的体积有上限,超过的部分不再加入。
终端里的 /init 可以按当前目录生成一份初稿。生成后要删掉不符合这个仓库的句子,再提交。建议写进去的有:用哪个包管理器、测试和检查命令、代码风格、不能修改的目录、提交前要跑什么。不要写密码、密钥或顾客数据。
## 仓库约定
- 依赖用 npm。没有明确要求时,不要新增别的包管理器。
- 改完 JavaScript 后运行 npm test。
- 不要修改 dist/,也不要为了凑任务去改锁文件。
- 不要读取或打印 .env。
文档:
- CLI 入门:https://learn.chatgpt.com/docs/codex/cli
- AGENTS.md:https://learn.chatgpt.com/docs/agent-configuration/agents-md
- 官方菜谱里的工作流示例:https://developers.openai.com/cookbook/examples/codex/iterating-development-workflows-with-codex
待店主核对:发现顺序、覆盖文件的优先级,以及体积上限的默认值,都以你打开文档时的页面为准。撰写本文时,文档里的默认上限大约是 32 KiB。安装命令和默认模型名称变化很快,本文故意不写死。若本地没有
/init或/review,以本地帮助里的命令列表为准。
自己读 diff
助手的摘要只是索引。提交前打开 git diff,至少看这几类问题:是不是改了无关文件,依赖版本有没有被带偏,测试是不是被删掉或被放宽,有没有把密钥写进代码,权限和删除操作是不是任务里要求的。
官方 CLI 文档里有 /review,用来再检查一遍改动。它可以指出你没注意到的地方,但不能代替你阅读 diff,也不能代替测试。测试通过、diff 也能解释,再提交。用 Git 留住任务前的状态,这样可以退回去。
和登录环境有关的风险,见 Claude 对使用地区和网络有什么要求。那篇讲的是另一个产品,但「不要让账号在很多地点之间跳」同样适用于这里。
一套可以重复的流程
- 在仓库目录启动 Codex,使用官方提供的登录方式。安装步骤只看官方 CLI 文档的当前页。
- 还没有 AGENTS.md 时,用
/init生成初稿,删掉不适合本仓库的内容。 - 先用一个很小的任务试跑,看它会不会改出你划定的范围。
- 阅读 diff,运行测试,再决定是否保留。
- 下一轮只追加一个新目标,并写清怎样验证。
这个流程适合个人仓库和小组项目。它不能保证每次改动都正确,只能让错误更容易在提交前被看见。
常见问题
没有 AGENTS.md 能不能用 Codex?
能。这份文件的作用是把每次都要重复的约定放在仓库里。没有它,就在每次任务里把测试命令和禁区写清楚。
审查命令能不能代替自己看 diff?
不能。官方文档里的审查命令是再看一遍的辅助。提交前仍要自己读改动、跑测试,确认没有动到无关文件。
任务写得越大是不是越省事?
通常相反。一次塞进很多目标时,diff 会变长,很难判断哪一处是不该改的。拆成可以单独验证的小任务,返工更少。
文档和本地命令不一致怎么办?
以你打开的官方文档和本地帮助为准。本文标了待店主核对的句子,产品更新后那些句子可能过时。
安装、登录、第一个任务和报错按顺序收在Codex 教程。这篇接着讲怎样把任务写小、怎样自己读 diff。