What is CLAUDE.md? The Practical Guide to Claude Code Project Memory

Claude Code starts every session at zero context. The model knows nothing about your project, your conventions, or what you typed last Tuesday. CLAUDE.md is how you fix that: a plain markdown file in your repo (or a few of them, at different scopes) that Claude Code reads at the start of every session and treats as persistent project context.¹ Write it once, every session inherits the rules.

This guide covers what CLAUDE.md is, where to put it, what to put in it, the best practices that hold up across thousands of public examples, where it falls short, and how it compares to AGENTS.md and similar standards from other AI coding tools.

Key Takeaways

• CLAUDE.md is a markdown file Claude Code loads into context at the start of every session. Four scope levels exist: managed policy (org), project, user, and local.¹
• Target under 200 lines per file. Longer files consume more context and reduce adherence.¹
• CLAUDE.md and auto memory are separate systems. CLAUDE.md is what you write. Auto memory is what Claude writes about itself as it works.

What CLAUDE.md is and how Claude Code reads it

CLAUDE.md is a plain markdown file Claude Code reads at the start of every session and injects into the context window before the conversation begins.¹ The model treats it as guidance, not enforced configuration. Specific, concise, well-structured instructions get followed more reliably than vague or contradictory ones.

The loading rule is straightforward. Claude Code walks up the directory tree from your current working directory, picks up every CLAUDE.md and CLAUDE.local.md along the way, and concatenates them into context (root-to-cwd order, with .local.md files appended last at each level).¹ Nested CLAUDE.md files in subdirectories aren't loaded at launch. They load on demand when Claude reads a file in that subdirectory.

There's also a separate system called auto memory. This is what Claude Code writes about itself as it works (build commands it discovered, debugging insights, code style patterns it picked up from your corrections). Auto memory lives in ~/.claude/projects/<project>/memory/MEMORY.md and the first 200 lines (or 25KB) load on every session.¹ CLAUDE.md is what you write. Auto memory is what Claude writes. Both load at session start. They are designed to complement each other, not replace each other.

Where to put CLAUDE.md: the four scopes

Claude Code recognizes four distinct CLAUDE.md locations. More specific scopes take precedence over broader ones.¹

Managed policy lives at an OS-level path (/Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux/WSL, C:\Program Files\ClaudeCode\CLAUDE.md on Windows). This is for organizations: company coding standards, security policies, compliance reminders. Cannot be excluded by individual settings.

Project lives at ./CLAUDE.md or ./.claude/CLAUDE.md in your repo root. This is the most common location and the one you share with your team via version control. Team-shared project architecture, build commands, conventions, and workflows belong here.

User lives at ~/.claude/CLAUDE.md. Personal preferences that apply to every project on your machine: code styling, tooling shortcuts, language preferences, your typical setup.

Local lives at ./CLAUDE.local.md in the project root. Personal project-specific preferences you don't want to commit (sandbox URLs, your local test data, machine-specific paths). Add it to .gitignore so it stays personal.

All four load together. Managed policy first, then project, then user, then local (each scope contributing context). A monorepo with multiple teams can use claudeMdExcludes in .claude/settings.local.json to skip CLAUDE.md files from other parts of the tree that aren't relevant to your work.¹

What to put in CLAUDE.md

The simplest rule from the Anthropic docs: CLAUDE.md is where you write down what you'd otherwise re-explain.¹ Add to it whenever Claude makes the same mistake twice, a code review catches something Claude should have known, or you find yourself typing the same correction you typed last session.

The sections that show up across most well-tuned project files:

Project architecture. A few sentences on what the repo is, what the major modules do, and how data flows. Don't recreate the README. Hit the parts that would help a new contributor orient.

Build, test, and run commands. The exact commands. Not vague directives like run the tests but npm test or pytest -xvs. Claude won't infer them from package.json alone half the time, and being explicit saves a turn.

Code conventions. Indentation, naming patterns, file organization, import ordering, we use X not Y directives. Write concrete instructions: Use 2-space indentation beats Format code properly.¹

Architecture decisions. Examples: We use Tanstack Query, not React Query directly. API handlers live in src/api/handlers/. Database migrations require approval from the DBA. Things a new dev would need to know to not break the team's conventions.

Common workflows. Examples: Before committing: run lint, run tests, format with Prettier. When adding a new API endpoint: update the OpenAPI schema, write a contract test, add to the docs. Workflow shortcuts that turn into Claude prompts.

