Specifikationsdriven utveckling: Det positiva – och vad vi lärde oss efter tre månader

Efter tre månader hade vi en tydligare bild av när den extra strukturen var till hjälp och när den var i vägen.

En av våra tekniker höll på att förbereda en datamigrering och bestämde sig för att använda specifikationsdriven utveckling (SDD) för att planera arbetet. SDD var tänkt att hjälpa dem att upptäcka brister i ett tidigt skede, göra tillvägagångssättet enklare att granska och ge agenten tydliga riktlinjer. Den resulterande planen var detaljerad och såg ganska rimlig ut på papperet. Arbetet strukturerades så här:

Problem → Undersökning → Specifikation → Granskning → Implementering → Verifiering

När implementeringen fortskred insåg teknikern att två jobb kunde krocka och skapa dubbletter av anpassade fält. Tillvägagångssättet gjorde också koden alltmer komplex och svår att följa. Lyckligtvis upptäckte de problemet, stoppade implementeringen, skrev ett designsdokument på en sida och taggade några medarbetare för att få deras synpunkter. Tillsammans gick de igenom designen och hittade ett säkrare tillvägagångssätt.

Den ursprungliga specifikationen gjorde vad vi bad om: den höll projektet i den ursprungliga riktningen. Problemet var att riktningen var fel. En detaljerad specifikation gjorde det enkelt att fortsätta med projektet, även när utgångsidén var osäker. Representanten kunde utveckla den idén snabbare än vad andra hann stanna upp och ifrågasätta den.

Det projektet visade en risk med ökad struktur: en agent kunde föra med sig samma felaktiga antagande från specifikationen till koden och testerna. Specifikationen, koden och testerna stämde överens med varandra, men det betydde inte att det underliggande antagandet var rätt. För mer riskfyllda beslut behövde någon annan fortfarande gå tillbaka till det ursprungliga målet och leta efter sätt på vilka implementeringen kunde strida mot det.

Ändå tog agenterna sig an arbete som varade längre än en session, och en prompt räckte ofta inte för att bevara vad projektet försökte göra eller varför. Det ledde oss till att skapa /spec-driven, ett arbetsflödesverktyg med en specifikation i centrum. Specifikationen gjorde projektets inriktning tillgänglig för nästa session. Skript tillförde sammanhang och utförde kontroller. När en körning avslöjade en saknad regel, kontroll eller del av kontext kunde vi lägga till den i arbetsflödet så att senare agenter inte behövde upptäcka samma brist igen.

Det råder fortfarande en hel del oenighet om huruvida SDD:s extra struktur är värd besväret. Microsoft och AWS främjar SDD, medan Thoughtworks beskriver det som nytt och omstritt och utövare rapporterar blandade erfarenheter. Kritiker varnar för att SDD kan producera mer Markdown än vad utvecklare kan underhålla, omvandla en detaljerad specifikation till kod skriven i prosa eller lämna kvar en annan beskrivning av systemet som avviker från koden.[1][2][3]

Efter tre månaders faktisk användning lärde vi oss att den viktiga frågan inte var om vi skulle använda SDD eller inte. Det var vad representanten saknade i projektet. Ibland var svaret en specifikation. Ibland var det ett bättre exempel, en automatiserad kontroll eller en tekniker som kände till området.

Varför vi utvecklade /spec-driven

Vissa tekniker på Asana hade redan testat GitHub Spec Kit och OpenSpec, men inget av dem blev en del av deras vanliga arbetsflöde. Vi ville ha en version som vi kunde anpassa allteftersom vi lärde oss och som vi kunde koppla till Asanas utvecklingsprocess.

Det inbyggda planeringsläget kunde redan undersöka kodbasen och ta fram en användbar implementeringsplan innan ändringar gjordes. SDD tillförde mer struktur kring den planen: den höll problemet, de viktigaste besluten och godkännandekriterierna synliga under implementeringen och verifieringen.

