BijoyIQ
AI & automation

Jag slutade skriva prompts — och började skriva specifikationer

Jag skrev länge "superprompts" för coding agents. Ju viktigare uppgiften var, desto längre blev prompten. Roll. Kontext. Krav. Edge cases. Best practices. Filstruktur. Vad modellen inte fick göra. Reviewsteg. Acceptanskriterier. Allt i samma meddelande. Det fungerade bättre än en två-radersprompt.

Shadip Rahman 11 september 2026 16 min läsning
Dela

Jag skrev länge "superprompts" för coding agents. Ju viktigare uppgiften var, desto längre blev prompten. Roll. Kontext. Krav. Edge cases. Best practices. Filstruktur. Vad modellen inte fick göra. Reviewsteg. Acceptanskriterier. Allt i samma meddelande. Det fungerade bättre än en två-radersprompt. Men till slut blev det tydligt att jag försökte lösa fel problem. Jag behövde inte en ännu bättre prompt. Jag behövde en specifikation som kunde överleva prompten.

Problemet med prompten som source of truth

En prompt är bra för att starta arbete. Den är dålig som långsiktig kontrakt mellan intention och implementation. I ett större projekt händer snabbt följande:

  1. agenten läser prompten,
  2. den börjar implementera,
  3. nya tekniska fakta upptäcks,
  4. några krav tolkas,
  5. ett par beslut ändras,
  6. koden blir den nya verkligheten,
  7. den ursprungliga prompten är nu delvis inaktuell.

Nästa gång jag ber modellen ändra något måste den rekonstruera varför systemet ser ut som det gör.

Det är exakt den lucka som specification-driven development försöker angripa. GitHubs Spec Kit beskriver — i sin dokumentation vid tidpunkten för den här artikeln — specifikationen som den primära artefakten: krav och intent driver plan, tasks och implementation, med kontinuerlig kontroll av motsägelser och luckor. Jag har börjat använda samma princip även utan att använda ett specifikt ramverk.

Vad jag menar med en specification

Det är inte ett långt PRD för sakens skull. En användbar spec svarar på saker modellen annars måste gissa:

För tekniska features lägger jag dessutom till berörda komponenter, migrationer, API-kontrakt och observability när det behövs. Det viktiga är att kraven kan granskas innan en stor diff finns.

Prompt → plan → implementation → review

Mitt standardflöde har därför flyttats från:

mot:

Det ser långsammare ut. För små engångsscript kan det vara det. Men när jag byggt större flows har det oftast minskat rework eftersom den dyra missuppfattningen hittas innan 20 filer förändrats.

Claude Academys kurs om AI-native SDLC — så som materialet såg ut när jag skrev det här — driver en liknande princip: börja coding-sessionen i plan mode, låt Claude läsa en godkänd spec och iterera på planen innan kod skrivs. Den godkända planen blir sedan en artefakt som senare steg kan kontrolleras mot.

Den viktigaste skillnaden: acceptanskriterier

En prompt säger ofta vad man vill ha. En bra spec säger hur vi vet att vi fått det. Exempel från en AI-contentpipeline:

Vagt: "Faktagranska artikeln noggrant."

Specificerat:

Nu går resultatet att testa. Det här är samma förändring jag gjort i mina prompts generellt: från adjektiv till observerbara villkor. "Robust", "best practice", "professionell" och "säkert" är inte krav förrän de operationaliseras.

Coding-prompt och research-prompt är inte samma kontrakt

Samma logik gäller innan jag ens kommer till spec-nivå: jag använder inte samma promptstruktur för kod och research, eftersom felkostnaden ser olika ut. En coding-prompt behöver framför allt definiera önskat systembeteende och verifierbar acceptans — befintlig arkitektur, vilka filer eller komponenter som får ändras, funktionella krav, edge cases, vad som inte får regressa, tester och acceptanskriterier. En research-prompt behöver i stället definiera frågan, källhierarkin och hur osäkerhet ska representeras: exakt researchfråga, scope och tidsgräns, primärkällor först, vad som räknas som verifierat, hur konflikter ska markeras, citation per claim och vilka slutsatser som inte får dras från underlaget.

Gemensamt för båda är att jag försöker separera krav från metod i stället för att detaljstyra exakt hur modellen ska tänka sig fram till svaret. Det ger agenten frihet där kreativ problemlösning hjälper, men gör resultatet testbart där det spelar roll. Research-outputen bör kunna vara "UNRESOLVED". Coding-outputen bör kunna vara "tests fail". Båda behöver ett legitimt misslyckandeläge.

Jag låter modellen attackera specen före implementation