What NOT to do. Negative instructions are powerful when paired with positive ones. Examples: Don't add comments unless asked. Don't write Python tests for the TypeScript code. Don't suggest design pattern changes without checking first.

For larger projects, split content into .claude/rules/*.md files (more on this below) instead of growing a single CLAUDE.md past 200 lines.

CLAUDE.md examples by project type

Different project types have different conventions worth encoding. The patterns below come from auditing well-maintained public CLAUDE.md files across language ecosystems. They're starting points, not prescriptions.

Node / TypeScript project

# Build & Test
- `npm run dev` to start the dev server (Next.js 14, App Router)
- `npm test` runs Jest (run before commits)
- `npm run typecheck` for TS type checks
- `npm run lint` runs ESLint + Prettier
 
# Architecture
- App Router under `app/`, components under `components/`
- Server components by default; mark client components with "use client"
- Database access via Prisma (`prisma/schema.prisma`)
- API routes in `app/api/[route]/route.ts`
 
# Conventions
- Use `pnpm` not `npm` (lock file is `pnpm-lock.yaml`)
- 2-space indentation, single quotes, semicolons enforced by ESLint
- Tests live alongside source files as `*.test.ts`
- Import order: external, internal alias (@/), relative
 
# Don't
- Don't add inline styles. Use Tailwind classes or CSS modules.
- Don't reach into Prisma directly from components. Use the data layer in `lib/db/`.

Python project

# Build & Test
- Python 3.12, managed via `uv`
- `uv sync` to install deps
- `uv run pytest -xvs` for tests (-x stops on first fail, -vs for verbose)
- `uv run ruff check` for linting
- `uv run mypy` for type checking
 
# Architecture
- FastAPI app entry: `src/app/main.py`
- Pydantic models: `src/app/schemas/`
- DB access via SQLAlchemy async (`src/app/db/`)
- Async/await throughout. No blocking I/O
 
# Conventions
- 4-space indentation (PEP 8)
- Type hints required on all functions
- Black-formatted (ruff handles it)
- Tests use pytest-asyncio for async tests
- Snake_case for files, modules, functions
 
# Don't
- Don't use `requests` (use `httpx` async client)
- Don't catch bare `Exception` without re-raising or logging

Rust project

# Build & Test
- `cargo check` for fast type check before committing
- `cargo test` runs the test suite
- `cargo clippy -- -D warnings` for lints (warnings are errors in CI)
- `cargo fmt` before any commit
 
# Architecture
- Workspace with two crates: `core/` (library) and `cli/` (binary)
- Async runtime: tokio
- Error handling: `thiserror` for library errors, `anyhow` for binary errors
 
# Conventions
- Prefer `?` operator over manual match for error propagation
- Doc comments (`///`) required on public APIs
- Use `tracing` for logs, not `println!`
- Tests live in the same file under `#[cfg(test)] mod tests`
 
# Don't
- Don't `unwrap()` or `expect()` in library code
- Don't use `Arc<Mutex<T>>` without thinking about lock contention

Monorepo (multi-package)

# Repo Layout
- `packages/web/` for Next.js frontend
- `packages/api/` for FastAPI backend
- `packages/shared/` for shared types and utilities
- `packages/cli/` for Rust CLI tool
 
# Build & Test
- Run all tests: `pnpm test` (orchestrated via Turborepo)
- Per-package: `pnpm --filter web test` or equivalent
- Each package has its own CLAUDE.md with package-specific rules
 
# Cross-package rules
- Shared types live in `packages/shared/types/`
- Never duplicate type definitions between packages. Always import from shared
- When changing shared types, run `pnpm typecheck` at root to catch breakage

The four examples above are starting templates. Most real CLAUDE.md files end up with sections specific to the project (deployment quirks, common pitfalls, the one weird workflow). Add those after the basics.

Common patterns from public CLAUDE.md files

Three patterns show up across most of the best-maintained public CLAUDE.md files in 2026.

The negative-instruction list. Almost every solid CLAUDE.md has a Don't section. Negative instructions are powerful because they catch the most common AI mistakes (over-commenting, suggesting unrequested refactors, choosing the wrong library variant, formatting differently than the project does). One or two paragraphs of don't X rules are often worth ten paragraphs of do Y rules.

The minimum-viable-context section. A 3-5 sentence summary of what the project is, what it does, and what its users care about. Sits at the top of the file. Useful because every session inherits this context, so Claude can answer questions like should I add a dependency for X without you having to re-explain the project.

The verifiable rules pattern. The Anthropic guidance to be specific enough to verify shows up consistently in well-maintained files. Use 2-space indentation instead of Format properly. Run npm test before commits instead of Test your changes. Rules that have a checkable yes/no answer outperform rules that require judgment.

CLAUDE.md best practices

Three practices show up consistently across the best-maintained public CLAUDE.md files.

Keep it under 200 lines. Anthropic's own guidance: longer files consume more context and reduce adherence.¹ If you're growing past 200, that's a signal to split into path-scoped rules or @-imported files instead.

Use structure, not paragraphs. Markdown headers and bullets work better than dense prose because Claude scans structure the same way humans do. Group related rules under headers (## Build & Test, ## Code Style, ## Architecture) and use bullets for individual rules. Avoid wall-of-text blocks.

Be specific enough to verify. Format code properly is too vague. Use 2-space indentation is concrete. Run npm test before committing beats Test your changes. Specific instructions work because Claude can either follow them or not, with no ambiguity to interpret.

A practical pattern that's emerged: use the @path/to/import syntax to pull in adjacent files (your README, a coding-standards doc, a workflow guide) instead of duplicating their contents in CLAUDE.md.¹ The imports load at launch alongside CLAUDE.md and keep your single source of truth in the original files. Max import depth is 5 hops.

A common failure mode: contradictions between nested CLAUDE.md files in subdirectories. Claude picks one arbitrarily when rules conflict. Run /memory periodically to see exactly what loads in a given working directory and prune the contradictions.

Path-scoped rules with .claude/rules/

For projects past the 200-line threshold, the modern pattern is .claude/rules/ instead of a sprawling CLAUDE.md.¹

The structure:

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions (short, high-level)
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       └── security.md     # Security requirements

Each file in .claude/rules/ is a topic. Rules without YAML frontmatter load at launch with the same priority as .claude/CLAUDE.md. Rules with a paths: field in YAML frontmatter only trigger when Claude works on matching files:

---
paths:
  - "src/api/**/*.ts"
