What Is CLAUDE.md? A Complete Guide to Claude Code’s Smart Memory File, Placement Rules, and Practical Patterns

What Is CLAUDE.md?

CLAUDE.md is a Markdown configuration file that Claude Code, Anthropic’s coding agent, automatically loads at startup and treats as part of its system prompt. By placing it in a project, you can give Claude persistent knowledge of build commands, coding conventions, testing instructions, repository quirks, and anything else it should know about your codebase. Think of it as a project-specific onboarding document for an AI teammate that happens to be read every single session.

Unlike a README, which is for humans, CLAUDE.md is written for Claude. Where a README explains what your project does to a contributor, CLAUDE.md tells Claude how to behave inside it: which commands to run, which files to avoid, which patterns are off-limits, and which decisions have already been made. Keep in mind that the file is part of the prompt, not a config flag — wording choices matter, and ambiguous instructions get followed just as faithfully as clear ones.

How to Pronounce CLAUDE.md

How CLAUDE.md Works

When Claude Code starts in a directory, it walks up the filesystem looking for CLAUDE.md files. Every match it finds is concatenated into Claude’s context, with deeper files (closer to where you are) appended last so they can override broader defaults. This hierarchical loading lets you separate global preferences (“always prefer functional components”) from per-project rules (“this repo uses React 18, never 19”). It is important to note that the file is loaded once per session — edits made mid-conversation do not retroactively rewrite the prompt.

Loading Order

The canonical hierarchy is:

1. ~/.claude/CLAUDE.md — applies to every project on your machine
2. <project root>/CLAUDE.md — applies to the whole repository
3. <subdirectory>/CLAUDE.md — applies only to that subtree (useful in monorepos)

Claude Code reads them in that order, so the most specific instructions win. Critically, Claude treats the contents the same way it treats your typed instructions: as authoritative input. This is why vague wording in CLAUDE.md can backfire — Claude will follow ambiguous rules just as enthusiastically as clear ones. You should write the file the way you would brief a careful but literal new teammate.

Why It Exists

Coding agents lose context every time a session ends. Without persistent memory, you have to re-explain “this codebase uses pnpm, the test command is pnpm test:unit, and we never use any in TypeScript” on day one of every project. CLAUDE.md fixes that by serving as a durable, version-controlled prompt that survives /clear and lives next to your code. Note that the goal is to encode team-level conventions, not session-specific instructions; per-task guidance still belongs in chat.

It is also worth understanding the relationship between CLAUDE.md and other configuration surfaces inside Claude Code. The settings file (.claude/settings.json) governs what Claude is allowed to do — which tools to expose, which directories to confine work to, which approval rules to enforce. CLAUDE.md governs what Claude should know — the project’s conventions, history, and context. The two are complementary: one sets capabilities, the other sets context. Confusing them is a common source of frustration for teams that try to encode “do not edit production config files” as a CLAUDE.md rule and discover Claude editing them anyway, when the right tool was a settings-level deny rule.

What Claude Code Actually Reads

Behind the scenes, Claude Code performs a deterministic walk: starting from the working directory, it ascends one parent at a time until it hits the home directory or the filesystem root, collecting any CLAUDE.md file along the way. The home-level file is processed first, then each project-level file in order of nesting. Files in unrelated branches of the tree are ignored. This is important because it means a CLAUDE.md sitting in a sibling project does not pollute the current session — only the chain from your current directory upward matters.

You should also note that Claude Code does not parse Markdown structure semantically. It hands the raw text to the language model as part of the system prompt, then trusts the model to parse headings, bullets, and code fences in context. Practically, this means weird Markdown (broken tables, unclosed code fences) does not “crash” Claude — it just confuses the model in subtle ways, which often shows up as ignored rules. Keeping the Markdown clean is therefore a quality issue, not a syntax issue.

CLAUDE.md Usage and Examples

Quick Start

Drop a file named CLAUDE.md at the root of your project and tell Claude what it should know. A minimal example:

# Project Overview
A Next.js 14 (App Router) e-commerce site, TypeScript + Tailwind.

# Build & Test
- Dev server: `pnpm dev`
- Production build: `pnpm build`
- Tests: `pnpm test` (Vitest)
- Lint: `pnpm lint`

# Coding Conventions
- Functional components only. Never class components.
- State management is Zustand. Do not introduce Redux.
- API calls live under `lib/api/` and must use the `apiClient` wrapper.

