Home / Writing / Automation

What Goes Where: Layered AGENTS.md Files and Tiered Model Routing

2026.11.17 · Automation
What Goes Where: Layered AGENTS.md Files and Tiered Model Routing

Spend enough hours a week in AI coding agents (GitHub Copilot, Claude Code, Codex) and you start wondering where the usage meter went. My first suspect was the instruction files. My multi-repo Git folder had grown a zoo of AGENTS.md, CLAUDE.md and .github/copilot-instructions.md files, several repeating the same PowerShell 5.1 gotchas and scope rules word for word, one of them 18 KB long and loaded on every turn.

Cleaning that up was worth doing, but the arithmetic showed the files were a small part of the bill. This post covers both halves: a five-layer instruction hierarchy that decides what goes where and when it enters the context window, and an explicit three-tier model routing contract, which is where the money actually is. A generalized starter kit is on GitHub Gist and mirrored on this site.

What one big instruction file really costs

One day I write PowerShell 5.1 customizers and Bicep modules for Azure Virtual Desktop; the next it is a Rust and Flutter log viewer (Tracehound, AIBHound), interactive HTML documentation or a WinDbg dump review. When every lesson is appended to one top-level file, three things go wrong:

  • Adherence drops. A session editing a Bicep parameter file has no use for WPF runspace traps or Flutter test rules, and the model has to weigh them anyway. Anthropic's own guidance for CLAUDE.md is blunt about it: longer files consume more context and reduce adherence.
  • Rules drift across copies. A rule against duplication copied into six repositories is the defect it warns against. Tighten it after an incident and five repositories keep the stale version.
  • Hard boundaries drown in checklists. When "never probe a live API by writing to it" sits next to indentation preferences, both start to read as suggestions.

Tokens are the smaller problem: as the numbers further down show, an 18 KB file costs a few percent of a long session.

The five layers: what goes where

Current harnesses already provide the primitives. The trick is giving each layer one job and never repeating a rule further down.

Diagram of the five instruction layers: L1 global policy (always loaded, about 2 KB), L2 workspace root (linked, about 2 KB), L3 repository entrypoint (per repository, about 2 KB), L4 path-scoped rules and subagents (loaded on a path match only), and L5 skills, specs and memory (loaded on demand only).
The five layers by scope and load cadence. L1 to L3 are in every turn, so they stay short; domain checklists move to L4 path rules and L5 skills.

L1, global policy (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.copilot/copilot-instructions.md) holds only rules that are true everywhere: flag unverified claims, treat agreed scope as a hard boundary, update every consumer of a shared helper, never discover a live API schema by writing to it. No frameworks or model names.

L2, workspace root (~/Projects/Git/AGENTS.md, a folder of sibling repositories, not a repository itself) holds the model routing table, cross-repo isolation (never commit into a sibling without being asked) and shared traps, such as editor buffers overwriting on-disk edits, or why git stash is banned when worktrees run in parallel: refs/stash is shared by all of them.

L3, repository entrypoint (<repo>/AGENTS.md) is short enough to read in ten seconds: what the repository builds, its stack, its branch and review rules, its protected surfaces and the exact commands that gate a commit, plus a read order for the layers above.

# Repository Agent Entrypoint (Layer 3)

Read, in this order, before non-trivial work:
1. `~/.claude/CLAUDE.md` — Layer 1 global engineering & anti-duplication policy.
2. `../AGENTS.md` — Layer 2 workspace model routing & cross-repo rules.
3. Matching path-scoped rules for the files you touch.
4. `docs/ARCHITECTURE.md` (and active `docs/specs/*.md` if assigned a slice).

Each harness finds these files differently

Codex starts at the Git root and Copilot reads files inside the repository, so neither picks up ../AGENTS.md when you open a child repository; the read order above is what brings it in. Claude Code does load CLAUDE.md from every parent directory, and it can skip a file it is merely told to read. In a CLAUDE.md, use an @../AGENTS.md import instead of a sentence. An imported file is still loaded on every turn, so the always-on budget covers it.

L4, path-scoped rules and subagents is where the domain checklists live. Each domain gets a file that loads only when a matching path is touched:

---
applyTo: "**/*.{ps1,psm1,psd1,bicep,tf,tfvars,hcl}"
---

# PowerShell 5.1 & IaC Rules
- Windows PowerShell 5.1 baseline: no `??`, `?.`, ternary, `&&`, `||`, or `-Parallel`.
- UTF-8 with BOM required: `WriteAllLines()` strips BOM in PS 5.1; use
  `[System.IO.File]::WriteAllText($path, $content, [System.Text.UTF8Encoding]::new($true))`.
- Never add `.GetNewClosure()` to WPF/DispatcherTimer handlers (loses `$Script:` scope).

Edit a Rust file and these rules stay out of the context; open a .ps1 and every one of them is there before the first edit. Next to them sit four subagent profiles (explorer, investigator, builder, verifier), each with an explicit model: and tool list.

L5, skills, specs and memory: long templates, feature specs and dated handoffs stay out of the prompt until a task calls for them. Durable lessons go into the harness's memory store rather than into competing MEMORY.md files in every repository.

The file names differ per harness. This is where each layer lives in the three I use, as of November 2026:

