CLAUDE.md files give Claude Code persistent instructions for a project, your personal workflow or your organization. They load at session start as context, not enforced configuration. Rules can be split into .claude/rules/ files, optionally scoped to paths.
What it does
Where CLAUDE.md runs and what it adds, from its documentation
Loads project instructions from ./CLAUDE.md or ./.claude/CLAUDE.md, shared via version control
Supports user-level ~/.claude/CLAUDE.md and private ./CLAUDE.local.md
Supports managed-policy CLAUDE.md for organization-wide instructions
Imports other files with @path/to/file syntax (max depth four hops)
Splits instructions into .claude/rules/*.md, with optional paths frontmatter for file-scoped rules
/init generates a starting CLAUDE.md from the codebase
When to use it
Good fit
You re-explain the same build commands or conventions each session
A team wants shared coding standards in version control
An organization needs company-wide policies applied to all users
Not for
Guaranteed enforcement: docs say to use a PreToolUse hook to block actions
Multi-step procedures or single-area instructions: use a skill or path-scoped rule
How to install CLAUDE.md
You need: Claude Code
Create ./CLAUDE.md or ./.claude/CLAUDE.md in the project root
Add build/test commands, conventions and project layout, targeting under 200 lines
Or run /init to generate a starting file
Run /context and check the Memory files list to confirm it loaded
Add CLAUDE.local.md to .gitignore for personal preferences
Configuration example (from the official docs)
See @README for project overview and @package.json for available npm commands for this project.
# Additional Instructions
- git workflow @docs/git-instructions.md
Permissions and security
Security notes from the maintainers
Treated as context, not enforced configuration; use hooks to guarantee behavior
Managed policy CLAUDE.md cannot be excluded by users
Review the source before granting an agent access to credentials or production systems. We document what the maintainers state; we do not audit code.
Limitations
Longer files consume more context and reduce adherence; target under 200 lines
Contradicting instructions may be resolved arbitrarily
Imports do not reduce context cost, imported files also load at launch
