# AGENTS.md: token-efficient agent work

Drop this into any repo where Claude, Codex or another coding agent does real work.
It keeps the expensive model on decisions and gives the rest to cheaper models.

## 1. Use the cheapest model that does the job well

| Job | Model tier |
|---|---|
| Watching: check whether something changed; answer "unchanged" or one line | Small (Haiku-class) |
| Scripted runs: a named script or command list; report the exit code and summary as-is. Never edits, reviews or decides | Small |
| Well-specified builds: small fixes with a named spec, plumbing on an existing pattern, docs | Mid (Sonnet-class), with self-checks |
| Design work: new modules, cross-cutting changes, anything touching auth, persistence or caching | Top model writes the spec; mid model builds it unit by unit and asks instead of improvising |
| Root cause after a failure; independent review | Top model, fresh context |

Name the model on every agent you start. Don't rely on the default.

## 2. Make the cheap tiers the workhorses

Each unit of work names four things: the model, the exact files or commands, what "done" means,
and when to stop and ask. A vague brief stops with a question. It doesn't move up a tier.

If you do a sequence twice, script it. Then a small model runs the script.

## 3. Don't pay to wait

- Wait with a background shell loop (`until <check>; do sleep 30; done`), not a model session.
  A long session re-sends its whole context every time it wakes up.
- Builds, test suites and renders run as background jobs that write a one-screen summary.
  Read the summary. Open the log only when the summary says to.
- Wake on events, not timers.

## 4. Keep context small

- Read big files with `grep` and `head`, not whole.
- A fresh agent with a short brief beats a long session kept alive.
- Near the context limit, write a handover note and start fresh instead of compacting.
- Reports are commit hashes, verdicts, numbers and paths. Ten lines or fewer.

## 5. Keep the structure flat

- Default to one loop that plans and does the work.
- Split off a worker only for independent parallel work, a fresh-context review,
  or to keep file dumps and long logs out of the main context.
- Lead, worker, fresh reviewer. No deeper than that.
- The reviewer gets the code, not the builder's reasoning. A cheaper builder makes
  the review more important, not less.

## 6. Re-verify, don't trust

- Re-run the proof yourself. Check that a review names the exact commit it reviewed.
- Read exit codes from the command, not from the agent's summary.
- Never print secrets or environment values, even in a failing test.

## 7. Check the split with numbers

Keep a small ledger per build: builder model, review verdicts, defects found later.
Every few builds, compare. If the cheaper model's numbers are worse for a kind of job,
move that job back up a tier and write down why.