Ett steg som blivit särskilt värdefullt är adversarial review. Jag ber modellen leta efter:

  • motsägelser,
  • saknade states,
  • odefinierade begrepp,
  • happy-path-antaganden,
  • permissions som är för breda,
  • migrationsrisk,
  • vad som händer vid timeout/retry,
  • vad som händer om data saknas,
  • acceptanskriterier som inte går att testa.

Det är billigare att få svaret "den här state transitionen är odefinierad" i Markdown än efter att systemet ligger i produktion.

Specs fungerar extra bra med Skills och agents

När samma typ av arbete återkommer vill jag inte heller kopiera spec-standarder in i varje prompt. Där kommer Skills och agentinstruktioner in. Jag separerar lagren ungefär så här:

  • Project constitution / CLAUDE.md — regler som alltid gäller i repot.
  • Skill — återanvändbar metodik för en viss arbetsuppgift.
  • Spec — kraven för just den feature eller förändring som ska byggas.
  • Plan — hur den aktuella koden ska förändras för att uppfylla specen.
  • Task — det exekverbara arbetet.
  • Prompt — instruktionen som startar nästa steg.

När de blandas ihop får man gigantiska prompts. När de separeras får varje lager en tydlig livslängd.

Ett konkret exempel från den här bloggen

BijoyIQ-contentprojektet började i princip med frågan: vad är värt att skriva om utifrån det jag faktiskt byggt? Det hade kunnat sluta med en prompt: "skriv 200 AI-artiklar". I stället växte det fram lager:

  • content briefs,
  • strategisk prioritering,
  • topical map,
  • canonical URL-konsolidering,
  • produktionsspecifikationer,
  • content Skill,
  • content-ops repo,
  • multi-agent pipeline,
  • handoff contracts och publisher gate.

Det är ett bra exempel på skillnaden. Själva skrivprompten blev mindre viktig ju bättre systemet runt den blev.

När räcker en vanlig prompt?

Jag använder fortfarande vanliga prompts hela tiden. En spec är överdriven när:

  • uppgiften är liten och reversibel,
  • ett enda output ska produceras,
  • konsekvensen av ett fel är låg,
  • kraven redan är uppenbara,
  • resultatet går att inspektera på några minuter.

Men ju fler av följande som gäller, desto mer vill jag ha en spec:

  • flera filer eller system påverkas,
  • arbetet ska leva länge,
  • fler agenter/människor ska fortsätta senare,
  • det finns business rules,
  • data kan migreras eller förstöras,
  • fel är dyra,
  • edge cases är viktiga,
  • output måste kunna evalueras.

Tecken på att en superprompt vuxit ur sig själv

Ibland är valet inte spec eller inte spec, utan att en enda stor instruktion har fått bära för mycket. En sådan superprompt kan vara praktisk för ett engångsjobb med liten risk, men jag ersätter den när samma logik ska återanvändas, testas eller delas mellan agenter. Tecknen är oftast tydliga: motstridiga regler, återkommande copy-paste mellan prompter, svårtolkade fel och att en liten ändring plötsligt påverkar oväntade delar av outputen. När det händer är det inte prompten som behöver bli längre — det är dags att bryta ut stabila lager till Skill, references och templates.

Prompt engineering försvinner inte. Det här betyder inte att prompts är oviktiga. Tvärtom. Men jag ser prompt engineering mer som runtime-instruktioner och specification engineering som systemdesign. Prompten ska inte bära hela produktens minne, policy, teststrategi och arkitektur på sina axlar. När jag slutade försöka få in allt i "den perfekta prompten" blev mina AI-coding-flöden mer förutsägbara. Inte för att modellen blev smartare, utan för att den fick mindre att gissa om. Det är i dag min främsta skillnad mellan vibe coding och ett produktionsmässigt AI-arbetsflöde: vibe coding optimerar nästa generation. Specification-driven development optimerar kedjan från intention till verifierbar implementation.

Så ser en spec ut i ett verkligt projekt

Jag behöver inte alltid 30 sidor dokumentation. För många features räcker ett fokuserat dokument. Ett exempel på struktur:

Redan där har modellen mycket mindre att gissa om än om jag skriver: "bygg smart bevakning för AVVAKTA-case enligt best practice".

Non-goals är oväntat viktiga

AI-agenter är optimerade för att vara hjälpsamma. Det betyder att de gärna bygger mer än du bad om om "mer" ser logiskt ut. Non-goals hindrar scope creep. I en migration kan det exempelvis vara:

Det kan kännas defensivt. Men det minskar diffstorlek och gör review bättre.

Business rules måste bli explicita

Ett annat problem med vanliga prompts är att viktiga business rules ofta ligger i huvudet på beställaren. Exempel: "Priser för produkt 1008 får inte vara lägre än 1003." Det är en regel, inte bakgrundsinformation. I en spec vill jag skriva den på ett sätt som kan bli ett test:

