Source: ai-research/claude-docs-prompting-claude-opus-5-5-2026-10-27.md — Anthropic’s “Prompting Claude Opus 5.5” page in the Claude platform docs (platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5), fetched 2026-10-27. The page carries no date; secondary coverage dates it to launch week (2026-09-22 to 09-28).
Secondary source: raw/Anthropic_Just_Revealed_12_New_Rules_for_Prompting_Opus_5.5.md — a creator’s 12-point digest of the same guide.
Creator: Robo Nuggets (Jay) URL: https://www.youtube.com/watch?v=vsGwx28z4jk Duration: 7:03 Platform: YouTube Published: 2026-09-24
Anthropic’s prompting guide for Claude Opus 5.5 is organised by symptom: find what you are seeing (long expensive turns, an agent that stops early, refusals, generic frontend output) and apply the matching fix. Its starting point is that Opus 5 prompts “should perform well without changes”; most of the changes it recommends delete or narrow instructions rather than add them. Jay’s video at Robo Nuggets relays 10 of the guide’s points accurately and adds two subscription tips that are not in the guide. This article covers the guide in full and notes where the video simplifies it.
Key Takeaways
- Effort is the main dial, and medium is the default. Opus 5.5 defaults to
medium(Opus 5 defaulted tohigh). Set it explicitly and test several levels on your own evals. Effort names do not mean the same amount of thinking across models: Anthropic found Opus 5.5 atmediummatches or beats Opus 5 athighon coding and knowledge work, andlowcomes close on several coding evals. - At the same level it thinks more than Opus 5. Carrying over your Opus 5 setting means longer turns and more output tokens, especially at
xhighandmax. Reserve those two for work where you have measured a gain. To get less thinking, lower effort; that works more reliably than prompt instructions. - Thinking is always on, and it counts toward
max_tokens. A limit sized for Opus 5 with thinking off can cut replies short. Anthropic found 128,000 (the maximum) works well for long agentic coding turns. - Changing top-level effort mid-conversation invalidates the prompt cache. The per-message effort change (beta) keeps the cache, and the new level holds until another change replaces it.
- Do not ask it to write out its reasoning. Prompts that push the model to reproduce its internal reasoning can be declined with the
reasoning_extractionrefusal category, and server-side fallback returns that refusal to you rather than retrying on another model. Read summarized thinking blocks instead (display: "summarized"). A short explanation of the answer or a summary of actions is still fine. - Unattended loops stop early because progress updates end turns. Opus 5.5 reports progress as it works, and some of those reports end the turn with text. Treat a text-only end of turn as a report, keep a checklist, and nudge with the open items. Cap automatic continuations at two or three.
- Time signals speed up agent teams. Opus 5.5 paces itself to an elapsed-time budget. With no sensible budget, show elapsed time and add the “Time matters here” sentence.
- Delete “think carefully” lines in chat system prompts. Anthropic found removing one made replies start sooner with no clear quality drop.
- Name the design patterns to avoid. “Avoid a generic AI look” swaps one default for another. Listing the specific styles (cream background, italic accent words,
01/02/03labels, monospace labels, pill buttons) works. - Two new defensive patterns. Tag text the user pasted in from elsewhere so the model does not follow instructions inside it, and tell multi-app agents to look through related sources before acting.
The guide by symptom
| What you see | What the guide says to do | What Anthropic measured |
|---|---|---|
| Unsure which effort to run; turns cost more than on Opus 5 | Start at medium, set it explicitly, test levels on your evals; raise max_tokens; reserve xhigh/max for measured gains | medium matches or beats Opus 5 at high; low close on several coding evals |
| Your Opus 5 integration ran with thinking disabled | Start at low and measure; remove “write your reasoning” substitutes; re-test the Opus 5 thinking-disabled mitigations; read responses by block type | Not stated |
| An unattended agent stops partway after reporting progress | Treat text-only turn ends as reports; checklist; nudge with open items; optional small-model completion checker; system-prompt addition naming the early stops to avoid | Not stated |
stop_reason: "refusal" | Biology and cyber: apply to the Life Sciences or Cyber Verification Program for legitimate work. reasoning_extraction: remove reasoning-in-response instructions | Not stated |
| Long agentic turns look silent | Set display: "updates" (beta); give a send-to-user tool for verbatim mid-turn content; ask for intent and recap lines; harness reminder after ~5 silent steps | Reminder roughly halved the share of tasks with a long silent stretch, no measurable cost change |
| Multi-app agent misses information the task did not point to | One “explore broadly before acting” sentence | Noticeably more multi-app tasks correct at medium and max, slightly more tool calls |
| You want an agent team to finish sooner | Time budget as an elapsed-time line in each harness message, or elapsed time plus “Time matters” | Teams finished sooner than a single agent; budgeted teams kept comparable answer quality |
| Chat replies start slowly | Remove “think carefully” lines; optionally add the “treat earlier answers as done” instruction | Replies started sooner, no clear quality drop |
| Model follows instructions inside pasted text | Wrap pasted blocks in <pasted_content id="..."> tags plus a system-prompt note | Not stated; may make the model slightly more cautious |
| Dense charts, diagrams or screenshots miss detail | Re-test old visual scaffolding first; for the densest inputs send higher resolution and give crop/zoom tools (PIL, OpenCV) | Even at lowest effort it read dense charts better than Opus 5 at highest |
| Frontend output looks generic | Name specific patterns to avoid; check which defaults the first result used and extend the list | Not stated |
Details worth knowing before you copy the fixes
- The unattended-run addition is for fully unattended agents only. It names four early stops the user does not want: a long summary that announces the next step without taking it; an offer to carry on “unless you’d prefer otherwise”; a list of decisions none of which blocks the work; deciding a milestone is a good place to report. It also names the stops that are wanted (nothing can move without the user, or the blocker is deliberately protected). Add it from the first request, because adding it mid-session changes the system prompt and invalidates earlier thinking blocks. Keep your own confirmation step for risky actions and leave it out of human-in-the-loop apps. The verbatim paragraph is in the source file.
- The “settled answers” instruction has a cost. It cut follow-up thinking in Anthropic’s chat tests, but it can make the model less likely to point out its own earlier mistake. Leave it out of long analyses and agentic tasks where a later step can reveal an earlier error. Added 2026-11-11: Anthropic’s Fable 5.2 guide reports the same two sentences made Fable 5.2 “far less likely to point out mistakes in its earlier answers,” so do not carry them over to Fable 5.2 without testing (see Prompting Claude Fable 5.2).
- A time budget is advisory. The model usually finishes well before it, so set it somewhat above the time you want, and keep your own timeout for a hard stop. Under time pressure it may search and verify a little less. A budget mostly increases parallel work; lowering effort reduces the work itself.
- The explore-broadly sentence tells the model to act on what it finds, so keep untrusted content out of the records it searches.
- Pasted-content tags are plain text and can be imitated. Treat them as one guardrail alongside other prompt-injection defences.
- Crop and zoom tools help more at higher effort. Without tools, raising effort improves reading of technical drawings but does little for charts.
How Jay’s 12 rules map to the guide
| # | Jay’s rule | Guide or other source | Caveat |
|---|---|---|---|
| 1 | Start at medium effort | Guide | Matches |
| 2 | Test your effort levels: have Opus run a real task at every level side by side | Guide (“test several levels against your own evals”) | His prompt version is his own; see Picking the Right Model for a fuller method |
| 3 | Claude Code now reads AGENTS.md | Not in the guide. Claude Code v2.1.277 (2026-09-18): “in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead” | See AGENTS.md for which clouds support it |
| 4 | Switching effort no longer wipes the cache | Guide, but narrower: only the per-message effort change (beta) keeps the cache; changing the top-level effort value still invalidates it | Whether Claude Code’s /effort uses the per-message mechanism is not confirmed in this wiki |
| 5 | Use your banked usage reset | Launch page: a rate-limit reset “subscribers can save and use when they choose” | Jay’s launch reset expired 2026-10-23 per his account; check Settings → Usage for current ones |
| 6 | Opus flags requests to show its reasoning | Guide (reasoning_extraction) | Jay reads it as anti-distillation; the launch page lists distillation among the safeguard classes |
| 7 | Tell it earlier answers are settled | Guide | Jay suggests CLAUDE.md or a skill; the guide frames it for chat system prompts and warns against it for agentic work |
| 8 | Keep a task checklist | Guide | The guide pairs it with a harness nudge and a continuation cap |
| 9 | Set a time budget (“finish in 3 minutes”) | Guide | The guide’s version is an elapsed-time line from the harness, aimed at multi-agent setups |
| 10 | Add “time matters” | Guide | The full sentence is longer; quoted below |
| 11 | Opus still has design defaults | Guide | Matches; Jay recommends a design system as the stronger fix |
| 12 | Give it crop and zoom tools | Guide | Matches |
Jay skips the thinking-disabled migration, max_tokens sizing, the progress-update display setting, the multi-app sentence and the pasted-content tags. API integrators need those most.
A second creator’s walkthrough: Brock Mesarich’s 8 tips (2026-09-26)
Source: raw/Anthropic_Revealed_Their_Secret_Guide_to_Mastering_Opus_5.5.md
Creator: Brock Mesarich URL: https://youtu.be/is3XYKl2bpI Duration: 8:40 Platform: YouTube Published: 2026-09-26
Brock’s eight tips are effort, thinking instructions, relevant context, pasted material, silent progress, unfinished tasks, design direction and small visual details. All eight match the guide, including the cost of the settled-answers instruction. He aims at non-developers: he skips max_tokens, the cache and the API settings, and he reduces the pasted-content tags to “start with a job … then paste the email in separately.” What he adds is a set of everyday example prompts. None of them is on the platform docs page, so they are his own or come from a version of the guide not captured here.
- Choosing effort. Give Claude two proposals and one list of requirements, run it at medium and at a higher level, and compare: “did one miss an important requirement? Was a recommendation more useful? How long did it take?” A longer answer alone does not show the higher level was worth it.
- Replacing “think deeply.” Instead of “think deeply and carefully,” ask it to compare the two proposals against your requirements, recommend one and explain the trade-off. That still asks for careful work but defines the result.
- Checking more than the first file. A project update drafted from a brief that says Monday, when a later email moved the deadline to Friday, comes out polished and wrong. His prompt tells Claude to check both the brief and the email before drafting.
- Timing progress updates. Ask for an update after the files are reviewed and again when the draft is ready, and let Claude keep working in between. That gives visibility “without turning every step into an approval request.”
- Defining done. Name the outputs (for example a report, a source list and a summary). If one is missing, name it rather than saying “keep going,” and ask Claude to finish it or explain the blocker.
- Design direction. Instead of “make it less generic,” name a background, headline style, button shape and spacing, or attach a reference image.
- Small visual details. Point Claude at the exact label or region, let it crop if it has tools or attach your own close-up, and ask it to say when a detail is unreadable rather than guess.
Try It
- Set effort to
mediumexplicitly in your API calls or Claude Code, then run three of your own recurring tasks atlow,mediumandhigh. Keep the lowest level that passes. - Search your system prompts, skills and CLAUDE.md for “think carefully”, “show your reasoning” and “step by step”. Delete the first and third. Replace the second with a request for a short explanation of the answer.
- Raise
max_tokenson any integration that ran Opus 5 with thinking off. - If you run unattended agents, add a checklist, a nudge that names open items, and a cap of two or three automatic continuations.
- For a frontend task, add a negative list of the defaults the last result used, starting from the guide’s example below.
- If your app accepts pasted emails or webpages, wrap them in the
pasted_contenttags and add the system-prompt note.
Implementation
Tool/Service: Claude Opus 5.5 (claude-opus-5-5) via the Claude API, Claude Code and the Claude apps.
Setup: No prompt changes are required to migrate from Opus 5; the guide’s changes are tuning. The four breaking API changes are in Anthropic’s migration guide (not captured in this wiki).
Cost: 20 per MTok, $0.20 cache reads (see Opus 5.5). The unattended-run addition and the explore-broadly sentence both add tool calls and tokens.
Integration notes:
- Beta features the guide relies on: per-message effort change;
thinking.display: "updates"(headerthinking-display-updates-2026-08-18); turn-scoped system messages withclear_at: "next_user_message"(headermid-conversation-system-clear-at-2026-08-21). - Progress updates arrive as
thinkingblocks, nottextblocks, so a client that renders only text looks silent. Check each block’s type rather than assuming the first block is text. - Declare any send-to-user tool in
toolsfrom the first request; adding it later invalidates earlier thinking blocks.
Copy-ready lines from the guide:
Your task list still has open items: migrate the remaining two endpoints and update their tests. Continue with them. If one is blocked, say what is blocking it.Time matters here: do not spend time that can be avoided, and the earlier a correct result is obtained, the better.Once you have answered something, treat that answer as done. On later turns, focus your thinking on what the user is asking now, and don't go back over an earlier answer unless the user asks about it or points out a problem with it.Before taking any action, explore broadly with tool calls: list and open the emails, documents, spreadsheet tabs and records across the available apps that could be relevant to this task, including ones the task does not explicitly mention, and use what you find.Output a vanilla HTML/CSS personal website with placeholder data. Do not use a cream or off-white background, italic accent words in headlines, numbered "01/02/03" section labels, monospace labels, or pill-shaped buttons.The user hasn't heard from you in a while — say in a few words what you're doing, then continue.Open Questions
- Does Claude Code’s
/effortkeep the cache? The guide describes the API’s per-message effort beta. Jay says switching effort mid-chat now keeps the cache on all 5.5 models and Fable 5.1, but he also says it is in beta and to test it. The advisor-tool article still says changing effort invalidates the cache. Largely resolved 2026-10-28: Thariq Shihipar’s “Spending your effort” (ai-research/claude-dev-blog-spending-your-effort-2026-09-25.md) says the newest models “respond to effort without breaking the prompt cache in Claude Code,” and suggests changing/effortmid-conversation. The Effort docs (ai-research/claude-docs-effort-2026-10-28.md) list per-message effort, which keeps the cache, for Fable 5.1, Mythos 5.1, Opus 5.5, Opus 5, Sonnet 5.5 and Haiku 5.5 on the Claude API; a top-level change restarts the cache. Whether Claude Code uses the per-message mechanism internally is still not stated. See Which Effort Level to Use. - Publication date. The docs page is undated; secondary coverage gives 2026-09-22 and 2026-09-28.
- Migration guide. The “four breaking API changes” page is linked from the guide but not captured here.
- Source of Brock’s example prompts. His deadline, proposal and design examples are not on the platform docs page. Whether Anthropic published them in a consumer-facing version of the guide is not confirmed here.
- Sonnet 5.5 and Haiku 5.5. The guide is Opus-specific. Whether the same effort calibration and settled-answers advice applies to the other 5.5 models is not stated.
Related
- Claude Opus 5.5 — the model, pricing, benchmarks and field reports.
- Prompting Claude Fable 5 — the previous model-specific guide; the
reasoning_extractionpitfall first appears there. - Prompting Claude Fable 5.2 — the next guide, same symptom-by-symptom format.
- Claude Prompting Best Practices — the cross-model guide this one extends.
- Claude 5.5 Mistakes and Fixes — Jay’s follow-up video turning this guide and Anthropic’s Claude Code advice into a 23-item checklist.
- Model vs. Effort — how effort works in Claude Code.
- Which Effort Level to Use — Thariq’s per-level rules and Opus 5.5 effort tests.
- The New Rules of Context Engineering for Claude 5 — the delete-instructions thesis this guide continues.
- Frontend Design Deep Dive — what to give the model instead of “make it less generic”.
- AGENTS.md — the instructions file Claude Code now reads when no CLAUDE.md exists.