Före implementeringen återgav /spec-driven sin förståelse av problemet och tog upp de frågor som kunde ändra planen. Det gav teknikern en chans att korrigera riktningen innan det fanns kod att skriva om.

Vi sparade det läget i databasen så att man inte behövde gissa sig till vad som hade hänt under senare sessioner. Vi ville att arbetsflödets regler skulle vara deterministiska, så skript hanterade bokföringen och kontrollerna. Modellen hanterade de delar som gynnades av omdöme: att ställa frågor, väga kompromisser och förklara beslut.

Arbetsflödet innehöll flera kommandon. Teknikerna använde /spec-driven spec för att gå igenom öppna frågor och ta fram en specifikation och en implementeringsplan. Efter att ha granskat planen använde de /spec-driven ship för att genomföra den, verifiera resultatet och förbereda arbetet för granskning. En tillståndsmaskin spårade projektet när det gick igenom dessa kommandon, så att senare sessioner visste vad som hade hänt och vad som kom härnäst.

Från början ville vi att /spec-driven skulle vara mer än bara ett sätt att skriva och genomföra specifikationer. Vi ville också att det skulle organisera arbetsflöden för agenter. Den ordnar uppgifter efter beroende och håller överlappande filändringar i separata körningsomgångar. Den skickar oberoende arbete till flera agenter parallellt och använder sedan resultaten för att bestämma vad som kan utföras härnäst.

Känns som en GPS för arbetet: när som helst är det tydligt vad nästa steg är och var de viktiga besluten fattas, så det är svårt att köra fast.”

Asana-ingenjörer använde /spec-driven både på ett specifikationsinriktat och ett specifikationsförankrat sätt. Med spec-first använde de en specifikation för att välja en riktning och slutade sedan att uppdatera den. Med specifikationsförankring höll de den aktuell när arbetet ändrades. Teknikerna skrev också oberoende specifikationer för delar av en större insats, så att en person kunde använda arbetsflödet utan att be hela teamet att anpassa sig till det.

När /spec-driven är värt det extra arbetet

Den extra strukturen lönade sig mest när viktigt sammanhang behövde finnas kvar under flera sessioner, överlämningar eller många relaterade uppgifter. Teknikerna kunde granska hur planen ändrades, och projektets inriktning var fortfarande tillgänglig när arbetet flyttades till en annan agent-session eller person. Två produktinsatser hade levande specifikationer under ungefär två till tre månader: den ena utvecklade en stor ny funktion, den andra flyttade datum för underuppgifter till överordnade uppgifter.

Jag har precis avslutat ett ganska stort initiativ med specifikationsdrivet arbete och jag tycker att det verkligen hjälpte mig! Jag arbetade med planen i ungefär två dagar och fick sedan allt tekniskt arbete gjort och sammanfört på tre dagar.”

Specifikationerna gjorde överlämningar enklare. Någon som tog över ett pausat projekt kunde se vad teamet försökte göra, varför det hade tagit den formen och vad som återstod. De behövde inte rekonstruera projektet utifrån åtaganden och konversationer.

Teknikerna använde också /spec-driven för att samordna stora batcher av agentstyrt arbete. I Asana-adminkonsolen, där IT-team på kundföretag hanterar organisationsövergripande säkerhets-, åtkomst-, integrerings- och delningsinställningar, använde teknikerna den för att flytta 66 inställningar till delade ramverk. För att flytta dessa inställningar krävdes cirka 150 migreringar över flera ramverk i adminkonsolen. Varje migrering blev ett Asana-ärende för en molnagent, och ingenjörerna körde dem i parallella grupper och uppdaterade de återstående ärendena baserat på tidigare resultat.

Teamet som stod för den insatsen rapporterade att 91 % av migreringarna inte behövde revideras efter granskningen och att den övergripande insatsen slutfördes mer än en månad tidigare än den ursprungliga planen.

