What Is CLAUDE.md? (And Is It Necessary?)
If you use Claude Code, you've seen `CLAUDE
If you use Claude Code, you've seen CLAUDE.md mentioned everywhere — in docs, in repos, in every "how I use Claude Code" post. It's the single file most likely to change how well the tool works for you. And most people either skip it or stuff it with the wrong things.
Here's what it is, where it lives, and whether you actually need one.
What is CLAUDE.md?
A Markdown file that Claude Code automatically reads at the start of every session in that directory. No need to reference or attach it — if the file exists, Claude has already read it.
Think of it as the briefing you'd give a capable new teammate on their first morning: how the team does things, what to avoid, where the important pieces live. Every session, Claude Code starts knowing nothing about your codebase. CLAUDE.md brings it up to speed instantly.
Technically, the file is loaded into the context window at session start and delivered as a user message right after the system prompt — not embedded in the system prompt itself. Claude treats it as context, not enforced configuration: the clearer and more specific your instructions, the more reliably Claude follows them.
Where does Claude Code look for it?
Claude Code checks several locations and merges what it finds, broad to specific:
- Project root —
CLAUDE.mdin your repo. The most common and usually all you need. - Subdirectories — service-level files in a monorepo, loaded when Claude works with matching files.
- Personal global —
~/.claude/CLAUDE.mdfor defaults that apply across all your projects.
This cascade matters. Universal rules go at the root. Module-specific rules go in subdirectories so they only load when relevant, saving context tokens. Most teams only need the project-root file — commit it to git so everyone benefits.
Is CLAUDE.md necessary?
No — Claude Code works without it. But "necessary" is the wrong test.
Claude Code can inspect your repo, read files, and recover structure on its own. What it can't infer is intent and convention: why you use event sourcing, which testing approach is non-negotiable, what "done" means on your team. Without CLAUDE.md, you re-explain those at the start of every conversation. With it, they're loaded automatically.
So: not required, but the highest-leverage file in the workflow. It affects every session, every task, every output. If you use Claude Code regularly and don't have one, that's the first thing to fix.
What should go in it?
Three categories, kept lean:
- WHAT — tech stack, project structure, key abstractions. Especially important in monorepos.
- WHY — what the project does and why certain patterns exist. "We use X because Y" stops Claude from refactoring toward something that breaks your architecture.
- HOW — build, test, lint, and deploy commands. Verification steps. Workflow rules.
Keep it under 200 lines. Longer files consume more context and actually reduce how reliably Claude follows them. Fewer, better instructions beat a wall of text. Run /init to auto-generate a draft by scanning your codebase, then trim the generic parts and add your real standards.
What CLAUDE.md doesn't cover
CLAUDE.md is scoped to a project. It tells Claude about this codebase — its conventions, its commands, its architecture.
What it doesn't carry is context that isn't project-specific: who you are, how you work, the client or team the project is for, the standards you bring to every repo. You can put some of that in the global ~/.claude/CLAUDE.md, but it stays inside Claude Code — it doesn't travel to Cursor, ChatGPT, or any other tool, and it doesn't distinguish between the context of you, your team, or the client you're building for.
That's a different layer: structured context — personal, team, or project — that loads into any tool, not just one. CLAUDE.md handles the project. A context layer handles everything that should follow you across projects and tools.
→ What that layer is: What Is Personal Context for AI?
→ How to build it: How to Build Personal Context for AI