---
 
# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

That ruleset only loads when Claude reads files matching src/api/**/*.ts, so the API conventions don't waste context tokens when you're working on the frontend. Path-scoped rules support glob patterns, multiple paths, and brace expansion (src/**/*.{ts,tsx}).

The .claude/rules/ directory also supports symlinks, so you can maintain shared rules in one place and link them into multiple projects.

Building your first CLAUDE.md: a worked example

Here's the workflow that produces a useful CLAUDE.md in 20 minutes, walked through end-to-end.

Step 1: Run /init. Inside Claude Code, in your project root, type /init. Claude analyzes your codebase, detecting the language, framework, build system, and existing config. Then it writes a starting CLAUDE.md with build commands, test instructions, and conventions it discovered.¹ If a CLAUDE.md already exists, /init suggests improvements instead of overwriting.

Step 2: Read the generated file. Open ./CLAUDE.md (or ./.claude/CLAUDE.md). The auto-generated content is a draft, not a final. It usually nails the obvious facts (build/test commands, framework detection) and misses the project-specific stuff a new contributor would actually need.

Step 3: Add a what-new-contributors-need-to-know list. Three to five bullets at the top. The kind of things you'd verbally tell a new teammate in their first hour. Examples: We migrated from REST to GraphQL last quarter, ignore the older REST handlers in legacy/. All payment code goes through Stripe, never raw card data. Our auth flow is custom, not Auth0 (see src/auth/README.md).

Step 4: Add three to five Don't rules. Negative instructions catch the most common AI mistakes. Examples that show up across well-tuned files: Don't add comments unless explicitly asked. Don't refactor when fixing a bug. Keep them as separate PRs. Don't suggest library changes without checking the existing version first.

Step 5: Add the workflow shortcuts. Multi-step processes you do repeatedly. Example: Before merging: run pnpm test, pnpm typecheck, pnpm lint. Update CHANGELOG.md. Mark the PR as ready for review.

Step 6: Test it. Restart Claude Code in the project. Run /memory to verify CLAUDE.md is loading. Then ask Claude something that should hit your new instructions, like Add a new API endpoint following our conventions or How should I run the tests?, and see if the response follows the rules. If not, the rules are vague. Rewrite them more specifically.