Nu kan implementationen generera en kontroll och QA kan verifiera den. Ju mer AI skriver kod, desto viktigare blir det att domänregler är maskinläsbara eller åtminstone testbara.

Best practice blir konkret genom testbara krav

"Följ best practice" är samma typ av problem som en adjektivkrav, fast förklätt som råd. Etiketten berättar inte vilken risk, målgrupp eller kompromiss som är viktig, och två erfarna utvecklare kan välja olika lösningar och båda kalla dem best practice. Jag skriver därför om beteendet till krav: secrets får inte loggas, write-actions kräver idempotency key, schema validation sker före tool-call och critical failures ska kunna retryas utan dublett. Om en practice är viktig ska den gå att verifiera i code review, test eller runtime metric — annars är den bara en önskan.

Det gäller även avvägningar som ofta gömmer sig bakom en rekommendation. "Använd cache" är inte alltid rätt; jag vill veta vad vi optimerar — latency, kostnad eller API-rate limits — och vilken stale-data-risk som accepteras. När kravet och avvägningen är explicita behöver agenten mindre kulturell gissning.

Examples och counterexamples

Jag försöker också lägga till exempel på både rätt och fel beteende. Det hjälper särskilt när kravet är språkligt.

Eller i översättning:

Ett par skarpa examples kan vara mer värdefulla än ytterligare 500 ord abstrakta instruktioner.

Specs behöver versioneras

Om en spec är source of truth måste den också kunna förändras kontrollerat. Jag vill veta: vad ändrades? Varför? Vilket beslut ersattes? Vilka tests påverkas? Kräver befintlig implementation migration? Det behöver inte vara mer avancerat än Git-history och ett kort decision log. Men om specen kan ändras utan att implementation/tester re-checkas skapar man bara en ny typ av dokumentationsdrift.

ADR för beslut som annars kommer tillbaka. Vissa tekniska diskussioner återkommer om och om igen: varför valde vi Postgres? Varför är den här delen deterministisk? Varför använder vi inte MCP här? Varför får agenten bara read access? Varför är modellen X default men Y escalation? Då är en liten Architecture Decision Record användbar:

Det gör att nästa agent inte "förbättrar" systemet genom att återinföra ett alternativ som redan analyserats och förkastats.

Spec och plan är inte samma dokument

Jag försöker hålla isär vad och hur.

Spec: "Systemet ska kunna återuppta ett blockerat contentjobb från senaste godkända state utan att köra om redan godkända steg."

Plan: "Lägg till resume i content_ops.py, läs manifeststatus, mappa status till nästa agent och verifiera att required artifacts finns innan delegation."

Om implementationstekniken står i specen låser jag lösningen för tidigt. Om produktkravet bara finns i planen kan det försvinna när planen byts.

Hur jag använder Claude i specfasen

Jag använder inte modellen bara för att fylla i en template. Den får göra motstånd. Bra frågor är:

  • Vilka krav är inte testbara?
  • Vilka ord kan två utvecklare tolka olika?
  • Vilka failure states saknas?
  • Vilken data saknar source of truth?
  • Vilka permissions är bredare än use caset kräver?
  • Vilka antaganden bygger på nuvarande implementation snarare än faktiskt krav?
  • Vilka migrationer kan bli irreversibla?
  • Vad måste vara backward compatible?

Jag vill att den kommer tillbaka med invändningar innan den kommer tillbaka med kod.

Specification debt

Det finns också en risk att specs själva blir dåliga. Jag ser några typiska former av specification debt:

  • Copy-paste requirements. Gamla krav följer med trots att de inte gäller.
  • Adjective requirements. "Robust", "snabb", "intuitiv" utan mått eller scenario.
  • Missing negative space. Specen beskriver bara happy path och säger inget om failure states.
  • Implementation leakage. Specen beskriver dagens filstruktur i stället för produktkravet.
  • Dead specs. Koden har ändrats men specen är inte uppdaterad.

Det är därför jag vill ha spec compliance som en del av review, inte bara spec creation.

Från spec till evals

En bra spec är också råmaterial till evals. Om acceptanskriteriet säger "Writer får inte introducera nya factual claims utan source mapping" kan jag skapa testfall:

  1. approved evidence innehåller tre claims,
  2. writern instrueras att skriva en sektion,
  3. output extraheras till claims,
  4. verifiera att ingen fjärde materiell claim skapats utan mapping.

På samma sätt kan user stories bli integrationstester och examples bli regressionstest. Det är en av de starkaste anledningarna till att specs är mer värdefulla i AI-utveckling än de ibland var i traditionell utveckling. AI:n kan hjälpa till att omsätta samma intent till både implementation och test — om intentet först är explicit.

När jag fortfarande använder en "superprompt"

