Workflow di sviluppo basato su specifiche: dalle esigenze 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 dei requisiti di prodotto.

L’obiettivo è attraversare una sequenza di artefatti verificabili, ciascuno dei quali riduce l’ambiguità prima che chiunque — umano o agente AI — modifichi il codice di produzione.

Se non sai cosa sia lo SDD a livello concettuale, inizia con Cos’è lo Spec-Driven Development? per le definizioni, i confronti con TDD e BDD e il caso a favore del trattamento della specifica come fonte di verità. Questo articolo nel cluster documentale di App Architecture è la guida operativa. Illustra 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

La modalità di fallimento più comune nello spec-driven development è trattare la specifica come burocrazia. Un team scrive un lungo documento dei requisiti, lo archivia in un wiki e poi scrive il codice basandosi sulla memoria e sui thread di chat. La specifica esiste, ma non guida nulla. Si tratta di teatro documentale, ed è peggio di non avere una specifica perché crea una falsa sensazione di sicurezza.

Un flusso di lavoro SDD funzionante produce una catena di artefatti, ciascuno verificato prima che inizi la fase successiva. I requisiti riducono l’ambiguità del prodotto. La progettazione riduce l’ambiguità tecnica. Le attività riducono l’ambiguità esecutiva. L’implementazione produce codice rispetto a un obiettivo noto. La validazione dimostra che la catena ha retto. Quando una fase rivela un errore, si corregge l’artefatto e si riparte da quel punto — non dopo che tremila righe di deriva sono state integrate nel ramo principale.

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

Fase 1 – Specificare i requisiti

La fase di specificazione risponde a quale problema stai risolvendo e a cosa significhi “completato”. Evita deliberatamente il modo in cui costruirci. Nel momento in cui la tua specifica dei requisiti dice “usa le sorted set di Redis”, hai smesso di specificare e hai iniziato a progettare nel documento sbagliato. Mantieni l’implementazione fuori dai requisiti. Mettila nel piano.

Dichiarazione del problema e utenti

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

Esempio per una funzionalità di rate-limiting per API:

I consumatori di API sul piano gratuito possono inviare richieste illimitate, causando picchi di costo e impatti da “vicino rumoroso” sui tenant a pagamento. Gli operatori della piattaforma necessitano 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 lavori adiacenti allettanti che deciderai esplicitamente di non svolgere. Insieme, delimitano la creatività dell’agente, il che è essenziale quando gli strumenti AI altrimenti “utilmente” espandono lo scope.

I criteri di accettazione devono essere abbastanza precisi da poter essere mappati ciascuno su almeno un test. “L’endpoint è sicuro” non è un criterio di accettazione. “Le richieste non autenticate ricevono HTTP 401” lo è. Se non riesci a scrivere un criterio concreto, il requisito è ancora troppo vago per essere implementato.

Domande aperte

Elenca ogni decisione che non è ancora stata risolta. Le domande non chiare non sono un segno di fallimento. Sono la fase di specificazione che svolge il suo compito. Risolviliele prima di scrivere il piano di progettazione, altrimenti pagherai l’ambiguità con il lavoro di rifacimento dell’implementazione.

Un modello minimale dei requisiti:

## Problem
[One paragraph: who hurts, why, and what triggers the pain.]

## Users
- [Primary user role]
- [Secondary user role]

## Goals
1. [Measurable outcome]
2. [Measurable outcome]

## Non-goals
- [Explicitly out of scope]
- [Explicitly out of scope]

## Acceptance criteria
- [ ] [Verifiable behavior]
- [ ] [Verifiable behavior]

## Open questions
- [ ] [Question that blocks planning]

Fase 2 – Pianificare la progettazione

La fase di pianificazione traduce l’intento in decisioni tecniche. È qui che appartengono le sorted set 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 progetto — scelte dello stack, decision records e convenzioni conservate in file come AGENTS.md o una costituzione del progetto.

Architettura e moduli interessati

Indica i moduli, i servizi o i pacchetti che verranno modificati e riassumi il modello di integrazione. Se la funzionalità attraversa un confine 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 dati, contratti API e migrazioni

Documenta le modifiche dello schema, le nuove tabelle o campi, i requisiti di indicizzazione e le regole di compatibilità retroattiva. 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 semantica di consegna. Includi i passaggi di migrazione e le note di rollback quando il modello dati cambia.

