How to write a CLAUDE.md that Claude Code follows

What goes in a CLAUDE.md, where the files live, how imports and .claude/rules work, and the writing habits that make Claude Code follow your instructions.

· 5 min read

A CLAUDE.md is a Markdown file Claude Code reads at the start of every session: your build commands, conventions and rules, written once instead of re-typed each time. Claude treats it as context, not as enforced configuration, so how you write it decides how well it is followed. Short, concrete, verifiable instructions win; long essays get ignored.

#What is a CLAUDE.md, and where does it go?

Each session starts with a fresh context window. CLAUDE.md files are one of two ways knowledge survives between sessions (the other is auto memory, notes Claude writes about your corrections). Claude Code reads these files:

ScopeLocationShared with
Organization (managed)/Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on LinuxEveryone on the machine
You, all projects~/.claude/CLAUDE.mdOnly you
Project./CLAUDE.md or ./.claude/CLAUDE.mdThe team, via git
You, this project./CLAUDE.local.md (add it to .gitignore)Only you

Files are concatenated, not overridden: Claude Code loads the ones in your working directory and every directory above it, from the root down, so the file closest to where you launched is read last. CLAUDE.md files in subdirectories load on demand, when Claude reads or edits a file there. That makes a packages/api/CLAUDE.md a good place for rules that only matter in that package.

#How do you generate a first one?

Run /init inside a session. Claude scans the codebase and writes a CLAUDE.md with the build commands, test instructions and conventions it finds. If one already exists, it suggests improvements instead of overwriting it.

Treat the output as a draft. Delete anything Claude could work out by reading the code, and add what it could not: the reason behind an odd convention, the command that actually runs your integration tests, the directory nobody should touch.

To confirm a file loaded, run /context all and look at the list of memory files. /memory opens the files for editing.

#What should go in it?

Write down what you would otherwise re-explain. The official guidance is to add a line when Claude makes the same mistake twice, when a code review catches something it should have known, or when you type the same correction as last session.

A solid project file usually has four short blocks:

# Commands
- Install: `pnpm install`
- Test one file: `pnpm vitest run path/to/file.test.ts`
- Lint and typecheck before finishing: `pnpm lint && pnpm typecheck`

# Layout
- API handlers live in `src/api/handlers/`, one file per route
- Shared types in `src/types/`; never import from `src/legacy/`

# Conventions
- TypeScript strict; no `any` without a comment saying why
- Use the `Result` helper in `src/lib/result.ts`, do not throw in handlers

# Don't
- Don't edit files under `generated/`; run `pnpm codegen` instead
- Don't commit directly to `main`

#How do you write instructions it actually follows?

Make each line verifiable. The docs give the contrast: "Use 2-space indentation" beats "Format code properly"; "Run npm test before committing" beats "Test your changes"; "API handlers live in src/api/handlers/" beats "Keep files organized". If you could not check a line in a code review, Claude cannot reliably follow it either.

Keep it short. The target is under 200 lines per file. Longer files use more context and adherence drops. If you cannot cut, move material elsewhere (see below).

Structure it. Headers and bullets are easier to follow than paragraphs.

Remove contradictions. If two lines disagree, Claude may pick either. This is easy to cause with a user file, a project file and a rules folder all saying slightly different things. /doctor prompt-audit asks Claude to look for outdated or conflicting instructions across your instruction files and proposes edits without applying them.

Do not use it as a lock. A CLAUDE.md line like "never run rm -rf" is a request. For anything that must never happen, use a permission deny rule or a PreToolUse hook; see permission modes.

#How do imports and rules keep the file small?

Reference other files with @ and Claude Code loads them alongside:

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

# Git workflow
@docs/git-instructions.md

Relative paths resolve from the file that contains the import, and imports can nest four levels deep. Note that imports organize a long file but do not reduce its context cost: imported content is loaded too. To mention a path without importing it, wrap it in backticks.

For real savings, split by topic into .claude/rules/. Each Markdown file there is loaded at launch, unless it declares paths:

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

# API rules
- Validate every input with the shared schema
- Return errors in the standard envelope

A rule with paths only loads when Claude touches a matching file. Personal rules for every project go in ~/.claude/rules/.

A related choice: if a block is a multi-step procedure (how to cut a release, how to add a migration), it belongs in a skill, which loads only when needed, not in a file that is read every time.

#What about notes for humans and several folders?

Block-level HTML comments (<!-- note for maintainers -->) are stripped before the content reaches Claude, so you can leave notes without spending context.

By default, CLAUDE.md files from folders you add with --add-dir are not loaded. Set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 and they are, which matters for a project split over several repositories.

If your repository uses an AGENTS.md for other tools, Claude Code can read it in place of CLAUDE.md; the docs describe how the two combine.

#A quick checklist

  • Under 200 lines, headers and bullets
  • Commands to build, test and lint are written out in full
  • Every rule is checkable
  • No duplicates between user, project and rules files
  • Hard guarantees live in settings or hooks, not prose
  • Big procedures moved to skills, area-specific rules to .claude/rules/
  • Revisit it whenever Claude repeats a mistake

New to the tool? Start with the beginner's guide.

#In Relais

In Relais a group is one project made of several folders. The first folder is where Claude starts and the others are added as extra directories, and Relais sets CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 so the CLAUDE.md of every folder loads. That suits a project spread over a frontend, a backend and a shared repo. See features.

Claude Code,
better organized.

$14.99 a month, everything included. Mac and Linux, on your Claude Pro or Max plan. Cancel any time.