第 1 章 任务定义与智能体指令

学习目标

• 把含糊的功能请求改写成带有可观察完成标准的任务指令。
• 把大功能拆成可以逐一运行、验证、回退的小任务。
• 根据任务的不确定性与影响范围，选择先获取计划还是直接下发任务。
• 审查智能体给出的计划，删除多余步骤，调整范围。
• 区分应写入仓库指南文件（AGENTS.md、CLAUDE.md、GEMINI.md）的内容与应交给其他机制的内容。

引言

一个周五晚上，一位独立创业者对编程智能体说“让注册更顺畅一些”，然后出门吃饭。回来时，智能体报告“任务已完成”，同时改了表单设计、密码规则，甚至软件包列表。由于缺乏判断哪些改动改善了功能、哪些破坏了功能的标准，他最终将改动全部回退。

这并非智能体能力不足。智能体认真执行了指令，并在“看起来做完了”的时候停下。问题是指令里没有说明终点在哪里、可以修改到哪里，以及用什么证明结果。

本章介绍将任务委派给智能体的人需要掌握的技巧。首先学习完成标准，以及一份好的任务指令应当具有的结构；接着学习如何把大功能拆分为小任务，如何让智能体遵循现有代码的实现方式。随后，我们将学习在什么情况下应当先获取计划、如何审查收到的计划，以及如何将每次都要重复说明的内容写入仓库指南文件。“深入阅读”部分讨论两类情况：业务规则尚未确定的功能，以及没有人在旁监督的任务。

核心概念

交付任务意味着什么

即使把工作交给编程智能体，结果的责任仍然由人承担。下发指令的人需要负责以下四件事。

1. 确定目标：确定要做什么、为什么要做，以及工作到什么程度才算结束。
2. 审查计划：确认智能体选择的方法是否符合目标与范围。
3. 确认结果：用证据判断结果，而非只看报告（第2章）。
4. 决定是否交付用户：留下记录（第3章），检查风险（第4章），决定是否交到用户面前（第5章）。

Claude Code最佳实践文档用一句话说明了这种关系：智能体会在任务“看起来已经做完”的时候停下来，如果没有能够自行运行的检查，“看起来是这样”就成了它判断完成的唯一信号。此时，人就必须充当验证负责人，亲自找出每一个错误。这就像只对装修公司说“把客厅装得漂亮一些”，即使对结果不满意，也没有可以据以交涉的标准。如果事先说清楚“墙面用白色，安装两盏暖色灯，原有的壁柜保持不动”，完工时就能逐项核对。

完成标准：预先定义“结束”

完成标准（definition of done）是事先写明的一组条件，使任何人检查工作是否结束时，都能够得出相同的结论。好的完成标准，应当能够通过查看界面或运行命令，判断条件是否得到满足。“做得更好”“整洁”“快速”这类形容词，每个人衡量的标准不同，因此不能作为完成标准。

把完成标准分成两类来写，可以减少遗漏。功能标准规定哪些功能必须能够正常运作（“点击4星后，只显示4星评价”），质量标准则规定需要遵守哪些条件（“现有测试全部通过”“不添加新软件包”“在较窄的屏幕上也不会出现布局错乱”）。

Claude Code最佳实践建议把完成标准写成智能体能够亲自执行的检查。列出几个示例输入与预期结果，再写上“实现后运行测试”，智能体就能自行修改，直到检查通过。

好任务指令的四个要素

好的任务指令通常包含四个要素，可以将其视为一份小合同。

1. 目标：要做什么。用户将能完成什么。
2. 完成标准：确认哪些事情后才算结束。
3. 范围与禁止事项：允许修改的范围，以及禁止修改的内容。
4. 验证方法：用哪些命令或检查程序证明完成，展示什么证据。

目标：在订单记录页面添加仅查看“配送中”订单的筛选器。
完成标准：
- 在筛选器中选择“配送中”，只显示状态为配送中的订单。
- 选择“全部”，恢复原列表。
- 添加验证上述两种情况的测试，npm test 全部通过。
范围与禁止事项：
- 只修改 src/pages/orders/ 内的文件。
- 不修改订单数据结构和支付相关代码。不安装新软件包。
验证方法：
- 展示执行的测试命令及完整输出，以及360px宽度的屏幕截图。

四个要素齐备，指令很短也可以。相反，即使写十行形容词，没有完成标准和范围，也无法判断结果。

