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>
This commit is contained in:
Janpeter Visser
GitHub
parent
f233dd815e
commit
8c63ba377d
18 changed files with 648 additions and 9 deletions
107
docs/runbooks/job-model-selection.md
Normal file
107
docs/runbooks/job-model-selection.md
Normal file
|
|
@ -0,0 +1,107 @@
|
|||
---
|
||||
title: "Job-model-selectie per ClaudeJob-kind"
|
||||
status: active
|
||||
audience: [ai-agent, contributor]
|
||||
language: nl
|
||||
last_updated: 2026-05-08
|
||||
when_to_read: "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`](../../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](./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](./worker-idempotency.md#config-doorgeven-aan-claude-code-pbi-67).
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
|
||||
```sql
|
||||
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](../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](./worker-idempotency.md#config-doorgeven-aan-claude-code-pbi-67)
|
||||
- Schema: `prisma/schema.prisma` → `Product`, `Task`, `ClaudeJob` velden uit migration `20260508085909_add_job_model_selection_fields`
|
||||
|
|
@ -110,6 +110,49 @@ Drie protocol-overtredingen die we met deze runbook + de nieuwe
|
|||
|
||||
---
|
||||
|
||||
## Config doorgeven aan Claude Code (PBI-67)
|
||||
|
||||
`wait_for_job` levert sinds PBI-67 een `config`-object mee in de
|
||||
response. Geef deze door aan `claude` als CLI-flags:
|
||||
|
||||
```bash
|
||||
claude \
|
||||
--model "$MODEL" \
|
||||
--permission-mode "$PERMISSION_MODE" \
|
||||
--thinking-budget "$THINKING_BUDGET" \
|
||||
${MAX_TURNS:+--max-turns $MAX_TURNS} \
|
||||
${ALLOWED_TOOLS:+--allowed-tools "$ALLOWED_TOOLS"}
|
||||
```
|
||||
|
||||
Waar:
|
||||
|
||||
| Variabele | Bron in response | Voorbeeld |
|
||||
|---|---|---|
|
||||
| `MODEL` | `config.model` | `claude-sonnet-4-6` |
|
||||
| `PERMISSION_MODE` | `config.permission_mode` | `bypassPermissions` |
|
||||
| `THINKING_BUDGET` | `config.thinking_budget` (0 = uit) | `12000` |
|
||||
| `MAX_TURNS` | `config.max_turns` (null = onbegrensd) | `15` of leeg |
|
||||
| `ALLOWED_TOOLS` | `config.allowed_tools.join(',')` (null = alle) | `Read,Grep,WebSearch` |
|
||||
|
||||
Verwachte CLI-aanroep per kind (kind-defaults zonder overrides):
|
||||
|
||||
| Kind | Model | thinking | permission_mode | max_turns |
|
||||
|---|---|---|---|---|
|
||||
| `IDEA_GRILL` | sonnet-4-6 | 12000 | plan | 15 |
|
||||
| `IDEA_MAKE_PLAN` | opus-4-7 | 24000 | plan | 20 |
|
||||
| `PLAN_CHAT` | sonnet-4-6 | 6000 | plan | 5 |
|
||||
| `TASK_IMPLEMENTATION` | sonnet-4-6 | 6000 | bypassPermissions | 50 |
|
||||
| `SPRINT_IMPLEMENTATION` | sonnet-4-6 | 6000 | bypassPermissions | (geen) |
|
||||
|
||||
**Onbekende flag:** als de huidige Claude Code-versie een vlag niet
|
||||
kent, log een waarschuwing en sla 'm over — geen hard error. De server
|
||||
blijft jobs queuen.
|
||||
|
||||
Volledige resolver-uitleg + override-cascade staat in
|
||||
[job-model-selection.md](./job-model-selection.md).
|
||||
|
||||
---
|
||||
|
||||
## Referenties
|
||||
|
||||
- Enum: `prisma/schema.prisma` → `enum ClaudeJobStatus`
|
||||
|
|
@ -119,4 +162,5 @@ Drie protocol-overtredingen die we met deze runbook + de nieuwe
|
|||
- KPI-aggregatie: `lib/insights/agent-throughput.ts` (terminal_7d
|
||||
inclusief SKIPPED)
|
||||
- Gerelateerd plan: `docs/plans/auto-pr-deploy-sync.md` Deel D
|
||||
- PBI-67 resolver: `scrum4me-mcp/src/lib/job-config.ts` + `lib/job-config.ts`
|
||||
(Sync-tab toont per-Story job-status incl. SKIPPED)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue