What is CLAUDE.md? Claude Code’s Project Memory File
CLAUDE.md is a plain Markdown file that Claude Code — Anthropic’s agentic coding tool — automatically reads at the start of a session and folds into its context, before you’ve typed a single instruction. It’s the mechanism for telling an AI coding agent things a human teammate would pick up from a README, a wiki page, and six months of tribal knowledge, all at once, every single time it starts working in your repository.
The Problem It Solves
Without project-specific context, every session with a coding agent starts from zero: it doesn’t know your test command, whether you use npm or pnpm, that your team prefers early returns over nested conditionals, or that the legacy/ directory is untouchable despite looking like dead code. You’d end up re-explaining the same things in every conversation — or worse, the agent would guess, and guess wrong.
# Project Conventions
## Commands- Run tests: `npm test`- Run a single test file: `npm test -- path/to/file.test.ts`- Lint: `npm run lint`- Build: `npm run build`
## Code Style- Prefer named exports over default exports- Use early returns instead of nested if/else- No `any` types — use `unknown` and narrow instead
## Notes- `legacy/` is being phased out — do not add new code there- Database migrations live in `migrations/` and must never be edited after mergeOnce this file exists at the repository root, Claude Code reads it automatically on every session in that project — no copy-pasting the same instructions into every conversation.
Not a Prompt, a Standing Context
The key distinction: CLAUDE.md isn’t something you send — it’s something the agent already has before you ask anything. This matters because it changes what kind of information belongs there. A one-off instruction (“refactor this function to use async/await”) belongs in your actual request. A standing fact that’s true across every session in this repo (“we use Vitest, not Jest”) belongs in CLAUDE.md.
Where It Lives
The simplest setup is a single CLAUDE.md at your repository root, checked into git alongside your code — so the whole team, and every session, benefits from the same context. Claude Code also supports multiple CLAUDE.md files at different levels (project root, subdirectories, and a user-level file for personal preferences that apply across all your projects), covered in full in How Claude Code Discovers & Loads CLAUDE.md Files.
What It’s Good For (and What It Isn’t)
CLAUDE.md is well-suited to: build/test/lint commands, architectural context an agent can’t infer from file structure alone, coding conventions specific to your team, and warnings about non-obvious gotchas (a script that looks safe to delete but isn’t, a directory generated by tooling that shouldn’t be hand-edited).
It’s poorly suited to: information that changes constantly (current sprint status, today’s specific task — that belongs in your actual conversation), exhaustive API documentation better served by dedicated docs, and generic advice that applies to any codebase in any language (“write clean code”) — an agent capable enough to need CLAUDE.md at all doesn’t need to be told that.
Common Mistakes
Treating CLAUDE.md as a dumping ground for every fact about the project. A bloated file costs context budget on every single session whether or not that section is relevant to the current task — see What to Include in CLAUDE.md for what actually earns a place in it.
Writing it once and never revisiting it. A CLAUDE.md that describes how the codebase worked eight months ago actively misleads the agent — it should be maintained with the same discipline as a README, not treated as a write-once artifact.
Assuming it replaces good code organization. CLAUDE.md supplements what the agent can infer from reading the actual code — it doesn’t substitute for clear naming, sensible structure, or documentation the code itself should carry.
Frequently Asked Questions
Does CLAUDE.md work with any AI coding tool, or just Claude Code? It’s Claude Code’s specific convention — other tools have their own equivalents (Cursor’s rules files, GitHub Copilot’s instructions file, and others), covered in CLAUDE.md vs Other AI Config Files.
Is CLAUDE.md required to use Claude Code? No — Claude Code works without one, relying purely on what it can read from your codebase and what you tell it in conversation. CLAUDE.md is an optimization, not a requirement, but for any repository you work in repeatedly, it pays for itself quickly.
Can I generate a CLAUDE.md automatically? Yes — Claude Code can bootstrap one by scanning your codebase and drafting an initial file, which you then review and refine rather than writing entirely from scratch; see Writing Your First CLAUDE.md.
Summary
CLAUDE.md is standing context, not a prompt — a small, maintained file that tells Claude Code the things about your project that would otherwise need re-explaining every session. Get the scope right (commands, conventions, and genuine gotchas — not everything) and it becomes one of the highest-leverage, lowest-effort investments in working effectively with an AI coding agent on a real codebase.