SPECMINE: A Large-Scale Corpus of Spec-Driven Development Artifacts

In de wereld van softwarecreatie bestaat er al lang een fundamentele spanning tussen het idee van een programma en het programma zelf. Traditioneel zou een ontwikkelaar een visie in zijn hoofd houden of aantekeningen op een servetje krabbelen, om vervolgens maandenlang die visie te vertalen naar regels code. De code was het primaire artefact, het ding dat werd geschreven, beoordeeld en onderhouden. Echter, een nieuwe praktijk is onlangs ontstaan waarbij de volgorde is omgedraaid. Voordat er ook maar één regel code wordt geschreven, stelt een ontwikkelaar, vaak met behulp van een kunstmatige intelligentie-tool, een gedetailleerde, gestructureerde beschrijving op van wat er gebouwd moet worden. Deze beschrijving, geschreven in gewone taal, fungeert als een blauwdruk. Een AI-agent leest vervolgens deze blauwdruk en genereert de eigenlijke software. Deze verschuiving betekent dat het belangrijkste document in het project niet langer de code is, maar de specificatie zelf. Begrijpen hoe deze specificaties worden geschreven, hoe ze veranderen en hoe ze uiteindelijk veranderen in werkende software, is nu een cruciale vraag voor iedereen die bestudeert hoe technologie wordt gemaakt.

Tot nu toe had niemand een duidelijke kaart van dit nieuwe landschap. Hoewel er tientallen tools zijn verschenen om ontwikkelaars te helpen bij het schrijven van deze blauwdijken, zijn de daadwerkelijke documenten die zij produceren nooit op grote schaal bestudeerd. Onderzoekers Shyam Agarwal en Bogdan Vasilescu van de Carnegie Mellon University hebben dat veranderd door SPECMINE te creëren, een enorme collectie van deze specificatiedocumenten en de code die ze produceren. Ze verzamelden bijna een half miljoen specificatiebestanden van publieke projecten op GitHub, waarmee ze een momentopname van deze praktijk vastlegden zoals deze ontstond in 2025 en 2026. Deze collectie bevat niet alleen de tekst van de specificaties, maar ook de volledige geschiedenis van de projecten waartoe ze behoren, de mensen die ze hebben geschreven, en de specifieke wijzigingen die in de code zijn aangebracht wanneer de specificaties werden bijgewerkt. Het is de eerste keer dat de softwaregemeenschap in detail kan zien hoe een geschreven beschrijving transformeert in een functionerend programma in het tijdperk van AI.

De onderzoekers hebben deze collectie op twee belangrijke manieren opgebouwd om ervoor te zorgen dat ze het volledige plaatje vastlegden. Ten eerste zochten ze naar bestanden met de naam "spec.md" of "specs.md", wat de standaardnaam is die de meeste van de nieuwe tools gebruiken. Alleen al deze zoekopdracht leverde meer dan 470.000 bestanden op uit meer dan 73.000 verschillende repositories. Vervolgens voegden ze een tweede, afzonderlijke zoekopdracht toe voor een specifieke tool genaamd AWS Kiro, die een andere naamgeving gebruikt met aparte bestanden voor vereisten, ontwerp en taken. Dit voegde nog eens 98.000 bestanden toe. Door deze zoekopdrachten te combineren, creëerden ze een brede census die de overgrote meerderheid van de momenteel in gebruik zijnde tools beslaat. Elk bestand in deze collectie is voorzien van informatie over het project waar het vandaan komt, zoals het aantal mensen dat het project heeft bekeken, welke programmeertaal het gebruikt en welke specifieke tool de specificatie heeft gegenereerd.

