意图工程：从模糊需求到可执行规范

第6章 意图工程：从模糊需求到可执行规范

第4章指出，冒进悖论和局部视野悖论有一个共同根源：智能体倾向于用可见的产出来替代理解，用局部范围内的优化来替代对整体目标的负责。第5章进一步说明，即使一次改动通过了全部确定性检查，也不能证明它真正解决了应该解决的问题。

本章提出的意图工程，正是针对这两类问题的第一层工程化回应。意图工程并不是要求开发者把提示词写得更长、更复杂，而是建立一套将模糊目标转化为可执行、可验收、可追责契约的方法。它从目标拆解和任务规划开始，通过任务简报（Mission Brief）明确工作范围与验收标准，通过自主性边界（Autonomy Envelope）划定智能体可以自行决策的边界，再通过承包商模型进一步明确委托关系中的责任划分。与此同时，AGENTS.md和CLAUDE.md等持久化机制，让这些约定能够跨越单次会话持续存在，而Planning Mode则把“先理解、再行动”的工作方式固化为稳定的工程流程。

意图工程解决的不是如何让智能体更快地产生代码，而是如何让它在获得更大自主性的同时，仍然围绕正确的目标行动。自主性越高，对任务边界、验收标准和责任归属的明确要求也越高。

读完本章，读者应能理解，为什么“先澄清、再授权”并不是一种牺牲效率的保守做法，而是让智能体能够承担更复杂任务的必要条件。只有当意图被转化为明确的约束和可验证的契约，智能体的执行能力才真正具有工程价值。

6.1 任务规划：目标分解与路径生成

面对一个复杂、多步骤的目标，如果智能体只依赖一次性生成，很容易在执行过程中逐渐偏离方向，或者忽略任务之间隐藏的依赖关系。任务规划解决的正是这一问题：要求智能体在真正执行之前，先将高层目标拆解为一组具有明确关系、可以逐步验证的子任务，形成一份可执行的行动计划，再根据计划推进工作。

这个过程类似于人类规划一次出行。一个人不会直接出现在目的地，而是先明确目标状态，了解当前位置，比较可能路径，再将整个过程拆解为购票、准备行李、前往车站等具有先后关系的步骤。在编码智能体场景中，这种对应关系同样成立：目标状态可能是“为IoTFlow平台增加设备异常告警能力”，初始状态是当前代码库中已有的设备接入、消息处理、时序存储和运维展示模块，而规划过程就是理解现有架构，判断哪些模块需要修改或新增，确定数据流转路径和验证方式，并将整个改造过程拆解为一组具有先后关系的可执行任务。

任务规划的核心特征是动态调整能力，而不是生成一份固定不变的执行清单。初始计划只是一个假设，智能体真正需要具备的能力，是在执行过程中根据新获得的信息重新评估路径。如果某个前提假设被证明错误，或者某个依赖关系比预期复杂，具备规划能力的智能体应当能够调整原有方案，而不是机械地沿着已经失效的路径继续执行。

这一点与第3章讨论的智能体循环“计划、行动、观察、验证”形成对应关系。任务规划关注的是“计划”这一阶段如何生成，以及如何根据反馈进行修正；智能体循环关注的是计划如何与后续行动、观察和验证连接起来，共同形成持续运行的控制回路。前者解决方向问题，后者解决执行过程中的闭环控制问题。

但需要注意的是，具备规划能力并不意味着所有任务都应该采用动态规划。规划是一种解决不确定问题的方法，而不是所有任务的默认流程。当任务路径已经明确、执行规则稳定时，采用固定流程往往更加可靠，因为它能够减少不必要的探索空间，降低行为的不确定性，保证执行结果的一致性。是否需要引入任务规划，关键取决于“如何完成任务”本身是否存在需要探索和判断的空间。如果路径已经确定，规划只会增加额外开销；如果路径依赖当前环境和实时信息进行判断，规划则成为不可缺少的环节。

放回本书提出的框架中，任务规划正是针对第4章冒进悖论的一种直接回应。冒进悖论描述的是智能体用可见的执行进展替代理解过程，而任务规划要求智能体在修改代码之前，先将自己对问题的理解显式化为一份行动计划。这一步迫使智能体回答“要解决什么问题”“为什么这样拆解”“下一步准备如何验证”等关键问题。

但规划本身并不能保证方向一定正确。它只能解决“是否形成计划”的问题，不能自动解决“计划是否建立在正确理解之上”的问题。一份基于错误目标生成的计划，同样可能逻辑严密、步骤完整，却把执行过程稳定地引向错误方向。因此，任务规划必须与后续讨论的任务简报、自主性边界结合使用：规划负责生成达到目标的路径，任务简报负责明确目标本身和验收标准，自主性边界负责限定智能体在路径选择和执行过程中的决策边界，三者共同构成完整的意图工程体系。

