La specifica che l'AI sa eseguire

Dal campo

Due persone chiedono la stessa cosa allo stesso assistente, nello stesso pomeriggio. La prima scrive: «fammi un gestionale per le prenotazioni della palestra». La seconda arriva con una pagina in cui c’è scritto chi prenota, cosa vede, quanti posti ha una lezione, cosa succede quando i posti finiscono e chi può cancellare.

La prima riceve qualcosa in due minuti e passa i tre giorni successivi a correggere fraintendimenti. La seconda aspetta venti minuti e riceve una cosa che somiglia a quello che aveva in testa.

Non è la bravura dell’assistente a cambiare fra i due casi. È che il secondo aveva già preso le decisioni, il primo le ha delegate senza accorgersene.

Cos’è una specifica, in concreto

È un file di testo dentro il progetto. Non una conversazione, non un messaggio lungo: un file, che resta, che si aggiorna e che l’assistente può rileggere ogni volta che serve. Negli strumenti che lavorano dentro una cartella di progetto è il documento a cui si torna a ogni sessione. È la ragione per cui la sessione di martedì sa cosa è stato deciso lunedì.

Il contenuto minimo è questo, in quest’ordine.

A cosa serve, in tre righe. Scritto per una persona che non sa niente del progetto. Se non riesci a spiegarlo in tre righe, torna alla lezione precedente: il perimetro è ancora troppo largo.

Chi lo usa e cosa vede. Le persone coinvolte e, per ciascuna, cosa trova davanti quando apre la cosa. Nel caso della palestra: chi prenota vede l’elenco delle lezioni di questa settimana con i posti liberi; chi gestisce vede l’elenco degli iscritti a ogni lezione.

Le azioni, una per riga. Con il verbo davanti. Prenotare un posto. Cancellare una prenotazione entro due ore dall’inizio. Vedere gli iscritti a una lezione.

Le regole. Qui sta il valore vero del documento: è la parte che quasi tutti saltano. Una lezione ha un numero massimo di posti. Non si può prenotare la stessa lezione due volte. Non si può cancellare a meno di due ore dall’inizio. Ogni regola che non scrivi verrà inventata dall’assistente. La inventerà ragionevole ma diversa da come la vuoi tu.

I dati. L’elenco delle cose che il sistema deve ricordare, con i loro attributi. Una lezione ha: nome, giorno, ora, posti totali, insegnante. Una prenotazione ha: persona, lezione, momento in cui è stata fatta.

Cosa è fuori. L’elenco «dopo» della lezione precedente, copiato qui. Serve a te, perché ti ricorda che avevi deciso; serve all’assistente, che altrimenti prende l’iniziativa.

Scrivere le regole prima delle schermate

L’istinto porta a descrivere per prime le schermate: come si vede, dove sta il bottone, di che colore. È la parte che l’AI fa meglio da sola e che tu cambierai comunque tre volte.

Le regole sono l’opposto: sono invisibili, sono noiose da scrivere e sono l’unica parte che l’assistente non può indovinare. «Non si può cancellare a meno di due ore dall’inizio» è una decisione di gestione della palestra, non di software. Nessun modello al mondo la conosce.

Una prova utile: leggi la tua specifica e conta le frasi che contengono «non si può», «solo se», «al massimo», «entro». Se sono zero, la specifica non è ancora finita.

Il formato: prosa, non schemi

Non serve un linguaggio formale, non servono diagrammi, non serve la sintassi di nessuno strumento. Prosa italiana, frasi corte, un’informazione per riga. Gli assistenti leggono bene la prosa strutturata e tu la rileggerai fra due settimane senza dover ricordare una convenzione.

Quello che conta è che il file stia nel progetto e non nella chat. Le conversazioni si perdono, si troncano, ricominciano. Il file no. Quando l’assistente sbaglia perché non sapeva una cosa, la risposta giusta non è spiegargliela nel messaggio successivo, ma aggiungerla al file, così non la chiederà mai più.

Questa è l’abitudine che separa chi costruisce qualcosa di finito da chi passa le settimane a ripetersi.

Quanto lunga

Per una prima versione ragionevole, fra una e tre pagine. Sotto una pagina mancano le regole. Sopra le tre, quasi sempre, c’è dentro roba dell’elenco «dopo».

La specifica cresce mentre costruisci. È normale: ogni volta che scopri una decisione che non avevi preso, la prendi e la scrivi. Alla fine del progetto quel documento vale più del codice, perché il codice si può rigenerare e le decisioni no.

Al lavoro con l’AI

Il primo passaggio si fa a specifica già scritta di tuo pugno, anche male: serve a trovare i buchi, non a scriverla al posto tuo.

«Ti allego la specifica del software che voglio costruire. Non scrivere codice. Leggila e dimmi, in elenco: 1) quali decisioni ho lasciato aperte, cioè i punti dove tu dovresti scegliere per me; 2) quali regole mancano, in particolare i limiti, i divieti e i casi di errore; 3) quali dati il sistema dovrebbe ricordare e io non ho elencato. Per ogni punto fammi una domanda secca a cui posso rispondere in una riga. Non proporre soluzioni: fammi le domande.»

«Ora riscrivi la mia specifica integrando le risposte che ti ho dato, nello stesso ordine di sezioni e nella stessa lingua. Non aggiungere funzionalità che non ho chiesto: se pensi che ne manchi una, mettila in fondo sotto il titolo «dopo».»

Errori comuni

• Tenere la specifica nella chat invece che in un file del progetto: la conversazione finisce e con lei tutto quello che avevi deciso.
• Descrivere le schermate e non le regole: le schermate l’assistente le sa immaginare, i tuoi limiti di gestione no.
• Lasciare che sia l’AI a scrivere la prima versione della specifica: restituirà un documento ordinato e generico. Le decisioni continueranno a mancare.
• Correggere a voce e non nel file: la stessa spiegazione data tre volte in tre sessioni è il segnale che manca una riga da qualche parte.
• Considerarla finita: la specifica si aggiorna a ogni decisione presa. Alla fine vale più del codice.

Checklist operativa

• Crea nel progetto un file di specifica e scrivici a cosa serve il software in tre righe.
• Elenca le persone coinvolte e, per ciascuna, cosa vede quando apre la cosa.
• Scrivi le azioni una per riga, con il verbo davanti.
• Scrivi le regole: cerca i «non si può», «solo se», «al massimo», «entro». Verifica che non siano zero.
• Elenca i dati che il sistema deve ricordare, con i loro attributi.
• Copia in fondo l’elenco «dopo» di quello che resta fuori dalla prima versione.
• Fai rileggere la specifica all’assistente perché ti faccia le domande. Integra le risposte nel file.