CLAUDE.md Guide: Write Project Memory That Claude Follows

Every Claude Code session starts with an empty context window. CLAUDE.md is how you stop re-explaining your build command, folder layout and “never touch the migrations folder” rule every single morning.

This guide covers where CLAUDE.md files live, how they load, what belongs in them, and five ready-to-adapt templates. Every behaviour below is checked against the official Claude Code memory documentation as of October 2026.

What CLAUDE.md is (and isn’t)

CLAUDE.md is a plain Markdown file of instructions that Claude Code reads at the start of every session. It sits alongside auto memory, the notes Claude writes for itself based on your corrections.

	CLAUDE.md	Auto memory
Who writes it	You	Claude
Contains	Instructions and rules	Learnings and preferences
Loaded	Every session	Every session (first 200 lines or 25KB of MEMORY.md)

One thing to internalise early: Claude treats CLAUDE.md as context, not enforced configuration. It is delivered as a user message after the system prompt. Clear, specific instructions are followed reliably; vague or contradictory ones are not. Anything that must happen every time belongs in a hook or a permission rule.

Where CLAUDE.md files live

Claude Code supports four scopes, loaded from broadest to most specific:

Scope	Location	Use it for	Shared with
Managed policy	macOS /Library/Application Support/ClaudeCode/CLAUDE.md, Linux/WSL /etc/claude-code/CLAUDE.md, Windows C:\Program Files\ClaudeCode\CLAUDE.md	Company standards, compliance reminders	Everyone on the machine
User	~/.claude/CLAUDE.md	Your personal preferences in every project	Only you
Project	./CLAUDE.md or ./.claude/CLAUDE.md	Build commands, architecture, team conventions	Team, via git
Local	./CLAUDE.local.md	Your sandbox URLs, test data	Only you (add to .gitignore)

How they load

• Claude Code loads CLAUDE.md and CLAUDE.local.md from your working directory and every directory above it. Files are concatenated, not overridden, ordered from the filesystem root down, so instructions closer to where you launched Claude are read last.
• Within a directory, CLAUDE.local.md is appended after CLAUDE.md.
• CLAUDE.md files in subdirectories load on demand, once Claude reads or edits a file in that subdirectory.
• Block-level HTML comments are stripped before injection, so you can leave notes for humans without spending tokens.
• After /compact, the project-root CLAUDE.md is re-read from disk and re-injected. Nested files reload on demand.

To see what actually loaded, run /context and look under Memory files. To open and edit any of these files, run /memory.

Generate a starter with /init

In a project without instructions, run:

/init

Claude analyses the codebase and writes a CLAUDE.md with build commands, test instructions and conventions it discovers. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it. It also pulls relevant parts from Cursor rules (.cursor/rules/, .cursorrules) and Copilot instructions (.github/copilot-instructions.md).

For a more guided flow, set CLAUDE_CODE_NEW_INIT=1 before running /init. It then asks which artifacts to set up (CLAUDE.md files, skills and hooks), explores the codebase with a subagent, asks follow-up questions and shows a proposal before writing files.

Treat the generated file as a first draft. The next section is about cutting it down.

What to put in CLAUDE.md

Anthropic’s guidance is to write down what you would otherwise re-explain. Add an entry when:

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

Include: build, test and lint commands; conventions that differ from tool defaults; where things live when it isn’t obvious; known pitfalls; “always” and “never” rules.

Leave out: anything Claude can derive from the code (full directory trees, dependency lists, generic architecture overviews), multi-step procedures (make those skills), and instructions that only matter for one part of the repo (make those path-scoped rules).

Write instructions Claude can verify

Vague	Specific
Format code properly	Use 2-space indentation
Test your changes	Run npm test before committing
Keep files organized	API handlers live in src/api/handlers/

Keep it short

The docs recommend under 200 lines per CLAUDE.md file. Longer files use more context and reduce adherence, and if two instructions contradict each other Claude may pick either one. Claude Code warns at startup and in /status when an instruction file is over the recommended length.

Two built-in helpers keep files tidy:

• /doctor runs a setup checkup and proposes trims for a checked-in CLAUDE.md, cutting content Claude can derive from the code.
• /doctor prompt-audit looks for outdated instructions, references to files or commands that no longer exist, and contradictions across your instruction files, then proposes edits without changing anything until you approve.

Imports with @path

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

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

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

• Relative paths resolve from the file containing the import.
• Imports can nest up to four hops deep.
• Wrap a path in backticks to mention it without importing it.
• Imports that resolve outside the project trigger a one-time approval dialog.

Imports help organisation but don’t reduce context cost: imported files load together with the CLAUDE.md that references them.

Path-scoped rules in .claude/rules/

For larger projects, split instructions into topic files under .claude/rules/. All .md files there are discovered recursively. Rules without frontmatter load at launch like .claude/CLAUDE.md. Rules with a paths field only load when Claude reads, writes or edits a matching file:

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

