编程助手

Codex 怎样把任务交代清楚

用 OpenAI Codex 改代码时,把任务范围写小,用 AGENTS.md 记下仓库约定,并自己读 diff。命令和界面以官方文档为准,不确定的地方已标出。

作者 Niko约 4 分钟
本页目录

Codex 是 OpenAI 的编程助手,可以在终端里阅读仓库、修改文件、运行命令。它也可能出现在官方文档描述的其他入口。哪一种入口包含在你的账号里,以你登录后的官方页面为准,本文不列举套餐。安装、登录、第一个任务和报错按顺序收在 Codex 教程。

这篇接着讲怎样把任务写小、怎样自己读 diff。

开始之前,给账号打开两步验证,见 两步验证是什么,怎么绑定和换手机。不要把密钥写进仓库或对话。

把一次任务写小

说不清「做完是什么样」,助手就只能猜。一次只交一件能验证的事,并写明三件事:改哪里、不要改哪里、怎样算做完。

含糊的说法是「把项目优化一下」。能检查的说法是:「给设置页的保存按钮补上失败提示。不要改接口。改完运行现有测试,把失败的输出留在回复里。」

可以先让它用几句话复述将要改的文件和验证方法,你点头之后再改。范围一旦变大,就停下来拆开,不要在同一轮里追加很多新目标。

用 AGENTS.md 记下约定

官方说明:Codex 动手之前会读取名为 AGENTS.md 的说明。仓库里放一份,重复的规矩就不用每次重打。

撰写本文时,官方文档描述的发现顺序大致是:

  1. 先读 Codex 主目录里的全局说明。文档中的默认位置是 ~/.codex/AGENTS.md。如果设置了 CODEX_HOME,以那个目录为准。同一层若有 AGENTS.override.md,文档写的是优先使用覆盖文件。
  2. 再从仓库根目录走到你当前的工作目录,把沿途的说明按顺序接在一起。更靠近当前目录的文件出现得更晚,因此更能覆盖前面的说法。
  3. 空文件会跳过。合并后的体积有上限,超过的部分不再加入。

终端里的 /init 可以按当前目录生成一份初稿。生成后要删掉不符合这个仓库的句子,再提交。建议写进去的有:用哪个包管理器、测试和检查命令、代码风格、不能修改的目录、提交前要跑什么。不要写密码、密钥或顾客数据。

## 仓库约定

- 依赖用 npm。没有明确要求时,不要新增别的包管理器。
- 改完 JavaScript 后运行 npm test。
- 不要修改 dist/,也不要为了凑任务去改锁文件。
- 不要读取或打印 .env。

文档:

待店主核对:发现顺序、覆盖文件的优先级,以及体积上限的默认值,都以你打开文档时的页面为准。撰写本文时,文档里的默认上限大约是 32 KiB。安装命令和默认模型名称变化很快,本文故意不写死。若本地没有 /init 或 /review,以本地帮助里的命令列表为准。

自己读 diff

助手的摘要只是索引。提交前打开 git diff,至少看这几类问题:是不是改了无关文件,依赖版本有没有被带偏,测试是不是被删掉或被放宽,有没有把密钥写进代码,权限和删除操作是不是任务里要求的。

官方 CLI 文档里有 /review,用来再检查一遍改动。它可以指出你没注意到的地方,但不能代替你阅读 diff,也不能代替测试。测试通过、diff 也能解释,再提交。用 Git 留住任务前的状态,这样可以退回去。

和登录环境有关的风险,见 Claude 对使用地区和网络有什么要求。那篇讲的是另一个产品,但「不要让账号在很多地点之间跳」同样适用于这里。

一套可以重复的流程

  1. 在仓库目录启动 Codex,使用官方提供的登录方式。安装步骤只看官方 CLI 文档的当前页。
  2. 还没有 AGENTS.md 时,用 /init 生成初稿,删掉不适合本仓库的内容。
  3. 先用一个很小的任务试跑,看它会不会改出你划定的范围。
  4. 阅读 diff,运行测试,再决定是否保留。
  5. 下一轮只追加一个新目标,并写清怎样验证。

这个流程适合个人仓库和小组项目。它不能保证每次改动都正确,只能让错误更容易在提交前被看见。

常见问题

没有 AGENTS.md 能不能用 Codex?

能。这份文件的作用是把每次都要重复的约定放在仓库里。没有它,就在每次任务里把测试命令和禁区写清楚。

审查命令能不能代替自己看 diff?

不能。官方文档里的审查命令是再看一遍的辅助。提交前仍要自己读改动、跑测试,确认没有动到无关文件。

任务写得越大是不是越省事?

通常相反。一次塞进很多目标时,diff 会变长,很难判断哪一处是不该改的。拆成可以单独验证的小任务,返工更少。

文档和本地命令不一致怎么办?

以你打开的官方文档和本地帮助为准。本文标了待店主核对的句子,产品更新后那些句子可能过时。

安装、登录、第一个任务和报错按顺序收在Codex 教程。这篇接着讲怎样把任务写小、怎样自己读 diff。