定义正常画面之外的状态

描述一项功能时，人们通常只会想到一张所有事情都顺利完成的界面。然而，实际应用在到达这一界面之前，还会经历多种状态。如果指令中没有写出这些状态，智能体就会自行决定如何处理，或者干脆将它们遗漏。

要找全这些状态，一个办法是先画出用户流程（user flow）。按照顺序写明用户从哪里进入、点击什么、最终在哪里结束，然后在每一步问：“这时如果没有数据呢？响应很慢呢？操作失败呢？用户中途退出呢？”从这些问题中得到的答案，就可以直接成为完成标准。

拆小任务：纵向切分

交付的任务越大，修改的文件越多，审查越难；出问题时也越难定位是哪次变更造成的。因此，大功能要拆成小任务。此时，切分的方向很重要。

想一想蛋糕。若按层分开制作（只做蛋糕胚、只做奶油、只做水果），在完整的一块做好之前，谁都无法品尝。若纵向切分，每一块都会包含所有层，因此从第一块开始，就可以品尝。任务也是一样。

通过纵向切分得到的每个任务，都可以独立运行、独立验证，也可以单独回退。要判断一个任务的大小是否合适，可以看两个标准：能不能用一句话解释清楚这次改了什么，以及能不能在一次集中审查中把这次改动完整检查完。就像搬家时在每个纸箱上标注里面装了什么一样，按照“一项任务＝一个目的”的原则划分任务，后续检查与回退都会更加容易。

Anthropic的长时间运行智能体实验中，每个会话只交付一个功能也是关键做法，并为每个功能留下提交，以便出问题时回到先前状态。

指明现有代码范例后再下发任务

智能体知道实现同一项功能的多种方法。如果指令中没有作出说明，它就会从中选择一种，而这种方法可能与当前仓库采用的方式不同。如果错误的格式、校验输入的方法、组件的结构在各个文件中各不相同，应用就会变得越来越难以修改。

解决办法是直接指明应该遵循的现有示例。Claude Code最佳实践也建议，将一个现有文件指定为好的范例，让智能体遵循其中的做法，并明确限定：不要使用项目已经采用的库以外的库。这样能让智能体以这个仓库的实际代码为标准，比长篇解释更有效。

先阅读 src/api/products.ts 校验输入和返回错误的方式。
按相同方式在 src/api/coupons.ts 中创建优惠券查询API。
只使用 package.json 中已有的软件包。

先要计划

需要在初次接触的代码中添加一个涉及多个文件的功能时，先让智能体提交计划，比让它立刻开始写代码更安全。因为在计划阶段，就可以提前确认并调整将要修改的文件、工作的先后顺序，以及不允许触碰的范围。修改计划的成本，要比将已经写好的代码回退低得多。

Claude Code最佳实践建议采用探索、计划、实现、提交四个阶段。探索与计划在plan mode中进行。该模式读取文件、用只读命令探索，但不修改源文件。可按Shift+Tab切换，直到状态栏显示plan mode已开启，或通过claude --permission-mode plan启动会话。收到计划后，可用Ctrl+G在文本编辑器中直接修改，再继续。批准计划或再次按Shift+Tab切换模式后，就进入实现阶段。

其他工具也有类似机制。Gemini CLI的--approval-mode接受plan值。即使没有计划模式，也可以要求“先只制定计划，不要改文件”，但这句话不会改变权限，不能实际阻止修改文件。若必须阻止，就要用计划模式或只读权限。

审查计划的五个问题

一份看起来合理的步骤清单，并不一定就是好的计划。收到计划后，应当依次提出下面五个问题。

1. 是否对应需求：能不能把每个步骤与它所服务的某项需求一一对应起来？找不到对应需求的步骤，很可能已经超出任务范围。
2. 是否超出范围：是否包含禁止修改的文件，或无关的整理工作（“顺便整理公共组件”）？
3. 是否有难以回退的操作：是否包含批量修改现有数据、修改数据库结构、向外部发邮件等步骤？若有，将该步单独拿出来确认。
4. 是否包含验证步骤：计划的最后有没有写清楚，将通过哪些检查来确认哪些事情？
5. 大小是否合适：相对于一个很小的需求，这份计划是否过于庞大？有没有隐藏着引入新库、调整文件夹结构等需求中未曾提出的重大决定？