This minimal file already covers about 80% of what most projects need: it tells Claude what the project is, how to run it, and what conventions to respect. From here, you can layer additional sections (decision history, do-not-do list, environment notes) as the codebase grows. Resist the urge to write everything on day one; CLAUDE.md is best built up incrementally as you discover which questions Claude keeps getting wrong.

Common Implementation Patterns

Pattern A: Command Cookbook

# Frequently Used Commands
- DB migrations: `pnpm db:migrate`
- Type generation: `pnpm typegen`
- E2E tests: `pnpm test:e2e --headed`

Best for: monorepos and microservices where there are dozens of memorable commands you can never recall correctly. Claude can suggest the right one without guessing.

Avoid when: you only have three commands. The cookbook becomes noise.

Pattern B: ADR Pointer

# Architectural Decisions
- Auth: Clerk ([ADR-002](docs/adr/002-auth.md))
- Database: Supabase, not PlanetScale ([ADR-005](docs/adr/005-db.md))
- State: Zustand ([ADR-008](docs/adr/008-state.md))

If you change any of these, update the ADR first.

Best for: teams where the “why” of decisions matters and ADRs already exist. Claude can pick up the rationale without you re-explaining it.

Avoid when: you do not maintain ADRs. Pointers to nonexistent docs are worse than no pointers.

Pattern C: Forbidden Pattern List

# Do Not Do
- Use `any` in TypeScript (use `unknown` and narrow)
- Leave `console.log` in production code (use the `debug` package)
- Reference `process.env.SECRET` from client-side code

Best for: codebases with a history of recurring mistakes. Claude pre-empts them.

Avoid when: rules are genuinely “it depends.” Vague forbidden lists confuse Claude more than they help.

Anti-Pattern: The Bloated CLAUDE.md

# Do not do this
<3,000 lines summarizing every file in the repo>
<Full library docs copy-pasted>
<The entire internal wiki>

Every line of CLAUDE.md is loaded into Claude’s context window on every session, eating tokens that would otherwise be used to read your actual code. Anthropic’s official guidance is to keep CLAUDE.md concise and link out to detailed docs. As a rule of thumb, 200 to 500 lines is the sweet spot. Past that, split the contents into docs/ and link from CLAUDE.md.

Secrets Hygiene

Never put API keys, database connection strings, or sensitive vulnerability details in CLAUDE.md. The file is intended to be committed to version control, which means anyone with repository access can read it. Reference environment variables instead: write “use DATABASE_URL” rather than the actual URL. You should treat CLAUDE.md as something that may eventually become public, even if it currently lives in a private repo.

Advantages and Disadvantages of CLAUDE.md

Advantages

• Persistent context: you stop re-explaining the same project quirks every session.
• Team alignment: everyone using Claude Code on the repo plays by the same rules.
• Versioned history: Git tells you when and why a rule changed.
• Decision transparency: encoding “why” alongside “what” makes future changes safer.
• Survives /clear: clearing the conversation does not wipe project knowledge.

You should weigh these benefits against the disadvantages below — for very small or short-lived projects, the overhead of writing and maintaining CLAUDE.md may not pay for itself. The break-even point is usually somewhere around the third Claude Code session on the same codebase: if you find yourself re-explaining the same context to Claude for the third time, it is time to write it down.

Disadvantages

• Token tax: longer files cost more context every session.
• Drift risk: if the codebase evolves but CLAUDE.md does not, Claude follows stale rules.
• Over-constraining: too many “do not” rules can suppress good suggestions.
• Leak risk: a careless commit can expose internal details to a public repo.

CLAUDE.md vs README.md vs .cursorrules

The three files all live near a project’s root and look superficially similar, but they serve different audiences. Confusion is common, especially when a project has all three.

The three coexist comfortably. A typical Claude-friendly repo has all three, with overlapping but differently-tuned content for each audience. You should not feel the need to deduplicate every sentence — the same rule may sensibly appear in two of the files for two different readers.

Common Misconceptions

Misconception 1: “Anything in CLAUDE.md is followed 100% of the time”

Why this confusion arises: the word “configuration file” suggests deterministic behavior, the way a Webpack config or a JSON setting flips features on or off. Anthropic’s documentation also describes CLAUDE.md as being “automatically loaded,” which sounds enforceable. The mental model is the wrong one because Claude is a probabilistic system that weighs the entire context, not a rule engine.

