Claude Code isn't a chatbot that answers questions and waits. It reads your files, runs commands, makes changes, and autonomously works 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.
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.
The Core Constraint: Context Window
Most best practices stem from one constraint: Claude's context window fills up fast, and performance degrades as it fills.
The context window holds your entire conversation — every message, every file Claude reads, every command output. A single debugging session might consume tens of thousands of tokens. When the window is getting full, Claude may start "forgetting" earlier instructions or making more mistakes.
Managing your context window is the foundation of effective Claude Code use.
1. Give Claude a Way to Verify Its Work
Claude performs dramatically better when it can verify its own work — run tests, compare screenshots, validate outputs. Without clear success criteria, you become the only feedback loop.
| 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. 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 | "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" |
Your verification can be a test suite, a linter, or a Bash command that checks output. Invest in making your verification rock-solid.
2. Explore First, Then Plan, Then Code
Letting Claude jump straight to coding can produce code that solves the wrong problem. Use plan mode to separate exploration from execution.
The recommended four-phase workflow:
Phase 1 — Explore (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 (Plan mode)
I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.
Phase 3 — Implement (Default 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
commit with a descriptive message and open a PR
When to skip planning: For tasks where the scope is clear and the fix is small (fixing a typo, adding a log line, renaming a variable), ask Claude directly. Planning is most useful when you're uncertain about the approach or the change touches multiple files.
3. Provide Specific Context in Your Prompts
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 | "add tests for foo.py" | "write a test for foo.py covering the edge case where the user is logged out. avoid mocks." |
| Point to sources | "why does ExecutionFactory have such a weird api?" | "look through ExecutionFactory's git history and summarize how its api came to be" |
| Reference existing patterns | "add a calendar widget" | "look at how existing widgets are implemented on the home page. 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." |
| Describe the symptom | "fix the login bug" | "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" |
Provide rich content:
- Reference files with
@ instead of describing where code lives
- Paste images directly into the prompt
- Give URLs for documentation and API references
- Pipe in data with
cat error.log | claude
Write an effective CLAUDE.md
CLAUDE.md is a special file Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules.
# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible
# Workflow
- Be sure to typecheck when done making a series of code changes
- Prefer running single tests over the whole test suite for performance
What to include vs. exclude:
| ✅ Include | ❌ Exclude |
|---|
| Bash commands Claude can't guess | Anything Claude can figure out by reading code |
| Code style rules that differ from defaults | Standard language conventions Claude already knows |
| Testing instructions and preferred test runners | Detailed API documentation (link instead) |
| Repository etiquette (branch naming, PR conventions) | Information that changes frequently |
| Architectural decisions specific to your project | Long explanations or tutorials |
If CLAUDE.md is too long, Claude ignores half of it. For each line ask: "Would removing this cause Claude to make mistakes?" If not, cut it.
Three ways to reduce interruptions:
- Auto mode: A classifier model reviews commands and blocks only what looks risky
- Permission allowlists: Permit specific safe tools like
npm run lint or git commit
- Sandboxing: OS-level isolation that restricts filesystem and network access
CLI tools like gh, aws, gcloud, and sentry-cli are the most context-efficient way to interact with external services. Install the gh CLI for GitHub — Claude knows how to use it for creating issues, opening pull requests, and reading comments.
Connect MCP servers
With MCP servers, you can ask Claude to implement features from issue trackers, query databases, analyze monitoring data, integrate designs from Figma, and automate workflows.
Set up hooks
Hooks run scripts automatically at specific points in Claude's workflow. Unlike CLAUDE.md instructions (advisory), hooks are deterministic and guarantee the action happens:
Write a hook that runs eslint after every file edit.
Create skills
Skills extend Claude's knowledge with project, team, or domain-specific information. Add a SKILL.md under .claude/skills/:
---
name: api-conventions
description: REST API design conventions for our services
---
# API Conventions
- Use kebab-case for URL paths
- Use camelCase for JSON properties
- Always include pagination for list endpoints
5. Manage Your Session
Course-correct early and often
Esc: Stop Claude mid-action. Context is preserved, so you can redirect.Esc + Esc or /rewind: Restore previous conversation and code state./clear: Reset context between unrelated tasks.
If you've corrected Claude more than twice on the same issue, the context is cluttered with failed approaches. Run /clear and start fresh with a more specific prompt.
Manage context aggressively
- Use
/clear frequently between tasks to reset the context window entirely
- Run
/compact <instructions> for more control (e.g., /compact Focus on the API changes)
- For quick questions that don't need to stay in context, use
/btw — the answer appears in a dismissible overlay without entering conversation history
Use subagents for investigation
Since context is your fundamental constraint, subagents are one of the most powerful tools available. They explore in separate context windows and report back summaries:
Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.
Rewind with checkpoints
Claude automatically checkpoints before changes. Double-tap Escape or run /rewind to open the rewind menu. You can restore conversation only, code only, or both. Checkpoints persist across sessions.
6. Automate and Scale
Non-interactive mode
# One-off queries
claude -p "Explain what this project does"
# Structured output for scripts
claude -p "List all API endpoints" --output-format json
# Streaming for real-time processing
claude -p "Analyze this log file" --output-format stream-json
Run multiple Claude sessions
- Worktrees: Run separate CLI sessions in isolated git checkouts so edits don't collide
- Writer/Reviewer pattern: One session implements a feature, another reviews for edge cases and inconsistencies with existing patterns
Fan out across files
For large migrations or analyses, distribute work across many parallel invocations:
for file in $(cat files.txt); do
claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
--allowedTools "Edit,Bash(git commit *)"
done
Test on a few files first, then run at scale. The --allowedTools flag restricts what Claude can do during unattended runs.
Run autonomously with auto mode
claude --permission-mode auto -p "fix all lint errors"
7. Avoid Common Failure Patterns
-
The kitchen sink session: You start with one task, then ask something unrelated, then go back. Context fills with irrelevant information.
Fix: /clear between unrelated tasks.
-
Correcting over and over: Claude does something wrong, you correct it, still wrong, correct again. Context is polluted with failed approaches.
Fix: After two failed corrections, /clear and write a better initial prompt.
-
The over-specified CLAUDE.md: Too long means Claude ignores half of it and important rules get lost.
Fix: Ruthlessly prune. If Claude already does something correctly without the instruction, delete it or convert it to a hook.
-
The trust-then-verify gap: A plausible-looking implementation that doesn't handle edge cases.
Fix: Always provide verification (tests, scripts, screenshots). If you can't verify it, don't ship it.
-
The infinite exploration: You ask Claude to "investigate" without scoping it. Claude reads hundreds of files, filling the context.
Fix: Scope investigations narrowly or use subagents.
Develop Your Intuition
The patterns in this guide aren't set in stone. Sometimes you should let context accumulate because you're deep in one complex problem and the history is valuable. Sometimes you should skip planning because the task is exploratory.
Pay attention to what works. When Claude produces great output, notice what you did. When Claude struggles, ask why. Over time, you'll develop intuition that no guide can capture — knowing when to be specific and when to be open-ended, when to plan and when to explore, when to clear context and when to let it accumulate.
Source: Claude Code Official Documentation
