What Is a CLAUDE.md File and Why Do Developers Use It?
CLAUDE.md is a plain markdown file you drop into the root of your project. Claude Code reads it at the start of every session, so it's where you encode the rules, standards, and context that apply to your specific project — without repeating yourself every chat. A 2,000-star GitHub repo helped popularize it, and the community debate about what actually belongs in it has been fierce.
How it works
When you run claude in a project directory, Claude Code automatically looks for CLAUDE.md (and .claude/CLAUDE.md) and injects the contents as a persistent system-level instruction before your first message. This means Claude knows your project's context before you type a single word.
It also stacks hierarchically: a root-level CLAUDE.md sets project-wide rules, while a CLAUDE.md inside a subdirectory adds context for that module. Most teams commit CLAUDE.md to git so every developer — and every Claude session — starts from the same shared baseline.
What actually belongs in it
The r/ClaudeAI thread that drove 2,000+ stars surfaced a sharp community split: half the comments called it "cargo culting" and "homeopathy," while the other half reported genuine improvements. The consensus from the most-upvoted replies:
- Specific beats vague. "Be helpful and accurate" does almost nothing. "Always write Jest tests for new functions, placed in
__tests__/next to the source file" is concrete enough to change behavior. - Project structure matters most. Document your directory layout, key file locations, and how modules relate. Claude has no other way to know this.
- Commands it should always/never run. "Always run
npm run lintbefore suggesting a commit." "Never rungit pushwithout confirmation." These are where CLAUDE.md earns its keep. - Tech stack and non-obvious constraints. Framework versions, deprecated APIs you've banned, third-party libraries already in use that Claude shouldn't reinvent.
Copy-paste starter template
# Project: [Your project name]
## Tech stack
- Node.js 22, TypeScript 5.4
- React 19 (functional components only — no class components)
- PostgreSQL via Drizzle ORM
## Directory structure
- src/ Source files
- src/routes/ Express route handlers
- src/db/ Database schema and queries
- tests/ Jest test files (mirror src/ structure)
## Rules
- Always write tests for new functions (Jest, placed in tests/)
- Run `npm run lint` before suggesting any git commit
- Never run `git push` or deploy commands without explicit user confirmation
- Prefer named exports over default exports
- Never use `any` in TypeScript — use `unknown` or a proper type
## Context
This is a SaaS dashboard. Authentication uses Clerk. Background jobs use BullMQ.
What the debate gets wrong
The "cargo cult" critics are often judging CLAUDE.md files filled with vague personality rules ("think step by step," "be thorough"). Those genuinely don't help. But project-specific structural rules — the kind only you could write because only you know your codebase — measurably reduce the friction of every Claude session. The question isn't whether CLAUDE.md works; it's whether you've put the right things in it.
← Back to Claude Cowork FAQ · See also: System Prompts Guide · OpenClaw SOUL.md