Sviluppo guidato da specifiche con Claude Code: un tutorial guidato

Che cos'è lo sviluppo guidato da specifiche?

Lo sviluppo guidato da specifiche è un flusso di lavoro basato su tre documenti in sequenza: uno che spiega cosa deve fare una modifica, un piano che specifica i passaggi e il codice scritto seguendo il piano, con una revisione umana tra ogni coppia.

I tre punti di revisione che una funzionalità attraversa nello sviluppo guidato da specifiche.

Una specifica è un breve documento, scritto in linguaggio semplice prima di qualsiasi codice, che spiega cosa deve fare una modifica. Prendi una funzionalità come "consenti agli utenti di esportare i loro dati". Una specifica per questa funzionalità fissa le risposte che altrimenti un agente dovrebbe indovinare. Elenca 

• Formati di file supportati
• La modalità di consegna
• Il comportamento durante un'esportazione a metà
• Le parti della funzionalità volutamente escluse

Ecco l'apertura reale di una specifica che Claude Code ha scritto per una modifica workout-shape-verification in una mia app di accountability basata su Telegram. La modifica sostituisce una fragile soglia della frequenza cardiaca con un controllo sulla forma della curva della frequenza cardiaca nel tempo:

# Workout Shape-Based Verification — Design Spec
 
**Created:** 2026-05-05
**Status:** Draft
**Supersedes (partially):** [2026-03-17-calisthenics-verification-design.md]
  — replaces the absolute-HR thresholds for the Workout activity type.
  Run / Ride / Walk verification is unchanged.
 
## Problem
 
The current Workout verifier accepts an activity only if absolute heart-rate
levels clear fixed cutoffs: avg ≥ 120, max ≥ 140, range ≥ 30, suffer_score ≥ 3.
Two failures in production:
 
1. **False-negative risk.** As cardiovascular fitness improved
   (resting HR ~80), real calisthenics sessions with disciplined rest now
   average 115–125 bpm. Recent sessions have come within 4 bpm of the 120 floor.
 
<!-- ... continues for hundreds of lines through Solution, Risks,
 	Out of scope, and What is removed / added / changed / unchanged -->

Il piano è il documento successivo. Scompone la specifica in task numerati su cui l'agente può lavorare uno alla volta, ciascun task indicando un file, una modifica, un ordine e un test. Dove la specifica risponde al "cosa", il piano risponde "in quali passaggi". 

Il codice viene per ultimo, scritto seguendo il piano un task alla volta.

Tre documenti. Una revisione umana siede tra ogni coppia. Rivedi la specifica prima che diventi un piano. Rivedi il piano prima che diventi codice. Rivedi il codice prima del merge.

In cosa lo sviluppo guidato da specifiche differisce dalla plan mode

Potresti aver usato la plan mode integrata di Claude Code (premi Shift+Tab due volte per entrarci) e chiederti perché questa è diversa. La plan mode produce un piano in un'unica interazione di chat. Il piano vive in memoria, senza una specifica persistita e senza un passaggio di revisione tra le fasi.

Lo sviluppo guidato da specifiche persiste specifica e piano come file su disco. Ognuno passa una revisione umana prima che inizi la fase successiva e gli artefatti sopravvivono tra le sessioni. La plan mode comprime due fasi dello sviluppo software in una sola interazione. Funziona per lavori piccoli e fallisce non appena la codebase cresce e inizia a servire utenti reali.

Perché il vibe-coding va a sbattere

Il vibe-coding funziona su prototipi, singoli file e script usa e getta. Peggiora nelle applicazioni reali con utenti a cui rispondere e in codebase già grandi. La linea da tracciare è attorno ai 4 file. Qualsiasi modifica che tocchi così tanti file ha bisogno di una specifica, così come qualsiasi refactoring con uno stato finale coerente o qualsiasi task in cui "che cosa dovrebbe fare esattamente?" è la parte difficile.

Il fallimento ha una causa chiara. Un prompt vago come "aggiungi la condivisione di foto alla mia app" fa sì che il modello indovini migliaia di requisiti impliciti.

Prendi uno solo di quei requisiti: le preferenze di notifica. Il product manager presume interruttori per canale. Il backend costruisce un interruttore on/off. Il frontend presuppone un'integrazione a livello di OS. Quattro letture ragionevoli di tre parole, quattro prodotti diversi.