Where each layer lives
Layer GitHub Copilot Claude Code Codex
L1 global ~/.copilot/copilot-instructions.md ~/.claude/CLAUDE.md ~/.codex/AGENTS.md
L2–L3 project .github/copilot-instructions.md, AGENTS.md (the nearest one wins); the CLI also reads CLAUDE.md CLAUDE.md in the working directory and every parent; AGENTS.md only where there is no CLAUDE.md AGENTS.md from the Git root down to the working directory, 32 KiB combined by default
L4 path rules .github/instructions/*.instructions.md with applyTo: .claude/rules/*.md with paths:; nested CLAUDE.md files load when that folder is touched No globs; a nested AGENTS.md applies when Codex runs in that folder
L4 subagents .github/agents/*.agent.md .claude/agents/*.md Check your version's documentation

Three-tier model routing: stop paying architect rates for grep

The second lever is model assignment, and here the price gaps are real. At Anthropic's list prices in November 2026, input to Claude Opus 5.5 costs $4 per million tokens, Sonnet 5.5 $2 and Haiku 5.5 $0.10 (for prompts under 100,000 tokens). Moving work one tier down halves it; moving it to the bottom tier makes it forty times cheaper. Yet many setups still spawn subagents with no model:, so every file search and test run inherits the most expensive model in the session.

Workspace three-tier model routing contract
Tier Model class (examples) Owns directly Never used for
Tier 1, architect Top reasoning model (Claude Opus or the top GPT or Gemini tier), pinned, with no silent fallback Scope and planning, architecture, ambiguous root causes, safety-critical math, security and migrations, shared contracts, subagent briefs, review of every diff Broad file searches, boilerplate edits, formatting, watching test runners
Tier 2, scoped judgment Workhorse coding model (Claude Sonnet, mid-tier GPT or Gemini) Multi-file investigation and doc or schema checks (investigator); UI, scripts, IaC and deterministic tests from a tight Tier 1 brief (builder) Open-ended redesigns, protected contracts, quiet scope growth
Tier 3, fast explorer Fast lightweight model (Claude Haiku, Gemini Flash) Read-only symbol and call-site mapping (explorer), bulk extraction, mechanical edits, running linters and test gates and reporting exit codes (verifier) Architectural trade-offs, subtle diagnosis, speculative fixes

Rules that keep the cheaper tiers honest

  1. No silent fallback on Tier 1. Classify work by consequence, not diff size. A three-line change to a financial formula, a UEFI certificate check or an authentication gate stays on Tier 1, and waits rather than falling back to a weaker model when Tier 1 is rate-limited.
  2. The brief test. Before delegating, ask whether you can write a brief tight enough (exact files, the helpers to reuse, the invariants, the verification command) that the cheaper tier's diff would match the tier above. If the shape of the problem is still unknown, it stays up.
  3. Count cost per finished task. Delegation is not free. Each subagent starts cold, prompt caches do not carry across models, and a summary handed back loses detail. Running the top model at lower effort is sometimes cheaper than a cascade; a cheap tier that needs three retries is not cheap.
---
name: verifier
description: Tier 3 deterministic check runner. Executes linters, AST checks, and test suites and returns literal exit codes without polling loops.
tools: [grep, glob, view, powershell]
model: <tier-3-fast-model>
---

You are the Tier 3 deterministic verification agent.
- Capture and report literal exit codes (`$LASTEXITCODE` / `$?`); never mask exit
  codes by piping through `tail` or `Select-Object -Last`.
- Never sit in polling loops on background jobs you cannot observe — if a runner
  stalls or is inaccessible, report immediately and return.

Where the tokens actually go

The polling rule in that file comes from a real post-mortem. Three subagents finished their edits in minutes and then burned between 200,000 and 330,000 tokens each re-reading status output while they waited on a shared job they could not observe. The code was cheap; the waiting was almost the whole bill.

That is the general pattern: an agent resends the whole conversation every turn, and the conversation grows with each file read and command run, while the instruction files stay the same size:

Stacked bar chart of input tokens per turn in a modelled 60-turn agent session. The harness prompt stays at 18,000 tokens and the instruction file at 4,500 tokens, while the conversation grows by 2,500 tokens per turn to about 148,000 at turn 60. The instruction file's share of each turn falls from 20 percent at turn 1 to 10 percent at turn 10 and 3 percent at turn 60.
A modelled session, not a measurement: an 18,000-token harness prompt (assumed), an 18 KB instruction file (about 4,500 tokens), 2,500 new tokens and 700 output tokens per turn, Claude Opus 5.5 list prices with prompt caching.

Over the whole 60 turns, the 18 KB file is 2.7 % of the cost with prompt caching and 4.5 % without. Cutting the always-on layers to 6 KB saves 1.8 % and 3 % respectively. In a short eight-turn subagent run the file weighs more, and trimming it saves about 5 %. Worth having, but it is the adherence argument that justifies the layers, not the bill.

The large levers are the ones that change the tall bars. Delegating exploration and test runs to a subagent keeps their raw output out of the main session's context, and a Tier 3 subagent reads it at a fortieth of the price. Compacting or restarting long sessions resets the growth. And Tier 1 reviewing the resulting git diff, rather than the whole exploration, keeps the quality bar where it matters.

Check your own numbers before trusting mine: Claude Code shows the context breakdown with /context and spend with /cost, and GitHub Copilot has billed by tokens since June 2026, so the same arithmetic applies there.

Grab the starter kit

The kit holds nine generalized files: a README, the three always-on layers, a PowerShell and IaC path rule and the four subagent profiles. Machine-specific paths are removed and model IDs are placeholders you map to Copilot, Claude Code or Codex. Get it as the GitHub Gist or file by file from this site, starting with the README.md.

Start by cutting your root AGENTS.md down to what is true for every file in that repository, move the noisiest domain checklist into a path rule, and put an explicit model: on every subagent. The context gets quieter immediately, and the frontier quota stays available for the bugs that earn it.