Hem › Agentiskt arbetsflöde › Specen som kontrakt
Agentiskt arbetsflöde

Specen som kontrakt

Specen är koordinationsobjektet. Tester genereras från specen — inte tvärtom.

Implementeringsstatus: Designanteckning — implementerar Thoughtworks Spec-Driven Development (SDD)-mönstret anpassat till multi-agent-exekvering.

Byggt idag: placeringen wiki/specs/<feature>.md är en konvention som läsare kan följa; PRD:er bor redan i wiki/plans/<feature>-YYYY-MM-DD.md med rätt frontmatter-form. PRD-to-PR-runnern förväntar sig nu en Acceptance Contract-tabell och registrerar en acceptanceCoverage-matris innan en körning kan godkännas som klar.

Mål-tillägg: en Architect-agent som faktiskt producerar wiki/specs/<feature>.md från PRD:n. Ingen sådan agent finns idag; specer skrivs ad hoc som del av implementationsarbetet, eller hoppas över helt med editorn som läser PRD:n direkt. Test-writerns "kompilera Gherkin → misslyckande tester"-producent finns inte heller.

Naturligt språk är för imprecist för att koordinera flera agenter. PRD:er är för långa för att hålla i arbetsminnet vid varje steg. Specen är mellanartefakten: precis nog för att kompileras till tester, kort nog för att rymmas i varje agents kontext.

Vad "spec" betyder här

En wiki/specs/<feature>.md-fil med tre kontraktssektioner:

  1. Acceptance Contract — en markdown-tabell med stabila AC-*-ID:n.
  2. Acceptanskriterier i Gherkin-stil-scenarier som innehåller matchande AC-*-ID.
  3. Koordinationsmetadata — filer som förväntas röras, modellroll förväntad i varje steg, alla explicita icke-mål.

Exempelskelett:

# Spec: Lab promotion banner

## Acceptance criteria

## Acceptance Contract

| ID     | Requirement                                        | Status          | Evidence | Notes |
| ------ | -------------------------------------------------- | --------------- | -------- | ----- |
| AC-001 | Pinned trial is shown above the leaderboard.       | not-implemented |          |       |
| AC-002 | Promote button is disabled for in-progress trials. | not-implemented |          |       |

## Acceptance criteria

Feature: Best-trial banner on lab leaderboard
Scenario: AC-001 Pinned trial is shown above the leaderboard
Given a service area with at least one completed lab trial
And one trial is pinned in ServiceAreaBestLabScenario
When the user opens /admin/optimization-lab/<id>
Then the BestTrialBanner is visible
And the banner shows the pinned trial's metrics

Scenario: AC-002 Promote button is disabled for in-progress trials
Given a trial whose solution.status is solving_active
Then the Promote button is disabled
And hovering the button shows the tooltip "Trial still solving"

## Files expected to be touched

- apps/dashboard/src/pages/admin/optimization-lab/BestTrialBanner.tsx (new)
- apps/dashboard/src/pages/admin/optimization-lab/LeaderboardSection.tsx (modify)
- apps/dashboard/src/pages/admin/optimization-lab/**tests**/BestTrialBanner.test.tsx (new)
- e2e/lab-promotion-banner.spec.ts (new)

## Non-goals

- No backend changes (the resolver already returns the SA-best trial id).
- No copy changes outside the banner itself.
- No analytics events for banner views.

## Stage routing (overrides)

- editor: default
- verifier: default + perf-reviewer NOT required (no list resolver / loop touched)

Varför Gherkin

Tre skäl:

  1. Tester är mekaniska från den. Test-writer-agenten kompilerar varje scenario till ett eller flera misslyckande testfall. Mappningen är direkt nog för att en regression i test-writern är lätt att upptäcka.
  2. Granskare kan greppa det. "Hitta varje scenario som nämner BestTrialBanner" är ett grep bort. Spec i ren prosa kräver läsning.
  3. Drift är auditerbar. När PRD:n säger en sak och specen säger en annan är diffen mellan PRD och spec den enda diskussionen att ha. Begrav inte oenigheten under prosa.

Done contract gate

"Done" betyder att varje AC-*-rad är antingen:

Runnern får inte flytta en körning till awaiting_approval medan något accepterat krav fortfarande är not-implemented. Sådana körningar är incomplete_scope, och dashboardens godkännandeknapp förblir blockerad.

Single-source-of-truth-regeln

När specen är skriven är PRD:n inte längre källan till sanning för vad som ska byggas. Specen är.

Resonemang: agenter nedströms ser specen, inte PRD:n. Om PRD:n ändras mitt i implementationen och specen inte gör det, fortsätter editorn och verifiern bygga mot specen — och det är rätt, eftersom specen är vad de verifierade mot.

Om PRD:n ändras, regenerera specen. Behandla det som en ny funktionsskiva, på ett friskt eller uttryckligen återupptaget worktree, med en frisk testkörning. Ändra inte tyst mitt i flygningen.

Felmod: spec-drift

Den vanligaste felaktigheten: arkitekten producerar en spec som nämner ett beteende PRD:n inte specificerade, och editorn implementerar det glatt. Motåtgärder:

Intag från Cursor-planer

Cursor-planer under .cursor/plans/ är utkast till planeringsartefakter, inte exekverbara kontrakt. Innan implementationen börjar måste orkestreraren:

  1. Konvertera den accepterade planen till wiki/plans/<feature>-YYYY-MM-DD.md.
  2. Bevara Cursor-plan-sökvägen i PRD:ns sources:-frontmatter.
  3. Generera wiki/specs/<feature>.md från PRD:n.
  4. Använd specen, inte Cursor-planen, som källan till sanning för tester och implementation.
  5. Behandla runnerns acceptanceCoverage-matris som den slutliga källan till sanning för "done". En passerande PR med saknade AC-*-bevis är inte klar.

Varför inte hoppa över specen och bara skriva tester?

Testat, fungerar inte. Ren test-first stöter på:

Att placera acceptanskriterierna i ett Gherkin-block ger test-writern en checklista att kompilera från, och ger granskare något att greppa mot utan att dyka in i test-interna detaljer.

Korsreferenser

Tillbaka till Agentiskt arbetsflöde