The Most Specific Rule Wins

One file can't hold the conventions of a whole monorepo without becoming a tangle of conditionals. Layer the files by scope and the conflict resolves itself — by position.

Why this, for you: last lesson shrank one file into a map. This one splits the map across scopes. When a project has a frontend, an API, and shared utilities with different conventions, a flat file forces the model to evaluate "if I'm in api/…" on every action. Layering replaces that conditional with an unconditional rule that simply wins.

A single root instruction file works for a small, uniform codebase. Scale up — multiple services, distinct frontend and backend conventions — and it either becomes an unmanageable list of conditionals that hits the ceiling, or fails to cover the cases that matter. Layering by scope is the structural answer.

1 Concentric scopes

Instruction files nest. OpenAI's Codex harness implements a three-scope hierarchy, and the same shape applies to any harness that reads files from disk:

Scope	What it holds
Global config	Defaults and preferences across all repositories
Git root	Project-wide conventions: test command, commit style
Working directory	Per-directory overrides: "use uv not pip here"

The harness traverses global → root → working directory, concatenating files in order of increasing specificity. The agent receives only the instructions appropriate to where it is working — no manual switching.

2 Priority is positional, not declared

When two layers conflict, the later one wins — and "later" means "more specific," because that's the concatenation order. There are no priority keywords.

A directory file saying use Bun, not npm overrides a root file saying

use
  npm

— for that directory and its children only. Global config provides defaults, the project root narrows them, the subdirectory overrides for its scope. Priority is implicit in the order, never declared.

3 Why position resolves the conflict

This is the same recency bias from Lesson 3, doing structural work. Instructions later in a prompt carry higher effective weight when they conflict with earlier ones. Concatenating general-to-specific exploits that property to produce scoped behaviour without conditional reasoning.

# A flat file makes the model evaluate a condition every time: "If in api/, use uv; otherwise use pip." # Layering replaces it with a later, unconditional rule: api/AGENTS.md: "Use uv." # wins by position

The conditional version can be evaluated wrong on any given turn. The layered version can't — there is no condition to get wrong.

4 Cap the assembled size

Layering has a cost: a file six directories deep inherits every ancestor. A few verbose ancestors saturate the budget before task work begins. Codex applies a 32 KiB default cap on assembled instruction content; if your harness doesn't, enforce the discipline manually — keep each file to 50–100 lines, prefer pointers over embedded content (Lesson 7), and audit the total for deep hierarchies.

When layering backfires

Layering assumes scopes are independent and that the harness respects concatenation order. It degrades when: tool support is inconsistent — some tools load only the root file, so rules written assuming full traversal are silently ignored; agents weight by relevance, not position — then a "directory wins" conflict can resolve unpredictably; and deep hierarchies bloat — inherited ancestors exhaust the budget before the specific rule lands.

↪ Your win: let scope do the resolving

Concatenate general-to-specific — global, then root, then each directory down to the cwd.
Most specific wins by position — no priority keywords; recency does the work.
Replace conditionals with placement — "use uv here" beats "if in api/, use uv."
Cap the assembled size — 50–100 lines per file; deep trees exhaust the budget first.
Confirm your tool traverses — some load only the root; full-traversal rules go unread.

Retrieval practice — recall, don't peek

Question 1Instruction files are concatenated in order of…

Question 2When two scopes conflict, the winner is decided by…

Question 3Layering beats a flat conditional file because it…

Question 4A real risk of deep directory hierarchies is that…

Question 5 · spaced recall from Lesson 7The test for whether a line belongs in AGENTS.md or in docs/ is whether it…

Ask me anything. Want to map your monorepo's conventions onto a scope hierarchy, or audit whether your harness actually traverses subdirectory files? Next in Part 4: Point at the Spec — using types, schemas, and tests as instructions that can't be misread.