CLAUDE.md
CLAUDE.md is Claude Code's project instruction file — the primary mechanism for shaping agent behavior before a conversation begins. It's the difference between an agent that knows your codebase and one that's guessing.
Why CLAUDE.md Matters
Every Claude Code session starts by reading CLAUDE.md files. This isn't optional context — it's the agent's mental model of your project. A well-architected CLAUDE.md eliminates entire categories of mistakes.
The Layered Architecture
CLAUDE.md files cascade from three levels:
- User-level (
~/.claude/CLAUDE.md) — Personal preferences, global tooling - Project-level (
./CLAUDE.md) — Repo-specific conventions, architecture - Directory-level (
./src/CLAUDE.md) — Module-specific rules, patterns
What's Inside
- Mental Model — How instruction layering works and when each level fires
- Playbook — Production CLAUDE.md architectures for different project types
- Compositions — CLAUDE.md with hooks, skills, and memory for full-stack control
- Pitfalls — Instruction conflicts, context window pressure, stale instructions
Mental Model
How CLAUDE.md instruction layering works — load order, precedence rules, context window impact, and what survives compaction.
Playbook
Production CLAUDE.md architectures for monorepos, full-stack apps, libraries, and team workflows.
Compositions
CLAUDE.md combined with hooks, skills, memory, and agents for full-stack agent control.
Pitfalls
Instruction conflicts, context window pressure, stale rules, and the mistakes that silently degrade agent performance.