agents-with-receipts

03 — 任务框架与规划

适用工具：Claude Code · Codex（框架通用） · 验证于 2026-08

agent 拿到的第一条 prompt 决定它解决的是哪个问题。本章给出把任务写成 agent 能执行、能自查的方法：四要素结构、先规划后动手、先探索后编辑、以及可验证的完成条件。

3.1 用 Goal / Context / Constraints / Done-When 四要素写任务

场景：任务超过”改一行”的量级——多文件改动、修 bug、新功能——一句话描述会让 agent 自行脑补缺失的信息。

做法：

1. 按四段写 prompt，对应官方要求的四件事：说清要什么行为（Goal）、指向相关代码或复现步骤（Context）、保住关键约束（Constraints）、说明如何验证（Done-When）。

2. 模板（替换方括号内容后直接可用）：

   Goal: [要实现/修复的具体行为，一句话]
   
   Context:
   - 相关代码：@src/settings/save.ts @src/api/client.ts
   - 复现步骤：
     1) npm run dev
     2) 打开 /settings，切换 "Enable alerts"，点 Save
     3) 刷新页面：开关被重置
   
   Constraints:
   - Do not change the API shape.
   - Keep the fix minimal and add a regression test.
   
   Done-When:
   - 上面的复现步骤不再触发 bug
   - npm run lint && npm test -- settings 全绿，贴出命令和输出
   

3. 坏/好对比：

   坏	好
   “fix the login bug”	“用户反馈 session 超时后登录失败。查 src/auth/ 的 auth flow，重点看 token refresh。先写一个复现该问题的失败测试，再修复它”

依据：Codex 官方 prompting 指引要求 prompt “names the behavior you want, points to the relevant code or reproduction steps, preserves important constraints, and says how to verify the change”，其 bug 修复工作流示例正是这个结构（Prompting Codex）；坏/好对比出自 Claude Code 最佳实践。

边界：一句话能说清 diff 的小改动（改 typo、加一行 log、重命名变量）直接下指令，四要素是负担不是帮助。探索性提问也不用套模板——”这个文件你会改进什么？”这类模糊 prompt 在你能承受纠偏成本时反而能带来意外收获。

反模式：四段都写满但 Done-When 只有”确保正常工作”——等于没写。

3.2 复杂任务先进 Plan mode，或让 agent 反向面试你

场景：方案不确定、改动跨多文件、或你自己说不清完整需求——直接开写大概率解决错误的问题。

做法：

1. Claude Code：按 Shift+Tab 切到 plan mode（状态栏显示 ⏸ plan mode on），或启动时指定；单条消息计划用 /plan 前缀。

   claude --permission-mode plan
   

   plan mode 下 Claude 只读文件、跑探索命令、写计划，不改源码。计划就绪后按 Ctrl+G 可在编辑器里直接修改计划再批准；批准即退出 plan mode 开始执行。

2. Codex：在 app composer 输入 /plan，让它先调查并提出方案再动手编辑；IDE 里有 $plan skill 时显式调用它产出重构计划，再逐条谈判修订。

3. 需求本身模糊时，反过来让 agent 面试你，产出 spec 后另开新会话执行：

   I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.
   
   Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.
   
   Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.
   

依据：Claude plan mode 的进入方式与只读行为见 Permission modes；Codex /plan 与 $plan 入口见 Prompting Codex；面试式 prompt 模板逐字出自 Claude Code 最佳实践。

边界：Anthropic 官方明说 plan mode 有额外开销：”如果你能用一句话描述 diff，就跳过计划”。计划最值钱的三种情况：方案不确定、改动跨多文件、你不熟悉被改的代码。

反模式：把 plan mode 当免死金牌——每个 typo 修复都先出一页计划，会话烧在仪式上。

3.3 不熟的仓库先让 agent 探索，再动手编辑

场景：接手陌生服务、新加入的仓库、或要改的模块你从没读过。

做法：

1. 在 plan mode 里先下纯探索指令，不带任何编辑要求：

   read /src/auth and understand how we handle sessions and login.
   also look at how we manage environment variables for secrets.
   