Step 7: Maintain it. Add to CLAUDE.md whenever Claude makes the same mistake twice or you find yourself typing the same correction. Treat it like collective team memory.¹

A common mistake at this stage: writing CLAUDE.md as documentation for humans. CLAUDE.md is instructions for Claude. Skip the prose. Use bullets, headers, and rules. The shorter and more concrete it is, the more reliably Claude follows it.

How CLAUDE.md compares: AGENTS.md, Cursor rules, Copilot instructions

The AI coding tool ecosystem developed similar files in parallel. The current state in 2026:

AGENTS.md is the cross-tool standard. OpenAI released the spec in 2025, and by December 2025 over 60,000 open-source projects had adopted it.² It's read by Codex, Cursor, Gemini CLI, and GitHub Copilot. Claude Code does NOT read AGENTS.md directly, but the recommended pattern is to either symlink CLAUDE.md to AGENTS.md or use the @AGENTS.md import at the top of your CLAUDE.md so both files read the same source.¹

.cursor/rules is Cursor's equivalent. Similar structure (markdown rules, scoped instructions), different filename and directory.

copilot-instructions.md is GitHub Copilot's repo-level instructions file.

.windsurfrules is Windsurf's version.

The good news: /init in Claude Code reads existing AGENTS.md, .cursorrules, .windsurfrules, and similar files when generating CLAUDE.md, so you don't start from scratch if you're migrating from another tool.¹ For multi-tool teams, AGENTS.md is the most portable choice (since CLAUDE.md can import it).

Auto memory: what Claude Code writes about itself

Auto memory is the second half of how Claude Code remembers your project, and it's often missed in CLAUDE.md guides. Worth knowing alongside CLAUDE.md.¹

Each project gets its own auto memory directory at ~/.claude/projects/<project>/memory/. The <project> is derived from your git repo, so all worktrees of the same repo share one auto memory directory. The entrypoint is MEMORY.md (an index file) plus optional topic files Claude creates as it works (debugging.md, api-conventions.md, etc.).

What Claude saves to auto memory: build commands it discovered, debugging patterns that worked, code style preferences inferred from your corrections, and workflow habits like user prefers running tests with -xvs. It doesn't save something every session. It decides based on whether the information would be useful later.

How it loads: at session start, the first 200 lines (or 25KB, whichever comes first) of MEMORY.md load into context.¹ Detailed topic files don't load at startup. Claude reads them on demand via its file tools when needed. This is how the system stays useful across long horizons without burning context every session.

You can audit and edit auto memory anytime with /memory. Both CLAUDE.md and auto memory show up as plain markdown you can open in your editor.

The practical takeaway: write what you want Claude to know in CLAUDE.md. Let auto memory accumulate what Claude figures out on its own. Don't try to use one for the other.

Where CLAUDE.md falls short

CLAUDE.md is excellent for what it covers. The honest assessment of where it doesn't:

Repo-scoped only. CLAUDE.md lives in your codebase. Open ChatGPT in a separate tab to brainstorm an architecture question and ChatGPT doesn't see your CLAUDE.md, your conventions, or any of the project context you've built up. The file is invisible outside Claude Code.

Static at session start. CLAUDE.md is loaded once, at the start of the session. If your project context changes mid-session, you have to manually update the file or wait for the next launch. It's not a live conversation memory.

Personal context lives elsewhere. CLAUDE.md is for project context. Your role, your preferences across all projects, what you said in a different repo last week. None of that belongs in a per-project CLAUDE.md. Auto memory captures some of it. Cross-tool memory captures more.

Context window cost. CLAUDE.md loads in full on every session. A 200-line file is a few thousand tokens that count against your context budget for every interaction. For Claude Pro users hitting weekly caps, this compounds.³

No portability across tools. Switch to Cursor and you re-encode the same context in .cursor/rules. Switch to ChatGPT and you paste the context in fresh. The AGENTS.md standard helps with code-context portability but not with conversational memory.

How to extend CLAUDE.md: cross-tool persistent memory

CLAUDE.md handles the repo-scoped, project-instruction layer well. The layer it doesn't handle is conversational continuity across tools.

A typical day for a multi-tool developer: morning coding in Claude Code, afternoon brainstorming in Claude chat, evening UI work in Cursor with help from ChatGPT for design. Each tool starts at zero conversational context. CLAUDE.md tells Claude Code about the repo, but Cursor still doesn't know what you decided in that Claude Code session. ChatGPT still doesn't know what design direction you settled on yesterday.

