How to Write a CLAUDE.md File in 2026: A Practical Guide

A CLAUDE.md file is a plain Markdown file that Claude Code reads automatically at the start of every session, giving the model persistent instructions it can't infer from your code: build commands, conventions, architecture, and the "always do X" rules you're tired of repeating. Put it at your project root, keep it under ~200 lines, and fill it with specific, verifiable instructions rather than a wiki dump. This guide covers where the file lives, what belongs in it, how to import and reuse existing docs, and how to generate and trim it with Claude Code's own commands.

It's worth being precise up front, because most write-ups blur two things Claude Code keeps separate: the CLAUDE.md you write, and the auto memory Claude writes for itself. We'll cover both, and why the file you hand-write is still the highest-leverage thing in the setup.

What is a CLAUDE.md file?

A CLAUDE.md file is the instruction layer for Claude Code. At session start, Claude Code loads it into the context window and delivers it as a message Claude reads before it touches your code. Anthropic's docs describe it as the place to "write down what you'd otherwise re-explain" — the tech stack, how to run tests, naming conventions, and architectural decisions a new teammate would need. It's Markdown, so headings and bullet lists are all the structure you need.

One nuance the docs are explicit about: CLAUDE.md is context, not enforced configuration. Claude reads it and tries to follow it, but there's no hard guarantee, especially for vague or contradictory rules. Anything that must happen at a fixed point — "run the linter before every commit" — belongs in a hook, not a line of prose. That distinction shapes everything below.

Where to put your CLAUDE.md file

CLAUDE.md can live in several places, and Claude Code loads them in order from broadest to most specific, concatenating all of them rather than overriding. A project instruction lands in context after a user one, so the more specific file is read last.

Scope	Location	Purpose	Shared with
Managed policy	/etc/claude-code/CLAUDE.md (Linux/WSL); /Library/Application Support/ClaudeCode/CLAUDE.md (macOS); C:\Program Files\ClaudeCode\CLAUDE.md (Windows)	Org-wide standards IT deploys	Everyone on the machine
User	~/.claude/CLAUDE.md	Your personal preferences across all projects	Just you
Project	./CLAUDE.md or ./.claude/CLAUDE.md	Team-shared project rules	Your team, via git
Local	./CLAUDE.local.md	Private per-project notes (gitignore it)	Just you, this project

Claude Code reads CLAUDE.md from your working directory and every directory above it, so in a monorepo a root file and a package-level file both apply. Files in subdirectories below you load on demand, only when Claude reads files there. Run /context in a session and check the Memory files list to confirm what actually loaded — this is the fastest way to debug "Claude is ignoring my CLAUDE.md," which is almost always a file that isn't in a loaded location.

What to put in a CLAUDE.md file (and what to leave out)

The best CLAUDE.md is a short list of concrete, checkable facts. Include build and test commands, the project layout, conventions that differ from tool defaults, and the mistakes you've had to correct more than once. Write "Run npm test before committing" and "API handlers live in src/api/handlers/", not "test your changes" or "keep files organized" — specificity is what Claude can actually act on.

What to leave out matters just as much. Don't make the model do a linter's job; if you have ESLint or Prettier, let them enforce style and keep it out of the file. Skip anything Claude can read straight from the codebase — directory trees, dependency lists, and architecture overviews are exactly what Claude Code's /doctor checkup will propose trimming. Task-specific, multi-step procedures belong in a Claude Code skill that loads on demand, and anything path-specific ("all API endpoints need input validation") belongs in a .claude/rules/ file scoped with a paths: glob, so it only enters context when Claude touches matching files. A good rule of thumb: if an entry isn't useful in every session, it shouldn't be in CLAUDE.md.

Keep it short: CLAUDE.md is a token budget, not a wiki

Because CLAUDE.md loads on every turn, every line costs context. Anthropic's stated target is under 200 lines per file; longer files consume more context and measurably reduce how closely Claude follows them (a file over 4 MiB is skipped entirely). The context-engineering team at HumanLayer pushes further, keeping their own file under 60 lines, and cites the practical ceiling that frontier models reliably follow only ~150–200 instructions — and Claude Code's own system prompt already spends roughly 50 of those before you've written a word.

