From 6a135ac1117a1e2b3e554851883745fe84e836c1 Mon Sep 17 00:00:00 2001 From: Mike Swanson Date: Sat, 18 Apr 2026 08:53:49 -0700 Subject: [PATCH] Session log: Claude Code model selection Q&A + complexity-based sub-agent routing system Co-Authored-By: Claude Sonnet 4.6 --- .claude/CLAUDE.md | 14 ++++++ .claude/COMPLEXITY_ROUTING.md | 74 ++++++++++++++++++++++++++++++ session-logs/2026-04-18-session.md | 31 +++++++++++++ 3 files changed, 119 insertions(+) create mode 100644 .claude/COMPLEXITY_ROUTING.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 56e0d95..f6b41ae 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -102,6 +102,20 @@ You are NOT an executor. You coordinate specialized agents and preserve your con **DO NOT** query databases directly (no SSH/mysql/curl to API). **DO NOT** write production code. **DO NOT** run tests. **DO NOT** commit/push. Use the appropriate agent. +### Model Routing (Complexity-Based) + +Before spawning an agent, pick a tier from `.claude/COMPLEXITY_ROUTING.md`: + +| Tier | Model | When | +|------|-------|------| +| 1 | `haiku` | Lookup, format, summarize, doc — no code changes | +| 2 | (inherit) | Standard code, DB, tests, git — most work | +| 3 | `opus` | Architecture, security, ambiguous failures, production risk | + +**Bump rule:** if the request involves `security`, `auth`, `credential`, `migration`, `production`, or `data loss` — bump one tier up. + +Pass `model: "haiku"` or `model: "opus"` explicitly. Omit for Tier 2 (inherits session model). + ### Coordination Flow ``` diff --git a/.claude/COMPLEXITY_ROUTING.md b/.claude/COMPLEXITY_ROUTING.md new file mode 100644 index 0000000..b970c34 --- /dev/null +++ b/.claude/COMPLEXITY_ROUTING.md @@ -0,0 +1,74 @@ +# Complexity-Based Model Routing + +When spawning an agent, pick a tier based on the request signals below, then pass `model` accordingly. + +--- + +## Tier 1 — Haiku (fast/cheap) + +**Signals:** single lookup, no code changes, classification, formatting, summarization, status check, documentation + +**Examples:** +- "What's the status of X?" +- Summarize or format a session log +- Search/grep for a value +- Convert or extract data +- Write/update a markdown doc + +**Agents that default here:** documentation-squire, explore (quick searches), photo + +**Agent call:** `model: "haiku"` + +--- + +## Tier 2 — Sonnet (default, inherit) + +**Signals:** standard code generation, routine DB queries, test execution, API work, multi-file reads, git operations + +**Examples:** +- Add or modify an endpoint +- Run tests and report results +- Write a DB migration +- Fetch credentials, configure a service +- Commit and push changes + +**Agents that default here:** coding, database, testing, gitea, general-purpose, deep-explore (standard search) + +**Agent call:** omit `model` (inherits session model) + +--- + +## Tier 3 — Opus (high-stakes reasoning) + +**Signals:** architectural decision, security/auth, 3+ interacting systems, ambiguous root cause, production data risk, anything that fails badly if wrong + +**Examples:** +- Redesign an auth or data flow +- Security or code review of a critical PR +- Debug a multi-service race condition +- Schema migration on production data +- Evaluate competing architectural approaches + +**Agents that default here:** code-review (when Sequential Thinking triggers), deep-explore (architecture questions) + +**Agent call:** `model: "opus"` + +--- + +## Bump Rule + +If the request contains ANY of these keywords, bump one tier up regardless of other signals: + +`security`, `auth`, `token`, `credential`, `migration`, `production`, `race condition`, `data loss`, `breach`, `encrypt` + +--- + +## Quick Reference + +| Tier | Model | Typical cost | Use when | +|------|-------|-------------|----------| +| 1 | `haiku` | ~10x cheaper | Lookup, format, summarize, doc | +| 2 | (inherit) | baseline | Standard code, DB, tests | +| 3 | `opus` | ~5x more expensive | Architecture, security, ambiguous failures | + +Err toward Tier 2 when uncertain. Only use Opus when the reasoning stakes justify the cost. diff --git a/session-logs/2026-04-18-session.md b/session-logs/2026-04-18-session.md index 9f29be1..de5c53e 100644 --- a/session-logs/2026-04-18-session.md +++ b/session-logs/2026-04-18-session.md @@ -176,3 +176,34 @@ No custom "Archived" status — used `Closed` for archival. 4. **All items in WORKITEMS.md** 5. **Cascades file search** — TickTick task for today 6. **Review Dataforth engineering docs and send** — TickTick task for today + +--- + +## Update: ~14:00 + +### Topic: Claude Code model selection + complexity routing system + +#### What was discussed + +1. **Model selection in Claude Code** — confirmed it is always manual (no automatic complexity-based switching). Options: `/model`, `--model` flag, `ANTHROPIC_MODEL` env var, `settings.json`. The `opusplan` alias is the closest to automatic — uses Opus for planning phase, then switches to Sonnet for execution. + +2. **Sub-agent complexity detection** — confirmed we had NO complexity-based model routing for spawned agents. Existing behavior: rule-based routing by operation type, `>500 token` delegation threshold, a few hardcoded Haiku hints in `AGENT_QUICK_REFERENCE.md` for documentation-squire. + +#### What was built + +**New file: `.claude/COMPLEXITY_ROUTING.md`** + +Full 3-tier scoring rubric for sub-agent model selection: +- Tier 1 (Haiku): lookup, format, summarize, doc — no code changes +- Tier 2 (inherit/Sonnet): standard code, DB, tests, git — most work +- Tier 3 (Opus): architecture, security, ambiguous failures, production risk + +Bump rule: if request contains `security`, `auth`, `token`, `credential`, `migration`, `production`, `race condition`, `data loss`, `breach`, `encrypt` → bump one tier up regardless. + +**Updated: `.claude/CLAUDE.md`** + +Inserted "Model Routing (Complexity-Based)" section in the coordinator block, just before Coordination Flow. Compact routing table + bump rule inline. References COMPLEXITY_ROUTING.md for full detail. + +#### Files modified +- `.claude/COMPLEXITY_ROUTING.md` — new file, full rubric +- `.claude/CLAUDE.md` — coordinator section updated with routing table