# Choosing a Claude Code model and effort level

Claude Code exposes three choices this repo has an opinion on: which model a session itself
runs as, what model a spawned subagent gets, and which `/code-review` effort level to pick.
None of them are enforced anywhere - the gates in [instructions/gates.md](../instructions/gates.md)
are code precisely because a model cannot be talked out of them
([why-gates-are-code.md](why-gates-are-code.md) makes that argument for gates; this page applies
the same axis to who is holding the keyboard). What follows is a reference for making that choice
well, not a rule anything checks.

The axis worth tracking is not how important a task feels, but **what would catch a mistake in
it**. Work behind `pytest`, `docs verify`, `instructions verify` or CI surfaces a bad call within
one more round. Work behind nothing but a session reading prose does not surface at all - it
ships, and stays until someone happens to notice. That asymmetry, not task size, is what the
phase guide below is built on.

## Phase guide

<!-- dist:strip-start -->
This repo's own stack-development work splits the axis into three phases, one per switch point
in its `stack-dev`/`stack-close` skills:

<!-- dist:strip-end -->
| Phase / task | What would catch a mistake | Suggested model | Effort |
|---|---|---|---|
| `wiki-status`, simple `wiki-query` lookups | the answer is re-checkable against the corpus | Sonnet | default |
| `wiki-lint` | `lint` itself is the check | Sonnet | default |
| `wiki-ingest`, `wiki-manage`, judgment-heavy `wiki-query` | `lint` and `docs verify`, partly | Sonnet | high |
| Stack dev: design, the version part, a boundary-crossing judgment | nothing mechanical | Opus | high |
| Stack dev: code, tests, mechanical doc sync | `pytest`, `docs verify`, `instructions verify`, CI | Sonnet | high |
| Stack dev: closing an issue, `docs/` staleness, changelog prose | nothing, by construction | Opus | high |

The middle stack-dev row is where the tokens are and where the checks are, so it is the one worth
running cheaper. The two rows around it are short - minutes, not hours - so keeping them on the
stronger model costs little and protects the only work in the session that fails silently.

**Effort is the cheaper lever than the model.** A reduced effort level is what gives up
multi-file consistency first, so `high` is a reasonable floor for anything touching more than one
file or a contract; `default` suits a single-file mechanical edit with a test behind it.

A session cannot switch its own model - that is the user's `/model` - so this table only pays off
if someone offers the switch at the moment a phase changes, once, without turning it into a
debate.

## Subagent models

The `Agent` tool's `model:` parameter (`haiku`, `sonnet`, `opus`, `fable`) is a per-subagent
choice a session *can* make on its own:

- Read-only search/lookup (an `Explore` agent, or a `general-purpose` agent doing pure
  retrieval): `haiku` - no judgment is being delegated, only retrieval.
- A subagent that writes pages, reviews code, or decides something: leave `model:` off so it
  inherits the parent session's model.
- A fork (`subagent_type: "fork"`) always inherits the parent's model; a `model:` override on a
  fork is ignored.

## `/code-review` effort

- A routine diff: `low` or `medium` - fewer, high-confidence findings are enough.
- Gate code, the compiler, or a change about to ship in a version bump: `high` and up - broader
  coverage is worth it when the blast radius of a missed bug is a safety gate.
- `ultra` is user-triggered and billed separately - worth recommending, not assuming.

## When it's unclear

- A task spans both a mechanical step and a judgment call: weigh it by the judgment call, not the
  mechanical one - the tooling carries the mechanical part regardless of which model supervises.
- No row fits cleanly: Sonnet at high effort is a safer default than the most capable model at
  the highest effort. Under-provisioning where a check exists costs one worse answer once;
  reflexively over-provisioning is a standing cost every session pays.
- Not sure whether a phase is checked: treat it as unchecked - a needless Opus phase costs money
  once, an unchecked Sonnet phase can ship something nobody looks at again.
- Mid-session and the phase changed but nobody switched: keep working - never block a publish or
  an issue close on a model the session cannot change itself. Naming which model ran which phase
  in the handover keeps the gap visible instead of silent.

## Scope

Specific to Claude Code: the model names, the `/code-review` dial and the `Agent` tool's `model:`
override have no equivalent in this repo's other supported harnesses (Codex CLI, GitHub Copilot
CLI, Mistral Vibe). Does not set the classifier model behind Claude Code's own `auto` permission
mode - that is a harness internal, not a per-task choice this repo controls.