# Model tiering: standing rule for a Claude Code agent

Everything below this line is written for the agent. Paste it into the project's `CLAUDE.md`
(or the agent's system instructions). Section B is config the agent can apply to its own setup.

---

## A. How you route models

You route work to models by the kind of work, automatically. Nobody will tell you to save
tokens and there is no phrase to wait for. Cheaper-by-default is the standard, not a mode.

1. **Your main session runs on the strongest model available.** That is where you reason,
   plan, and decide. Never downgrade it.

2. **Everything you spawn defaults to Sonnet.** That means every Agent-tool sub-agent, every
   worker, every background task, every loop, every scheduled job. Do not pass a stronger
   model to a spawned job by habit. Summaries, classification, and log or transcript reduction
   go one tier lower, to Haiku, because their output is checked by reading it against the
   source, not by which model wrote it.

3. **Five kinds of work keep the strongest model with no justification needed:**
   - reasoning, planning, and strategy in your main session;
   - image and video creation (rendering, editing, composing);
   - the definition of website design (information architecture, wireframes, layout, design
     system, visual direction); implementing that design in code goes to the cheap tier;
   - prose a human will read (client email, articles, social posts, newsletters, reports);
   - judging quality (QA gates, scoring, design and copy reviews), because a weaker judge
     passes weaker work.

4. **Anything else that wants the strongest model must say why, in one line, in the spawning
   prompt:** `judgment: <reason>`. No line, no upgrade. Every such override is logged so the
   spend is visible later. Before spawning ten helpers on the strong model, ask whether even one
   of them is doing thinking. Usually none are.

5. **Effort follows the same map as the model.** Run high effort in your main session and on
   the five jobs above, where the answer depends on wrestling with ambiguity. Run medium effort
   on Sonnet implementation work. Run low effort on Haiku reductions and summaries, where a test,
   a diff, or a re-read decides correctness anyway. High effort on a mechanical job is tokens
   wasted; low effort on a judgment call is a wrong answer arrived at quickly.

6. **Report weekly:** calls by the model that actually ran, how many were downgraded, how many
   opted up with `judgment:`.

## B. Config that makes it mechanical (apply if not already set)

A rule you have to remember is a rule you will break. Make these true in the project, then the
routing happens whether anyone remembers it or not.

- **Default spawned model.** In `settings.json`, set the environment variable
  `CLAUDE_CODE_SUBAGENT_MODEL=sonnet`. Every Agent-tool sub-agent now runs on Sonnet unless
  explicitly told otherwise. Precedence is: an explicit model argument, then an agent
  definition's `model:` frontmatter, then this variable, then the session model.

- **A gate that rewrites.** Add a `PreToolUse` hook on the `Agent` tool. When the call's model is
  the strongest model or is omitted, and the prompt does not contain a `judgment:` line and the
  work is not one of the five reserved jobs above, the hook returns `hookSpecificOutput.updatedInput` with
  the model set to `sonnet`, and appends the decision to a log file. The only way past the gate
  is the one-line reason. Hooks reference: https://code.claude.com/docs/en/hooks

- **Per-agent definitions.** In each `.claude/agents/*.md`, set `model: sonnet` (or `haiku` for
  reduction agents) and `effort: medium` (or `low` for reductions) in the frontmatter. These
  override the session for that agent's runs.

- **Pin every scripted job.** Every `claude -p` invocation in a cron, a script, or a scheduler
  carries an explicit `--model haiku` or `--model sonnet` and an explicit `--effort low` or
  `--effort medium`. Headless runs do not read your interactive settings; the flag beats the
  setting. Add a check that flags any new `claude -p` line without a pinned model.

- **Session effort.** Set `effort: high` in `settings.json` for the interactive session, so the
  reasoning and planning you do in the main session get the full model.

- **Where things are documented.** Subagents and their model selection:
  https://code.claude.com/docs/en/subagents. Settings keys: https://code.claude.com/docs/en/settings.