The single fastest improvement to your Claude Code workflow: a well-structured CLAUDE.md. Most developers write one, get it half-right, and leave a significant amount of output quality on the table.
This guide gets specific. You will find:
- A copy-paste CLAUDE.md starter template with the sections that actually matter
- The rule that most developers miss: CLAUDE.md under 200 lines, or adherence quietly drops
- How hooks and skills work — and when to use each instead of CLAUDE.md
- The anti-patterns that waste context and degrade output quality
- Real examples from the 165+ CLAUDE.md files in the rules gallery
Claude Code’s behavior is controlled at three levels:
- 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. Here is how to set up each one correctly.
The CLAUDE.md Starter Template
Copy this, fill in your project’s values, and you have a working CLAUDE.md in under 5 minutes:
# [Project Name]
## 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`
## Architecture
[2-3 sentences on how the project is structured. Key directories. Entry points.]
## Code Style
- [Language and strict mode settings]
- [Formatting tool and config]
- [Naming conventions if non-obvious]
## Testing
- Framework: [vitest/jest/pytest/etc]
- Test location: `__tests__/` directories
- Always mock external APIs
- Run `npm test` before reporting completion
## Do Not
- Do not add comments explaining obvious code
- Do not create abstraction layers for single-use functions
- [Add your project-specific hard constraints here]
## Workflow
- Read existing code before modifying it
- Run tests after any change
- Do not propose changes to files you have not readThat is the minimum viable CLAUDE.md. Everything else in this guide is about making it more effective.
CLAUDE.md Best Practices
Keep It Under 200 Lines (Not 500 — That Number Is Wrong)
We analyzed CLAUDE.md files from 165+ repositories. The commonly cited “keep it under 500 lines” advice is too generous. The most effective files are under 200 lines.
Why the lower ceiling: Claude Code’s system prompt already consumes roughly 50 instruction slots. Frontier models reliably follow about 150-200 instructions total. Beyond that, adherence quietly drops — not all at once, but gradually, starting with the rules nearest the bottom of the file.
The practical implication: every line in CLAUDE.md is competing with every other line for Claude’s consistent attention. Write only what you would actually notice Claude violating.
If your CLAUDE.md is growing past 200 lines, 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 — but the root file should be the leanest.
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: When CLAUDE.md Instructions Are Not Enough
Skills are custom slash commands stored in .claude/skills/. They turn complex, multi-step workflows into one-line commands. The difference from CLAUDE.md: CLAUDE.md loads every session and shapes general behavior. Skills load on demand and handle specific, repeatable tasks.
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: Guaranteed Execution, Not Advisory Instructions
Hooks run shell commands in response to Claude Code events. They are configured in .claude/settings.json. The key distinction from CLAUDE.md: instructions are advisory — Claude follows them unless context pressure or prompt wording pushes against them. Hooks are deterministic — they run regardless of what Claude decides.
{
"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: What Belongs in .claude/memory/ vs CLAUDE.md
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 Patterns That Produce Consistently Better Output
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.
Close the Loop on Visual Output
Claude Code’s review workflow catches logic errors and style violations, but it cannot verify how the rendered UI actually looks in a browser. If your team reviews Claude Code output on staging or preview environments, BugHerd is worth adding to the workflow — it lets reviewers pin bug reports directly onto the staging page, attached to the exact element, with browser context captured automatically. The feedback arrives structured and actionable rather than as a vague Slack message, which means Claude Code’s next session starts with a clear reproduction rather than “the button looks wrong.”
Anti-Patterns That Silently Degrade Output Quality
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.
The Fastest Way to Improve Your Setup Right Now
If you only do one thing after reading this: run /init in your project root. Claude Code generates a starter CLAUDE.md based on your actual codebase — it reads your package.json, identifies your test framework, finds your build commands. That gives you a real starting point to edit rather than a blank file to fill from scratch.
Then check: is your CLAUDE.md over 200 lines? If yes, that is your first fix.