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.mdis 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.
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:
| 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.
| 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
- 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.
- 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.
- 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:
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.