Sicurezza, osservabilità e strategia di test

I vincoli di sicurezza appartengono al piano, non come ripensamenti nella revisione del codice. Annota 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 tracce necessari per confermare che la funzionalità funzioni in produzione.

La strategia di test torna indietro 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 il test unitario in Go o il test unitario in Python, indica i pacchetti e i file di test che prevedi di aggiungere. Un piano senza una strategia di test è un piano che verrà rilasciato con lacune che scoprirai in produzione.

Fase 3 – Scomporre le attività di implementazione

La fase delle attività scompone il piano in fette abbastanza piccole da poter essere implementate, verificate e validate indipendentemente. È ciò che rende lo sviluppo assistito da agenti verificabile. Invece di un enorme diff, ottieni una sequenza di modifiche focalizzate che ciascuna torna indietro a un requisito nominato.

Dimensionamento delle attività e dipendenze

Una buona attività tocca un insieme limitato di file, si completa in una sessione dell’agente e termina con un passaggio di verifica. Le attività dovrebbero dichiarare esplicitamente le dipendenze. Le attività di migrazione vengono eseguite 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 di revisione

Ogni attività dovrebbe elencare i file che probabilmente verranno modificati, 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 attività termina in un punto di controllo di revisione umana. Il revisore conferma che il diff corrisponde alla descrizione dell’attività prima che inizi l’attività successiva.

Un’attività minimale:

### Task 3 -- Add rate-limit middleware

**Depends on:** Task 1 (schema), Task 2 (repository)
**Files:** middleware/ratelimit.go, middleware/ratelimit_test.go, server.go
**Satisfies:** AC-2 (429 over limit), AC-3 (limit headers in response)
**Validate:** `go test ./middleware/...` passes; curl over limit returns 429 with Retry-After
**Review checkpoint:** Confirm middleware runs after auth, before handler

Attenzione alle esplosioni di attività generate. Gli agenti AI possono produrre piani di cinquanta attività in pochi secondi. La maggior parte di quelle attività sarà ridondante o troppo granulare per essere verificata efficientemente. Un elenco di attività utile per una funzionalità media ha spesso da cinque a quindici elementi, non cinquanta.

Fase 4 – Implementare un’attività alla volta

L’implementazione è deliberatamente stretta. Scegli un’attività, fornisci all’agente solo il contesto di cui ha bisogno per quell’attività e fermati quando la validazione passa. Il reset del contesto tra le attività è una caratteristica, non un bug. Impedisce alle assunzioni precedenti di inquinare il lavoro successivo e mantiene i diff verificabili.

Applicare i vincoli dalla pila delle specifiche

L’agente di implementazione dovrebbe leggere la specifica dei requisiti, il piano di progettazione, la descrizione dell’attività 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 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 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 ciò accade, aggiorna la specifica prima di continuare. Correggi i requisiti o il piano, ottieni una rapida revisione, poi riprendi l’implementazione rispetto all’artefatto corretto. Il codice che diverge silenziosamente dalla specifica è il modo in cui la deriva diventa permanente.

Fase 5 – Validare rispetto alla specifica

La validazione è dove lo SDD si guadagna il suo prezzo. Senza di essa, la specifica è un esercizio di pianificazione. Con essa, la specifica è un contratto contro cui puoi verificare il codice rilasciato.

Controlli automatizzati

Esegui la suite di test completa, lint e controlli di tipo in CI. Collega questi alla tua pipeline usando i modelli dal GitHub Actions cheatsheet se hai bisogno di un punto di partenza pratico. I controlli automatizzati catturano le regressioni. Non catturano funzionalità sbagliate costruite correttamente, ed è per questo che la revisione dei criteri di accettazione conta ancora.

Criteri di accettazione e revisione manuale

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

Diff da specifica a codice

Il passaggio finale di validazione confronta l’implementazione con il piano di progettazione. I file modificati corrispondevano ai file previsti dal piano? Le decisioni architettoniche nel codice corrispondevano alle decisioni registrate? I file inaspettati nel diff sono un segnale — o il piano era incompleto o l’agente si è perso. Entrambi meritano attenzione prima della merge. Keeping Specs, Tests, And Code In Sync In AI Development trasforma questa revisione di diff una tantum in una tabella di tracciabilità ripetibile e un insieme di controlli CI, in modo che la deriva venga catturata in ogni PR e non solo quando qualcuno ricorda di guardare.