应当给出具体的审查反馈。例如，“删除第3步，不要修改现有会员数据”，或者“在第5步之前增加编写测试的步骤”。把步骤编号和理由一起告诉智能体，它才能准确地修改计划。

仓库指南文件：各工具如何读取

仓库（repository）是存放项目文件及其变更记录的文件夹。仓库中的指南文件是智能体每次开始会话时先读的说明备忘录，让团队不用重复同样的话，类似交给新员工的工作指南。

同时使用多种工具的团队，往往希望把共用内容集中在一份文件中维护。Claude Code文档说明，当CLAUDE.md与AGENTS.md同时存在时，默认只读取CLAUDE.md。如果希望共享同一份文件，可以在CLAUDE.md的最顶部写入@AGENTS.md，将其导入。也可以在个人设置中选择让两个文件一同加载的值（claude-md-and-agents-md）。@路径是Claude Code的导入语法，Gemini CLI也支持在GEMINI.md中使用@文件导入内容。对于Codex，可以通过~/.codex/config.toml中的project_doc_fallback_filenames配置其他备选指南文件名，让它识别使用这些名称的指南文件。

@AGENTS.md

## Claude Code专用
- 修改 src/billing/ 下的内容时，先用plan mode展示计划。

可以核实指南是否实际读取。Claude Code用/context查看加载的文件，Gemini CLI用/memory show展示拼接后的内容。Codex文档介绍了让智能体概括指南、核对读取顺序的方法。

指南文件应写什么

标准只有一个：只写仅靠读代码无法得知、但不知道就会犯错的内容。Claude Code最佳实践建议逐行问“删掉这一行，智能体会犯错吗？”不会就删。指南过长，真正重要的规则会被埋没而遭到忽略。

也要控制篇幅。Claude Code文档建议单个CLAUDE.md保持在200行以下。超过的内容按性质移到其他地方。

@路径导入有助于整理长文件，但导入内容也在会话开始时一起加载，因而不能减少加载量。首次创建指南文件，可先用Claude Code的/init等草稿生成命令（分析代码库生成草稿，已有文件则提出改进建议），再由人补充代码中看不出来的内容。

深入阅读

规则尚未确定的功能：访谈与规格说明

有时候，即使想写完成标准，也无法写出来。这通常是因为业务规则尚未确定，例如出现空余预约名额后，要给候补者多少分钟的优先权，如果没有回应，是否转给下一个人。这时如果直接把实现交给智能体，它就会用看似合理的猜测填补空白，而这些猜测会扩散到代码的各个位置。

Claude Code最佳实践建议，功能越大，就越应先让智能体对人进行访谈。只给它简短的说明，再让它通过AskUserQuestion工具详细提问；应跳过显而易见的问题，深入追问实现方式、界面、边界情况、顾虑，以及不同选项的优缺点等，人还没有想到的困难之处。提问结束后，再让它把结果写成SPEC.md之类的规格文件。

好的规格说明应当自成一体：明确列出相关文件与接口的名称，说明哪些工作不在本次任务范围内，并在结尾给出从头到尾的验证流程，用来证明整个功能确实能够正常运行。规格说明完成后，应当在新会话中开始实现。这样做，是为了让智能体在没有保留访谈过程冗长对话的干净上下文中，仅以规格文件为依据开展工作。文档也指出，花时间打磨规格说明，比花同样的时间盯着智能体实现功能更有价值。

访谈也能暴露人的盲点。“两位候补者几乎同时接受怎么办？”“优先权期限内课程取消怎么办？”这些问题能帮助运营者发现自己遗漏的情况。不过，规则仍由人决定。

上下文是一项预算

智能体在一次对话中参考的全部内容（消息、读取的文件、命令输出）称为上下文（context）。上下文有容量限制，Claude Code文档指出，随着上下文填满，智能体可能忘记先前指令、增加错误，因此称其为最需要管理的资源。

因此，指南文件应当保持简短，因为每次会话都会加载它；在两个互不相关的任务之间，应使用/clear清空上下文。执行一个任务时，中途又问了无关问题，然后再回到原任务，这样形成的“杂乱会话”是最常见的上下文浪费。需要浏览几十个文件的调查，则交给子智能体（subagent）完成。子智能体在自己独立的上下文中读取文件，只将调查摘要返回给主会话，因此正在进行实现工作的对话上下文能够得到保留。

无人值守的任务

