# Model routing by evidence, not brand

URL: https://developertoolkit.ai/en/developer-scorecard-guide/model-routing/
Description: Route each class of agent work to a model and effort level your own evals picked: a dated routing table, per-tool config, and a before-and-after test.

Model routing is a versioned rule that assigns each class of agent work (exploration, implementation, review, bulk edits) to a model and effort level chosen by repository-specific evals. Start on the tool's default model, tune effort before switching, and change a route only when accepted-task quality holds at lower cost or latency.

Three developers on your team use three different models, and nobody can say which one produced last week's bad migration. One teammate switched to the most expensive model for everything after a single impressive session. Another runs the cheapest one and quietly reruns failed tasks three times. This page is for the **developer** who builds the routing table and the **tech lead** who owns it and signs off every change to it.

> **Scorecard Q3 · Plan:** How do you choose a model and runtime for each task?
>
> **Maximum-score answer (3 points):** "I route task classes with versioned evals and review quality, latency, failures, and completed-work cost."

## What a model routing policy gives you

- A dated routing table in `docs/ai/model-routing.md` that names one model and effort level per task class, and a fallback.
- The same routes wired into Claude Code, Codex, and Cursor configuration, so nobody copies a model name into a prompt.
- A before-and-after eval run that justifies each route with pass rate, retries, latency, and cost per accepted task.
- Four copy-paste prompts: classify your work, run a candidate, compare results, and draft the routing change.
- A recovery path for the day a model is retired, renamed, or starts refusing a task class.

Current model names, prices, and context windows live on one page, the [AI model comparison guide](/en/ecosystem/models/). This page names models only in its dated example and links there for the numbers.

## Why start on the default model and tune effort first?

The rule this site follows is: **start on the tool's default model, tune effort before switching model, and switch model only when your own evals say so.** The default is the model each vendor tells you to start with, and effort is a cheaper, reversible lever than a model switch.

As of 2026-10-12 the defaults are:

| Tool | Default model | Default effort | Caveat |
| --- | --- | --- | --- |
| Claude Code | Claude Opus 5.5 | `medium` | From v2.1.280, on both release channels (checked 2026-10-12). Microsoft Foundry sessions default to Claude Sonnet 4.5, which Anthropic retires on 2026-11-30 on Anthropic-operated platforms. |
| Codex | GPT-6.1 Sol | `low` | Bundled default since CLI 0.159.1 (2026-09-29); GPT-6 Astra was the default from 0.153.4 (2026-09-04). The server can override it for signed-in accounts. |
| Cursor | No single default; Hobby uses Auto | Not stated | Cursor names no single default model (models and pricing page, checked 2026-10-12). Read the model picker in your own account and record what it shows. |

Two consequences follow. First, raise effort on the default model (`medium` to `high` or `xhigh` in Claude Code, `low` to `medium` or `high` in Codex) before you evaluate a more expensive model. Second, confirm the release channel and provider before you compare two developers' results, because the same command can start on different models.

## Which task classes need their own route?

Route by task class, not by person or by mood. A class earns its own route when its success criterion differs from the others. Most repositories need four to six classes. The example below is a **starting hypothesis** built from the vendors' own positioning on 2026-09-26, not a result. Replace every cell with what your evals show.

| Task class | What decides the route | Example starting route (2026-10-12) | Fallback | Measure |
| --- | --- | --- | --- | --- |
| Repository exploration | Relevant files found, speed | A read-only subagent on Claude Haiku 5.5 or GPT-6 Luna | The session's default model | Relevant files found vs. a known list, latency |
| Implementation | Diff accepted after gates | Default model at default effort: Claude Opus 5.5 or GPT-6.1 Sol | Same model, one effort level higher | Gate pass rate, retries, cost per accepted task |
| Long-horizon or hardest reasoning | Task finished without human rescue | Claude Fable 5.1 chosen by hand, or GPT-6 Astra at `max` | Split the task and rerun on the default | Completion without intervention, cost per task |
| Review | Real defects found, few false positives | A different session, and a different model where evals show it finds more | A human specialist | Accepted findings, false-positive rate |
| Bulk mechanical edits | Correct edits at volume | Claude Sonnet 5.5 or GPT-6 Luna | Default model on the failed files only | Gate pass rate per file, cost per file |
| Regulated data | Approved provider, region, retention | The policy-approved route only | Human-only path | Policy violations (target: zero) |

Two rules keep the table honest. A quality threshold must pass before cost or speed can decide between candidates. And a flagship model can be cheaper per accepted task than a small one if it avoids retries, so compare **cost per accepted task**, never price per token.

## Run a before-and-after routing eval