Dove si inseriscono gli agenti AI nel flusso di lavoro

Gli agenti AI sono acceleratori in ogni fase, non sostituti della revisione. Il modello 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 non sono corretti. Chiedi a un agente di bozzare il piano di progettazione dai requisiti approvati, poi rivedi le decisioni architettoniche prima che esista codice. Chiedi a un agente di implementare una fetta di attività alla volta, con te che approvi ogni diff prima che inizi l’attività successiva.

Gli agenti sono particolarmente utili nella produzione di prime bozze e test boilerplate. Gli umani sono particolarmente utili nel catturare obiettivi errati, architetture non sicure e sottili espansioni dello scope. Il flusso di lavoro fallisce quando uno dei due lati viene saltato — quando gli agenti implementano senza specifiche, o quando gli umani scrivono specifiche senza mai validarle rispetto al codice.

Questo articolo sul flusso di lavoro rimane deliberatamente neutrale rispetto agli strumenti. Le guide di esecuzione specifiche degli strumenti — configurazione dell’editor, comandi slash, configurazione dell’agente — appartengono al cluster AI Developer Tools. Il pilastro dei processi vive qui sotto le pratiche documentali perché gli artefatti contano più del vendor.

Errori comuni che uccidono lo Spec-Driven Development

Specifiche enormi prima di qualsiasi validazione. Un documento dei 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 valida le assunzioni presto. Non ogni funzionalità ha bisogno del ciclo completo di 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 lo scope di default. Aggiungono layer di caching, rifattorizzano moduli vicini e introducono dipendenze che non hai richiesto. I non-obiettivi sono il modo per dire di 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 indicare quali criteri di accettazione si mappano su quali tipi di test prima che il primo file di produzione venga modificato.

Saltare la revisione ai confini delle fasi. La specifica verificata prima del piano. Il piano verificato prima delle attività. Le attività verificate prima dell’implementazione. Ogni gate è economico. Correggere la deriva dopo una merge grande è costoso.

Lasciare esplodere le attività generate. Tratta un elenco di attività generato da AI di cinquanta elementi come una prima bozza, non come un programma. Unisci gli elementi ridondanti, dividi quelli sovradimensionati e elimina le attività che non si mappano su un requisito.

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

Modelli riutilizzabili

Copia questi nel tuo repository e adattali. Conserva le specifiche accanto alla branch della funzionalità, rilevale nelle pull request e tienile sotto controllo di versione in modo che agenti e umani leggano la stessa fonte.

Modello dei requisiti

# Feature -- [name]

## Problem
## Users
## Goals
## Non-goals
## Acceptance criteria
## Open questions

Modello di progettazione

# Design -- [feature name]

## Summary
## Affected modules
## Data model changes
## API contracts
## Migrations
## Security
## Observability
## Test strategy
## Risks and mitigations

Modello dell’elenco delle attività

# Tasks -- [feature name]

## Task 1 -- [title]
Depends on:
Files:
Satisfies:
Validate:
Review checkpoint:

## Task 2 -- [title]
...

Checklist di validazione

# Validation -- [feature name]

## Automated
- [ ] All tests pass
- [ ] Lint clean
- [ ] Type check clean

## Acceptance criteria
- [ ] AC-1 --
- [ ] AC-2 --

## Spec-to-code
- [ ] Changed files match plan
- [ ] No undocumented architectural changes
- [ ] Spec updated if implementation differed

Conclusione

Lo spec-driven development non riguarda la scrittura di più documenti. Riguarda il passaggio attraverso specificare, pianificare, attività, implementare e validare con un gate di revisione a ogni passo. Ogni fase dovrebbe lasciare all’attore successivo — umano o agente — meno congetture rispetto alla fase precedente.

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

Quando la catena diventa burocrazia, taglia lo scope — non la revisione. Una specifica di due pagine che è stata validata batte una specifica di trenta pagine che nessuno ha letto.

Link utili

• Documentazione di GitHub Spec Kit – toolkit open-source che implementa un loop simile di specifica-piano-attività-implementazione
• Superpowers Quickstart: Install, Workflow, and Tryout – un pacchetto di competenze installabile che automatizza questo stesso loop di cinque fasi con gate di revisione obbligatori
• Martin Fowler sugli strumenti di Spec-Driven Development – analisi di Kiro, Spec Kit e Tessl