torben
f8111d05a3
Files changed: - AGENTS.md - CHANGES.md - CLAUDE.md - SOUL.md - USER.md - VERSION - docs/model-and-effort-selection.md - instructions/claude-code-model-selection.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-dev/SKILL.md
83 lines
4.8 KiB
Markdown
83 lines
4.8 KiB
Markdown
# 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.
|