
transcript
show notes
Claude Code's CLAUDE.md file is supposed to make every coding session smarter, but load it up carelessly and it does the opposite: burying the instructions that matter under everything else you've dumped in over time. This episode is a practical walkthrough of how CLAUDE.md actually works and how to keep it from getting out of hand.
The episode covers where these files live in Claude Code's memory hierarchy: a personal file in your home directory, a project file shared through source control, a gitignored CLAUDE.local.md for personal preferences, and an organization-wide managed policy file IT can push to every developer's machine, and how they combine. Nested CLAUDE.md files inside subdirectories like backend or backend/payments don't override their parent. Claude Code concatenates every discovered file into context, with broader instructions loaded first and more specific ones last, so contradictory rules across files can leave Claude with competing guidance instead of a clean override.
It also draws a distinction most CLAUDE.md advice skips: auto memory, the separate system where Claude Code writes its own notes based on corrections and preferences you give it as you work, versus CLAUDE.md, which only holds what you deliberately write. Mixing the two is one reason files balloon. Other practical guidance covered includes Claude Code's own recommendation to keep each CLAUDE.md under roughly two hundred lines, the .claude/rules folder for instructions scoped to specific file paths, skills for procedures that only need to load when relevant, the @ import syntax and why it doesn't actually shrink context, and the /init and /context commands for generating and auditing memory files. The episode closes on a point worth remembering on its own: CLAUDE.md is guidance the model tries to follow, not an enforced boundary, and anything that has to be blocked regardless of what Claude decides belongs in a hook or a permission setting instead.
Useful for anyone running Claude Code day to day who wants their CLAUDE.md file to actually get followed instead of ignored.
Sources & References
How Claude remembers your project, Claude Code docs — https://code.claude.com/docs/en/memory
Voice narration is AI-generated.