# API rules

- Validate all request input with zod
- Return errors in the standard { error: { code, message } } shape
- Add OpenAPI comments to every handler

This is the single best way to keep a big repo’s root CLAUDE.md short. Personal rules for every project go in ~/.claude/rules/. You can also symlink a shared rules directory into several projects.

One caveat: path-scoped rules load into message history, so compaction summarises them away until a matching file is touched again. If a rule must survive compaction, keep it unscoped or move it to the root CLAUDE.md.

CLAUDE.md and AGENTS.md

If your repo already has an AGENTS.md for other coding agents, recent versions of Claude Code can read it directly:

Your repo has	Claude reads
AGENTS.md and no CLAUDE.md/CLAUDE.local.md	AGENTS.md
AGENTS.md plus a CLAUDE.md	CLAUDE.md only
A CLAUDE.md that imports @AGENTS.md	Both, via the import

The cleanest pattern for mixed-tool teams is one shared file plus a thin Claude-specific layer:

@AGENTS.md

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

You can change the default in /config under Project instructions (for example, claude-md-and-agents-md to always read both). Our Claude Code vs Codex comparison covers why this matters when a team uses more than one agent.

Five CLAUDE.md templates

These are starting points. Delete anything Claude would figure out on its own, and add the gotchas only your team knows.

1. Next.js (App Router, TypeScript)

# Project
Next.js App Router app, TypeScript strict, pnpm.

## Commands
- Dev: pnpm dev
- Typecheck: pnpm tsc --noEmit
- Test: pnpm vitest run
- Lint: pnpm lint

## Conventions
- Server Components by default; add "use client" only when needed
- Data fetching in server components or route handlers, never in useEffect
- Use the cn() helper from src/lib/utils for class names
- Never edit files in src/components/ui/ by hand (generated by shadcn)

## Before finishing
Run typecheck and tests. Fix failures before reporting done.

2. Python / FastAPI

# Project
FastAPI service, Python 3.12, uv for dependencies, PostgreSQL via SQLAlchemy 2.

## Commands
- Install: uv sync
- Run: uv run fastapi dev app/main.py
- Test: uv run pytest -q
- Lint/format: uv run ruff check --fix . && uv run ruff format .

## Conventions
- Pydantic v2 models in app/schemas/, ORM models in app/models/
- All DB access through repository functions in app/repositories/
- New endpoints need a test in tests/api/
- Migrations: uv run alembic revision --autogenerate; never edit applied migrations

3. Go service

# Project
Go 1.23 HTTP service, standard library router, sqlc for queries.

## Commands
- Build: go build ./...
- Test: go test ./... -race
- Lint: golangci-lint run
- Generate queries after editing SQL: sqlc generate

## Conventions
- Return wrapped errors: fmt.Errorf("doing x: %w", err)
- No global state; pass dependencies through constructors
- Table-driven tests with t.Run subtests
- Do not edit files in internal/db/ by hand (sqlc output)

4. Django

# Project
Django 5 monolith, Python 3.12, Poetry, PostgreSQL, Celery for background jobs.

## Commands
- Run: poetry run python manage.py runserver
- Test: poetry run pytest
- Migrations: poetry run python manage.py makemigrations && poetry run python manage.py migrate

## Conventions
- Business logic in services.py per app, not in views or models
- Use select_related/prefetch_related for any queryset rendered in a list
- Settings come from environment variables via django-environ; never hardcode secrets
- Celery tasks must be idempotent

5. Monorepo (root file)

# Monorepo
pnpm workspaces + Turborepo. Apps in apps/, shared packages in packages/.

## Commands
- Everything: pnpm turbo run build test lint
- One package: pnpm --filter <name> test

## Rules
- Shared types live in packages/types; never duplicate them in apps
- Each app has its own CLAUDE.md with app-specific commands
- Changes to packages/ui need a changeset: pnpm changeset

In a monorepo, keep the root file short and let each apps/*/CLAUDE.md load on demand when Claude works there. If other teams’ files get picked up, the claudeMdExcludes setting (for example in .claude/settings.local.json) skips them by glob.

Troubleshooting

• Instruction ignored? Run /context and confirm the file appears under Memory files. Then make the instruction more specific and check for contradictions in nested files and .claude/rules/.
• Subdirectory file not listed? That’s expected: it loads on demand, and a Loaded line appears when it does.
• Instruction lost after compaction? It was probably given only in chat. Add it to CLAUDE.md. See our context management guide for what survives /compact.
• Must never be broken? Convert it to a PreToolUse hook or a permissions.deny rule. Our permission modes guide explains how rules interact with modes.

CLAUDE.md in your Claude kit

CLAUDE.md is the foundation of any Claude kit: facts and conventions here, procedures in skills, isolated work in subagents, enforcement in hooks. If you’re unsure which mechanism a given instruction belongs in, our skills vs subagents vs hooks guide walks through the decision.