Rule Layering: User > Project > Framework

You start with a framework. The framework ships default rules. Your project adds its own. Someone on the team adds a personal preference. Three sources of rules exist, each loaded on every agent turn, and nothing explicitly says which one wins when they disagree.

Before I had a precedence system, I'd see agents follow my personal preference ("use British English") in one session, the project rule ("match the existing codebase") in another, and the framework's default ("prefer American English") in a third. Same model, same codebase. Different answer. The agent was cherry-picking from an ambiguous rule set, and the pick wasn't reproducible.

The one thing to take from this post: every rule you add needs a layer, and every layer needs a precedence number. Ambiguity between layers is bugs you can't reproduce.

The three layers

The system I settled on:

LayerWhereLoaded forOverrides
1. User global~/.config/devin/AGENTS.md + ~/.config/devin/rules/every sessioneverything below
2. Project<repo>/AGENTS.md + <repo>/.devin/rules/*.mdsessions in that repolayer 3
3. Framework<framework>/skills/, <framework>/rules/, .bread-kit/always—

Precedence rule: user > project > framework. A conflict is resolved by taking the highest-priority value. Each layer's rules can add to a lower layer or override a specific rule, but nothing silently merges.

What a layered rule file looks like

Rule file snippet from layer 2 (project):

 1# Pseudocode: shape of a project-layer rule file
 2# Project rules (ic-core)
 3
 4## Overrides from layer 3
 5- `test.framework`: JUnit 4 (framework default is JUnit 5 — this repo isn't migrated yet)
 6- `naming.booleans`: `isX` or `hasX` (framework default is `isX` — adds `hasX`)
 7
 8## Additions
 9- Database schemas named in `SysSecurity`, `Client`, `LprsGlobal` are canonical;
10  don't invent new ones.
11- Transactions use `investmentcafe.ngs.util.Transactional`, not Spring's or Jakarta's.

The "Overrides from layer 3" section is explicit. An agent reading this file knows exactly what the project is saying no to. Nothing is implicit. Nothing is "surprisingly" different from the framework.

The three failure modes layering prevents

1. Silent override. Without layering, a project rule can accidentally neutralize a security or safety rule from the framework. Layering forces the override to be named. If a project file reads "disable confirm-before-destructive", it's visible — and a code review can push back.

2. Rule drift between repos. Six repos, each slightly different. Without layering, the framework rules "feel the same" but have been locally adjusted everywhere. Layering lets the framework update once, and every repo picks it up automatically. Only the overrides stay local.

3. Personal preferences in a team repo. My preference for a specific git commit style is mine — it shouldn't go in a project file where other devs' agents will inherit it. Layer 1 (user global) is where it belongs. Agents on the same repo now behave consistently per-user, not per-repo.

Enforcement

Three practical details that made layering actually work:

Validation script. validate-rule-layers.py reads every rule file and checks:

  • Each override is annotated with the layer it overrides ([overrides layer 3]).
  • No two rules at the same layer contradict each other.
  • No rule at layer 3 (framework) contradicts another at layer 3.
  • Deprecated rules are tombstoned, not silently removed.

Fails CI if any check fails. A silent override added by a PR fails the build.

Precedence hint in the system prompt. The agent's boot sequence includes a one-line reminder: "When rules at different layers disagree, follow the higher layer (user > project > framework)." That line costs ~15 tokens and reliably prevents cherry-picking in the hard cases.

No layer-skipping. A rule can only override the layer immediately below it or at the same level. Layer 1 can't bypass layer 2 and claim precedence over layer 3 differently from how it treats layer 2. Keeps the mental model simple.

When this bites

Three real cases where layering changed the outcome:

  • Rule: "Always run tests before committing." Framework default. I'm in a session where the tests are flaky and I know it. Layer 1 override: allow-skip-tests: true with a comment explaining the local flake. Framework stays strict; my sessions proceed.
  • Rule: "Prefer @Autowired field injection." Project default on a legacy repo. Framework default (newer) says constructor injection. The project override is named; new modules in the same repo can carry [overrides layer 3]: @Autowired on files that already use it, but new files follow the framework. Mixed codebase stays coherent.
  • Rule: "Default to 4-space indent." Framework. One repo uses tabs. The project rules/indentation.md overrides to tabs with a one-sentence justification. Every agent session in that repo reads the override. The agents stopped reformatting the whole file on every edit.

What not to put in which layer

  • Security rules → framework. Never let a project override "don't log secrets" or "confirm before rm -rf." These rules are deliberately below the override surface.
  • Codebase-specific conventions → project. "Use JUnit 4," "pool naming," "transaction type" — anything tied to this repo's history.
  • Personal taste → user global. Commit message style, local tooling, review tone. Nothing that other developers should inherit by default.

When layering is overkill

Two cases where layering hurts more than it helps:

1. Single-developer, single-repo projects. If you're the only user and there's only one project, you have two "layers" — the framework and your own additions — and no team-wide coherence problem to solve. Flat rules are faster to reason about.

2. Rapid-prototyping agents. When you're iterating on the agent itself week-to-week, layered rules add friction. Flatten first; add layering once the rules stabilize.

The pattern pays off at team scale (multiple devs, multiple repos, long-running agent). For hobby projects, don't bother.

The dashboard view

Rule layering precedence: User over Project over Framework. For a max_retries conflict where User says 2, Project 3 and Framework 5, the User value of 2 wins

Every time the validation script runs, it emits a layer summary:

Framework: 143 rules
Project (ic-core): 28 rules (12 overrides, 16 additions)
User (markon): 7 rules (3 overrides, 4 additions)
Conflicts caught: 0

That bottom line is the one I check. A conflict means an override wasn't named explicitly, and the fix is a one-line annotation. Four months in, we average one caught conflict per PR touching rules — exactly where I want it to be.

Attribution: The patterns and specific numbers in this post come from Devin with the ic-documentation agent framework my team maintains — not from an independent reproduction. See the series intro for the full disclosure. The patterns themselves generalize to any coding-agent setup.

Up next: The 2-retry limit — how to stop an agent from burning tokens on the wrong error (coming soon).