把工作交给智能体通宵执行、对数百个文件批量应用同一项变更，或让运行在云端的智能体处理任务时，中途都没有人能够回答它的问题。越是这样的任务，指令本身就越需要完整、自足。

批量任务的顺序很重要。Claude Code最佳实践介绍的方法是：先把目标列表写入文件，再编写为每个目标调用非交互运行（claude -p "지시"）的脚本；全量执行前，先试两三个，根据暴露的问题修改指令。用--allowedTools预先允许所需工具，再用--permission-mode dontAsk让原本需要询问批准的调用直接被拒绝，而非提问（在工作目录内读文件等无需批准的操作仍照常执行）。用--max-turns限制轮数，也能停止在单个目标上徘徊的执行。先做小规模试验，才能避免同一错误扩散到全部目标。

云端智能体的情况也是一样。Codex的云端环境设置中，包含用于指定依赖安装脚本、环境变量与机密值，以及是否允许访问互联网、允许访问哪些域名范围的选项。测试所需的内容应提前准备齐全，但访问权限只开放到实际需要的程度。

工作场景

巷陌书店：回退十一个文件之后

社区书店“巷陌书店”的店主尹经理，想在读者评价区增加一个星级筛选功能。第一次只交代“帮我改善一下评价页面”，智能体就把设计、排序，甚至评价填写表单都改了，一共修改了十一个文件。尹经理没有办法判断哪些地方做对了，最后将所有改动全部回退。

第二次，尹经理把四个要素写齐，重新下发了指令。

1. 目标：在评价列表上方放置星级（1～5）筛选按钮。
2. 完成标准：点击4星后，只显示星级为4的评价；点击“全部”后，显示所有评价。如果所选星级还没有评价，就显示“暂时没有该星级的评价”。添加分别验证这三种情况的测试，并且npm test通过，才算工作结束。
3. 范围与禁止事项：只改评价列表页面。不改评价表单与数据库结构。
4. 验证：展示测试输出与浏览器截图。

尹经理一开始漏掉了空状态，后来画用户流程时才将它补上。因为可能会有顾客点击2星，而如果连一条2星评价都没有，顾客看到的就只会是一张空白界面。

考虑到可能需要修改多个文件，尹经理先通过plan mode获取计划。计划中包含一个步骤：“为评价表增加星级索引。”尹经理用五个问题逐一检查计划：这个步骤无法与任何需求对应（问题1）；它需要修改数据库，触及了明确禁止的范围（问题2）；而现有评价只有200条左右，在界面端进行筛选已经足够（问题5）。于是，尹经理删除了这个步骤，让智能体改为在界面端筛选。

智能体展示了测试输出和界面截图，尹经理又在浏览器中亲手点击操作，确认后才接受结果。两次尝试的区别，在于指令的结构，而不是智能体的能力。完成标准告诉了智能体应当在哪里停下来，而范围限制则帮助排除了计划中不必要的步骤。

浪声冲浪学校：纵向切分大功能

运营课程预约应用的“浪声冲浪学校”负责人都经理，想制作一项功能：“在海浪危险的日子，如果课程取消，就通知预约者，并完成退款处理。”这项功能横跨管理员界面、预约数据、短信发送，以及支付退款几个部分。

都经理最初想到三种办法。

• 一次交付全部任务：似乎只要下发一次指令就能完成。然而，需要修改的文件会超过二十个，即使发生错误退款，也很难查出是哪一项改动造成的。因此否决了这个选项。
• 按层拆分：按照数据结构、服务器、界面的顺序分别交付任务。这三个任务全部结束之前，没有任何实际能够运行的成果，因此无法在中途确认功能是否正常。这个选项也被否决了。
• 纵向切分：按照用户可以实际使用的成果单元来划分任务。都经理选择了这个办法。

都经理首先意识到，业务规则还没有完全确定。例如，如果在开课前两小时取消，是否应当全额退款，是否允许预约者选择替代课程，都还没有定下来。因此，都经理先让智能体进行访谈，逐一回答“已经选择了替代课程的人，是否也要发送短信？”等问题，借此确定规则，并将规则记录在SPEC.md中。

随后拆成三个任务。

1. 管理员将课程改为“因天气取消”时，预约者列表出现取消标记。暂不发短信、不退款。
2. 因天气取消后，给预约者发送且只发送一次通知短信。测试中不实际发送，只记录发送日志。
3. 预约者从通知链接选择“退款”后，发出撤销付款请求，预约状态变为“退款完成”。

