CLAUDE.md hierarchy, scoping, and modular organization

Three levels, and almost every configuration bug is really a question about which one something was put in.

The hierarchy

• User level, ~/.claude/CLAUDE.md — applies to you, on your machine.
• Project level, root CLAUDE.md or .claude/CLAUDE.md — travels with the repository.
• Directory level, a CLAUDE.md inside a subdirectory — applies when working there.

~/.claude/CLAUDE.md                 you, on this machine, never committed
repo/CLAUDE.md                      everyone who clones the repository
repo/packages/checkout/CLAUDE.md    adds to the above, inside that package

The levels add to one another rather than replacing one another, so a package file never restates the root standards. Copy them down instead and the copies drift apart silently, until two packages get reviewed by different rules.

Why shared instructions sometimes disappear

Someone puts a team convention in ~/.claude/CLAUDE.md. It works perfectly for them. A new teammate joins and Claude ignores the convention entirely.

Nothing is broken. User-level configuration is not in version control, so it was never shared. Move the convention to project-level configuration. When a rule works for one developer but not another, check its scope before rewriting its wording.

/memory shows which memory files are actually loaded, which is how you confirm this rather than guessing.

It runs backward too: a personal working habit put in the project file reaches every teammate, and labeling it optional changes nothing, because a loaded file is acted on. Both directions turn on one question — who should receive this?

A note on your own desk and a note on the shared fridge differ in one respect that matters: who reads it. Put the shared rule on your desk and nobody follows it; put your own habit on the fridge and everybody does.

Keeping it modular

A CLAUDE.md that grows without bound becomes something nobody reads and everybody half-follows.

Two mechanisms:

• @path imports reference external files, so a package's CLAUDE.md can pull in exactly the standards relevant to it. The path is written bare — a line containing @docs/standards.md expands that file at launch. There's no @import keyword; the @ and the path are the whole syntax.
• .claude/rules/ holds topic-specific files — testing.md, api-conventions.md, deployment.md — instead of one monolith.

A package file becomes mostly a selection:

## Checkout service

@docs/standards/typescript.md
@docs/standards/payments.md

Import the subset that applies; an import you did not need is context paid for on every turn.

Both keep each file about one thing, which is what makes them maintainable and reviewable.