Claude Opus 5.5 prompting tips from Anthropic's own guide
Practical prompting tips for Claude Opus 5.5, taken from Anthropic's guide: old habits to drop, the new effort default, agents that stop early, lines to copy.
At a glanceNine working habits for coding agents such as Claude Code: what to write down, how to phrase a task, how to make the agent check its work, and when to restart.
Not testedWritten from Anthropic's documentation. One shell line was run; the habits themselves were not measured.
Most time lost with a coding agent is not lost while it writes code. It is lost afterwards: reading a change that solved the wrong problem, correcting it three times, or discovering a day later that "all tests pass" was a summary and not a fact. The habits below aim at that rework. They come from Anthropic's guidance for Claude Code, but most apply to any agent that reads your repository and runs commands.
Every instruction you give an agent is one of two kinds. Anthropic's guide calls them non-deterministic and deterministic:
| Advice | Law | |
|---|---|---|
| Where it lives | Your prompt, the project instruction file, a skill | A hook, a deny rule, a managed setting, CI |
| Who applies it | The model reads it and decides | The tool enforces it every time |
| Good for | Guidelines with exceptions | Things that must always or never happen |
Most rules should be advice. The agent has the actual code in front of it and can usually judge whether a guideline fits. Reserve law for the few things with no exceptions, such as never editing a generated folder.
The guide offers a useful test. If you keep adding emphasis to a line in your instruction file and the agent still misses it, the line belongs in a hook. And the reverse: if you have hooks for things that are only preferences, delete them.
An agent starts each task by reading your code, and it is good at that. It finds the file layout, the conventions and the test framework faster than you can describe them. What it cannot find is what was never in the repository: a decision made in a meeting, a deploy process in one person's head, the environment variable the integration tests need.
Before adding anything to the instruction file, ask the guide's two questions:
If both answers are yes, leave it out. Every line in that file is read on every task, relevant or not, so a short file is a better file. What earns a place: the exact commands for tests, type checks and linting; places where the code is misleading; team decisions; and anything you have had to correct twice. The files themselves are covered in Claude Code project setup.
A specific prompt works for the same reason: it supplies information the agent does not have. The guide's own examples show the difference.
| Instead of | Try |
|---|---|
| "fix the login bug" | "users report login fails after the session times out. look at token refresh in src/auth/, write a failing test that reproduces it, then fix it" |
| "add a calendar widget" | "follow the pattern in HotDogWidget.php and build a calendar widget that lets you pick a month and page between years. no new libraries" |
The better versions contain three things: where to look, how to tell the problem is real, and what done looks like. They also state a preference between reasonable options, such as "no new libraries". An agent cannot read your preferences from the code.
Scope is the other thing only you know. An agent tends to build the smallest thing that satisfies the request. If you want empty states, error handling and keyboard navigation as well as the layout, say so in the prompt.
If you already have what the agent needs, give it directly:
@ and the path.cat error.log | claude -p "what's going on here".A retyped error message loses the line number, the stack trace and the one odd character that was the cause.
This is the habit with the largest effect. An agent stops when the work looks done. Without something to run, "looks done" is all it has, and you become the test suite. With a check, it can change the code, run the check, read the failure and try again without you.
The check can be a test file, a build's exit code, a linter, a script that compares output with a saved sample, or a browser screenshot next to the mockup. The guide puts it this way: if your repository already has one of these, the single most useful line in your instruction file is the command that runs it.
You choose how strict to be:
| Level | How | Who decides it passed |
|---|---|---|
| In the prompt | "run the auth tests after, and keep going until they pass" | The agent |
| As a stop condition | A hook that runs when the agent tries to finish | The tool |
| By a reviewer | A fresh review of the diff, or CI on the pull request | Something that did not write the code |
For the middle level in Claude Code, the guide's example is a Stop hook in .claude/settings.json:
{
"hooks": {
"Stop": [
{
"hooks": [
{ "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
]
}
]
}
}
Two details make it work. Exit code 2 is what blocks the stop; the hooks reference notes that exit code 1 does not block, even though 1 is the usual code for failure. And the output is redirected to standard error, because that is what the agent is shown as the reason it cannot finish.
The shell behaviour of that line was checked for this article: with a failing command it exits with status 2 and the message goes to standard error, and with a passing command it exits with 0. Replace pnpm tsc --noEmit with your own project's check.
Whichever level you use, ask for evidence: the command that was run and its output. Reading the output takes less time than rerunning the check, and for a session you did not watch it is the only evidence there is.
You do not need a finished specification before you start. The guide suggests asking for an interview:
I want to add rate limiting to the public API but haven't thought it through yet.
Interview me until you could write the spec, then write it to SPEC.md.
The agent asks about the parts you have not decided: per user or per key, what happens to requests over the limit, what is out of scope. Then start a fresh session and build from the written spec. The build begins with a clean context and a definition of done, and the same file is what a reviewer checks against later.
No configuration replaces watching how the agent starts. If it heads the wrong way, stop it at once; in Claude Code that is the Esc key, which keeps the work done so far.
The second half of this habit is counterintuitive. If you have corrected the same thing twice and it is still wrong, do not write a third correction. The conversation now contains two failed attempts that the agent keeps rereading. Clear the session and write one new prompt that includes what you learned. The guide's summary: watch the first minute, stop the moment it drifts, and after two failed corrections start over with a better prompt.
Tools that keep checkpoints make bold attempts cheap, because you can roll back. In Claude Code, note the limit the guide states: checkpoints cover files the agent edited with its own file tools, not files changed only by a shell command. Keep using version control.
A reviewer that saw the whole conversation is swayed by the reasoning that produced the code. A fresh one is not. In Claude Code, /code-review reviews the diff in a subagent that never saw your session.
To check the work against your plan, write the review prompt yourself. The guide's example:
use a subagent to review the rate limiter diff against SPEC.md, check every requirement
is implemented and the listed edge cases have tests, report gaps that affect correctness
and skip style
Keep the last two words. A reviewer asked to find problems always finds something. If you fix every finding, you end up with extra layers and tests for cases that cannot happen.
Every request sends the whole conversation. A session that has collected three unrelated tasks pays to reread all three on every turn of the fourth, and old context can blur the answer. Clear between unrelated tasks; in Claude Code, /clear does it and /usage shows where usage went.
Subagents are worth their cost in four cases, according to the guide: independent work that can run in parallel, long output you want kept out of the main conversation, a reviewer with fresh eyes, and a task that should have fewer tools. They cost tokens, and sometimes time, because a new subagent must first gather context your session already had. Handing the same task to a subagent does not make the answer better.
The same guide lists advice that was once useful and no longer is. A few entries:
| Old habit | Why it can go |
|---|---|
| Writing IMPORTANT in capitals | Current models follow a plainly worded line. Piled-on emphasis makes them over-apply the rule. If a rule cannot bend, make it a hook. |
| Describing the architecture and file layout in the instruction file | The agent reads the repository itself. Write down only what is not there. |
| "Think hard" and "be thorough" | These are ordinary prompt text. In Claude Code the effort setting is the real control. |
| "Keep going, don't be lazy" | Models usually carry on through an agreed task, and such lines cause over-work more often than they fix a stall. Give a check to pass instead. |
If you adopt one habit this week, make it the fifth: find the command that tells you whether your project is healthy, and put it in the instruction file. Then, the next time you ask for a change, end the prompt with "run it and show me the output". Most of the other habits follow from wanting that output to be trustworthy.
This article reflects public information available when it was written. Versions, defaults and prices can change; check the linked official documentation.
The habits are drawn from Anthropic's Claude Code best-practices page and hooks reference as read on November 12, 2026, and the two prompt examples in section 3 are quoted from that page. The one shell line in section 5 was run in a shell for this article to confirm its exit codes. Nothing here was measured across teams; treat the habits as a starting point and keep the ones that help you. Written for this site with AI assistance, from the sources above. For errors or additional information, please request a correction. Editorial policy
Found this useful? Share it, or follow for new guides.