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

Lo Spec-Driven Development funziona quando la specifica è un flusso di lavoro, non un documento da archiviare dopo il kickoff. L’obiettivo non è produrre un ampio documento di requisiti del prodotto.

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

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

Lo SDD è un Flusso di Lavoro, Non un Documento

La modalità di fallimento più comune nello spec-driven development è trattare la specifica come burocrazia. Un team scrive un lungo documento di requisiti, lo memorizza in un wiki e poi codifica basandosi sulla memoria e sui thread delle chat. La specifica esiste, ma non guida nulla. È teatro della documentazione, ed è peggio di non avere una specifica perché crea una falsa sicurezza.

Un flusso di lavoro SDD funzionante produce una catena di artefatti, ciascuno revisionato prima che inizi la fase successiva. I requisiti riducono l’ambiguità del prodotto. La progettazione riduce l’ambiguità tecnica. I compiti riducono l’ambiguità di esecuzione. L’implementazione produce codice rispetto a un target noto. La convalida dimostra che la catena ha tenuto. Quando una fase rivela un errore, si corregge l’artefatto e si riparte da quel punto – non dopo che tremila righe di deriva sono finite nella branch principale.

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 di revisione, non il brand degli strumenti.

Fase 1 – Specificare i Requisiti

La fase di specifica risponde a quale problema stai risolvendo e a cosa assomiglia il completamento. Evita deliberatamente il come costruirlo. Nel 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 enuncia il problema in linguaggio semplice. Nominare gli utenti coinvolti e la situazione che rende il problema doloroso. Una buona dichiarazione del problema permette a un revisore che non ha partecipato alla riunione di pianificazione di decidere se una soluzione proposta affronta realmente il problema.

Esempio per una funzionalità di limitazione della frequenza delle chiamate API:

I consumatori 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 esplicitamente non farai. 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 di essi corrisponda ad 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 presa. Le domande non chiare non sono un segno di fallimento. Sono la fase di specifica che fa il suo lavoro. Risolvile prima di scrivere il piano di progettazione, altrimenti pagherai l’ambiguità con il lavoro di reimplementazione.

Un modello minimo di requisiti:

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

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

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

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

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

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

Fase 2 – Pianificare la Progettazione

La fase di piano traduce l’intento in decisioni tecniche. Qui appartengono gli insiemi ordinati di Redis, insieme ai confini 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 delle decisioni, 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 confine di servizio, documenta il contratto su entrambi i lati. Gli 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 dei topic, schemi dei payload e semantiche di consegna. Includi i passaggi di migrazione e note sul rollback quando il modello di dati cambia.

Sicurezza, osservabilità e strategia di test

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

La strategia di test si collega ai criteri di accettazione. Identifica quali criteri necessitano di test unitari, quali necessitano di test di integrazione e quali necessitano di verifica manuale. Se usi i test unitari in Go o i 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 sarà distribuito con lacune che scoprirai in produzione.

Fase 3 – Decomporre i Compiti di Implementazione

La fase dei compiti decompone il piano in slice sufficientemente piccole da implementare, revisionare e convalidare in modo indipendente. Questo è ciò che rende lo sviluppo assistito da agente revisionabile. Invece di un enorme diff, ottieni una sequenza di modifiche focalizzate che ciascuna risale 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 esplicitamente le dipendenze. I compiti di migrazione vengono eseguiti prima del codice che legge il nuovo schema. Le modifiche alle librerie condivise vengono eseguite prima dei consumatori. Le modifiche al middleware di autenticazione vengono eseguite prima degli endpoint che dipendono dal nuovo comportamento.

File, convalida e punti di controllo per la revisione

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

Un’entry minima per un compito:

### Compito 3 -- Aggiungi middleware di limitazione della frequenza

**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)
**Convalida:** `go test ./middleware/...` passa; curl oltre il limite restituisce 429 con Retry-After
**Punto di controllo revisione:** Conferma che il middleware viene eseguito dopo l'autenticazione, prima del gestore

Attenzione alle esplosioni di compiti generati. Gli agenti AI possono produrre piani di cinquanta compiti in secondi. La maggior parte di quei compiti sarà ridondante o troppo granulare per essere revisionata in modo efficiente. Un elenco di compiti utile per una funzionalità di media dimensione spesso ha da cinque a quindici voci, 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 convalida passa. Il reset del contesto tra i compiti è una caratteristica, non un bug. Impediscono alle assunzioni precedenti di contaminare il lavoro successivo e mantengono i diff revisionabili.