The fix is a memory layer that sits above the tool, not inside it. MemoryBase syncs conversations across ChatGPT, Claude, and Claude Code into a single persistent store, so context built in one tool follows you to the next when you switch. Your project's CLAUDE.md still does its job inside Claude Code. The cross-tool layer adds what CLAUDE.md was never designed to handle: the ongoing conversational context that lives outside any single repo. Letta and MemoryPlugin work the same category from different angles.

For deeper context on the cross-tool memory problem, see stop repeating context to AI. For the broader landscape of AI coding tools, see AI coding tools that actually help you ship in 2026.

Frequently asked questions

Where do I put CLAUDE.md in a project?

The most common location is ./CLAUDE.md in your repo root, or ./.claude/CLAUDE.md if you want it grouped with other Claude Code config. Both are loaded the same way. Commit it to version control so your team shares the same project context.¹ For personal preferences that shouldn't be committed, use ./CLAUDE.local.md (gitignored) instead.

How big should CLAUDE.md be?

Under 200 lines, per Anthropic's own guidance.¹ Longer files consume more context and reduce instruction adherence. If your rules are growing past 200 lines, split them into .claude/rules/*.md topic files, use path-scoped rules to load instructions only when Claude works on matching files, or move multi-step workflows into Claude Code skills instead of CLAUDE.md.

Does Claude Code read AGENTS.md?

No, not directly. Claude Code reads CLAUDE.md. The recommended pattern for repos that already have AGENTS.md is to import it from your CLAUDE.md using @AGENTS.md so both files reference the same source. A symlink also works on Linux and macOS.¹ Running /init in a repo with an existing AGENTS.md will read it and incorporate the relevant parts.

What's the difference between CLAUDE.md and auto memory?

CLAUDE.md is what you write: persistent instructions, rules, project facts. Auto memory is what Claude Code writes about itself as it works: build commands it discovered, debugging patterns, code style preferences. Both load at session start. CLAUDE.md is intentional. Auto memory is learned.¹

Can I have CLAUDE.md files at multiple levels in a monorepo?

Yes. Claude Code walks up the directory tree from your working directory and loads every CLAUDE.md it finds, concatenating them root-first into context.¹ Nested CLAUDE.md files in subdirectories are loaded on demand when Claude reads files in those directories. Use claudeMdExcludes in your settings to skip CLAUDE.md files from teams whose rules aren't relevant to your work.

How do I generate a starting CLAUDE.md?

Run /init inside Claude Code. It analyzes your codebase, infers build commands, test instructions, and project conventions, and writes a starting CLAUDE.md you can refine.¹ If a CLAUDE.md already exists, /init suggests improvements instead of overwriting. Setting CLAUDE_CODE_NEW_INIT=1 enables an interactive multi-phase flow that asks which artifacts to set up (CLAUDE.md, skills, hooks), explores your codebase with a subagent, and presents a reviewable proposal before writing any files.

How does CLAUDE.md interact with /compact?

Project-root CLAUDE.md survives compaction. After /compact, Claude Code re-reads it from disk and re-injects it into the session. Nested CLAUDE.md files in subdirectories don't re-inject automatically. They reload the next time Claude reads a file in that subdirectory.¹ If a conversation-only instruction disappears after compaction, that's the signal to write it into CLAUDE.md so it persists.

Should I check CLAUDE.md into version control?

Yes for the project file (./CLAUDE.md or ./.claude/CLAUDE.md): that's what makes it team-shared. No for CLAUDE.local.md: that's personal and belongs in .gitignore. The user-level file at ~/.claude/CLAUDE.md lives outside any repo so version control doesn't apply.

Can I import other files into CLAUDE.md?

Yes. Use the @path/to/file.md syntax to import additional files at session start. Both relative and absolute paths work, and relative paths resolve relative to the file containing the import.¹ Imported files can recursively import others, with a maximum depth of 5 hops. This is how you keep your CLAUDE.md short while still loading detailed content from elsewhere (your README, a coding-standards doc, a workflow guide).

Sources

1. Anthropic, How Claude remembers your project (Claude Code documentation). Retrieved 2026-05-11.
2. Linux Foundation (December 9, 2025), Linux Foundation Announces the Formation of the Agentic AI Foundation.
3. Anthropic, Use Claude Code with your Pro or Max plan. Retrieved 2026-05-11.