The reality: CLAUDE.md is appended to the system prompt. Claude is still a language model picking the most reasonable response from the entire context, and explicit user instructions in the chat usually outweigh CLAUDE.md when they conflict. Treat it as strong guidance, not a contract — and repeat critical rules in multiple places to make them stick.

Misconception 2: “~/.claude/CLAUDE.md and project CLAUDE.md are different file types”

Why this confusion arises: the two locations are documented in different sections of Anthropic’s guides, and the home-directory copy is often described in terms of “user preferences” while the project copy is described as “project context.” This makes them sound like separate categories. The naming reason for the confusion is that some tutorials only ever mention one of the two and present it as “the” CLAUDE.md.

The reality: they are the same file format. The only difference is scope — global vs. project. Both are concatenated into Claude’s context, with the project file appended later and therefore taking precedence on conflict.

Misconception 3: “Bigger CLAUDE.md = smarter Claude”

Why this confusion arises: software engineers tend to assume more documentation produces better outcomes, the way a denser README helps onboarding. The reasoning that “more rules equals more discipline” stems from human-team experience. The token economics of LLMs are easy to overlook because they are invisible to the user.

The reality: CLAUDE.md content competes for context window space with your actual code. A 3,000-line CLAUDE.md leaves Claude little room to read the files it is supposed to modify. Anthropic explicitly recommends keeping it short and focused; their own template fits in a single screen.

You should also keep in mind that misconceptions about CLAUDE.md tend to compound. Once a team adopts the wrong mental model — for example, treating it as a hard config — they often follow up by writing brittle, over-specific rules that fail the moment a new edge case appears. Periodically rereading what is actually in the file, with the eye of a new team member, is the cheapest way to catch this drift.

Real-World Use Cases

• Legacy code handover: capture undocumented quirks, deprecated APIs to avoid, and “the way we have always done it” rules so a fresh Claude session inherits them.
• Microservice monorepos: place a CLAUDE.md in each service directory so Claude understands which language, framework, and deploy target applies where.
• Open-source maintenance: maintainers can ship a CLAUDE.md so external contributors using Claude Code get higher-quality PRs by default.
• New-hire onboarding: junior engineers can read CLAUDE.md as a “rules of the road” doc, doubling its value for humans.
• Regulated environments: in finance and healthcare, encoding “do not generate code that does X” prevents Claude from accidentally violating compliance constraints.

Beyond those headline scenarios, teams often discover smaller but high-value uses once they get comfortable with the file. A few patterns that come up repeatedly:

• Encoding the test pyramid: spelling out which kind of test belongs where (“unit tests under __tests__, integration under tests/integration, no E2E in this repo”) prevents Claude from inventing the wrong style of test.
• Documenting frozen APIs: marking specific modules as “do not change without ADR” helps Claude treat them with appropriate caution during refactors.
• Bridging team handoffs: when ownership of a service changes, the outgoing team can dump tribal knowledge into CLAUDE.md so the new team’s Claude sessions inherit it without a long handover meeting.
• Reproducing flaky-test triage steps: if a particular test fails for known infrastructure reasons, recording the workaround in CLAUDE.md keeps Claude from chasing red herrings.
• Pinning library choices: explicitly stating “we use date-fns, never moment, never dayjs” eliminates a common source of inconsistency in mature codebases.

What ties these patterns together is the same principle: any rule that would normally take three paragraphs of code review to explain to a junior engineer is a candidate for CLAUDE.md. The cost of writing it down once is small, and the savings compound across every future session.

Frequently Asked Questions (FAQ)

Conclusion

• CLAUDE.md is the file Claude Code reads on startup to learn your codebase’s commands, conventions, and constraints.
• Place a global one at ~/.claude/CLAUDE.md and a project-specific one at the repo root; subdirectory files override both.
• Keep it tight — 200 to 500 lines. Past that, link out to detailed docs.
• It is treated as part of the system prompt, not as a hard config; clear, repeated wording wins.
• Never put secrets in CLAUDE.md. It is committed to Git and visible to anyone with repo access.
• Pair it with README.md (for humans) and, if relevant, .cursorrules (for Cursor users) — they coexist happily.

Adopted thoughtfully, CLAUDE.md becomes the cheapest source of leverage in a Claude-powered workflow: write a few hundred lines once, and every future session inherits the team’s hard-won context for free. Skip it, and you pay the same onboarding tax over and over. The goal is not to encode every rule, but to encode the rules that keep biting you — and to update the file the moment a new one starts to.

References