Ogni passaggio di revisione nello sviluppo guidato da specifiche intercetta una classe di errori diversa prima che diventino costosi. La revisione della specifica intercetta l'espansione dello scope e le diagnosi sbagliate della causa radice. La revisione del piano intercetta implementazioni a metà e pattern in conflitto. La revisione del codice intercetta piani che sulla carta funzionano ma si rompono al primo test fallito.

Il ritorno è reale e cresce lentamente. La fase di specifica costa ore di scrittura prima che giri un solo test, e le prime funzionalità sembrano più lente del vibe-coding. Il mio punto di pareggio è arrivato intorno alla quarta o quinta funzionalità. A quel punto, le specifiche intercettavano errori di design che altrimenti avrei rilasciato e riscritto una settimana dopo.

Le prossime tre sezioni passano in rassegna tre approcci open source che eseguono questo flusso di lavoro dentro Claude Code. Sono ordinati dal più leggero al più pesante in termini di struttura imposta.

Superpowers

Superpowers è il più leggero dei tre. È quello che uso ogni giorno ed è quello che tratteremo più nel dettaglio.

Che cos'è Superpowers?

Superpowers è un plugin di Claude Code di Jesse Vincent (obra/superpowers, MIT license), con circa 194k stelle su GitHub. 

Fornisce un set di skill. Una Claude skill, in Claude Code, è un file di istruzioni con nome che l'agente carica su richiesta per seguire un flusso di lavoro specifico. Superpowers fornisce skill che vincolano Claude Code al ciclo guidato da specifiche invece di lasciarlo saltare direttamente al codice.

La pagina del progetto Superpowers su GitHub.

Come installare Superpowers

Installalo tramite il marketplace ufficiale dei plugin di Claude Code:

/plugin install superpowers@claude-plugins-official

