Specifiche software e AI: guida a GitHub Spec Kit e Kiro

L'obiettivo non è produrre più documentazione. Serve un accordo sintetico che permetta a un fondatore di respingere un comportamento errato, a un ingegnere di mettere in discussione il progetto tecnico e a chi revisiona il lavoro di stabilire quali prove servono per approvare il merge.

Per iniziare, scegli una funzionalità ben delimitata nel repository che usi già. Un'esportazione, una regola di approvazione o una preferenza per le notifiche rendono evidente il valore del metodo più di quanto faccia chiedere a un agente di definire un'intera applicazione.

Spec driven development: come usare le specifiche software?

Nello sviluppo guidato dalle specifiche con agenti AI, una descrizione del comportamento atteso, già sottoposta a revisione, orienta la pianificazione, la definizione delle attività, l'implementazione e la verifica. La specifica stabilisce che cosa deve accadere e perché. Il piano spiega come l'applicazione esistente realizzerà quel comportamento. Le attività suddividono il piano in interventi verificabili.

Già prima dell'AI, pratiche affini basate sulle specifiche le utilizzavano come test eseguibili, come nel behavior-driven development. Quella tradizione è compatibile con questo flusso di lavoro, ma una specifica in Markdown non è di per sé un test eseguibile. Documentazione BDD di Cucumber.

La novità pratica è che gli agenti di programmazione possono usare questi documenti durante tutta l'implementazione. GitHub Spec Kit, un toolkit open source per organizzare il lavoro di un agente, fornisce il processo da affiancargli. Kiro, l'ambiente di sviluppo di AWS, integra nel prodotto un flusso basato sulle specifiche. In entrambi i casi resta da decidere quale esperienza offrire al cliente.

Documentazione verificata il 13 ottobre 2026: i nomi dei comandi, i percorsi dei file e le funzionalità descritti qui provengono dalla documentazione corrente di GitHub, Kiro, Anthropic e OpenAI. L'esempio della funzionalità ha uno scopo illustrativo: non descrive un rilascio in produzione né una prova di produttività misurata.

Per chi sviluppa, il risultato è un perimetro di implementazione più ristretto: l'agente dovrebbe riutilizzare l'applicazione che circonda la funzionalità, senza riprogettarla. Per chi gestisce il prodotto e chi ha fondato l'azienda, la revisione decisiva avviene prima: si stabilisce chi può esportare i dati prima di esaminare il pulsante di esportazione. Per chi acquista gli strumenti, adottare il metodo non richiede di spostare tutti gli sviluppatori su un nuovo editor. Si parte dall'agente già in uso; si investe in strumenti più strutturati quando mantenere i documenti diventa un problema.

Sviluppo guidato dalle specifiche: il flusso di lavoro

Tieni separati i documenti, perché ciascuno risponde a una domanda diversa. Un diagramma architetturale non può risolvere una regola di prodotto mancante, e un elenco di attività non dimostra che la funzionalità operi correttamente.

La decisione sul comportamento spetta al fondatore o al responsabile di prodotto. Al responsabile tecnico spetta valutare se la soluzione si integra nel sistema. L'agente può preparare entrambe le proposte, ma una prosa scorrevole non dimostra che le decisioni siano corrette.

Strumenti per lo spec driven development: quanta struttura serve?

Scegli gli strumenti in base al punto in cui il coordinamento smette di funzionare. GitHub Spec Kit è adatto a un repository in cui serve un processo ripetibile attorno a un agente già in uso. Kiro si rivolge a chi vuole requisiti, progettazione ed esecuzione delle attività dentro l'ambiente di sviluppo. Semplici file bastano per una prima funzionalità o per un team che ha già una prassi di revisione affidabile.

GitHub Spec Kit: comandi e file da conoscere

GitHub Spec Kit fornisce istruzioni riutilizzabili, modelli e script di supporto; a svolgere il lavoro è l'agente di programmazione scelto. Il README corrente esplicita la sequenza principale: stabilire i principi del progetto, specificare la funzionalità, pianificarla, definire le attività, implementarle e verificare ciò che manca.

