Your CLAUDE.md should be a map, not your entire product context One thing that has helped me a lo...Your CLAUDE.md should be a map, not your entire product context One thing that has helped me a lo...
The network for creativity
Join 1.25M professional creatives like you
Connect with clients, get discovered, and run your business 100% commission-free
Creatives on Contra have earned over $150M and we are just getting started
Back to feedPost
Sebastian's avatar
Sebastian Avelar
pro
• Aug 29
Your CLAUDE.md should be a map, not your entire product context One thing that has helped me a lot when working with Claude Code on bigger products is progressive disclosure.
The idea is simple:
Claude doesn’t need to know your entire product for every task. It needs to know where to find the right context.
A common approach is to keep adding things to CLAUDE.md:
Product rules, database structure, authentication, architecture decisions, workflows, edge cases...
Eventually you end up with a giant file that gets loaded again and again, even when 90% of it has nothing to do with the task.
Instead, I use CLAUDE.md mainly as a navigation file.
Something like:
Product context
Start with:
docs/product-overview.md
Read when relevant:
docs/data-model.md → database structure + relationships
docs/routing.md → routes, layouts and access rules
docs/decisions.md → important architecture decisions
docs/features/ → feature-specific business logic
Only load the documents relevant to the current task.
Then the actual knowledge lives in smaller, focused documents.
So if Claude is working on authentication, it doesn't need to read 4,000 lines about orders, billing, notifications and every other feature.
It starts with a small amount of context → understands where the information lives → pulls more context only when the task requires it.
That's the progressive disclosure part.
And IMO this becomes more important as the product grows.
You are basically giving the agent a map of the product, instead of trying to fit the whole product inside its head every time you start a task.
The nice side effect is that the documentation also becomes much easier for humans to maintain :)
I wrote a bigger guide about the documentation structure I'm using while rebuilding a SaaS with coding agents here:
https://docswarp.notion.site/How-to-document-your-product-so-AI-can-actually-build-it-3c09678204c580948a52c0f4ec86d6fc
*This applies to all AI models and not only Claude
ClaudeAI Engineer GitHub
Post image
Back to feed
The network for creativity
Join 1.25M professional creatives like you
Connect with clients, get discovered, and run your business 100% commission-free
Creatives on Contra have earned over $150M and we are just getting started