任务规划的价值也不局限于单个智能体的任务执行。当一个复杂目标被拆解为多个子任务之后，这些任务既可以由同一个智能体按顺序完成，也可以进一步分配给不同角色的智能体协同处理。这正是第16章和第17章讨论多智能体编排的基础。本章关注的是单智能体场景下的规划能力，读者可以将其理解为多智能体协作的最小单元：只有先让一个智能体能够正确拆解目标，后续才有可能有效组织多个智能体围绕共同目标协作。

6.2 任务简报：让意图成为可执行契约

任务规划解决的是“如何把目标拆解成路径”，但在此之前，还有一个更基础的问题：这个目标本身究竟是什么？

团队成员之间，尤其是人类与智能体之间，天然存在理解偏差。一句“把仪表盘做得更快一点”，可能被理解为优化数据库查询效率，也可能被理解为减少前端渲染开销，或者压缩传输数据量。这几种理解都符合字面含义，也都可能产生技术上合理的实现，但最终导向的是完全不同的改动方向。如果这种理解差异没有在行动前被显式消除，智能体就会基于自己的推断选择一种实现路径，并以很高的执行速度推进，直到验收阶段才暴露出双方对目标的理解并不一致。

任务简报正是用于解决这一问题。它的作用不是让智能体获得更多文字信息，而是在任务开始之前，将双方对目标、边界和完成标准的共同理解固化下来，形成一份可以被执行、检查和追溯的契约。

这里所说的任务简报，并不是传统意义上的任务描述文档，而是人类与智能体之间关于一次工作的共同约定。它定义的不是“智能体需要执行哪些具体步骤”，而是这项工作的权威边界：为什么要做、希望达到什么状态、哪些事情不在范围内、智能体可以自主决定什么、最终需要提供什么证据证明完成。换句话说，任务简报描述的是工作的“意图空间”和“责任边界”，而不是预先编排好的操作流程。它允许智能体在明确约束下自主规划和执行，同时保证人类仍然能够理解、检查并承担最终责任。任务简报通常包括以下内容：

1）目标与意图：明确希望达成什么目标，以及为什么要开展这项工作。

2）概念性计划：描述整体策略和关键检查点，而不是脆弱、僵化的操作步骤。

3）成功标准：通常采用属性和不变量的形式进行描述，用于定义什么状态可以被认为任务完成。

4）经过筛选的上下文指引：提供经过整理的信息来源和关键背景，而不是简单堆积大量原始资料。

5）实现指导：明确编码偏好、设计约定以及“禁止修改”的边界。

6）验证计划与证据义务：说明如何验证结果正确，以及需要提供哪些证据证明工作已经完成。

7）升级机制与权限边界：明确哪些决策可以由智能体自主完成，哪些情况必须暂停并请求人工确认。

8）版本管理与汇总机制：保持任务简报的版本演进记录，并将相关变化持续汇总，确保其始终作为工作的权威定义来源。

需要澄清一个常见误解：任务简报不是“写得更详细的提示词”，而是一份将意图、约束、决策权限和证据要求绑定在一起的工程制品。它至少包含四个核心部分。

第一，意图。回答“为什么要做这件事”。它需要说明目标、背景和约束条件，同时明确同样重要的非目标（non-goals）。例如，在IoTFlow项目中，如果任务是“提升设备接入网关的可维护性”，目标可能是降低新增协议适配的开发成本、改善模块边界，而非重新设计整个设备管理平台。明确非目标，可以防止智能体在探索过程中不断扩大任务范围，将一个局部优化演变成没有边界的系统重构。

第二，计划。描述解决问题的总体策略、关键检查点以及需要暂停并请求确认的情况，而不是把每一步操作提前写死。过度具体的步骤清单看似降低了不确定性，实际上可能限制智能体根据实际情况调整方案的能力。当现实情况与预设步骤发生偏差时，这种“伪确定性”反而可能诱导智能体机械执行错误路径。

第三，上下文。用于指定权威信息来源，包括相关代码位置、架构约定、已知限制以及历史决策。它的作用不是简单增加信息量，而是帮助智能体区分哪些信息可信、哪些约束必须遵守。在IoTFlow这样的持续演进系统中，一个协议适配模块为什么采用当前接口设计，某个数据字段为什么不能随意修改，这类背景知识通常不会完整体现在代码结构中，必须通过显式上下文传递给智能体。

第四，验收。验收部分定义什么才算真正完成，是任务简报中最关键的组成。好的验收标准应当描述属性和不变量，而不是简单罗列几个示例。例如，“无论输入何种合法设备状态，告警规则引擎都应产生一致且可解释的判断结果”描述的是系统属性；而“输入设备A、设备B、设备C时分别返回三个结果”只是几个具体案例。前者能够覆盖更多未知情况，使“完成”从主观判断转变为可以被验证的工程标准。

将验收标准从示例提升为属性，是对第4章两个悖论的直接回应。冒进悖论的问题在于，智能体容易用“产生了结果”替代“解决了问题”。属性化验收要求每个目标都对应可观察的证据，例如测试结果、性能指标、静态分析报告或人工确认记录，从机制上避免“看起来完成”的假象。局部视野悖论的问题在于，局部实现可能正确，但整体系统仍然错误。属性化验收则要求团队从系统层面定义成功标准。例如，对于IoTFlow中的协议适配任务，“新增协议后系统能够稳定采集设备数据，并通过统一接口接入告警和可视化模块”是系统级属性；“某个适配函数返回了正确数据”只是局部属性。如果任务简报只关注后者，就很容易重新陷入局部优化陷阱。

任务简报还有一个容易被忽视、但非常重要的设计原则：它必须像代码一样被版本管理。实际协作过程中，团队往往会通过讨论、评审和调试不断补充任务理解。如果这些变化只停留在聊天记录中，而没有同步更新任务简报，就会形成“任务简报漂移（Brief Rot）”现象：聊天记录和任务简报逐渐成为两个相互矛盾的信息源，智能体和后续接手者可能依据不同版本行动，最终导致目标偏移。

更可靠的做法是，将每一次影响目标、范围或验收标准的澄清，都转化为任务简报的一次正式修订，并记录修改原因。这样，任务简报本身也成为一种跨会话知识载体，回应第4章学习悖论中提出的问题：今天解决过的问题，不应该在下一次任务中重新消失。

任务简报也存在几类典型反模式。

第一类是把原始需求直接转交给智能体，期待它自行推断目标、约束和验收方式。这种做法实际上把最关键的需求澄清工作重新交给了一个无法承担最终责任的执行者。

第二类是使用“优化一下”“做得更好”“提升体验”等模糊表述作为验收标准。这类描述没有定义完成状态，智能体只能选择一个最容易证明完成的解释，而不一定是团队真正期待的结果。

第三类是任务粒度失衡。任务拆分过细，智能体只能完成孤立的代码操作，无法理解系统目标；任务范围过大，则难以定义明确的验收证据，评审也会失去有效依据。

判断任务粒度是否合适，可以采用一个简单标准：如果一个任务完成后，能够自然产生一组说明“改了什么、为什么改、如何证明正确”的证据包，并且该证据包可以支持一次有效评审，那么这个任务的边界通常是合理的。

任务简报的真正价值，不在于增加文档负担，而在于把原本存在于人脑中的隐含约定，转化为智能体能够理解、执行和接受检查的工程约束。只有当意图被明确表达，智能体获得的自主性才不会变成无边界的自由行动。

6.3 自主性边界与决策关卡

自主性边界是任务简报中的重要组成部分之一，它直接决定了智能体在一次任务中能够自主推进到什么程度，以及在什么情况下必须暂停并等待人类介入。自主性边界将决策权明确划分为三类：智能体可以自主决定的事项、需要上报并由指定角色作出决定的事项，以及无论如何都不得触碰的禁止事项。这一设计同时解决了两种常见的失衡。如果没有清晰的授权边界，智能体可能在不应自主决策的地方擅自做主；反过来，如果边界过于保守，智能体在本可以自主处理的事项上也事事请示，把大量琐碎确认变成沟通噪音，拖慢整个协作过程。将升级请示的对象明确到具体角色，而不是笼统地要求询问，则进一步使请示本身成为一种受控的决策流程，而不再是临时性的沟通打扰。

自主性边界对应的英文术语为“Autonomy Envelope”，它并不是一个简单的权限列表，强调的是在特定任务、特定风险条件下，允许智能体自主作出决策的范围。因此，本文将其译为“自主性边界”，重点突出其工程含义：它不是描述智能体“能做什么”的能力清单，而是规定智能体“可以自行决定什么”的授权范围。对于同一种操作，智能体可能具备执行能力，但并不意味着它拥有自主决策权；相反，一旦某项操作被明确纳入自主性边界，智能体就应当能够在无需逐项请示的情况下连续推进。

自主性边界和第5章第7节讨论的可逆性，实际上是同一个判断在不同层面的体现。第5章从整体委托姿态出发指出，恢复路径明确、代价有界的操作值得给予更宽的自主空间，而代价不可逆或者难以撤销的操作则需要收紧约束。自主性边界则把这一判断落实到单次任务内部的具体决策点上：哪些改动即使判断有误也能够随时回滚，可以纳入“自主决定”范围；哪些改动一旦执行就难以撤销，或者可能影响任务简报之外的系统边界，则应当划入“需要上报”甚至“禁止”范围。这也意味着，自主性边界不应当被理解为一次性写死的权限清单，而应当根据任务的风险和执行过程中获得的新信息进行调整。

当执行过程触及需要人工决策的边界时，需要有一份结构化的产物来承载这次请示，而不是一句松散的“我要不要继续”。这份产物应当明确说明当前需要作出的决策、可选方案、各方案的主要权衡，以及智能体的建议，再交由预先指定角色的人作出决定。决策一旦形成，还应连同决策理由一起记录下来，形成可追溯、可复用的决议记录。这份记录的价值并不只在于解决眼前的问题。当类似的决策点在后续任务中再次出现时，团队可以直接查阅既有决议，而不必重新讨论一遍。这实际上也是对第4章学习悖论的一种工程化回应：把一次性的现场判断转化为可以被后续任务复用的制度性知识。

