Claude Code Best Practices
Based on the official Anthropic documentation at
https://code.claude.com/docs/en/best-practices.
The single most important constraint: Claude's context window fills up fast,
and performance degrades as it fills. Every best practice flows from this.
Instructions
Step 1: Always give Claude a way to verify its work
Provide a runnable check (test suite, build exit code, linter, diff script) so Claude can confirm success independently. Ask for evidence (test output, command result), not just assertions.
Step 2: Use the Explore → Plan → Implement workflow for non-trivial tasks
Enter
mode, let Claude read the codebase first, then draft a plan before writing any code. Exit plan mode to implement. Skip this only for small, obvious changes.
Step 3: Write specific, scoped prompts
Name files (
), describe symptoms rather than guesses, reference existing patterns. Vague prompts produce vague results.
Step 4: Keep CLAUDE.md short and actionable
Include only what Claude cannot infer from the code. Every line should answer: "Would removing this cause Claude to make mistakes?" If not — cut it.
Step 5: Manage context aggressively
Use
between unrelated tasks. After two failed corrections on the same issue: clear and write a better prompt. Use
to compact with focus.
Step 6: Use subagents for investigation and review
Let subagents explore unfamiliar code or review your implementation — they run in a fresh context without bias toward the code they just wrote.
Examples
Example 1: Implementing a feature correctly
User says: "I keep getting flaky results when I ask Claude to implement something"
Actions:
- Add a verification step to the prompt: "write a validateEmail function — run the existing test suite after implementing, show me the output"
- If no tests exist: "write the function AND write tests for it, run them, show results"
- Set a Stop hook to block turn completion until tests pass
Result: Claude iterates until tests pass instead of stopping when the code looks done.
Example 2: Tackling a complex, multi-file change
User says: "How should I approach a big refactor across 10 files?"
Actions:
- Enter mode — Claude explores without making changes
- Ask: "read the affected files and write a step-by-step implementation plan"
- Edit the plan directly with if needed
- Exit plan mode — Claude implements and commits per the plan
- Run a subagent to review the diff in a fresh context
Result: Structured refactor with a reviewable plan, no context-thrashing from mixed explore/write turns.
Example 3: Claude keeps repeating the same mistake
User says: "I've corrected Claude 3 times on the same issue and it keeps doing it wrong"
Actions:
- Run — start a fresh context
- Identify what was missing from the original prompt (missing constraint, missing example, ambiguous scope)
- Write a new initial prompt that includes the constraint explicitly: "IMPORTANT: do not use mocks in these tests — use real database connections"
- Add the constraint to CLAUDE.md if it applies project-wide
Result: Clean session with a better-specified prompt outperforms a long session with accumulated corrections.
1. Give Claude a way to verify its work
Claude stops when the work looks done. Without a runnable check, you become
the verification loop. Provide something that returns a pass/fail signal Claude
can read: a test suite, a build exit code, a linter, a script that diffs output.
- Ask Claude to run the check and iterate in the same prompt.
- Set conditions for multi-turn verification.
- Use a Stop hook to block the turn from ending until a script passes.
- Use a verification subagent so the reviewer has a fresh context.
Ask Claude to show evidence (test output, command result, screenshot) rather
than just asserting success.
Example upgrade:
Before: "implement a function that validates email addresses"
After: *"write a validateEmail function. test cases: user@example.com → true,
invalid → false. run the tests after implementing"*
2. Explore first, then plan, then code
Use
plan mode (
or the UI toggle) to separate reading from writing.
- Explore — enter plan mode; Claude reads files without making changes.
- Plan — ask Claude to write a detailed implementation plan. Press
to open the plan in your editor for direct edits.
- Implement — exit plan mode; Claude codes and verifies against the plan.
- Commit — ask Claude to commit and open a PR.
Skip planning when the scope is clear and the fix is small (typo, rename,
single-line change). Plan mode adds overhead — use it when the change touches
multiple files or you are unfamiliar with the code.
3. Provide specific context in your prompts
Claude can infer intent but cannot read your mind.
| Strategy | Vague | Specific |
|---|
| 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 a weird API?" | "look through ExecutionFactory's git history and summarize how its API evolved" |
| Reference patterns | "add a calendar widget" | "look at HotDogWidget.php as a pattern reference and follow it to implement a calendar widget" |
| Describe the symptom | "fix the login bug" | "users report login fails after session timeout. check src/auth/ token refresh. write a failing test, then fix it." |
Rich context techniques:
- Use to reference files directly.
- Paste screenshots or drag images into the prompt.
- Pipe data:
- Give URLs for documentation (allowlist domains via ).
4. Write an effective CLAUDE.md
CLAUDE.md is read at the start of every session. Keep it short and
human-readable — bloated CLAUDE.md files cause Claude to ignore actual
instructions.
Include:
- Bash commands Claude cannot guess (e.g., build/test commands)
- Code style rules that differ from language defaults
- Testing instructions and preferred test runners
- Repository etiquette (branch naming, PR conventions)
- Architectural decisions specific to the project
- Developer environment quirks, required env vars
- Common gotchas or non-obvious behaviors
Exclude:
- Anything Claude can figure out by reading the code
- Standard language conventions Claude already knows
- Detailed API documentation (link instead)
- Self-evident practices like "write clean code"
For each line: "Would removing this cause Claude to make mistakes?" If not, cut it.
Use
to confirm Claude loaded the file. Use
imports
in CLAUDE.md to pull in other files selectively.
5. Manage session context aggressively
- — reset context between unrelated tasks.
- — compact with focus (e.g.,
/compact Focus on API changes
- / — open the rewind menu; restore conversation and/or
code state to any previous checkpoint.
- — ask a quick side-question; answer appears in an overlay and never
enters conversation history.
After two failed corrections on the same issue: run
and write a
better initial prompt incorporating what you learned. A clean session with a
better prompt outperforms a long session with accumulated corrections.
Customize compaction in CLAUDE.md:
*"When compacting, always preserve the full list of modified files and any
test commands"*
6. Use subagents for investigation and review
Subagents run in their own context window and report back summaries, keeping
your main conversation clean.
Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.
After implementation:
use a subagent to review this code for edge cases
Use
skill for a bug-focused adversarial review of the current diff.
7. Automate and scale
Non-interactive mode — integrate Claude into CI, pre-commit hooks, scripts:
bash
claude -p "List all API endpoints" --output-format json
claude -p "Analyze this log file" --output-format stream-json --verbose
Fan out across files — loop through tasks:
bash
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
Parallel sessions — run multiple Claude sessions with git worktrees so
edits don't collide. Writer/Reviewer pattern:
- Session A implements a feature.
- Session B reviews the diff in a fresh context (no bias toward the code it
just wrote).
Auto mode — uninterrupted execution with background safety checks:
bash
claude --permission-mode auto -p "fix all lint errors"
8. Common failure patterns and quick reference
For the full failure patterns table, all CLI commands, and non-interactive mode examples, consult
.