I put explanations of the code in other .md files. There's architecture.md, checklist.md, (feature).md, components.md, navigation.md.
These are designed to be easy for humans to read. There's also notes on things like deprecated libs to avoid, or how to use the design system. Get it to update things as they change.
Claude.md for me is a kind of directory to tell it what to read based on what it's trying to do.
Roadmap.md is one of my favorites. A lot of the problems that arise for both human and LLM coders is that we don't notice that there's tech debt or incomplete items. It's also easy to get back into 'flow' 7 months later.
I mostly use:
Project ./claude.md - team stuff like our weird API naming conventions, how we structure components, deployment steps that always trip people up
Local ./claude.local.md - my dev URLs, test accounts, personal shortcuts. Stuff I don't want to commit to the team file
User ~/.claude/claude.md - code style preferences, how I like explanations (brief vs detailed), tools I always use
The recursive thing is neat - it picks up memories from parent folders so you don't have to duplicate everything.
That # shortcut is way faster than editing files manually. Still forget about /memory command half the time tho.
Main thing I learned is being specific helps a lot. 'Use our error handling pattern' vs actually showing the pattern makes a big difference.
These are designed to be easy for humans to read. There's also notes on things like deprecated libs to avoid, or how to use the design system. Get it to update things as they change.
Claude.md for me is a kind of directory to tell it what to read based on what it's trying to do.
Roadmap.md is one of my favorites. A lot of the problems that arise for both human and LLM coders is that we don't notice that there's tech debt or incomplete items. It's also easy to get back into 'flow' 7 months later.