Every team using AI coding agents starts the same way: someone drops a CLAUDE.md (or .cursorrules, or a copilot-instructions.md) into a repo. It works. So the next repo gets one too. And the next.
Then you look up and you have 20 repos, 6 teammates, and 3 different AI tools — and no two of those config files are the same. Which one is right? Nobody knows.
I hit this wall running an integration platform with dozens of small repos. This post is the pattern I landed on, and a small open template you can clone to do the same.
Why a single instructions file breaks
A single file is perfect for one repo and one person. At team scale it fails in five predictable ways:
