Flusso di lavoro per lo sviluppo guidato dalle specifiche: dai requisiti al codice

Lo sviluppo guidato dalle specifiche (Spec-Driven Development) funziona quando la specifica è un flusso di lavoro, non un documento da archiviare dopo il via. L’obiettivo non è produrre un lungo documento di requisiti del prodotto.

L’obiettivo è attraversare una sequenza di artefatti revisionabili che riducono l’ambiguità ciascuno, prima che chiunque – umano o agente AI – modifichi il codice di produzione.

Se non sai cos’è SDD a livello concettuale, inizia con Cos’è lo Spec-Driven Development? per definizioni, confronti con TDD e BDD, e il caso per trattare la specifica come fonte di verità. Questo articolo nel cluster di documentazione Architettura dell’App è la guida operativa. Attraversa le cinque fasi, mostra cosa dovrebbe contenere ciascun artefatto, spiega dove si inseriscono gli agenti AI e fornisce modelli riutilizzabili che puoi copiare nel tuo repository oggi stesso.

SDD è un Flusso di Lavoro, Non un Documento

Il modo di fallimento più comune nello sviluppo guidato dalle specifiche è trattare la specifica come burocrazia. Un team scrive un lungo documento di requisiti, lo memorizza in un wiki e poi codifica dalla memoria e dalle thread di chat. La specifica esiste, ma non guida nulla. È teatro della documentazione, ed è peggio di nessuna specifica perché crea falsa sicurezza.

Un flusso di lavoro SDD funzionante produce una catena di artefatti, ciascuno revisionato prima dell’inizio della fase successiva. I requisiti riducono l’ambiguità del prodotto. Il design riduce l’ambiguità tecnica. I compiti riducono l’ambiguità di esecuzione. L’implementazione produce codice contro un obiettivo noto. La validazione prova che la catena ha tenuto. Quando qualsiasi fase rivela un errore, si corregge l’artefatto e si riparte da quel punto – non dopo che tre mila righe di deriva sono atterrate in main.

Il flusso di lavoro è neutrale rispetto agli strumenti. Puoi eseguirlo con file markdown in Git, con GitHub Spec Kit, con piani di Cursor, o con un editor di testo semplice e un revisore disciplinato. Ciò che conta è la sequenza e i punti di controllo della revisione, non il marchio degli strumenti.

Fase 1 – Specificare i Requisiti

La fase di specificazione risponde a quale problema stai risolvendo e a cosa significa “fatto”. Evita deliberatamente il “come” costruirlo. Il momento in cui la tua specifica dei requisiti dice “usa gli insiemi ordinati di Redis”, hai smesso di specificare e hai iniziato a progettare nel documento sbagliato. Tieni l’implementazione fuori dai requisiti. Mettila nel piano.

Dichiarazione del problema e utenti

Inizia con un paragrafo che dichiara il problema in linguaggio semplice. Nomina gli utenti interessati e la situazione che rende il problema doloroso. Una buona dichiarazione del problema permette a un revisore che non era nella riunione di pianificazione di decidere se una soluzione proposta affronta effettivamente il dolore.

Esempio per una funzionalità di limitazione della frequenza (rate-limiting) dell’API:

I consumatori dell’API sul piano gratuito possono inviare richieste illimitate, il che causa picchi di costi e impatto da “vicino rumoroso” sugli inquilini a pagamento. Gli operatori della piattaforma hanno bisogno di un limite per chiave applicabile senza intervento manuale.

Obiettivi, non-obiettivi e criteri di accettazione

Gli obiettivi descrivono i risultati che consegnerai. I non-obiettivi descrivono il lavoro adiacente tentante che non farai esplicitamente. Insieme, delimitano la creatività dell’agente, il che è essenziale quando gli strumenti AI altrimenti “utilmente” espandono l’ambito.

I criteri di accettazione dovrebbero essere abbastanza precisi che ciascuno mappi su almeno un test. “L’endpoint è sicuro” non è un criterio di accettazione. “Le richieste non autenticate ricevono HTTP 401” sì. Se non puoi scrivere un criterio concreto, il requisito è ancora troppo vago per essere implementato.

Domande aperte

Elenca ogni decisione che non è ancora stata stabilita. Le domande non chiare non sono un segno di fallimento. Sono la fase di specificazione che fa il suo lavoro. Risolvi prima di scrivere il piano di design, o pagherai l’ambiguità nel lavoro di reimplementazione.

Un modello minimo di requisiti:

## Problema
[Un paragrafo: chi soffre, perché, e cosa scatena il dolore.]

## Utenti
- [Ruolo utente primario]
- [Ruolo utente secondario]