自主性边界还需要与决策关卡结合起来理解。边界回答的是“智能体可以自行决定到哪里”，决策关卡回答的是“走到边界时，什么条件必须满足才能继续”。例如，在修改普通业务代码时，智能体可以自主完成实现、运行测试并整理结果；但如果准备修改认证策略、删除生产数据或者扩大外部网络访问范围，就应当触发相应的决策关卡，暂停执行并提交证据和方案供指定角色审批。这样，权限边界就不再只是写在任务简报中的文字，而成为执行流程中的实际控制点。

需要强调的是，自主性边界划定的是决策权，而不是对智能体执行能力的否定。被纳入“自主决定”范围的操作，应当允许智能体连续执行、减少不必要的人为打断，这恰恰是设置自主性边界的意义所在。它通过明确“哪些事情不需要问”，反过来保护了智能体在授权范围内的行动自由，使人类注意力能够集中于少数真正需要判断力的决策点，而不是被大量本可以自主处理的琐碎确认所消耗。

6.4 承包商模型：四根支柱

任务简报和自主性边界为单次委托建立了一份契约，而承包商模型则把这种契约关系推向了更完整的形态：把智能体从一个依赖简短指令、容易因理解偏差而失败的执行者，转变为一个通过正式契约建立协作关系、并且能够用客观标准核验交付结果的承包商。承包商模型建立在四根支柱之上：正式合同、动态协商与反馈、质量导向的迭代执行，以及分层分解与子合同，如图6-1所示。

图6-1 承包商模型的四根支柱

第一根支柱是正式合同。它是任务执行过程中的权威依据，承载的信息远远超过一句简短提示。一份典型的合同应当明确交付物的具体形式、覆盖的数据源与范围、功能和性能要求、时限以及验收标准。例如，在IoTFlow项目中，如果任务是开发设备告警分析模块，与其简单要求“增加一个告警分析功能”，不如明确规定：“基于设备遥测数据和告警记录，实现设备异常检测与告警聚合；支持MQTT和CoAP接入的设备数据；异常事件需要按照设备、时间窗口和告警等级进行聚合；提供REST API供运维控制台查询；在既有测试数据集上满足规定的检测准确率和响应时间要求，并补充单元测试和集成测试。”这样的描述把目标、范围、接口、性能和验收要求都转化成了可以核验的约束，也比一句“把告警功能做好”更不容易产生歧义。

第二根支柱是动态协商与反馈。这根支柱和6.3节讨论的自主性边界，本质上是同一机制在不同层面的体现：合同不是一条只能被动执行的静态命令，而是协作的起点。承包商智能体可以分析合同条款，发现其中的歧义、冲突或者不可行之处，并主动提出反馈。例如，IoTFlow的告警分析任务要求同时使用设备遥测数据和历史告警记录，但智能体检查代码库后发现当前版本只保存遥测数据，没有保留完整的历史告警记录。此时，它不应自行假设缺失数据的生成方式，更不能凭空构造历史数据，而应提出明确的协商请求：“当前系统缺少满足要求的历史告警数据。可以新增历史记录存储机制，也可以将验收范围调整为现有遥测数据；前者会扩大本次任务的实现范围，请确认采用哪种方案。”这样，智能体面对不确定性时的默认行为就从“自行填补空白”转变为“暴露问题并请求决策”。

第三根支柱是质量导向的迭代执行。承包商模型并不满足于生成一版看起来合理的结果后直接提交，而是要求智能体围绕合同规定的验收标准进行迭代验证。以IoTFlow为例，完成告警分析模块后，智能体不能仅仅报告“代码已经实现”，而应当运行合同中规定的单元测试和集成测试，检查MQTT和CoAP两类设备数据是否能够正确进入告警分析链路，验证异常检测和告警聚合结果是否满足约定的属性，同时检查API接口和性能指标。发现某项标准未满足时，应继续修改并重新验证，直到达到交付条件后再提交最终结果。这一支柱实际上把第5章讨论的“自我报告不等于验证”反向纳入了智能体自身的工作流程：与其等到外部评审发现明显问题，不如要求智能体在提交前主动生成和核对证据。虽然这种自检不能替代第9章讨论的独立验证，但能够显著减少明显不合格的产出进入评审队列。

第四根支柱是分层分解与子合同。一个复杂任务可以由主承包商智能体进一步拆解成若干相对独立的子任务，每个子任务对应一份独立的子合同，拥有自己的交付物和验收规范，再分配给专门的智能体完成。以IoTFlow为例，如果目标是构建完整的设备异常管理能力，可以将其拆解为“设计告警数据模型”“实现MQTT设备数据接入”“实现CoAP设备数据接入”“开发异常检测与告警聚合服务”“扩展运维控制台”“编写端到端测试”等子合同。每个子任务都有明确的输入、输出和验收标准，完成后可以独立验证，再由主承包商负责整合。这样一来，复杂度就被分散到多个可以独立管理和验证的单元，而不是全部堆积在一个无所不包的委托中。