每一个任务，都在新的会话中以SPEC.md为依据交给智能体。只有会触及支付代码的第三项任务，先通过plan mode获取了计划。看到计划中混入“整理支付模块的公共错误处理”这一项时，都经理认为它超出了范围，就将其删除。第一项任务完成的当天，管理员就已经能够实际使用取消标记。后来，在第三项任务中发现退款金额计算错误时，由于此前的任务已经验证完毕，只需在第三项任务的变更范围内寻找原因。

易错点

1. “指令写得越长、越详细越好。” 人们很容易觉得，写得长就会更准确。然而，即使罗列十行形容词，只要没有可以核对的条件，就无法判断结果。即使篇幅很短，只要完成标准、范围和验证方法清楚明确，这样的指令就更好。
2. “只要写进指南文件，智能体就一定会遵守。” 写在文件里的规则，看起来确实像规则。然而，指南只是智能体作出判断时参考的材料；内容太长或前后不一致，就会有某些行被遗漏。必须禁止的行为，应交给权限规则或钩子等能够强制执行的机制处理。
3. “要做到谨慎，所有任务都应当先获取计划。” 谨慎是优点，但计划真正能够发挥作用的，是不确定性较高、规模较大的任务。连能够用一句话解释清楚的修改也先索取计划，只会增加耗时。
4. “一次交付的任务越多，沟通往返越少，就越有效率。” 如果只看下发指令的次数，确实如此。然而，与减少的往返相比，增加的审查时间和回退成本更大。一旦出问题，甚至可能必须放弃整个大批次的变更。
5. “拆分功能的标准做法，就是按数据、服务器、界面的顺序来分。” 沿着技术结构拆分，看起来很整齐。然而，在最后一层完成之前，都无法确认功能是否实际正常运作。应当按照用户可以完成的一件事，纵向切分任务。
6. “既然智能体已经制定了计划，就可以相信这份计划。” 一份看起来合理的步骤清单很有说服力。然而，其中可能混有需求之外的整理工作、难以回退的数据变更，或者遗漏了验证步骤。应先用五个问题审查，再批准计划。

要点速览

查阅官方文档

• Claude Code: Best practices — 提供验证手段、探索→计划→实现→提交、何时跳过计划、访谈与规格、批量执行
• Claude Code: How Claude remembers your project — CLAUDE.md位置与加载顺序、@导入、.claude/rules/、AGENTS.md处理
• Claude Code: Skills — 技能文件位置与disable-model-invocation
• Codex: Custom instructions with AGENTS.md — AGENTS.md查找顺序、大小限制、替代文件名
• Gemini CLI: GEMINI.md — 指南文件层级、@导入、/memory、context.fileName
• Anthropic: Effective harnesses for long-running agents — 逐个交付功能与记录进度

自测

1-1. 有两个请求：（A）“让通知设置页面更好用些”；（B）“关闭通知后，次日早晨不再收到摘要邮件，刷新设置页面也保持关闭”。哪一个有完成标准？另一个应如何改写？

1-2. 要交付显示顾客以往预约记录的列表页面。除了正常页面，还应在指令中写明哪四种状态？为每种状态写一行完成标准。

1-3. 要给手工作坊体验预约应用添加“团体预约咨询”功能，需要咨询表单、管理员查看页面、受理通知邮件。将功能纵向切分成三项任务，各附一项完成标准。

1-4. 想直接修改Claude Code的plan mode计划中某一步的措辞后继续，应使用什么快捷键？再举一个可以不经过plan mode直接交付的任务例子。

1-5. 收到一个在商品详情页添加“到货通知申请”按钮的计划：①添加申请按钮与申请成功提示 ②添加保存申请记录的API ③整理整个应用按钮组件的颜色与间距 ④报告任务完成。用五个问题审查，这个计划有什么问题？你会如何反馈修改要求？

1-6. 仓库中只有团队使用的AGENTS.md，Claude Code原本能正常读取。一位成员在根目录创建存放个人备忘的CLAUDE.local.md后，只有该成员的会话开始不遵守团队规则。解释原因及解决办法。

1-7. 团队决定用TEAM_GUIDE.md一份文件管理智能体指南。要让Codex与Gemini CLI分别把它作为指南读取，各需修改什么设置？

实操练习