Frameworks

What Anthropic's Opus 5.5 Prompting Guide Gets Wrong About Old Habits

Anthropic shipped a standalone prompt engineering doc for Opus 5.5, a first for the Opus line. Three of its design choices run counter to conventional prompt wisdom, and one of them could change how you write tool-calling loops.

Font size

Anthropic published a standalone prompt engineering doc on platform.claude.com for Claude Opus 5.5. The move itself is a signal: prior Opus 4.x releases never got their own dedicated document. Prompting guidance was always bundled into the general-purpose guide.

The doc sat on the Hacker News front page long enough to rack up 127 points and 122 comments, denser discussion than most AI news gets. After reading it through, three design choices stood out as running against common assumptions.

Why a standalone document matters

When OpenAI and Google ship a new model, they typically append a section to the general prompting guide, something like "notes for GPT-5" or "tuning tips for Gemini 3." Anthropic went the other way: an independent page at platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5, sitting at the same hierarchy level as the main docs.

The implication: the vendor is willing to spend an entire URL on prompting, which means prompting has graduated from "best practice" to "product feature." Old models tolerate stale templates. Opus 5.5 running on 4.5-era patterns loses measurable performance.

I tested this directly. Moving an agent prompt that worked well on 4.5 over to 5.5 dropped the completion rate on complex tasks by nearly 20%.

The "fewer examples" bias

This is the most counterintuitive one.

Read through the Opus 5.5 doc and the absence of few-shot examples is striking. The official guidance repeatedly pushes "structured instructions instead of example stacks." Compared to OpenAI's GPT-5 prompting guide and Google's Gemini 3 docs, Anthropic's restraint is notable.

OpenAI's docs are full of passages like this:

Example 1: ...
Example 2: ...
Example 3: ...

Anthropic's 5.5 doc shows this kind of pattern instead:

# Role
You are a ...

# Constraints
- ...
- ...

# Output Format
...

Pure Markdown-structured instructions. I used to treat few-shot as the universal default. The 5.5 era forces a reassessment.

The reasoning prompt pattern has shifted

Second counterintuitive finding, and the biggest departure from 4.5-era practice.

The traditional chain-of-thought template is familiar:

Let's think step by step.
1. First, ...
2. Then, ...
3. Finally, ...

Anthropic's Opus 5.5 recommendation is "constraints first, then reasoning." The gist: list all constraints, edge conditions, and output format requirements up front, then let the model reason freely.

# Constraints
- Output must be valid JSON
- All numbers must be integers
- Do not include explanations

# Task
Given the following data, compute ...

I tested this on a small dataset. On older 7B-scale models, constraints-first underperformed, sometimes worse than classic step-by-step. On Opus 5.5, accuracy improved noticeably.

Reasoning models have moved on from old prompt structure preferences. CoT used to be the silver bullet. The new winning combination is "structure upfront plus free reasoning."

The most underrated page: tool calling

Third counterintuitive finding, hiding in the function calling section.

The retry and validation pattern the doc recommends:

# Tool Execution Loop

1. Call the tool with the user's request
3. If the tool returns an error:
   a. Inspect the error message
   b. Adjust the parameters
   c. Retry up to 3 times
4. If validation fails:
   a. Return a structured error response
   b. Do not attempt to fix the error silently

Two details worth noting:

  1. Retries explicitly adjust parameters, rather than blindly resending the same request.
  2. Validation failures return structured errors, no silent fixes.

Compare this to the default behavior in LangGraph and the OpenAI Agents SDK, which tend to "retry the same call and hope the model self-corrects." Anthropic's pattern is more engineering-minded: make errors explicit, make parameter adjustments explicit.

I ported this pattern into a production agent project. Stability improved, especially in scenarios involving external API calls.

Editorial take

The fact that a vendor is willing to ship a dedicated prompt document for a single model matters more than anything inside the document.

My read: prompting has moved from "individual engineer craft" to "part of the product deliverable." It's the same trajectory as MCP standardization. AI engineering is consolidating fast, and the era of "prompt voodoo tuning" is winding down.

What's different this time: model iteration used to be slow, and one prompt template could survive across versions. Now the capability frontier moves quickly, and a pattern that excels on Opus 4.5 can actually hurt on 5.5. That pressure is forcing vendors to elevate prompt engineering docs to the same status as API references.

One thing I'm uncertain about: whether this "dedicated doc per model" pattern becomes an industry standard. OpenAI and Google are still using "general guide plus incremental updates." Anthropic's standalone page might just reflect how large the 5.5 changes are. If the 6.x series returns to incremental tweaks, the independent URL could quietly disappear.

Sources: Anthropic Opus 5.5 Prompting Guide | Hacker News discussion

Source: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5