Claude Code: Best Practices for Agentic Coding

Claude Code: Best Practices for Agentic Coding

By Boris Cherny and the Claude Code Team at Anthropic

A comprehensive guide to getting the most out of Claude Code, from configuring your environment to scaling across parallel sessions.

---

Preface

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.

---

Chapter 1: The Fundamental Constraint

Most best practices in this guide 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 because 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. Track context usage continuously with a custom status line.

The key insight behind all of these best practices: intelligence is not the bottleneck -- context is. Every organization has unique workflows, standards, and knowledge systems, and Claude does not inherently know any of these. The key to making Claude successful is giving it the right context.

---

Chapter 2: Give Claude a Way to Verify Its Work

This is the single highest-leverage thing you can do.

Include tests, screenshots, or expected outputs so Claude can check itself. Claude performs dramatically better when it can verify its own work -- running tests, comparing screenshots, and validating outputs.

Without clear success criteria, Claude might produce something that looks right but actually does not work. You become the only feedback loop, and every mistake requires your attention.

Verification Strategies

Provide verification criteria:

• Before: "implement a function that validates email addresses"
• After: "write a validateEmail function. example test cases: [email protected] is true, invalid is false, [email protected] is false. run the tests after implementing"

Verify UI changes visually:

• Before: "make the dashboard look better"
• After: "[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:

• Before: "the build is failing"
• After: "the build fails with this error: [paste error]. fix it and verify the build succeeds. address the root cause, don't suppress the error"

Your verification can also be a test suite, a linter, or a Bash command that checks output. Invest in making your verification rock-solid.

Internal teams at Anthropic report a 2-3x improvement in output quality when Claude can check its own work, stemming from tighter feedback loops.

---

Chapter 3: Explore First, Then Plan, Then Code

Separate research and planning from implementation to avoid solving the wrong problem. Use Plan Mode to separate exploration from execution.

The recommended workflow has four phases:

Phase 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.

Phase 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.

Phase 3: Implement

Switch back to Normal Mode and let Claude code, verifying against its plan.

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

Phase 4: Commit

Ask Claude to commit with a descriptive message and create a PR.

claude (Normal Mode)
commit with a descriptive message and open a PR

When to Skip Planning

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 are uncertain about the approach, when the change modifies multiple files, or when you are unfamiliar with the code being modified. If you could describe the diff in one sentence, skip the plan.

---

Chapter 4: Provide Specific Context in Your Prompts

The more precise your instructions, the fewer corrections you will need. Claude can infer intent, but it cannot read your mind. Reference specific files, mention constraints, and point to example patterns.

Prompting Strategies

Scope the task: Specify which file, what scenario, and testing preferences.

• Before: "add tests for foo.py"
• After: "write a test for foo.py covering the edge case where the user is logged out. avoid mocks."

Point to sources: Direct Claude to the source that can answer a question.

• Before: "why does ExecutionFactory have such a weird api?"
• After: "look through ExecutionFactory's git history and summarize how its api came to be"

Reference existing patterns: Point Claude to patterns in your codebase.

• Before: "add a calendar widget"
• After: "look at how existing widgets are implemented on the home page to understand the patterns. HotDogWidget.php is a good example. follow the pattern to implement a new calendar widget that lets the user select a month and paginate forwards/backwards to pick a year. build from scratch without libraries other than the ones already used in the codebase."

Describe the symptom: Provide the symptom, the likely location, and what "fixed" looks like.

• Before: "fix the login bug"
• After: "users report that login fails after session timeout. check the auth flow in src/auth/, especially token refresh. write a failing test that reproduces the issue, then fix it"

Vague prompts can be useful when you are exploring and can afford to course-correct. A prompt like "what would you improve in this file?" can surface things you would not have thought to ask about.

Provide Rich Content

You can provide rich data to Claude in several ways:

• Reference files with @ instead of describing where code lives. Claude reads the file before responding.
• Paste images directly. Copy/paste or drag and drop images into the prompt.
• Give URLs for documentation and API references. Use /permissions to allowlist frequently-used domains.
• Pipe in data by running cat error.log | claude to send file contents directly.
• Let Claude fetch what it needs. Tell Claude to pull context itself using Bash commands, MCP tools, or by reading files.

---

Chapter 5: Configure Your Environment

A few setup steps make Claude Code significantly more effective across all your sessions.

Write an Effective CLAUDE.md

CLAUDE.md is a special file that Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules. This gives Claude persistent context it cannot infer from code alone.

Run /init to generate a starter CLAUDE.md file based on your current project structure, then refine over time.

There is no required format for CLAUDE.md files, but keep it short and human-readable. For example: