Every time Claude Code starts a new session, it reads one file before anything else. That file is CLAUDE.md. It is not documentation. It is a contract — the agreement between you and your AI about how work gets done.
Why It Is the Most Important File
You deal with a lot of config files: package.json, tsconfig.json, .eslintrc. One file matters more than all of them combined.
Claude Code reads CLAUDE.md at the start of every session. Project structure, code style, test commands, known pitfalls — Claude learns all of it from this file. Without it, Claude is a new hire parachuted into an unfamiliar codebase. With it, Claude knows the rules before it writes a single line.
Shrivu Shankar, VP of AI Strategy at Abnormal AI, puts it bluntly: in effective Claude Code use, the most important file in your repository is the root CLAUDE.md. It is the agent’s constitution — the primary source of truth for how your specific codebase works.
He used the word “constitution.” A constitution is short, principle-driven, and does not handle details. The analogy is precise.
Guardrails, Not Manuals
The most common beginner mistake: trying to write an encyclopedia. Every function’s purpose, every file’s role, every API parameter — thousands of lines that consume Claude’s context window before it even starts working.
Boris’s team runs Claude Code itself with a CLAUDE.md of roughly 2,500 tokens — about 100 lines. The core rules file for managing the Claude Code product fits in 100 lines.
Shrivu’s approach is even more instructive: start small and add rules based on what Claude actually gets wrong. Do not try to pre-write a complete manual. Every time Claude makes a mistake, add one rule. This is what “start with guardrails” means.
The beauty of this method: the rule file stays perpetually precise because every entry corresponds to a real problem you have hit. The file stays naturally concise because you only record what has actually gone wrong.
Boris takes it further. During code review, he sometimes tags @.claude on a colleague’s PR and has it automatically add a new rule to CLAUDE.md. The team shares one CLAUDE.md file, checked into Git. Everyone contributes. The file is alive.
His exact words: “Claude is very good at writing rules for itself.” Tell it what mistake it made, and it will write a precise rule to prevent it next time.
What Actually Belongs in CLAUDE.md
The decision framework is simple: if Claude can figure it out by reading the code, do not write it. If Claude cannot guess it, it belongs in CLAUDE.md.
| Write This | Skip This |
|---|---|
| Custom build scripts Claude cannot guess | “This is a React project” (Claude can see that) |
| Code style preferences that differ from defaults | Standard language conventions (Claude already knows them) |
| Test commands and preferred test framework | Full API docs (link to them instead) |
| Architecture decisions and project context | Frequently changing information |
| Dev environment quirks and special env vars | File-by-file descriptions (Claude reads the file tree) |
| Common pitfalls and their fixes | “Write clean code” and “follow best practices” |
Additional rules from Shrivu: do not use @references to embed large documents — mention the path and tell Claude when to read it. Never write just “never do X” — always provide the alternative. And if a CLI command is so complex it needs paragraphs of explanation in CLAUDE.md, simplify the command itself. Write a bash wrapper with a clean API, then document only the wrapper.
The Hierarchy System
CLAUDE.md is not one file. It is a layered system. Claude Code automatically reads CLAUDE.md files at multiple levels, merging them in order:
~/.claude/CLAUDE.md ← Global: personal preferences across all projects
./CLAUDE.md ← Project: checked into Git, shared with the team
./src/CLAUDE.md ← Subdirectory: rules for a specific module in a monorepo
./src/api/CLAUDE.md ← Deeper subdirectory
Global level (~/.claude/CLAUDE.md): your universal preferences. Prefer TypeScript, default to Jest, write commit messages in English. These apply to every project.
Project level (./CLAUDE.md): project-specific rules. Check this into Git. Code style, architecture constraints, test commands, common pitfalls — everything the team needs to share.
Subdirectory level: invaluable in monorepos. Frontend rules in the frontend directory, backend rules in the backend directory. Claude loads the right rules for the right context.
You can also use @docs/coding-standards.md syntax to import other files. But be careful — @referenced files are fully embedded in the context. Only reference short files you genuinely need every time.
What a Good CLAUDE.md Looks Like
Here is a concise, real project-level example. Notice how short it is:
# MyApp
## Architecture
- Next.js 15 + TypeScript + Tailwind CSS
- Database: PostgreSQL + Drizzle ORM
- Auth: Better Auth
- State: Zustand (not Redux)
## Dev Commands
- Start: pnpm dev
- Test: pnpm test (Jest + React Testing Library)
- Type check: pnpm typecheck
- Lint: pnpm lint
## Code Style
- Functional components, no classes
- Tailwind for styles, no CSS files
- Server components for data fetching, not useEffect
- Error boundaries (error.tsx), not try-catch in components
## Common Pitfalls
- After Drizzle migrations, run pnpm db:generate or types will be stale
- Restart dev server after changing env vars
- better-auth session check is in middleware, do not re-check in page components
## Do Not
- Do not install new dependencies unless I explicitly approve
- Do not modify drizzle.config.ts
- Do not call the database directly from client components
Under 300 words. Every line earns its place — either a command Claude cannot guess or a lesson from a real mistake. Zero filler.
Do not copy this example. A good CLAUDE.md grows from your own project. Start with an empty file. Every time Claude makes a mistake, add one rule. After three months, that file is your most valuable AI asset.
Auto Memory: What Claude Remembers on Its Own
Beyond your hand-written CLAUDE.md, Claude Code has an automatic memory system. When you correct Claude’s behavior in conversation — “write commit messages in English from now on,” “put test files in __tests__” — Claude saves those preferences automatically. Next session, it remembers.
These memories live in ~/.claude/projects/<project>/memory/, with MEMORY.md as the entry point. They work alongside CLAUDE.md but serve a different purpose:
| Hand-Written CLAUDE.md | Auto Memory |
|---|---|
| Rules for the whole team | Personal preferences |
| Checked into Git | Stored locally |
| You maintain it | Claude maintains it |
| Structured and organized | Scattered, chronological |
Use both. Team rules go in the project CLAUDE.md; personal habits let Auto Memory handle.
The Iterative Flywheel
Mitchell Hashimoto, co-founder of HashiCorp and creator of Terraform, describes the exact same pattern. When he built AI workflows for Ghostly, every line in his config file corresponded to a past mistake the agent had made. The file was alive, constantly growing.
The process unfolds in stages. Week one: your CLAUDE.md is nearly empty — basic architecture and dev commands. Claude makes plenty of mistakes. Week two: guardrails emerge. You add rules one by one: “do not use relative paths in this file,” “regenerate types after running migrations.” The error rate drops. Month one: the flywheel is spinning. Twenty to thirty rules, all born from real experience. Claude’s output quality is noticeably higher, and you are correcting it less often. After that: continuous iteration. Occasional new rules, occasional pruning of outdated ones. The file stays lean but deeply customized. When you start a new project, you port over what applies and the whole cycle accelerates.
One sentence to remember: CLAUDE.md starts empty, gains one rule per mistake, stays lean, gets checked into Git, and is shared with the team. After three months of real use, that file is the most valuable AI asset you own.