OmniscioGuidesClaude Code best practices
Claude Code best practices
Most of the time a plain prompt in a fresh session already does the right thing. Anthropic's own best-practices page is about the rest: the project knowledge, rules and checks that no default could guess.
This page covers what to write down, how to phrase the prompt, how to give Claude a check it can close the loop on, which rules must leave CLAUDE.md, and the older advice Anthropic says to stop following.
Last checked against Anthropic's best practices documentation on November 17, 2026. By the Omniscio team. Updated .
On this page
- The three ways a session goes wrong
- Tell Claude what it cannot see
- Give Claude a check to run
- Enforce the rules that cannot bend
- Steer a session that drifts
- Running without you
- Advice worth dropping
The settings files these habits write to are covered separately, in where settings.json lives and the CLAUDE.md guide.
The three ways a session goes wrong
Anthropic says that when a session does not go as expected, it is almost always one of these:
- Claude built something different from what you had in mind, or it rediscovers the same fact at the start of every session.
- Claude said it was done and it was not quite, usually because it had no way to check its own work.
- Claude did something that must never happen in this repo, or skipped a step that must always run.
Each cause has one fix, and they are the rest of this page: tell it what it cannot see, give it a check, and enforce the rules that cannot have exceptions.
Source: the introduction of Anthropic's best practices page, read November 17, 2026.
Tell Claude what it cannot see
Claude already reads your code well. Anthropic's rule is to write down only what Claude cannot find that way, or what it would otherwise spend time rediscovering every session.
The test is two questions. Could Claude find this by reading the code? Would it actually go and look? If both answers are yes, leave the line out.
What is left is the information that was never in the repo: a decision made in a meeting, a deploy process that lives in one person's head, the environment variable your integration tests need.
A specific prompt does the same job for one task. Anthropic contrasts “fix the login bug” with naming the symptom, the file and the check: users report login failing after the session times out, look at token refresh in the auth folder, write a failing test, then fix it.
That example has the shape of a prompt that works. Say what is broken and who sees it, point at where to look, say what “fixed” means, and name the check to run. Here is the same shape with the words filled in:
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 and run the auth tests
until they pass.Naming the check is the part people skip. It is also the part that lets Claude keep going without you, which the next section covers.
“Be ambitious” is the one phrase Anthropic says still helps, because it tells Claude about scope, which only you know. Think step by step and be thorough are ordinary prompt text, not keywords.
When you have the thing Claude needs, hand it over instead of describing it: @ plus a path for a file, a pasted screenshot, or command output piped to claude -p.
And when you have not decided what you want yet, ask Claude to interview you until it could write the spec. Then start a fresh session to build from that file, so the build begins with a clean context and a written definition of done.
Sources: the tell-Claude-what-it-cant-see and write-a-specific-prompt sections of Anthropic's best practices page, read November 17, 2026.
Give Claude a check to run
Claude stops when the work looks done. If it has nothing to run that says whether the work is done, looking done is all it has, and in practice you become the test suite.
Give it something that comes back pass or fail and it closes that loop itself: it makes the change, runs the check, reads the failure and fixes it. Anthropic's list is a test file, a build exit code, a linter, a script that diffs output against a fixture, or a screenshot next to a mockup.
If your repo already has one, the single most useful line in your CLAUDE.md is the command that runs it. That is the whole reason to write that file, in one sentence.
How strict the check is, is your choice. In the prompt, “run the auth tests after, and keep going until they pass” needs no setup at all, and Claude decides when it is satisfied.
Stricter is /goal, which sets a condition a separate model checks after every turn, and is most useful for long background runs that would otherwise end with a progress summary. Type it with the condition, as in /goal all tests in tests/auth pass and lint is clean.
Strictest is a Stop hook: a script that runs whenever Claude tries to end its turn, and sends it back to work when the script exits with code 2. Anthropic notes Claude Code overrides the next block after eight blocked stops in a row with no tool call between them, and the cap can be raised with CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.
Whatever the mechanism, ask for evidence: the command it ran and its output, or the screenshot. “All tests pass” on its own tells you very little.
The hooks guide covers writing and registering the hook itself.
Sources: the give-Claude-a-check-to-run and enforce-the-check-with-a-stop-hook sections of Anthropic's best practices page, read November 17, 2026.
Enforce the rules that cannot bend
Take three lines you might have in CLAUDE.md: never read .env, always run the formatter after editing, do not touch the migrations folder. Claude will follow each of them almost every time, and almost is the problem for a rule that cannot bend.
Anthropic's line is blunt: if something has to happen every time, make it a hook, a deny rule, or a managed setting. CLAUDE.md is for guidelines, and Claude is allowed to decide a guideline does not apply.
Hooks run your code at fixed points in the loop: before or after a tool call, when Claude tries to stop, or when a session starts. A deny rule in the permissions settings stops a path being read or edited whatever Claude decides.
The reverse test matters too. If you keep adding emphasis to a CLAUDE.md line and Claude still misses it, that is a sign the line belongs in a hook. If you have hooks for things that are only preferences, delete them and let Claude decide.
Source: the enforce-the-rules-that-cant-have-exceptions section of Anthropic's best practices page, read November 17, 2026.
Steer a session that drifts
No configuration replaces watching the first minute. Anthropic's advice is to press Esc the moment Claude heads somewhere you did not intend, and after two failed corrections to run /clear rather than correcting a third time.
Esc stops Claude mid-action and keeps everything up to that point, so you can redirect without losing work. /rewind, or Esc twice on an empty prompt, opens a menu that rolls the code, the conversation or both back to an earlier prompt.
That makes it cheap to try the bolder approach first. Anthropic warns that checkpoints cover files Claude edited with its own file tools, so a file only a Bash command touched is not restored, and checkpoints work alongside git rather than replacing it.
/clear plus one new prompt that folds in what you learned beats a third correction almost every time. The failed attempts stay in the conversation otherwise, and Claude keeps re-reading them.
Source: the steer-the-session section of Anthropic's best practices page, read November 17, 2026.
Running without you
Everything above matters more when nobody is watching. While you are there, Claude missing a piece of context is a minor annoyance; in a run you started before bed, nobody tells it, and it can spend the night on the wrong assumption.
Anthropic's five questions before an unattended run. Does it know what done looks like, as a goal, a spec file or a failing test? Can it check its own work, through the suite, a Stop hook or a review step?
What is it allowed to touch? Permission rules, the sandbox, a worktree, one branch. What stops it? A cap on turns or spend, and --max-turns and --max-budget-usd are flags you pass when you start Claude. And where does the result go, with a person approving anything you cannot take back?
The parts that stay with you are starting the run, deciding what done means this time, and approving the merge at the end.
The usage limits guide covers the caps and what happens when one is reached.
Source: the let-Claude-run-without-you section of Anthropic's best practices page, read November 17, 2026.
Advice worth dropping
Anthropic keeps a table of advice that was good when it was written and is now a habit. Six of them are worth knowing, because each one costs tokens or attention for nothing.
- Managing the context window aggressively. Most current models have a 1M-token window and compaction happens on its own.
/clearbetween tasks is still worth doing, for a focused context. - Adding IMPORTANT or ALL CAPS. Current models follow a plainly worded line, and piling on emphasis makes Claude over-apply the rule.
- Subagents to protect context. Running out is rarely the problem. They still help for parallel work and independent review, at extra token cost.
- Subagents for a better answer. The same task handed to a subagent is not answered better. A fresh reviewer helps because it has not seen your reasoning.
- Think hard, think harder, be thorough. Effort is the control. Those phrases nudge within the effort setting rather than raising it.
ultrathinkis the exception: Anthropic documents it as asking for deeper reasoning on that one turn without moving the setting. - Describing your architecture in CLAUDE.md. Claude reads the repo itself. Only write down what is not in there.
The effort level guide covers the setting those phrases do not change, and the context window guide covers what compaction keeps.
Source: the what-you-can-stop-doing table on Anthropic's best practices page, read November 17, 2026.
Running several sessions at once
These habits are per project, so every session in a repository inherits them. Omniscio, the desktop app we make for running many Claude Code sessions at once, puts those sessions in one window with a sidebar instead of separate terminals.
It is free to use with up to 8 projects. Pro is $20/month or $192/year, and neither plan includes an AI allowance.
The multi-session guide compares the ways to run more than one, and running many coding agents at once covers what changes at five and above.
Where these answers come from
- Anthropic, Best practices for Claude Code: the three failure modes, the write-down test, the prompt examples, the check options including
/goaland the Stop hook, the hooks-versus-CLAUDE.md rule, the steering controls, the unattended-run questions, and the advice-to-drop table. Read November 17, 2026. - Anthropic, Hooks: the Stop hook's exit code 2 and its eight-block cap. Read November 17, 2026.
Anthropic's page changes often. Read it again before trusting an older copy.
Common questions
What should go in CLAUDE.md?
Only what Claude cannot work out by reading the repo: the exact commands that confirm work here, places where the code is misleading, decisions that live outside the repo, and anything you have already had to correct twice. If Claude could find it in the code and would go and look, leave it out.
Why does Claude stop before the work is really finished?
Usually because it has nothing to run that comes back pass or fail, so looking done is all it has. Give it a test, a linter, a build exit code or a script, and name that command in CLAUDE.md. A Stop hook can enforce it so the turn does not end until the check passes.
Does saying think harder or ultrathink make Claude reason more?
Effort is the control for how hard Claude thinks. Phrases such as think hard or be thorough are ordinary prompt text that nudge Claude within its effort setting rather than keywords that raise it. ultrathink still works: it asks for deeper reasoning on that one turn without changing the setting.
How do I make a rule that Claude can never skip?
Move it out of CLAUDE.md into something the harness applies: a hook, a permission deny rule, or a managed setting. CLAUDE.md is a guideline Claude is allowed to judge inapplicable, so anything that must happen every time belongs in configuration instead.
When should I run /clear instead of correcting Claude again?
After you have corrected the same thing twice and it is still wrong. A third correction adds to a conversation that already holds two failed attempts Claude keeps re-reading. /clear plus one new prompt that folds in what you learned works better almost every time.
What should I check before leaving Claude running unattended?
Five things: does it know what done looks like, can it check its own work, what is it allowed to touch, what stops it, and where does the result go with who signs off. --max-turns and --max-budget-usd are the caps Anthropic names.
Good habits, and a window for every session
Omniscio runs many Claude Code sessions side by side, each one with the same project rules. The features page lists what it does today.