Spec driven development con AI

Cosa significa spec driven development con AI

Spec driven development significa trattare la specifica come artefatto principale del lavoro software. Nel contesto degli agenti AI, la richiesta non passa subito a una patch: viene trasformata prima in requisiti, design tecnico, task e criteri di verifica. Il codice arriva dopo, come esecuzione di un contratto più esplicito.

• Il punto non è scrivere più documentazione, ma togliere ambiguità prima che l'agente tocchi il codice.
• Una buona specifica dice cosa costruire, cosa non costruire, quali casi limite coprire e come verificare il risultato.
• Il valore cresce quando più persone o più agenti devono condividere la stessa intenzione.
• Il valore cala quando il task è piccolo, locale e già verificabile con un test semplice.

Quando basta un prompt libero

Il prompt libero resta la scelta giusta quando il costo di strutturare supera il rischio del task. Se devi correggere un errore evidente, spiegare una funzione, aggiornare copy, sistemare uno stile locale o aggiungere un test piccolo, puoi dare contesto mirato e chiedere una patch. In questi casi una specifica formale può diventare rumore.

• Il risultato atteso è chiaro in una frase.
• I file coinvolti sono pochi e facili da nominare.
• Il fallimento è economico: puoi leggere il diff e correggere subito.
• La verifica è immediata: un test, una build, uno screenshot o una query.

Quando passare a SDD

Passa a SDD quando la domanda vera non è come scrivere codice, ma quale comportamento deve avere il sistema. Feature con stati, permessi, pagamenti, onboarding, ruoli utente, migrazioni o design system hanno troppe decisioni implicite. Se lasci quelle decisioni nel prompt, l'agente le riempie con assunzioni.

• Ci sono più stakeholder: product, design, engineering, compliance o cliente.
• Ci sono edge case che il caso felice non copre.
• La feature tocca più moduli o più repository.
• Serve dividere il lavoro in task indipendenti per agenti o persone diverse.
• Vuoi poter rileggere la decisione tra una settimana, non solo nel transcript della chat.

Spec Kit, GSD e altri pattern pratici

Il riferimento più pratico da cui partire è GitHub Spec Kit, perché offre template e comandi portabili per passare da intenzione a specifica, piano, task e implementazione. GSD, Get Shit Done, è interessante come pattern più pragmatico: meno specifica formale, più isolamento del lavoro, review e consegna. Kiro può essere utile se vuoi un IDE che guidi requisiti, design e task nello stesso ambiente, soprattutto su feature che devono passare dal prototipo a un lavoro più tracciabile.

• Spec Kit parte da una costituzione di progetto, poi usa passaggi come specify, plan, tasks e implement.
• GSD è da valutare quando vuoi un approccio operativo centrato su worktree, esecuzione rapida e review umana.
• Kiro genera requirements.md, design.md e tasks.md, ma oggi è più un buon esempio di prodotto spec-first che una scelta universale.
• I requisiti in stile EARS aiutano a scrivere condizioni testabili: quando succede X, il sistema deve fare Y.
• BMAD, OpenSpec e altri framework meritano attenzione, ma vanno scelti per processo e portabilità, non per hype.
• Questi pattern non sostituiscono Claude Code, Codex o Cursor: danno loro un contratto migliore da eseguire.

Starter kit pratico

Per iniziare non serve adottare subito un framework completo. Parti da un pattern minimo e aggiungi strumenti solo quando il processo si ripete. La combinazione più pratica è: template di requisiti, formato testabile per i criteri di accettazione, task piccoli e una skill o istruzione riusabile per far ripetere il flusso all'agente.

• Pattern minimo: idea, requisiti, criteri di accettazione, design breve, task atomici, verifica.
• Formato requisiti: usa EARS quando vuoi condizioni testabili, per esempio WHEN succede X, il sistema SHALL fare Y.
• Formato scenari: usa Given, When, Then quando vuoi esempi vicini a test e comportamento utente.
• Framework guidato: prova Spec Kit se vuoi comandi e template portabili tra agenti di coding.
• Delivery pragmatico: valuta GSD se il collo di bottiglia è far lavorare agenti in isolamento e rivedere output rapidamente.
• IDE guidato: guarda Kiro Specs come esempio di requisiti, design e task dentro un ambiente integrato.
• Workflow ripetuto: trasformalo in una skill, in un template di issue o in una sezione di AGENTS.md.

Il compromesso nascosto

La specifica non è garanzia di qualità. Può essere incompleta, vecchia, troppo lunga o scritta con il tono giusto ma senza vincoli reali. Uno dei rischi principali è il drift: il documento dice una cosa, il codice evolve in un'altra direzione, e l'agente continua a trattare il documento come vero.

• Aggiorna la specifica quando cambia una decisione, non solo quando inizia il task.
• Tieni i task piccoli: se una voce richiede molti file e molte decisioni, va divisa.
• Non usare SDD per evitare review umana: usalo per rendere la review più semplice.
• Chiedi all'agente di citare file, test e vincoli che ha usato, così puoi vedere se ha lavorato su prove o su memoria.

Workflow consigliato

Per un team piccolo, il flusso migliore è leggero: una pagina di requisiti, un piano tecnico breve, una lista di task atomici e una verifica finale. Non serve imitare un processo enterprise. Serve dare all'agente abbastanza struttura per non inventare prodotto, architettura o criteri di successo.

• Scrivi prima il risultato utente e i non-obiettivi.
• Trasforma i requisiti in criteri verificabili, inclusi errori e permessi.
• Fai generare un design tecnico e chiedi all'agente di indicare rischi e file coinvolti.
• Dividi in task piccoli, ciascuno con test o controllo di completamento.
• Solo dopo avvia Claude Code, Codex, Cursor o Copilot sull'implementazione.

Prompt pratico per iniziare:

Voglio trasformare questa richiesta in una mini specifica per un coding agent.

Richiesta:
[descrivi feature o bug]

Prima fammi domande se manca contesto.
Poi produci:
1. requisiti utente
2. non-obiettivi
3. criteri di accettazione testabili
4. design tecnico breve
5. task atomici
6. comando o controllo di verifica per ogni task

Non scrivere codice finché non approvo la specifica.

Come collegarlo a /goal e AGENTS.md

SDD non sostituisce le istruzioni di progetto o il goal operativo. AGENTS.md spiega all'agente come lavorare nel repository: comandi, stile, file da non toccare, vincoli editoriali o tecnici. La specifica spiega che cosa costruire per questa feature. /goal può essere il ponte finale: esegui questi task, rispetta questa spec, e dimostra il risultato con questi controlli.

• AGENTS.md: regole stabili del repository.
• Spec: intenzione e vincoli della feature corrente.
• /goal: condizione di completamento per la sessione agentica.
• Task list: unità di lavoro che puoi assegnare, verificare e chiudere una per una.

Domande frequenti