Rule Composition: Multiple Sources, One Output
Rule composition is the process of combining multiple rule sources into a single, effective rule set that the AI reads. The sources: organization rules (security, code quality — apply to all projects), technology rules (TypeScript patterns, Go conventions — apply to projects using that technology), and team rules (project-specific patterns, domain terminology — apply to one project). The composition: merges all applicable sources into one CLAUDE.md (or .cursorrules) that the AI reads. The developer: does not need to know which source contributed which rule. The AI: sees one unified set of conventions.
Why compose instead of using one file? At 1-5 projects: one file per project works. At 50+ projects: maintaining 50 separate files is impossible. Changes to a shared convention (updating the TypeScript version reference): require editing 50 files. With composition: the TypeScript convention is in the technology rules (one source). The composition: distributes it to all 50 TypeScript projects. Update once: all 50 projects get the update on the next sync. Composition: the scaling mechanism for AI rules.
The analogy: CSS cascade. In CSS: styles come from browser defaults, user stylesheets, and author stylesheets. More specific styles override less specific ones. In rule composition: conventions come from organization defaults, technology conventions, and team specifics. More specific rules override less specific ones. Team rules: override technology rules. Technology rules: override organization rules. The cascade: resolves conflicts predictably.
The Three Layers of Rule Composition
Layer 1 — Organization rules (lowest priority, broadest scope): conventions that apply to every project in the organization. Security rules (parameterized queries, no secrets in code, input validation). Code quality rules (no any type, consistent error handling, testing requirements). These rules: the baseline. Every project inherits them. They are the guardrails that protect every codebase regardless of technology stack or team. Maintained by: the platform team or staff engineers.
Layer 2 — Technology rules (medium priority, technology-scoped): conventions specific to a language or framework. TypeScript rules (strict mode, Result pattern, Zod validation). Go rules (error-as-values, interface-based abstraction, table-driven tests). Next.js rules (Server Components default, App Router conventions). These rules: applied to projects using that technology. A TypeScript project: gets organization rules + TypeScript rules. A Go project: gets organization rules + Go rules. Maintained by: the technology lead or senior engineer for that stack.
Layer 3 — Team rules (highest priority, project-scoped): conventions specific to one project. Domain terminology (payment processing terms, healthcare abbreviations), project-specific patterns (the custom error wrapper, the specific API response format), and architectural decisions unique to the project. These rules: override technology and organization rules for conflicts. Maintained by: the project's tech lead. AI rule: 'Three layers: organization (broad, low priority) → technology (medium) → team (narrow, high priority). More specific layers override less specific for conflicts.'
CSS: browser defaults → user styles → author styles. More specific wins. AI rules: organization defaults → technology conventions → team specifics. More specific wins. The mental model: identical. A web developer hearing 'rule composition': immediately understands the concept if framed as a cascade. 'Your team rule overrides the org rule, just like an inline style overrides a class style.' The analogy: bridges the new concept to existing knowledge in 5 seconds.
How Composition Works in Practice
The composition process: the system reads all applicable rule sources (organization + technology + team), merges them into one output file, with later layers overriding earlier layers for conflicts. The output: a single CLAUDE.md that contains all rules from all layers, organized by section, with clear attribution ('## Security Rules [from: Organization Base v2.5]', '## TypeScript Conventions [from: TypeScript Rules v1.8]', '## Project-Specific [from: Team Rules v1.2]'). The developer: sees one file. The AI: reads one file. The management: happens at the source layers.
Override resolution: when two layers have rules on the same topic, the more specific layer wins. Organization rule: 'Use try-catch for error handling.' Technology rule (TypeScript): 'Use the Result<T, E> pattern for error handling.' The TypeScript rule: overrides the organization rule for TypeScript projects (more specific). Go projects: follow the organization rule (no Go-specific override). The override: documented in the composed output ('Override: TypeScript Result pattern replaces organization try-catch for this project').
Composition tools: manual (concatenate rule files with a script — simplest), RuleSync (automatic composition with override resolution and attribution — most feature-rich), and git-based (a build script that composes from source files in a central repo — middle ground). The tool: determines how automated and managed the composition is. The concept: the same regardless of tooling. AI rule: 'The composition concept is tool-independent. Manual concatenation, RuleSync, or custom scripts: all implement the same three-layer model. Choose the tool that matches your organization's scale.'
Without composition: updating the TypeScript version reference from 5.3 to 5.4 requires editing CLAUDE.md in 50 repos. One PR per repo. 50 PRs. With composition: update the TypeScript technology rules (one source file). The composition: regenerates CLAUDE.md in all 50 TypeScript projects with the updated reference. One edit. 50 updates. The composition: turns a 50-edit task into a 1-edit task. At scale: composition is not optional. It is the only sustainable approach.
When You Need Composition (and When You Do Not)
You need composition when: the organization has multiple tech stacks (TypeScript and Go projects need different rules but share security rules), the organization has more than 20 projects (maintaining individual rule files becomes unsustainable), different teams need different conventions (the mobile team and the backend team have different patterns), or compliance requirements mandate shared security rules (all projects must follow the same security baseline). These scenarios: require the layered model to remain manageable.
You do NOT need composition when: the team has one project with one tech stack (a single CLAUDE.md covers everything), the organization is small (under 10 developers — one shared rule file works), or all projects use the same technology (one technology rule set applied to all projects — no layering needed). In these cases: a single rule file per project is simpler and sufficient. Composition: adds value when complexity demands it, not as a default.
The progression: start with single-file rules (one CLAUDE.md per project). When the organization grows to 20+ projects with shared conventions: introduce composition (organization + technology layers). When teams need project-specific customization: add the team layer. The progression: matches organizational growth. Do not introduce composition before you need it — the simplicity of single files is valuable until the scale demands layers. AI rule: 'Single-file at 1-20 projects. Two-layer (org + tech) at 20-100. Three-layer (org + tech + team) at 100+. Match the complexity to the scale.'
A 5-person team with 3 projects: composition adds complexity without adding value. One CLAUDE.md per project: simple, sufficient, and maintainable. Introducing three layers, a central repo, and a composition pipeline: over-engineering for the scale. The simple approach: works until it does not. When it stops working (20+ projects, shared conventions need centralized updates): introduce composition then. Early composition: premature complexity. Late composition: a migration. Just-in-time composition: the right amount of complexity for the current scale.
Rule Composition Quick Reference
Quick reference for rule composition.
- What: combining multiple rule sources into one AI-readable file. Organization + technology + team → one CLAUDE.md
- Layer 1 (org): security, quality. Broadest scope, lowest priority. All projects inherit
- Layer 2 (tech): TypeScript, Go, Python conventions. Technology-scoped. Override org for tech-specific topics
- Layer 3 (team): project-specific patterns. Narrowest scope, highest priority. Override everything for conflicts
- Override: more specific layer wins. Team > technology > organization for conflicting rules
- Output: one file with all rules. Sections attributed to their source layer
- Tools: manual script (simplest), RuleSync (most features), git-based build (middle ground)
- When: 20+ projects or multiple tech stacks. Single-file is simpler and sufficient for small teams