The Router file, line by line: your agent's first read

Every AI coding agent reads one file first. Claude Code reads CLAUDE.md. Codex and others read AGENTS.md. Gemini reads GEMINI.md. Whatever the name, this file is the agent's front door — the first and sometimes only context it loads before it starts work.

In C² this file has a job and a name: the Router. Get it right and every session starts oriented. Get it wrong — and most people get it wrong the same way — and the agent quietly stops reading it. Here's how to write one that works, section by section.

What the Router is for

The Router has one job: point the agent to the right context for the task at hand. It's the living index of your contextbase — a short overview of the project plus links to where everything else lives.

The critical word is index. The Router is not where your knowledge lives. It's the map to where your knowledge lives. That distinction is the whole game, and it's the one almost everyone gets backwards at first.

The rule: it routes, it doesn't duplicate

The failure mode is irresistible: you start stuffing everything into the Router. Every rule, every convention, every gotcha, every decision — all into the one file the agent definitely reads. It feels safe. It's the opposite.

A Router that contains everything becomes a wall of text the agent skims and half-ignores — and that nobody keeps current, so it drifts out of date. The empirical research on context files for coding agents lands here too: the files that work are focused and point outward, not exhaustive dumps.

Stuart Leo

A good Router is a switchboard, not an encyclopedia. It points. It doesn't repeat.

The rule: route, don't duplicate. Detail lives in linked docs. The Router carries the overview and the pointers.

Section by section

A Router that earns its keep has roughly five short sections:

# Project Name — Router

One-paragraph overview: what this is, who it's for, the stack.

## Critical rules
The 3–7 things that must always hold. Not 30. The non-negotiables.

## Where things go
- PRDs / specs → docs/01-planning/
- Session briefs → docs/02-working/session-briefs/
- Gotchas → docs/03-knowledge/gotchas/

## Quick reference
Common commands: dev, build, test, deploy.

## Status
One line on where the project is + a link to the latest session brief.

• Overview — orient the agent in a paragraph.
• Critical rules — only the load-bearing ones. If everything's critical, nothing is.
• Where things go — the actual routing: pointers into the contextbase.
• Quick reference — the handful of commands the agent reaches for constantly.
• Status — a single line plus a link to the latest session brief, so the agent finds the current state in one hop.

Each section points outward. The detail is a click away, not pasted in.

The bloat trap and how to avoid it

The Router decays in one direction: it grows. Every time something goes wrong, the urge is to add a rule to the Router so it never happens again. Do that enough and you've rebuilt the wall of text.

The discipline: when you reach for the Router to add detail, ask whether it belongs in a linked doc instead. A new convention goes in a reference file, with a pointer from the Router. A trap goes in a gotcha file, with a pointer from the Router. The Router gains a line, not a paragraph. Keep it short enough that the agent reads all of it, every time.

Linking out to the contextbase

The Router's power is that it's the one stable entry point to everything else. From it, the agent reaches the brief for today's task, the gotcha for the file it's touching, the decision behind the architecture — by following links, loading only what the task needs. That's lazy-loading, and it's also how your context stays lean: the agent reads the index, not the whole library.

A good Router is a switchboard, not an encyclopedia — it points, it doesn't repeat.

Start here: see how to write an AGENTS.md that agents follow, the field note on a Router that got too big, or read the method.