Oscar Hoang
Articles

· AI & LLMs, Claude Opus 5.5, Claude Code, AI coding agents, effort levels, subagents, prompting

Claude Opus 5.5 Best Practices for Agentic Coding

Abstract illustration of an AI coding agent working through a long task

Opus 5.5 does best when you give it a clear spec and then get out of the way. Here I cover which effort level to pick, how to define "done", how to make it check its own work, and when to hand it a whole task.

This post starts from Maximilian Schwarzmüller's Academind video, "Stop treating Opus 5.5 like the other AI models". Below, each of his tips is lined up against Anthropic's documentation, with the spots where the two disagree called out.

The short answer: run Opus 5.5 at its default medium effort. Step up to high or xhigh only for harder or longer work. Tell it exactly what "done" means and give it a check it can run. Name the styles you don't want, let it delegate to subagents, and hand it whole tasks once the plan is agreed.

Why Opus 5.5 needs less hand-holding

You stop micromanaging steps and start specifying outcomes.

Max's main point is that Opus 5.5 is unusually consistent. In his words, "you don't need to handhold it as much as you do with other models." That's his impression after two days with it. Anthropic publishes no data on it, so treat it as a hypothesis to test.

Anthropic's own claims point the same way. The Opus 5.5 prompting guide says it sustains long autonomous work better than Opus 5, "such as multi-hour audits and migrations of large code bases run end to end with parallel subagents and little oversight." The launch post cites a 680,000-line code migration finished in under a day.

My read: if that holds up on your codebase, your job shifts to writing one good spec instead of ten small prompts.

Which effort level should you use for Opus 5.5?

Start at medium, the Opus 5.5 default. Move up only when the task calls for it.

Thinking is always on in Opus 5.5 and can't be turned off, which makes effort your main lever. The effort docs say Opus 5.5 defaults to medium. Opus 5 and earlier defaulted to high. In Anthropic's testing, Opus 5.5 at medium "matches or exceeds Claude Opus 5 at high" on coding and knowledge-work evaluations.

This is how I'd map the levels. The wording comes from Claude Code's model configuration docs:

Level Use it for Where I'd start
low Quick exchanges you review each time, a first sketch, a rename, subagents Small, reviewed edits
medium Default. Day-to-day engineering with a clear scope, like a new feature Most work
high Work where verification matters or edge cases are likely, like a bug in an existing codebase Bug fixes, tricky refactors
xhigh Long-running agentic and coding tasks (the API docs say over 30 minutes) Migrations and audits
max Hard problems you want worked through without you. Docs warn it "may show diminishing returns and is prone to overthinking" Only after testing

Where the video and the docs disagree

Max says to skip low because it's "far too dumb." On xhigh he's more nuanced. He ran one account on xhigh constantly as a test, but from Anthropic's benchmark charts he concludes "xhigh instead of high doesn't make a lot of sense," and calls the ideal "medium or high, or maybe also xhigh." Anthropic's docs read differently on both points. The prompting guide says that "on several coding evaluations low comes close to [Opus 5 at high] at much lower cost," and the effort docs list low as the typical choice for subagents. The API docs also position xhigh specifically for long agentic runs.

I think the two positions are closer than they look. Both land on medium as the default. Anthropic also covers the cheap end, where low suits small edits and subagents. On max they agree too. The guide says to reserve xhigh and max "for work where you've measured a quality gain." So before you settle, test two adjacent levels on your own tasks.

Setting it

In Claude Code:

/effort            # open the slider
/effort high       # set a level and save it as your default for this model
/effort auto       # back to the model default
/effort status     # show the level in effect

claude --effort xhigh   # launch a session at a given level

Per the docs, max only lasts for the current session unless you set it through the CLAUDE_CODE_EFFORT_LEVEL environment variable. If you want one deeper turn, put ultrathink in the prompt. "Think hard" is just plain text.

In the API, effort lives at output_config.effort:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

const response = await client.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 64000,
  output_config: { effort: "medium" }, // low | medium | high | xhigh | max
  messages: [{ role: "user", content: "Review this diff for edge cases: ..." }],
});

for (const block of response.content) {
  if (block.type === "text") console.log(block.text);
}

Thinking counts toward max_tokens, so leave room there. Also, changing top-level effort between requests invalidates the prompt cache.

Define "done" before it starts

Write down the finish line before the model starts. Then it knows when to stop and when to keep going.

Anthropic's guide on unattended agentic runs suggests stating "the completion condition up front" and keeping the task's parts in a checklist the model updates. Claude Code's best practices name the problem plainly: "Claude stops when the work looks done."

Max says he rarely needs to spell this out, because his skills already describe the loop. He also says you don't need plan mode for it. Agreeing on the endpoint in conversation is enough.

Here's the checklist I'd put in every plan:

  • Outcome: the result in one sentence.
  • Done means: conditions you can observe. Tests pass, no type errors, the old code is deleted.
  • Checks to run: the exact commands, plus any UI flow to click through.
  • Evidence: test output, command results, a screenshot.
  • Out of scope: what not to touch.
  • Known pitfalls: fragile modules and things that broke before.
  • Stop and ask only if: it hits a blocker it can't resolve, or before anything destructive.

Give it a way to verify its own work

Give Opus 5.5 a check that returns pass or fail, and ask it to show evidence.

