Why CLAUDE.md matters
Claude Code auto-loads CLAUDE.md from your working directory and every directory above it at the start of every session. Files in subdirectories load on demand, once Claude works with files there. Write it well once and the same guidance applies to every session — no repeating yourself.
A good CLAUDE.md immediately improves answer quality and reduces wrong assumptions and repeated mistakes.
Four locations
The docs list four CLAUDE.md locations, in load order from broadest scope to most specific:
| Location | Scope |
|---|---|
Managed policy (macOS /Library/Application Support/ClaudeCode/CLAUDE.md, Linux /etc/claude-code/CLAUDE.md) | Organization-wide, managed by IT/DevOps |
~/.claude/CLAUDE.md | User instructions (all projects) |
./CLAUDE.md or ./.claude/CLAUDE.md | Project instructions, shared with your team via source control |
./CLAUDE.local.md | Personal project-specific preferences (add to .gitignore) |
These files don’t override each other. All discovered files are concatenated into context, so a project instruction simply appears after a user instruction. If two instructions contradict each other, Claude may pick one arbitrarily — keep your files free of conflicts.
For larger projects, organize instructions into topic-specific files under .claude/rules/. A rule with paths frontmatter only loads when Claude works with matching files. Personal rules in ~/.claude/rules/ apply to every project on your machine.
Bootstrap a draft
/init
Claude analyzes your codebase and creates a file with build commands, test instructions, and project conventions it discovers. If a CLAUDE.md already exists, /init suggests improvements rather than overwriting it. Refine from there with instructions Claude wouldn’t discover on its own.
For an interactive multi-phase flow, set CLAUDE_CODE_NEW_INIT=1 before running /init. It then asks which artifacts to set up: CLAUDE.md files, skills, and hooks.
Five principles
1. Short and structured
It’s loaded into every session, and longer files consume more context and reduce adherence. Target under 200 lines per CLAUDE.md file. @path/to/import imports help you organize a long file but don’t reduce its context cost, because imported files load together with the CLAUDE.md that imports them.
2. “How to handle it” beats “what’s there”
Skip the full directory tree — describe what each key directory is for and the commands you actually run. Claude can explore files itself.
3. State only the don’ts that matter
Spell out the rules where breaking them is hard to undo or project-specific.
## Rules
* Never commit or push without explicit user instruction
* Don't add error handling for impossible scenarios
* Don't introduce new dependencies without approval
Don’t let that list grow, though. Anthropic reports that with Claude 5 generation models, rigid rules conflict with what the user actually asks for and cost you more than they help. Drop taste-level rules like “never write comments” and keep the ones that cause real problems when violated — see Context engineering for Claude 5.
4. Put commands in code blocks
Build/dev/test commands should be in code blocks so Claude copies and runs them exactly.
## Commands
\```bash
npm run build # production build
npm run dev # dev server (port 3030)
npm test # unit tests
\```
5. Document recurring workflows
Tasks like adding content, running migrations, or shipping a release belong here as procedures.
Solid structure example
# Project Name
## Overview
One paragraph on what the project does.
## Stack
* Frontend: Next.js 15, Tailwind CSS
* Backend: Node.js, Prisma, PostgreSQL
* Hosting: Cloudflare Pages
## Commands
\```bash
npm run dev
npm run build
npm test
\```
## Layout
* src/app — Next.js App Router pages
* src/components — UI components
* prisma/ — DB schema and migrations
## Conventions
* Function components only
* State via Zustand
* Tests with Vitest
## Rules
* Commit/push only on explicit instruction
* Confirm before adding new dependencies
Common mistakes
- ❌ Pasting the full directory tree — Claude can explore
- ❌ Mixing languages — pick one and stay consistent
- ❌ Feature descriptions (those belong in the README)
- ❌ Generic best practices (“write readable code”) — keep it project-specific
- ❌ Long lists of taste-level don’ts — they conflict with the model’s judgment
- ❌ Repeating instructions that already live in the system prompt or a skill — they drift apart
Move detailed rules into Skills and rules
When CLAUDE.md grows, extract multi-step workflows (content authoring, migration procedures) into separate Skill files. Leave a short pointer in CLAUDE.md saying “for X, invoke skill Y.” Instructions that matter for only part of the codebase belong in a path-scoped rule under .claude/rules/, which loads only when Claude works with matching files.
Check what loaded and audit for stale instructions
- Run
/contextand check the list under Memory files to see which CLAUDE.md and rules files loaded at launch. - Run
/doctor prompt-audit(Claude Code v2.1.283 or later) to check your CLAUDE.md, CLAUDE.local.md, and AGENTS.md files, plus rules, skills, and more under.claude/. It looks for instructions written for older models, references to files or commands that don’t exist, and files that contradict each other, and nothing changes until you ask Claude to apply the proposed edits.
Next steps
- Andrej Karpathy Skills — a CLAUDE.md template plugin distilling Karpathy’s principles
- Superpowers — pair with CLAUDE.md for stronger workflow consistency
- Build a Skill — extract rules into reusable Skills
- Context engineering for Claude 5 — the latest guidance on cutting length and removing rules