Where to Put CLAUDE.md in Claude Code (and How to Write It)

In short: Claude Code does not pick one CLAUDE.md. It finds every one that applies and concatenates them into context, from broadest scope to narrowest. Put personal rules in ~/.claude/CLAUDE.md, team rules in the project root, and keep each file short and specific. Checked against the official memory docs on 2026-10-12.

Where CLAUDE.md files live

The first question most people have is where the file should go. Each location has a different scope.

  • User (global):~/.claude/CLAUDE.md. Loaded in every project. Use it for personal preferences such as commit message style or which package manager you prefer.
  • Project:./CLAUDE.md or ./.claude/CLAUDE.md. Committed to git and shared with the team. Build commands, architecture notes and coding conventions belong here.
  • Local (personal, per project):./CLAUDE.local.md. Lives in the project root but goes in .gitignore, so only you see it. Good for local dev server URLs or personal test data.
  • Subdirectory: for example src/api/CLAUDE.md or packages/web/CLAUDE.md. These are not loaded at session start. Claude loads one only after it reads, writes or edits a file in that directory.
  • Managed policy (organizations):/Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux and WSL, C:\Program Files\ClaudeCode\CLAUDE.md on Windows. IT teams deploy it with MDM or similar tools, and individual users cannot exclude it.

Load order and how files merge

A common misunderstanding: the closest file does not win. Claude Code loads CLAUDE.md and CLAUDE.local.md from your working directory and every directory above it, and concatenates all of them. The order runs from broad to narrow:

  1. Managed policy
  2. User ~/.claude/CLAUDE.md
  3. Project ./CLAUDE.md or ./.claude/CLAUDE.md
  4. Local ./CLAUDE.local.md

If you start Claude Code in foo/bar/, then foo/CLAUDE.md appears in context before foo/bar/CLAUDE.md. Instructions closest to where you launched are read last. Within one directory, CLAUDE.local.md is appended after CLAUDE.md.

To see what actually loaded, run /context in a session and look at the Memory files list. If your file is not there, Claude cannot see it.

Splitting rules in a monorepo

If your frontend and backend follow different conventions, do not cram everything into one root file.

project-root/
├── CLAUDE.md              # overall architecture, shared rules
├── frontend/
│   └── CLAUDE.md          # React conventions, component layout
└── backend/
    └── CLAUDE.md          # API design rules, DB migrations

frontend/CLAUDE.md only enters context when Claude touches files under frontend/, so backend work stays free of frontend noise. For finer control, put rule files in .claude/rules/ and scope them with a paths frontmatter field:

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

# API rules

- Every endpoint validates its input
- Errors use the standard response format

This rule only loads when Claude works on matching TypeScript files under src/api/, so you are not paying for it in every session.

What to write in CLAUDE.md

One test works well: write down what you keep having to explain again. Add a line when Claude makes the same mistake twice, when a code review reveals a project convention Claude did not know, or when a new teammate would need the same explanation.

Include:

  • Build, test and lint commands you actually run (npm run build, pytest -x, make lint)
  • A short architecture overview: what each directory is for
  • Conventions that differ from tool defaults: indentation, naming, import order
  • Explicit instructions for things Claude often gets wrong
  • Hard prohibitions, such as files that must not be edited by hand

Leave out:

  • Directory listings Claude can discover by reading the repo
  • Dependency lists already in package.json
  • Long background explanations

Verifiable sentences beat vague ones. "Use 2-space indentation" and "run npm test before committing" get followed far more reliably than "write clean code."

One thing to keep in mind: CLAUDE.md is context, not enforced configuration. The docs say Claude treats it as guidance, and that to block an action regardless of what Claude decides you should use a PreToolUse hook. If something must happen every time, such as a script before each commit, use a hook instead.

Keep it under 200 lines

The official guidance is to target under 200 lines per CLAUDE.md. Longer files use more context and lower adherence. When a file grows, move part-of-the-codebase rules into path-scoped .claude/rules/ files. You can also split a file with @path imports:

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

Imports are for organization only. Imported files still load at launch, so they do not reduce context cost. Imports follow other imports up to four hops deep.

An import that points outside your working directory (for example @~/.claude/my-project-instructions.md inside a project file) counts as an external import. Claude Code shows an approval dialog the first time it meets one, so a committed project file cannot quietly pull in files from your home directory.

Using CLAUDE.md with AGENTS.md

This is the part that has changed. Earlier versions of Claude Code ignored AGENTS.md, and the usual workaround was a CLAUDE.md that imported it. According to the current docs, Claude Code (v2.1.277 or later) reads AGENTS.md directly when your working directory and its parents contain no CLAUDE.md or CLAUDE.local.md. If both exist, only the CLAUDE.md files are read by default.

That last rule has a catch: adding a CLAUDE.local.md to a repo that relies on AGENTS.md makes Claude stop reading AGENTS.md. To load both, either import it from your CLAUDE.md:

