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

Nel mondo della creazione di software, esiste da tempo una tensione fondamentale tra l'idea di un programma e il programma stesso. Tradizionalmente, uno sviluppatore custodiva una visione nella propria mente o scarabocchiava note su un tovagliolo, per poi trascorrere mesi a tradurre quella visione in righe di codice. Il codice era l'artefatto primario, la cosa che veniva scritta, revisionata e mantenuta. Tuttavia, una nuova pratica è emersa recentemente in cui l'ordine viene invertito. Prima che venga scritta una singola riga di codice, uno sviluppatore, spesso con l'aiuto di uno strumento di intelligenza artificiale, redige una descrizione dettagliata e strutturata di ciò che deve essere costruito. Questa descrizione, scritta in linguaggio naturale, funge da progetto. Un agente di IA legge poi questo progetto e genera il software effettivo. Questo cambiamento significa che il documento più importante del progetto non è più il codice, ma la specifica stessa. Comprendere come queste specifiche vengono scritte, come cambiano e come diventano infine software funzionante è ora una questione critica per chiunque studi come viene creata la tecnologia.

Fino ad ora, nessuno aveva una mappa chiara di questo nuovo panorama. Sebbene siano apparsi decine di strumenti per aiutare gli sviluppatori a scrivere questi progetti, i documenti effettivi che producono non sono mai stati studiati su larga scala. I ricercatori Shyam Agarwal e Bogdan Vasilescu della Carnegie Mellon University hanno cambiato le cose creando SPECMINE, una vasta collezione di questi documenti di specifica e del codice che essi producono. Hanno raccolto quasi mezzo milione di file di specifica da progetti pubblici su GitHub, catturando un'istantanea di questa pratica mentre nasceva nel 2025 e nel 2026. Questa collezione include non solo il testo delle specifiche, ma anche l'intera cronologia dei progetti a cui appartengono, le persone che le hanno scritte e le modifiche specifiche apportate al codice quando le specifiche venivano aggiornate. È la prima volta che la comunità del software è stata in grado di vedere, in dettaglio, come una descrizione scritta si trasformi in un programma funzionante nell'era dell'IA.

I ricercatori hanno costruito questa collezione in due modi principali per garantire di aver catturato l'immagine completa. Per prima cosa, hanno cercato file denominati "spec.md" o "specs.md", che è il nome standard utilizzato dalla maggior parte dei nuovi strumenti. Questa ricerca da sola ha recuperato oltre 470.000 file da più di 73.000 diversi repository. Hanno poi aggiunto una seconda ricerca separata per uno strumento specifico chiamato AWS Kiro, che utilizza una convenzione di denominazione diversa con file separati per requisiti, progettazione e attività. Questo ha aggiunto altri 98.000 file. Combinando queste ricerche, hanno creato un censimento ampio che copre la stragrande maggioranza degli strumenti attualmente in uso. Ogni file in questa collezione è etichettato con informazioni sul progetto da cui proviene, come il numero di persone che hanno osservato il progetto, quale linguaggio di programmazione utilizza e quale strumento specifico ha generato la specifica.

Per capire come questi piani scritti portino effettivamente al codice, i ricercatori sono andati un passo oltre. Si sono concentrati su un gruppo più piccolo e attentamente selezionato di progetti popolari e hanno tracciato ogni richiesta di modifica del codice che coinvolgeva un file di specifica. Hanno trovato quasi 6.000 di tali richieste, note come pull request, in cui uno sviluppatore o un agente di IA aggiornava il progetto e il codice contemporaneamente. Ciò ha permesso loro di vedere il legame diretto tra l'idea e l'implementazione. In molti casi, la specifica e il codice cambiavano insieme in un unico aggiornamento, confermando che il progetto veniva utilizzato per guidare il lavoro in tempo reale. Tuttavia, i ricercatori hanno anche notato che questo non è l'unico modo in cui accade; a volte un piano viene scritto prima e il codice arriva dopo, o il codice viene scritto prima e il piano viene aggiunto successivamente. I dati mostrano che, sebbene il cambiamento simultaneo sia comune, la relazione è complessa e varia da progetto a progetto.

Oltre al semplice conteggio dei file, il team ha analizzato la struttura di questi documenti per vedere come siano fatti realmente. Hanno scoperto che le specifiche non sono semplici note casuali; spesso seguono schemi specifici, come l'uso di intestazioni chiare, elenchi o formati strutturati che le rendono facili da leggere sia per gli esseri umani che per le macchine. I ricercatori hanno anche costruito un sistema per tracciare i riferimenti all'interno di questi documenti. Se una specifica menziona un file specifico o un compito che deve essere svolto, il sistema controlla se quel file esiste effettivamente nel progetto o se il compito è stato mai completato. Ciò ha rivelato una lacuna significativa in alcuni progetti: ci sono migliaia di specifiche che menzionano file o compiti che non sono mai apparsi nel codice. Questo suggerisce che, sebbene la pratica di scrivere specifiche stia crescendo, la disciplina di garantire che tali specifiche siano pienamente realizzate è ancora in fase di evoluzione.

La collezione offre anche una finestra su chi stia scrivendo. Poiché i dati includono la cronologia di ogni modifica, i ricercatori possono vedere se una specifica è stata scritta da un essere umano, generata da un'IA o da un mix di entrambi. Possono tracciare quanto spesso questi documenti vengono aggiornati e quanto tempo rimangono attivi prima di essere abbandonati. Questo livello di dettaglio permette di affrontare domande precedentemente impossibili da rispondere, come se una specifica ben scritta porti a meno errori nel codice finale, o se certi tipi di progetti siano più propensi ad adottare questo nuovo modo di lavorare. I dati mostrano che la pratica si sta diffondendo rapidamente, con la stragrande maggioranza di questi file che appare solo negli ultimi due anni, segnando una nuova era distinta nello sviluppo del software.

I ricercatori hanno reso disponibile al pubblico l'intero dataset, organizzato in modo da permettere a chiunque di esplorare le connessioni tra idee e codice. Hanno fornito il testo grezzo delle specifiche, la cronologia dei progetti e i collegamenti tra i due, senza nascondere l'identità dei contributori o dei progetti, poiché tutto proviene da fonti pubbliche. Questa trasparenza significa che altri scienziati possono verificare i risultati, porre nuove domande e studiare come questa pratica cambi nel tempo. Il lavoro non sostiene che questo nuovo metodo sia perfetto o che abbia risolto tutti i problemi dello sviluppo del software. Al contrario, fornisce la prima solida base di evidenze, una mappa su larga scala di un territorio che era precedentemente inesplorato. Mostra che, sebbene gli strumenti per scrivere specifiche siano presenti e il volume del lavoro stia crescendo, il modo in cui esseri umani e macchine collaborano per trasformare quelle parole in software è ancora in fase di definizione, un progetto alla volta.