Ogni sviluppatore conosce quella sensazione: hai scritto centinaia di righe di codice, funziona, ma nessuno ricorda più perché doveva funzionare così. La documentazione è sparsa, i requisiti sono in una slide dimenticata, e il test coverage racconta solo metà della storia.
Lo Spec Driven Development nasce per risolvere questo problema. Non è l'ennesimo buzzword: è un cambio di prospettiva che diventa fondamentale quando lavori con agenti AI.
Cos'è lo Spec Driven Development
In parole povere: scrivi prima una specifica strutturata e testabile che descrive cosa deve fare il software, poi generi il codice — manualmente o tramite AI.
La specifica diventa la fonte di verità. Non un documento Word che nessuno legge, ma un artefatto vivo che guida sviluppatori, tester e agenti AI.
Il flusso tradizionale è:
- Scrivi codice
- (Forse) scrivi test
- (Forse) documenti
Con SDD diventa:
- Definisci la specifica
- Validi la specifica con il team
- Generi codice e test dalla specifica
- La specifica resta aggiornata
Perché ha senso nel 2026
Con tool come Claude Code, GitHub Copilot o Gemini CLI, le specifiche non sono più solo documentazione passiva. Diventano input eseguibili.
Quando dai a un agente AI una specifica ben scritta:
- Il codice generato è più aderente ai requisiti
- I test nascono automaticamente dai criteri di accettazione
- Le iterazioni sono più veloci (cambi la spec, rigeneri)
- Il team è allineato su cosa stiamo costruendo
Ho notato che la qualità dell'output di un agente AI dipende direttamente dalla qualità dell'input. Una specifica vaga produce codice vago. Una specifica precisa produce codice che funziona al primo colpo.
Anatomia di una specifica SDD
Una buona specifica non è un muro di testo. È strutturata, testabile, e risponde a domande precise.
Sezioni tipiche
| Sezione | Contenuto | |---------|-----------| | Obiettivo | Cosa risolve questa feature? Perché esiste? | | Comportamenti | Cosa deve fare il sistema in scenari specifici | | Vincoli | Limiti tecnici, di sicurezza, di performance | | Criteri di accettazione | Condizioni verificabili per dire "è fatto" | | Non-goal | Cosa NON fa questa feature (importante!) |
Esempio pratico
## Feature: Reset Password via Email
### Obiettivo
Permettere agli utenti di recuperare l'accesso quando dimenticano la password.
### Comportamenti
- L'utente inserisce la propria email
- Il sistema invia un link di reset valido 1 ora
- Il link porta a un form per impostare nuova password
- Password minimo 8 caratteri, almeno 1 numero
### Vincoli
- Rate limit: max 3 richieste per email ogni 15 minuti
- Il link deve essere invalidato dopo l'uso
- Loggare tutti i tentativi di reset
### Criteri di accettazione
- [ ] Email valida riceve link entro 30 secondi
- [ ] Link scaduto mostra errore chiaro
- [ ] Password debole viene rifiutata con feedback
- [ ] Utente può fare login con nuova password
### Non-goal
- Reset via SMS (fase successiva)
- Reset per admin (workflow separato)
Questa specifica è comprensibile da un PM, testabile da un QA, e eseguibile da un agente AI.
Workflow SDD in pratica
Ecco come applico SDD nei miei progetti:
1. Discovery
Raccolgo requisiti con stakeholder. Chiedo sempre: "Come faccio a sapere che è fatto bene?" La risposta diventa un criterio di accettazione.
2. Specifica
Scrivo la spec in markdown, strutturata come sopra. La rivedo con il team. Ogni ambiguità che emerge qui è un bug evitato dopo.
3. Piano tecnico
Dalla spec derivo decisioni architetturali:
- Quali endpoint servono?
- Che modelli dati?
- Quali servizi esterni?
4. Task breakdown
Spezzo il piano in task atomici. Ogni task ha criteri di done chiari, derivati dalla specifica madre.
5. Implementazione
Qui entra l'AI. Passo la specifica a Claude Code o simili, e il codice generato è già allineato ai requisiti. I test li scrivo partendo dai criteri di accettazione.
6. Validazione
Verifico che l'output rispetti la specifica. Se qualcosa non torna, aggiorno la spec e rigenero.
SDD vs TDD vs BDD
Facciamo chiarezza sulle differenze:
| Aspetto | TDD | BDD | SDD | |---------|-----|-----|-----| | Focus | Test prima del codice | Comportamento in linguaggio naturale | Specifica completa prima di tutto | | Artefatto | Test unitari | Scenari Gherkin | Documento di specifica | | Chi lo scrive | Developer | Dev + QA + Business | Team cross-funzionale | | Quando | Durante lo sviluppo | Prima dello sviluppo | Prima di tutto | | AI-friendly | Medio | Medio | Alto |
SDD non sostituisce TDD o BDD: li comprende. I test TDD possono essere generati dalla specifica. Gli scenari BDD possono essere estratti dai comportamenti.
Quando NON usare SDD
Essere onesti: SDD ha un overhead. Non ha senso per:
- Bug fix semplici (il bug È la specifica)
- Spike esplorativi (stai ancora capendo cosa costruire)
- Prototipi usa-e-getta (la velocità conta più della precisione)
SDD brilla quando:
- Costruisci feature complesse con più stakeholder
- Usi agenti AI per generare codice
- Lavori in team e l'allineamento è critico
- Il software deve durare e evolvere
Tool che uso per SDD
Non servono tool esotici. Uso:
- Markdown per le specifiche (versionabile, leggibile, portabile)
- GitHub Issues/Projects per tracciare spec → task
- Claude Code per generare codice dalla specifica
- Test framework standard (pytest, vitest) per i criteri di accettazione
La vera "tecnologia" è la disciplina di scrivere specifiche prima di toccare il codice.
Conclusione
Lo Spec Driven Development non è magia. È la disciplina di pensare prima di scrivere. Con l'AI che genera sempre più codice, chi controlla la specifica controlla il progetto.
Il codice è un artefatto. La specifica è l'intenzione. E l'intenzione, se scritta bene, sopravvive a qualsiasi refactoring.
Vuoi approfondire?
Se stai integrando agenti AI nel tuo workflow o vuoi strutturare meglio i requisiti dei tuoi progetti, posso aiutarti.
Contattami per una consulenza su AI, automazione o architetture software.