Most people using Claude Code either ignore CLAUDE.md or auto-generate it and never touch it again. Not great practices. CLAUDE.md is the only persistent memory Claude has about your project. Every new session, Claude starts completely fresh, no memory of your stack, your folder structure, your preferences or that weird workaround you put in last week. CLAUDE.md is the fix for that. If you’re using Claude Code seriously, this is the one file that determines whether it feels like a helpful collaborator or a confused intern.
What it actually is
CLAUDE.md is a markdown file that Claude Code reads at the start of every session. This file gets loaded into Claude’s working context at the start of each session. Think of it as a briefing doc Claude reads before it starts working. The catch: Anthropic actually wraps your file in a note that says something like “this may or may not be relevant to your tasks.” Which means Claude can decide to filter parts of it if they don’t seem related to what you’re currently doing, especially if it’s a longer file.
Where to put it:
~/.claude/CLAUDE.md - global file, loads for every project on your machine
./CLAUDE.md in your project root - project-specific, goes into git
./CLAUDE.local.md - personal notes for a project, gitignored (more on this later)
Why shorter is actually better
Frontier AI models can reliably follow somewhere around 150–200 instructions before things start breaking down.Claude’s system prompt already uses ~50, leaving ~100-150 effective instructions.
In practice:
<200 lines recommended
300 lines = noticeable drop in adherence
The test for every line you write: “If I deleted this, would Claude actually make a mistake?” If the answer is no, cut it.
The structure that works
Think of it like onboarding a smart new person on your team on day one. You wouldn’t hand them a 50-page manual. You’d give them the essentials and tell them where to look when they need more. Start with one line about what the project is. Not a paragraph. One sentence.
List your commands in a code block
| ------- | ----------- | | pnpm test | Run tests | | pnpm typecheck | Type check |
Commands in code blocks get treated as commands. Commands buried in sentences get treated as suggestions.
Add a shallow directory map Not every file. Just the top level with one-line descriptions. Claude can open files itself - you don’t need to describe them all.
| --------- | ----------- | | app/ | Screens and navigation | | components/ | Reusable UI | | services/ | API and third-party calls | | lib/ | Business logic (no external calls here) |
Add version numbers to your tech stack Claude cannot guess that you’re using React Native 0.74 not 0.73. Be explicit.
Conventions - only the non-obvious ones Skip anything your linter already enforces. Skip standard language patterns. Only write down the things that are specific to how your project works. Good examples: “Expo Router for navigation. Not React Navigation.” “All API calls go through services. Never make fetch calls directly in components.”
Hard rules Every “never do X” should come with “do Y instead” and a quick explanation. The reason matters because it lets Claude generalize the rule to situations you didn’t anticipate.
How to keep the file short without losing information
The trick is progressive disclosure. Don’t dump everything into CLAUDE.md. Point to where details live.
Scoped rule files in .claude/rules/ load automatically at session start. You can even scope them to specific parts of your codebase, so they only activate when Claude is working in those areas - not burning context the rest of the time.
Skills in .claude/skills/ are on-demand. Claude loads a skill when the task matches the description. Good for things that matter on specific tasks but would be noise otherwise. External docs with “Read when” triggers in your CLAUDE.md:
Reference docs
Navigation structure - docs/navigation.md
Read when: Adding new screens or changing routing.
API integration - docs/api.md
Read when: Adding or modifying anything in services/.
This tells Claude when to actually get it. The result: your main file stays lean.
What to leave out
As said earlier, don’t include too much. Cut:
- Standard coding practices (Claude already knows them)
- File-by-file explanations
- Full documentation pasted inline
- Generic advice like “write clean code”
- Task-specific instructions (move them to skills)
Treat it like code
The most common failure mode: after every frustrating session, you add a new rule. Nobody ever removes old ones. Eventually the file is long enough that Claude starts filtering it, which makes things worse, which leads to more rules. Two signs your file needs pruning:
- Claude apologizes for missing an instruction that’s clearly already there. Rewrite that line - the phrasing is ambiguous.
- The same mistake keeps happening across sessions. The file is probably too long. Cut before you add. Only add a rule after a real mistake happened. Not speculatively.
Takeaway
The goal isn’t to tell Claude everything about your project. It’s to tell Claude the things it genuinely cannot figure out on its own, as concisely as possible so the rest of the budget goes toward actually building. Keep it short, keep it specific, update it when reality changes.