Sviluppo guidato dalle specifiche con Spec Kit
Il vibe coding — "costruiscimi una dashboard", accetta qualunque cosa torni indietro — funziona benissimo finché la funzionalità non diventa grande. Poi l'agente va alla deriva: dimentica una decisione presa prima, re-inventa una funzione, oppure consegna qualcosa che tecnicamente gira ma non è ciò che intendevi. Lo Sviluppo guidato dalle specifiche (Spec-Driven Development, SDD) è la soluzione che ha preso piede in tutta la comunità dell'agentic coding nel 2026: invece di trattare il prompt come usa e getta, rendi una specifica scritta e revisionabile la fonte di verità e fai generare il codice all'agente a partire da essa.
L'open-source Spec Kit di GitHub trasforma quell'idea in un flusso di lavoro concreto che puoi eseguire dentro Claude Code già oggi.
- Capire cos'è lo sviluppo guidato dalle specifiche e quale problema risolve
- Percorrere le fasi di Spec Kit: constitution → specify → plan → tasks → implement
- Installare la CLI Specify e integrarla in Claude Code
- Conoscere i controlli di qualità opzionali (clarify, analyze, checklist)
- Decidere quando lo SDD vale l'overhead e quando saltarlo
Perché le specifiche, non solo i prompt
Un prompt sparisce nel momento in cui il turno finisce. Una specifica è un artefatto: può essere letta, revisionata in una PR, corretta e ri-eseguita. Quel singolo cambiamento risolve i tre modi in cui le grandi build agentiche vanno male:
- Deriva (Drift) — l'agente contraddice una decisione precedente perché nessuno l'ha messa per iscritto. La specifica è la memoria.
- Ambiguità — "fallo bello" significa dieci cose diverse. Costringere i requisiti nella prosa fa emergere le lacune prima che il codice esista, dove sono economiche da correggere.
- Diff non revisionabili — una PR generata da 2.000 righe è difficile da giudicare. Una specifica + un piano revisionati rendono il diff atteso invece che sorprendente.
Il modello mentale: l'intento è la cosa di valore e durevole; il codice è un artefatto a valle, rigenerabile. Lo SDD è il cugino disciplinato della stessa Plan Mode di Claude Code — prima pianifica, poi costruisci — scalato a un'intera funzionalità e persistito in file nel tuo repo.
Il flusso di lavoro di Spec Kit
Spec Kit struttura una funzionalità come una breve pipeline di slash command. Ognuno scrive artefatti Markdown nel tuo repo (sotto .specify/), così ogni fase è ispezionabile e sotto controllo di versione.
- Esegui /speckit.constitution una volta per progetto. Scrive i principi di governo — stile del codice, soglia di testing, scelte architetturali non negoziabili — in .specify/memory/constitution.md. Ogni fase successiva viene verificata rispetto a essa, quindi questo è il tuo guardrail durevole (pensalo come un CLAUDE.md focalizzato sui principi).
- Esegui /speckit.specify e descrivi COSA stai costruendo e PERCHÉ — user story, requisiti, criteri di successo. Deliberatamente NON lo stack tecnologico. L'agente produce una specifica strutturata che leggi e correggi prima di andare avanti.
- Esegui /speckit.plan con le tue scelte tecniche — framework, archivio dati, vincoli. Ora viene scritto il COME: architettura, componenti e come soddisfano la specifica. Le decisioni tecnologiche vivono qui, non nella specifica, così la specifica resta agnostica rispetto all'implementazione.
- Esegui /speckit.tasks per scomporre il piano in un elenco numerato e ordinato di passi piccoli e revisionabili singolarmente. È questo che rende la build verificabile — puoi vedere la sequenza prima che venga scritto qualunque codice.
- Esegui /speckit.implement e l'agente esegue l'elenco dei task, costruendo la funzionalità rispetto al piano e alla constitution. Poiché ogni fase precedente è stata revisionata, il diff risultante è atteso, non una sorpresa.
Controlli di qualità opzionali
Altri tre comandi stringono il ciclo quando una funzionalità è ad alto rischio:
/speckit.clarify— interroga la specifica per le aree sotto-specificate e ti pone domande mirate prima della pianificazione. È meglio eseguirlo subito dopospecify./speckit.analyze— verifica in modo incrociato specifica, piano e task per coerenza e lacune di copertura./speckit.checklist— genera una checklist di validazione così che "fatto" sia definito e testabile.
- Esegui /speckit.clarify prima di /speckit.plan — correggere l'ambiguità è più economico prima che l'architettura sia decisa.
- Tratta ogni artefatto generato come una PR: leggilo, correggilo e solo allora avanza alla fase successiva.
- Committa gli artefatti .specify/ — sono il registro revisionabile dell'intento dietro al codice.
Mettilo in funzione con Claude Code
Spec Kit include una CLI, Specify, che genera gli slash command nel tuo progetto. Supporta oltre 30 agenti di coding, tra cui Claude Code.
- Usa uv per installarla dal repo. (Richiede Python + uv.)
- Genera la struttura .specify/ e i comandi dell'agente. Esegui init in un repo nuovo o esistente; quando richiesto, scegli Claude Code come agente (oppure passa il flag di integrazione attuale dal README).
- Avvia claude nella cartella del progetto. Saprai che è tutto collegato quando /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks e /speckit.implement compaiono come slash command.
Install the Specify CLI (uv)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
Scaffold spec-driven workflow into a project
# new project specify init my-feature # or in the current repo specify init --here
Then, inside Claude Code, run the pipeline
/speckit.constitution Establish principles: TypeScript strict, tests for every public function, no secrets in code. /speckit.specify Build a CSV export for the reports page: users pick a date range and download a CSV of matching rows. /speckit.clarify /speckit.plan Next.js App Router, server action for the query, stream the CSV; no new dependencies. /speckit.tasks /speckit.implement
- Il flag esatto di selezione dell'agente per specify init cambia tra una release e l'altra — controlla la quickstart nel README invece di copiare un flag alla cieca.
- Lo SDD non elimina la necessità di verificare: leggi il codice generato ed eseguilo. La specifica rende il diff revisionabile, non automaticamente corretto.
- Non mettere mai segreti o credenziali nella specifica, nel piano o nella constitution — vengono committati come qualunque altro file.
Quando usarlo (e quando no)
Lo SDD scambia un po' di cerimonia iniziale per ottenere controllo. Quello scambio vale la pena quando il lavoro è grande, ambiguo o deve essere revisionato da altri — ed è puro overhead quando non lo è.
- Usa lo SDD: funzionalità greenfield, build su più file, qualunque cosa un collega debba revisionare, oppure lavoro che affiderai a una flotta di subagent.
- Salta lo SDD: script una tantum, fix minuscoli, codice esplorativo usa e getta — un semplice prompt o la Plan Mode è più veloce.
- Funziona anche su brownfield: punta /speckit.specify a un miglioramento di un codebase esistente, non solo a progetti nuovi.
Mettiti alla prova
Check yourself
0/3- Lo sviluppo guidato dalle specifiche rende una specifica revisionabile — non il prompt — la fonte di verità, eliminando deriva, ambiguità e diff non revisionabili.
- Spec Kit di GitHub (la CLI Specify) porta lo SDD in Claude Code come slash command /speckit.*.
- La pipeline è constitution → specify → (clarify) → plan → (analyze) → tasks → (checklist) → implement, e ogni fase scrive artefatti ispezionabili.
- Tieni il COSA/PERCHÉ nella specifica e il COME nel piano; revisiona ogni artefatto come una PR prima di avanzare.
- Usalo per funzionalità grandi, ambigue o revisionate; saltalo per lavoro usa e getta — e verifica sempre comunque il codice generato.
Avanti
- Plan Mode — il ciclo integrato e più leggero "pianifica prima di costruire"
- Slash Commands — come i comandi /speckit.* si inseriscono nel sistema di comandi di Claude Code
- CLAUDE.md & Memory Files — l'idea dei principi-come-memoria dietro la constitution
- Subagents — affida un elenco di task revisionato a una flotta di agenti
- Coding & Software Development — la mentalità del verifica-tutto da cui dipende lo SDD