What Is CLAUDE.md? How to Write One for Claude Code (Examples, Imports, Best Practices)

If Claude Code keeps forgetting your build command, your coding style or the one folder it must never touch, you need a CLAUDE.md file. It is a plain Markdown file that Claude Code reads at the start of every session, so you write your project rules once instead of repeating them in every chat.

This guide explains what CLAUDE.md is, where each file goes, how to write one that Claude actually follows (with a copy-ready template), how imports, rules and AGENTS.md work, how it differs from auto memory, and how to fix it when Claude ignores your instructions. Everything is checked against Anthropic’s current Claude Code docs.

What CLAUDE.md Is

Every Claude Code session starts with a fresh context window. CLAUDE.md is how you carry knowledge from one session to the next. You write it in plain Markdown, and Claude reads it at the start of every session.

Anthropic’s docs suggest treating CLAUDE.md as the place for anything you would otherwise re-explain. Add to it when:

• Claude makes the same mistake a second time.
• A code review catches something Claude should have known about the codebase.
• You type the same correction you typed last session.
• A new teammate would need the same context to be productive.

Keep it to facts Claude needs in every session: build and test commands, conventions, project layout and firm rules. Multi-step procedures belong in a Claude Skill, and rules for one part of the code belong in a path-scoped rule (covered below).

Where CLAUDE.md Files Go

You can have several CLAUDE.md files at once. They load from broadest to most specific, and all of them are added to context together.

Files in the folders above your working directory load at launch. CLAUDE.md files inside subfolders load on demand, when Claude first reads or edits a file in that subfolder.

How to Create Your First CLAUDE.md

1. Open your project in a terminal and start Claude Code with claude. New to it? See how to install Claude Code.
2. Run /init. Claude analyses your codebase and writes a CLAUDE.md with the build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it.
3. Optional interactive setup: set the environment variable CLAUDE_CODE_NEW_INIT=1 before running /init. It then asks whether to set up CLAUDE.md files, skills and hooks, and can create a personal CLAUDE.local.md for you.
4. Edit the draft. Remove anything Claude can work out from the code itself, and add the things it cannot discover: team habits, gotchas and “never do this” rules.
5. Check it loaded. Run /context all and look under Memory files.
6. Commit it so your whole team (and every Claude session) uses the same rules.

A Copy-Ready CLAUDE.md Template

Here is a lean starting point for a typical web project. Replace the examples with your own facts and delete sections you do not need.

