Summary
Global rules can’t capture domain-specific constraints, forcing developers to mentally context-switch and LLMs to hallucinate patterns. The hierarchical rule files pattern collocates documentation and configuration files (CLAUDE.md, ESLint configs, learning files) as close as possible to the code they govern. This creates semantic locality where context lives at the point of need, reducing cognitive load and improving LLM code generation accuracy.
The Problem
Monolithic root-level rule files (CLAUDE.md, .eslintrc) don’t scale to large codebases with multiple domains. Global rules miss domain-specific constraints (API patterns vs database migrations vs UI components), forcing developers to remember context and LLMs to guess patterns. When context is far from code, it becomes stale, unused, and eventually wrong. Teams waste time searching for relevant documentation across scattered files.
The Solution
Apply the collocation principle: ‘Rules should live as close as possible to the code they govern.’ Create a hierarchy of rule files that mirror your codebase structure. Root files contain architecture and global principles. Domain directories contain domain-specific patterns. Module directories contain implementation details. This creates semantic locality where LLMs and developers always have relevant context without searching.
