developmentL3 SystematicCoding Agent Usage

Rules files per-team/per-repo

How to evolve from a single project-level CLAUDE.md to a layered system of context files tailored to each team's tech stack and conventions.

·CLI agents (Claude Code, Codex) are the primary coding interface for 50%+ of feature work
·Per-team or per-repo rules files exist and are maintained with code review
·Coding conventions are written as explicit, agent-parseable rules (not implicit tribal knowledge)

·Agent usage is tracked per developer and per repository
·Agent instruction files follow a standardized template across the organization

Evidence

·CLI agent session logs or telemetry showing primary usage
·Rules files in repository with commit history showing regular updates
·Coding conventions document cross-referenced from agent instruction files

What It Is

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).

Why It Matters

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.

Tip

When a developer says "the AI keeps getting X wrong in our module even though CLAUDE.md mentions it," that's a signal that the root-level rule is too general to apply correctly in their context. The fix is a per-directory or per-team CLAUDE.md with a more specific version of the rule.

Getting Started

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.
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.
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.
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.
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.
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.

6 steps to get from here to the next level

Common Pitfalls

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.

Mistakes teams actually make at this stage - and how to avoid them

How Different Roles See It

BobHead of Engineering

Bob has rolled out CLAUDE.md across all repositories (L2 success), but the files are already showing signs of drift. The frontend team's React conventions are mixed into the same file as backend Python patterns, and different teams keep adding conflicting rules. The file has become a 600-line mess that nobody maintains.

What Bob should do: This is the canonical signal to move from L2 to L3. Bob should convene a half-day "context engineering workshop" with one senior engineer from each team. The agenda: audit the current root CLAUDE.md, separate universal rules from team-specific rules, assign each team their own file to maintain, and establish the quarterly review cadence. Bob should treat CLAUDE.md maintenance the same way he treats documentation: it's engineering work, it has an owner, and it's part of the definition of done for significant changes. The investment of one afternoon per quarter per team produces continuous improvement in AI output quality - that's a measurable ROI.

What Bob should do - role-specific action plan

SarahProductivity Lead

Sarah has data showing that AI quality varies significantly across teams even though they're using the same tools. The frontend team reports much higher satisfaction with AI suggestions than the backend team. She suspects the difference is context quality, but needs to verify.

What Sarah should do: Run a simple diagnostic: compare the specificity of each team's CLAUDE.md. Teams with detailed, current, example-rich rules files almost always report higher AI satisfaction scores. Sarah should correlate CLAUDE.md quality (lines, specificity, recency of last update) with AI satisfaction scores and PR-correction rate. This correlation is her business case for the per-team rules file investment. Once the correlation is established, she can set a target: "every team's CLAUDE.md should be reviewed quarterly and have at least X specific conventions documented." This turns context quality into a trackable metric.

What Sarah should do - role-specific action plan

VictorStaff Engineer - AI Champion

Victor's been advocating for per-team CLAUDE.md files for months. He maintains his own team's file meticulously and has noticed that his team's AI quality is consistently better than teams with generic root-level rules. But getting other teams to own their files has been harder than expected.

What Victor should do: Victor should create a CLAUDE.md template for each common team archetype in the company - frontend React, backend Node.js, data pipeline Python, infrastructure Terraform. Each template has the right structure, the right categories of rules, and example entries that teams can customize. This lowers the activation energy from "write your own rules file from scratch" to "edit this template to match your team." Victor should also propose adding a CLAUDE.md health check to the CI pipeline: a script that checks for staleness (last update date), minimum length (at least 50 lines), and basic structure. Automated quality gates for context files is a distinctly L3 behavior.

What Victor should do - role-specific action plan