让编码 Agent 少返工：先写验收，再调推理强度

description: 编码 Agent 反复返工，可能源于任务信息不完整，也可能源于推理投入不足。以历史模型的使用建议和分页修复示例为切口，学习如何明确验收、要求工具证据，并比较完成任务的总成本。 tags: [编码 Agent, Claude Code, 提示词, 推理强度, 工程验收]

让编码 Agent 少返工：先写验收，再调推理强度

设想一个常见场景：让编码 Agent 修复分页问题，它改完了；你补充“排序也要稳定”，它又改了一遍；最后才想起旧客户端还依赖原来的响应字段，于是第三次返工。

如果这时只比较模型用了多少 token，很容易把需求补全的成本算成模型推理低效。即使提高推理强度，模型也无法可靠推断一条从未告知、代码中又看不出的兼容约束。

以旧模型 Opus 4.7 在 Claude Code 中的使用建议为例，Anthropic 在 2026 年 4 月发表的文章已经讨论过这类成本问题。模型会更新，先明确验收、再比较推理投入的做法仍值得保留：它帮助我们区分信息不足和能力不足，也能用来评估下一个模型。

比较模型成本，先看它接到的任务是否完整

在这个历史案例中，官方提醒：分词器变化和较高强度下的思考会影响 token 用量，多轮交互也可能增加推理开销。本文于 2026 年 9 月 7 日核对了这篇发表于 4 月 16 日的文章；以下具体档位和默认行为均指向当时的模型说明。

这里的 token 是模型处理文本时使用的计量单位；分词器负责把文本转换为这些单位。同样的文字在分词方式变化后，用量也可能变化，因此升级前后只看 token 数，不能直接判断模型是否做了更多有效工作。

在这个案例中，effort 表示模型的推理投入级别。官方一方面建议首轮提供目标、约束、验收标准和文件位置，另一方面给出了不同 effort 档位的选择建议。这里有两个需要分别检查的变量：任务提供了什么信息，以及模型投入多少推理来处理信息。

具体档位属于产品设计，任务是否明确则可以独立检查。以下分页案例和比较方法是本文的应用示例；迁移到其他模型时，需要重新核对可用设置，并用项目验收验证效果。

把“修好分页”改成可以判定对错的任务

“修复分页，保持兼容”看起来已经明确，实际仍留下了几个决定：什么现象算故障，排序冲突如何处理，哪些行为必须保留。

下面是假设项目的一份任务说明。路径和命令应替换成项目中实际存在的内容。

目标：修复订单列表在相同创建时间下跨页出现重复记录的问题。

上下文：从订单列表路由及对应查询函数开始检查，定位现有分页测试。
复现条件：构造多条创建时间相同的订单，按当前默认顺序连续取两页。

约束：保留现有响应字段、默认页大小和外部调用方式。
本次不引入新的分页协议；如果现有协议无法满足要求，先说明冲突。

验收：在静态数据集上，两页订单 ID 不重复；相同输入重复查询顺序一致；
已有接口兼容测试通过。

交付：说明根因、修改位置、实际执行的验证及未覆盖的情况。

这份说明的价值在于收窄了解空间。例如，“静态数据集”明确了验证前提：它没有要求同时解决翻页期间新增或删除记录的问题。

如果业务需要在并发写入下也不重不漏，那是另一条验收要求，需要先讨论分页语义。仅仅把“稳定”写得更强烈，无法替代这个决定。

官方当时建议把问题集中提出，减少必须等待用户回复的轮次，并在合适任务中配合 auto mode 和完成通知。通知可以通过 hook 实现，也就是在特定事件发生时触发动作的机制。

这几项分别减少了信息补充、操作确认和人工盯守的负担。它们不能互相替代：即使执行过程不再频繁暂停，遗漏的兼容要求仍然会造成返工。换用其他工具时，也可以按这三类负担检查工作流。减少确认之前，应先明确哪些操作允许自动执行、哪些必须由人决定。

验收失败之后，先判断缺信息还是缺推理

把模型的失败笼统归为“不够聪明”，会导致所有问题都走向提高 effort。更有效的诊断顺序如下。

这张图把提高推理投入放在需求和证据之后。例如，模型保留了错误的返回字段，先检查兼容要求是否明确；模型没有复现重复记录，先检查测试数据是否包含相同时间戳。

只有当要求清楚、相关代码可访问、复现条件也成立，模型仍反复选错方案时，提高推理投入才是值得单独验证的变量。这个顺序是排查方法，不保证每次失败都只有一个原因。

更高的推理投入，需要额外收益来证明

对于提供推理强度选项的模型，可以先以该模型推荐的档位建立基准，再比较增减投入的结果。下面保留 Opus 4.7 当时的档位作为例子，展示“任务难度—投入—代价”的取舍；它不代表其他模型也有这些选项，或同名档位具备相同能力。

