What the Claude Code CLAUDE.md File Is (and Why It Exists)
The claude code claude.md file is a plain-text file you place in your project root that Claude Code reads automatically at the start of every session. It's not a config file for the tool itself - it's a brief for Claude. When you open the desktop app or start a terminal session in that directory, Claude reads CLAUDE.md before it reads anything you type. Everything in it is in context before your first message lands.
Before I set one up on a client project, every session started the same way: I'd spend the first few messages re-establishing which tech stack we were using, what commands to run, what files were off-limits, and what patterns the client cared about. A five-minute re-orientation tax on every chat. CLAUDE.md is the fix. You pay the setup cost once. Every session after that starts with Claude already oriented.
Where CLAUDE.md Lives and How Claude Finds It
Drop the file in your project root and name it exactly CLAUDE.md - all caps, .md extension. Claude Code finds it automatically. You do not need to import it, reference it in a config, or point Claude at it. It's just there and Claude reads it. In the Claude Code desktop app the file is picked up as soon as you open the project folder. In the terminal, it's read from the working directory when you start your session.
You can also have a global CLAUDE.md at the root of your home directory for rules that apply across every project - things like your preferred response style, tone guardrails, or the way you like code commented. Project-level CLAUDE.md takes priority over the global one when both exist.
What to Put In It - The Standing-Context Method
I use what I call the Standing-Context method: write the brief once, make it specific to the project, and keep it under one screen of text. The goal is to answer the three questions Claude would otherwise ask in the first three messages of every session: what are we building, how do we build it here, and what are the rules.
- Stack and tooling: the language, framework, package manager, and any non-obvious library choices. One line each. 'We use Bun not npm.' 'UI is Tailwind only - no inline styles.'
- Key commands: the exact command to start the dev server, run tests, and build. Claude will suggest these constantly - give it the right ones up front.
- File and folder conventions: what the directory structure means, which folders are off-limits, and where generated files go.
- Always/never rules: the explicit guardrails. 'Never edit files in /dist.' 'Always write tests for any new utility function.' 'Use server actions, not API routes.'
- Client or project context: one short paragraph on what the product does and who it's for. Gives Claude a frame for every decision it makes.
What NOT to Put In CLAUDE.md
The file earns its value by being short and specific. Every line that doesn't need to be there makes the file worse - Claude has to weigh it along with everything that does matter.
- Don't paste in large code blocks, component examples, or schema definitions. Link Claude to the file instead - 'see src/types/schema.ts for the full type definitions.'
- Don't put secrets, API keys, or credentials in CLAUDE.md. It's a plaintext markdown file that lives in your repo.
- Don't copy your README into it. The overlap wastes space and both files go stale at different rates.
- Don't add aspirational rules you haven't actually decided yet. Stale or speculative guardrails cause Claude to follow conventions you've abandoned.
Before and After: The Client Build Where CLAUDE.md Saved a Full Afternoon
I was three weeks into a client build - a Next.js dashboard with a specific folder structure the client's team had already agreed on. Every session I'd open Claude Code, describe the task, and within a few messages Claude would start suggesting component placements that didn't match the project structure. Not wrong, just different from what we'd agreed. I'd correct it, it would adjust, and we'd move forward. A small tax every time.
I spent fifteen minutes writing a CLAUDE.md: the folder conventions, the component naming rules, the three commands the client's CI needed, and two hard always/never rules about where server logic could live. The next session Claude walked in already knowing all of it. It placed files correctly without prompting, suggested patterns that matched the existing codebase, and I didn't correct a single structural decision in the entire session. The re-orientation tax went to zero.
The Mistakes That Make CLAUDE.md Backfire
CLAUDE.md only works as long as it's accurate. The two failure modes I see most:
Common CLAUDE.md mistakes and what they cost you
| Mistake | What Goes Wrong |
|---|---|
| Bloating it with every project detail | Claude treats all rules equally - the important ones get diluted among the noise |
| Never updating it after you change conventions | Claude confidently follows rules you've abandoned, which is worse than no rules |
| Copy-pasting the same generic rules into every project | You lose the project-specific signal that makes CLAUDE.md valuable |
| Writing rules too vaguely | 'Write clean code' tells Claude nothing. 'No function longer than 40 lines' is something it can actually follow |
How to Use CLAUDE.md with Subagents and Multi-File Builds
When Claude Code spins up subagents to run tasks in parallel, each subagent also reads CLAUDE.md. This means your guardrails propagate automatically - you don't have to re-brief each agent or worry that a background subagent is going to place a file in the wrong folder or use the wrong naming convention. The Standing-Context in CLAUDE.md travels with every agent that runs in the project.
On large multi-file builds, I also use CLAUDE.md to define a small set of /skills that Claude should treat as available. I'll list the skill name and a one-line description so Claude knows it can invoke them without me prompting it each time. This keeps orchestration decisions inside the project context file rather than buried in chat history.
How to Create Your CLAUDE.md Right Now
In the Claude Code desktop app, open your project and look for the project settings - you'll find an option to create or edit CLAUDE.md directly. In the terminal, run `touch CLAUDE.md` in your project root and open it in any editor. Start with three sections: Stack, Commands, Rules. Keep each section to five bullets or fewer. Once you've shipped one project with it, you'll find you don't know how you worked without it.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
What is the CLAUDE.md file in Claude Code?
CLAUDE.md is a plain-text file you place in your project root that Claude Code reads automatically at the start of every session. It acts as a standing brief - your stack conventions, key commands, and always/never guardrails - so Claude is already oriented before your first message. You write it once and every future session inherits that context.
Where do I put the CLAUDE.md file?
Place it in your project root, named exactly CLAUDE.md with all caps. Claude Code finds it automatically from the working directory - no config required. You can also keep a global CLAUDE.md in your home directory for rules that apply across every project, though project-level rules take priority when both exist.
What should I put in CLAUDE.md?
The five things that earn their place: your tech stack and tooling choices, the key commands to start, test, and build the project, folder and file conventions, explicit always/never guardrails, and a short paragraph of project context. Keep each section to five bullets or fewer. The goal is a file short enough to read in thirty seconds that still answers every question Claude would otherwise ask in the first messages of a new session.
Does CLAUDE.md work with subagents?
Yes. When Claude Code spins up subagents to run tasks in parallel, each subagent reads CLAUDE.md as well. Your guardrails and conventions propagate to every agent running in the project automatically, so you don't need to re-brief them or worry about background agents drifting from the conventions you've set.
How often should I update CLAUDE.md?
Update it the same day you change a project convention. A stale CLAUDE.md is actively worse than no file - Claude will confidently follow rules you've abandoned and place things in patterns you've moved away from. Treat it like a living document that stays in sync with the actual project decisions, not an archive of how things used to work.
Is there a difference between a global and a project-level CLAUDE.md?
Yes. A global CLAUDE.md at your home directory root sets defaults for every session - things like your preferred response style or general code quality rules. A project-level CLAUDE.md sets rules specific to that codebase. When both exist, Claude reads both, with project-level rules taking priority on any conflict. Use global for personal habits, project-level for project facts.
Last reviewed by David Iya on July 25, 2026
