CLAUDE.md: the highest-leverage file in your repository

Where the files live and how they load

Four scopes, listed here in load order from broadest to most specific. A project instruction therefore appears in context after a user instruction.

Files in subdirectories below your working directory are found too, but they are not loaded at launch. They enter context when Claude reads a file in that subdirectory. Within any one directory, CLAUDE.local.md is appended after CLAUDE.md, so your personal notes are the last thing read at that level.

# in a session: lists Memory files that are in context right now
/context

# open or create any memory file across user and project scope
/memory

# generate a starting CLAUDE.md from the codebase
/init

What belongs in it

One test for every line: would a competent engineer new to this repository get this wrong? If no, delete it. Anthropic’s own guidance is to add an entry when Claude makes the same mistake a second time, or when you type the same correction you typed last session.

A complete example

# Project context

TypeScript API on Fastify, Postgres via Drizzle. pnpm workspace.

<!-- Maintainer note: block HTML comments are stripped before this
     file reaches the model, so notes like this cost no context. -->

## Commands

- `pnpm dev` - local server on :3000
- `pnpm test` - full suite, about 4 minutes
- `pnpm test src/routes/auth.test.ts` - ONE file. Prefer this.
- `pnpm lint --fix` - run before proposing a diff
- `pnpm db:migrate` - after any schema change

## Conventions

- **No default exports.** Named exports only, enforced by lint.
- Errors: throw `AppError` from `src/errors.ts`, never a bare `Error`.
- All money is integer minor units. Never a float.
- Dates cross the wire as ISO 8601 UTC strings, never Date objects.

## Traps

- `src/legacy/billing.ts` is load-bearing and untested. Ask before touching it.
- Drizzle migrations are NOT reversible here. Check the generated SQL first.
- The test suite needs Postgres running: `docker compose up -d db`.

## Never

- Never commit directly to `main`.
- Never add a dependency without asking.
- Never edit anything under `src/generated/`.

Keeping it under 200 lines

Anthropic documents a target of under 200 lines per CLAUDE.md file, and is explicit about why: longer files consume more context and reduce adherence. Splitting into @path imports helps organisation but does not reduce context, because imported files load at launch too. The mechanism that actually reduces context is path-scoped rules.

---
paths:
  - "src/api/**/*.{ts,tsx}"
---

# API rules

- Every endpoint validates input with the shared zod schema.
- Errors use the standard response envelope in `src/errors.ts`.
- Add an OpenAPI comment block above each handler.

CLAUDE.md, rules, skills, and auto memory

Claude Code now has four ways to carry knowledge into a session, and picking the wrong one is the most common cause of a file that is both long and ignored.

Auto memory is on by default. Claude writes its own notes to ~/.claude/projects/<project>/memory/, keyed on the git repository so every worktree of the same repo shares one directory. Only MEMORY.md is loaded at session start, and only the first 200 lines or 25KB of it, whichever comes first. Topic files next to it are read on demand.

{
  "autoMemoryEnabled": false
}

AGENTS.md, and repos that carry both

Claude Code reads CLAUDE.md. It does not read AGENTS.md, which is the cross-tool file Codex and several others use. If your repository already has one, do not duplicate it.

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

ln -s AGENTS.md CLAUDE.md

# then confirm it loaded
claude
> /context

When the file is loaded and still ignored

CLAUDE.md is delivered as a user message after the system prompt. It is context, not enforced configuration, so there is no guarantee of compliance, particularly for vague or conflicting instructions.

Questions people ask

Keep reading