Scoping and precedence

Read these first

• Agent configuration files (AGENTS.md, CLAUDE.md and equivalents)

What you will know

• Configure nested files in a monorepo and predict which one wins

  A reliable result depends on whether discovery is nearest-file, cumulative, or tool-specific; guessing from directory depth causes cross-package drift.

• Run a precedence test across user, project, and organisation layers and record the resulting value

  The observed result must distinguish replacement from merging, since a lower layer may survive for some fields but not others.

• Resolve a conflict between two layers deliberately

  A deliberate resolution requires choosing an explicit owner or merge rule instead of relying on incidental load order.

• Scope an instruction to a subdirectory

  A package boundary should prevent local conventions from leaking into unrelated directories while preserving inherited defaults where intended.

• Debug an instruction that is being ignored because it was overridden

  Tracing file discovery, layer order, and the final assembled configuration exposes silent overrides that logs often omit.

Chapters

1. 1

   Nearest-file and cumulative discovery predict opposite outcomes

   A root config demanding a changeset and `packages/internal-tools/` saying to skip it produces intermittent behaviour, which is exactly what cumulative discovery looks like: the local file added a second, contradicting rule rather than replacing the first. Nearest-wins is a convention borrowed from other systems, not a guarantee. Learn the five-minute check that tells you which model your tooling implements before you file a bug against it.

   Read chapter
2. 2

   Read the assembled configuration before believing the file

   When someone says a project instruction is being ignored, the first artefact is what that session actually assembled, not the file they wrote. The same view answers the previous chapter's question in five minutes: start a session inside the nested package and see whether the root text is present alongside the local text or instead of it. It is also how you explain the incident two engineers cannot reproduce and a third reproduces every time on the same commit — a personal user-layer entry applies to every session that person runs and appears in no repository anyone else can read. Make the assembled view one step, not five.

   Read chapter
3. 3

   A layer can lose one instruction and survive on another

   User, project and organisation layers may replace wholesale or merge field by field, and only the assembled result tells you which happened for a given instruction. Run the test with values you can recognise in the output. Note also that prose does not overwrite prose: an org rule and a project rule on the same subject can both be present, which is how a team's local instruction appears to silently disable a security requirement.

   Read chapter
4. 4

   An instruction loaded for the session travels into every package

   'Use `Result` types rather than throwing', added under `packages/checkout/`, starts turning up in unrelated packages because the text is loaded once per conversation and not re-evaluated per file. Directory scoping constrains discovery, not application. Learn to write local conventions so they name their own boundary, and to keep inherited defaults intact where the package genuinely wants them.

   Read chapter
5. 5

   Deliberate resolution means the losing layer says nothing

   With an org rule requiring conventional commits and a project rule imposing a local prefix scheme, leaving both in place makes the outcome depend on load order — an implementation detail that will change under you. Decide who owns the policy, then delete the other statement. Where the local rule is a genuine exception rather than a rival — a root rule demanding changesets against a package that is never published — neither layer can go silent, and the deliberate resolution is instead a single statement that names its own exception. Ordering is not enforcement: putting org rules last influences weighting and guarantees nothing, so a non-overridable guarantee has to be built outside the text.

   Read chapter
6. 6

   The guarantee the security team wants is a gate, not a sentence

   The previous chapter ends where most answers stop, on the claim that a non-overridable rule has to live outside the instruction text. What you actually build is a required review on any diff touching the authentication paths, a CI check that fails the change, or a gate on the tool call itself — mechanisms that hold whether or not the model weighted one paragraph above another on that run. Each costs something real: coverage limited to the paths you thought to enumerate, friction on legitimate changes, and an owner for a control the org layer never needed. Say which of those the security team is buying.

   Read chapter
7. 7

   A lint cannot detect that two sentences contradict each other

   Banning nested files entirely removes precedence ambiguity and removes genuine per-package convention with it. The popular compromise — allow nested files but lint that they never contradict the root — fails because 'skip changesets here' and 'always add a changeset' share no words, while innocuous overlaps trip the check. Ship a rule you can defend, and name the first thing that will go wrong with it.

   Read chapter