Best practices for Claude Code - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. Claude Code is built in a way that, in most cases, your first plain prompt in a fresh session already does the right thing, without any setup on your part. For example: To let commands run without you approving each one, new terminal and VS Code sessions start in auto mode .
To keep your main conversation focused while independent work happens in parallel, Claude delegates to subagents and checks in only when it has to. To keep a long session going without you managing it, your conversation is compacted automatically before the context window fills. This page covers what to do when the defaults aren’t enough. That usually happens when your project has knowledge, rules, or constraints that Claude can’t see from the code alone: A deploy process that lives in someone’s head A file that must never be read A check that has to pass before anything counts as done A budget you need to stay under No default can know those things about your project, so this is where a small amount of setup on your side pays off.
When a session doesn’t go the way you expected, it’s almost always one of these: Claude built something different from what you had in mind, or it has to rediscover the same fact at the start of every session. It’s missing information it can’t get from reading the repo. See Tell Claude what it can’t see . Claude said it was done and it wasn’t quite, usually because it had no way to check its own work. See Give Claude a check to run .
Claude did something that must never happen in this repo, or skipped a step that must always happen. A prompt alone can’t guarantee either of those. See Enforce the rules that can’t have exceptions . Claude got it right, but it took more time, tokens, or permission prompts than the task was worth. See Change a default . Let Claude run without you applies the same four points to unattended runs, and What you can stop doing lists the advice that current models have made unnecessary.
Setup for a whole team is on a separate page: Set up Claude Code for your organization . Deterministic and non-deterministic instructions Every instruction you give Claude Code is one of these: Non-deterministic: you write the instruction, and Claude (the model) reads it. This can be your prompt, CLAUDE.md , or a skill. The model then decides what to do with this information. It usually follows your commands, and current models are good at understanding your intent without much context, but there’s no guarantee that it’ll follow your instructions.
It can still decide not to do things, or do other things. Deterministic: you configure the instruction, and Claude Code (the harness) has to execute this. This can be a hook, a deny rule, or a managed setting. Claude Code applies this every time, no matter what the model decided to do. Most things in Claude Code come in both forms: Non-deterministic (Claude decides) Deterministic (Claude Code enforces) What to do Your prompt, CLAUDE.md , skills Claude picks up itself Hooks, and which skills only you can start What it can touch Auto mode’s classifier Deny rules, the sandbox in strict mode , managed settings When it’s done A request for evidence, /goal , /code-review Tests, typecheck, a Stop hook, CI How much it spends Effort level, Claude’s own pace --max-turns or --max-budget-usd with -p , a spend limit you’ve set Who has the last word Claude’s summary of what it did Branch protection, a person who approves the merge Most of the time, you want Claude to decide.
Almost every guideline has exceptions, and current models are good at reading the code in front of them and judging whether a guideline fits the situation. With the actual code in front of it, Claude is usually better placed to make that call than a rule you wrote in advance. The deterministic kind is for when you want to make sure certain things always happen (or never happen), no matter what the model decides. This doesn’t have to be anything dramatic.
Auto mode already blocks the dramatic things , like a production deploy or a force push over someone’s work. It’s usually something specific to your project, and it can be as niche as you want it to be: Never edit the generated client in src/gen/ Always run the license-header script after creating a file You could’ve written either of these as a line in CLAUDE.md or in your prompt, and Claude would follow it nearly every time.
But no matter how strongly you word it, whether Claude follows that line on a given turn is still Claude’s call. If you keep adding emphasis to a CLAUDE.md line and Claude still misses it, that’s a sign the line belongs in a hook. The reverse holds too: if you have hooks for things that are only preferences, delete them and let Claude decide. Tell Claude what it can’t see Only write down what Claude can’t find by reading the repo, or what it would otherwise spend time rediscovering every session.
Claude starts every task by reading your code, and current models are very good at this. They’ll find your file layout, your conventions, your test framework, and how existing components are built, usually faster than you could explain them. That means Claude already knows most of what you might be tempted to write down for it. What it can’t find is the information that was never in the repo: A decision your team made in a meeting A deploy process that lives in one person’s head The environment variable your integration tests need There’s also information that is in the repo but takes a few minutes of digging to find, and Claude has to redo that digging at the start of every session.
A good test before you write anything down for Claude: Could it find this by reading the code? Would it actually go and look? If both are yes, leave it out. Write a specific prompt A specific prompt helps for the same reason, because it gives Claude information it doesn’t already have. If you name the file, describe the symptom, and say what “fixed” looks like up front, you usually save yourself a round of corrections later.
The same goes for a preference between two reasonable approaches: Claude can’t read that from the code, so if you care which one it picks, say so up front. 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” If you already have the thing Claude needs, hand it over instead of describing it: A file: type @ and the path to include the file contents in your message.
An image: paste the screenshot of the design or the error into the prompt. Command output: pipe it in from your shell with cat error.log | claude -p "what's going on here" . Phrases like think step by step or be thorough are ordinary prompt text rather than keywords. The main control for how hard Claude thinks is the effort level , which Change the model and effort covers. Wording like that can still nudge Claude within its effort setting, but it won’t lift it past it.
One phrase that does still help is be ambitious . Claude tends to read a request conservatively and build the smallest thing that satisfies it, since it can’t see how much you were hoping for. When you want the fuller version, with the edge cases handled and the natural follow-on included, say so: build the settings page from the mockup. be ambitious: empty and error states, the save flow wired up, keyboard navigation, not just the layout That’s telling Claude about scope, which only you know, rather than how hard to think.
And when you’re exploring rather tha
The rest of this page is on the live site.