这份官方指南说明了 Claude Sonnet 5.5 在 effort、主动完成任务、无预先思考、结构化 JSON、进度更新、工具调用、中途用户消息和代码验证上的专属提示写法，可直接用于调整 Sonnet 5.5 的 system prompt 与 API harness。
适合的任务：Agent 编码、多轮工具调用、需要当前信息的研究和客服、需要 JSON 输出的多步推理、长任务进度展示，以及需要真实测试或构建验证的代码修改。
不适合的任务：直接把同一 effort 档位视为 Sonnet 5 的等价配置；只给模型提高 effort 却不测量质量、延迟和成本；用 between_tools 处理没有工具但需要多步推理的任务。
适用的模型版本：Claude Sonnet 5.5。页面提示，现有 Claude Sonnet 5 提示词通常无需修改；最困难的长时程工作应考虑 Opus 模型。
适用的客户端、Agent 或 API：Claude API、Claude Platform 以及提供工具调用、流式输出和消息级 effort 控制的自建 harness。部分配置使用 beta 能力，需按 API 当前文档核对。
推荐的推理档位和参数：API 默认从 high 开始；定义清楚的 Agent 编码和多步工具任务从 medium 开始，困难或更长的任务再升到 high；聊天和延迟敏感任务从 medium 或 low 开始。编码 Agent 的 max_tokens 建议留出思考和回复空间，页面建议设为模型上限 128,000 并开启流式输出。
以下代码围栏内的英文均为原文可直接复用片段；中文说明是对官方适用边界的整理。
当模型在低或中 effort 下经常完成一部分就停下来询问时，可将以下两段加入 system prompt。第二段也可单独使用，用于限制未请求的附加改动。
Keep working until everything the user asked for is done, and only stop to ask when you can't go on without the user or before a risky step.
When the work the user asked for is done and checked, stop and report. Don't add features, tests, files, docs or refactors that weren't asked for. If you think one would help, mention it at the end instead of doing it.官方说明：第一段会让低、中 effort 的会话更可能持续完成工作，因此会增加时长和成本；它不能替代自己的风险操作规则。
当 harness 提供 subagent，且 xhigh 或 max effort 会自行发起额外审查、加固或修复时，可使用以下 system prompt 片段：
When the work the user asked for is done and its checks pass, stop and report. Don't start extra rounds of review or hardening on your own, and don't launch reviewer sub-agents unless the user asked for a review. If you think a deeper review is worth doing, say so at the end.官方文档称，在其编码任务测试中，这段话使 reviewer subagent 的启动减少，单任务成本约降低三分之一，质量没有测得变化；它不能完全消除主 Agent 自发的复核轮次。
对于“展示你能做什么”这类开放请求，如果用户只想先看思路，可在 system prompt 中加入：
When the user asks for ideas, options or a plan, give them that and stop. Don't start building or changing anything until they say to go ahead.若需求本身已经明确要求执行，应在用户请求中直接说明要开始构建，避免把这段规则应用得过宽。
当任务需要汇总数字、应用规则或排序，而输出必须是 JSON 时，官方建议使用 adaptive thinking，并将以下一句放在 system prompt 末尾：
Think the problem through before you answer.官方文档说明：结构化输出可使回复正文只保留符合 schema 的 JSON，模型需要在 thinking 中完成推理；在 high effort 下，这句话能让准确率接近 xhigh，同时增加的输出 token 较少。若使用 between_tools 且请求没有工具，模型不会先思考，这句话也不会生效。
如果产品提供搜索工具，并且回答涉及可能变化的规定、要求、价格或其他当前信息，可使用：
Use the search tool to check specifics that may have changed since your training, such as what is allowed, required or charged, even when you feel confident. For researched work such as a report or a comparison, gather current sources rather than writing from your training knowledge.同时删除“only use tools when strictly necessary”或“minimize tool calls”等会压制工具调用的旧规则。
当连续多次工具调用没有面向用户的文本或进度更新时，harness 可以追加一条 turn-scoped system message：
The user hasn't heard from you in a while — say in a few words what you're doing, then continue.官方建议在连续多次静默后再提醒，例如五次；如果仍然静默，第二或第三次提醒后停止发送。提醒应追加在最近工具结果之后，并保留在后续请求的 messages 中，以维持 prompt cache 和 preserved thinking。
当模型报告代码改动完成，但没有运行测试或构建时，将以下段落加入 system prompt：
When you change code that can be run, built, or type-checked, run a real check that exercises the change before reporting it done: the project's tests, type-checker, or build, or the changed command itself. A syntax-only check, or a check command that failed to start, does not count; if all that is missing is the project's declared dependencies, install them with its own package manager and lockfile (e.g. npm install, pip install -r requirements.txt), never via sudo or the system package manager, unless told not to. Only if no real check can run here, say which one you did not run and why instead of reporting the change as done.官方文档称，在低 effort 测试中，这段话使跳过或浅层检查变得少见，对任务质量没有测得影响，单任务成本只有小幅增加。
Sonnet 5.5 的 effort 档位不能按 Sonnet 5 的同名档位直接迁移。官方建议先用自己的 eval 重新扫描。页面给出的配置边界如下：
{"type": "between_tools"}between_tools 是 Sonnet 5.5 的最低思考设置，适用于 high 或更低 effort。
xhigh 或 max 配合 between_tools 会返回 400。
使用 between_tools 时，不能通过每条消息改变 effort；要按消息改变 effort，改用 adaptive thinking。
没有工具但需要多步推理的请求应使用 adaptive thinking，而不是 between_tools。
读取响应时按 block type 处理，不要假设第一个 content block 一定是 text；将模型返回的 thinking blocks 原样传回。
改变顶层 effort 会使 prompt cache 失效；若只想改变单个 turn，使用支持 beta 的 per-message effort change，并保持 adaptive thinking。
使用 structured outputs 时，低、中 effort 偶尔会因为思考持续到 max_tokens 而没有正常结束。官方建议：
把 stop_reason: "max_tokens" 视为失败，即使正文看起来是合法 JSON；
为思考和 JSON 留出足够的 max_tokens，但不要高于单次请求可接受的成本；
无法使用 structured outputs 时，解析文本中最后一个 JSON 值，而不是把第一个 { 到最后一个 } 之间的全部内容当作 JSON；
校验结果字段，必要时重试一次。
这份指南的核心是按问题现象调整配置：
| 现象 | 官方建议 |
|---|---|
| 迁移 Sonnet 5 后延迟、质量或 token 用量变化 | 重新测试 effort，不沿用同名档位的假设 |
| Agent 在任务中途停下询问 | 先提高 effort；或加入“Keep working…”片段 |
| Agent 擅自增加测试、文档或重构 | 使用“done and checked”之后停止的第二段 |
| xhigh / max 自发启动审查 Agent | 加入停止额外 review 的片段，或降低 effort |
| 无工具 JSON 多步推理不准确 | 使用 adaptive thinking，并要求 “Think the problem through…” |
| 长工具链看起来无响应 | 启用 display: "updates" beta，或由 harness 在连续静默后追加提醒 |
| 研究回答使用过时知识 | 提供搜索工具并加入主动检索片段 |
| 中途用户消息被当作注入文本 | 将用户文本作为 user turn 放在携带 tool_result 的消息中，不能塞进 tool_result；harness 通知另放 system message |
| 代码未验证就宣布完成 | 加入真实测试、构建或类型检查片段 |
| 工具名大小写或参数名轻微错误 | 对唯一匹配的调用容错，或返回带正确工具名的 is_error: true tool_result |
| 图表或技术图纸识别遗漏细节 | 提供裁剪、缩放或运行代码的图像工具；图表上工具帮助大于单纯提高 effort |
这份文档适合作为 Sonnet 5.5 的 system prompt 和 harness 调整清单。最关键的迁移点是：重新测量 effort；用明确规则控制 Agent 的主动性和范围；需要多步推理的 JSON 请求使用 adaptive thinking；把工具结果、中途用户消息和进度 block 按正确的消息类型传递；代码任务在报告完成前运行真实检查。
页面中的“准确率接近”“成本约降低三分之一”“没有测得质量变化”等数字来自 Anthropic 的内部测试说明，文档没有公开完整任务集、样本量、模型构建、提示词对照和逐次输出。因此这些数字适合用来决定本地 eval 的测试方向，不能直接当作任何应用的保证。
可根据页面的原文片段、effort 边界、消息位置和响应 block 处理规则，搭建对照测试。要复现官方关于质量、成本和延迟的结论，还需要 Sonnet 5.5 的明确模型部署、相同任务集、工具定义、structured output schema、effort、max_tokens、流式设置、重试策略和评分方法；这些材料未在该指南完整公开。
Claude Sonnet 5.5