这种结构化分解也为第16章、第17章讨论的多智能体协作提供了自然的组织形式：主合同负责界定整体目标、范围和最终验收边界，子合同负责把复杂目标拆解成可以独立委托和验证的工作单元。不同智能体之间不再只是简单地分工写代码，而是通过明确的交付物和验收标准形成具有清晰边界的协作关系。

值得指出的是，承包商模型的四根支柱，与6.2节讨论的任务简报以及6.3节讨论的自主性边界之间存在明显的对应关系。正式合同进一步强化了任务简报中的意图、范围和验收标准；动态协商与反馈对应自主性边界中的上报机制；质量导向的迭代执行强化了任务简报中的验收与证据要求；分层分解与子合同则将单次任务的契约机制进一步扩展到复杂任务和多智能体协作场景。两套框架虽然来自不同的知识库来源，但在核心思路上高度收敛。这种收敛也说明，把委托关系从一句简短指令升级为一份可协商、可验证、可分解的正式契约，是构建可控智能体协作关系的一条重要工程路径。

6.5 AGENTS.md与CLAUDE.md：把项目约定沉淀为持久化指令

任务简报解决的是单次任务的意图澄清问题，但一个团队里反复出现的项目级约定，例如构建命令怎么执行、测试怎么运行、代码风格有哪些要求、哪些接口不能随意修改，如果每次任务都要重新在简报里交代一遍，本身就是对第4章学习悖论的又一次重演：同样的背景信息一次又一次被重新解释。AGENTS.md和CLAUDE.md正是为了解决这一问题而出现的机制。它们把跨任务、跨会话都成立的项目级约定写入持久化文件，由智能体在适当的工作阶段读取，使这些约定从“每次都要重新交代”变成“写一次、持续复用”的项目记忆。

需要先澄清的是，AGENTS.md和CLAUDE.md并不是同一种文件格式，也不是某个统一标准的两个不同名称。它们分别对应不同编码智能体工具所采用的项目上下文机制。它们解决的问题高度相似，都是为智能体提供稳定、持久的项目级指令，但具体的文件层级、加载方式和支持能力取决于所使用的工具。因此，本节将二者放在一起讨论，是为了说明一种通用的工程思想，而不是暗示它们已经完全统一。

以Codex CLI采用的AGENTS.md为例，一份精炼的文件通常围绕构建与运行命令、提交规范、代码风格约定，以及项目特有的约束条件组织。文件本身并没有要求复杂的字段格式，普通的Markdown即可，但有一个容易被忽视的问题：可被智能体有效读取的上下文容量是有限的，过长的规则文件可能导致部分内容无法进入当前工作上下文。因此，最关键、最容易被遗漏的规则应当放在靠前的位置，而不是把所有项目文档都堆进同一个文件。在体量较大的单体仓库中，还可以按目录层级放置AGENTS.md，使不同子系统的任务只需要读取与当前工作范围相关的约定，而不必一次性加载整个仓库的规则。

Claude Code采用的CLAUDE.md在层级设计上更为丰富，可以分别承载组织级策略、用户级偏好、项目级团队约定，以及仅供个人使用的本地覆盖。智能体会根据当前工作目录和配置层级确定哪些规则适用于当前任务。对于大型项目，位于更深层级目录中的规则还可以在智能体真正进入相关目录时再加载，从而减少与当前任务无关的信息进入上下文。这种按范围组织项目规则的方式，本质上是在回答一个问题：什么规则应该在什么范围内对什么任务生效。

这里有一处技术细节尤其值得注意，因为它直接关系到本节所说的“指令”究竟有多强。项目上下文文件中的内容通常是作为上下文信息提供给模型，而不是操作系统级别的权限控制。因此，模型对这些规则的遵守仍然具有概率性，并不能提供类似文件系统权限那样的确定性保证。真正能够提供强制约束的，是第8章将讨论的权限控制、沙箱和工具调用策略，它们能够在工具实际执行之前直接拒绝不被允许的操作。

因此，更准确的理解是：AGENTS.md和CLAUDE.md提供的是持久化的约束性指导，而不是确定性的安全边界。它们比一次性的对话说明可靠得多，因为规则可以被持续复用，也可以随着项目演化而更新，但它们不能替代不依赖模型判断的强制机制。这一点再次呼应第5章的核心判断：即使规则已经被明确写下来，也不能因此假设智能体一定会按照规则行动；真正的可靠性仍然需要依靠独立的验证和强制执行机制。

这类文件还有一个重要价值，就是把项目知识从人的记忆和临时对话中提取出来，形成可以版本管理的工程制品。一个团队可能通过长期协作逐渐形成很多经验，例如某个接口虽然技术上可以修改，但会影响多个下游服务；某类测试必须在提交前运行；某个目录中的代码只能由特定模块调用。如果这些知识只存在于资深开发者的记忆里，智能体当然无法稳定获得。把其中真正需要反复遵守的规则写入项目上下文文件，相当于把个人经验转化为团队共享的显式约束，也因此成为应对第4章学习悖论的一种具体机制。

