Hey! I wanted to share something I learned the hard way while rebuilding my product with AI agents.
Over the last 2 months at, my work i rebuilt our app which is a multi-module, multi-tenant SaaS with a lot of business logic across different instances working mostly with Claude Code.
While doing this, I ended up building an internal tool that combines a lot of the ideas and insights I had seen other people share across different places online.
One of the ideas that inspired the system the most was using CLAUDE.md as a navigation file, instead of dumping all your context inside of it.
The idea is pretty simple.
You keep your CLAUDE.md or whatever equivalent your coding agent uses small.
Instead of putting all your product knowledge in there, it points the agent to the folder structure inside the repo where the actual documentation lives as markdown files.
This helps a lot with progressive disclosure of context.
You don't need to overload the AI with your entire product every time you ask it to work on one feature.
The documentation lives directly inside the repo because that's simply the easiest place for the AI to access it while working on the codebase.
The internal tool I built looks something like this:
It's basically a dashboard to navigate all those documentation files.
They're split into the main components of the app — foundations, and in our case the different product instances/modules — with subfolders that describe individual screens and features.
There are two documents that, for me, need to exist very early:
I normally start with the Technical Architecture.