If you use Claude Code for development, you may notice that you repeatedly have to explain the same project structure, coding conventions, commands, and workflows.
That's exactly what CLAUDE.md is designed to solve.
CLAUDE.md gives Claude Code persistent instructions that it can use across sessions. Instead of repeating project-specific information every time you start Claude Code, you can write that information once and let Claude load it automatically.
This guide explains what CLAUDE.md is, where it lives, how Claude Code loads it, how to create one, what to put inside it, how to organize large projects, and what to do when Claude doesn't appear to follow your instructions.
Quick Answer
CLAUDE.md is a Markdown file containing instructions and persistent project context for Claude Code.
You can use it for things such as:
- Build and test commands
- Coding conventions
- Project architecture
- File locations
- Naming conventions
- Development workflows
- Security requirements
- Common mistakes Claude should avoid
For most projects, start with a CLAUDE.md in the project root.
You can also use ~/.claude/CLAUDE.md for personal instructions that apply across projects, and .claude/rules/ for more specialized instructions.
A good CLAUDE.md should be short, specific, structured, and easy to verify. Anthropic recommends targeting fewer than about 200 lines per file because longer instructions consume more context and can reduce adherence.
If Claude isn't following your instructions, first check whether the file was actually loaded rather than immediately rewriting it.
What Is CLAUDE.md?
CLAUDE.md is a plain Markdown file that provides persistent instructions to Claude Code.
Think of it as an onboarding document for your AI coding teammate.
A human developer joining your project might need to know:
- How to run the application
- How to run tests
- Where important files are located
- Which coding conventions the team follows
- How authentication works
- Which files shouldn't be modified
- How changes should be verified
Claude Code needs much of the same context.
Instead of explaining these things in every conversation, you can put them into CLAUDE.md.
For example:
# Project Instructions ## Commands - Run tests with `npm test` - Start development with `npm run dev` - Run linting with `npm run lint` ## Conventions - Use TypeScript for new code - API handlers live in `src/api/handlers/` - Add tests for new API endpoints ## Security - Never commit API keys - Use test credentials locally
Claude Code reads this information as context when starting sessions.
CLAUDE.md Is Not a Hard Configuration File
One important detail is often misunderstood.
CLAUDE.md provides guidance, not an absolute enforcement mechanism.
Claude Code receives the instructions as context and tries to follow them. However, there is no guarantee that Claude will obey every instruction perfectly, particularly when instructions are vague or conflicting.
That's why writing clear, concrete rules is important.
CLAUDE.md vs Auto Memory
Claude Code has two different mechanisms for carrying information across sessions:
| CLAUDE.md | Auto Memory |
|---|---|
| Written by you | Written by Claude |
| Contains instructions and rules | Contains learned patterns and notes |
| Used for project conventions | Used for things Claude learns |
| Can cover project, user, or organization context | Per-repository memory |
| You control the instructions | Claude accumulates learnings automatically |
A simple way to remember the difference is:
CLAUDE.md = what you tell Claude to remember
Auto Memory = what Claude learns while working
Use CLAUDE.md for stable instructions you explicitly want Claude to follow, such as coding standards, workflows, architecture decisions, and important project rules.
Auto Memory can capture things Claude learns from corrections, debugging sessions, and recurring project patterns.
You can inspect and manage Auto Memory using:
/memory
This distinction is useful because you don't need to turn CLAUDE.md into a giant database of every fact Claude might learn.
Where CLAUDE.md Files Live
Claude Code supports several instruction scopes.
| Scope | Location | Typical Purpose |
|---|---|---|
| Managed | Organization-controlled locations | Organization-wide policies |
| User | ~/.claude/CLAUDE.md | Your personal preferences |
| Project | ./CLAUDE.md | Team-shared project instructions |
| Project | ./.claude/CLAUDE.md | Alternative project location |
| Local | ./CLAUDE.local.md | Personal project-specific instructions |
For most developers, the two most important locations are:
~/.claude/CLAUDE.md
and:
./CLAUDE.md
The first is useful for personal preferences across projects.
The second is normally where you put instructions that belong to a particular repository.
What About CLAUDE.local.md?
CLAUDE.local.md is still supported for personal, project-specific instructions.
If you use it, add it to .gitignore so your personal instructions aren't committed to the repository.
For example:
CLAUDE.local.md
If you work across multiple Git worktrees and want the same personal instructions available in each worktree, Anthropic recommends importing a file from your home directory instead:
@~/.claude/my-project-instructions.md
That's particularly useful because a gitignored CLAUDE.local.md exists only in the worktree where it was created.
How CLAUDE.md Loading Actually Works
This is one of the most important parts to understand.
Claude Code doesn't simply look for one CLAUDE.md file.
It walks up the directory tree from your current working directory and loads applicable CLAUDE.md and CLAUDE.local.md files.
For example, suppose your project looks like this:
project/ ├── CLAUDE.md ├── backend/ │ ├── CLAUDE.md │ └── api/ │ └── CLAUDE.md └── frontend/
If you start Claude Code inside:
project/backend/api/
Claude can load the applicable instruction files from the directory hierarchy.
These files are concatenated into context rather than one file simply overriding another. Instructions closer to your current working directory appear later in the hierarchy. CLAUDE.local.md is appended after CLAUDE.md at the same directory level.
What About Nested CLAUDE.md Files?
CLAUDE.md files inside subdirectories are handled differently.
They aren't all loaded immediately at session startup. Claude Code can load them when it reads files in those directories.
This is particularly useful for large repositories and monorepos where different areas need different instructions.
How to Create Your First CLAUDE.md
The easiest way to start is with Claude Code's built-in:
/init
Start Claude Code in your project:
claude
Then run:
/init
Claude Code analyzes your project and can generate a starting CLAUDE.md containing things such as:
- Build commands
- Test commands
- Project structure
- Coding conventions it can discover
If a CLAUDE.md already exists, /init suggests improvements instead of simply overwriting it.
After generating the file, review it yourself.
Claude can discover many mechanical details automatically, but it cannot necessarily know your team's business rules, architectural preferences, or every project-specific mistake you want to prevent.
How to Check Whether CLAUDE.md Loaded
This is an important troubleshooting step.
If Claude doesn't appear to follow your instructions, don't immediately assume the instructions are bad.
First verify that Claude actually loaded the file.
Use:
/context
The /context command helps you inspect what's consuming the current context window, including loaded memory files and other context sources.
You can also use:
/memory
to inspect loaded CLAUDE.md files, CLAUDE.local.md files, rules, and Auto Memory.
If your CLAUDE.md isn't being loaded, rewriting the instructions won't solve the underlying problem.
CLAUDE.md Example
Here's a practical example for a fictional Node.js billing API:
# Project: Internal Billing API ## Commands - Install dependencies: `npm install` - Start development server: `npm run dev` - Run tests: `npm test` - Run lint: `npm run lint` ## Project Structure - API handlers: `src/api/handlers/` - Database code: `src/db/` - Tests: `tests/` ## Coding Conventions - Use TypeScript for new code. - Use 2-space indentation. - Prefer existing utility functions over creating duplicates. - Add tests for new API endpoints. ## Security - Never commit secrets or API keys. - Stripe uses test mode locally. - Never use production credentials during local development. ## Verification - Run relevant tests after changing API behavior. - Run the linter before completing a task.
The key is that every instruction has a reason.
Avoid filling the file with generic statements such as:
Write clean code.
Instead, tell Claude what "clean" means in your project.
How to Write Instructions Claude Actually Follows
Anthropic's guidance emphasizes three major principles:
1. Keep It Short
A useful target is under 200 lines per CLAUDE.md file.
CLAUDE.md content consumes context alongside your conversation, files, tool results, and command output. As the context gets crowded, performance and instruction adherence can decline.
Don't treat CLAUDE.md as a place to document your entire company.
Keep high-value information there.
2. Be Specific
Weak:
- Format code properly. - Test everything. - Keep files organized.
Better:
- Use 2-space indentation. - Run `npm test` before completing changes. - API handlers belong in `src/api/handlers/`.
The second version gives Claude something concrete to act on and verify.
3. Keep Instructions Consistent
If multiple CLAUDE.md files or rules give conflicting instructions, Claude may not behave as expected.
For example:
CLAUDE.md: Use npm.
and:
.claude/rules/package.md: Use pnpm.
creates unnecessary ambiguity.
Review your instruction files periodically and remove outdated or conflicting rules.
What Should NOT Go in CLAUDE.md?
More instructions don't automatically mean better results.
Avoid putting unnecessary information into the file.
Don't Put Secrets in CLAUDE.md
Never add:
- API keys
- Passwords
- Access tokens
- Private credentials
- Production secrets
Use environment variables or appropriate secret-management systems instead.
Don't Add Generic Instructions
Statements such as:
Always be professional. Write high-quality code. Think carefully.
are usually less useful than concrete project requirements.
Prefer:
- Never modify generated files. - Run `npm test` after changing authentication. - Ask before modifying production configuration.
Don't Duplicate Tooling Rules
If Prettier already handles formatting and ESLint already enforces a rule, you don't necessarily need to describe every formatting rule again in CLAUDE.md.
Use CLAUDE.md for information that tooling cannot fully communicate.
Don't Turn It Into a Giant Documentation File
Long architecture documents, specifications, and guides don't necessarily belong inside CLAUDE.md.
Keep the important instruction in CLAUDE.md and reference detailed documentation when needed.
Build Context, Not Just Better Prompts
One of the most useful Claude Code habits is to think about context, not just prompt wording.
Instead of:
Fix the authentication bug.
give Claude a specific task:
Investigate the authentication bug in `src/auth/`. First inspect the existing session flow and related tests. Identify the root cause before changing code. Keep the existing API behavior. After the fix, run the authentication tests and report the results.
This gives Claude:
- A goal
- A scope
- Relevant files
- Constraints
- A verification requirement
Claude Code can inspect files itself, so you don't need to paste your entire codebase into every prompt.
Anthropic's best-practice guidance recommends providing specific context, including relevant files, constraints, examples, and expected outcomes.
Explore → Plan → Implement → Verify
For larger tasks, don't always ask Claude to immediately start changing files.
A better workflow is:
Step 1: Explore
Ask Claude to understand the relevant code first.
Analyze the authentication system. Explain how login and sessions currently work. Do not modify any files.
Step 2: Plan
Then ask Claude for an implementation plan:
I want to add Google OAuth. Identify the files that need to change and create an implementation plan. Include security concerns and testing requirements.
For complex tasks, Plan Mode can separate exploration and planning from implementation.
Step 3: Implement
After reviewing the plan:
Implement the approved plan. Add tests for the OAuth callback.
Step 4: Verify
Don't accept "Done" as proof.
Ask Claude to verify the implementation:
Run the relevant test suite. Fix any failures. Show me the commands you ran and their results.
Verification can use tests, builds, linters, scripts, or other checks appropriate to the task. Anthropic specifically recommends giving Claude a reliable way to verify its work.
For a tiny change such as renaming a variable, full planning may be unnecessary. Planning is most useful when the task is complex, affects multiple files, or involves an unfamiliar part of the codebase.
Importing Other Files with @
You can keep your CLAUDE.md organized by importing other files.
For example:
@README.md @package.json @docs/git-workflow.md
Or:
# Additional Instructions - Git workflow: @docs/git-instructions.md
Both relative and absolute paths are supported.
Relative paths are resolved relative to the file containing the import.
Imports can also reference other imported files, with a maximum depth of five hops.
Important: Imports Don't Automatically Reduce Context
Imports are useful for organization, but they aren't a magic context-saving mechanism.
Imported content is expanded and loaded into the context at launch.
So this:
@docs/large-guide.md
can still consume context just like putting the content directly into CLAUDE.md.
If your goal is to reduce context usage, consider path-scoped rules or Skills for information that doesn't need to be loaded all the time.
CLAUDE.md vs AGENTS.md
Claude Code reads:
CLAUDE.md
not:
AGENTS.md
If your repository already contains an AGENTS.md used by another coding agent, you don't need to duplicate everything.
You can import it:
@AGENTS.md ## Claude Code - Use plan mode for changes under `src/billing/`. - Run the billing tests before completing changes.
This allows Claude Code to use the shared instructions while still letting you add Claude-specific rules.
A symlink can also work:
ln -s AGENTS.md CLAUDE.md
On Windows, however, symlink creation may require Administrator privileges or Developer Mode, so the @AGENTS.md approach can be simpler.
Organizing Large Projects with .claude/rules/
A single CLAUDE.md can become difficult to maintain as a project grows.
For larger repositories, use:
your-project/
├── CLAUDE.md
└── .claude/
└── rules/
├── testing.md
├── security.md
├── frontend.md
└── backend.md
Each file can focus on one topic.
For example:
--- paths: - "src/api/**/*.ts" --- # API Rules - Validate all external input. - Use the standard API error format. - Add tests for new endpoints.
Path-scoped rules are useful because specialized instructions only need to enter context when Claude is working with matching files.
This makes .claude/rules/ particularly useful for large projects and monorepos.
CLAUDE.md vs Skills vs Hooks
These features solve different problems.
CLAUDE.md
Use it for instructions that should apply broadly and regularly:
Use TypeScript. Run tests after API changes. Follow this project architecture.
Skills
Use Skills for specialized workflows or procedures that don't need to be loaded into every session.
For example:
Create a release.
could invoke a specialized release workflow.
Hooks
Use hooks when something needs deterministic execution at a specific point in Claude Code's lifecycle.
For example:
Run a security check after specific file changes.
CLAUDE.md can tell Claude to perform the check, but a hook can provide actual lifecycle-based enforcement.
The distinction is simple:
CLAUDE.md = guidance
Skills = specialized workflows
Hooks = automated lifecycle actions
Anthropic's documentation recommends choosing the mechanism based on whether information should always be present, loaded for a specialized workflow, or executed automatically.
Troubleshooting: Claude Isn't Following My CLAUDE.md
If Claude seems to ignore your instructions, work through these checks.
1. Verify That the File Loaded
Run:
/context
and inspect the context information.
You can also run:
/memory
to inspect loaded instruction files and Auto Memory.
2. Check the File Location
Make sure the CLAUDE.md is located somewhere Claude Code actually loads.
For a project, the simplest option is:
project/ └── CLAUDE.md
3. Make the Instruction More Specific
Change:
Write good tests.
to:
Every new API endpoint must have at least one success test and one validation-error test. Run `npm test` after modifying API handlers.
4. Check for Conflicting Instructions
Review:
- Parent CLAUDE.md files
- Project CLAUDE.md
- CLAUDE.local.md
- .claude/rules/
- Imported files
Conflicting instructions can produce unpredictable behavior.
5. Use Enforcement When Guidance Isn't Enough
If an action absolutely must happen, don't rely solely on CLAUDE.md.
For deterministic requirements, consider hooks, permissions, or CI.
For example:
CLAUDE.md: Run tests before completing a task.
is guidance.
A CI pipeline that blocks a pull request when tests fail is enforcement.
What Happens to CLAUDE.md After /compact?
A common question is whether Claude forgets CLAUDE.md after a long session or context compaction.
Project-root CLAUDE.md instructions survive /compact because Claude Code can re-read the file from disk and inject it back into the session.
However, nested CLAUDE.md files may not be immediately re-injected after compaction. They can load again when Claude reads files in their relevant directories.
This is another reason to keep important, always-needed instructions in the appropriate root CLAUDE.md rather than only mentioning them in conversation.
Can You Use CLAUDE.md Outside the Terminal?
Yes.
CLAUDE.md is a Claude Code project instruction mechanism rather than a terminal-only configuration.
The same project instructions can be relevant when using Claude Code through supported surfaces such as the terminal, IDE integrations, or desktop workflows.
How to Maintain a Good CLAUDE.md
Don't try to create a perfect CLAUDE.md on day one.
Start small.
Add an instruction when:
- Claude makes the same mistake repeatedly.
- A code review identifies something Claude should have known.
- You type the same correction more than once.
- A new developer would need the same information.
- A project workflow is easy for Claude to misunderstand.
Remove information when it becomes outdated or is already enforced by tooling.
The goal isn't to create the longest CLAUDE.md.
The goal is to create the highest-signal CLAUDE.md.
Frequently Asked Questions
Project CLAUDE.md files provide persistent project context and are loaded according to Claude Code's directory and configuration rules.
Yes. Claude Code can load applicable CLAUDE.md files from the directory hierarchy, while files in subdirectories can be loaded when Claude works in those areas.
Anthropic recommends targeting under 200 lines per file. Larger files consume more context and can reduce instruction adherence.
No.
CLAUDE.md contains instructions you write, while Auto Memory stores learnings Claude records during work.
Not by itself. Imported files are loaded into context, so imports primarily help with organization. Use path-scoped rules or Skills when specialized information doesn't need to be present all the time.
Claude Code reads CLAUDE.md, not AGENTS.md. If you already use AGENTS.md, you can import it from CLAUDE.md with @AGENTS.md.
First verify that the file is loaded with /context or inspect the loaded instruction files with /memory. Then check its location, remove conflicting rules, and rewrite vague instructions as specific, verifiable rules. If you need deterministic enforcement, use hooks, permissions, or CI instead.
For a new project, /init is a good starting point because Claude can inspect the codebase and generate project-specific instructions. You should then review and refine the file with information Claude couldn't discover on its own.
Conclusion
CLAUDE.md is one of the most useful configuration mechanisms in Claude Code because it lets you turn repeated explanations into persistent project instructions.
A strong setup doesn't require a huge instruction file.
Start with:
- Create a project CLAUDE.md.
- Use /init if you want Claude to generate a starting point.
- Add project-specific commands, conventions, architecture, and rules.
- Keep instructions short and specific.
- Use /context and /memory to verify what Claude loaded.
- Use @imports when you need to organize related instructions.
- Use .claude/rules/ for specialized or path-specific rules.
- Use Skills for specialized workflows.
- Use hooks, permissions, or CI when you need deterministic enforcement.
- Update CLAUDE.md whenever you discover a recurring mistake.
The best CLAUDE.md isn't the one with the most instructions.
It's the one that gives Claude the right context at the right time with the least unnecessary noise.