@AGENTS.md

## Claude Code

Always use plan mode for changes under `src/billing/`.

or set the Project instructions option to claude-md-and-agents-md. A symlink (ln -s AGENTS.md CLAUDE.md) still works too, though on Windows creating one needs administrator rights, so the @AGENTS.md import is simpler there.

Generate a first draft with /init

You do not have to write the file from scratch. Run /init in a session and Claude Code analyzes the codebase and generates a CLAUDE.md with the build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, /init suggests improvements rather than overwriting it. After that, add what Claude cannot discover by itself, such as team rules and deployment steps.

A realistic CLAUDE.md example

For a project built on Next.js, tRPC and Prisma, it could look like this:

# Project overview

SaaS dashboard on the Next.js 15 App Router. API via tRPC,
Prisma + PostgreSQL, auth with next-auth v5.

## Build & test

- Dev server: `pnpm dev`
- Type check: `pnpm typecheck`
- Tests: `pnpm test` (vitest; watch mode is `pnpm test:watch`)
- Before committing, `pnpm lint && pnpm typecheck` must pass

## Architecture

- `src/server/routers/`: tRPC routers, one file per domain
- `src/server/db/schema.prisma`: DB schema. Create migrations with
  `pnpm prisma migrate dev --name <description>`
- `src/app/`: App Router pages. Server components are the default;
  client components declare `"use client"` at the top of the file

## Conventions

- Named exports only for components; no default exports
- Throw API errors as `TRPCError`, never a bare `throw new Error()`
- Import order: external packages, then `@/` absolute paths, then relative

## Watch out

- `src/legacy/` is being migrated; do not add new code there
- Before changing billing logic (`src/server/routers/billing.ts`),
  write the test cases first

That is well within 200 lines, and it answers the questions Claude would otherwise ask every session: build commands, how to migrate, how to throw errors.

Setting the response language

If you want Claude Code to answer in a language other than English, say so in CLAUDE.md:

## Language

- Write all responses, commit messages and code comments in Japanese.
- Keep code identifiers (variables, functions) in English.

Put it in ~/.claude/CLAUDE.md to apply everywhere, or in the project's CLAUDE.md to apply to one project. Because CLAUDE.md is context, compliance is not guaranteed. Vague or conflicting instructions across files can make Claude pick one arbitrarily, so a concrete line such as "always respond in Japanese" works best.

Debugging a CLAUDE.md that is being ignored

Work through these in order:

  1. Run /context and check that the file appears under Memory files.
  2. Confirm the file sits in the right scope. People often miss that a subdirectory CLAUDE.md only loads after Claude reads a file in that directory.
  3. Make the instruction more concrete. "2-space indentation, use semicolons" gets followed more than "keep the code tidy."
  4. Look for contradictions between CLAUDE.md files.
  5. If instructions seem to vanish after /compact: the project-root CLAUDE.md is re-read from disk and re-injected, while nested subdirectory CLAUDE.md files and rules with paths frontmatter load again only when Claude next works on matching files. Anything you only said in conversation is gone, so move it into CLAUDE.md.

For a second opinion on your instruction files, the docs describe /doctor prompt-audit (Claude Code v2.1.283 or later), which looks for outdated references, instructions written for older models, and files that contradict each other, and proposes edits without applying them.

CLAUDE.md vs. auto memory

Auto memory is easy to miss. Both are loaded at the start of each session, but they are different things: CLAUDE.md is rules you write, while auto memory is notes Claude writes itself from your corrections and preferences. If Claude figures out mid-session that the real build command is pnpm build:prod, it can save that.

Auto memory is stored per repository at ~/.claude/projects/<project>/memory/. All worktrees and subdirectories of the same repo share one folder. MEMORY.md acts as an index, and only its first 200 lines or 25KB load at session start. Detailed notes live in topic files such as debugging.md that Claude reads on demand. Run /memory to browse the folder, edit files, or toggle auto memory.

A simple rule: team conventions that should go through code review ("always use pnpm") belong in CLAUDE.md. Environment quirks Claude picks up on its own ("the tests need a local Redis") are fine in auto memory.

Common mistakes

  • Everything in one file. Frontend, backend and infrastructure rules in a single CLAUDE.md blow past 200 lines quickly. Split with subdirectory files or .claude/rules/.
  • Vague instructions. "Write good code" gives Claude nothing to check. "Functions stay under 30 lines" or "throw errors with our AppError class" does.
  • Never updating it. When the project structure changes and CLAUDE.md does not, Claude follows directories and conventions that no longer exist. Treat CLAUDE.md as part of code review.
  • Secrets in the project file. Internal URLs or personal API keys must not go into a committed CLAUDE.md. Use the gitignored CLAUDE.local.md.

Avoid those four and a CLAUDE.md stays useful for a long time.