Applicare i vincoli dallo stack delle specifiche

L’agente implementativo dovrebbe leggere la specifica dei requisiti, il piano di progettazione, 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 refattorizzare moduli non correlati, non modificare le firme delle API pubbliche al di fuori di questa funzionalità, non introdurre nuove dipendenze senza aggiornare il piano.

Aggiornare il piano quando la realtà differisce

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

Fase 5 – Convalidare Rispetto alla Specifica

La convalida è dove lo SDD si guadagna il suo valore. Senza di essa, la specifica è un esercizio di pianificazione. Con essa, la specifica è un contratto che puoi controllare rispetto al codice distribuito.

Controlli automatizzati

Esegui la suite completa di test, lint e controlli di tipo su CI. Collegali alla tua pipeline usando pattern dal trucco per GitHub Actions se hai bisogno di un punto di partenza pratico. I controlli automatizzati catturano le regressioni. Non catturano funzionalità errate costruite correttamente, ed è per questo che la revisione dei criteri di accettazione rimane importante.

Criteri di accettazione e revisione manuale

Passa attraverso 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 dalla specifica al codice

Il passo finale di convalida confronta l’implementazione con il piano di progettazione. I file che sono cambiati corrispondono ai file previsti dal piano? Le decisioni architetturali nel codice corrispondono alle decisioni registrate? File inaspettati nel diff sono un segnale – o il piano era incompleto o l’agente si è perso. Entrambi meritano attenzione prima del merge.

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 procedi. Chiedi a un agente di redigere la bozza della specifica dei requisiti da una descrizione del problema, poi modifica l’intento finché obiettivi, non-obiettivi e criteri di accettazione sono corretti. Chiedi a un agente di redigere la bozza del piano di progettazione dai requisiti approvati, poi revisiona le decisioni architetturali prima che esista alcun codice. Chiedi a un agente di implementare una slice di compito alla volta, con te che approvi ciascun diff prima che inizi il compito successivo.

Gli agenti sono particolarmente utili nella produzione di bozze e test boilerplate. Gli umani sono particolarmente utili nel catturare obiettivi errati, architetture insicure e scope creep sottili. Il flusso di lavoro fallisce quando uno dei lati viene saltato – quando gli agenti implementano senza specifiche, o quando gli umani scrivono specifiche senza mai convalidarle rispetto al codice.

Questo articolo sul flusso di lavoro rimane neutrale rispetto agli strumenti appositamente. Le guide di esecuzione specifiche per gli strumenti – configurazione editor, comandi slash, configurazione agente – appartengono al cluster Strumenti per Sviluppatori 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 convalida. Un documento di requisiti di trenta pagine scritto prima di un prototipo o uno spike è burocrazia waterfall, non SDD. Scrivi la specifica minima che rimuove l’ambiguità per la fase successiva, poi convalida 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 comportamenti misurabili. 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, refattorizzano moduli vicini e introducono dipendenze che non hai richiesto. I non-obiettivi sono il modo per dire no in anticipo.

Nessun piano di test nella fase di progettazione. 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 confini di fase. 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 dall’AI di cinquanta elementi come una prima bozza, non come un programma. Unisci elementi ridondanti, dividi quelli sovradimensionati e elimina i compiti che non mappano a un requisito.

Lo SDD funziona quando ciascuna 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 nei pull request e mantienile nel controllo di versione in modo che agenti e umani leggano la stessa fonte.

Modello di requisiti

# Funzionalità -- [nome]

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

Modello di progettazione

# Progettazione -- [nome funzionalità]

## Riassunto
## Moduli interessati
## Cambiamenti 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:
Convalida:
Punto di controllo revisione:

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

Checklist di convalida

# Convalida -- [nome funzionalità]

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

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

## Dalla specifica al codice
- [ ] I file cambiati corrispondono al piano
- [ ] Nessun cambiamento architetturale non documentato
- [ ] Specifica aggiornata se l'implementazione è differita

Conclusione

Lo Spec-driven development non riguarda scrivere più documenti. Riguarda attraversare specificare, pianificare, compito, implementare e convalidare con un gate di revisione a ciascun passo. Ciascuna fase dovrebbe lasciare l’attore successivo – umano o agente – con meno lavoro di indovinare rispetto alla fase precedente.

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

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

Link Utili

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