This guide compiles Claude Code best practices from two sources: Anthropic’s official documentation and patterns that actually work in production, based on analysis of hundreds of CLAUDE.md files across open-source projects.
If you searched for “Claude Code best practices,” you probably want actionable rules, not theory. That is what this guide delivers.
The Three Layers of Claude Code Configuration
Claude Code’s behavior is controlled at three levels, and understanding this hierarchy is the first best practice:
- CLAUDE.md files — Persistent instructions loaded every session
- Skills (Custom Slash Commands) — Reusable task templates (
.claude/skills/) - Hooks — Shell commands triggered by Claude Code events
Most developers only use the first layer. The best setups use all three.
CLAUDE.md Best Practices
Keep It Under 500 Lines
We analyzed CLAUDE.md files from 165+ repositories. The most effective ones share a pattern: they are concise. Files under 500 lines get fully read and consistently followed. Files over 1,000 lines lead to Claude ignoring or deprioritizing later sections.
If your CLAUDE.md is growing too long, split it. Put project-level rules in the root CLAUDE.md, and put directory-specific rules in subdirectory CLAUDE.md files. Claude Code reads all of them and merges the context.
Structure With Headers, Not Paragraphs
Claude Code parses CLAUDE.md as Markdown. Headers create semantic boundaries that help Claude prioritize information. Compare:
Bad:
We use TypeScript with strict mode. Tests go in __tests__ directories.
Use vitest for testing. Always mock external APIs. Run npm test before
committing. Format with prettier. Use single quotes.Good:
## Code Style
- TypeScript strict mode
- Single quotes, no semicolons
- Format with Prettier
## Testing
- Framework: vitest
- Location: `__tests__/` directories
- Always mock external APIs
- Run `npm test` before committingThe second version is not just more readable for humans. Claude Code processes it more reliably because each section has a clear scope.
Put the Most Important Rules First
Claude Code reads CLAUDE.md top to bottom. If your context window gets compressed (long sessions), later sections may get summarized. Put your non-negotiable rules at the top:
- Build/test commands — What Claude needs to run to validate its work
- Critical constraints — Things that must never happen (e.g., “never delete migration files”)
- Architecture decisions — Patterns Claude should follow
- Style preferences — Formatting, naming conventions
- Nice-to-haves — Optional guidelines
Use Negative Rules Sparingly but Precisely
Telling Claude what NOT to do is sometimes more effective than telling it what to do:
## Do Not
- Do not add comments explaining obvious code
- Do not create abstraction layers for single-use functions
- Do not use `any` type in TypeScript
- Do not add error handling for impossible statesThe key is precision. “Don’t write bad code” is useless. “Don’t use any type” is enforceable.
Include Runnable Commands
The single most impactful thing you can put in CLAUDE.md is your project’s build and test commands:
## Commands
- Build: `npm run build`
- Test all: `npm test`
- Test single: `npm test -- --grep "test name"`
- Lint: `npm run lint`
- Type check: `npx tsc --noEmit`Without these, Claude guesses. With them, Claude can validate its own work before presenting it to you.
Skills Best Practices
Skills are custom slash commands stored in .claude/skills/. They turn complex, multi-step workflows into one-line commands.
When to Create a Skill
Create a skill when you find yourself giving Claude the same multi-step instruction more than twice. Common candidates:
/review— Run a specific code review checklist/deploy— Execute your deployment pipeline/refactor— Apply your team’s refactoring patterns/test— Generate tests following your conventions/handover— Summarize session context for the next developer
Skill Structure That Works
A good skill file has three parts:
# /skill-name
Brief description of what this skill does.
## Steps
1. First, do X
2. Then check Y
3. Finally, output Z
## Rules
- Always validate before executing
- Use [specific format] for output
- Never skip step 2Keep Skills Focused
One skill should do one thing. If your skill file is over 100 lines, it is probably trying to do too much. Split it into smaller skills that can be composed.
Hooks Best Practices
Hooks run shell commands in response to Claude Code events. They are configured in .claude/settings.json:
{
"hooks": {
"on_tool_use:write": "npm run lint --fix $FILE",
"on_tool_use:bash": "echo 'Command: $COMMAND'"
}
}Use Hooks for Automated Quality Gates
The best use of hooks is automated validation:
- After file writes: Run linter/formatter automatically
- Before commits: Run tests
- After bash commands: Log what Claude executed
Do Not Use Hooks for Complex Logic
Hooks should be fast, simple shell commands. If your hook needs conditional logic or takes more than a few seconds, it belongs in a skill instead.
Memory and Context Best Practices
Use the Memory System for Cross-Session Knowledge
Claude Code’s memory system (.claude/memory/) persists information across sessions. Use it for:
- User preferences that apply to all projects
- Feedback patterns (corrections Claude should remember)
- Project knowledge that changes over time
Do NOT use memory for things derivable from code (architecture, file paths, conventions). Those belong in CLAUDE.md.
Compact Proactively in Long Sessions
Long sessions degrade performance as context fills up. Use /compact proactively:
- After completing a major task
- Before starting a different type of work
- When Claude starts repeating itself or forgetting earlier context
Workflow Best Practices
Let Claude Read Before It Writes
The most common source of bad Claude Code output is writing code without reading existing code first. Enforce this in your CLAUDE.md:
## Workflow
- Read existing code before modifying it
- Understand the current implementation before suggesting changes
- Do not propose changes to files you haven't readUse Plan Mode for Complex Changes
For changes that touch more than 3 files, use plan mode (/plan) to align on approach before Claude starts coding. This prevents wasted work on the wrong approach.
One Task at a Time
Give Claude one clear task. “Refactor the auth module AND add rate limiting AND update the tests” leads to worse results than three separate, focused requests.
Anti-Patterns to Avoid
Over-Engineering CLAUDE.md
Your CLAUDE.md is not a novel. It does not need an introduction, a philosophy section, or motivational quotes. Every line should be an actionable instruction.
Duplicating Documentation
If your project has a CONTRIBUTING.md or style guide, do not copy it into CLAUDE.md. Reference it:
## Style Guide
Follow the conventions in CONTRIBUTING.md. Key points:
- [list only the 3-5 most critical rules here]Ignoring the Feedback Loop
The best CLAUDE.md files evolve. When you correct Claude during a session, add that correction to CLAUDE.md so you never have to make it again. This is the compound interest of AI-assisted development.