En annan stor migrering behövde bara en kort uppmaning. Skillnaden var hur mycket kodbasen redan hade tydliggjort. Den innehöll exempel som agenterna kunde följa och kontroller som kunde verifiera resultatet. Agenterna för adminkonsolen kunde inte lista ut alla krav utifrån koden, så arbetet behövde mer struktur.

/spec-driven hjälpte också till med att snabbt ta fram prototyper. Teknikerna kunde snabbt besvara tillräckligt många av de öppna produktfrågorna för att skapa en fungerande helhetsupplevelse. Produktchefer och designers kunde prova en prototyp innan ingenjörerna investerade i att göra den produktionsklar. Om ingenjörerna bestämde sig för att behålla koden behövde den vanligtvis städas upp ordentligt innan den kunde slås samman. Vid det laget hade prototypen redan visat om idén var värd att genomföra.

Vad de första siffrorna visade

Vi uppmuntrade alla att prova /spec-driven en gång, men krävde inte fortsatt användning. Ungefär hälften av teknikerna provade den. Under den sista månaden varierade den veckovisa användningen från 30 till 50 ingenjörer. Bland de inbyggda och Asana-utvecklade agentfärdigheterna som teknikerna använde direkt hamnade /spec-driven på tredje plats. Den fortsatta användningen var uppmuntrande, men den gav oss inte någon information om hur /spec-driven påverkade leveransen.

Det är välkänt att det är svårt att mäta teknikens hastighet. Pull-förfrågningar och tillägg av implementeringskod är inte perfekta mått på produktivitet, men vi anser att de ofta är användbara indikatorer. För jämförelsen av hastigheten tittade vi på sju ingenjörer och 524 sammanslagna pull-begäranden under fyra månader. Vi jämförde arbetet före och efter varje ingenjörs första tydliga användning av /spec-driven och exkluderade specifikationer, planer och andra arbetsflödesartefakter. För jämförelsen av återställningar klassificerade vi en pull-förfrågan som /spec-driven när den ändrade arbetsflödets projektfiler.

Antalet pull-förfrågningar per vecka ökade med 38 %, och antalet tillägg av implementeringskod ökade 2,66 gånger. En kort period med ovanligt hög volym påverkade resultatet för tilläggen. Även utan den var tilläggen fortfarande 66 % högre. Andelen explicita återställningar var också något lägre: 1,2 % för /spec-drivet arbete, jämfört med 1,66 % för andra pull-förfrågningar.

Mer kod är inte nödvändigtvis ett bra resultat. En agent kan producera en stor implementering när en mindre skulle räcka, så ökningen av kodtillägg kan ha återspeglat onödigt stora lösningar snarare än mer slutfört arbete. Den vanliga granskningen gav oss en kontroll mot det här feltypen. Vi förlitade oss på att granskare skulle flagga implementeringar som var större eller mer komplexa än vad problemet krävde, och dessa ändringar godkändes ändå. Det gav oss viss tillförsikt om att överdimensionerade implementeringar inte låg bakom hela ökningen.

Dessa jämförelser var inte kontrollerade, och vi kunde inte skilja effekten av /spec-driven från projektmixen eller mer omfattande förbättringar av agentverktygen. Trots dessa begränsningar blev vi uppmuntrade av resultaten.

Vad som fortfarande behöver förbättras

Granskningen av dokumenten kan bli en flaskhals

Att skapa en specifikation tog allt från 30 minuter till flera dagar beroende på ingenjörens kännedom om området och projektets komplexitet och risk. Teknikerna kunde använda /spec-driven för att få en agent att snabbt skriva ett utkast till en specifikation, men det tog fortfarande tid att granska det.

Under en insats ägnade en ingenjör flera timmar åt att granska en pull-begäran med research.md, en arbetsfil där agenten registrerade vad den lärde sig av kodbasen, dokumentationen och tidigare beslut innan den utarbetade specifikationen. Några av dessa resultat var vaga, oprecisa eller något felaktiga.