## Obiettivi
1. [Risultato misurabile]
2. [Risultato misurabile]

## Non-obiettivi
- [Esplicitamente fuori dall'ambito]
- [Esplicitamente fuori dall'ambito]

## Criteri di accettazione
- [ ] [Comportamento verificabile]
- [ ] [Comportamento verificabile]

## Domande aperte
- [ ] [Domanda che blocca la pianificazione]

Fase 2 – Pianificare il Design

La fase di pianificazione traduce l’intento in decisioni tecniche. Qui appartengono gli insiemi ordinati di Redis, insieme ai limiti dei moduli, alle modifiche dello schema, ai contratti API, ai passaggi di migrazione, ai vincoli di sicurezza e alla strategia di test. Il piano è derivato dalla specifica dei requisiti più i vincoli esistenti del tuo progetto – scelte dello stack, registri decisionali e convenzioni memorizzate in file come AGENTS.md o una costituzione del progetto.

Architettura e moduli interessati

Nomina i moduli, servizi o pacchetti che cambieranno e riassumi il pattern di integrazione. Se la funzionalità attraversa un limite di servizio, documenta il contratto su entrambi i lati. Gli agenti allucinano API quando i contratti sono impliciti. Rendere espliciti nel piano previene endpoint inventati e forme di risposta errate.

Modello di dati, contratti API e migrazioni

Documenta le modifiche dello schema, nuove tabelle o campi, requisiti di indicizzazione e regole di compatibilità backward. Per le API HTTP, scrivi metodo, percorso, forma della richiesta, forma della risposta e codici di errore. Per gli eventi, scrivi nomi degli argomenti, schemi dei payload e semantiche di consegna. Includi i passaggi di migrazione e le note di rollback quando il modello di dati cambia.

Sicurezza, osservabilità e strategia di test

I vincoli di sicurezza appartengono al piano, non come pensieri successivi nella revisione del codice. Nota i requisiti di autenticazione, le regole di autorizzazione, i limiti di validazione degli input e i dati che non devono comparire nei log. L’osservabilità dovrebbe coprire metriche, log o trace necessarie per confermare che la funzionalità funziona in produzione.

La strategia di test si collega ai criteri di accettazione. Identifica quali criteri hanno bisogno di test unitari, quali hanno bisogno di test di integrazione e quali hanno bisogno di verifica manuale. Se usi test unitari in Go o test unitari in Python, nomina i pacchetti e i file di test che ti aspetti di aggiungere. Un piano senza una strategia di test è un piano che verrà spedito con lacune che scoprirai in produzione.

Fase 3 – Decomporre i Compiti di Implementazione

La fase dei compiti decompone il piano in slice abbastanza piccole da implementare, revisionare e validare in modo indipendente. È ciò che rende lo sviluppo assistito da agente revisionabile. Invece di una singola enorme diff, ottieni una sequenza di cambiamenti focalizzati che ciascuno mappano a un requisito nominato.

Dimensionamento dei compiti e dipendenze

Un buon compito tocca un insieme limitato di file, si completa in una sessione dell’agente e termina con un passo di verifica. I compiti dovrebbero dichiarare le dipendenze esplicitamente. I compiti di migrazione vengono eseguiti prima del codice che legge il nuovo schema. Le modifiche alla libreria condivisa vengono eseguite prima dei consumatori. Le modifiche al middleware di autenticazione vengono eseguite prima degli endpoint che dipendono dal nuovo comportamento.

File, validazione e punti di controllo della revisione

Ogni compito dovrebbe elencare i file che probabilmente cambieranno, i criteri di accettazione che soddisfa e come validare il completamento. La validazione potrebbe essere un comando di test, un esempio curl o un controllo manuale descritto in passaggi copiabili. Ogni compito termina a un punto di controllo della revisione umana. Il revisore conferma che la diff corrisponde alla descrizione del compito prima che il prossimo compito inizi.

Un’entry minima di compito:

### Compito 3 -- Aggiungi middleware rate-limit

**Dipende da:** Compito 1 (schema), Compito 2 (repository)
**File:** middleware/ratelimit.go, middleware/ratelimit_test.go, server.go
**Soddisfa:** AC-2 (429 oltre il limite), AC-3 (header del limite nella risposta)
**Valida:** `go test ./middleware/...` passa; curl oltre il limite restituisce 429 con Retry-After
**Punto di controllo revisione:** Conferma che il middleware si esegua dopo l'autenticazione, prima dell'handler

Attenzione alle esplosioni di compiti generati. Gli agenti AI possono produrre piani di cinquanta compiti in pochi secondi. La maggior parte di quei compiti saranno ridondanti o troppo granulari per essere revisionati efficientemente. Un elenco di compiti utile per una funzionalità di medie dimensioni spesso ha da cinque a quindici elementi, non cinquanta.

Fase 4 – Implementare un Compito alla Volta

L’implementazione è deliberatamente ristretta. Scegli un compito, fornisci all’agente solo il contesto di cui ha bisogno per quel compito e fermati quando la validazione passa. I reset del contesto tra i compiti sono una funzionalità, non un bug. Prevengono che le assunzioni precedenti contaminino il lavoro successivo e mantengono le diff revisionabili.

Applica i vincoli dallo stack delle specifiche

L’agente implementante dovrebbe leggere la specifica dei requisiti, il piano di design, la descrizione del compito corrente e i vincoli a livello di progetto. I vincoli sono la sezione con il ROI più alto che la maggior parte dei team salta. Dicono all’agente cosa non fare – non rifattorizzare moduli non correlati, non cambiare le firme delle API pubbliche fuori da questa funzionalità, non introdurre nuove dipendenze senza aggiornare il piano.

Aggiorna il piano quando la realtà differisce

L’implementazione farà emergere sorprese. Una libreria non supporta il comportamento assunto. Una migrazione richiede più tempo del previsto. Un caso limite mancava dai criteri di accettazione. Quando succede, aggiorna la specifica prima di continuare. Correggi i requisiti o il piano, ottieni una revisione rapida, poi riprendi l’implementazione contro l’artefatto corretto. Il codice che diverge silenziosamente dalla specifica è come la deriva diventa permanente.

Fase 5 – Validare Contro la Specifica

La validazione è dove SDD guadagna il suo posto. Senza di essa, la specifica è un esercizio di pianificazione. Con essa, la specifica è un contratto contro cui puoi controllare il codice spedito.

Controlli automatizzati

Esegui la suite completa di test, lint e controlli di tipo su CI. Collega questi alla tua pipeline usando pattern dal GitHub Actions cheatsheet se hai bisogno di un punto di partenza pratico. I controlli automatizzati catturano le regressioni. Non catturano funzionalità errate costruite correttamente, ecco perché la revisione dei criteri di accettazione è ancora importante.

Criteri di accettazione e revisione manuale

Attraversa ciascun criterio di accettazione dalla specifica dei requisiti. Segna ciascuno come soddisfatto, fallito o rinviato con giustificazione. La revisione manuale cattura problemi UX, lacune di sicurezza e comportamenti errati che i test hanno mancato perché i test sono stati scritti per corrispondere a una specifica difettosa.

Diff Specifica-Codice

Il passo finale di validazione confronta l’implementazione contro il piano di design. I file che sono cambiati corrispondono ai file che il piano ha previsto? Le decisioni architetturali nel codice corrispondono alle decisioni registrate? File inaspettati nella diff sono un segnale – o il piano era incompleto o l’agente si è disperso. Entrambi meritano attenzione prima del merge. Mantenere Specifiche, Test e Codice In Sync nello Sviluppo AI trasforma questa revisione diff one-off in una tabella di tracciabilità ripetibile e un set di controlli CI, così la deriva è catturata su ogni PR piuttosto che solo quando qualcuno ricorda di guardare.

Dove si Inseriscono gli Agenti AI nel Flusso di Lavoro

Gli agenti AI sono acceleratori in ciascuna fase, non sostituti della revisione. Il pattern produttivo è bozza, revisione, raffinamento, poi procedere. Chiedi a un agente di bozzare la specifica dei requisiti da una descrizione del problema, poi modifica l’intento finché obiettivi, non-obiettivi e criteri di accettazione sono giusti. Chiedi a un agente di bozzare il piano di design dai requisiti approvati, poi revisiona le decisioni architetturali prima che esista qualsiasi codice. Chiedi a un agente di implementare una slice di compito alla volta, con te che approvi ciascuna diff prima che il prossimo compito inizi.

Gli agenti sono particolarmente utili nel produrre prime bozze e test boilerplate. Gli umani sono particolarmente utili nel catturare obiettivi errati, architettura non sicura e creep dell’ambito sottile. Il flusso di lavoro fallisce quando uno dei lati è saltato – quando gli agenti implementano senza specifiche, o quando gli umani scrivono specifiche senza mai validarle contro il codice.

Questo articolo sul flusso di lavoro rimane neutrale rispetto agli strumenti appositamente. Le guide di esecuzione specifiche per gli strumenti – setup dell’editor, comandi slash, configurazione dell’agente – appartengono al cluster Strumenti di Sviluppo AI. Il pilastro del processo vive qui sotto le pratiche di documentazione perché gli artefatti contano più del vendor.

Errori Comuni che Uccidono lo Spec-Driven Development

Specifiche enormi prima di qualsiasi validazione. Un documento di requisiti di trenta pagine scritto prima di un prototipo o spike è burocrazia waterfall, non SDD. Scrivi la specifica minima che rimuove l’ambiguità per la fase successiva, poi valida le assunzioni presto. Non ogni funzionalità ha bisogno del ciclo completo a cinque fasi – Spec-Driven Development vs Vibe Coding spiega quando una struttura più leggera è sufficiente.

Criteri di accettazione vaghi. Aggettivi come “veloce”, “pulito” e “user-friendly” non sono criteri di accettazione. Sostituiscili con comportamento misurabile. Se non puoi testarlo, non puoi implementarlo in modo affidabile – specialmente con un agente AI.

Non-obiettivi mancanti. Senza non-obiettivi, gli agenti espandono l’ambito di default. Aggiungono layer di caching, rifattorizzano moduli vicini e introducono dipendenze che non hai richiesto. I non-obiettivi sono come dire no in anticipo.

Nessun piano di test nella fase di design. I test scritti solo dopo l’implementazione tendono a confermare ciò che è stato costruito, non ciò che era inteso. Il piano dovrebbe nominare quali criteri di accettazione mappano a quali tipi di test prima che il primo file di produzione cambi.

Saltare la revisione ai limiti delle fasi. La specifica revisionata prima del piano. Il piano revisionato prima dei compiti. I compiti revisionati prima dell’implementazione. Ogni gate è economico. Correggere la deriva dopo un merge grande è costoso.

Permettere ai compiti generati di esplodere. Tratta un elenco di compiti generato da AI di cinquanta elementi come una prima bozza, non come un programma. Unisci elementi ridondanti, dividi quelli troppo grandi e elimina i compiti che non mappano a un requisito.

SDD funziona quando ogni fase riduce l’ambiguità. Fallisce quando crea burocrazia.

Modelli Riutilizzabili

Copia questi nel tuo repository e adattali. Memorizza le specifiche accanto alla branch della funzionalità, revisionale in pull request e mantienile in version control così agenti e umani leggono la stessa fonte.

Modello di requisiti

# Funzionalità -- [nome]

## Problema
## Utenti
## Obiettivi
## Non-obiettivi
## Criteri di accettazione
## Domande aperte

Modello di design

# Design -- [nome funzionalità]

## Riepilogo
## Moduli interessati
## Modifiche modello di dati
## Contratti API
## Migrazioni
## Sicurezza
## Osservabilità
## Strategia di test
## Rischi e mitigazioni

Modello elenco compiti

# Compiti -- [nome funzionalità]

## Compito 1 -- [titolo]
Dipende da:
File:
Soddisfa:
Valida:
Punto di controllo revisione:

## Compito 2 -- [titolo]
...

Checklist di validazione

# Validazione -- [nome funzionalità]

## Automatizzato
- [ ] Tutti i test passano
- [ ] Lint pulito
- [ ] Controllo tipo pulito

## Criteri di accettazione
- [ ] AC-1 --
- [ ] AC-2 --

## Specifica-Codice
- [ ] File cambiati corrispondono al piano
- [ ] Nessuna modifica architetturale non documentata
- [ ] Specifica aggiornata se l'implementazione è differita

Conclusione

Lo sviluppo guidato dalle specifiche non riguarda scrivere più documenti. Riguarda attraversare specificare, pianificare, compito, implementare e validare con un gate di revisione a ogni passo. Ciascuna fase dovrebbe lasciare l’attore successivo – umano o agente – con meno indovinelli rispetto alla fase precedente.

Inizia piccolo. Esegui il flusso di lavoro completo su una funzionalità di medie dimensioni. Mantieni gli artefatti in markdown nel repository. Aggiorna la specifica quando la realtà diverge. Valida prima del merge. Quando la catena funziona, ottieni meno deriva, diff revisionabili più piccoli e un registro duraturo dell’intento che sopravvive ai reset delle sessioni e ai passaggi di consegne del team.

Quando la catena diventa burocrazia, taglia l’ambito – non la revisione. Una specifica di due pagine che è stata validata batte una specifica di trenta pagine che nessuno ha letto.

Link Utili

• Documentazione GitHub Spec Kit – toolkit open-source che implementa un loop simile specifica-piano-compiti-implementa
• Martin Fowler sugli strumenti di Spec-Driven Development – analisi di Kiro, Spec Kit, e Tessl