为 Claude Opus 5 编写提示

本指南涵盖 Claude Opus 5 特有的提示模式。有关该模型的能力和 API 变更，请参阅 Claude Opus 5 的新功能。有关适用于所有当前 Claude 模型的技巧，请参阅提示最佳实践。

Claude Opus 5 专为复杂的代理式编码和企业工作而构建，在长周期代理式任务方面尤为出色。它在现有的 Claude Opus 4.8 提示上开箱即用地表现良好。以下模式涵盖了最常需要调优的行为。



能力改进

与 Claude Opus 4.8 相比，与提示最相关的改进包括：

• 代理式编码： Claude Opus 5 在困难的编码任务上表现最强：多文件功能、较大规模的重构以及端到端的功能开发。它会完成完整的任务，而不是留下桩代码或占位符，并且在预先获得完整的任务规格说明并被放手运行时表现最佳。它在单轮编辑等较简单的任务上也表现良好，只是与先前模型的差异较小。
• 代码审查和缺陷发现： Claude Opus 5 以高精确率和高召回率审查代码：它每轮能以较高比率发现真实的缺陷，并且其额外发现大多是真实问题而非误报。在较低的 effort 设置下准确性依然保持，这支持在审查时先进行快速一轮、之后再进行更彻底的一轮。如果您的审查提示中写着"只报告高严重性问题"或"保持保守"，模型可能会字面地遵循该指令并减少报告；请改为让它报告所有内容，然后在单独的一轮中进行过滤。
• 较低 effort 下的效率： low 和 medium effort 能以更高设置的一小部分令牌和延迟产出强劲的质量。从默认值（high）开始，并根据您的评估进行调整：在质量保持的情况下，大量使用 low 和 medium 作为控制令牌成本和响应时间的主要手段，并在要求苛刻的编码和代理式工作中提升到 xhigh。如果您从先前模型沿用了 effort 默认值，请在您自己的评估上重新运行一次 effort 扫描。完整建议请参阅 Effort。
• 视觉： Claude Opus 5 在图表、文档和示意图理解以及 UI 和前端视觉复刻方面表现强劲。请重新验证您为先前模型调优的任何提示侧视觉变通方案；它们可能不再需要。当模型拥有可以迭代分析、裁剪并以视觉方式验证其工作的工具时，视觉性能最强，而且工具使用比单纯的思考是更具成本效益的手段。
• 长上下文工作： Claude Opus 5 拥有 100 万令牌的上下文窗口，这既是默认值也是最大值，并且其指令遵循、工具调用和推理在整个窗口范围内保持一致。
• 办公和文档任务： Claude Opus 5 能生成并处理包含非平凡公式的复杂多工作表电子表格，并能产出结构良好的幻灯片。请在提示中提供它需要遵循的任何特定样式或模板。
• 多代理协调： Claude Opus 5 能很好地协调子代理团队，具有有效的写入者-验证者模式，且代理之间相互覆盖工作的情况很少。对于成本敏感的工作负载，请限制委派；请参阅控制子代理生成。



响应长度和冗长度

Claude Opus 5 面向用户的默认响应比先前的 Opus 模型更长。effort 参数控制的是模型思考的多少，而不是它说多少：降低 effort 可以减少思考量，但不能可靠地缩短可见响应。要控制响应长度，请在提示中明确说明。

一条简短的简洁性指令就很有效。例如，对于面向用户的多轮产品：

Keep responses focused, brief, and concise. Keep disclaimers and caveats short, and spend most of the response on the main answer. When asked to explain something, give a high-level summary unless an in-depth explanation is specifically requested.

在较长的系统提示中，请在提示末尾附近将该指令与一条简短的提醒配对：

<tone_preference>
Keep outputs reasonably concise.
</tone_preference>



面向用户的进度更新

Claude Opus 5 在代理式工作期间很乐于叙述：它倾向于宣布自己即将做什么，并且其在代理式会话中每条消息的输出通常比先前模型更长。为它提供关于在任务期间如何与用户沟通的明确指导会有所帮助。要调低叙述，请描述您想要的节奏和形式：

Before your first tool call, say in one sentence what you're about to do. While working, give a brief update only when you find something important or change direction. When you finish, lead with the outcome: your first sentence should answer "what happened" or "what did you find," with supporting detail after it for readers who want it.