Il README corrente richiede Python 3.11 o successivo, uv (un programma per installare pacchetti Python) e un agente supportato. L'esempio di configurazione usa GitHub Copilot, l'assistente di programmazione di GitHub. Esegui questi comandi nel terminale:

uv tool install specify-cli
specify init my-project --integration copilot
cd my-project

Poi avvia l'agente di programmazione in quella directory. Esegui ogni istruzione del flusso di lavoro nella chat dell'agente e rivedi il risultato prima di proseguire. Non sono comandi da eseguire nella shell.

La differenza nei nomi conta. Il README usa la sintassi predefinita delle skill di Copilot, /speckit-specify. Il riferimento dettagliato dei comandi usa la forma con il punto, /speckit.specify. L'integrazione delle skill di Codex usa $speckit-specify. Adotta la sintassi dell'integrazione installata: la punteggiatura non è intercambiabile. Riferimento delle integrazioni.

Nomi e funzioni seguono il riferimento Agentic SDD di GitHub. Clarify, checklist e analyze aggiungono ulteriori verifiche della qualità. Il documento constitution stabilisce le regole permanenti del progetto: non va riscritto per ogni piccola funzionalità.

Nell'esempio dell'esportazione, l'istruzione specify dovrebbe descrivere chi può esportare, quali record includere, il contenuto del file e il comportamento in caso di errore. Fornisci lo stack esistente e i vincoli del repository nella fase di pianificazione. Richiedi esplicitamente i test di accettazione: il comando tasks documenta la generazione dei test quando vengono richiesti, quindi un elenco di attività generato non dimostra che siano stati inclusi test adeguati.

I file da rivedere sono:

• .specify/memory/constitution.md: i principi del progetto. Modello del documento constitution.
• specs/<feature-directory>/spec.md: il comportamento della funzionalità. Le directory delle funzionalità si trovano normalmente sotto specs/; il nome della directory viene generato o configurato. Modello di specify.
• plan.md e tasks.md nella directory della funzionalità: il progetto tecnico dell'implementazione e la suddivisione del lavoro. La pianificazione produce anche research.md, data-model.md e quickstart.md, con contracts/ per le interfacce esterne pertinenti. Modello del piano, riferimento di tasks.

Dopo l'implementazione, converge confronta il codice con la specifica, il piano e le attività. Se trova lacune, aggiunge lavoro a tasks.md; non corregge direttamente il codice. Esegui le attività aggiunte, poi ripeti la verifica. Il risultato «Converged» è un elemento utile per la revisione, ma non sostituisce i test né l'approvazione.

Per un'applicazione esistente, la guida all'adozione di GitHub parte dalla conservazione dello stato iniziale e dall'inizializzazione nel progetto stesso. Il comando è specify init --here --force --integration <key>, sostituendo <key> con la chiave dell'integrazione documentata, come claude o codex. La guida avverte che --force può sostituire i file gestiti in conflitto. Esamina il diff risultante. Non serve ricostruire le specifiche dell'intera applicazione prima di definire la modifica successiva.

Il limite: Spec Kit può mettere in luce contraddizioni tra i documenti e, al tempo stesso, accettare una regola di business sbagliata ma coerente in tutti i documenti. La manutenzione dei file aggiuntivi si giustifica quando più persone o più sessioni devono fare riferimento allo stesso accordo.

Spec driven development con Kiro: spec, steering e hook

Kiro distingue l'intento della funzionalità, le indicazioni permanenti del progetto e le azioni automatiche. Usa le spec per la funzionalità in corso, lo steering per le convenzioni dell'intero repository e gli hook per le verifiche ripetibili.

Nell'IDE, l'editor di codice di Kiro, fai clic su + sotto Specs, oppure scegli Spec nella chat. Seleziona Feature, poi Requirements-First. Rivedi i requisiti prima di accettare il progetto tecnico e la suddivisione delle attività. La directory della funzionalità così creata contiene .kiro/specs/<feature-name>/requirements.md, design.md e tasks.md. Dopo averle riviste, esegui le attività dall'interfaccia dedicata. Documentazione delle spec di Kiro.