2. 像问资深工程师一样提问：”How does logging work?”、”How do I make a new API endpoint?”、”What edge cases does CustomerOnboardingFlowImpl handle?”——官方确认这类问题不需要特殊 prompt 技巧，直接问。
3. 探索完成后再要计划、再实现，走完整四阶段：Explore → Plan → Implement → Commit。

4. Codex 对应工作流：打开或 @ 附上相关文件，让它解释请求流再动手：

   Explain how the request flows through the selected code.
   
   Include:
   - a short summary of the responsibilities of each module involved
   - what data is validated and where
   - one or two "gotchas" to watch for when changing this
   

依据：Anthropic 官方推荐工作流是 “Explore first, then plan, then code”，四阶段与探索 prompt 均出自 Claude Code 最佳实践；Codex 的 “Explain a codebase” 工作流见 Prompting Codex。

边界：已熟悉的代码路径重复探索只烧上下文。探索的产出（结论、涉及文件清单）应固化进计划或 spec 文件，不要依赖对话记忆——对话会被压缩，文件不会。

3.4 把关键约束写进首条 prompt，用 @ 精确附上文件

场景：任务有不可违反的红线（API 形状不能变、已批准的数字不能改），或你已经知道该看哪些文件。

做法：

1. 约束在 agent 动手之前就写进 prompt 的 Constraints 段，只留一两条最要命的，不要等它做错再纠正：

   Constraints:
   - Do not change the API shape.
   - Use only the supplied sources. Flag missing information instead of guessing.
   

2. 用 @ 直接引用文件，代替描述”代码大概在哪”：Claude Code 里写 @src/auth/token.ts，agent 回答前会先读该文件；Codex CLI 里用 @ 路径自动补全，或用 /mention 附加指定文件。
3. 记住各 surface 的默认上下文差异：Codex IDE 扩展自动带上你打开的文件；CLI 里必须显式写路径或 @ 附件。

依据：Codex 官方指引把 boundaries 定义为”防止改错一个细节导致整个结果作废”的少数几条指令，并要求”聚焦最重要的一两条”；其 bug 工作流注明复现步骤和约束 “matter more than a high-level description”（Prompting）；@ 文件引用与 IDE/CLI 上下文差异见 Claude Code 最佳实践与 Prompting Codex。

边界：对每次会话都成立的规则（测试命令、代码风格、禁改目录）属于 AGENTS.md / CLAUDE.md 这类 memory 文件，不该在每条 prompt 里重复；prompt 里只留本任务特有的约束。

反模式：”别忘了遵守我们的编码规范”——agent 不知道你的规范是什么，也没被给到写着规范的文件。

3.5 把 Done-When 写成可执行的检查，不是形容词

场景：任何你打算离开屏幕的任务，或打算一次接受较大 diff 的任务。

做法：

1. 完成条件写成 agent 自己能跑、能读到 pass/fail 的东西：测试命令、构建退出码、linter、对比 fixture 的脚本、浏览器截图对照。

2. 在 prompt 里写明具体用例和”实现后要跑测试”：

   write a validateEmail function. example test cases: user@example.com is true,
   invalid is false, user@.com is false. run the tests after implementing
   

3. 修复类任务要求 agent 修完重跑复现步骤，并跑最小相关检查：

   After the fix, run lint + the smallest relevant test suite. Report the commands and results.
   

4. 要证据不要断言：让 agent 贴出测试输出、执行过的命令及返回值、或结果截图。你审证据比自己重跑验证快，也覆盖你不在场的会话。

依据：Anthropic 官方：”Claude stops when the work looks done”——没有可跑的检查时你本人就是验证环节，每个错误都要等你发现；给出 pass/fail 信号后循环自动闭合（Claude Code 最佳实践）。Codex 同样要求 prompt “says how to verify the change” 并在修复后重跑 repro（Prompting Codex）。

边界：检查本身要快——完成条件挂在十分钟的全量集成测试上，agent 的自查循环会退化成你等结果；挂最小相关测试集，全量检查留给 CI。验证闭环的升级形态（test-first、独立评审、Stop hook 硬门禁）见验证闭环一章。

反模式：Done-When 写”代码质量高、无明显问题”——没有命令、没有测试名，agent 无法自查，只能”看起来完成了”就停。

This site is open source. Improve this page.