Quando usarlo

Hai un’idea («vorrei una pagina che mostri lo stato dei servizi») e devi passarla a chi la realizza: uno sviluppatore, un fornitore, o un agente. Se la passi così com’è, ricevi qualcosa che assomiglia a quello che volevi ma non lo è, e comincia il tira e molla dei chiarimenti. Questo playbook trasforma l’idea vaga in una specifica che chi la riceve può eseguire senza indovinare, scrivendola insieme all’assistente.

Cosa serve

Un assistente AI e l’idea di partenza, anche a livello di «vorrei una cosa che…». Non serve sapere già i dettagli: il metodo li tira fuori con un’intervista, che è il punto.

I passi

1 · Fatti intervistare, non scrivere subito. L’errore è chiedere all’assistente di scrivere la specifica al volo: la riempie di assunzioni. Meglio che ti faccia le domande giuste prima:

Devo scrivere una specifica per [l'idea, in una frase]. Prima di scriverla, intervistami: fammi le domande necessarie a togliere le ambiguità, una alla volta o in piccoli gruppi. Chiedimi in particolare: chi la userà e per fare cosa, cosa deve succedere nei casi normali e in quelli strani, cosa è esplicitamente fuori ambito, come capiremo che è fatta bene. Non scrivere ancora la specifica: prima le domande.

2 · Rispondi, e lascia emergere i buchi. Le domande dell’assistente ti fanno scoprire cosa non avevi deciso: cosa succede se un dato manca, chi può vedere cosa, quali casi limite contano. È il lavoro vero, e va fatto ora, non a cose costruite.

3 · Fai scrivere la specifica con le quattro parti. Dopo l’intervista, chiedi il documento:

Ora scrivi la specifica con questa struttura:
- OBIETTIVO: cosa deve fare e per chi, in un paragrafo.
- CASI D'USO: le situazioni concrete, inclusi i casi limite e cosa deve succedere in ognuno.
- CRITERI DI ACCETTAZIONE: la lista spuntabile che dice quando è "fatta". Ogni criterio verificabile.
- FUORI AMBITO: cosa NON deve fare, per evitare che chi realizza aggiunga di testa sua.

4 · Collauda la specifica su un secondo lettore. La prova che regge: dalla a un secondo prompt nel ruolo di chi deve realizzarla, e vedi se fa domande. Se ne fa molte, la specifica ha ancora buchi, e sai quali. Se dice «chiaro, ecco come procederei», è pronta.

Un esempio completo

Idea di partenza: la pagina «Sempre Online» di Lumen, quella che mostra ai clienti lo stato dei loro siti. L’intervista del passo 1 fa emergere le decisioni non prese: cosa vede un cliente (solo i suoi siti o tutti?), cosa mostra la pagina quando un sito è giù davvero, cosa succede se il controllo dello stato non risponde, chi può accedere. Senza l’intervista, lo sviluppatore avrebbe indovinato queste risposte, probabilmente in modo diverso da come volevi. La specifica finita ha i criteri di accettazione spuntabili («il cliente vede solo i propri siti», «un sito irraggiungibile è marcato in rosso entro 5 minuti») e un fuori-ambito esplicito («non gestisce le notifiche via email, quello è un altro lavoro»). Il collaudo del passo 4: un secondo prompt costruttore la legge e, se è buona, non ha bisogno di chiederti nulla di essenziale.

Gli errori tipici

Saltare l’intervista. Una specifica scritta di getto è piena di assunzioni invisibili, che saltano fuori come errori a lavoro fatto. Le domande prima costano minuti, le assunzioni sbagliate costano rifacimenti.

Nessun fuori-ambito. Se non dici cosa NON fare, chi realizza aggiunge quello che gli sembra utile, e ti ritrovi con funzioni che non volevi e con cui poi convivi. Il fuori-ambito è la parte che protegge dal lavoro in più.

Criteri non verificabili. «Deve essere veloce» non è un criterio, è un desiderio. «Carica in meno di 2 secondi» sì. Un criterio che non sai spuntare non serve a decidere se è fatto.

La variante team

Quando le richieste passano di mano spesso, il prompt d’intervista diventa un modello condiviso, e la specifica ha sempre le stesse quattro parti, così chi realizza sa dove guardare. Il fuori-ambito, in particolare, diventa il posto dove si scrivono i confini una volta invece di litigarci dopo. La specifica è parente stretta del brief per un agente: entrambi servono a far fare la cosa giusta a qualcuno senza stargli addosso a ogni passo.