Prompting Claude Opus 5.5

Prompting Claude Opus 5.5 involves adjusting several key settings to optimize performance, cost and output. One of the most important controls is the "effort" setting, which directly affects how much Claude Opus 5.5 thinks during each turn. For coding and knowledge-work tasks, medium effort tends to match or exceed high effort on Claude Opus 5, while at the same time providing significant cost savings.

Starting with medium effort as the default on Claude Opus 5.5 is recommended, and then testing several effort levels to find the optimal balance for your specific use case.

At each effort level, Claude Opus 5.5 tends to think more per turn than Claude Opus 5, especially at xhigh and max. This means longer turns and more output tokens, unless adjustments are made. To keep the model's thinking consistent across requests, changing the top-level effort value between requests invalidates the prompt cache. If you need to change the effort level for a single turn, use a per-message effort change instead, which preserves the prompt cache.

Claude Opus 5.5 provides progress updates between tool calls, which can help users stay informed about the model's progress. However, these updates come back as thinking blocks with empty text in the default configuration. To receive summaries of each progress note, set the "display" option to "updates" in your client. This will allow you to see the short summaries of each note, making long agentic turns less silent.

Safety classifiers are also in place for Claude Opus 5.5, including for biology, cybersecurity and reasoning extraction. If any of these classifiers decline a request, a normal response with stop_reason set to "refusal" will arrive. This can be automatically retried on a fallback model, except for reasoning extraction declines, which will return to you instead of retrying. Be aware that these additional classifier checks can lead to more tool calls and output tokens per task.

When running Claude Opus 5.5 in an unattended agent loop, pay close attention to the model's end-of-turn behavior. If a turn ends with text rather than a tool call, it may be signaling the end of the task. Treat this as a report rather than proof the task is complete, and make sure to keep the task's parts in a checklist that the model updates. If a turn ends with items still open and no blocker stated, send a short user message listing them so the loop can continue appropriately.