要调高叙述或改变其风格，同样的手段反向适用：明确描述更新应该是什么样子并提供示例。您想要的沟通风格的正面示例往往比关于不要做什么的指令更有效。



书面交付物长度

与对话冗长度不同，Claude Opus 5 写入磁盘的文件（报告、Markdown 文档、摘要）通常比先前模型更长。如果您的产品包含由 Claude 撰写的文档，请添加明确的长度校准：

Match the length of written documents to what the task needs: cover the substance, but do not pad with filler sections, redundant summaries, or boilerplate.



任务范围和过度验证

Claude Opus 5 无需被告知就会验证自己的工作。如果您的提示包含明确的验证指令（"为任何非平凡任务包含最终验证步骤"、"使用子代理进行验证"），请将其删除：这类指令会导致 Claude Opus 5 过度验证，而删除它们可以减少浪费的令牌且不会损失质量。这同样适用于添加单独验证步骤的遗留框架脚手架。

Claude Opus 5 也可能扩大任务范围，添加未被要求的步骤，或对任务应该是什么运用自己的判断。对于范围狭窄的任务，请明确约束范围：

Deliver what was asked, at the scope intended. Make routine judgment calls yourself, and check in only when different readings of the request would lead to materially different work. If the request seems mistaken or a better approach exists, say so in a sentence and continue with the task as asked rather than quietly narrowing, widening, or transforming it. Finish the whole task, and stop short of actions that are clearly beyond what was asked.



控制子代理生成

Claude Opus 5 比先前模型更乐于委派给子代理。委派在真正独立、规模可观的工作线上是值得的，但应用于小任务时会成倍增加成本和时间。如果您的框架支持子代理，请就哪些场景值得委派给出明确指导，或对可以启动的代理数量设置确定性上限。例如：

Delegate to a subagent only for large tasks that are genuinely independent and parallelizable, such as a wide multi-file investigation. Do not delegate work you can finish yourself in a handful of tool calls, and do not use subagents to verify or double-check your own work. If one subagent can complete the task, use one rather than several, and keep spawn counts low.



自我纠正

Claude Opus 5 无需提示就能很好地发现并修复自己的错误。请避免指示它进行它已经在执行的重新检查（"仔细检查您的答案"、"在响应前重新验证"）；与验证指令一样，这些指令会与模型自身的行为叠加，在不改善结果的情况下增加成本。

该模型也比先前模型更多地叙述对其早先陈述的纠正，这在面向用户的产品中可能是不可取的。要将纠正叙述限制在重要的纠正上：

Only correct an earlier statement when the error would change the user's code, conclusions, or decisions. State corrections plainly and briefly, then continue the task. For slips that change nothing for the user, make the fix and move on without noting it.



在禁用思考的情况下运行

Claude Opus 5 默认开启思考运行，并且只有在 effort 为 high 或更低时才能禁用思考；请参阅迁移指南。禁用思考后，模型的可见输出中偶尔会出现两种伪影。对这两者的主要缓解措施都是保持思考启用，并通过较低的 effort 级别而非禁用思考来控制令牌成本：对于大多数任务，在 low effort 下启用思考的表现优于在相近成本下禁用思考。

以文本形式出现的工具调用。 禁用思考后，模型偶尔会将工具调用写入其面向用户的文本中，而不是发出结构化的 tool_use 块。该轮次会正常完成且调用永远不会运行，并且在代理式循环中，泄漏的文本会留在对话历史中，因此后续轮次也会受到影响。这在搜索等工具密集型工作负载中最为常见。

输出中的内部 XML 标签。 禁用思考后，模型可能会在其可见响应中发出 <thinking> 标签或其他内部 XML 标签。如果您的系统提示包含指示模型不要思考或不要推理的规则，请将其删除；这类指令会增加标签泄漏。

对于必须保持禁用思考的集成，一条组合指令即可缓解这两种伪影：它给予模型在工具调用前发言的明确许可、在没有合适工具时强制调用的替代方案，以及一条禁止内部标签的通用规则：

When you use a tool, you may say a brief sentence first. If no tool can express what the user asked for, say so instead of guessing. Do not include internal or system XML tags in your response.

点名提及思考标签的指令不如通用形式有效，因此请避免具体点名它们。