但项目上下文文件并不是写得越详细越好。一项由苏黎世联邦理工学院团队开展的系统性评估发现，让智能体自动生成上下文文件，在真实任务中不但没有提升任务完成率，反而使平均完成率出现下降，同时增加了推理成本；即便由开发者亲自撰写、针对具体代码库定制的上下文文件，收益也十分有限。研究还发现，上下文文件会促使智能体进行更广泛的探索，例如搜索更多文件、读取更多内容、执行更多测试，而其中额外增加的要求并不一定有助于完成任务。换言之，规则一旦写进项目上下文文件，智能体往往真的会认真对待它；因此，不必要的规则反而会成为额外负担。

这项观察给出的结论非常朴素：项目上下文文件应当只描述真正必要的最小要求，而不是试图承担完整项目文档的职责。这与第4章讨论的上下文悖论直接呼应。上下文的价值不取决于数量，而取决于有效信息密度。AGENTS.md和CLAUDE.md真正应该保存的，是那些跨任务稳定成立、违反后果明确、并且值得智能体反复遵守的规则，而不是把架构文档、开发教程和历史讨论全部复制进去。

下面给出一个结构性的AGENTS.md片段示例。它遵循IoTFlow项目已经确立的目录约定和验证命令，只展示网关模块需要长期遵守的信息，而不是完整的项目文档：

这份片段刻意保持精简，只登记会反复用到、违反后果又较为明确的几条约定，而不是试图把整个网关模块的架构说明都塞进去。比如“MQTT适配器负责什么”属于架构文档可以解决的问题，而“所有设备消息必须使用DeviceMessage结构”则属于智能体每次修改代码时都可能需要遵守的稳定规则，后者更适合进入项目上下文文件。

从这个角度看，AGENTS.md和CLAUDE.md真正解决的并不是“如何让智能体知道更多”，而是如何让智能体在每次工作时稳定获得那些真正重要、且值得重复遵守的信息。它们把一次性的沟通转化为持久化的项目约定，把个人经验转化为团队共享的工程制品，同时又通过控制内容范围避免重新陷入第4章所讨论的上下文过载问题。

6.6 Planning Mode：把“先规划、后执行”固化为工程流程

6.1节讨论的任务规划说明了智能体为什么需要在执行前先拆解目标、生成路径，而本节讨论的Planning Mode，则进一步把这一原则固化为一种具体的工程机制。在这一模式下，智能体被限制在只读状态，只能浏览文件、检索代码库、查阅文档和分析现有实现，但不能修改或创建文件，不能执行可能改变环境状态的命令，也不能提交代码。只有当它先产出一份完整的实施计划，并且该计划经过明确审阅和批准后，智能体才会退出这一模式，进入真正可以执行修改的阶段。

这种工作流程刻意模拟了资深工程师处理复杂问题时的典型方式：先收集背景信息，理解需求和系统约束，再设计解决方案，确认方向之后才开始实现。将这一习惯固化为工具支持的流程，而不是依赖每个人在每次任务中都自觉执行，本质上是一种工程化提升。它把“三思而后行”从一种个人经验，转变为协作流程中的结构性约束。

Planning Mode的价值在复杂系统或者需要深入理解大型代码库的任务中尤其明显。例如，一个涉及IoTFlow多个模块的改动，如果智能体直接开始修改代码，可能很快进入某个局部实现细节，却尚未理解设备接入、消息处理、数据存储和告警流程之间的依赖关系。相比之下，在Planning Mode下，智能体首先需要回答几个基础问题：当前架构如何组织，目标功能影响哪些模块，现有接口是否能够支持需求，哪些地方存在潜在风险，以及如何验证最终结果。最终形成的计划，本质上就是一次显式化的系统理解过程。

一种常见实践是将生成的计划保存为独立的Markdown文件，使其成为可以被团队成员评审、修改和持续引用的工程制品。这一步与6.5节讨论的AGENTS.md、CLAUDE.md机制形成自然衔接：经过审阅的计划不再只是某次对话中的临时产物，而可以成为项目知识的一部分，为后续任务提供背景信息。这也是Planning Mode回应第4章学习悖论的一种方式，即把一次性的理解过程转化为可保存、可复用的工程资产。

从更具体的角度看，Planning Mode的另一个价值在于提前暴露需求理解中的不确定性。一份高质量的实施计划通常应当说明目标范围、涉及模块、预期修改方式、验证方法以及潜在风险，而不是简单列出几个准备修改的文件名称。例如，对于IoTFlow新增设备协议适配功能，计划不应只是“新增mqtt_adapter.py并修改接口”，而应进一步说明新适配器如何接入现有消息封装机制，是否影响设备注册流程，如何验证消息解析、异常处理和告警链路。这种要求迫使智能体在行动之前先形成系统层面的理解，减少因为局部判断导致的错误实现。

