janpeter/Scrum4Me
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Scrum4Me/docs/runbooks/job-model-selection.md
Janpeter Visser 8c63ba377d
feat(PBI-67): model + mode-selectie per ClaudeJob-kind (#169) 
* feat(PBI-67/ST-1297): datamodel-velden voor job-model-selectie

Voegt 8 nieuwe optionele velden toe verspreid over Product, Task en
ClaudeJob ten dienste van de override-cascade:

  task.requires_opus → job.requested_* → product.preferred_* → kind-default

Bestaande rijen krijgen NULL (Product/ClaudeJob) of false (Task) en
vallen daarmee terug op de kind-defaults uit de resolver (ST-1298).

Migration is additief: alleen ALTER TABLE ADD COLUMN, geen RENAME of
DROP. Bestaande factories en seed-script blijven werken zonder
aanpassing omdat alle nieuwe velden default-waardes hebben.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(PBI-67/ST-1299): job-config snapshot bij enqueue + worker-flag-runbook

T-789: Snapshot van resolved JobConfig in ClaudeJob.requested_*
bij elke job-creatie. Helper in lib/job-config-snapshot.ts laadt
product (preferred_*) en task (requires_opus) en draait de resolver
uit lib/job-config.ts (mirror van scrum4me-mcp/src/lib/job-config.ts —
zelfde matrix, sync-comment in bestand). Toegepast op alle 5
enqueue-locaties:

  - actions/user-questions.ts          (PLAN_CHAT)
  - actions/sprint-runs.ts × 3         (SPRINT_IMPLEMENTATION x2,
                                        TASK_IMPLEMENTATION loop)
  - actions/ideas.ts                   (IDEA_GRILL / IDEA_MAKE_PLAN)

Test-mocks uitgebreid met product.findUnique en task.findUnique zodat
de helper bij unit tests veilig terugvalt op kind-defaults (alle 563
tests groen).

T-790: Sectie 'Config doorgeven aan Claude Code' toegevoegd aan
docs/runbooks/worker-idempotency.md met CLI-flag-mapping en de
verwachte aanroep per kind. Forward-link naar
docs/runbooks/job-model-selection.md (volgt in T-794).

Plus: docs/plans/job-model-selection.md (de approved plan-doc).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(PBI-67/ST-1300): cost-attribution voor thinking-tokens + admin UI

T-792: token-stats + token-history rekenen actual_thinking_tokens nu
mee in de totale kosten (tegen input-rate, conform Anthropic billing).
COALESCE-veilig zodat oude rijen 0 bijdragen i.p.v. NaN. Nieuwe export
`getTokenStatsByKind` aggregeert tokens en kosten per ClaudeJob.kind
zodat we relatieve uitgaven van IDEA_GRILL/IDEA_MAKE_PLAN/PLAN_CHAT/
TASK_IMPLEMENTATION/SPRINT_IMPLEMENTATION kunnen zien.

T-793: admin/jobs Kosten-tabel toont:
  - Nieuwe kolom 'Thinking' (aantal verbruikte thinking-tokens)
  - Mismatch-marker (rood) als requested_model afwijkt van actuele
    model_id — duidt op een worker die de CLI-flag niet doorgaf.
    Tooltip toont aangevraagd model. Geen Sentry/log-noise.

Page-level cost-berekening volgt dezelfde formule (input_price ×
thinking_tokens). 563 tests groen.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(PBI-67/ST-1301): runbook + CLAUDE.md updates voor model/mode-selectie

T-794: Nieuwe runbook docs/runbooks/job-model-selection.md met
override-cascade, kind-default-matrix, override-voorbeelden,
auditspoor en cost-attribution-formule. 107 regels.

T-795: CLAUDE.md hardstop-bullet voor 'Model/mode per ClaudeJob'
(verwijst naar nieuwe runbook) + patterns-quickref-rij voor
job-config resolver. CLAUDE.md blijft 139 regels (≤ 150).

T-796: docs:check-links groen — 108 files, geen broken links. Twee
externe-repo verwijzingen (scrum4me-mcp/...) ge-de-linked tot plain
text omdat de check-links script de zustertree niet traverseert; de
referenties blijven leesbaar.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-08 11:20:10 +02:00

4.4 KiB
Raw Blame History

title status audience language last_updated when_to_read
Job-model-selectie per ClaudeJob-kind active
ai-agent
contributor
nl 2026-05-08 Vóór het wijzigen van model/thinking/permission-mode-keuze of bij debugging van 'verkeerd model gebruikt'-incidents.

Job-model-selectie per ClaudeJob-kind

PBI-67. Per ClaudeJob.kind bepaalt de Scrum4Me-mcp resolver scrum4me-mcp/src/lib/job-config.ts welk Claude-model + thinking- budget + permission-mode + max_turns + allowed_tools de Claude Code- worker moet gebruiken.

Dezelfde resolver staat — als één-op-één spiegel — in lib/job-config.ts voor de enqueue-laag, zodat we bij job-creatie het resolved resultaat al snapshotten in ClaudeJob.requested_*.

Override-cascade

   1. Task.requires_opus = true   →  forceer claude-opus-4-7
   2. Job.requested_*             →  snapshot bij enqueue
   3. Product.preferred_*         →  product-brede default
   4. KIND_DEFAULTS               →  per kind onderstaand

Eerste match wint. max_turns en allowed_tools blijven in V1 altijd kind-default — geen product- of task-override.

Kind-default-matrix

Kind Model Thinking-budget Permission-mode max_turns allowed_tools
IDEA_GRILL claude-sonnet-4-6 12 000 plan 15 Read, Grep, Glob, WebSearch, AskUserQuestion
IDEA_MAKE_PLAN claude-opus-4-7 24 000 plan 20 Read, Grep, Glob, WebSearch, AskUserQuestion, Write
PLAN_CHAT claude-sonnet-4-6 6 000 plan 5 Read, Grep, AskUserQuestion
TASK_IMPLEMENTATION claude-sonnet-4-6 6 000 bypassPermissions 50 (alle)
SPRINT_IMPLEMENTATION claude-sonnet-4-6 6 000 bypassPermissions (geen) (alle)

bypassPermissions is verdedigbaar voor de implement-kinds omdat elke run in een geïsoleerde git-worktree start (zie branch-and-commit.md). Productie-product? Zet Product.preferred_permission_mode = 'acceptEdits'.

Wanneer overrul je een default?

Scenario Wijzig op Voorbeeld
Cross-file refactor of architectuurkeuze in TASK_IMPLEMENTATION Task.requires_opus = true Een PBI met "rip out auth middleware"
Klant wil budget-control op een product Product.preferred_model = claude-sonnet-4-6 Side-product met Haiku-only-budget
Productie-product zonder bypassPermissions Product.preferred_permission_mode = 'acceptEdits' Klant-facing repo waar elke wijziging review nodig heeft
Ad-hoc: Opus voor één specifieke story-job ClaudeJob.requested_model = claude-opus-4-7 (handmatige UPDATE) Nood-debug van prod-incident
Geen thinking voor een PLAN_CHAT (snelle reactie) Product.thinking_budget_default = 0 (alle kinds in dat product) Demo-product

Auditspoor

Kolom Wat Wanneer ingevuld
requested_model Resolved model op enqueue-tijd actions/* enqueue-laag via lib/job-config-snapshot.ts
requested_thinking_budget Resolved budget op enqueue-tijd idem
requested_permission_mode Resolved permission-mode idem
model_id Werkelijk gebruikt model update_job_status na worker-run
actual_thinking_tokens Werkelijk verbruikte thinking-tokens idem

Verschillen tussen requested_model en model_id zijn zichtbaar in admin → Jobs → Kosten (rood-gemarkeerd modelveld + tooltip). Meestal duidt dat op een worker die de CLI-flag niet doorgaf — controleer de worker-script tegen de flag-tabel in worker-idempotency.md.

Cost-attribution

Thinking-tokens worden bij Anthropic-billing gerekend tegen de input-rate van het model. lib/insights/token-stats.ts en lib/insights/token-history.ts doen hetzelfde:

COALESCE(cj.actual_thinking_tokens, 0) * mp.input_price_per_1m / 1000000.0

Voor per-kind aggregatie binnen een sprint: gebruik getTokenStatsByKind(userId, sprintId).

Referenties

  • Plan: docs/plans/job-model-selection.md
  • Resolver (MCP): scrum4me-mcp/src/lib/job-config.ts
  • Resolver (main): lib/job-config.ts
  • Snapshot-helper: lib/job-config-snapshot.ts
  • Worker-flag-mapping: worker-idempotency.md
  • Schema: prisma/schema.prisma → Product, Task, ClaudeJob velden uit migration 20260508085909_add_job_model_selection_fields