The mental model that helps: treat CLAUDE.md as RAM, and skills, rules, and reference docs as disk. You don't load the whole hard drive on boot. Put the always-true rules in CLAUDE.md and point to everything situational with a link or an import. If the file is creeping past 200 lines, that's the signal to split, not to keep scrolling.

Import other files and reuse your AGENTS.md

CLAUDE.md can pull in other files with @path/to/file syntax. Imports expand into context at launch, paths can be relative or absolute, and they can nest up to four levels deep. Wrap a path in backticks when you want to mention it without importing it.

The most useful case is interop. Claude Code reads CLAUDE.md, not AGENTS.md — so if your repo already uses the cross-tool AGENTS.md standard, don't duplicate it. Create a CLAUDE.md that imports it and add any Claude-specific notes below:

@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

A symlink (ln -s AGENTS.md CLAUDE.md) works too if you don't need Claude-specific additions. One caveat: an import that resolves outside your working directory triggers a one-time approval dialog, a deliberate guard against files other people commit to a shared repo.

Generate and maintain it with /init, /memory, and /doctor

You don't have to start from a blank file. Run /init and Claude analyzes the codebase and writes a starting CLAUDE.md with the build commands, test steps, and conventions it discovers; if one already exists, it suggests improvements instead of overwriting. It even reads existing Cursor and Copilot rule files and folds the relevant parts in. Treat the output as a draft — the real value is the handful of instructions Claude couldn't infer, which you add afterward.

From there, /memory lists and opens every memory file across scopes, and /doctor proposes trims for a checked-in CLAUDE.md, cutting derivable content while keeping the pitfalls and rationale. When you tell Claude "add this to CLAUDE.md," it edits the file directly. And because the file is just Markdown in version control, changes go through code review like any other part of the repo — which is how the CLAUDE.md that drives our own publishing pipeline here at TechRiseUps stays honest over time.

CLAUDE.md vs auto memory

Recent Claude Code versions added a second, automatic memory system, and it's easy to conflate with CLAUDE.md. The split is clean: you write CLAUDE.md (instructions and rules); Claude writes auto memory (things it observes about your preferences and corrections). Auto memory lives at ~/.claude/projects/<project>/memory/, with a MEMORY.md index whose first 200 lines (or 25KB) load every session and topic files that load on demand.

Keep them in their lanes. CLAUDE.md is your requirements; auto memory is what Claude has learned about how you work. Claude deliberately skips saving anything your CLAUDE.md already states, so a tight CLAUDE.md actually makes auto memory cleaner too. You can browse, edit, or delete any of it through /memory — it's all plain Markdown.

FAQ

What should I put in my CLAUDE.md file? Build and test commands, project structure, conventions that differ from defaults, and the corrections you find yourself repeating. Keep each entry specific and verifiable. Leave out code style (use a linter), task-specific procedures (use skills), and anything Claude can read from the code.

How do I write the perfect CLAUDE.md file? There isn't a perfect one, but the reliable pattern is short and specific: under 200 lines, concrete instructions, grouped under Markdown headings, with situational detail pushed into imports, rules, or skills. Start with /init, then trim with /doctor and refine as Claude makes mistakes.

Can Claude create the CLAUDE.md file for me? Yes. Running /init generates a starting CLAUDE.md from your codebase, and you can ask Claude to add or edit entries at any time. You still own the final file — hand-craft the rules it couldn't discover on its own.

How is CLAUDE.md different from AGENTS.md? AGENTS.md is a cross-tool open standard; CLAUDE.md is the file Claude Code actually loads. Claude Code does not read AGENTS.md directly, so if you maintain one, import it into CLAUDE.md with @AGENTS.md or symlink the two rather than keeping duplicate files.

Why is Claude ignoring my CLAUDE.md? Usually the file isn't in a loaded location — run /context and check Memory files. If it loaded but Claude still strays, make the instruction more specific, remove contradictions, and for anything that must always run, move it to a hook instead of relying on prose.

Sources

• Claude Code docs — How Claude remembers your project: official reference for CLAUDE.md locations, load order, imports, size limits, /init, /memory, and auto memory.
• HumanLayer — Writing a good CLAUDE.md: context-engineering guidance on length, progressive disclosure, and the ~150–200 instruction ceiling.