The Claude Code docs open their best practices with this. Give Claude "a check it can run: tests, a build, a screenshot to compare." Unit tests are the floor. For UI work, the model has to see the page. Claude Code can drive a real browser through the Chrome integration (claude --chrome). Max uses Vercel Labs' agent-browser CLI.

Here's an illustrative CLAUDE.md section, written for this post. It isn't Max's file:

## Verification

- Verify every task before moving on: run the checks named in the plan.
- For UI changes, open the page in a real browser and check the console.
- Show evidence (command output or a screenshot). Don't just say it works.
- When all tasks are done, review the full diff before reporting.

## When to stop

- If a step doesn't need my input, keep going.
- Stop and ask only when you can't continue without me, or before anything destructive.

CLAUDE.md is plain Markdown with no frontmatter. The memory docs recommend keeping it under about 200 lines. If your repo already has an AGENTS.md, Claude Code can read it (v2.1.277 or later), but by default only when there's no CLAUDE.md or CLAUDE.local.md in the working directory or above it. To use both, put an @AGENTS.md import in your CLAUDE.md, or set Project instructions to claude-md-and-agents-md in /config.

Want a second opinion before calling a task done? The bundled /code-review skill reviews the current diff in a fresh subagent.

Workflow: agree the plan and done criteria, build one task, and repeat until the checks pass and all tasks are done, then review the full diff and report evidence

Be specific, especially about what you don't want

Name the exact patterns to avoid. A vague negative just swaps one default for another.

This tip comes straight from Anthropic's guide on frontend design defaults. An instruction like "avoid a generic AI look" mostly trades one default style for another. Their example bans cream backgrounds, italic accent words, "01/02/03" section labels, monospace labels and pill-shaped buttons. Max's own examples are "no purple gradients" and no eyebrow subtitles above titles.

Slides work the same way. See what it picked instead, then add to the list.

Let Opus 5.5 orchestrate subagents

Ask for subagents on complex or parallel work, even though Claude Code often delegates on its own.

The subagents docs say Claude automatically uses the built-in subagents when appropriate. Max still writes the instruction into his "implement plan" skill. As he puts it, it "increases the chance of it doing it," and the skill also gets used with other models. For large fan-outs, /batch splits a change across 5 to 30 subagents, each in its own worktree. Subagent frontmatter accepts model and effort, so the helpers can run cheaper than the lead.

Here's an illustrative skill with done criteria and delegation built in. Save it as .claude/skills/implement-plan/SKILL.md:

---
name: implement-plan
description: Implements an agreed plan task by task. Use when a plan has been settled and should now be built.
---

1. Keep the plan's tasks in TASKS.md and tick them off as you go.
2. Hand complex or parallel tasks to subagents and check each one's evidence before accepting it.
3. Verify every task with the checks the plan names before moving on.
4. The work is done only when every task passes its checks. Then review the full diff and report what you verified.

Max also runs one Claude Code session as an orchestrator over other agents on several machines, using Herdr, a terminal workspace manager for coding agents.

Plan first, then hand it the big task

Once you and the model share a clear plan, give it the whole job in one go instead of a string of small prompts.

Max's examples are migrating a full website to another stack and moving a library to Effect. That one ran for hours. He's clear that it only works after planning: a shared plan, clear completion criteria, the checks to run and known pitfalls.

The guardrails I'd keep are a TASKS.md checklist so progress stays visible, the stop rules from the CLAUDE.md above, and permission prompts left on for anything destructive.

Key takeaways

  • Default to medium. Test adjacent levels on your own tasks before moving up.
  • low is fine for small, reviewed edits and for subagents, whatever the video says.
  • Save xhigh for long agentic runs and max for measured gains.
  • Write down what done means, and give it a pass or fail check with evidence.
  • Name the styles you don't want.
  • Plan together, then hand over the whole task.

Setup checklist

  • Effort default chosen and tested (/effort status to confirm)
  • Done-criteria checklist in the plan template
  • CLAUDE.md with verification and stop rules
  • Browser verification set up for UI work
  • A list of style don'ts for frontend tasks
  • A skill or prompt that asks for subagents on parallel work
  • TASKS.md for long runs
  • Permission prompts kept for destructive actions

FAQ

What effort level should I use for Opus 5.5 in Claude Code? Start at medium, the default. Anthropic found it matches or beats Opus 5 at high on coding evaluations. Go to high for bug fixes and work with lots of edge cases, and to xhigh for long agentic runs.

Is max effort worth it on Opus 5.5? Usually not as a default. Claude Code's docs say it "may show diminishing returns and is prone to overthinking," and Anthropic's prompting guide says to reserve it for work where you've measured a gain.

Should I ever use low effort with Opus 5.5? Yes, for small changes you review and for subagents. Anthropic says low comes close on several coding evaluations at much lower cost. Test it on your own tasks before you rule it out.

How do I stop Claude Code from stopping early? Say what "done" means up front and keep the task list in a file. Then add a CLAUDE.md rule telling it to keep going unless it's blocked or about to do something destructive.

Do I still need to tell Opus 5.5 to "think hard"? No. Thinking is always on, and effort is the control. In Claude Code, only the ultrathink keyword requests a deeper turn. "Think hard" is treated as plain text.

Sources