Om te begrijpen hoe deze geschreven plannen daadwerkelijk tot code leiden, gingen de onderzoekers nog een stap verder. Ze richtten zich op een kleinere, zorgvuldig geselecteerde groep populaire projecten en volgden elke aanvraag om de code te wijzigen die een specificatiebestand betrof. Ze vonden bijna 6.000 van dergelijke verzoeken, bekend als pull requests, waarbij een ontwikkelaar of een AI-agent de blauwdruk en de code tegelijkertijd bijwerkte. Dit stelde hen in staat om de directe link tussen het idee en de implementatie te zien. In veel gevallen veranderden de specificatie en de code samen in een enkele update, wat bevestigde dat de blauwdruk werd gebruikt om het werk in realtime aan te sturen. De onderzoekers merkten echter ook op dat dit niet de enige manier is waarop het gebeurt; soms wordt eerst een plan geschreven en komt de code later, of wordt de code eerst geschreven en wordt de blauwdruk achteraf toegevoegd. De gegevens laten zien dat hoewel de gelijktijdige verandering gebruikelijk is, de relatie complex is en per project verschilt.

Naast het simpelweg tellen van bestanden, analyseerde het team de structuur van deze documenten om te zien hoe ze er daadwerkelijk uitzien. Ze ontdekten dat de specificaties niet zomaar willekeurige aantekeningen zijn; ze volgen vaak specifieke patronen, zoals het gebruik van duidelijke koppen, lijsten of gestructureerde formaten die ze zowel voor mensen als machines gemakkelijk leesbaar maken. De onderzoekers bouwden ook een systeem om referenties binnen deze documenten te traceren. Als een specificatie verwijst naar een specifiek bestand of een taak die moet worden uitgevoerd, controleert het systeem of dat bestand daadwerkelijk bestaat in het project of dat de taak ooit is voltooid. Dit onthulde een aanzienlijk gat in sommige projecten: er zijn duizenden specificaties die bestanden of taken noemen die nooit in de code zijn verschenen. Dit suggereert dat hoewel de praktijk van het schrijven van specificaties groeit, de discipline om ervoor te zorgen dat die specificaties volledig worden gerealiseerd, nog volop in ontwikkeling is.

De collectie biedt ook een venster naar wie de schrijvers zijn. Omdat de gegevens de geschiedenis van elke wijziging bevatten, kunnen onderzoekers zien of een specificatie door een mens is geschreven, door een AI is gegenereerd, of een combinatie van beide is. Ze kunnen bijhouden hoe vaak deze documenten worden bijgewerkt en hoe lang ze actief blijven voordat ze worden verlaten. Dit niveau van detail maakt vragen mogelijk die voorheen onmogelijk te beantwoorden waren, zoals of een goed geschreven specificatie leidt tot minder fouten in de uiteindelijke code, of dat bepaalde soorten projecten eerder geneigd zijn deze nieuwe manier van werken te adopteren. De gegevens tonen aan dat de praktijk zich snel verspreidt, waarbij de overgrote meerderheid van deze bestanden in slechts de laatste twee jaar is verschenen, wat een duidelijk nieuw tijdperk in softwareontwikkeling markeert.

De onderzoekers hebben deze volledige dataset publiekelijk beschikbaar gesteld, op een manier die iedereen in staat stelt de verbindingen tussen ideeën en code te verkennen. Ze hebben de ruwe tekst van de specificaties geleverd, de geschiedenis van de projecten en de links tussen de twee, zonder de identiteiten van de bijdragers of de projecten te verbergen, aangezien alles afkomstig is van publieke bronnen. Deze transparantie betekent dat andere wetenschappers de bevindingen kunnen verifiëren, nieuwe vragen kunnen stellen en kunnen bestuderen hoe deze praktijk in de loop van de tijd verandert. Het werk beweert niet dat deze nieuwe methode perfect is of dat het alle problemen van softwareontwikkeling heeft opgelost. In plaats daarvan biedt het het eerste solide fundament van bewijs, een grootschalige kaart van een gebied dat voorheen onverkend was. Het laat zien dat hoewel de tools om specificaties te schrijven aanwezig zijn en de omvang van het werk groeit, de manier waarop mensen en machines samenwerken om die woorden in software te veranderen, nog steeds wordt uitgevogeld, project voor project.