Workflow di sviluppo basato su specifiche: dalle esigenze al codice

Lo sviluppo basato su specifiche funziona quando la specifica è un flusso di lavoro, non un documento da archiviare dopo l’avvio. L’obiettivo non è produrre un ampio documento dei requisiti di prodotto.

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

Se non sai cos’è lo SDD (Spec-Driven Development) a livello concettuale, parti da Cos’è lo Spec-Driven Development? per le definizioni, i confronti con TDD e BDD e il motivo per cui la specifica dovrebbe essere trattata come fonte di verità. Questo articolo nel cluster di documentazione di Architettura delle Applicazioni è la guida operativa. Descrive 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 sviluppo basato su specifiche è trattare la specifica come mera burocrazia. Un team scrive un lungo documento dei requisiti, lo archivia in una wiki e poi scrive codice sulla base di ricordi e thread di chat. La specifica esiste, ma non guida nulla. Si tratta di teatro della documentazione ed è peggio di non avere una specifica, perché crea una falsa fiducia.

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. Il design 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. Se una qualsiasi 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 è indipendente dagli strumenti. Puoi eseguirlo con file markdown in Git, con GitHub Spec Kit, con un CLI leggero e centrato sui cambiamenti come OpenSpec, con i piani di Cursor, con un pacchetto di competenze obbligatorio come Superpowers, o con un semplice editor di testo e un revisore disciplinato. Ciò che conta è la sequenza e i punti di controllo, non il marchio dello strumento.

Fase 1 – Specificare i requisiti

La fase di specifica risponde a quale problema stai risolvendo e a cosa significa “finito”. Evita deliberatamente come costruirlo. Nel momento in cui la tua specifica dei requisiti dice “usa set ordinati 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. Nomi degli utenti interessati e della 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 realmente il problema.

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

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

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

Domande aperte

Elenca ogni decisione non ancora risolta. 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 design, o pagherai l’ambiguità con un rifacimento dell’implementazione.

Un modello minimo 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 il design

La fase di piano traduce l’intento in decisioni tecniche. È qui che appartengono i set ordinati 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 deriva dalla specifica dei requisiti e dai vincoli esistenti del progetto – scelte di stack, decision records e convenzioni memorizzate in file come AGENTS.md o una costituzione del progetto.

Architettura e moduli interessati

Noma dei moduli, servizi o pacchetti che verranno modificati e riassumi il pattern 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 i contratti nel piano previene endpoint inventati e forme di risposta errate.

Modello dati, contratti API e migrazioni

Documenta le modifiche dello schema, nuove tabelle o campi, requisiti di indicizzazione e 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 note sul 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 della 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 torna indietro ai criteri di accettazione. Identifica quali criteri necessitano di test unitari, quali di test di integrazione e quali 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à rilasciato con lacune che scoprirai in produzione.

Fase 3 – Decomporre le attività di implementazione

La fase di attività scompone il piano in fette abbastanza piccole da essere implementate, revisionate e validate indipendentemente. Questo è ciò che rende lo sviluppo assistito da agenti revisionabile. Invece di un enorme diff, ottieni una sequenza di modifiche focalizzate che ciascuna si rimappa a un requisito nominato.

Dimensionamento delle attività e dipendenze

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

Ciascuna attività dovrebbe elencare i file probabili da modificare, 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 umano per la revisione. Il revisore conferma che il diff corrisponde alla descrizione dell’attività prima che inizi l’attività successiva.

Una voce minima per un’attività:

### 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 revisionata 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 funzionalità, non un bug. Prevengono che le assunzioni precedenti inquinino il lavoro successivo e mantengono i diff revisionabili.

Applicare i vincoli dalla pila di specifiche

L’agente che implementa dovrebbe leggere la specifica dei requisiti, il piano di design, la descrizione dell’attività corrente e i vincoli a livello di progetto. I vincoli sono la sezione a più alto rendimento 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 al di fuori di questa funzionalità, non introdurre nuove dipendenze senza aggiornare il piano.

Aggiornare il piano quando la realtà differisce

L’implementazione rivelerà 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 è come la deriva diventa permanente.

