The Context Hierarchy
Context Management is about what's in the window this turn — assembling, compacting, and persisting context at runtime. Grounding is the other half: the durable, authored knowledge an agent can't infer from the code, written down once so it can be assembled or retrieved on every task. That knowledge has a natural hierarchy, and getting the tiers right is what separates an agent that guesses at your project from one that works inside it.
Information that doesn't exist in the repo doesn't exist for the agent. An agent's entire world is its prompts, the files it can read, and its tool output — so anything it must know has to be written down somewhere it will look.
Four tiers, each answering what the one below can't
Read the nesting outward: a file sits inside a repo, inside a system, inside the org. Each tier is nested in the next. A file grounds one set of rules; a repo's .agents/ grounds everything one repo's agents can't infer; a system's parent .agents/ grounds the contracts between repos; the org context layer grounds knowledge across every team. You climb a tier exactly when the tier below can no longer hold what the agent needs to know.
AGENTS.md / CLAUDE.md at the repo root: the entry router that names the stack, the run and verify commands, and the few non-negotiable rules. It works until it becomes a monolith — which is why it must stay a short router that points to detail on demand..agents/ describing the whole system — the boundaries and contracts between services that no single repo can know. Cross-repo grounding without the monorepo migration.Authored, then retrieved
The first three tiers are authored: plain markdown a human writes and versions in git, assembled into the prompt by the context assembly layer. They're cheap, reviewable, and exact. The fourth tier is retrieved: there's too much org knowledge to paste into every prompt, so it gets chunked, embedded, and pulled in on demand by RAG.
The crossover is the whole design decision. Author for as long as the knowledge fits in a handful of files an agent can read in full — that's most repos and many systems. Reach for retrieval only when the corpus outgrows the window, because an index adds real machinery (chunking, embeddings, freshness, reranking) that a markdown file in git does not.
The authored tiers are no longer a personal convention — the industry has standardized on them.
The same three rules at every tier
The tiers differ in scope, not discipline. Whether you're writing one AGENTS.md or operating an org-wide index, the rules are identical:
Only what can't be inferred
signal
If an agent could read it from the code, leave it out — it’s noise that burns budget. The value is the non-obvious: the encryption choice, the boundary rule, the migration that burned you once.
Route it to who needs it
precision
Don’t broadcast one monolith to every agent. Split by concern and route by role so each agent — or each retrieval — loads exactly its slice and nothing else.
Keep it true
freshness
Stale context is worse than none: it leads agents to confident wrong assumptions. Updating the grounding is part of the change that invalidates it, not a cleanup for later.
These are the same instincts the run loop depends on at runtime — the difference is that grounding is where the knowledge lives between runs, and the hierarchy is how it scales from one file to an entire organization.