Un hook SessionStart carica automaticamente la skill using-superpowers, quindi il flusso di lavoro è attivo dal momento in cui inizi a digitare. (Gli hook di Claude Code sono script che l'agente esegue in uno specifico evento del ciclo di vita.) Non c'è nulla da configurare per progetto.

Il workflow di Superpowers

Dopodiché, quattro skill gestiscono il tuo lavoro quotidiano:

Un subagente è un'istanza separata di Claude Code che il genitore delega a svolgere un lavoro focalizzato nella propria finestra di contesto. I subagenti revisori nella tabella sopra girano come subagenti, quindi leggono il codice a freddo, senza l'inquadramento del genitore.

Come usare Superpowers

Richiami le quattro skill descrivendo in linguaggio naturale cosa vuoi. La skill di brainstorming capisce "parliamo di una nuova funzionalità" e avvia da sola la conversazione sulla specifica. Le altre si attivano allo stesso modo.

Le quattro skill di Superpowers in ordine, con i due punti di revisione umani tra brainstorming e writing-plans.

La walkthrough qui sotto usa la stessa funzionalità workout-shape-verification dall'estratto della specifica sopra.

Fase 1: dal brainstorming alla specifica

Apro Claude Code e scrivo:

Let's discuss a new feature. The Workout verifier in make-me-work uses absolute heart-rate cutoffs and is now misfiring as my resting HR drops. I want to replace the absolute cutoffs with a check on the shape of the HR curve over the session.

La skill brainstorming prende in mano la conversazione e fa una decina di domande, tra cui:

• Cosa conta come la "forma" giusta
• Quali flussi di dati combinare
• Cosa fare con sessioni che hanno la forma giusta ma falliscono una vecchia soglia
• Se la modifica deve applicarsi anche a Run e Ride

Qui cadono due punti di revisione umani. Il primo è la revisione del design, dove confermo che le risposte date corrispondono a ciò che voglio. Il secondo è la revisione della specifica. Leggo il file che Claude ha scritto e lo approvo prima che inizi qualsiasi lavoro di pianificazione.

Fase 2: dalla specifica al piano

Eseguo la skill writing-plans. Legge la specifica approvata e scrive un file di piano con quattro parti:

• Una definizione di cosa significa “Fatto”
• Una mappa dei file toccati
• Un percorso utente attraverso il cammino demo
• Una lista numerata di task con sottopassi a checkbox. 

Rivedo il piano, contesto i task che sembrano fuori ordine o troppo grossolani e approvo.

Fase 3: dal piano al codice

Eseguo subagent-driven-development. Da questo punto il loop gira senza di me. Per ogni task nel piano, la skill:

1. Scrive un test fallente
2. Scrive il codice per farlo passare
3. Rifattorizza
4. Inoltra a un subagente di code review che legge il diff a freddo

Se il revisore segnala un problema, il loop lo corregge prima di passare al task successivo. Non c'è un punto di revisione umana dentro questa fase. Le revisioni che contano per questa fase sono le due precedenti.

Fase 4: revisione del diff completo

Una volta terminato il piano, eseguo requesting-code-review. Un subagente fresco legge l'intero diff rispetto alla specifica e al piano e pubblica una review. Accolgo i suggerimenti prima del merge.

Quando un task del piano rivela una contraddizione con la specifica, il loop si ferma e chiede. Posso modificare la specifica (o lasciare che lo faccia Claude) e rigenerare i task interessati. L'altra opzione è una correzione puntuale nel task stesso. Superpowers non aggira in silenzio gli errori nella specifica.

Specifiche e piani reali su disco

Ecco la specifica per la funzionalità workout-shape-verification, aperta in un editor:

Il file di specifica così come finisce su disco dopo che la skill di brainstorming lo ha scritto.

L'intestazione include i campi Created, Status e Supersedes che la skill di brainstorming scrive per impostazione predefinita. Segue la sezione Problem. Nulla di tutto ciò è codice. Il file prosegue oltre lo screenshot con sezioni per la soluzione proposta e i vincoli su cosa la modifica debba e non debba toccare.

Il piano corrispondente si apre con la sua User Journey:

Il file di piano che la skill writing-plans produce dalla specifica approvata.

Il percorso guida la demo cinque passaggi alla volta, indicando comandi, file e argomenti esatti a ogni passaggio. I task numerati che seguono traducono ciascun passaggio in sotto-passaggi a checkbox che la skill subagent-driven-development può eseguire.

I due documenti si affiancano così:

Specifica e piano fianco a fianco. La specifica risponde cosa cambia e perché. Il piano risponde in quali passaggi.

Per specifiche e piani più grandi, aggiungo uno step che il loop ufficiale non prevede: un passaggio di red-team. Prima di dare l'ok, faccio leggere la specifica a freddo a uno o più subagenti Opus, cercando falle da angolazioni diverse. È un'abitudine personale, non una funzione di Superpowers. Ha intercettato abbastanza assunzioni sbagliate da farmela mantenere.

Quando Superpowers non è la scelta giusta

Superpowers è adatto al lavoro in solitaria su una singola repo. Funziona al meglio quando l'intera codebase entra in una sessione di Claude Code e quando leggerai davvero una specifica di 2 pagine. Il confronto dettagliato è in Come scegliere tra loro più sotto. La versione breve: Superpowers fatica con funzionalità multi-repo e con lavori che richiedono una chiara separazione dei ruoli.

Un developer ha colto una quarta modalità di fallimento in un reclamo pubblico sul plugin: “Anche il più piccolo dei task richiede un'eternità, con Claude che avvia subagenti e scrive piani completamente eccessivi. Cambiare un po' di CSS ora richiede un'eternità.”

La soluzione è saltare Superpowers per le modifiche minuscole. Le skill si attivano solo sul trigger di brainstorming. Una modifica di una riga di CSS può passare per Claude Code senza invocare il ciclo della specifica. La vera modalità di fallimento lì è applicare troppo il flusso di lavoro a lavori che non hanno bisogno di una specifica.

GitHub Spec Kit

Spec Kit è la scelta quando la specifica deve sopravvivere oltre una singola sessione di Claude Code. È anche la scelta giusta quando persone che non aprono mai Claude Code devono leggere la specifica.

Che cos'è il GitHub spec-kit?

Spec Kit è un progetto GitHub (github/spec-kit, MIT license), mantenuto da GitHub stesso, con oltre 100k stelle. Fornisce una CLI più un flusso di lavoro che gira allo stesso modo su tutti i principali agenti di coding AI. Claude Code, Cursor, Aider, Cline e Roo Code sono tutti supportati. Il design agente-neutrale è ciò che consente alla specifica di vivere fuori da Claude Code.

La pagina del progetto Spec Kit su GitHub.

Come installare il GitHub spec-kit

Non c'è ancora un pacchetto PyPI ufficiale, quindi installa la CLI dal tag Git con uv:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Sostituisci vX.Y.Z con il tag di rilascio attuale. Il pacchetto è specify-cli, e il comando che registra è specify.

Il workflow del GitHub spec-kit

Il flusso di lavoro scorre attraverso nove slash command che la CLI installa nella lista dei comandi slash del tuo agente. Sei sono core per il loop, tre sono opzionali per i casi non coperti dal core.

Il separatore tra gruppo di comando e verbo è un punto, non i due punti: /speckit.specify, non /speckit:specify. 

I nove slash command di Spec Kit: sei comandi core sulla pipeline, tre comandi opzionali collegati.

Gli artefatti prodotti da questi comandi sono la stessa specifica e lo stesso piano visti nella sezione Superpowers, anch'essi scritti su disco e tracciati da Git. La differenza è la portabilità: gli artefatti di Spec Kit sono progettati per funzionare con qualsiasi agente di coding AI, non solo con Claude Code, e il flusso di lavoro è costruito per la revisione degli stakeholder via pull request su GitHub piuttosto che come sottoprodotto del loop di un singolo strumento.

Quando usare il GitHub spec-kit

In un progetto in solitaria, probabilmente non ti servirà Spec Kit. Usalo quando:

• Il progetto cresce oltre una persona
• La tua specifica necessita di revisione da parte di persone che non aprono mai Claude Code
• Stai usando un agente non-Claude-Code per parte del lavoro
• Vuoi un formato di specifica che viva fuori da qualsiasi strumento e sia leggibile anche mesi dopo

Il metodo BMAD

Dove Spec Kit organizza gli artefatti, BMAD organizza le persone. Divide il flusso di lavoro dalla specifica al codice in quattro fasi, ciascuna gestita da un agente-ruolo nominato.

Che cos'è BMAD?

BMAD-METHOD (bmad-code-org/BMAD-METHOD, MIT license, circa 47k stelle) è alla versione 6. L'acronimo, nella documentazione del progetto, si espande in "Breakthrough Method for Agile AI-Driven Development". Gira sopra Claude Code e altri agenti e si installa come un ecosistema di moduli. L'installazione predefinita ti fornisce un modulo core con sei agenti-ruolo, quattro fasi di workflow e 34 o più workflow nominati.

La pagina del progetto BMAD-METHOD su GitHub.

Come installare BMAD

Installa BMAD con Node:

npx bmad-method install

I sei agenti-ruolo sono personae di prompt che l'utente attiva per nome dall'interno dell'host agente. In Claude Code, significa digitare il comando di attivazione installato da BMAD. Controlla il README per la sintassi esatta, che varia tra le versioni. 

Presentazione degli agenti-colleghi e degli artefatti BMAD

Una volta attivato, l'agente assume le istruzioni, la voce e gli output di quel ruolo fino a quando non cambi persona. I sei sono:

• Mary, l'Analista
• Paige, la Technical Writer
• John, il Product Manager
• Sally, la UX Designer
• Winston, l'Architect
• Amelia, la Developer

Due ruoli che potresti aspettarti mancano nella v6: non c'è uno Scrum Master e nessun agente QA standalone. La pianificazione sprint e la preparazione delle story ricadono sull'agente Developer, e la generazione dei test QA è un workflow che la Developer avvia.

Il set di artefatti è più pesante di una singola specifica. Ottieni:

• un product brief
• un PRD (Product Requirements Document)
• una specifica UX
• un documento di architettura
• epic suddivisi in user story (cosa gli utenti possono fare una volta che il lavoro è online)

Il PRD e il documento di architettura insieme giocano lo stesso ruolo della specifica di Superpowers. La suddivisione li distribuisce su due agenti-ruolo e in un formato più formale. L'insieme degli artefatti copre l'intero ciclo di vita dello sviluppo software, con ogni funzionalità che eredita contesto dallo strato superiore.

Il workflow BMAD

Il flusso di lavoro v6 gira in quattro fasi.

Le quattro fasi BMAD e l'agente-ruolo che gestisce ciascuna. Il percorso Quick Flow salta le prime tre fasi per i lavori piccoli.

Fase 1, analysis, è opzionale. Mary (Analyst) e Paige (Tech Writer) svolgono ricerca e producono un product brief. Salta la fase se sai già cosa stai costruendo.

Fase 2, planning, è obbligatoria. John (PM) scrive il PRD. Sally (UX Designer) aggiunge una specifica UX quando la funzionalità ha un'interfaccia.

Fase 3, solutioning, è la fase di Winston. L'Architect abbozza prima l'architettura, poi John suddivide i requisiti in epic e story. Mettere le story dopo l'architettura è una scelta della v6 che le dimensiona su confini di implementazione reali. Winston poi esegue un controllo di prontezza all'implementazione che si conclude con un verdetto PASS, CONCERNS o FAIL.

Fase 4, implementation, è dove Amelia (Developer) lavora story per story: crea la story, la costruisce e la revisiona. Una volta completato un intero epic, avvia un workflow di generazione dei test QA su tutto l'epic. Questa è la fase in cui Claude Code scrive effettivamente il codice, lavorando come Amelia.

Per lavori piccoli e ben definiti, BMAD fornisce un percorso "Quick Flow" che attiva direttamente Amelia e salta le prime tre fasi. Il comando di attivazione è nel README di BMAD (la sintassi esatta varia tra le versioni). Quick Flow non produce PRD né documento di architettura, solo una breve story e il codice che la soddisfa. È la risposta all'obiezione "è eccessivo per cambiare un bottone".

Quando la specifica si rivela sbagliata a metà implementazione, BMAD torna al verdetto della Fase 3 di Winston. Un FAIL ti rimanda alla Fase 2 a riscrivere il PRD. Un CONCERNS procede con i rischi annotati da Winston allegati alla story. La distinzione ti permette di continuare su piccole incoerenze e fermarti nettamente su quelle grandi.

Quando la complessità ripaga

BMAD ripaga su progetti di lunga durata con utenti reali a cui rispondere. Si adatta anche a team multi-sviluppatore, con passaggi di consegne tra persone. La separazione per fasi e ruoli deve far risparmiare più tempo di quanto ne costi.

È la scelta sbagliata per un progetto personale in solitaria. Nel lavoro da soli, la suddivisione in quattro fasi e sei agenti è per lo più overhead. Non c'è una seconda persona nel team per cui la separazione dei ruoli faccia la differenza.

Come scegliere tra i framework

Tre regole guidano la scelta.

• Usa Spec Kit se la specifica deve essere letta da persone che non aprono mai Claude Code, o deve vivere in Git come artefatto a lungo termine.
• Se più persone lavorano con ruoli distinti, o c'è un vero stakeholder in stile PM nel loop, usa BMAD.
• Altrimenti, usa Superpowers.

Tre domande sul tuo progetto, quattro scelte di framework dall'altra parte.

C'è una quarta opzione che l'albero decisionale nomina: combina Spec Kit con Superpowers. Usa Spec Kit per la fase di specifica così che gli artefatti vivano in Git per la revisione trasversale del team. Poi punta la skill subagent-driven-development di Superpowers al file di piano di Spec Kit con una riga di configurazione. Ottieni la specifica durevole di Spec Kit insieme al loop di implementazione serrato di Superpowers.

Conclusione

Lo sviluppo guidato da specifiche sono tre documenti in sequenza. La specifica dice cosa costruire, il piano dice in quali passaggi e il codice segue il piano. Una revisione umana siede tra ogni coppia.

Esegui l'albero decisionale qui sopra per scegliere un framework che, per la maggior parte dei lettori, ricadrà su Superpowers. Installalo e scegli una funzionalità che altrimenti faresti in vibe-coding, qualcosa che tocchi da 3 a 5 file. Eseguila end-to-end tra brainstorming, specifica, piano ed esecuzione. Un'esecuzione reale insegna il flusso di lavoro meglio di qualsiasi descrizione.

Se vuoi ripassare prima le basi di Claude Code, DataCamp ha un tutorial pratico su Claude Code, una guida alle best practice che copre plan mode, CLAUDE.md e TDD e un approfondimento sulla plan mode stessa.