Kiro usa EARS, acronimo di Easy Approach to Requirements Syntax, per esprimere una condizione e il comportamento atteso dal sistema. Nel nostro esempio: «Quando un membro richiede un'esportazione, il sistema deve negare la richiesta e non restituire alcun file di esportazione». È una formulazione abbastanza concreta da diventare un test. Specifiche delle funzionalità.

Kiro offre anche Design-First e Quick Spec. Design-First parte dal progetto tecnico; Quick Spec crea i documenti senza i passaggi intermedi di approvazione. Se sei un fondatore e l'agente continua a fraintendere ciò che vuoi ottenere, scegli Requirements-First e sfrutta quelle revisioni. Eliminare i punti di revisione significherebbe eliminare proprio la parte del processo che affronta il problema.

Lo steering fornisce un contesto permanente in Markdown sotto .kiro/steering/. I file di base sono product.md, tech.md e structure.md e descrivono prodotto, stack e organizzazione del repository. Nell'IDE, Generate Steering Docs crea questo contesto iniziale. Confrontalo con il repository. Inserisci qui «riutilizzare la policy esistente per autorizzare gli utenti in base alla loro appartenenza al workspace» se vale per più funzionalità; «solo i proprietari possono esportare» va invece nella specifica dell'esportazione. Documentazione dello steering.

Gli hook eseguono comandi shell o prompt per l'agente al verificarsi di un evento. Attualmente, i file degli hook di progetto si trovano in .kiro/hooks/<id>.json; PostFileSave è uno dei trigger documentati. Un hook mirato potrebbe eseguire i test di esportazione già presenti quando cambia il codice sorgente pertinente. Mantieni le stesse verifiche anche nell'integrazione continua, cioè nei controlli automatici sulle modifiche al codice proposte, in modo che non vengano eseguite soltanto da un hook locale. La tabella corrente delle funzionalità di Kiro indica il supporto degli hook nell'IDE e nella CLI, ma non su Web o Mobile. Documentazione degli hook.

Il limite: un requisito generato automaticamente può formalizzare un presupposto che nessuno ha approvato. Prima del progetto tecnico, rivedi permessi, risultati vuoti e comportamento in caso di errore. La modalità spec aggiunge struttura, ma non colma le lacune nelle decisioni di prodotto.

Sviluppo guidato dalle specifiche con Claude Code

Claude Code, l'agente di programmazione di Anthropic, può seguire questo processo con una specifica della funzionalità e Plan Mode. Per provare il metodo non occorre installare un framework per le specifiche.

Crea direttamente specs/workspace-export/spec.md, oppure rivedi una bozza preparata dall'agente. Poi avvia la sessione del terminale in modalità pianificazione:

claude --permission-mode plan

Chiedi a Claude di leggere il file, esaminare il codice esistente collegato all'esportazione e proporre un piano di implementazione legato ai criteri di accettazione. Prima di approvare l'implementazione, chiedi quali questioni restano aperte e quali verifiche precise intende eseguire.

Plan Mode è pensata per l'analisi e la proposta di un approccio. Anthropic documenta un'eccezione nelle sessioni interattive da terminale in cui sono disponibili i permessi di bypass: in quel caso i blocchi alle modifiche previsti dalla modalità pianificazione non vengono applicati. Se vuoi che il vincolo di approvazione resti efficace, avvia la sessione senza bypass abilitato. Documentazione delle modalità di autorizzazione.

Dopo aver rivisto la proposta, salva l'approccio accettato in specs/workspace-export/plan.md e la relativa checklist in tasks.md, quindi autorizza l'implementazione. Questi percorsi sono una convenzione suggerita dall'articolo, non file che Plan Mode promette di creare automaticamente. La guida a Plan Mode di Claude Code descrive i controlli e il passaggio all'approvazione.

