Scrivi una specifica prima di dare un prompt a un agente di coding AI

Scrivere la richiesta direttamente a un agente di coding sembra più veloce che scrivere prima qualcosa su carta, e per un'attività davvero banale spesso lo è. I problemi iniziano con tutto ciò che ha più di un'interpretazione ragionevole: l'agente ne sceglie una, costruisce in quella direzione e tu scopri che era quella sbagliata solo quando leggi il codice finito. Ogni giro successivo costa più dei pochi minuti che una specifica avrebbe richiesto.

Una specifica cambia l'ordine delle operazioni. Prima che venga scritto qualsiasi codice, metti per iscritto tre cose in linguaggio semplice: cosa deve fare la cosa, per chi è e i controlli di completamento che dimostrano che funziona. Non è un documento tecnico. Somiglia di più al biglietto che lasceresti a un assistente capace che non ti ha mai incontrato: abbastanza dettagli perché non debba tirare a indovinare sulle parti che contano.

Funziona per una ragione semplice. L'agente smette di riempire i vuoti della tua richiesta con le proprie ipotesi, perché i vuoti da riempire sono meno. E tu smetti di scoprire cosa volevi davvero leggendo a posteriori l'output dell'agente, perché l'hai già scritto prima di chiedere qualsiasi cosa.

Niente di tutto questo vale per un solo strumento. Claude Code, Codex, Copilot, Cursor e ogni altro agente di coding funzionano alla stessa maniera di base: istruzioni in linguaggio semplice in ingresso, codice e comandi in uscita. Una specifica cambia ciò che entra, e quindi ciò che torna indietro, qualunque agente tu stia usando.

Spec Kit di GitHub è un toolkit open source, mantenuto nel repository di GitHub con licenza MIT, pensato per dare agli agenti di coding AI processi strutturati, modelli riutilizzabili e risultati documentati invece di conversazioni isolate. Si installa con un proprio strumento da riga di comando e il suo README lo descrive come un toolkit per iniziare con lo sviluppo guidato dalle specifiche, o con qualsiasi altro processo strutturato che vuoi far seguire a un agente.

Il flusso principale, secondo la documentazione del progetto, attraversa una sequenza con nome di sei comandi: uno fissa i principi guida del progetto, uno scrive la specifica vera e propria, uno trasforma la specifica in un piano tecnico, uno divide il piano in un elenco ordinato di attività, uno esegue le attività e scrive il codice, e un ultimo verifica quanto il risultato sia convergente rispetto alla specifica. L'indicazione del progetto è di eseguirli uno alla volta, rivedendo ogni risultato prima di proseguire, e di ripetere i passaggi di implementazione e convergenza finché la convergenza non segnala il lavoro come convergente, invece di affidare tutto all'agente in un colpo solo.

Il toolkit include anche estensioni separate da aggiungere al flusso principale, sempre secondo la sua documentazione: un gruppo di comandi costruito attorno alla valutazione e alla correzione di un bug specifico, e un altro costruito per portare un'idea abbozzata attraverso ricerca e definizione prima di decidere se costruirla davvero.

Quanto agli agenti a cui si collega, la documentazione di installazione di Spec Kit ne indica diversi tramite una chiave di integrazione da passare in fase di installazione, tra cui Claude Code e GitHub Copilot, e rimanda a una propria documentazione separata per collegare altri agenti oltre a quelli citati direttamente. Considera qualsiasi elenco di agenti, compreso questo, come un'istantanea: controlla la documentazione aggiornata di Spec Kit prima di dare per scontato che uno strumento sia o non sia supportato oggi.

Per chi non è sviluppatore e deve costruire una sola piccola cosa, eseguire l'intero flusso di Spec Kit può essere più cerimonia di quanta ne serva. La sola specifica in tre parti, scritta come primissimo messaggio all'agente che usi già, fa gran parte del lavoro da sola, senza niente da installare.

Incolla la specifica, poi lascia che l'agente ti faccia domande di chiarimento prima di scrivere qualsiasi cosa. Un agente capace chiede quando qualcosa non è chiaro, e una specifica gli dà qualcosa di concreto su cui chiedere, invece di indovinare in silenzio e costruire con sicurezza la cosa sbagliata.

Questa versione semplice dell'abitudine è portabile. Lo stesso documento in tre parti funziona con Claude Code, Codex, Copilot, Cursor o qualsiasi altro agente di coding, perché nulla dipende da una funzione specifica di un solo strumento. È un'abitudine che stai costruendo, non un plugin che stai installando.

Per una singola piccola build, una semplice specifica in tre parti scritta direttamente in chat basta ed è più rapida che installare qualcosa. La maggior parte degli esempi di questa guida è scritta proprio per questo caso.

Spec Kit comincia a valere il costo di configurazione quando ripeti questo lavoro sullo stesso progetto, vuoi che i principi siano applicati automaticamente a ogni nuova funzione, oppure vuoi la struttura delle estensioni per la correzione di bug o la valutazione di idee invece di inventarne ogni volta una tua versione.

In ogni caso la competenza vera è la stessa: dire cosa fa, per chi è e come saprai che è finito, prima che venga scritta una sola riga di codice. Il toolkit si limita ad automatizzare questa messa per iscritto in modo coerente, quando l'abitudine è una che metti in pratica abbastanza spesso da valere l'automazione.