这一点也与6.2节任务简报中“验收标准应表达为属性而不是示例”的要求一致。规格和计划越清晰，智能体自行定义“完成”的空间就越小。没有明确边界时，智能体可能生成一个技术上完整、测试也能通过的实现，却没有真正解决用户需要的问题；而经过规划和确认的任务，则把“应该做什么”和“如何证明做到了”提前固定下来。

当然，并非所有任务都值得进入Planning Mode。对于范围明确、修改集中在单个文件、验证方式简单的任务，直接执行通常更加高效；而对于涉及多个模块协同、影响系统架构、需求本身存在歧义，或者预计持续多个小时甚至跨越多个会话的任务，先规划再执行通常更加稳妥。一个实用判断标准是：如果错误实现需要返工多个模块，或者单靠代码差异无法判断修改是否正确，那么提前投入规划成本通常是值得的。

在肯定Planning Mode价值的同时，也需要避免对它产生过高期待。规划模式本身并不会自动产生正确方案，它的主要价值在于强迫智能体暂停行动、显式表达理解，并为人类提供一个介入和纠偏的机会。有观点指出，规划工具本身并不执行复杂计算，它的核心作用是把智能体的注意力锚定在明确目标上，避免执行过程中逐渐偏离初始意图。这个判断提醒我们：Planning Mode提供的是一种过程约束，而不是替代工程判断的自动化能力。

此外，还需要注意不同工具对Planning Mode的实现方式差异。一些工具中的“不可写入”限制主要通过提示层面的约束实现，而不是由运行时环境中的权限隔离强制保证。这意味着，在高风险任务中，不能仅依赖Planning Mode本身确保智能体不会修改环境，更稳妥的做法是结合版本控制分支、沙箱环境和权限限制，把可能的影响范围控制在可恢复范围内。这一点与6.5节关于AGENTS.md和CLAUDE.md的讨论是一致的，依赖模型遵守的规则，本质上仍然具有概率性，真正可靠的控制，需要与第8章讨论的沙箱、权限管理等确定性机制结合。

因此，Planning Mode的真正价值并不在于让智能体“想得更多”，而在于建立一个明确的协作节奏：先理解，再计划，再执行，再验证。它把原本容易被忽略的需求澄清和方案设计阶段重新放回智能体工作流程的中心位置，也是意图工程从抽象原则走向具体实践的重要一步。

6.7 小结：意图工程如何回应两个悖论

本章讨论的六种机制，看似分别来自不同的知识体系，使用着不同的术语，但放回第4章建立的诊断框架中，可以看到它们共同回应的是同一个核心问题：如何在赋予智能体自主性的同时，避免它用行动替代理解，又避免局部正确的实现脱离系统整体约束。

针对冒进悖论，任务规划要求智能体在真正执行之前，先显式表达对目标和路径的理解；任务简报进一步把目标、约束和验收标准转化为可以核查的契约，避免“看起来完成了”成为默认的完成定义；Planning Mode则把“先计划、后执行”从一种工程习惯提升为工具支持的流程关卡。三者共同形成了一条约束链：智能体不能直接从需求跳跃到实现，而必须先让自己的理解过程变得可观察、可讨论、可验证。

针对局部视野悖论，任务简报通过非目标定义和系统级验收属性，避免团队只关注某个文件或某个函数层面的局部正确性；承包商模型通过主合同与子合同的分层结构，要求被拆分后的子任务仍然服务于整体交付目标，而不是形成彼此孤立的局部优化；AGENTS.md和CLAUDE.md则把项目级架构约束、接口约定和禁止事项沉淀为持续可访问的项目记忆，减少智能体因为缺少背景信息而破坏系统一致性的可能。

其中，自主性边界是贯穿本章的一条主线。它并不直接对应某一个悖论，而是为上述机制提供统一的调节机制：决定哪些决策可以由智能体依据已有理解自主推进，哪些决策必须暂停并请求人工判断，哪些操作无论如何都不能由智能体执行。这一边界不应被理解为一次性固定的权限清单，而应根据任务风险、操作可逆性和已有可信证据动态调整，正如第5.7节讨论的“可逆性与信任校准”所强调的，自主性更像一个可以调节的旋钮，而不是简单的开启或关闭。

表6-1总结了本章六种意图工程机制、它们主要解决的问题，以及与后续章节的关联。

表6-1　本章六种意图工程机制与对应问题概览

意图工程解决的是“方向是否正确”的问题。它让智能体在行动之前明确目标、理解约束，并建立可验证的交付标准。但即使意图已经被准确表达，执行过程仍然会面临另一个现实挑战：智能体需要不断读取代码、文档、历史决策和工具反馈，而这些信息都会竞争有限的上下文空间。

因此，把意图澄清好、把任务契约建立起来，只是让智能体“朝正确方向出发”，并不能保证它在长时间工作过程中始终保持正确判断。一份精炼的任务简报，也可能在几十轮工具调用之后被大量临时信息稀释；一个设计良好的项目规则文件，也可能因为上下文过载而失去实际影响力。第7章讨论的上下文工程，正是在这一基础上继续推进：当任务简报、AGENTS.md、历史决议记录和工具反馈共同进入智能体工作集时，如何在有限的上下文预算内维持信息密度，使真正重要的知识始终处于可用状态。