# Project: Acme Shop

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (http://localhost:3000)
- Tests: `pnpm test` (run before every commit)
- Lint and format: `pnpm lint --fix`

## Layout
- API handlers live in `src/api/handlers/`
- Shared UI components live in `src/components/ui/`
- Database migrations live in `db/migrations/` (never edit old ones)

## Conventions
- TypeScript strict mode; no `any`
- 2-space indentation, single quotes
- Use pnpm, never npm or yarn
- Name React components in PascalCase, hooks as useSomething

## Rules
- Do not touch files in `vendor/`
- Ask before adding a new dependency
- Write a test for every bug fix

## Gotchas
- API tests need a local Redis on port 6379
- `src/legacy/` uses CommonJS; do not convert it

See @README.md for the product overview.

This file is about 30 lines, specific and easy to check. That is the target.

How to Write Instructions Claude Follows

The docs give clear guidance: write instructions that are concrete enough to verify, and keep files short and organised.

• Size: aim for under 200 lines per file. Longer files use more context and reduce adherence.
• Structure: group instructions under Markdown headings and bullets. Dense paragraphs are harder to follow.
• Consistency: if two instructions contradict each other, Claude may pick either one. Review your files now and then.
• Hidden notes: block-level HTML comments like <!-- note for humans --> are stripped before Claude sees the file, so you can leave maintainer notes for free.
• Audit: recent versions (v2.1.283 or later) offer /doctor prompt-audit, which looks for outdated, broken or contradictory instructions and proposes edits.

A lean CLAUDE.md also saves tokens on every message. See our guide to reducing Claude Code token usage.

Imports With @path

CLAUDE.md can pull in other files with @path/to/file. Imported files are loaded alongside the CLAUDE.md that references them.

See @README for the project overview and @package.json for npm commands.

# Additional instructions
- git workflow @docs/git-instructions.md

• Relative paths resolve from the file that contains the import, not your working directory.
• Imports can be nested up to four hops deep.
• Paths with spaces need a backslash before each space, for example @Design\ Docs/api.md.
• To mention a path without importing it, wrap it in backticks.
• Imports from outside your project (like @~/.claude/my-notes.md) trigger a one-time approval dialog in that project.

Imports help you organise, but they do not save context: imported files load in full at launch.

Split Big Files With .claude/rules/

For larger projects, put topic files in .claude/rules/, such as testing.md, api-design.md or security.md. All .md files there are discovered recursively.

The real power is path-scoped rules. Add a paths field in YAML frontmatter, and the rule only loads when Claude works with matching files:

---
paths:
  - "src/api/**/*.ts"
---
# API rules
- Validate every input
- Use the standard error response format

Personal rules for every project go in ~/.claude/rules/. Rules without a paths field load at launch, just like CLAUDE.md.

How CLAUDE.md Files Load

• Claude Code loads CLAUDE.md and CLAUDE.local.md from your working directory and every folder above it.
• Files are combined, not overridden. Content closer to where you launched Claude is read last.
• CLAUDE.md files in subfolders load once Claude reads or edits a file in that subfolder.
• Folders added with --add-dir do not load their CLAUDE.md unless you set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1.
• In big monorepos, skip other teams’ files with the claudeMdExcludes setting (it cannot exclude a managed file).
• A CLAUDE.md over 4 MiB is skipped entirely.

CLAUDE.md and AGENTS.md

Many repos already have an AGENTS.md for other coding agents. Claude Code v2.1.277 and later can read it directly:

To keep one shared file for every tool, put @AGENTS.md in a short CLAUDE.md next to it. You can also change the Project instructions setting in /config to read both files.

CLAUDE.md vs Auto Memory

Auto memory is on by default in local sessions. Toggle it in /memory, turn it off per project with "autoMemoryEnabled": false, or set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Saying “remember to use pnpm” saves to auto memory; saying “add this to CLAUDE.md” writes it to the file.

CLAUDE.md vs Skills, Hooks and Settings

Running Claude Code in scripts? Our guide to claude -p headless mode shows how CLAUDE.md applies there too.

Troubleshooting

My Take

CLAUDE.md is the single cheapest way to make Claude Code better on your project. Run /init, cut the draft down to the 20 to 50 lines that really matter, and add a line every time you catch yourself repeating a correction.

Treat it like a README for your AI teammate: short, concrete and kept up to date. Anything that must happen every time belongs in a hook, not in CLAUDE.md.

FAQ

What is CLAUDE.md?

A Markdown file of instructions that Claude Code loads at the start of every session, such as build commands, coding conventions and project rules.

Where should I put CLAUDE.md?

Put team rules in ./CLAUDE.md or ./.claude/CLAUDE.md at your project root, personal rules for every project in ~/.claude/CLAUDE.md, and private project notes in ./CLAUDE.local.md.

How do I create a CLAUDE.md automatically?

Run /init inside Claude Code. It analyses your codebase and writes a starter file, or suggests improvements if one already exists.

How long should CLAUDE.md be?

Anthropic recommends under 200 lines per file. Shorter, specific files are followed more reliably and use less context.

Does Claude always follow CLAUDE.md?

Not strictly. It is context, not enforcement. Use hooks for steps that must always run and permission settings to block actions.

What is the difference between CLAUDE.md and CLAUDE.local.md?

CLAUDE.md is shared with your team through git. CLAUDE.local.md holds your personal notes for the project and should be added to .gitignore.

Does Claude Code read AGENTS.md?

Yes, from v2.1.277, when no CLAUDE.md or CLAUDE.local.md is present. Otherwise import it with @AGENTS.md in your CLAUDE.md.

How do I check which CLAUDE.md files are loaded?

Run /context all and look under Memory files, or open /memory to see and edit every memory file.

Sources

• Claude Code docs: How Claude remembers your project (CLAUDE.md, rules, AGENTS.md, auto memory)
• Claude Code docs: Skills
• Claude Code docs: Hooks guide
• Claude Code docs: CLI reference