Rules files per-team/per-repo

Rules files per-team and per-repo is the systematic evolution of the L2 CLAUDE.md approach. Instead of one root-level instruction file for the entire codebase, each team and repository has tailored context files that reflect their specific technology, patterns, and constraints. A frontend team's rules differ from a backend team's. A data pipeline repository has different conventions than an API repository. In a monorepo, individual packages have their own CLAUDE.md files that supplement (and can override) the root-level file.

Claude Code supports this natively through hierarchical CLAUDE.md resolution: it reads the root-level file, then the directory-level file for the current working path, building a layered context picture. Cursor supports per-directory .cursorrules with similar hierarchy. This layered system means the AI can have both "this is our company's general approach to TypeScript" and "this specific package uses a different testing pattern because of legacy constraints" - simultaneously, without confusion.

At L3 (Systematic), the proliferation of rules files is intentional and governed. There's a policy for who maintains each file, how conflicts are resolved between layers, and how files are reviewed for accuracy. This transforms context engineering from a one-time setup task into an ongoing discipline - like documentation, but with direct, measurable impact on AI output quality.

The move from single CLAUDE.md (L2) to layered per-team files (L3) typically happens when teams start noticing that the root-level file is either too generic (it doesn't capture team-specific patterns) or too specific (it includes rules that only apply to one module and confuse agents working in others).

Layered rules files are the foundation of systematic context engineering:

• Precision improves agent behavior - a backend team's CLAUDE.md that says "use PostgreSQL with Prisma ORM, following patterns in /src/db/" produces far better results than a root-level file that says "we use a database"
• Reduces cross-team interference - without per-team files, the frontend team's rules about React patterns confuse agents working on the Python backend; scoped files eliminate this
• Scales with organizational complexity - as the codebase grows and teams diverge, layered files grow with it; a single file becomes an unmanageable compromise
• Creates team ownership - each team owns and maintains their own rules file, creating accountability and keeping context current
• Enables specialization without fragmentation - the root-level file ensures company-wide standards; team files add specificity; both layers are active simultaneously

Without per-team files, context engineering hits a ceiling at L2. Large codebases have too much diversity to capture in a single file, and the compromise rules that emerge serve no team particularly well.

1. Audit your current CLAUDE.md - Identify rules that are genuinely universal vs. rules that only apply to specific teams or modules. This audit reveals where to split.
2. Create team-specific subdirectory files - For each major team or service boundary, add a CLAUDE.md in the relevant directory. Start with the teams that have the most unique conventions or that are most active in AI-assisted development.
3. Establish the inheritance model - Decide explicitly: do team-level rules override root rules, or supplement them? Document this in the root CLAUDE.md so developers know how the layers interact. Claude Code uses additive layering by default; conflicts should be resolved by specificity.
4. Assign ownership - Each CLAUDE.md file should have an owner (a team lead or senior engineer) responsible for keeping it current. Add ownership metadata to the file header: # Maintained by: Platform Team.
5. Add rules files to your code review checklist - When a PR changes patterns, conventions, or introduces a new library, the reviewer should ask: "does this need to be reflected in the CLAUDE.md?" Make CLAUDE.md updates as natural as documentation updates.
6. Run a quarterly rules audit - Schedule a 30-minute review per team to check their rules file for accuracy. Delete stale rules, add new conventions, and note patterns that keep causing AI misfires.

Duplicating rules across files. When the same rule appears in the root file and three team files, maintaining consistency becomes a burden. Establish a principle: root-level CLAUDE.md owns universal rules; team files add specificity without repeating root-level content. Use comments to reference root rules: # See root CLAUDE.md for general TypeScript conventions; the following are specific to this package.

Files that contradict each other. Team files that directly contradict root-level rules create confusion for both developers and agents. When a team needs to deviate from a company-wide convention, the team file should explicitly explain why: # This package uses CommonJS modules instead of ESM due to legacy Lambda compatibility requirements. Context for overrides is as important as the overrides themselves.

Letting files go stale. A rules file that describes how the codebase was 18 months ago is worse than no file - the agent confidently follows outdated patterns. Stale context is a form of misinformation. The quarterly audit process is non-negotiable at L3; assign it to a specific team member as a recurring calendar task.

Over-engineering before it's needed. Some teams jump to a complex 10-layer hierarchy before they've learned what context actually affects agent behavior. Start with root + one team layer, iterate based on observed misfires, and add layers only when a clear gap exists. Complexity for its own sake increases maintenance burden without proportional benefit.