Fase 5 – Validare rispetto alla specifica

La validazione è dove lo SDD si guadagna il suo valore. 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 l’intera suite di test, lint e controlli dei tipi su CI. Integra questi nella tua pipeline usando pattern della Scheda rapida GitHub Actions se hai bisogno di un punto di partenza pratico. I controlli automatizzati catturano le regressioni. Non catturano funzionalità sbagliate costruite correttamente, motivo per cui la revisione dei criteri di accettazione conta ancora.

Criteri di accettazione e revisione manuale

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

Diff da specifica a codice

Il passo finale di validazione confronta l’implementazione con il piano di design. 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 è disperso. Entrambi meritano attenzione prima della merge. Mantenere specifiche, test e codice in sincronia nello sviluppo AI trasforma questa revisione di diff una tantum in una tabella di tracciabilità ripetibile e in un insieme di controlli CI, in modo che la deriva venga catturata in 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 abbozzare 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 abbozzare il piano di design dai requisiti approvati, poi revisiona le decisioni architetturali prima che esista qualsiasi codice. Chiedi a un agente di implementare una fetta di attività alla volta, con l’approvazione di ogni diff da parte tua prima che inizi l’attività successiva.

Gli agenti sono particolarmente utili nel produrre prime bozze e test boilerplate. Gli umani sono particolarmente utili nel catturare obiettivi sbagliati, architetture non sicure e sottili scope creep. Il flusso di lavoro fallisce se viene saltata una delle due parti – quando gli agenti implementano senza specifiche, o quando gli umani scrivono specifiche senza mai validarle rispetto al codice.

Questo articolo sul flusso di lavoro resta deliberatamente indipendente dagli strumenti. Guide di esecuzione specifiche per strumento – configurazione editor, comandi slash, configurazione agenti – appartengono al cluster di 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

Enormi specifiche 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 loop 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. Sostituirli 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 in cui dici 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 si mappano a quali tipi di test prima che il primo file di produzione venga modificato.

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

Lasciare che le attività generate esplode. Tratta un elenco di attività AI-generate di cinquanta elementi come una prima bozza, non come una pianificazione. Unisci gli elementi ridondanti, dividi quelli eccessivamente grandi ed elimina le attività che non si mappano a un requisito.

Eliminare le indagini rigettate invece di registrare il perché. Quando la revisione della fase 2 conclude che una direzione non vale la pena di essere costruita, il riflesso è eliminare la specifica e andare avanti. Ciò cancella il ragionamento e la stessa idea riappare il trimestre successivo, indagata da zero da chiunque – umano o agente – capiti di colpirla di nuovo. Registrare il rifiuto con la stessa rigore di una decisione accettata è economico per confronto; Proposte Rigettate in OpenSpec: Una Convenzione di Memoria Decisionale attraversa un modo concreto per farlo, inclusa l’istruzione che fa a un agente cercare decisioni precedenti prima di riproporre.

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

Modelli riutilizzabili

Copia questi nel tuo repository e adattali. Archivia le specifiche accanto alla branch della funzionalità, revionale nei 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 del design

# Design -- [feature name]

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

Modello della lista 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 sviluppo basato su specifiche non riguarda il scrivere più documenti. Riguarda il passare attraverso specificare, pianificare, taskare, implementare e validare con un gate di revisione a ogni passo. Ogni fase dovrebbe lasciare l’attore successivo – umano o agente – con meno congetture della fase precedente.

Inizia in piccolo. Esegui il flusso 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 più piccole e revisionabili, e un registro duraturo dell’intento che sopravvive ai reset di sessione e alle 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 GitHub Spec Kit – toolkit open-source che implementa un loop simile specify-plan-tasks-implement
• OpenSpec Quickstart: Installazione, Flusso di lavoro e Errori comuni – un CLI leggero e centrato sui cambiamenti che esegue questo stesso loop come explore-propose-apply-archive
• Proposte Rigettate in OpenSpec: Una Convenzione di Memoria Decisionale – registrazione di una decisione di fase 2 rigettata in modo che non venga ri-indagata da zero
• Superpowers Quickstart: Installazione, Flusso di lavoro e Prove – 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