Run this for one task class at a time. Budget at least three runs per task per candidate: a 10-task set with a baseline and one candidate is 60 runs. If you do not have an eval set yet, [build one from merged pull requests](/en/ecosystem/models/benchmarks/) first.

1. **Freeze the harness.** Record the CLI version, `CLAUDE.md` or `AGENTS.md` commit, skills, and MCP servers. A route compared across two harness versions tells you nothing about the model.

2. **Pick 10 to 20 tasks for the class.** Each task needs a base commit and a grader script that exits `0` on success: tests the agent cannot see, the type checker, the linter, and a scope check on touched files.

3. **Run the baseline and each candidate three times per task, in a disposable worktree.** Use the same prompt for every run. One run per task hides the variance that makes a cheap model look good.

4. **Grade with code, then record the sheet below.** Pass rate first. Only candidates within your quality threshold of the baseline move on to cost and latency.

5. **Open a pull request that changes `docs/ai/model-routing.md` and the tool config together.** Attach the results sheet. The tech lead reviews the numbers, not the prose, and merges.

To run the candidate matrix from one config instead of shell loops, use promptfoo (npm `promptfoo`, 0.123.1 on 2026-09-26), which supports Claude Code and Codex as providers: run `npx promptfoo@latest init`, then `promptfoo eval` and `promptfoo view`.

The commands differ by tool. Each run below is headless, stays inside the repository, and writes a machine-readable result.

**Claude Code**

```bash
# Terminal, inside a throwaway worktree for one task
claude -p "$(cat evals/implementation/task-07/prompt.md)" \
  --model claude-opus-5-5 --effort high \
  --permission-mode acceptEdits \
  --allowedTools "Bash(npm test *)" "Bash(npx tsc *)" "Bash(npm run lint *)" \
  --max-budget-usd 5 \
  --output-format json > runs/task-07-opus55-high-run1.json
./evals/implementation/task-07/check.sh "$PWD"; echo "exit=$?"
```

The JSON result includes `total_cost_usd` and a per-model cost breakdown. Both are client-side estimates, so reconcile them with your usage dashboard monthly. Swap `--model` and `--effort` for each candidate.

**Codex**

```bash
# Terminal, inside a throwaway worktree for one task
codex exec -m gpt-6-sol -c model_reasoning_effort="medium" \
  -c default_permissions=":workspace" \
  --json -o runs/task-07-sol-medium-run1.txt \
  "$(cat evals/implementation/task-07/prompt.md)" > runs/task-07-sol-medium-run1.jsonl
./evals/implementation/task-07/check.sh "$PWD"; echo "exit=$?"
```

`--json` prints the run as JSONL events; sum the `usage` field of the `turn.completed` events for token counts, and `-o` keeps the final message. Permission profiles such as `:workspace` are beta (Codex CLI 0.138.0 and later); do not combine them with `--sandbox`.

**Cursor**

Cursor names no single default model (checked 2026-10-12), so run Cursor evals where you can script them: the `@cursor/sdk` package requires a `model` for every local agent and lists the IDs your account can use with `Cursor.models.list()`. Record the ID the call returns, never a name from memory. Grade with the same `check.sh`.

**A stronger model does not get more authority**

Run every candidate with the same permissions, tools, and credentials. A route changes which model does the work, never what the work is allowed to touch. Production access, merge rights, and secrets stay behind their own gates.

### Record every run on one sheet

```yaml
# evals/results/2026-09-26-implementation.yaml
date: 2026-09-26
task_class: implementation
harness: { claude_code: 2.1.283, codex: 0.157.1, agents_md_commit: 4f1c2e9 }
tasks: 12
runs_per_task: 3
candidates:
  - route: claude-opus-5-5 @ medium   # baseline: the default
    pass_rate: 0.83
    median_retries: 0
    median_latency_s: 410
    cost_per_accepted_task_usd: 1.90
  - route: claude-opus-5-5 @ high
    pass_rate: 0.92
    median_retries: 0
    median_latency_s: 520
    cost_per_accepted_task_usd: 2.30
decision: promote "@ high" for implementation; quality gain beats the cost rise
signed_off_by: tech lead, 2026-09-26
```

The numbers above are placeholders that show the shape; yours come from your runs.

## Encode the route in each tool

A route that lives only in a document drifts. Put it where the tool reads it, and keep full model IDs there rather than aliases. Aliases such as `opus` and `sonnet` resolve to different models on different providers and move when a new model ships.

**Claude Code**

Set the session model in `.claude/settings.json` (`"model": "claude-opus-5-5"`), or leave it unset to follow the default. Route classes through subagents: each subagent file takes a `model` and an `effort` field. Give exploration its own project subagent on a cheaper model, then ask for it by name or reference it in `CLAUDE.md`:

