AI Knowledge Center 🎓 Exam Prep
Foundations Soft · model-mediated GA ⓘ legend

Conventions

Persistent markdown instructions Claude loads every session. The first thing you reach for, and the thing most problems actually need. Soft: Claude reads it and tries to comply, but there is no guarantee.

Analogy — the onboarding doc & house style guide you hand a new teammate. They’ll read it and mostly follow it; they won’t always. For anything that must happen, you need a lock on the door (a hook) or a company policy (a managed policy), not a style guide.

Mechanism

Plain markdown, concatenated by walking up the directory tree (broad → specific) and loaded as a user message after the system prompt — not as enforced config. Supports @path imports (max depth 4) and modular .claude/rules/*.md files (optionally path-scoped via paths: frontmatter).

Load order (broad → specific)
managed CLAUDE.md   (org, can't be excluded)
~/.claude/CLAUDE.md (you, all projects)
./CLAUDE.md  or  ./.claude/CLAUDE.md   (project, committed)
./CLAUDE.local.md   (local, gitignore it)

Auto-memory: Claude-written notes at ~/.claude/projects/<project>/memory/MEMORY.md (first 200 lines / 25KB loaded each session; v2.1.59+, on by default; toggle autoMemoryEnabled).

When to reach for it

✓
A fact Claude needs every session: build/test commands, project layout, naming conventions.
✓
Claude got the same convention wrong twice.
✓
Path-specific guidance (e.g. rules for /api only) → a .claude/rules/ file.

When not to

✕
A guardrail that must hold → use a hook or permission rule; CLAUDE.md can’t enforce.
✕
A multi-step procedure used occasionally → move it to a skill (loads on demand, saves context).

Best practices

★
Keep it under ~200 lines. Every line is a recurring token cost on every turn.
★
Be concrete and verifiable: “use 2-space indentation,” not “write clean code.”
★
Push procedures into skills, path-specific notes into .claude/rules/, hard rules into hooks.
★
Run /init to scaffold one; /memory to edit; # at the start of a message to append a memory.
The #1 misconception Conventions are not the same as policies. CLAUDE.md shapes behavior softly; managed settings enforce it hard. See the terminology corrections.

Sources