Claude Platform Docs
最佳实践提示工程

为 Claude Sonnet 5.5 编写提示

Claude Sonnet 5.5 特有的提示模式：effort、主动性与范围、无预先思考运行、JSON 输出、进度更新、工具使用、轮次中途消息、编码验证、工具调用、视觉输入以及拒绝。

本指南介绍 Claude Sonnet 5.5 特有的提示模式。有关该模型的 API 变更，请参阅 Claude Sonnet 5.5 的新功能。有关适用于所有当前 Claude 模型的技巧，请参阅提示最佳实践。

现有的 Claude Sonnet 5 提示无需修改即可表现良好，为 Claude Sonnet 5 编写提示中的模式仍然是一个合理的起点。对于最困难的长周期工作，Opus 模型是更好的选择。请从与您观察到的情况相符的部分开始：

校准 effort

Effort（努力程度）是控制 Claude Sonnet 5.5 思考量的主要手段，并由此影响质量、"latency"（延迟）和成本。其级别已重新校准：某个级别产生的思考量与 Claude Sonnet 5 上相同级别并不相同。请针对您自己的评估重新进行一轮测试，而不是沿用您在 Claude Sonnet 5 上使用的设置。除非您的工作负载是智能体型或对延迟敏感的，否则请从 high（Claude API 上的默认值）开始。对于智能体编码和多步骤工具使用，明确定义的任务从 medium 开始，更难或更长的任务改用 high。对于聊天和其他对延迟敏感的工作，从 medium 或 low 开始，因为更高的 effort 意味着回复开始前需要等待更长时间。如果质量需要，再提高 effort。

较低的 effort 也会改变模型完成智能体工作的方式。在 low 级别，它会保持简短的思考，并可能跳过对更改的验证。请参阅编码任务中的验证。在 low 和 medium 级别，在长时间的智能体任务中，它更有可能在完成之前停下来与用户确认。请参阅引导主动性与范围。

以下三项调整会有所帮助：

  • 设置 max_tokens 时，为思考和您预期的回复留出空间。即使思考内容不会返回给您，思考也会计入 max_tokens。按无思考请求设定的上限可能会截断回复。对于智能体编码，请将 max_tokens 设置为 128,000（模型的最大值），并对响应进行流式传输。
  • 仅在您已测得质量提升的工作中使用 xhigh 和 max，因为在这些级别下思考和回复会变得长得多。在这些级别下不接受 between_tools，因此无法关闭预先思考。
  • 要减少思考，请降低 effort 级别。从 medium 起，模型几乎在每次回复之前都会简短思考，即使是问候语也是如此，这会增加第一个可见令牌出现前的时间。在系统提示中要求它少思考并不能可靠地减少其思考量。在 low 级别，它会在大多数简单请求上跳过思考。

在请求之间更改顶层 effort 值会使提示缓存失效。要在对话中途更改级别，请改用按消息更改 effort（beta），这样可以保留缓存。一次更改会对之后的每个轮次生效，直到被另一次更改替换。例如，在 low 级别的交互式会话中，在用户提出难题之前添加一次改为 high 的更改，并在 Claude 回答之后再添加一次改回 low 的更改。按消息更改 effort 需要自适应思考。与 between_tools 一起使用时，它们会返回 400 错误，如无预先思考运行中所述。

引导主动性与范围

Claude Sonnet 5.5 自主推进的程度取决于 effort 级别和请求本身。在较低的 effort 下，它有时会在编码任务完成之前与您确认。在较高的 effort 下，或面对开放式请求时，它可能会做超出您要求的事情。请通过 effort 级别和系统提示中的指令来引导它。

将工作进行到底。 在 low 和 medium effort 下的智能体编码任务中，模型有时会在工作完成之前与您确认。它可能会停下来确认计划、提出一个它本可以自己回答的问题，或者在完成多部分任务中的一部分后停下来询问是否继续。请先尝试更高的 effort 级别。若要在不更改 effort 的情况下让模型持续工作，请将以下内容添加到您的系统提示中：

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.

使用此提示后，模型在 low 和 medium effort 下会完成更多工作，因此这些级别的会话运行时间更长、成本更高。该提示不能替代您自己关于高风险或不可逆操作的规则。请将这些规则保留在您的系统提示中。

编码时未经请求的附加内容。 模型倾向于添加符合您代码仓库惯例的测试、文档和小型辅助文件，即使您没有要求。它在每个 effort 级别都会这样做，effort 越高越明显。所请求的更改本身仍会紧扣要求。大多数团队会欢迎这一点。如果您希望更改仅限于明确要求的内容，请只添加上述提示的第二段，即以"When the work the user asked for is done"开头的那一段。在 xhigh 和 max effort 下，该段落会减少这些附加内容，并使更改总体上更小。

xhigh 和 max effort 下的彻底性。 在这些级别下，模型尤其彻底。完成任务后，它可能会自行开始多轮审查和验证，如果您的 "harness"（运行框架）提供子代理，有时还会使用子代理。它还可能顺带修复途中注意到的相关问题。这会花费更多时间和令牌，因此请在 high 或更低级别运行常规工作，在这些级别下这种情况很少见。如果您确实需要这些 effort 级别带来的额外彻底性，但希望将其集中在任务本身上，请将以下内容添加到您的系统提示中：

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.

在 max effort 下的编码任务测试中，这阻止了模型启动审查子代理，并将会话成本降低了约三分之一，而质量没有变化。它会减少主代理自行发起审查轮次的频率，但不会完全消除。

开放式请求。 当请求是开放式的，例如"show me what you can do with this"，模型可能会开始构建演示文稿、报告或视频，而您只是想要一些想法。如果您想先获得想法或计划，请在请求中说明，或将以下内容添加到您的系统提示中：

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.