```markdown
---
name: explore-cheap
description: Read-only codebase search. Use before any edit to find files, call sites, and tests.
tools: Read, Grep, Glob
model: claude-haiku-4-5
---
Return file paths with one line each on why they matter. Never edit files.
```

Claude Haiku 5.5 is the current Haiku since 2026-10-07 and needs Claude Code v2.1.293 or later (`latest` channel only on 2026-10-12). Claude Haiku 4.5 is Legacy; its retirement floor is 2026-10-15 and it had no deprecation notice as of 2026-10-12. Rerun the exploration eval on Claude Haiku 5.5 before you move the row.

Other levers: `opusplan` uses Opus in plan mode and Sonnet for execution; `fallbackModel` in settings (or `--fallback-model`) holds an ordered list of fallback models tried when the primary is overloaded or unavailable; and administrators restrict choices with `availableModels`, plus `deniedModels` from v2.1.283. Note that `/model` saves your pick as the default for new sessions; press `s` in the picker to switch for the current session only.

**Codex**

Commit the default route and the review route to the repository's `.codex/config.toml`, under the same `CODEOWNERS` rule as the routing table. Codex loads that file only when the developer has marked the project as trusted; in an untrusted directory it silently falls back to each developer's `~/.codex/config.toml` (both checked in Codex CLI 0.157.1).

```toml
# .codex/config.toml — committed; default route and the /review route
model = "gpt-6.1-sol"
model_reasoning_effort = "low"
review_model = "gpt-6-sol"
plan_mode_reasoning_effort = "high"
```

The first two lines are the table's default route for Codex: GPT-6.1 Sol is the bundled default model since codex-cli 0.159.1 and runs at `low` effort in Codex by default (OpenAI's models page and the 0.162.1 catalog, checked 2026-10-12). Pinning them in the committed file keeps every developer on the same route when a bundled default changes, and the table's fallback, one effort level higher, is a one-line edit.

Select the exploration route with flags, not a profile. `--profile` layers `$CODEX_HOME/<name>.config.toml`, which lives outside the repository, and in 0.157.1 the project's `model` still wins over it; flags win over both:

```bash
codex -m gpt-6-luna -c model_reasoning_effort="medium"
```

`/model` in the TUI switches model and effort and saves the choice to your config (checked in Codex CLI 0.157.1), so re-check `/status` after using it. `/status` shows the configuration a session actually loaded; check it in each new checkout to confirm the project config loaded, because an untrusted project silently ignores `.codex/config.toml`.

**Cursor**

Record the model each workflow uses in the routing table and select it in the picker, or pass it as the `model` option when you call Cursor's agent from `@cursor/sdk`. If your Cursor account offers an automatic model option, treat it as unreproducible and pin an evaluated model for CI and audited runs (Cursor's Auto routes each request through Cursor Router, and the routed model is hidden by default; Cursor docs, checked 2026-10-12).

## Copy-paste prompts for model routing

**Copy-paste prompt: classify last month's agent work**

```text
Read the titles, descriptions, and changed-file lists of the pull requests merged
into main in the last 30 days (use `gh pr list --state merged --limit 100 --json
number,title,body,files`). Group them into four to six task classes whose success
criteria differ: for example exploration, implementation, review, bulk edits,
regulated data. For each class give: a one-line definition, how many PRs fall into it,
the check that decides success, and three PR numbers that would make good eval tasks.
Do not edit any files.
```

**Copy-paste prompt: run one eval task under a candidate route**

```text
Implement the task in evals/implementation/task-07/prompt.md in this worktree.
Stay inside the files the task names. Run the repository's test, type-check, and lint
commands and fix failures until they pass or you have tried three times.
Finish with: the files you changed, each command you ran with its exit code, and
any deviation from the task. Do not commit, push, merge, or deploy.
```

**Copy-paste prompt: compare candidate runs**

```text
Read every file in runs/ and evals/results/2026-09-26-implementation.yaml.
For each candidate route compute: pass rate from the check.sh exit codes, median
retries, median latency, and cost per accepted task (total cost divided by passing
runs). Exclude any candidate whose pass rate is more than 5 points below the baseline.
Rank the rest by cost per accepted task and name the tasks where candidates disagree.
Report numbers only from the files; mark anything missing as missing.
```

**Copy-paste prompt: draft the routing change**

```text
Using the comparison you just produced, edit docs/ai/model-routing.md so the
implementation row names the promoted route with today's date, the fallback, and a
link to the results file. Make the matching change in .claude/settings.json or
.codex/config.toml. Do not change any other row. Summarise the diff for the
pull request description and list what a reviewer should check.
```

