CLAUDE.md best practices
# Add to your Claude Code skills
git clone https://github.com/abhishekray07/claude-md-templatesGuides for using ai agents skills like claude-md-templates.
Last scanned: 5/30/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-05-30T15:27:59.644Z",
"npmAuditRan": true,
"pipAuditRan": true
}No comments yet. Be the first to share your thoughts!
30 days in the Featured rail
Get better output from Claude Code in 5 minutes. No plugins, no MCP servers, no configuration — just markdown files in the right places.
Claude Code reads instructions from three locations. Each has a different scope:
~/.claude/CLAUDE.md -> Global: your personal preferences (every project)
.claude/CLAUDE.md -> Project: shared with your team (committed to git)
./CLAUDE.local.md -> Local: your personal overrides (gitignored)
Global = rules you'd repeat across every project ("always run tests," "prefer simple code"). Project = context your whole team benefits from (stack, structure, commands, conventions). Local = stuff only you need (your terminal, your MCP servers, your editor quirks).
mkdir -p ~/.claude
cp global/CLAUDE.md ~/.claude/CLAUDE.md
Edit it with your personal preferences. Keep it under 15 lines.
mkdir -p .claude
# Pick the template closest to your stack:
cp project/nextjs-typescript.md .claude/CLAUDE.md # Next.js / React / TypeScript
cp project/python-fastapi.md .claude/CLAUDE.md # Python / FastAPI
cp project/generic.md .claude/CLAUDE.md # Anything else
Fill in the blanks. Commit it to git so your team gets the same behavior.
cp local/local.md ./CLAUDE.local.md
echo "CLAUDE.local.md" >> .gitignore
Add your personal setup. This file lives at the project root (not inside .claude/) and is never shared.
mkdir -p .claude/rules
cp rules/code-style.md .claude/rules/code-style.md
cp rules/testing.md .claude/rules/testing.md
# Edit placeholders like [your test command]
Rules are modular instruction files. Path-scoped rules only load when Claude works with matching files. See principles.md for when and why to use rules vs CLAUDE.md.
Your final setup should look like this:
your-project/
├── .claude/
│ ├── CLAUDE.md # Project instructions (committed)
│ └── rules/
│ ├── code-style.md # Always loaded
│ └── testing.md # Loaded when working with test files
├── CLAUDE.local.md # Your personal overrides (gitignored)
└── ...
Claude Code automatically reads these files at the start of every session. All discovered files are concatenated into context — they don't override each other. When instructions conflict, Claude sees the last one it read. Within each directory, CLAUDE.local.md loads after CLAUDE.md, so your personal notes get the final word at that level.
Important: Claude Code's system prompt already contains ~50 instructions. That's a third of the ~150-200 instruction limit frontier models can reliably follow. Your CLAUDE.md must be lean. Every line competes for attention.
Auto memory: Claude also maintains its own notes at ~/.claude/projects/<project>/memory/ — build commands it discovers, patterns from your corrections, debugging insights. These load at session start too. You don't need to put things in CLAUDE.md that Claude will learn on its own. Run /memory to see everything that's loaded. See principles.md for when to use CLAUDE.md vs auto memory.
This is the single most impactful habit you can build:
After every correction you give Claude, end with:
"Update CLAUDE.md so you don't make that mistake again."
Claude is good at writing rules for itself. Over time, your CLAUDE.md becomes a living document that gets smarter with every session.
| Rule | Where it goes | Why |
|------|--------------|-----|
| "Run tests after changes" | Global | You want this everywhere |
| "Use shadcn/ui components" | Project | Team convention |
| "I use Ghostty terminal" | Local | Only you need this |
| "Never use any in TypeScript" | Project | Team standard |
| "Ask before committing" | Global | Personal preference |
| "I have Context7 MCP configured" | Local | Your setup, not theirs |
| "Prices are in src/lib/config" | Project | Domain knowledge |
| "Keep code simple" | Global | Universal preference |
Too long. If your project CLAUDE.md is over 80 lines, Claude starts ignoring parts of it. HumanLayer keeps theirs under 60 lines. That's a good benchmark.
Personality instructions. "Be a senior engineer" or "Think step by step" wastes tokens. Claude Code already has strong system-level instructions.
@-mentioning docs. Writing @docs/api-guide.md embeds the entire file into context every single session. Instead, pitch Claude on when to read it: "For Stripe integration issues, see docs/stripe-guide.md."
Formatting rules without a formatter. If you have a linter/formatter configured, use a hook to run it — don't burn CLAUDE.md lines on what a tool enforces. But if you don't have a formatter, concrete style rules like "Use 2-space indentation" are exactly the kind of specific instruction Anthropic recommends.
Duplicate rules. If your global file says "run tests" and your project file also says "run tests," you've wasted tokens saying the same thing twice.
For larger codebases, you can place CLAUDE.md files in subdirectories:
.claude/CLAUDE.md -> Project root (always loaded)
src/auth/CLAUDE.md -> Auth module (loaded when working in src/auth/)
src/api/CLAUDE.md -> API module (loaded when working in src/api/)
Claude Code loads these on demand — only when working in that directory. This keeps your root file lean while giving Claude deep context where it matters.
Use this when your root CLAUDE.md pushes past 80 lines, or when different parts of the codebase have different conventions.
For rules that only apply to specific parts of your codebase, use .claude/rules/:
.claude/rules/
testing.md -> Only activates for test files
api-design.md -> Only activates for API route handlers
code-style.md -> No path restriction = applies everywhere
Rules use YAML frontmatter with paths globs to scope when they activate. See rules/ in this repo for annotated guides you can adapt to your stack, and principles.md for the full guide on writing effective rules.
CLAUDE.md vs rules: Use CLAUDE.md for project-wide context (stack, commands, structure). Use rules for focused standards that apply to specific file types or directories.
| File | What it is | When to use it |
|------|-----------|---------------|
| global/CLAUDE.md | Personal preferences template | Copy to ~/.claude/CLAUDE.md |
| project/nextjs-typescript.md | Next.js/React/TS project template | Copy to .claude/CLAUDE.md |
| project/python-fastapi.md | Python/FastAPI project template | Copy to .claude/CLAUDE.md |
| project/generic.md | Fill-in-the-blank for any stack | Copy to .claude/CLAUDE.md |
| local/local.md | Personal overrides template | Copy to .claude/local.md |
| rules/testing.md | Testing standards (path-scoped) | Copy to .claude/rules/testing.md, edit placeholders |
| rules/api-design.md | API design standards (path-scoped) | Copy to .claude/rules/api-design.md, adjust paths |
| rules/code-style.md | Universal code style standards | Copy to .claude/rules/code-style.md |
| workflows/self-improvement-rules.md | Structured rules for planning, verification, self-correction | Paste sections into your CLAUDE.md |
| workflows/prompting-patterns.md | 11 copy-paste prompts from the Claude Code team | Use directly in your sessions |
| cheatsheet.md | One-page reference card | Bookmark or print |
| principles.md | The full research — why these patterns work | Read when you want to go deeper |
principles.md contains everything we know about writing effective CLAUDE.md files:
.claude/rules/ — path-scoped modular rules with YAML frontmatterIMPORTANT, YOU MUST)@import syntaxIf you only read one file in this kit besides the templates, read that one.
This starter kit is based on: