The Problem
Your monorepo has a React frontend, a Python backend, a Go microservice, and shared packages. You create one CLAUDE.md at the root. Now Claude is confused: "Use TypeScript strict mode" when working on Python? "Follow Django patterns" when editing React? AI needs context, but giving it everything at once creates noise.
The issue: Monorepos have different rules for different packages. A single config file forces you to choose between too generic (useless) or too detailed (overwhelming).
Different parts of your codebase need different guidance. The web app follows React conventions, the API follows Flask patterns, shared libraries have their own rules. AI should know where it is and what applies.
The Core Insight
Organize configuration hierarchically: root level for shared conventions, package level for specific rules. AI traverses up the tree, inheriting and overriding as needed.
Think of it like CSS specificity: root config applies everywhere (like *), package config applies to that package (like .class), and more specific configs override less specific ones.