On this page
TLDR
CLAUDE.md is persistent project memory loaded automatically by Claude Code. A three-level hierarchy (user → project → directory) lets you set global defaults, team standards, and per-directory rules. Project-level files are version-controlled and shared. Use @import to keep CLAUDE.md modular.
What it is
CLAUDE.md is a configuration file for Claude Code that defines project rules, conventions, and architectural decisions. It's not a .gitignore or a README, it's a working set of instructions that Claude reads every time it edits code or runs a command. The hierarchy has three levels: user (~/.claude/CLAUDE.md, your personal defaults), project (.claude/CLAUDE.md or root CLAUDE.md, shared rules), and path-specific (.claude/rules/*.md with glob frontmatter, rules for specific files).
The content is free-form Markdown but structured: stack info, test commands, code-style rules, key architectural decisions, gotchas, and @import directives that pull in modular rule files. Claude parses it as plain text, there's no schema validation, so mistakes in naming or structure cause silent ignores. The real power is reusability: rules travel with the code (version-controlled in .claude/), every teammate sees them on git clone, and new team members onboard faster.
Path-specific rules use YAML frontmatter with a paths glob array. When Claude edits a file matching the glob (e.g. **/*.test.tsx), that rule file auto-loads alongside the project CLAUDE.md. This enables scoped rule enforcement without drowning the main CLAUDE.md in per-file details. A testing rule file specifies pytest/Jest conventions, coverage thresholds, naming, all loaded only when you touch a test file.
Production misuse centers on scope creep (main CLAUDE.md becomes 500 lines of every possible rule) and rule inheritance traps (team expects user rules to apply but they don't, user rules are personal, project rules are shared). A contributor clones the repo, uses their personal style from ~/.claude/CLAUDE.md, and produces inconsistent code. The fix is always: put team rules in `.claude/CLAUDE.md`, never in user files.
How it works
When Claude Code starts, it loads CLAUDE.md in order: (1) reads user ~/.claude/CLAUDE.md (personal defaults); (2) reads project root .claude/CLAUDE.md or root CLAUDE.md (shared); (3) while editing a file, checks all .claude/rules/*.md files, tests the paths glob against the filename, and loads matches. All loaded content is concatenated and injected as context into Claude's system prompt. The result is a layered set of rules: personal, then project, then path-scoped.
When a .claude/rules/*.md file contains @import ./subdir/rules/testing.md, Claude resolves the import and inlines that file's content. This prevents the main CLAUDE.md from exploding; rules live in modular files and compose via import. Circular imports are not detected and will hang the load. A production gotcha if you @import a file that imports its parent. Keep the import graph acyclic.
Path-specific rules are scoped via glob frontmatter. A testing rule file declares paths: ["**/*.test.tsx", "**/*.spec.ts"]. When you create or edit a file matching either glob, the rule auto-loads. Token-efficient: irrelevant rules don't load, keeping context focused. A migration rule (paths: ["migrations/*.sql"]) only loads when you touch SQL files.
Claude reads CLAUDE.md once at startup, not continuously. Changes require a session restart (or a manual reload command in newer versions). This is a UX tradeoff: rules are stable within a session (no surprise mid-conversation changes), but editing CLAUDE.md does not take effect immediately. Plan edits before sessions, not during.
Where you'll see it
Open-source repo onboarding
New contributor clones the repo. Project CLAUDE.md auto-loads: stack, test commands, code-style rules, key decisions. Saves a 30-min onboarding email per contributor. Rules travel with the code; nobody works from outdated docs.
Monorepo with subteam directories
Frontend team has rules in app/.claude/CLAUDE.md (component patterns, testing conventions); backend has api/.claude/CLAUDE.md (db migration discipline, error handling). Root CLAUDE.md holds shared rules. Editing inside app/ loads frontend rules; inside api/ loads backend rules.
Personal vault across many projects
Solo dev keeps personal preferences in ~/.claude/CLAUDE.md (preferred indent, commit message format). Each project repo has its own root CLAUDE.md with stack details. Switching projects: project rules change automatically; personal style stays consistent.
Code examples
# Project: PrecisionCare Navigator
## Stack
- Python 3.11 + FastAPI + Postgres
- React 19 + ShadCN + Tailwind
- Claude Opus for medical NER
- AWS ECS + RDS, region us-east-1
## Commands
- Dev: `make dev` (FastAPI :8000, React :3000)
- Test: `pytest -v --cov=app`
- Lint: `ruff check . && black --check .`
- Deploy: `make deploy ENV=staging`
## Code style
- 4-space Python (Black), 2-space React (Prettier)
- Type hints on every function (mypy strict)
- Named exports only
- Server actions for mutations; route handlers for queries
## Key decisions
- All patient data encrypted at rest and in transit
- Never log PII (mask in middleware)
- Async background work via Celery + Redis (not asyncio in FastAPI)
## Modular rules
@import ./rules/testing.md
@import ./rules/healthcare-compliance.md
@import ./rules/api-design.md
## Don't
- Add new endpoints without a corresponding test
- Mock the database in integration tests
- Commit secrets (use .env.example as the template)
---
paths: ["tests/**/*.py", "**/test_*.py"]
---
# Test Rules, auto-loads only when editing test files
## Naming
- Files: test_<module>.py (mirrors source file path)
- Functions: test_<function>_<scenario>
- Fixtures live in conftest.py at the deepest applicable level
## Patterns
- Use pytest.parametrize for data-driven cases
- Each test asserts ONE behavior (fail message tells you what)
- Mock external services with respx (httpx) or responses (requests)
## Anti-patterns
- Tests that depend on execution order
- Tests that read `os.environ` without monkeypatch
- Snapshot tests checked in without explicit PR review
- `time.sleep` in tests (use freezegun)
## Coverage
- Floor 85% per module
- Branch coverage on policy-critical files (auth, refund, billing)
Looks right, isn't
Each row pairs a plausible-looking pattern with the failure it actually creates. These are the shapes exam distractors are built from.
Put all team rules in ~/.claude/CLAUDE.md so they live with each developer.
User-level files are personal and not in the repo. Team rules belong in project-level CLAUDE.md (root, committed). Otherwise new team members miss them.
Document every framework convention exhaustively in CLAUDE.md.
CLAUDE.md is appended to every prompt. Bloated files burn tokens and dilute attention. Keep it concise (~1500 tokens). Use @import for modular detail; link to long-form docs.
Embed API keys in CLAUDE.md so Claude has them on every session.
CLAUDE.md is committed to git. Secrets leak. Use environment variables and reference them in CLAUDE.md by name (e.g., 'OPENROUTER_API_KEY required in env').
Side-by-side
| Mechanism | Scope | Shared? | Loaded when | Best for |
|---|---|---|---|---|
| ~/.claude/CLAUDE.md | All your projects | No (personal) | Every session | Personal preferences, indent style |
| ./CLAUDE.md (project) | One repo | Yes (in git) | Every session in repo | Stack, commands, team standards |
| .claude/rules/*.md | Path-glob scoped | Yes (in git) | When editing matching files | Per-folder conventions (tests, api/) |
| Skills (.claude/skills/) | Task-scoped | Yes (in git) | When task description matches | Reusable workflows (PR review, etc.) |
Decision tree
Does this rule apply to everyone on the team?
Does the rule apply only to certain file types or directories?
paths: [...]. Loads on demand.Is it a reusable workflow (e.g., PR review process)?
Question patterns
A teammate's PRs use a different code style than yours. They have rules in `~/.claude/CLAUDE.md` but not in the repo. Fix?
.claude/CLAUDE.md (project root, version-controlled). User-level rules are personal; only project rules are shared via git. Team standards belong in the repo.You add a rule to `.claude/CLAUDE.md` mid-session. Claude doesn't follow it. Why?
Your testing rule file sits in `.claude/rules/testing.md` but doesn't auto-load when editing test files. What's missing?
paths glob. Make sure it matches your file paths exactly. Try paths: ["**/*.test.tsx", "**/*.spec.ts"] for broad coverage.You have `@import ./shared.md` in two CLAUDE.md files, and `shared.md` has `@import ../main.md`. Claude Code hangs on load. Why?
A new contributor follows the README but writes code that violates project conventions. They don't read CLAUDE.md. Architectural fix?
Your project root `CLAUDE.md` is 1,500 lines and Claude's responses are getting slower. Why?
.claude/rules/*.md with paths globs. Keep root CLAUDE.md to ~300 lines of universal team rules.A path-scoped rule file's `paths: ["src/**/*.ts"]` matches but the rules don't apply to a file in `src/lib/utils.ts`. What's wrong?
** matches multiple directory levels, so src/**/*.ts should match src/lib/utils.ts. If not, check for typos in the glob or restart Claude Code.You want different rules for `api/` (backend) and `app/` (frontend). Best structure?
.claude/rules/backend.md with paths: ["api/**"], .claude/rules/frontend.md with paths: ["app/**"]. Keep root CLAUDE.md for shared rules. Each rule auto-loads only when relevant.