chemenu/docs/model-and-effort-selection.md

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 are code precisely because a model cannot be talked out of them (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

This repo's own stack-development work splits the axis into three phases, one per switch point in its stack-dev/stack-close skills:

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.