分页案例如果已经定位到具体查询，修改范围很小，就有理由比较较低投入能否完成。如果问题横跨查询、缓存和接口兼容，则先在推荐档位建立基准，再判断是否需要增加投入。这里的任务映射是本文建议，是否合适仍由验收结果决定。

还要区分推理强度与固定思考预算。在 Opus 4.7 的设计中，固定预算的 Extended Thinking 不受支持，取而代之的是自适应思考：模型根据当前步骤决定是否思考、何时投入更多思考。对采用这种机制的模型，选择较高 effort，不意味着每一步都必须消耗相同数量的思考 token。

下面用分页任务说明“按步骤分配”的含义，而非展示模型内部必然发生的过程。

三个步骤需要的判断不同，固定地要求每一步都深入思考，未必带来同等收益。在这个案例中，官方还建议通过提示词表达偏好，例如要求认真分析难点，或优先快速回应；同时也提醒，减少思考可能降低困难步骤的准确性。换用其他模型时，提示词是否能有效改变投入，也需要实际比较。

“自适应思考更少过度思考”和“max 更容易过度思考”并不冲突：前者是在描述这一版本机制的改进，后者是在描述较高投入档位的风险。两者都没有承诺任何任务绝不会浪费推理。

工具调用习惯会变，交付证据需要明确

从 Opus 4.6 到 4.7，官方记录了三项默认行为变化：回复长度更贴合任务复杂度，工具调用更少而推理更多，创建子 Agent 也更审慎。后续模型未必继续朝同一个方向变化，这个案例提醒我们：工作流如果依赖模型主动读取文件或主动并行，就需要在更换模型时重新检查这些行为。

以分页修复为例，可以补充一条明确的证据要求：

修改前，读取实际查询实现、接口调用处和相关测试，确认默认排序与兼容要求。
修改后，运行覆盖复现条件的测试；无法运行时说明阻碍，不把预测结果写成通过。
最终用三个短段落交付：根因、改动、验证证据。

这里规定了工具何时有用、要取得什么证据，也给出了回复结构的正面示例。它比单独要求“多用工具”更容易验收；多读取无关文件不会自动提高正确性。

子 Agent 是接受委派、执行一部分工作的独立助手。若需要分别检查查询层、接口层和测试覆盖，可以明确要求并行调查，并让各自返回证据与待确认事项；若只改一个已经看见的函数，拆分反而增加任务说明与结果整合的负担。

并行调查适合能独立取得证据的事项。如果几项工作相互依赖，或需要同时修改同一处代码，还应明确执行顺序与整合责任，避免分工本身制造返工。

比较设置，要让两次运行做同一道题

如果第一次运行已经留下修复代码，第二次运行只需补一个测试，那么两次耗时和 token 没有直接可比性。比较设置时，应从相同代码状态和等价的会话上下文开始，保持任务说明、工具权限和验收要求一致。

先选择少量有代表性的任务，例如一个定位明确的缺陷和一个涉及多个模块的修改。如果要判断推理强度的影响，就保持模型不变，每次只改变 effort；如果要比较两个模型，就固定其余可控制的条件，记录各自配置，不把同名档位当成等量推理。记录以下结果。

这里最容易混淆的是单次成本与完成成本。一次便宜但需要多次返工的结果，未必比一次较贵的成功交付更划算。反过来，如果两种设置都稳定通过，提高投入也未必带来实际收益。

单个任务只能提供线索。模型输出存在波动，任务难度也不同；不要把一次成功写成“该档位普遍最好”，更不要在没有用量记录时估算节省百分比。

在允许任务中途切换推理强度的工具中，可以按阶段调整投入。这样做便于实际执行，但不构成严格的档位对比：后一个阶段已经继承了前面的信息和工作成果。要判断哪档更划算，应单独设计前提一致的比较。

下一次开始任务前，先补上那条最容易被遗忘的约束

回到分页案例，三次返工里至少有一部分来自迟到的信息。把兼容边界和验收条件放进第一条消息，可以让后续的失败更容易诊断，也让 effort 的比较有共同基准。

执行前检查三件事就够了：模型知道要改变什么行为吗，知道必须保留什么吗，知道用什么证据判定完成吗？如果其中一项说不清，先补任务说明。

对于需要探索后才能确定的问题，也不必强行写出完整实现方案。可以先委托一个边界明确的调查任务，以复现、证据和待决策问题作为交付，再据此确定修改要求。清晰的任务不等于预先知道答案。

模型和档位更新后，具体推荐需要重新验证。可以继续沿用的是这套顺序：先检查信息是否完整，再检查证据是否充分，最后比较达到同一验收标准的总成本。即使换了模型，已有的任务说明和验收样例也能成为下一次评估的起点。