Det finns tillfällen där en stor prompt är rätt verktyg, särskilt för en avgränsad analys där hela kontexten behövs en gång. Skillnaden är att jag inte längre förväxlar den med systemets permanenta dokumentation. Jag kan exempelvis skriva en stark audit-prompt för att reviewa en spec. Men auditens findings går tillbaka in i specen. De stannar inte bara i chatthistoriken. Det är en viktig mental modell:

Min checklista för en AI-vänlig spec

Innan jag lämnar en större spec till en coding agent vill jag kunna svara ja på:

  1. Är problemet tydligt utan att beskriva lösningen?
  2. Finns explicit mål och non-goals?
  3. Är centrala termer definierade?
  4. Finns source of truth för viktig data?
  5. Är business rules separerade från prose?
  6. Finns failure states?
  7. Finns permissions/security constraints?
  8. Är acceptanskriterier observerbara?
  9. Finns examples/counterexamples där språk kan misstolkas?
  10. Finns migrations- och compatibilitykrav där de behövs?
  11. Kan tests eller evals härledas från specen?
  12. Kan nästa person förstå varför viktiga beslut togs?

Om inte försöker jag förbättra specen innan jag ber modellen bygga. Det är i praktiken det som har ersatt mina allt längre "gör exakt så här och glöm inget"-prompts.

Hur detaljerad ska en spec vara? Det finns ingen poäng i att specificera sådant som agenten säkert kan upptäcka i repot. Om kodbasen redan visar vilket formatteringsverktyg som används behöver specen sällan säga "använd Prettier". Jag försöker lägga detaljer där fel tolkning är dyr:

  • business rules,
  • data semantics,
  • permissions,
  • backward compatibility,
  • failure behavior,
  • acceptanskriterier,
  • scope/non-goals.

Implementationdetaljer som kan härledas från befintliga conventions får ofta ligga i planen. Det håller specen kortare och mer hållbar.

En bra spec ska kunna överleva ett modellbyte

Det här är ett test jag gillar. Om jag byter Claude mot en annan coding agent i morgon, är specen fortfarande begriplig och komplett? Om svaret är nej har jag sannolikt lagt för mycket av projektets kunskap i modell-specifika prompttrick. Skills, agents och toolkonfiguration får gärna vara leverantörsspecifika. Men domänkraven bör inte vara det. Det gör också multi-model routing enklare. En billig modell kan göra en avgränsad task eftersom kravet och outputkontraktet redan är tydligt, medan en starkare modell kan användas för arkitektur eller svåra reviews.

Reviewa diffen mot specen, inte bara mot koden

En vanlig code review frågar: fungerar koden och ser den rimlig ut? I ett spec-driven flow vill jag dessutom fråga:

  • vilket acceptance criterion uppfyller den här ändringen?
  • finns kod som inte kan härledas till spec/plan?
  • finns speckrav som inte implementerats?
  • introducerades ny behavior som borde tillbaka in i specen?

Det kan automatiseras delvis med en reviewer-agent som får spec, plan, tasks och diff samtidigt. GitHubs Spec Kit har samma grundidé i sina analyssteg, så som de var utformade vid tidpunkten för den här artikeln: kontrollera konsistens och coverage mellan artefakter innan implementationen betraktas som klar.

Jag trodde länge att bättre AI-coding främst handlade om bättre prompts. Nu ser jag prompten som den minsta, mest flyktiga artefakten i kedjan. Det som gör störst skillnad i större projekt är att intentionen finns kvar i en form som går att reviewa, versionera, testa och återanvända.

När specen är bra blir prompten enklare. Planen blir tydligare. Reviewen får ett facit. Evals går att härleda från acceptanskriterier. Och nästa agent behöver inte läsa mina tankar för att förstå varför systemet ser ut som det gör.

Specs gör delegering billigare. En praktisk effekt jag märker är att jag kan lämna över arbete mellan modeller eller sessioner utan att återberätta hela historiken. Om spec, plan och decisions finns i repot behöver nästa agent inte förlita sig på gammal chatthistorik. Det spelar särskilt stor roll i långa projekt där kontextfönster, människor och modeller byts. Den permanenta artefakten blir organisatoriskt minne. Prompten blir bara den instruktion som pekar på vilket steg som ska köras nu. Det är därför jag ser specs som mer än ett sätt att få bättre kod. De är ett sätt att minska beroendet av att rätt person eller rätt AI råkar minnas varför ett beslut togs.

Den korta versionen. Ju större och mer långlivad förändringen är, desto mindre vill jag att dess viktigaste krav bara ska finnas i en prompt. Prompten startar arbetet. Specen gör intentionen granskningsbar och beständig. Det är den arbetsfördelningen jag försöker bevara även när modellerna blir bättre.

Källor och vidare läsning

Relaterade artiklar

Prompt engineeringPraktisk AI
Dela
Fler artiklar