Chiedere a un agente di costruire un’app partendo da una sola frase produce quasi sempre qualcosa che funziona nella demo e si rompe appena lo usa una persona vera. Il problema non è il modello. Ogni dettaglio che non hai scritto diventa una decisione che l’agente prende da solo, con una risposta plausibile ma non tua. Una specifica breve, scritta prima del primo prompt, sposta molte di queste decisioni nel punto in cui costano poco.
Perché la specifica viene prima del codice
Un agente di codice lavora su quello che gli dai. Se una regola non c’è, la deduce dal contesto, dagli esempi che trova nel progetto e dalle soluzioni che ha già visto in casi simili. Il risultato sembra coerente, ed è proprio questo che lo rende difficile da notare. Correggere una scelta sbagliata dopo che il codice è scritto costa molto più che scriverla in due righe prima.
Vale anche per chi non programma. Se sai dire che cosa deve fare l’app, a chi serve e che cosa non deve fare, hai già metà del lavoro. L’altra metà consiste nel rendere quelle frasi verificabili.
Le cinque domande che la specifica deve chiudere
Una specifica utile risponde a cinque domande, in quest’ordine. Se una risposta manca, l’agente la inventerà.
- Chi la usa. Un ruolo preciso, non “gli utenti”. Il titolare di uno studio che prenota dal telefono ha esigenze diverse da chi amministra il sistema dal computer di ufficio.
- Quale problema risolve. Una frase sola, con la situazione attuale: “oggi le richieste arrivano per telefono e poi vanno ricopiate a mano nel gestionale”.
- Che cosa entra e che cosa esce. I dati in ingresso (un modulo, un file, una API) e il risultato atteso (una schermata, un messaggio, un record salvato).
- Che cosa non fa. È la domanda più trascurata. Un elenco di esclusioni esplicite impedisce all’agente di aggiungere accessi con i social, pagamenti o dashboard che nessuno ha chiesto.
- Come si capisce che funziona. Criteri verificabili, scritti come prove da eseguire.
Il template in una pagina
Non serve un documento formale. Basta un file di testo nella radice del progetto, lungo una pagina. Nei progetti piccoli questa struttura funziona bene:
- Scopo: una frase.
- Utenti e ruoli: elenco breve, un ruolo per riga.
- Flussi principali: da tre a cinque passi numerati per ogni flusso.
- Dati: nome dei campi, tipo, obbligatorio sì o no, valori ammessi.
- Fuori scopo: elenco esplicito.
- Vincoli: lingua, paese, privacy, servizi a pagamento consentiti, stack tecnico già scelto.
- Domande aperte: tutto ciò che non hai ancora deciso, marcato come tale.
La sezione delle domande aperte è quella che si dimentica più spesso, e la più utile. Scriverla obbliga a decidere prima, oppure a far decidere l’agente solo dopo averlo chiesto esplicitamente.
Criteri di accettazione scritti come prove
Un criterio come “l’app deve essere veloce” non si verifica. Un criterio come “una prenotazione confermata compare nell’agenda del titolare entro un minuto” si può controllare con un test automatico o con una prova a mano. Ogni criterio dovrebbe avere tre parti: la situazione di partenza, l’azione, il risultato atteso.
Esempio ipotetico per un piccolo gestionale di appuntamenti: dato un utente senza ruolo amministratore, quando apre la pagina Impostazioni, allora il modulo di modifica dei prezzi non compare, e il server rifiuta una richiesta diretta di salvataggio. Questa frase dice due cose che l’agente non può reinterpretare. Stabilisce chi vede che cosa, e stabilisce che la protezione sta sul server, oltre che nell’interfaccia.
Per il primo rilascio ne bastano da cinque a dieci. Se ne scrivi molti di più già nella prima versione, di solito la portata è troppo larga.
Il primo prompt: un piano, non il codice
Quando la specifica è pronta, il primo messaggio all’agente non deve chiedere codice. Deve chiedere un piano. Una formulazione semplice:
Leggi il file della specifica. Prima di scrivere codice, elenca le ambiguità che trovi, proponi un piano in passi piccoli e indica come testerai ciascun criterio di accettazione. Non modificare ancora nessun file.
Le ambiguità elencate dall’agente sono il valore principale di questo passaggio. Ognuna corrisponde a una decisione che altrimenti sarebbe stata presa in silenzio, e male. Rispondi punto per punto, aggiorna la specifica con le risposte, e solo dopo chiedi il primo passo.
Lavora poi un passo alla volta, con una prova per ogni passo. Chiedere dieci modifiche in un solo giro rende impossibile capire quale ha rotto che cosa.
Quando cambia una decisione, cambia prima la specifica
Durante lo sviluppo le decisioni cambiano. Conta l’ordine delle operazioni. Se modifichi prima il codice e ricordi la specifica solo in un secondo momento, la specifica diventa falsa, e il prossimo agente la seguirà alla lettera. La regola è semplice: la modifica entra nel file con la data, poi parte il prompt per il codice.
Tieni la specifica nel repository, versionata come il resto del progetto. Ogni cambiamento resta leggibile nella cronologia e non dipende dalla memoria di nessuno. Una sessione di agente, di solito, non ricorda le decisioni prese in quella precedente.
Errori frequenti
- Una specifica che descrive il codice invece del comportamento. “Usa una tabella con indice sulla data” è un dettaglio di implementazione. “La lista delle prenotazioni si carica in meno di due secondi con diecimila record” è un requisito.
- Una specifica troppo lunga. Oltre le due pagine nessuno la rilegge, né tu né l’agente, che tenderà a seguire le parti più recenti e a trascurare le altre.
- Nessuna esclusione. È il modo più comune in cui un prototipo cresce senza che nessuno l’abbia deciso.
- Una specifica scritta a codice finito. Serve come documentazione, ma non come guida, che era lo scopo.
Un test rapido: fai leggere la specifica a una persona che non conosce il progetto. Se le serve chiederti due volte che cosa intendi, un agente farebbe la stessa cosa, con la differenza che non ti chiederebbe nulla e riempirebbe il vuoto con supposizioni. Riscrivere fino a quando non restano domande aperte è il lavoro vero.
Domande frequenti
Quanto deve essere lunga una specifica per un progetto piccolo?
Una pagina, al massimo due. Se superi due pagine, di solito stai descrivendo più di un progetto. Dividilo in fasi e scrivi la specifica solo per la prima.
Posso scrivere la specifica con l’AI?
Puoi farti aiutare a strutturarla, ma le decisioni devono restare tue. Se la specifica nasce da una richiesta generica che non hai riletto riga per riga, ottieni solo il problema di partenza scritto in modo più ordinato.
Serve anche se lavoro da solo?
Sì. Quando lavori da solo nessuno ti chiede che cosa intendevi, quindi la specifica è l’unico punto in cui quella domanda viene posta. Nei progetti personali è spesso l’unico documento che permette di riprendere il lavoro dopo settimane.
Quale delle cinque domande della specifica ti risulta più difficile da rispondere per il progetto su cui stai lavorando adesso?