agentmentoragentmentor

第 01 节:把任务交清楚

本节 objectives:

  • 能把一句模糊需求改成 Codex 可执行任务。
  • 能写出目标、范围、验收和禁止事项。
  • 能判断什么时候先让 Codex解释,什么时候让它直接改。

先修:能打开 Codex 并进入一个项目 ｜ 上一节:无 ｜ 下一节 02 >>

Codex 不是搜索框,它在你的项目里动手

新用户最常见的失败,不是 Codex 不会写代码,而是任务像一句愿望:"帮我优化这个项目"。Codex 可以读仓库、编辑文件、运行命令,也会在交互式 CLI 里展示计划、diff 和命令审批点。任务写得太散,它会把上下文花在猜意图上。1

好任务像一张小工单:目标明确,只允许碰哪些地方,怎么验证,遇到不确定要先问还是先调查。OpenAI 的 Codex prompting 指南也强调,给代理任务时要说明目标、上下文、约束、成功标准和可用工具,而不是只丢一句结果愿望。2

讲解

把任务写成四块:

块问题例子
目标最终用户可见变化是什么"修复课程阅读站里 glossary tooltip 遮住正文的问题"
范围允许读写哪里"只改 course-reader/lib/glossary.ts 和相关测试"
验收怎么知道完成"新增/更新测试,跑 npm test -- glossary 通过"
安全哪些动作不要做"不要升级依赖,不要改样式系统"

如果你只是想理解项目,任务应该是读和解释:"先不要改代码,读 README、AGENTS.md、相关目录,画出执行路径。"如果你要 Codex 修改,任务要带验收:"实现后跑测试,最后列出改动文件和验证结果。"这两类任务不能混在一句话里。

还有一个实用句式:先让 Codex复述任务。它能暴露误解,也能让你在它动文件前收紧边界。

跟我做一遍(worked example)

模糊任务:

text
帮我修一下课程生成的质量。

改成 Codex 可执行任务:

text
你在这个仓库里工作。请先读agent-mentor/skills/generate-course-from-topic/SKILL.md、course-authoring-guide.md 和 docs/course-quality-rubric.md。
目标:找出 learn-mcp-server-basics 样课里最影响自学质量的 1-2 个问题并修复。范围:只改 agent-mentor/skills/generate-course-from-topic/examples/learn-mcp-server-basics/。验收:跑 node scripts/course-guard.mjs agent-mentor/skills/generate-course-from-topic/examples/learn-mcp-server-basics。安全:不要改 course-reader,不要提交 git。动手前先用三句话复述你读到的契约。

这段不是更长就更好,而是少了猜测空间。Codex 知道要先读什么、只能碰哪里、怎么证明完成。

换你补全(faded example)

把这句改成可执行任务:

text
让登录页好看一点。

请补全:

text
目标: ____________________范围: ____________________验收: ____________________安全: ____________________动手前要求 Codex: ____________________

参考答案:

text
目标: 改善登录页首屏的信息层级和按钮状态,不改登录逻辑。范围: 只改 app/login/page.tsx 和已有 CSS/module 文件。验收: 在桌面和手机宽度各截图一次;跑现有 lint/test。安全: 不新增依赖,不改 auth API,不改数据库。动手前要求 Codex: 先读登录页组件和现有设计约定,再给 3 步计划。

关键判断点是"好看"被拆成可观察的 UI 变化,且认证逻辑被明确排除。

小结 + 通向下一节

Codex 任务不是一句愿望,而是一张小工单。你写清目标、范围、验收和安全项,它就更容易先计划、再执行、再验证。

下一节把任务交出去之前的第一件事拆开:让 Codex 读项目,尤其是 AGENTS.md 和局部约定。

Footnotes

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

  2. Codex prompting — https://developers.openai.com/codex/prompting ↩

练习

Level 1: 找一个你想让 Codex 做的小任务,用四块格式写出来。

提示 1

先问"我现在要理解还是要改变?"。

提示 2

如果要改变,写验收。

提示 3

如果要理解,写证据类型。 常见错误剖析:把"不要乱改"当安全边界不够。Codex 需要的是具体边界,比如"不要改数据库 schema"、"不要升级依赖"、"不要触碰未跟任务相关的文件"。

自评