AGENTS.md as a routing table from task to place
Instead of prose rules, AGENTS.md opens with a two-column table. The agent finds the row for its task and reads only the file that row points to.
Reported by @juliandierker · Verified 2026-11-20
- Agent
- Claude Code
- Model
- claude-opus-5-5
- Stack
- TypeScript, Remix 3
Problem
A prose AGENTS.md about architecture, style and process gets read in full for every task, and the one line that matters for this task is easy to miss: schema changes need their own database branch, bug fixes start with a reproduction.
Setup
The file now opens with a table. Left column: the task. Right column: the one place to go. Everything else moved into the files the rows point to.

## If you do X, go here
| Task | Go to |
|---|---|
| Product, UI, design | `docs/brief.md` (follow its banned list) |
| Business rules | `web/app/domain/` (imports nothing outside domain/) |
| Schema change | new numbered migration, own Neon branch `agent-<topic>` |
| Bug fix | `/diagnosing-bugs` |
| Before committing | `vp check`, then `/cleanory` |Below the table sit only the hard rules, six lines, that apply to every task.
CLAUDE.md is one line, @AGENTS.md, plus three Claude-only notes.
What happened
Without it
Every task pays for every rule. The rule that applies sits somewhere in the middle of a long page, next to rules that don't.
With it
The agent matches its task to one row and opens one file. New rules land as a new row or inside the file a row points to, so the top file stays short.
Reproduce
Cut your AGENTS.md down to a
| Task | Go to |table plus at most ten hard rules.Move the details into the files the rows point to.
Give the agent a schema change and a bug fix, and check that its plan names the matching row.