Claude Code Best Practices

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

Claude Code is an agentic coding environment. Unlike a chatbot that answers questions and waits, Claude Code can read your files, run commands, make changes, and autonomously work through problems while you watch, redirect, or step away entirely. This changes how you work. Instead of writing code yourself and asking Claude to review it, you describe what you want and Claude figures out how to build it. Claude explores, plans, and implements. But this autonomy still comes with a learning curve. Claude works within certain constraints you need to understand. This guide covers patterns that have proven effective across Anthropic’s internal teams and for engineers using Claude Code across various codebases, languages, and environments. For how the agentic loop works under the hood, see How Claude Code works .

Most best practices are based on one constraint: Claude’s context window fills up fast, and performance degrades as it fills. Claude’s context window holds your entire conversation, including every message, every file Claude reads, and every command output. However, this can fill up fast. A single debugging session or codebase exploration might generate and consume tens of thousands of tokens. This matters since LLM performance degrades as context fills. When the context window is getting full, Claude may start “forgetting” earlier instructions or making more mistakes. The context window is the most important resource to manage. To see how a session fills up in practice, watch an interactive walkthrough of what loads at startup and what each file read costs. Track context usage continuously with a custom status line , and see Reduce token usage for strategies on reducing token usage.

​

Give Claude a way to verify its work

Give Claude a check it can run: tests, a build, a screenshot to compare. It’s the difference between a session you watch and one you walk away from.

Claude stops when the work looks done. Without a check it can run, “looks done” is the only signal available, and you become the verification loop: every mistake waits for you to notice it. Give Claude something that produces a pass or fail, and the loop closes on its own. Claude does the work, runs the check, reads the result, and iterates until the check passes. The check is anything that returns a signal Claude can read in the conversation: a test suite, a build exit code, a linter, a script that diffs output against a fixture, or a browser screenshot compared against a design. Strategy Before After Provide verification criteria ”implement a function that validates email addresses" "write a validateEmail function. example test cases: user@example.com is true, invalid is false, user@.com is false. run the tests after implementing” Verify UI changes visually ”make the dashboard look better" "[paste screenshot] implement this design. take a screenshot of the result and compare it to the original. list differences and fix them” Address root causes, not symptoms ”the build is failing" "the build fails with this error: [paste error]. fix it and verify the build succeeds. address the root cause, don’t suppress the error”

Once the check exists, decide how hard it gates the stop:

In one prompt : ask Claude to run the check and iterate in the same message, as in the table above.

Across a session : set the check as a /goal condition . A separate evaluator re-checks it after every turn and Claude keeps working until it holds.

As a deterministic gate : a Stop hook runs your check as a script and blocks the turn from ending until it passes. Claude Code overrides the hook and ends the turn after 8 consecutive blocks.

By a second opinion : a verification subagent or a dynamic workflow that checks its own findings has a fresh model try to refute the result, so the agent doing the work isn’t the one grading it.

Each step trades setup for attention. The prompt version works on any task today. The /goal and Stop hook versions are what let an unattended run finish correctly without you. Have Claude show evidence rather than asserting success: the test output, the command it ran and what it returned, or a screenshot of the result. Reviewing evidence is faster than re-running the verification yourself, and it works for sessions you weren’t watching.

​

Explore first, then plan, then code

Separate research and planning from implementation to avoid solving the wrong problem.

Letting Claude jump straight to coding can produce code that solves the wrong problem. Use plan mode to separate exploration from execution. The recommended workflow has four phases:

1

Explore Enter plan mode. Claude reads files and answers questions without making changes. claude (plan mode)

read /src/auth and understand how we handle sessions and login. also look at how we manage environment variables for secrets.

2

Plan Ask Claude to create a detailed implementation plan. claude (plan mode)

I want to add Google OAuth. What files need to change? What's the session flow? Create a plan.

Press Ctrl+G to open the plan in your text editor for direct editing before Claude proceeds.

3

Implement Switch out of plan mode and let Claude code, verifying against its plan. claude (default mode)

implement the OAuth flow from your plan. write tests for the callback handler, run the test suite and fix any failures.

4

Commit Ask Claude to commit with a descriptive message and create a PR. claude (default mode)

commit with a descriptive message and open a PR

Plan mode is useful, but also adds overhead. For tasks where the scope is clear and the fix is small (like fixing a typo, adding a log line, or renaming a variable) ask Claude to do it directly. Planning is most useful when you’re uncertain about the approach, when the change modifies multiple files, or when you’re unfamiliar with the code being modified. If you could describe the diff in one sentence, skip the plan.

​

Provide specific context in your prompts

The more precise your instructions, the fewer corrections you’ll need.

Claude can infer intent, but it can’t read your mind. Reference specific files, mention constraints, and point to example patterns. Strategy Before After Scope the task. Specify which file, what scenario, and testing preferences. ”add tests for…