Every Claude Code session starts the same way: Claude Code reads your CLAUDE.md file before it reads anything else. Before it looks at your code, before it processes your first prompt, it reads that file.
If the file is accurate and specific, the rest of the session benefits. If the file is missing or vague, Claude Code makes assumptions, and assumptions are where mistakes come from.
This is what CLAUDE.md is: a markdown file that provides the persistent context Claude Code needs to work accurately in your project.
What CLAUDE.md Is
CLAUDE.md is a plain markdown file that Claude Code automatically reads at the start of every session. It is not a configuration file in the technical sense, it is not parsed for settings.
It is context, written in natural language, that Claude Code uses to understand your project before doing anything.
The information in CLAUDE.md stays constant across sessions. Unlike conversation history, which disappears when you run /clear or start a new session, CLAUDE.md is always there.
It is the one source of persistent, project-level context that survives every session boundary.
CLAUDE.md is the difference between Claude Code knowing your project and Claude Code guessing about your project. One produces consistent output. The other produces surprises.
Two Locations
CLAUDE.md exists in two places, and they serve different purposes.
Project CLAUDE.md (Repo Root)
The project-level CLAUDE.md lives at the root of your repository, next to your package.json, pyproject.toml, or equivalent. It applies only to sessions started in that project directory.
This is where you put everything specific to this project: the stack, the testing framework, the conventions, the file structure, the services it integrates with, and the things that should never be changed without explicit instruction.
Global CLAUDE.md (~/.claude/CLAUDE.md)
The global CLAUDE.md lives in your home directory under ~/.claude/. It applies to every Claude Code session on your machine, regardless of which project you are working in.
This is where you put preferences and constraints that are true across all your projects: your preferred response style, output format preferences, a reminder to always ask before deleting files, or global security practices you always want enforced.
The two files stack. Claude Code reads the global CLAUDE.md first, then the project-level CLAUDE.md on top.
Project-level instructions take precedence when they conflict.
What Goes in CLAUDE.md
A well-written CLAUDE.md covers six categories of information:
1. Stack and Dependencies
List the language, framework, major libraries, and versions you are using.
Claude Code will use this to write idiomatic code for your stack rather than defaulting to the most common pattern it has seen.
## Stack
- Node.js 20, Express 4.18
- PostgreSQL 15 via pg (not an ORM)
- Jest 29 for testing
- ESLint with the Airbnb config2. Conventions
List the code patterns you use that differ from defaults or common practice.
This includes things like naming conventions, file organization, error handling patterns, and import styles.
## Conventions
- Use CommonJS (require/module.exports), not ESM
- Route handlers follow the pattern in src/routes/users.js
- Always validate input with Joi before touching the database
- Error responses: { error: string, code: string }3. Testing Approach
Specify where tests live, what framework you use, how to run them, and whether tests are required for every change.
## Testing
- Unit tests in tests/unit/, integration tests in tests/integration/
- Run tests: npm test
- New functions require unit tests; new routes require integration tests4. Do Not Touch
The most underused section of CLAUDE.md. List files, directories, or patterns that Claude Code should never modify without explicit instruction.
## Do Not Touch
- .env and .env.example (never read or modify)
- src/db/migrations/ (use migration scripts, never edit directly)
- package-lock.json (do not run npm install without asking)5. Key File Structure
A brief map of where important things live. This helps Claude Code navigate your project without indexing everything first.
## File Structure
- Entry point: src/server.js
- Routes: src/routes/
- Business logic: src/services/
- Database queries: src/db/queries/
- Shared utilities: src/utils/6. External Service Context
Any integrations, environment variables, or external dependencies that Claude Code should know about.
## External Services
- Sends email via SendGrid (SENDGRID_API_KEY env var)
- Stripe for payments (src/services/billing.js)
- All API keys are in .env, never hardcode themWhat Does NOT Belong in CLAUDE.md
Length is the enemy of a useful CLAUDE.md. Include only information that is specific to your project and not something Claude Code already knows.
Do not include:
- Generic best practices Claude Code already follows (
write clean code,handle errors properly) - Documentation that already exists in your codebase and that Claude Code can read directly
- Instructions that only apply to one specific task (put those in the prompt instead)
- Anything longer than what you could read in 2 minutes
A CLAUDE.md over 400 lines is a sign that some of it should be removed, moved to actual code documentation, or split into section-specific files.
How CLAUDE.md Affects Output Quality
The difference between a project with a good CLAUDE.md and one without is measurable.
Without CLAUDE.md:
- Claude Code defaults to the most common patterns it has seen (which may not match your stack)
- It guesses at your naming conventions and file structure
- It does not know what files to avoid
- Each session starts from scratch
With a specific CLAUDE.md:
- Code matches your existing patterns on the first try
- New files go in the right directories
- Conventions are consistent across sessions and team members
- You spend less time reviewing and correcting output
The 20 minutes it takes to write a good CLAUDE.md saves hours across the lifetime of the project.
How to Create CLAUDE.md with /init
Claude Code can generate a starting CLAUDE.md for you. Run /init in an active session and Claude Code will analyze your repository and produce a CLAUDE.md draft based on what it finds.
The /init output is accurate for what it can infer: your stack, your test framework, your package scripts.
It will not know your conventions unless they are already in the code, and it will not know your “Do Not Touch” list at all.
Treat the /init output as a first draft. Review every section, add the conventions and constraints that are not inferable from the code, and delete anything that is generic rather than specific to your project.
CLAUDE.md Template for a Web App Project
# [Project Name]
[One sentence: what this project is and what it does.]
## Stack
- [Language and version]
- [Framework and version]
- [Database]
- [Test framework]
- [Linter/formatter]
## Conventions
- [Import style: ESM or CommonJS]
- [Error handling pattern]
- [Naming conventions for files and functions]
- [Preferred patterns for [key task in your project]]
## Testing
- Test location: [path]
- Run tests: [command]
- [What requires tests]
## Do Not Touch
- [File or directory]
- [Reason for each]
## File Structure
- Entry point: [path]
- [Key directory]: [what lives there]
- [Key directory]: [what lives there]
## External Services
- [Service name]: [what it does, which file handles it, which env var it uses]
## Setup
- [How to install dependencies]
- [How to start the dev server]
- [Any required environment setup]A CLAUDE.md Is Not Optional for Team Projects
On a team, CLAUDE.md is the shared context that ensures every developer gets consistent Claude Code output. Without it, each team member’s sessions will produce differently styled, differently structured code.
With a shared CLAUDE.md committed to the repo, every session, for every developer, starts from the same baseline.
Commit your CLAUDE.md to version control. Review it in pull requests the same way you review code.
Update it when conventions change.
If your team is adopting Claude Code and wants help building effective CLAUDE.md files and development practices, Phos can help.
We are a CCA-F certified Claude partner with 400+ AI engagements.
Talk to the Phos team to learn how we help teams get consistent, high-quality output from Claude Code.
FAQ
Does CLAUDE.md have a required format or schema?
No. CLAUDE.md is plain markdown read as natural language context. There is no required schema, no required sections, and no parsing beyond what the language model does when reading it.
The format that works best is clear headings and bullet points, because those are easy to scan and understand.
What happens if my project CLAUDE.md and global CLAUDE.md conflict?
Claude Code reads the global CLAUDE.md first, then the project-level CLAUDE.md. When instructions conflict, the project-level instruction takes precedence.
Use this intentionally: set global defaults that apply everywhere, then override them in the project CLAUDE.md when a project needs something different.
Should I commit CLAUDE.md to my repository?
Yes, for team projects. Committing CLAUDE.md means every team member gets the same baseline context, and the file evolves through your normal code review process.
For personal projects, it is optional, but committing it means you always have the latest version when cloning the repo on a new machine.
How often should I update CLAUDE.md?
Update it whenever your conventions change, when you add a new major dependency, when the file structure changes significantly, or when you notice Claude Code consistently making the same mistake that a CLAUDE.md instruction would prevent.
A good heuristic: if you have corrected Claude Code on the same issue more than twice, add a rule to CLAUDE.md.