Don’t make CLAUDE.md hold every project memory
CLAUDE.md works well for stable rules inside a code project. It can hold test commands, coding habits, unusual structure notes, and warnings about old parts of the code that should not be touched casually. It becomes a poor fit when it also carries the reasons behind product decisions, customer reports that started a problem, changes from the last coding session, launch details that matter this week, and follow-up work sitting outside GitHub.
Putting all of that into CLAUDE.md makes the file stale and bloated. Leaving it out lets Claude Code work on the code, but it can miss the real context around the work. A cleaner split is to keep stable project behavior in CLAUDE.md, put clear source material in issues, , and docs, and use a separate for people, decisions, open loops, and changes over time.
The should receive only the context it needs, and it should show which source or memory it used.
Key points
- CLAUDE.md is best for stable project rules, such as test commands and coding conventions.
- Product reasons, customer reports, recent session changes, launch context, and open follow-ups can make CLAUDE.md stale.
- Without that wider context, Claude Code may work on the repo but miss why the work matters.
- A better split is CLAUDE.md for stable rules, issues and docs for sources, and a for changing context.
- The should reveal which source or memory it used.