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.
Show 1 more examples
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)
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').
User CLAUDE.md overrides project CLAUDE.md when they conflict.
Order is the opposite.
Project CLAUDE.md is loaded after user CLAUDE.md, so project rules take precedence on conflicts (later instructions in the prompt have stronger weight). A teammate's personal ~/.claude/CLAUDE.md cannot override a team rule, that's the whole point of the hierarchy.
Edit CLAUDE.md mid-session and Claude will pick up the changes immediately.
CLAUDE.md is loaded once at session start.
Changes require either a new session or, in newer Claude Code versions, the /init reload command. Mid-session edits are silent no-ops; this is why teams discover that "my new rule isn't being followed", they edited but didn't restart.
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.) |
| @import directives | Inlined into parent CLAUDE.md | Inherits parent's git status | Loaded with parent at session start | Modular rule decomposition |
| AGENTS.md (override file) | Project-wide; non-Claude tools | Yes (in git) | Read by Claude Code at startup | Cross-tool agent instructions (Codex, Cursor, Claude) |
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)?
Is the CLAUDE.md exceeding ~1500 tokens?
@import chunks: @import ./rules/testing.md, @import ./rules/security.md. Keeps the always-on context lean and lets you scope detailed rules to topics.Are you running other agentic tools (Codex, Cursor) on the same repo?
AGENTS.md file with cross-tool instructions and have CLAUDE.md include @AGENTS.md at the top. Single source of truth across tools.Question patterns
6 V2 questions wired to this concept. Tap an answer to check it instantly - you'll see whether it's right and why - then expand the full breakdown for the mental model and all four rationales.
Cross-task context like a vendor matrix path should live in: project Instructions or session messages?
Frequently asked
Showing 10 of 10 questions
@import ./rules/testing.md from CLAUDE.md reads ./rules/testing.md. URLs are not supported. Circular imports hang the loader, keep the import graph acyclic.apps/web/CLAUDE.md adds frontend-specific rules on top of root rules.paths: array in their frontmatter. Use imports for organization, glob rules for scoped policy.@AGENTS.md import inside CLAUDE.md, or directly if present. Use AGENTS.md for tool-agnostic rules; use CLAUDE.md for Claude-specific patterns (skills, hooks, MCP).settings.local.json is per-developer (your local permissions, env vars). The shared file is .claude/settings.json. Add settings.local.json to .gitignore; otherwise teammates inherit each other's accidental "allow all" permissions.@import ./shared-rules/*.md. Drift management is the #1 reason large orgs adopt the modular import pattern.CLAUDE.md exceeds recommended size) and continues. The model still receives it but with degraded attention to any single rule. The fix is decomposition: move detailed rules to .claude/rules/*.md with path globs, keep the main CLAUDE.md as a high-level index of imports.