无预先思考运行

要在无预先思考的情况下运行 Claude Sonnet 5.5，请发送 thinking: {"type": "between_tools"}。这是该模型上最低的思考设置，在 high effort 或更低级别下可用。如果您的集成目前在关闭思考的情况下运行，请将其切换为 between_tools 并检查以下几点：

  • 在 high effort 或更低级别下发送 between_tools。 在 xhigh 或 max effort 下，带有 between_tools 的请求会返回 400 错误。使用 between_tools 时，effort 也不能在对话中途更改：与当前生效级别不同的按消息 output_config.effort 会返回 400 错误。要按轮次改变 effort，请使用自适应思考。使用 between_tools 时，请删除任何告诉模型不要思考的指令。此类指令会使模型更有可能在其可见输出中写出内部 XML 标签。
  • 按块类型读取响应。 使用自适应思考时，响应可能以 thinking 块开头，在默认的 display: "omitted" 下，其 thinking 字段为空。使用 between_tools 时，响应可能以进度更新 thinking 块开头。不要假设第一个内容块是文本。
  • 原样传回 thinking 块。 使用 between_tools 时，模型在工具调用之间写下的说明如果超过一两句话，仍会以 thinking 块的形式返回。每个块都带有该说明的摘要。请将它们与助手轮次的其余部分一起原样传回。您传回的块会向模型提供它所写的完整说明，而不是摘要。
  • 对于不使用工具的推理任务，请使用自适应思考。 在不含工具的请求中，between_tools 意味着模型不先思考就直接作答。对于需要几步推算的任务，请改用自适应思考。请参阅带 JSON 输出的推理任务。

带 JSON 输出的推理任务

本节适用于您要求 Claude Sonnet 5.5 对需要几步推算的任务给出 JSON 答案的情况。示例包括汇总文档中的数字、应用某条规则或对项目进行排序。在此类任务中，模型经常不经思考直接作答，尤其是在 low 和 medium effort 下。有效的做法取决于您请求 JSON 的方式。在可用的情况下，请使用结构化输出。这样响应文本就是符合您 schema 的 JSON，无需解析。

使用结构化输出时，响应文本只包含 JSON，因此模型只能在思考中推算问题。当它跳过思考时，在这些任务上的准确性可能会降低。以下更改有助于保持高准确性。

要求模型先思考。 使用自适应思考时，将以下这行添加到系统提示的末尾：

Think the problem through before you answer.

加上这行后，模型会更频繁地在作答前思考。在 high effort 下，这行能使准确性接近模型在 xhigh 下达到的水平，而输出令牌仅适度增加。在 low 和 medium effort 下，它能提高准确性，但达不到模型在 high 下的水平，且输出令牌的增加幅度更大。

或者使用 xhigh effort。 使用自适应思考时，即使不加这行，xhigh 也能在这些任务上提供最高的准确性。它比 high 使用更多的输出令牌。

使用自适应思考而非 between_tools。 在不含工具的请求中，模型在 between_tools 下不会在作答前思考。这行在那里不起作用，这些任务的准确性也更低。请对这些请求使用自适应思考，并配合本节中的步骤。在测试中，将请求拆分为两个（一个请求获取答案，一个请求获取 JSON）可以获得很高的答案准确性和 JSON 合规性，但成本和延迟非常高。

在 low 和 medium effort 下使用结构化输出时，模型偶尔会持续思考直到达到 max_tokens。在 high effort 及以上，这种情况几乎不会发生。请将任何 stop_reason 为 "max_tokens" 的响应视为失败，即使其文本包含有效的 JSON，并进行重试。按照校准 effort 中的说明，将 max_tokens 设置得足够容纳思考和 JSON，但不要高于您愿意为单次尝试花费的上限。

如果您无法使用结构化输出，请改为在提示中要求 JSON。此时模型通常会在响应文本中推算问题，并在末尾写出 JSON。JSON 通常包含正确答案，但期望整个响应都是 JSON 的解析器会失败。以下两点会有所帮助：

  • 解析响应中的最后一个 JSON 值。 只读取 text 块，并将 stop_reason 为 "max_tokens" 的响应视为失败。从每个 { 或 [ 开始，尝试解析一个 JSON 值。当某个值解析成功时，从该值的末尾继续，这样嵌套在其中的值就不会被单独计算。保留找到的最后一个值。不要截取从第一个 { 到最后一个 } 的全部内容。模型偶尔会在最终 JSON 之前写一个草稿，而该范围会同时包含两者。如果您的答案是连续的多个 JSON 值，例如每行一条记录，请保留最后一组仅由空格、逗号或换行分隔的值。检查结果是否包含您期望的字段，如果没有，则重试一次。在测试中，这使几乎每个响应都可用，且不影响其准确性。
  • 也可以考虑使用自适应思考配合 xhigh effort。 此时模型会在思考中推算问题，并且几乎总是只返回 JSON。总输出令牌与 high 下大致相同，因为推算过程从响应文本转移到了思考中。

面向用户的进度更新

在工具调用之间，Claude Sonnet 5.5 会写下面向用户的说明，介绍它刚刚发现了什么以及接下来要做什么。超过一两句话的说明会以进度更新 thinking 块的形式返回。较短的评论仍为 text。在默认的 thinking.display 下，进度更新块的文本为空，因此只渲染 text 块的客户端在长时间的智能体轮次中可能看起来没有任何输出。这在聊天界面以及用户实时跟踪模型工作的其他产品中最为重要。

要显示这些说明，请设置 display: "updates"（beta，thinking-display-updates-2026-08-18 标头）。使用