Opus 5.5's prompting guide is a diff, not a doc — here's what changed

What happened

Anthropic quietly dropped a dedicated prompting guide for Claude Opus 5.5 at `platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5`. The HN thread hit 108 points in a few hours, which for a docs page is a tell: practitioners are reading it as a changelog, not a tutorial.

The guide is unusually specific about what to *stop* doing. Anthropic is explicitly telling developers to strip the 'you are an expert Python developer with 20 years of experience' preambles that have been cargo-culted across every LangChain tutorial since 2023. The claim is that Opus 5.5 already assumes competence and that role-priming now introduces noise more often than it shapes behavior. In its place, the doc pushes concrete task framing — describe the artifact you want, the constraints, the failure modes to avoid — and leaves the model's self-conception alone.

The second big shift is around tool use. The guide leans hard on giving each tool a tight, JSON-schema-shaped contract with explicit examples of when *not* to call it. Anthropic's own internal eval numbers, referenced in the doc, suggest that adding negative examples ("do not call `search_web` if the answer is in the current conversation") reduces spurious tool calls by a material margin. It also formally deprecates the older pattern of stuffing tool selection logic into the system prompt as prose.

Why it matters

Every model release ships with implicit prompting norms, but they're usually reverse-engineered by the community over the following month. Publishing them upfront is a small operational courtesy that saves a lot of A/B testing. The subtext is that Anthropic has finally accepted that most Claude usage now happens inside agent loops and IDE integrations, not chat UIs, and the prompting advice has to reflect that.

Compare this to the guidance for Sonnet 4 and even the original Opus 4.5 release, which still gently endorsed multi-shot examples and chain-of-thought scaffolding. Opus 5.5's guide is the opposite: it argues that internal reasoning is now strong enough that adding "think step by step" or manually decomposed reasoning steps in the prompt tends to *degrade* output on hard tasks by anchoring the model to a suboptimal decomposition. The doc's recommendation is to let the model plan and only intervene if the plan is wrong — a very different posture than the meticulous scaffolds people were writing 18 months ago.

There's also a subtle but important change in how the guide talks about context. Rather than the classic 'put the most important thing last' rule, Anthropic now recommends structuring long-context prompts with explicit XML-tagged sections and a short 'reading order' hint at the top, arguing that Opus 5.5's attention allocation benefits more from structure than from positional tricks. For anyone shoving 100k tokens of codebase into a request, this is not academic — it's the difference between the model finding the right file and confidently editing the wrong one.

The community reaction on HN is split along predictable lines. Working engineers are treating the doc as the release notes it effectively is; the sentiment is closer to "finally" than "wow." The skeptics, meanwhile, are latching onto the meta-point: if prompting best practices need to be relearned every 6-12 months per model, that's a real tax on anyone maintaining a serious prompt library. One top comment puts it plainly: "My prompts are now versioned per model. That's fine for us, but I don't envy anyone shipping SDKs that wrap Claude."

What this means for your stack

If you're running Opus in production, three concrete audits are worth doing this week. First, grep your prompts for 'You are a' and 'act as' — those openers are now dead weight at best and mildly harmful at worst. Delete them and re-run your evals; most teams report neutral-to-positive movement, and you'll shave tokens off every request. Second, look at your tool definitions. If your tool descriptions are prose ('This tool searches the web when the user wants recent information...'), rewrite them as tight schemas with explicit negative examples. Anthropic's own numbers suggest this alone can meaningfully cut latency on agent loops by reducing round-trips.

Third, and least obvious: if you've been doing manual chain-of-thought — asking the model to output reasoning steps before the answer — test whether removing it hurts. On Opus 5.5, the guide's implicit claim is that it usually won't, and you'll get faster, cheaper responses. The exception is genuinely novel multi-step math or planning tasks, where explicit CoT still helps. But the default should flip from "add CoT" to "try without CoT first."

For teams shipping products on top of Claude — Cursor, Zed, the pile of agentic coding startups — this guide is basically a spec for the next round of prompt engineering. Expect the wrapper ecosystem to churn through a new set of default system prompts over the next few weeks, and expect a lag before third-party benchmarks catch up to what the model can actually do when prompted correctly.

Looking ahead

The broader pattern here is that prompting is professionalizing into something closer to compiler tuning — model-specific, empirical, and increasingly divorced from the folk wisdom of the ChatGPT era. Anthropic publishing this guide on release day rather than three months later is a small acknowledgment that the ecosystem has enough serious users that vibes-based prompting no longer scales. The next question is whether OpenAI and Google follow suit with the same specificity, or whether Claude's docs become the de facto reference for anyone trying to figure out how these models actually want to be talked to.