## How do you know a route is right without reading every diff?

You judge a route by its evidence, not by reading the code it produced.

- **Graders decide pass or fail.** Each eval task has a `check.sh` with tests hidden from the agent, the type checker, the linter, and a scope check. A route that cannot pass them does not ship, whatever it costs.
- **Production confirms the eval.** After a route change, watch the acceptance rate of agent pull requests and the rework rate for that class for two weeks, using the definitions in [lifecycle metrics](/en/method/lifecycle/metrics/).
- **Every change reruns automatically.** A model or effort change in the routing table triggers the [continuous eval suite](/en/developer-scorecard-guide/continuous-evals/), and a vendor model release triggers the [new-model playbook](/en/ecosystem/models/new-model-playbook/).
- **The pull request records the route.** The agent's [evidence bundle](/en/workflows/ship/evidence-bundle/) names the model and effort that produced the change, so a regression traces back to a route.
- **One person signs off.** The tech lead owns `docs/ai/model-routing.md` and `evals/` through `CODEOWNERS` and is the only one who merges a route change. The developer who proposes it attaches the results sheet.

## What breaks in model routing, and how to recover

| Symptom | Cause | Recovery |
| --- | --- | --- |
| A pinned model disappears or starts failing | The vendor retired or renamed it. Claude Haiku 4.5, for example, has a retirement floor of 2026-10-15 with no deprecation notice as of 2026-10-12. | Point the row at the vendor's named replacement, rerun that class's eval set, and date the change. Never guess a successor from marketing copy. |
| Two developers get different results from the same command | Different release channels, providers, or a saved `/model` choice in either tool | Compare `/status` output in both tools. Pin the model in project settings (`.claude/settings.json`, or `.codex/config.toml` in a trusted project), and record the CLI version on the sheet. |
| The cheap route looks good but costs more | Retries and human repair are not counted | Recompute cost per accepted task including reruns and repair time. Promote the route with the lower total. |
| A Claude Code request switches model mid-task | A safety classifier re-ran a flagged cybersecurity or biology request on a fallback model, or `fallbackModel` fired on an outage | Read the notice in the transcript. If a class trips it often, route that class to the fallback model deliberately and eval it there. |
| A run's model cannot be reproduced | No model was pinned, so the tool or account default chose it | Record the model ID on the sheet. Pin an evaluated model for CI and audited runs. |
| A fallback crosses a data boundary | The fallback provider is not approved for that data | Keep the task on the approved provider or use the human-only path. Availability never overrides data policy. |
| Everyone upgrades to the biggest model | One impressive session, no eval | Run the eval for that class. If the flagship wins on cost per accepted task, promote it through the same pull request as any other change. |

## Check your routing policy

- [ ] Every important task class has a quality threshold, a current route, and a fallback.
- [ ] Model names appear in one dated routing table and the tool config, not in prompts.
- [ ] Each route links to a results sheet from the same harness version.
- [ ] Effort was tuned on the default model before any other model was tried.
- [ ] At least one fallback has run on the same eval set.
- [ ] Cost per accepted task includes retries and human repair.
- [ ] Permissions, sandboxing, and data boundaries are the same for every candidate.
- [ ] The tech lead owns the table through `CODEOWNERS` and reviews it at least quarterly.

## Where to go next with model routing

Before this page, [choose a primary AI engineering harness](/en/developer-scorecard-guide/primary-ai-tool/) (Q1) and [size your plan from measured workload](/en/developer-scorecard-guide/subscription-plan-fit/) (Q2), and map the [ecosystem of skills, MCP servers and plugins](/en/ecosystem/). After it, carry the routes into the [AI-native SDLC](/en/method/lifecycle/) and compare the harnesses in the [tool map](/en/method/lifecycle/tool-map/). Next on the developer track: [agent frameworks](/en/ecosystem/frameworks/).

Official references: Claude Code [model configuration](https://code.claude.com/docs/en/model-config) and [subagents](https://code.claude.com/docs/en/sub-agents); the Codex [configuration schema](https://github.com/openai/codex/blob/main/codex-rs/config/src/config_toml.rs); the [`@cursor/sdk` package](https://www.npmjs.com/package/@cursor/sdk).

- [AI model comparison guide](/en/ecosystem/models/) — Current model names, prices, context windows, and defaults.
- [Benchmarks and your own evals](/en/ecosystem/models/benchmarks/) — What public boards miss, and how to build the eval set this page runs.
- [New-model playbook](/en/ecosystem/models/new-model-playbook/) — Re-evaluate your routes within 48 hours of a model release.
- [Developer answer key](/en/developer-scorecard-guide/) — Every scorecard question mapped to its canonical page.
