C'e un divario crescente tra gli sviluppatori che ottengono output affidabile da Claude Code e quelli che passano meta giornata a disfare cio che l'agente ha appena costruito. La differenza non e talento, esperienza o qualche trucco segreto di prompt engineering. E una questione di metodologia. Gli sviluppatori che rilasciano software di produzione con agenti IA sono convergiti su uno schema, che lo chiamino cosi o meno: definire cosa si vuole prima che l'agente inizi a scrivere codice.
Questo articolo da un nome a quello schema. Lo sviluppo spec-first e una metodologia per l'ingegneria del software assistita da IA. Non una vaga "best practice." Un ciclo di vita strutturato e ripetibile con fasi definite, checkpoint chiari e artefatti concreti ad ogni passo. Se hai cercato un modo per rendere l'output di Claude Code prevedibile abbastanza da scommettere il tuo calendario di rilascio, questo e il framework.
Il tetto del Vibe Coding
"Vibe coding" e entrato nel vocabolario a inizio 2025. La proposta: descrivi cosa vuoi in linguaggio naturale, lascia che l'IA lo scriva, itera finche non sembra giusto. Per prototipi, progetti del weekend e script una tantum, il vibe coding funziona. Si ottiene qualcosa di funzionale velocemente, e se si rompe dopo, la posta in gioco e bassa.
Il software di produzione opera sotto vincoli diversi. Il codice deve integrarsi con una codebase esistente, soddisfare requisiti specifici e sopravvivere al contatto con altre persone che lo manterranno. Quando il vibe coding incontra questi vincoli, le modalita di fallimento sono prevedibili.
Il primo fallimento e la deriva. Descrivi una funzionalita vagamente, l'agente implementa la sua interpretazione, aggiusti, l'agente reimplementa la sua interpretazione corretta. Tre iterazioni dopo, hai codice funzionante che non soddisfa nessuno dei tuoi requisiti originali perche ogni iterazione ha spostato il bersaglio. Stai convergendo su cio che l'agente pensa tu voglia, non su cio di cui hai realmente bisogno.
Il secondo fallimento sono le decisioni invisibili. Ogni lacuna nella tua descrizione e una decisione che l'agente prende silenziosamente. Schema del database, strategia di gestione errori, forma dell'API, regole di validazione, scelta delle librerie. Scopri queste decisioni durante il code review, o peggio, in produzione. L'agente non ha preso decisioni cattive. Ha preso decisioni non commissionate, e non avevi meccanismo per intercettarle prima che fossero incorporate nell'implementazione.
Il terzo fallimento e la paralisi da review. Un diff di 600 righe in cui l'agente ha scelto l'architettura, il modello dati, i codici di errore e la gestione dei casi limite non e revisionabile nel senso tradizionale. Non stai revisionando codice contro una spec. Stai ricostruendo la spec dal codice, poi decidendo se sei d'accordo. Questo richiede piu tempo di quanto ne avrebbe richiesto scrivere la spec.
Il vibe coding raggiunge un tetto perche confonde due attivita distinte: decidere cosa costruire e costruirlo. Lo sviluppo spec-first le separa.
Spec-First come metodologia
Lo sviluppo spec-first e un ciclo di vita a quattro fasi. Ogni fase produce un artefatto concreto. Ogni transizione ha una condizione di gate chiara. La metodologia funziona con qualsiasi agente di codifica IA, ma gli esempi in questo articolo usano Claude Code perche e li che la community sta iterando piu velocemente.
Fase 1: Brainstorm
Tu e l'agente (o solo tu) esplorate lo spazio del problema. Quali sono i vincoli? Quali approcci esistono? Quali sono i compromessi? E conversazionale. Non ti stai impegnando su nulla. Stai mappando il territorio.
La condizione di gate: hai un approccio preferito e puoi articolare perche questo approccio e non le alternative.
Il brainstorming con Claude Code e prezioso perche l'agente ha ampie conoscenze di pattern e librerie. L'errore e saltare dal brainstorm direttamente al codice. Il brainstorm fa emergere opzioni. Non sceglie tra di esse. Lo fai tu.
Fase 2: Spec
Scrivi la decisione. Questo e il contratto contro cui l'agente implementera. Una spec non e una user story, non e un ticket Jira, non e un paragrafo di prosa. E un documento strutturato con:
- Dichiarazione del problema: cosa e rotto o mancante, in termini concreti
- Approccio proposto: la soluzione scelta dalla fase di brainstorm
- File interessati: quali file l'agente deve toccare (e implicitamente, quali no)
- Criteri di accettazione: condizioni testabili che definiscono "fatto"
- Fuori ambito: cosa l'agente deve esplicitamente evitare
I criteri di accettazione sono l'elemento piu importante. Ognuno deve essere un'azione concreta con un risultato osservabile. "L'autenticazione dovrebbe funzionare" non e un criterio. "Inviare credenziali valide restituisce un 200 con un token di sessione; inviare credenziali non valide restituisce un 401 senza token" lo e.
La sezione fuori ambito previene il gold-plating. Senza di essa, gli agenti "miglioreranno" codice adiacente, faranno refactoring di file che hanno notato disordinati, o aggiungeranno funzionalita che sembrano correlate. Ogni minuto che l'agente spende su lavoro non richiesto e un minuto che tu spendi revisionando lavoro non richiesto.
La condizione di gate: qualcuno che non era al brainstorm potrebbe leggere questa spec e costruire la cosa giusta.
Fase 3: Implementazione
L'agente esegue contro la spec. Non contro una conversazione. Non contro un ricordo di cio che avete discusso. Contro un documento concreto con criteri testabili.
Prima di scrivere codice, l'agente produce un piano: una lista numerata di modifiche che intende fare, quali file modifichera e come verifichera il risultato. Questo piano e un checkpoint di due minuti. Lo leggi, confermi che corrisponde alla tua intenzione e dai il via libera all'implementazione. Oppure intercetti un malinteso e lo correggi. In entrambi i casi, hai investito due minuti invece di venti.
Il pattern plan-before-code non e burocrazia. E il singolo intervento a maggior leva in tutto il workflow. La maggior parte degli errori di implementazione non sono errori di codifica. Sono errori di comprensione: l'agente ha frainteso la spec. Intercettare un errore di comprensione in un piano costa due minuti. Intercettarlo in un diff di 400 righe costa venti. Intercettarlo in produzione costa un giorno.
La condizione di gate: l'agente ha pubblicato un rapporto di completamento con affermazioni specifiche su cosa e stato costruito e come e stato verificato.
Fase 4: Verifica
Tu o un processo QA confermate l'implementazione contro la spec. Non "sembra giusto?" ma "soddisfa ogni criterio di accettazione?"
La verifica e meccanica. Prendi ogni criterio dalla spec, esegui il test (lancia un comando, apri un browser, innesca un evento) e registri il risultato: superato o fallito. I criteri che falliscono tornano alla Fase 3. La verifica e documentata insieme all'implementazione cosi che chiunque legga il task tra sei mesi possa vedere esattamente cosa e stato testato.
La condizione di gate: ogni criterio di accettazione ha un risultato registrato superato/fallito.
Questo e il ciclo di vita completo. Quattro fasi, quattro artefatti (motivazione dell'approccio, spec, piano di implementazione, registro di verifica), quattro condizioni di gate. Le fasi sono sequenziali ma leggere. Per una funzionalita di media dimensione, le fasi 1 e 2 richiedono 15-20 minuti. La fase 3 richiede il tempo dell'implementazione. La fase 4 richiede 5-10 minuti.
Perche conta di piu con gli agenti che con gli umani
Ogni argomento per scrivere spec precede l'IA. "Scrivi i requisiti prima del codice" e un consiglio che esiste da prima che la maggior parte di noi nascesse. Allora perche inquadrarlo come qualcosa di specifico allo sviluppo assistito da IA?
Perche gli agenti cambiano la funzione di costo.
Uno sviluppatore umano che riceve un requisito vago si fermera e fara domande. "Intendevi auth con password o SSO?" "Deve funzionare su mobile?" "Cosa succede quando il token scade?" Ogni domanda e un mini-checkpoint che spinge l'implementazione verso il target corretto. Il costo di una spec vaga con uno sviluppatore umano e qualche thread Slack e forse un pomeriggio di rework.
Un agente che riceve un requisito vago non si fermera. Prendera ogni decisione ambigua silenziosamente, si impegnera su un approccio e ti presentera un'implementazione finita. Il costo di una spec vaga con un agente e un'implementazione finita che potrebbe essere completamente sbagliata, piu il tempo che impieghi a scoprire che e sbagliata, piu il tempo per rifarla.
L'asimmetria e netta. Gli agenti sono piu veloci nell'esecuzione e peggiori nel giudizio rispetto agli sviluppatori umani. Ogni ambiguita nella spec e una chiamata di giudizio, e ogni chiamata di giudizio che l'agente fa senza guida e un lancio di moneta su se il risultato corrisponde alla tua intenzione. Una spec elimina i lanci di moneta.
C'e una seconda ragione, piu sottile. Gli agenti non obiettano. Un ingegnere senior che riceve una spec cattiva dira "questo non ha senso a causa di X." Un agente implementera fedelmente una spec cattiva e produrra output fedelmente errato. Lo sviluppo spec-first ti costringe a mettere alla prova il tuo pensiero prima di consegnarlo a un'entita che lo eseguira senza fare domande. La spec non e solo per l'agente. E per te.