$ skilldirectory
— zsh — registry.skilldirectory.dev
skill libraryblogguidesabout

home / blog / claude code

CLAUDE.md: How to Write One That Claude Code Actually Follows (2026 Guide)

Quick answer: A CLAUDE.md file is a plain Markdown file Claude Code reads at the start of every session. Put build commands, conventions and "always do X" rules in it, keep each file under about 200 lines, and run /init to generate a first draft.

Treat it as guidance, not enforcement. If something must happen every time, use a hook instead.

Every Claude Code session starts with an empty context window. Claude does not remember that your team uses pnpm, that tests live in tests/, or that you never touch the billing module without review. A CLAUDE.md file is where you write those facts down once so you stop retyping them.

This guide covers what to put in the file, where Claude looks for it, and the mistakes that make it ignored. Everything below was checked against Anthropic's memory documentation on November 19, 2026. Details such as version numbers change, so check the docs if you run an older version.

What is a CLAUDE.md file?

CLAUDE.md is a Markdown file that gives Claude persistent instructions for a project, for you personally, or for your whole organization. You write it in plain text, and Claude reads it at the start of each session.

It is one of two memory systems in Claude Code. The other is auto memory, where Claude writes its own notes from your corrections.

CLAUDE.mdAuto memory
Who writes itYouClaude
What it holdsInstructions and rulesLearnings and patterns
ScopeProject, user or organizationPer repository
LoadedEvery sessionEvery session (first 200 lines or 25KB)

Use CLAUDE.md when you want to steer Claude's behavior. Let auto memory handle the small stuff Claude picks up from your corrections.

Where Claude looks for CLAUDE.md files

Files can live in several places, and each has a different audience. The docs list them from broadest to most specific:

ScopeLocationShared with
Managed policy/Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux and WSL), C:\Program Files\ClaudeCode\CLAUDE.md (Windows)Everyone in an organization
User~/.claude/CLAUDE.mdJust you, all projects
Project./CLAUDE.md or ./.claude/CLAUDE.mdYour team, through git
Local./CLAUDE.local.mdJust you, this project

A few details matter in practice:

  • Claude loads CLAUDE.md and CLAUDE.local.md from your working directory and every directory above it. Files are combined, not overridden.
  • Files in subdirectories load on demand, when Claude reads files in those folders.
  • Add CLAUDE.local.md to your .gitignore. It is for personal notes such as sandbox URLs.
  • For large monorepos where other teams' files get picked up, the claudeMdExcludes setting lets you skip them.

What to put in it

Anthropic's guidance is to treat CLAUDE.md as the place you write down what you would otherwise re-explain. Add a line when:

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

Good entries are specific and checkable:

  • "Use 2-space indentation" instead of "Format code properly."
  • "Run npm test before committing" instead of "Test your changes."
  • "API handlers live in src/api/handlers/" instead of "Keep files organized."

Here is a small example for a US startup's web app:

# Project notes

## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Lint: `pnpm lint` (must pass before any commit)

## Conventions
- TypeScript strict mode, 2-space indentation
- API handlers live in `src/api/handlers/`
- Currency is stored in cents; display in US dollars

## Rules
- Never edit files in `migrations/` without asking first
- Use American English in user-facing copy

Notice what is missing: long explanations, history, and anything Claude can read straight from the code. The docs' own /doctor check trims exactly that kind of content, such as directory layouts and dependency lists that Claude can derive from the repository.

Start with /init

You do not have to write the first version from scratch. Run /init in Claude Code and it analyzes your codebase and generates a starting 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.

Then edit it by hand. The most valuable lines are the ones Claude could not discover on its own, like "we deploy on Fridays only after QA signs off."

Keep it short

This is the rule people skip. Anthropic recommends targeting under 200 lines per CLAUDE.md file. Longer files use more context and can reduce how well Claude follows them. Claude Code even shows a warning at startup and in /status when a file runs long.

If your file is growing, you have three options:

  • Move instructions to path-scoped rules. Put them in .claude/rules/ with a paths field so they load only when Claude touches matching files.
  • Move procedures to a skill. A multi-step workflow that matters only sometimes belongs in a skill, which loads when needed. See what Claude skills are and how to create your own.
  • Cut it. If Claude would do the right thing without the line, delete the line.

Imports help with organization but not with size. The docs are explicit that imported files still load into context at launch, so splitting one file into five does not save space.

Imports and the rules folder

CLAUDE.md can pull in other files with an @ path:

See @README for the project overview and @package.json for npm commands.
- Git workflow: @docs/git-instructions.md

Relative paths resolve from the file that contains the import, and imports can chain up to four hops deep. Writing a path in backticks keeps it literal instead of importing it.

For bigger projects, use .claude/rules/. Each Markdown file covers one topic, such as testing.md or security.md. A rule with no paths field loads every session. A rule with a paths field loads only when Claude reads, writes or edits a matching file:

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Every endpoint validates its input
- Use the standard error response format

Personal rules that apply to every project can go in ~/.claude/rules/.

What about AGENTS.md?

Many repos already have an AGENTS.md for other coding agents. According to the docs, Claude Code can read it directly (version 2.1.277 or later), but with a catch: by default it reads AGENTS.md only when there is no CLAUDE.md in your working directory or above it.

If you want both, create a short CLAUDE.md that imports the other file:

@AGENTS.md

That way Claude Code picks up the same instructions your other agent tools use. For how those tools handle skills, see our guides to Cursor skills and Codex skills.

CLAUDE.md is guidance, not a guardrail

Anthropic is direct about this: Claude treats CLAUDE.md as context, not enforced configuration. The content arrives as a user message after the system prompt, so there is no guarantee of strict compliance, especially with vague or conflicting instructions.

That has a practical consequence. Do not rely on CLAUDE.md for anything with real consequences, like keeping secrets out of commits. For rules that must hold every time, the docs point to hooks, which run as shell commands at fixed points and apply no matter what Claude decides. Our guide to Claude Code hooks shows how.

For a side-by-side view of hooks, skills and subagents, read subagents vs skills vs hooks vs commands vs plugins.

Troubleshooting

If Claude seems to ignore your file, work through this list:

  1. Run /context and check the Memory files list to confirm your file actually loaded.
  2. Make instructions more specific. Concrete beats vague.
  3. Look for contradictions between your user file, project file and rules. Claude may pick one arbitrarily.
  4. Use /memory to open and edit the loaded files.
  5. Run /doctor prompt-audit to have Claude flag outdated or conflicting instructions. The docs say it needs Claude Code v2.1.283 or later.

A final tip from the docs: block-level HTML comments (<!-- note -->) are stripped before the file is sent to Claude, so you can leave maintainer notes without spending context.

FAQ

What is CLAUDE.md? A Markdown file of persistent instructions that Claude Code reads at the start of every session. It can be personal, shared with your team, or managed for an organization.

Where should I put CLAUDE.md? For a team project, put it at the repository root as ./CLAUDE.md or in ./.claude/CLAUDE.md and commit it. For personal preferences across all projects, use ~/.claude/CLAUDE.md.

How long should a CLAUDE.md be? Anthropic recommends under 200 lines per file. Move the rest into .claude/rules/ files or skills.

Does Claude read AGENTS.md? Yes, in recent versions, but by default only when no CLAUDE.md exists. Import it from a CLAUDE.md if you want both.

Is CLAUDE.md enforced? No. It shapes behavior but does not guarantee it. Use hooks or permission settings for hard rules.

Should I commit CLAUDE.md to git? Commit the project file so your team shares it. Keep CLAUDE.local.md out of version control.

Sources: How Claude remembers your project (Anthropic documentation).