agentmentoragentmentor

第 02 节:先让 Codex 读项目

本节 objectives:

  • 能让 Codex 先读项目指令和相关文件,再动手。
  • 能解释 AGENTS.md 对 Codex 的作用。
  • 能判断读项目时该用宽搜索还是窄文件路径。

先修:能写出目标、范围、验收和安全项 ｜ 上一节 << 01 ｜ 下一节 03 >>

你不需要把整个仓库塞进 prompt

新手常把大量文件复制给 Codex,像把一箱零件倒在桌上。更稳的做法是让 Codex 在项目里自己定位:先读项目说明、局部约定、相关文件,再说明它看到的路径。

Codex 会在开始工作前读取 AGENTS.md 等项目指令。官方说明里,它会从全局范围和项目路径逐层发现这些文件,越靠近当前工作目录的指令越靠后出现,也就更能覆盖前面的通用规则。1 所以你要问的不是"我怎么把所有规则粘给它",而是"当前任务所在目录有没有该读的规则"。

讲解

读项目的顺序可以很朴素:

  1. 读用户给的任务和当前工作目录。
  2. 读根目录 README、AGENTS.md、package/scripts 或等价入口。
  3. 用索引、符号工具或 rg 找相关文件。
  4. 读最小必要文件,归纳真实执行路径。
  5. 再提出计划。

如果你已经知道文件路径,直接给路径,不要让 Codex 全仓搜索。如果你只知道现象,给现象和复现步骤,让 Codex 先定位。Codex CLI 的交互模式适合这种边读边问的流程,因为你能实时看到它的计划、命令和 diff。2

读项目还有一个反面:不要一上来要求 Codex "重构全项目"。先让它回答"当前机制是什么",再让它改最窄的一刀。

跟我做一遍(worked example)

任务:你想知道课程生成 skill 为什么要求 glossary.json。

给 Codex:

text
先不要改代码。请读:- agent-mentor/skills/generate-course-from-topic/SKILL.md- agent-mentor/skills/generate-course-from-topic/course-authoring-guide.md- scripts/course-guard.mjs
回答三个问题:1. glossary.json 是交付物还是可选文件?2. guard 具体检查哪些字段?3. 如果我要新写一门样课,最小合格 glossary 应该长什么样?请用文件路径和规则原文附近的证据回答。

这里你没有让 Codex 猜。你指定了本地真实机制,也把输出限定成证据回答。课程生成 skill 的契约确实要求 README.md、若干 NN-*.md、sources.md 和 glossary.json,并且 guard 会检查 glossary 的 term、def、source。34

换你补全(faded example)

你遇到一个 bug:"搜索结果里术语 tooltip 没有出现。"请补全读项目 prompt:

text
先不要改代码。请先读:- ____________________- ____________________- ____________________
然后回答:1. ____________________2. ____________________3. ____________________

参考答案:

text
先不要改代码。请先读:- course-reader/lib/glossary-load.ts- course-reader/lib/glossary.ts- course-reader/lib/search.ts
然后回答:1. 术语数据从哪里加载?2. search 页面是否会经过 glossary 包裹逻辑?3. 如果没有,最小改动点在哪里?

关键判断点是先找数据流,不是先改 UI。

小结 + 通向下一节

Codex 会读项目,但你要给它正确的读法:先规则,再入口,再相关实现,最后计划。让它在动手前说清读到了什么,你就更容易发现跑偏。

下一节看 plan 和 status:Codex 开始工作后,你怎么判断它是在推进,还是在消耗上下文。

Footnotes

  1. Custom instructions with AGENTS.md — https://developers.openai.com/codex/guides/agents-md ↩

  2. Codex CLI features — https://developers.openai.com/codex/cli/features ↩

  3. generate-course-from-topic SKILL.md ↩

  4. course-guard.mjs ↩

练习

Level 1: 在你的项目里选一个你不熟的功能,写一条"只读定位"任务给 Codex。

提示 1

路径明确时,直接给路径。

提示 2

路径不明确时,给现象和复现。

提示 3

要求证据,少要观点。

自评