Guides

CLAUDE.md: what it is, what to put in it, and examples

Updated September 28, 2026

CLAUDE.md is a markdown file of instructions that Claude Code reads at the start of every session. You write it, and Claude treats it as context for the project: build commands, conventions and rules it cannot work out from the code. Keep it short, specific and checked into git.

What is a CLAUDE.md file?

Each Claude Code session starts with a fresh context window. Two things carry knowledge from one session to the next. CLAUDE.md files hold instructions you write. Auto memory holds notes Claude writes for itself from your corrections. Both load at the start of every session.

Anthropic’s docs describe CLAUDE.md as the place to write down what you would otherwise re-explain. Claude reads it and tries to follow it, but it is context, not enforced configuration. For something that must happen every time, such as a check before every commit, the docs point to hooks, which run as shell commands at fixed points. Permissions, hooks and the environment variables a project needs go in settings files such as .claude/settings.json, not in CLAUDE.md.

To start one, run /init. Claude reads 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.

Where does CLAUDE.md go?

CLAUDE.md can live in four places, each with its own reach:

Claude Code loads CLAUDE.md and CLAUDE.local.md from your working directory and every directory above it when it starts. Files in subdirectories load later, when Claude reads files in those directories.

Which CLAUDE.md wins?

None of them. Claude Code concatenates every file it finds instead of letting one override another. The order runs from broadest to most specific: managed, then user, then project. Across the directory tree, content runs from the root down to where you launched Claude, so the closest file is read last. In each directory, CLAUDE.local.md comes after CLAUDE.md.

Because nothing overrides, conflicts are yours to fix. The docs note that if two rules contradict each other, Claude may pick one arbitrarily. In a monorepo, the claudeMdExcludes setting skips other teams’ CLAUDE.md files by path or glob.

If your repository has an AGENTS.md for other coding tools, Claude Code reads it when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. To keep both, put @AGENTS.md at the top of your CLAUDE.md and add Claude-specific instructions below it.

CLAUDE.md imports

A CLAUDE.md can pull in other files with @path/to/file. Relative paths resolve from the file that contains the import, and imports can nest up to four hops deep. Paths inside backticks or code blocks are left alone.

Imports help you organize, but they do not save context: imported files load at launch with the CLAUDE.md that references them. The first time a project imports a file from outside your working directory, Claude Code asks you to approve it.

CLAUDE.md best practices

These come from Anthropic’s memory and best practices pages:

• Aim for under 200 lines per file. Longer files use more context and reduce adherence.
• Be specific enough to verify. “Run npm test before committing” instead of “Test your changes”.
• Use headers and bullets. Grouped sections are easier for Claude to follow than dense paragraphs.
• Test each line. Ask whether removing it would cause Claude to make mistakes. If not, cut it.
• Emphasize sparingly. If Claude keeps skipping one instruction, add “IMPORTANT” to that line alone. If many lines are emphasized, none stands out.
• Add to it when a correction repeats. When Claude makes the same mistake twice, or you type the same correction as last session, write it down.
• Move narrow instructions out. Multi-step procedures belong in skills, which load on demand. Rules for one part of the codebase belong in .claude/rules/, scoped to matching paths.
• Leave notes for people in HTML comments. Block-level HTML comments are stripped before Claude sees the file.

The best practices page sums up what to include and what to leave out:

How to check which CLAUDE.md files loaded

Run /context and look under Memory files. If a CLAUDE.md is not listed there, Claude cannot see it.

Run /memory to list your CLAUDE.md, CLAUDE.local.md and auto memory locations and open any of them in your editor. Asking Claude to “remember” something saves it to auto memory. To put it in CLAUDE.md, say “add this to CLAUDE.md” or edit the file yourself.

After /compact, Claude re-reads the project-root CLAUDE.md from disk, so its instructions survive. An instruction you only gave in conversation does not.

A CLAUDE.md example

Here is an illustrative CLAUDE.md for a small TypeScript API. Every line is something Claude could not reliably guess:

# Tally

A small invoicing API: Node 22, TypeScript, Fastify, Postgres.
Product overview: @README.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (start the database first with `docker compose up db`)
- One test file: `pnpm vitest run path/to/file.test.ts`
- Typecheck: `pnpm tsc --noEmit`. Run it after a series of changes.
- Migrations: `pnpm db:migrate`

## Code style
- ES modules only, no `require`
- Money is integer cents (`amountCents`), never floats

## Architecture
- Route handlers live in `src/routes/`. SQL lives only in `src/db/`.
- IMPORTANT: never edit a migration that is already on main. Add a new one.

## Workflow
- Branches: `feat/<name>` or `fix/<name>`
- Run the tests for the files you changed before you commit

## Gotchas
- Tests need `DATABASE_URL` from `.env.test`
- `src/generated/` is written by `pnpm codegen`. Do not edit it by hand.

A CLAUDE.md template

Copy this into ./CLAUDE.md, fill in what applies and delete the rest. The sections follow the “Include” column above.

# <Project name>

<One line: what it is and the main stack.>

## Commands
- Build:
- Test (one file):
- Lint and typecheck:

## Code style
- <Only rules that differ from the language's defaults>

## Architecture
- <Decisions Claude cannot see in the code, and why>

## Workflow
- <Branch naming, commit and PR conventions>

## Gotchas
- <Required env vars, generated files, things that break quietly>

What CLAUDE.md is not for

CLAUDE.md is a short file that loads in full every session, and it lives in one repository or in one home directory. That makes it and auto memory a poor fit for some knowledge:

• Knowledge other agents need. Your user file, local file and auto memory belong to Claude Code on one machine. An AGENTS.md shares project instructions with other coding tools, but only inside that repository.
• Knowledge for other machines and teammates. A project CLAUDE.md reaches teammates through git, but only for that repository. Auto memory is not shared across machines or cloud environments.
• Decisions and research that grow past a file. Anthropic’s own list says to leave out long explanations and information that changes often. Why you chose a vendor, what an investigation found, how three services fit together: that needs pages, not lines.

A shared wiki fits here. Dexio is a hosted wiki for AI agents: Claude Code and your other agents list, read, search, write, edit, move and link markdown pages over MCP, and you see the link graph and broken links at https://app.dexio.wiki. It is free for one person.

Keep CLAUDE.md short and point it at the wiki. Add a section like this to ~/.claude/CLAUDE.md for every project, or to a project’s CLAUDE.md if your whole team uses the wiki:

## Dexio wiki
- Keep notes in the Dexio wiki.
- Before you work on a topic, search the wiki with `search_pages` and read what is there.
- When you work out something that will be needed again, write it down.
  Update the page that exists instead of adding a duplicate.
- Pass the `base_version` from `read_page` when you change a page.
- Put "Claude Code" in the `agent` field on every change.

base_version stops one agent from overwriting another’s edit, and the agent field lets page_history show which agent wrote what. To connect, send Claude Code this message:

Connect yourself to my Dexio wiki. Read the steps with curl -s https://dexio.wiki/agents.md and follow them.

The Claude Code memory guide walks through setup and troubleshooting. For the same wiki in other agents, see the guides for Codex, Cursor, Hermes and OpenClaw, or read how an LLM wiki grows from linked pages. All guides are at https://dexio.wiki/guides.

Sources

• https://code.claude.com/docs/en/memory
• https://code.claude.com/docs/en/best-practices
• https://code.claude.com/docs/en/settings
• https://dexio.wiki/agents.md