Den granskningen visade att vi inte hade kommit överens om huruvida dessa filer var tillfälliga arbetsanteckningar eller dokumentation som framtida tekniker skulle kunna lita på. Vissa ingenjörer värdesatte dokumentationen av hur ett beslut fattades. Andra var oroliga för att det skulle se ut som att den var auktoritativ om man checkade in ofullständig research.

I ett av infrastrukturteamen blev granskningen av specifikationerna ett nytt hinder före implementeringen.

Jag tyckte att kommandona och arbetsflödet kändes mycket mer komplicerade och tidskrävande än att bara skapa en plan och sedan genomföra den.”

De flesta granskare ville inte läsa en lång specifikation och sedan även granska koden. När arbetet nådde en pull-begäran behövde överlämningen innehålla en sammanfattning av beslutet, varför vi fattade det, vad som såg riskfyllt ut och hur vi kontrollerade resultatet. Om själva riktningen behövde granskas behövde vi be om det tidigare, medan det fortfarande var lätt att ändra.

En användbar specifikation ändras i takt med projektet

Teknikerna fortsatte att lära sig när de implementerade planen. Att uppdatera specifikationen med vad de lärde sig krävde en insats. Dess detaljer var till hjälp under implementeringen genom att visa vad agenten trodde att den skapade. Därefter upprepade mycket av den detaljen koden.

Vi anser nu att en fungerande specifikation bör växa medan projektet är osäkert och krympa när koden kan förklara implementeringen. Det som återstår bör hjälpa nästa läsare att förstå designen, viktiga beslut, begränsningar och olösta risker.

Slutförda specifikationer väcker en relaterad fråga: vad ska hända med dem? Vi väntade för länge med att svara på den. Genom att lämna dem i monorepon blir de lätta att hitta, men det innebär också att det blir kvar dokument som ingen äger. Vi flyttar dem till ett separat arkiv. Vi behöver fortfarande en kortare överlämning som bevarar det som är viktigt senare. Om ett dokument skapade mer arbete än det sparade in var det inte till någon hjälp.

Bygga in feedbackslingor i systemet

Ibland var lösningen inte ett nytt dokument utan en ändring i systemet kring agenten. Ett exempel var en bugg i hur /spec-driven läste Markdown: rubriker och kryssrutor i exempel kunde misstas för faktiska milstolpar eller oavslutade uppgifter. Efter att ha registrerat buggen sökte vi igenom resten av /spec-driven och hittade flera kommandon med sin egen lilla Markdown-parser och samma blinda fläck. Vi ersatte dem med en gemensam parser, lade till regressionstester och en arkitekturkontroll och implementerade lösningen i miljön. OpenAI beskriver ett relaterat tillvägagångssätt som harness engineering: placera viktig kunskap där agenter kan hitta den, se till att regler kan verkställas och använda fel för att förbättra miljön runt agenten.

Andra lärdomar kunde inte bli ett test eller en arkitekturregel. Vi sammanställde återkommande misstag till en vägledning. Eftersom /spec-driven guidade användare genom ett förutsägbart arbetsflöde kunde vi visa varje lektion när agenten nådde det relevanta steget. Det var fortfarande ingenjörerna som bestämde vilka lärdomar som var tillämpliga utöver det ursprungliga projektet.

Vi testade vägledningen på åtta tidigare pull-förfrågningar, tillsammans med syntetiska fall som utformats för att upptäcka irrelevanta råd. I en uppföljning testade vi tre av dessa tidigare uppgifter med korta, medellånga och detaljerade uppmaningar, vilket gav totalt nio jämförelser. Vägledningen lyfte fram en användbar extra fråga eller planeringsgräns i åtta av de nio jämförelserna. Ett separat test omfattade ytterligare tre tidigare uppgifter. Det förbättrade tydligt två planer; i den tredje hade den ovägledda agenten redan upptäckt problemet.

