CLAUDE.md and Claude Code memory, explained: what loads, when, and what fits

Claude Code's memory system is simple to describe and easy to get
wrong: three file locations, one import mechanism, one finite budget.
Everything that goes wrong with Claude Code instructions traces to
misunderstanding one of those.

The three locations

File	Scope	Loaded
./CLAUDE.md (repo root)	Project, shared with the team	At session start in that tree
./subdir/CLAUDE.md	Per-package, monorepos	When Claude works in that subtree
~/.claude/CLAUDE.md	User-global, all projects	Every session, every project

The common mistakes follow directly:

• Personal preferences in the repo file. The repo CLAUDE.md is committed, it belongs to the team. Your personal conventions belong in ~/.claude/CLAUDE.md, which is yours alone.
• Team conventions in the user file. The inverse: anything in ~/.claude/CLAUDE.md applies to every repo you touch and to nobody else. Team standards do not live there.
• Monorepo root bloat. With per-package files available, the root file should hold what is true repo-wide and let package files carry the specifics, they only load when relevant, which is free budget.

The @import mechanism

CLAUDE.md supports imports:

@import AGENTS.md
@import skills/verify-and-stop.md

This is the feature that makes a layered config possible: the repo
CLAUDE.md does not need to contain the baseline, it can import
it. One source of truth (AGENTS.md), tool-specific extensions on
top, and the two can never drift apart because the tool layer is a
reference, not a copy.

Imports also compose with the monorepo pattern: a package-level
CLAUDE.md can import shared skills without re-declaring them.

The budget: what fits

There is no published hard limit, but there is a practical one, and it
arrives faster than people expect: instructions compete with your
source code for attention, and compliance degrades as the instruction
block grows. Empirically, the drop-off starts well before any technical
ceiling, configs in the hundreds of lines show visibly worse
rule-following than configs under ~300 lines.

Practical budget rules:

1. Front-load identity-level rules. Commands, conventions, safety. If the file must be truncated in someone's setup, the tail is what gets lost.
2. Imperatives, not essays. Each rule earns its line. Explanations live in docs; the config carries directives.
3. Scope what you can. Claude Code reads the whole file always, so unlike Cursor there is no glob mechanism, the budget discipline has to come from editing. Anything stack-specific-but-not-always- relevant is a candidate for the team's Cursor rules instead, or for a skill imported on demand.
4. Count periodically. wc -l CLAUDE.md in CI is not overkill. A file that creeps from 120 to 400 lines across fifty PRs degrades behavior so gradually nobody notices.

A structure that works

# CLAUDE.md

@import AGENTS.md          # team baseline: commands, conventions, safety

## Verification loop       # how this repo wants work verified
1. smallest change
2. run tests (real output reported)
3. lint
4. commit (conventional)

## Stack notes             # the 3-5 things specific to working here

## Anti-patterns           # the failure modes seen in this repo

Baseline imported, loop explicit, stack notes short, anti-patterns
concrete. Under 100 lines total for most repos, leaving enormous head
room against the compliance drop-off.

This is exactly the shape of the CLAUDE.md in our stack kits, baseline imported, a verification loop, stack guidance, anti-patterns, kept under a validated 300-line ceiling by the same validator that
ships with the pack.

---

If you'd rather not assemble this by hand: AgentConfig Studio on Gumroad ships this as version-pinned, validator-tested kits for 12 stacks. The complete Next.js/TypeScript kit is free (MIT) if you want to inspect the structure first.