Mastering CLAUDE.md

CLAUDE.md is not a project wiki. Treat it as an operating contract for the agent: concise, actionable, and biased toward rules that prevent real mistakes. Claude Code loads it at the start of every session as context, not as enforced configuration. Specific, well-structured instructions are followed far more reliably than vague ones, and for anything that must run at a fixed point (for example, before every commit) a hook is the right tool, not a CLAUDE.md line.

Hierarchy

CLAUDE.md files live in several locations, each with a different scope. They are loaded from broadest scope to most specific, so more specific instructions appear later in context (and Claude reads them last).

Think of these as three working layers:

• Global rules (~/.claude/CLAUDE.md) for personal preferences and machine-specific constraints.
• Repository rules (./CLAUDE.md or ./.claude/CLAUDE.md) for build commands, architecture boundaries, and workflow expectations.
• Directory rules — CLAUDE.md files in subdirectories for specialized areas such as docs, apps, migrations, or package internals.

On top of these, organizations can deploy a managed policy CLAUDE.md that applies to every session on a machine and cannot be excluded by individual settings.

The repository file should be useful even when read alone. Directory files should add local context, not restate the whole project.

How files load

Claude Code walks up the directory tree from your working directory, loading every CLAUDE.md and CLAUDE.local.md it finds along the way. All discovered files are concatenated (they do not override one another), ordered from the filesystem root down to your working directory, so instructions closer to where you launched Claude are read last. Within a directory, CLAUDE.local.md is appended after CLAUDE.md.

CLAUDE.md and CLAUDE.local.md files in subdirectories below your working directory are not loaded at launch. They load on demand when Claude reads files in those subdirectories. After a /compact, the project-root CLAUDE.md is re-read from disk and re-injected, but nested subdirectory files are not re-injected until Claude next reads a file there.

What Belongs In The File

Good entries are specific:

- Use `rg` for code search.
- Run `yarn workspace handbook typecheck` after changing handbook routes or MDX source code.
- Do not edit generated `.source` files manually.
- Keep English locale content under `content/books/en`.

Weak entries are broad:

- Write clean code.
- Be careful.
- Make it scalable.

The agent cannot reliably execute vague values. Convert them into commands, constraints, or review criteria. Because the file is delivered as context (a user message after the system prompt) rather than enforced configuration, specificity directly improves adherence: "Use 2-space indentation" works better than "format code nicely."

Keep it small

Target under 200 lines per file. Longer files consume more context and reduce how reliably Claude follows them. CLAUDE.md is loaded in full regardless of length, so trimming matters. If instructions grow large, prefer path-scoped rules over a longer file — @path imports help organization but do not reduce context, since imported files still load at launch.

Use markdown headers and bullets to group related instructions; Claude scans structure the way readers do. Block-level HTML comments (<!-- maintainer notes -->) are stripped before the content is injected into context, so you can leave human-only notes without spending tokens.

Imports And Modules

If the file grows, split stable sections into imported files using @path/to/import syntax anywhere in your CLAUDE.md:

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

@docs/agent-routing.md
@docs/testing-contract.md

Both relative and absolute paths work; relative paths resolve relative to the file containing the import, not the working directory. Imported files can recursively import other files, up to a maximum depth of four hops. Imported content is expanded into context at launch alongside the CLAUDE.md that references it.

Keep imports close to the work they affect. A frontend package should not need to load backend migration policy on every task.

AGENTS.md

Claude Code reads CLAUDE.md, not AGENTS.md. If your repo already uses AGENTS.md for other agents, create a CLAUDE.md that imports it so both tools read the same instructions:

@AGENTS.md

## Claude Code

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

A symlink (ln -s AGENTS.md CLAUDE.md) also works when you do not need Claude-specific additions. On Windows, prefer the @AGENTS.md import since symlinks require elevated privileges.

Path-Scoped Rules (.claude/rules/)

For larger projects, organize instructions into multiple files under .claude/rules/. Each file covers one topic, and all .md files are discovered recursively (including subdirectories like frontend/ or backend/).

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Loaded every session
│       ├── testing.md
│       └── security.md

Rules without a paths frontmatter field load at launch with the same priority as .claude/CLAUDE.md. Add a paths field to scope a rule so it only enters context when Claude works with matching files — useful for keeping large instruction sets out of every session:

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

# API Development Rules

- All API endpoints must include input validation.
- Use the standard error response format.

Personal rules in ~/.claude/rules/ apply to every project on your machine and load before project rules (giving project rules higher priority). The .claude/rules/ directory also supports symlinks for sharing a common rule set across projects.

Auto Memory

Beyond the files you write, Claude can accumulate knowledge on its own. Auto memory lets Claude save notes for itself — build commands, debugging insights, architecture notes, preferences — based on your corrections as you work. It is on by default.

• Storage: each project gets ~/.claude/projects/<project>/memory/, derived from the git repo, so all worktrees and subdirectories in the same repo share one directory. It contains a MEMORY.md index plus optional topic files.
• Loading: only the first 200 lines or 25KB of MEMORY.md (whichever comes first) load at the start of every session. Topic files load on demand when Claude needs them.
• Disable: toggle it in /memory, set "autoMemoryEnabled": false in project settings, or set the CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 environment variable.
• Relocate: set autoMemoryDirectory (absolute path or ~/-prefixed) in user or policy settings — it is deliberately rejected from project/local settings so a cloned repo cannot redirect memory writes.

When you ask Claude to "remember" something, it goes to auto memory. To add a rule to CLAUDE.md instead, say "add this to CLAUDE.md" or edit the file directly.

Working With The Files

• /init generates a starting CLAUDE.md by analyzing your codebase (build commands, test instructions, conventions). If a CLAUDE.md already exists, it suggests improvements rather than overwriting. In a repo with AGENTS.md, .cursorrules, or .windsurfrules, it reads those and incorporates relevant parts. Setting CLAUDE_CODE_NEW_INIT=1 enables an interactive multi-phase flow that also offers to set up skills and hooks.
• /memory lists every CLAUDE.md, CLAUDE.local.md, and rules file loaded in the current session, lets you toggle auto memory, and opens any file in your editor. Use it to confirm a file is actually being loaded.

Maintenance Rhythm

Update CLAUDE.md when a mistake repeats, when a command changes, when a code review catches something Claude should have known, or when a new workflow becomes standard. Do not add instructions for one-off incidents unless they reveal a durable rule.

If two rules contradict each other, Claude may pick one arbitrarily — review your CLAUDE.md, nested files, and .claude/rules/ periodically to remove outdated or conflicting instructions. In monorepos, use the claudeMdExcludes setting (path or glob patterns, matched against absolute paths) to skip ancestor CLAUDE.md files from other teams. Note that managed policy CLAUDE.md files cannot be excluded.

Review Checklist

• Can a new agent understand how to build and test the repo?
• Are destructive commands explicitly restricted?
• Are generated files and ownership boundaries named?
• Are instructions short enough to stay in working context (under ~200 lines)?
• Is each rule observable during review?
• Does /memory confirm the file is actually loaded for the session?