The 7 Best Practices That Actually Move the Needle
According to Anthropic's official Claude Code docs, most best practices are downstream of one constraint: context. These seven habits give you the highest leverage per minute spent learning them.
Give Claude a way to verify
Tests, screenshots, lint commands. Anthropic calls this the highest-leverage practice.
Plan before you code
Plan Mode for non-trivial work. Catches wrong assumptions before the diff lands.
Be specific in prompts
Reference files with @, point to patterns, describe symptoms not fixes.
Keep CLAUDE.md under 200 lines
Bloat causes Claude to ignore actual rules. Ruthlessly prune.
Manage context aggressively
/clear between tasks. /compact mid-session. /rewind for failed branches.
Delegate to subagents
Investigation in subagents stays out of your main context.
Run parallel sessions in worktrees
Each task gets its own working directory. Writer plus Reviewer pattern beats a single long session.
1. Give Claude a Way to Verify Its Work
This is the single highest-leverage practice. Anthropic's official docs say so verbatim. Without verification, Claude produces code that looks right but quietly fails on edge cases, and you become the only feedback loop.
Verification can be tests, a linter, a screenshot diff, or a one-line Bash check. The form does not matter. What matters is that Claude can run it and decide if it succeeded.
Vague success criteria
"implement a function that validates email addresses"
Verifiable outcome
"write validateEmail. test cases: user@example.com -> true, invalid -> false, user@.com -> false. run the tests after implementing."
For UI work, the Claude in Chrome extension lets Claude open tabs, take screenshots, and iterate until the code matches the design. For backend work, point Claude at your test command and your lint command, then ask it to keep working until both pass.
2. Explore First, Then Plan, Then Code
Letting Claude jump straight to coding produces code that solves the wrong problem. The recommended Anthropic workflow has four phases: explore, plan, implement, commit. Plan Mode separates research from execution.
Step 1: Explore (Plan Mode)
Claude reads files and answers questions without making changes. Build a shared mental model.
Step 2: Plan (Plan Mode)
Ask for a detailed implementation plan with files to change and tradeoffs. Press Ctrl+G to edit it in your editor.
Step 3: Implement (Normal Mode)
Claude codes against the plan and verifies against your test command.
Step 4: Commit
Descriptive commit message, PR opened. Move on with /clear.
Skip Plan Mode for tasks where the diff fits in one sentence: a typo, a renamed variable, a single log line. Planning is overhead. Use it when you are uncertain about the approach, when changes touch multiple files, or when you are unfamiliar with the code.
3. Provide Specific Context in Every Prompt
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.
| Strategy | Vague | Specific |
|---|---|---|
| Scope the task | add tests for foo.py | write a test for foo.py covering the logged-out edge case. avoid mocks. |
| Point to sources | why does the API look like this? | look through ExecutionFactory git history and summarize how the api evolved |
| Reference patterns | add a calendar widget | follow the pattern in HotDogWidget.php to build a calendar widget |
| Describe symptoms | fix the login bug | login fails after session timeout. check src/auth/ token refresh. write a failing test, then fix. |
- ●Reference files with @. Type @src/auth/login.ts and Claude reads the file before responding.
- ●Paste images directly. Drag screenshots into the prompt for UI work or error messages.
- ●Pipe in data. cat error.log | claude sends file contents straight into context.
- ●Allowlist URLs. Use /permissions to allow frequently-fetched docs domains.
The complete playbook
Get every workflow, every config, and the reasoning behind each decision in the full KaiShips Guide to Claude Code.
This post covers the high-leverage best practices. The guide adds chapters on memory architecture, skills, hooks, MCP servers, subagents, cron automation, and a production CLAUDE.md template.
Get the KaiShips Guide to Claude Code -- $294. Write a Concise CLAUDE.md
CLAUDE.md is loaded into every conversation. Every line costs tokens on every request, and bloated files cause Claude to ignore actual instructions because the important rules get buried. Keep it under 200 lines and review it like code.
For each line, ask: would removing this cause Claude to make mistakes? If not, cut it.
| Include | Exclude |
|---|---|
| Bash commands Claude cannot guess | Anything Claude can figure out by reading code |
| Code style rules that differ from defaults | Standard language conventions Claude already knows |
| Test commands and preferred runners | Detailed API docs (link to docs instead) |
| Repository etiquette and PR conventions | Information that changes frequently |
| Required env vars and dev quirks | File-by-file descriptions of the codebase |
| Common gotchas and non-obvious behaviors | "Write clean code" and similar self-evident advice |
Minimal CLAUDE.md template
# Code style
- ES modules (import/export), not CommonJS
- Destructure imports when possible
# Workflow
- Typecheck after a series of changes: npm run typecheck
- Prefer single tests, not full suite, for speed: npx vitest <file>
# Repo etiquette
- Branch names: feat/<slug>, fix/<slug>
- Never commit to main directlyRun /init to generate a starter CLAUDE.md based on your project structure, then prune. Use the @path/to/file import syntax to reference longer docs without inlining them.
5. Manage Context Aggressively
Claude's context window holds your entire conversation, including every message, every file Claude reads, and every command output. Performance degrades as context fills. Treating context as a precious resource is the difference between consistent quality and Claude "forgetting" instructions mid-session.
/clear between unrelated tasks
Resets context entirely. Run it whenever the next task has nothing in common with the last one.
/compact mid-session
Summarizes conversation while preserving code and key decisions. Pass instructions like /compact Focus on the API changes for control.
Esc + Esc or /rewind
Rolls back conversation, code, or both to a prior checkpoint. Use it after a failed approach instead of trying to course-correct in place.
/btw for side questions
Answers in a dismissible overlay that never enters conversation history. Perfect for quick lookups.
The two-correction rule: if you have corrected Claude more than twice on the same issue, the context is polluted with failed approaches. Run /clear and start fresh with a more specific prompt that incorporates what you learned. A clean session with a better prompt almost always beats a long session with accumulated corrections.
6. Delegate Investigation to Subagents
Subagents run in their own context window and report back a summary. The dozens of files they read never enter your main conversation. Anthropic's docs call them "one of the most powerful tools available" because context is the fundamental constraint.
Three high-leverage subagent uses
Codebase investigation
"use subagents to investigate how our auth handles token refresh and whether OAuth utilities exist"
Code review
"use a subagent to review this code for edge cases"
Specialized custom subagents
Drop a definition in .claude/agents/ with its own allowed tools and model. A security-reviewer agent that only gets Read, Grep, Glob, and Bash will not write code, just report.
Custom subagent definition
---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review for:
- Injection vulnerabilities (SQL, XSS, command)
- Authn / authz flaws
- Secrets in code
- Insecure data handling
Provide line references and suggested fixes.7. Use Hooks for Anything That Must Always Happen
CLAUDE.md instructions are advisory -- Claude usually follows them, but may not. Hooks are deterministic. The harness runs them every time, regardless of what Claude decides. Use hooks for actions that must happen with zero exceptions.
Auto-format on edit
Run prettier or eslint --fix after any Edit or Write.
Block protected paths
Reject Edit calls that target migrations/, prod configs, or .env.
Notify on session end
Ping Slack or Discord when Claude finishes a long unattended task.
Inject extra context
Auto-attach the current branch, last commit, or open PRs to every prompt.
Tell Claude to write the hook for you: "write a hook that runs eslint after every file edit." Then run /hooks to browse what is configured.
8. Pick the Right Tool: Skills vs CLAUDE.md vs Hooks vs MCP
Claude Code gives you four extension surfaces and they all look superficially similar. The choice matters because CLAUDE.md content is loaded every session while skills and MCP load on demand. Picking wrong wastes tokens or hides capabilities.
| Surface | When to use | Loads |
|---|---|---|
| CLAUDE.md | Rules that apply broadly to every conversation in this repo | Every session |
| Skills | Domain knowledge or workflows that only matter sometimes | On demand |
| Hooks | Deterministic actions that must always run | On tool events |
| MCP servers | External tool access (databases, Notion, Figma, your APIs) | On demand |
| Subagents | Isolated investigation or specialized review with its own context | On demand |
The fastest way to bloat CLAUDE.md is to dump workflow-specific instructions into it. Move those into skills under .claude/skills/ and Claude loads them only when relevant.
9. Run Parallel Sessions in Worktrees
Once you are effective with one Claude, multiply output by running several. Git worktrees give each session its own working directory so changes do not collide. The Claude Code desktop app handles this natively, and Claude Code on the web runs each session in an isolated VM.
Three patterns that scale
Writer + Reviewer
Session A implements. Session B reviews with a fresh context, so it is not biased toward the code it just wrote. Feed B's feedback back to A.
Test-first split
Session A writes failing tests. Session B writes the code to make them pass. Neither session sees the other's reasoning.
Fan-out across files
For migrations: list every file, then loop with claude -p on each one. Test the prompt on 3 files, then run on 2,000.
Fan-out script template
for file in $(cat files.txt); do
claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
--allowedTools "Edit,Bash(git commit *)"
doneThe --allowedTools flag restricts what Claude can do during unattended runs. Combined with auto mode, this lets you run dozens of instances safely.
10. Five Common Failure Patterns to Avoid
Every Claude Code regression I have shipped traces back to one of these. Learn to recognize them and the fix is fast.
The kitchen sink session
One task, then an unrelated question, then back to the first. Context full of noise. Fix: /clear between unrelated tasks.
Correcting over and over
Three rounds of corrections on the same issue. Context polluted with failed approaches. Fix: After two failed corrections, /clear and write a better initial prompt.
The over-specified CLAUDE.md
500 lines, including six rules Claude already follows by default. Real rules get lost. Fix: Ruthlessly prune. If Claude follows it without the rule, delete the rule.
The trust-then-verify gap
Plausible code that fails on edge cases. Fix: Always provide verification. If you cannot verify it, do not ship it.
The infinite exploration
"Investigate this" with no scope. Claude reads hundreds of files, context melts. Fix: Scope investigations narrowly or push them into a subagent.
11. Course-Correct Early and Often
The best results come from tight feedback loops. Claude occasionally solves problems perfectly first try, but correcting it quickly almost always produces better solutions faster than letting it burn through a wrong approach.
Esc: stop mid-action
Halts whatever Claude is doing without losing context. Redirect with a follow-up message.
Esc + Esc: rewind menu
Restore conversation, code, or both to a checkpoint. Try something risky -- if it fails, rewind.
"Undo that"
Plain English revert. Faster than reaching for git when you just want the last change gone.
12. The One-Page Best Practices Cheatsheet
Print this. Tape it to your monitor. The shortcuts compound as habits.
| Situation | Action |
|---|---|
| Starting a non-trivial change | Plan Mode -> plan -> implement |
| Switching tasks | /clear |
| Mid-session context bloat | /compact <instructions> |
| Two failed corrections | /clear + better prompt |
| Researching a codebase | use a subagent to investigate X |
| After a risky change | Esc + Esc -> restore |
| Long unattended task | claude --permission-mode auto -p "..." |
| Reusable workflow | .claude/skills/<name>/SKILL.md |
| Must-always-happen action | .claude/settings.json hooks |
| Resuming yesterday's work | claude --resume |
The Fix-Once Rule: Have Claude Teach Itself
When Claude makes the same mistake twice, do not just correct it again. Have Claude write a rule that prevents the mistake -- then drop the rule into CLAUDE.md, a hook, or a skill. Over time, Claude teaches itself to be better at your specific project.
Sample prompt: "You just forgot to add the new route to routes.ts and the build broke. Write a CLAUDE.md rule or a hook that would prevent this from happening again. Pick the right surface: hook if it must always run, rule if it is advisory."
This pattern transforms one-off mistakes into permanent improvements. Each correction makes the next session smoother. After a few weeks of doing this, your CLAUDE.md and hooks form a moat of project-specific knowledge that no off-the-shelf agent can match.
FAQ
What is the most important Claude Code best practice?
Give Claude a way to verify its own work. Anthropic's official documentation calls this 'the single highest-leverage thing you can do.' Provide tests, screenshots, expected outputs, or a Bash command Claude can run to check itself. Without verification, Claude produces code that looks right but quietly fails on edge cases, and you become the only feedback loop.
How long should a CLAUDE.md file be?
Keep CLAUDE.md under 200 lines. The file is loaded into every conversation, so each line costs tokens on every request. Bloated CLAUDE.md files cause Claude to ignore actual instructions because important rules get buried. Include only what Claude cannot infer from the code itself: bash commands, code style rules that differ from defaults, repository etiquette, and developer environment quirks.
When should I use Plan Mode in Claude Code?
Use Plan Mode when you are uncertain about the approach, when the change touches multiple files, or when you are unfamiliar with the code being modified. Skip Plan Mode for tasks where the diff fits in one sentence (a typo fix, a renamed variable, a single log line). Plan Mode adds overhead, but for non-trivial work it forces end-to-end thinking and catches wrong assumptions before any code is written.
How often should I run /clear in Claude Code?
Run /clear between every unrelated task. The context window holds your entire conversation, including every file Claude reads and every command output, and Claude's performance degrades as context fills. If you have corrected Claude more than twice on the same issue, the context is polluted with failed approaches -- run /clear and start fresh with a more specific prompt.
Should I use subagents or load files into the main context?
Use subagents for any investigation that reads more than three files. Subagents run in their own context window and report back a summary, so the dozens of files they read never enter your main conversation. The official Anthropic best practices doc calls subagents 'one of the most powerful tools available' precisely because context is the fundamental constraint in Claude Code.
What is the difference between hooks and CLAUDE.md instructions?
CLAUDE.md instructions are advisory -- Claude usually follows them but may not. Hooks are deterministic -- the harness runs them every time, regardless of what Claude decides. Use CLAUDE.md for guidance and conventions. Use hooks for actions that must happen with zero exceptions, like running a linter after every edit, blocking writes to a protected folder, or formatting code on save.
How do I run multiple Claude Code sessions in parallel?
Use git worktrees to give each session its own isolated working directory, then launch Claude Code in each one. Anthropic recommends this for parallel features, Writer/Reviewer patterns, and large migrations. The Claude Code desktop app and Claude Code on the web both manage multiple sessions natively, with each getting its own worktree so changes do not collide.
Keep Going
Each of the practices above has its own deep dive. Here is where to land next based on what you want to improve.
CLAUDE.md Setup Guide
Production-tested CLAUDE.md template and pruning workflow.
Claude Code Hooks Guide
Every hook event, real configs, and what breaks if you skip them.
Subagents Tutorial
Custom agents in .claude/agents/ for review, research, and specialization.
Worktrees Guide
Parallel sessions with isolated working directories step by step.
Skills Tutorial
When to use a skill instead of CLAUDE.md, with full examples.
Best Configuration
settings.json, env vars, model routing, and a statusline that earns its keep.
The complete playbook
Get every workflow, every config, and the reasoning behind each decision in the full KaiShips Guide to Claude Code.
This post covers the high-leverage best practices. The guide adds chapters on memory architecture, skills, hooks, MCP servers, subagents, cron automation, and a production CLAUDE.md template.
Get the KaiShips Guide to Claude Code -- $29