本章要点

（1）意图工程是针对第4章冒进悖论与局部视野悖论提出的第一道工程化回应。其核心思想是在赋予智能体自主行动能力之前，先将任务理解显式化、可验证，并通过系统级约束防止局部优化偏离整体目标。

（2）任务规划要求智能体在执行前先将高层目标拆解为具有依赖关系的行动路径，并能够根据执行过程中获得的新信息动态调整方案。但规划只能保证“存在一份行动路径”，并不能保证路径建立在正确理解之上，因此必须与任务简报结合使用。

（3）任务简报（Mission Brief）不是更详细的提示词，而是一份用于约束智能体工作的任务契约。它将任务意图、概念性计划、上下文指针、属性化验收标准、自主性边界以及证据义务统一纳入管理。其中，将验收标准表达为可核查的属性而非简单示例，是避免“看起来完成”被误认为“真正完成”的关键设计。

（4）任务简报应当像代码一样进行版本管理。每一次影响任务目标、范围或约束的澄清，都应转化为简报的增量修订，并附带相应的决议记录。否则，聊天记录与任务简报可能逐渐形成两个相互冲突的信息源，导致“简报漂移”。

（5）自主性边界（Autonomy Envelope）将决策权划分为三类：智能体可自主决定的事项、需要请求人工介入的事项，以及明确禁止执行的事项。其范围应根据第5章讨论的可逆性原则动态调整，是控制自主程度的调节机制，而不是一次性固定的权限清单。

（6）承包商模型将人与智能体之间的委托关系进一步形式化，其正式合同、动态协商与反馈、质量导向的迭代执行、分层分解与子合同四个组成部分，分别对应任务定义、权限管理、验证机制和复杂任务拆解。这种跨来源框架的高度一致性，说明契约化委托正在成为构建可信智能体系统的重要方向。

（7）AGENTS.md与CLAUDE.md将项目级约定沉淀为跨会话持久化上下文，但其本质仍属于面向模型的指导性约束，而非操作系统级的强制机制。智能体对这些规则的遵守仍具有概率性，真正的确定性保障需要依靠权限控制、沙箱隔离等运行时机制。同时，项目上下文文件并非越详细越好，只有保持较高的信息密度，才能真正提升智能体效率。

（8）Planning Mode将“先规划、后执行”固化为一种工具层面的工作流程，尤其适用于跨模块改动或需求尚不明确的复杂任务。但它的价值在于约束行动方向，而不是自动保证方案正确；部分工具中的Planning Mode依赖提示层约束，而非运行时隔离，因此高风险任务仍需结合分支隔离、权限控制等机制。

（9）本章讨论的六类机制共同构成了意图工程体系：规划模式解决如何形成行动路径，任务简报解决目标和验收如何明确，自主性边界解决权限如何划分，承包商模型解决复杂委托如何组织，AGENTS.md与CLAUDE.md解决长期约束如何沉淀，Planning Mode解决规划如何进入执行流程。这些机制共同为后续章节讨论上下文工程、工具执行、验证测试和人类监督提供了基础。

延伸阅读

[1] Ahmed E. Hassan，《Agentic Software Engineering: Building Trustworthy Software with Stochastic Teammates at Unprecedented Scale》，2026年。该书第4章系统提出任务简报作为自主性契约、自主性边界与决策关卡的完整框架，并给出了详尽的反模式清单，链接：https://agenticse-book.github.io/。

[2] Antonio Gullí，《Agentic Design Patterns: A Hands-On Guide to Building Intelligent Systems》，2025年。该书第6章讨论目标分解与路径生成的适应性和边界，和第19章提出承包商模型的四支柱，ISBN：978-3032014016。

[3] Daniel Vaughan，《Agentic Coding with OpenAI Codex CLI》，2026年。该书第4章给出了AGENTS.md的结构规范，ISBN：978-1808348891。

[4] Eden Marco，《Agentic Coding with Claude Code: The everyday developer's guide to agentic coding with Claude Code》，2026年。该书第3章介绍了CLAUDE.md的层级加载机制，第6章介绍了Planning Mode的完整工作流程，ISBN：978-1806022595。

[5] Thibaud Gloaguen等，《Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?》，2026年。该研究系统评估了项目上下文文件对智能体任务表现的实际影响，链接：https://arxiv.org/abs/2602.11988。

[6] AGENTS.md官方网站，该网站介绍了AGENTS.md作为开放格式的设计初衷与基本结构，并持续更新其治理与工具支持状态，链接：https://agents.md/。

[7] Anthropic，Building Effective Agents，2024年。该文章讨论了工作流与智能体的架构分野，其中关于何时应当采用固定流程、何时应当采用动态规划的判断标准，链接：https://www.anthropic.com/engineering/building-effective-agents。