4. Add rules for your codebase (~2 min, optional)

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)
└── ...

How It Works

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.

The Self-Improvement Loop

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.

What Goes Where (Decision Guide)

| 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 |

Common Mistakes

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.

Scaling Up: Module-Specific Files

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.

Scaling Up: Rules

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.

Included Files

| 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 |

The Principles (Go Deeper)

principles.md contains everything we know about writing effective CLAUDE.md files:

• The attention budget (why less is more)
• Advisory vs deterministic: CLAUDE.md vs hooks
• Anthropic's official include/exclude table
• .claude/rules/ — path-scoped modular rules with YAML frontmatter
• Writing rules Claude actually follows (with bad/good examples)
• Emphasis keywords that actually work (IMPORTANT, YOU MUST)
• Module-specific CLAUDE.md files for scaling
• Progressive disclosure patterns and @import syntax
• Architecture diagrams (HumanLayer's pattern)
• The "Don't X, Do Y" rule
• Troubleshooting: "Claude isn't following my rules" diagnostic checklist
• Matt Pocock's plan loop
• Real-world benchmarks from HumanLayer, Boris Cherny, Cloudflare, ChrisWiles
• Skill activation mapping
• TODO priority systems
• Every anti-pattern and what to do instead

If you only read one file in this kit besides the templates, read that one.

Sources

This starter kit is based on:

• Anthropic — "Claude Code Best Practices" — Official guidance, include/exclude table, rules
• Anthropic — "Effective Context Engineering" — Context rot, attention budget, just-in-time context
• Anthropic — "Memory and Project Configuration" — CLAUDE.md hierarchy, rules, auto memory
• Anthropic — "Hooks Guide" — Deterministic lifecycle hooks
• Boris Cherny's team tips — 10 tips from the Claude Code team (Jan 31, 2026)
• Boris Cherny's personal setup — How the creator uses Claude Code (Jan 2, 2026)
• HumanLayer — "Writing a Good CLAUDE.md" — Instruction limits, progressive disclosure, leverage dia