Conserva le istruzioni permanenti del repository in CLAUDE.md, seguendo la guida alla memoria del team, e il comportamento della singola funzionalità nella specifica. Altrimenti, un requisito temporaneo per l'esportazione può trasformarsi in un'istruzione permanente che influenza lavori estranei.

Il limite: un piano lasciato soltanto nella conversazione è facile da perdere o contraddire. Salvarlo serve solo se l'implementazione e la revisione successive vi fanno riferimento esplicito.

Codex: Plan Mode con lo stesso file di specifica

Codex, l'agente di programmazione di OpenAI, supporta lo stesso passaggio essenziale dalla specifica al piano. In una chat della CLI senza attività in corso, /plan avvia la pianificazione e può includere la richiesta sulla stessa riga. Documentazione ufficiale dei comandi.

Una richiesta utile è: «Leggi specs/workspace-export/spec.md. Esamina la policy esistente per l'appartenenza al workspace, la query delle attività e i test. Proponi il piano di implementazione più contenuto che soddisfi tutti i requisiti. Individua le decisioni mancanti prima di implementare».

Rivedi il piano, salva i file concordati e poi chiedi a Codex di implementare le attività, producendo un resoconto finale che colleghi ciascun requisito ai test. Usa AGENTS.md per le istruzioni permanenti del repository; /init può crearne la struttura iniziale. La guida alla configurazione di Codex CLI descrive l'ambiente da cui partire.

OpenAI documenta anche l'uso di Markdown per conservare specifiche, piani e avanzamento nei lavori più lunghi. Il vantaggio è che una sessione successiva può riaprire l'accordo. Il limite: Plan Mode non mantiene aggiornata da sola una specifica separata della funzionalità. Includi il suo aggiornamento nella revisione delle modifiche. Flusso di lavoro documentato da OpenAI.

Un esempio pratico: esportare in CSV i dati di un workspace

Una piccola esportazione CSV, cioè il download di record come valori separati da virgole, mostra perché decidere prima il comportamento può evitare di rimettere mano a più file. «Aggiungi l'esportazione CSV» lascia all'agente il compito di indovinare ruolo dell'utente, perimetro dei dati, paginazione e formato del file. Un pulsante ben disegnato può nascondere una risposta sbagliata a ciascuna di queste domande.

Quello che segue è un esempio ragionato per un'applicazione esistente di gestione delle attività. Percorsi, identificativi dei requisiti e test proposti hanno scopo didattico: non descrivono un repository su cui siano stati eseguiti test o approvati merge per questo articolo.

La specifica in una pagina

Salva questo contenuto nel file spec.md della funzionalità, oppure inserisci gli stessi requisiti di comportamento nel file requirements.md di Kiro:

Nota la decisione contenuta in R2: «tutti i risultati corrispondenti» è diverso da «la pagina visibile». Chiarirla prima dell'implementazione cambia subito la query e il piano dei test. Chiarirla dopo la demo può richiedere di rivedere entrambi.

R4 indica volutamente una decisione che richiede esempi concreti. Prima di approvare la specifica, stabilisci come gestire gli input che possono essere interpretati come formule nei fogli di calcolo e registra gli esempi. Scrivere soltanto «rendere sicure le esportazioni» lascerebbe all'agente la scelta della policy al posto tuo.

Il piano: integrare la funzionalità nell'applicazione esistente

Il piano dovrebbe riutilizzare la sessione e la policy esistente per l'appartenenza al workspace, estrarre o riutilizzare la logica dei filtri dell'elenco delle attività e aggiungere una risposta per l'esportazione senza cambiare quella dell'elenco. L'esportazione deve passare dai controlli di autorizzazione del server. L'accesso al workspace va stabilito in base all'appartenenza dell'utente autenticato; solo dopo si applicano i filtri richiesti all'interno di quel perimetro.