Den mest användbara vägledningen ställde frågor om beteendeförändringar, berörda konsumenter och varianter samt kontrakt mellan API:er, scheman eller parsrar. Utvärderingarna omfattade endast frågor och planer. Vi mätte inte om vägledningen påskyndade implementeringen. Begränsad vägledning blev också föråldrad snabbare och dök ibland upp i arbete som inte var relaterat.

Att underhålla vägledningen och utvärderingarna krävde mer arbete än att utveckla den första versionen. Vi kunde kartlägga landminan med hjälp av vägledning, röja den genom att åtgärda det underliggande systemet eller acceptera risken att en agent eller granskare skulle behöva hitta den igen. Vi kartlade den vanligtvis först eftersom det var billigare. Att åtgärda det underliggande API:et, testet, dokumentationen eller exemplet krävde mer arbete, men gynnade alla och gjorde vägledningen överflödig.

Hur vi skulle arbeta med /spec-driven nu

Vi ville hindra teknikerna från att upprepa samma uppmaningar och förklara projektet på nytt utan att ta bort den användbara friktionen. Representanten behövde fortfarande pausa när den hade en viktig fråga, när det saknades bevis eller när nästa steg krävde mänskligt omdöme. Vi kom fram till några praktiska riktlinjer:

• För de flesta små, lokala ändringar räcker det med en konversation eller en kort plan.

• Använd specifikationsfokus för att komma överens om en riktning. Håll fast vid specifikationen när beslut måste gälla även vid senare möten eller överlämningar.

• Ta inte med alla saknade delar i specifikationen. Verktyget ska ge kontext och genomföra kontroller; arkitektoniska bedömningar behöver fortfarande mänsklig granskning.

När en specifikation är värd att behålla ska du skriva den för nästa läsare. Se till att beslut och risker är lätta att hitta, länka till underlag istället för att kopiera det och bestäm vad som ska hända med specifikationen när projektet avslutas.

Vart vi går härifrån

Efter tre månader använder teknikerna fortfarande /spec-driven när arbetet sträcker sig över flera sessioner, överlämnas mellan olika personer eller delas upp i många relaterade uppgifter. De har använt den för att driva projekt som sträcker sig över flera månader framåt och för att organisera stora mängder arbete som utförs av agenter. Det är ett bra resultat för ett internt experiment.

När vi utökade /spec-driven för att stödja fler typer av arbete löste vissa nya funktioner verkliga problem för specifika team, men gjorde arbetsflödet mer komplext för alla. I nästa version vill vi gå mot en mindre, mer fokuserad kärna.

Folk har starka åsikter om SDD och Harness Engineering. Vi lärde oss mer genom att prova dem i det riktiga arbetet än genom att diskutera dem. Innan vi lägger till fler processer frågar vi nu vad agenten saknar i det projektet. Börja i liten skala, se var arbetsflödet hjälper till eller ställer till problem och anpassa det sedan baserat på vad du lär dig.

[1] Birgitta Böckeler, ”Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl”, oktober 2025.

[2] François Zaninotto, ”Spec-Driven Development: The Waterfall Strikes Back”, november 2025.

[3] Gabriella Gonzalez, ”A sufficiently detailed spec is code”, mars 2026.

Om författaren

Walter Li är mjukvaruingenjör i Asanas team för kärnlagringsinfrastruktur och Rohan Batra är mjukvaruingenjör i teamet för backend-ramverk. Båda tillbringade några månader i Agent Success Tiger-teamet, där de ledde utvecklingen och utvärderingen av det /spec-drivna arbetsflöde som beskrivs i det här inlägget.

Ett stort tack till teamet

Ett särskilt tack till Leo Zhang, Karol Krupa, Gordie Levitsky och Mitch Conquer för att de hjälpte oss att utforma och utveckla /spec-driven och för att de var bland de första att använda det.