Se il repository dispone già di un serializzatore CSV, usa quello. Specifica gli header relativi al contenuto e al download, la policy per la sicurezza dei campi, il comportamento in caso di errore e i test. Aggiungi il pulsante usando gli stati di caricamento ed errore già presenti nell'applicazione.

Il piano deve anche confrontare la dimensione prevista dei risultati con i limiti di richiesta e memoria dell'applicazione. Se l'esportazione di tutti i risultati non è compatibile con questi limiti, riporta il conflitto al responsabile della funzionalità. Decidete se limitare l'esportazione o definire separatamente l'elaborazione in background. L'agente non deve inventare in silenzio un limite massimo né aggiungere un sistema di job in contrasto con R6.

Le attività: rendere verificabile ogni modifica

Traduci il piano in interventi che chi revisiona possa riconoscere:

1. Copri con controlli di regressione il comportamento esistente dell'elenco delle attività e le regole condivise dei filtri.
2. Aggiungi test di autorizzazione delle richieste per proprietario, membro, proprietario rimosso e un altro workspace.
3. Implementa la query limitata al perimetro autorizzato e la risposta CSV usando la policy concordata per i campi.
4. Aggiungi il comando di esportazione, lo stato di caricamento e la visualizzazione degli errori.
5. Completa le verifiche di accettazione ed esamina il diff per individuare modifiche estranee alla funzionalità.

Questa suddivisione vale per l'esempio. Un toolkit potrebbe generare un elenco diverso: valutalo in base alla sua capacità di coprire quanto concordato.

In un'applicazione TypeScript, le modifiche da revisionare potrebbero interessare server/exports/tasks.ts per autorizzazione, filtri e risposta; ui/tasks/ExportButton.tsx per l'interazione; e tests/task-export.test.ts per i casi di accettazione. Sono percorsi illustrativi, non convenzioni obbligatorie di un framework. Un nuovo worker per una coda o una migrazione del database segnalerebbero una variazione del perimetro da risolvere prima del merge.

Dai criteri di accettazione alla decisione sul merge

Chiedi prove del comportamento, non un elenco dei file modificati dall'agente. La descrizione della pull request dovrebbe collegare i requisiti a verifiche come queste:

Chi revisiona dovrebbe confrontare questi controlli con la specifica, esaminare il codice di autorizzazione e delle query e provare il flusso utente concordato nell'ambiente normalmente usato per la revisione del progetto. Se l'agente ha scritto sia l'implementazione sia i test, valuta i risultati attesi in modo indipendente. Un test può confermare fedelmente lo stesso presupposto errato su cui si basa il codice.

Supponiamo, per esempio, che durante la revisione emerga che l'endpoint legge soltanto la pagina corrente. Mantieni R2 se il responsabile vuole ancora tutti i risultati corrispondenti; correggi la query e aggiungi un test con corrispondenze oltre quella pagina. Se il responsabile modifica il perimetro, aggiorna insieme R2, il piano e i test prima dell'approvazione.

Procedi al merge quando le prove corrispondono a quanto concordato: includi nella stessa pull request la specifica revisionata, il piano finale, il registro delle attività completate, l'implementazione e i test. Registra lì ogni variazione del perimetro accettata. Dopo il merge, mantieni la specifica come riferimento aggiornato oppure contrassegnala come documento storico della funzionalità. Lasciare che una vecchia specifica sembri ancora autorevole prepara il terreno per nuove incomprensioni.

Il vantaggio nasce dal chiarire permessi e paginazione prima che i relativi presupposti si propaghino nell'implementazione. Specifica, test e codice conservano così la stessa decisione anche dopo il merge.

Quanto costa e quando conviene?

Il costo del metodo comprende il tempo di revisione e manutenzione e il lavoro dell'agente per preparare i documenti e implementare la funzionalità. Spec Kit è open source, ma l'agente di programmazione collegato mantiene le proprie condizioni d'uso. Il semplice Markdown non aggiunge un abbonamento a uno strumento per le specifiche; l'uso del modello, però, non diventa gratuito.

Il listino commerciale standard di Kiro prevede Free a $0 al mese con 50 crediti e Pro a $20 per utente al mese con 1,000 crediti, prima delle imposte applicabili. Quattro abbonamenti Pro costano quindi 4 × $20 = $80 al mese, esclusi crediti aggiuntivi e imposte. È il calcolo del costo delle licenze, non una previsione del numero di funzionalità che potrai rilasciare. Pagina ufficiale dei prezzi di Kiro.

I crediti aggiuntivi a pagamento costano $0.04 ciascuno. Kiro dichiara che l'affinamento delle specifiche, l'esecuzione delle attività e l'esecuzione degli hook dell'agente consumano crediti, e che un'attività complessa di una specifica può consumare più di un credito. Senza osservare il carico di lavoro reale, non c'è una conversione attendibile da «crediti» a «funzionalità completate». Definizioni dei crediti di Kiro.

La valutazione economica è semplice: il costo aggiuntivo per specificare, rivedere e mantenere la funzionalità deve essere inferiore al costo del rifacimento che permette di evitare. Misura questi costi nel tuo processo. Un metodo che aggiunge documenti ma rimanda le stesse decisioni alla revisione del codice non giustifica il lavoro supplementare.

Che cosa viene sopravvalutato e quando è eccessivo?

La promessa esagerata è che un documento sufficientemente dettagliato garantisca la correttezza del lavoro dell'agente. Non è così. Una specifica può essere sbagliata, l'implementazione può ignorarla e i test possono ripeterne i presupposti errati.

La distinzione utile è tra intento dichiarato e comportamento fatto rispettare dal sistema. Un requisito afferma che i membri non possono esportare; un controllo lato server e i relativi test aiutano a far rispettare quella regola. Una checklist dei requisiti verifica la descrizione. Non esegue l'applicazione. Considerare equivalenti queste cose crea una falsa sicurezza.

Un altro problema è il progressivo disallineamento dei documenti. Se uno sviluppatore cambia il comportamento dei permessi ma modifica soltanto il codice, l'agente successivo potrebbe «correggere» l'applicazione per riportarla alla specifica ormai superata. Ogni modifica al comportamento deve aggiornare l'accordo pertinente, oppure quell'accordo va esplicitamente archiviato. Un contesto permanente più ricco aiuta solo finché resta accurato.

Adotta subito il metodo se l'agente continua a sbagliare permessi, casi limite, integrazioni o criteri di accettazione. Usa questo flusso per una funzionalità le cui ambiguità coinvolgono più componenti o più persone incaricate della revisione.

Rimanda la specifica formale se stai ancora cercando di capire se qualcuno desidera la funzionalità. Prima realizza un prototipo usa e getta o indaga ciò che non conosci. Una specifica curata per un'idea non validata può far sembrare già giustificato l'investimento sbagliato.

Mantieni semplici le piccole correzioni quando la modifica desiderata è evidente e circoscritta: un refuso, un adeguamento a uno stile già stabilito o un bug limitato con un chiaro test di regressione. Descrivi il comportamento atteso e verificalo. Un ciclo completo con constitution, piano e attività può richiedere più attenzione di quanta ne serva per quella modifica.

Il criterio di scelta non è il numero di righe di codice. È il numero di presupposti rilevanti che, altrimenti, l'agente dovrebbe stabilire da solo.

La prima settimana con lo spec driven development

Scegli una piccola funzionalità già nel backlog. Fai approvare al suo responsabile una specifica del comportamento di una pagina, includendo esclusioni e casi di errore. Usa il tuo agente attuale in modalità pianificazione, oppure il flusso corrispondente di Spec Kit o Kiro, per proporre un piano basato sul repository.

Rivedi le domande aperte prima dell'implementazione. Chiedi un elenco di attività collegato ai requisiti. Nella pull request, confronta le prove con lo stesso accordo e registra le decisioni cambiate. Il processo deve avere solo il peso che le ambiguità rendono necessario.

Iscriviti alla newsletter per scoprire metodi pratici per sviluppare e gestire prodotti con l'AI.