La specifica in 15 righe, scritta e poi demolita

La consegna

Scegli una cosa che fai a mano ogni settimana e scrivi la specifica dell'app che la farebbe al posto tuo. Solo la specifica: quindici righe numerate, con dentro almeno due divieti e un caso di collaudo che hai calcolato tu, sulla carta. Poi la dai a Claude e gli chiedi di romperla — prima di far costruire qualsiasi cosa.

Non c'è una risposta sola: la tua app non è la mia. C'è però un modo di riconoscere una specifica che regge, ed è quello che trovi qui sotto, con un caso svolto per intero.

Come si ragiona

1. Scegli il compito, non l'idea. Un'app buona per il primo giro ha tre segni: la fai già a mano, ha regole che sai enunciare, e produce un numero o un documento. Prova del nove: sai svolgere un caso completo su un foglio in cinque minuti? Se no, non è ancora un'app — è un desiderio, e la specifica ti verrà vaga perché lo sei tu.

2. Fatti intervistare invece di scrivere di getto. P245 fa al massimo otto domande, una alla volta. Serve a una cosa sola: tirarti fuori i numeri veri. Chi scrive la specifica da solo mette «il prezzo», chi la scrive rispondendo mette «45 € a lezione».

3. Rispetta le proporzioni. Due righe di Contesto, due di Obiettivo, nove di Regole, due di Esempi. Lo sbilanciamento verso le regole non è un capriccio: contesto e obiettivo dicono cosa vuoi, le regole dicono cosa succede nei casi che non hai in mente adesso.

4. Cerca la riga dell'ordine. Ogni volta che due operazioni toccano lo stesso numero, l'ordine cambia il risultato: sconto prima o dopo l'IVA, arrotondamento a ogni riga o solo alla fine, mesi contati sul calendario o in giorni. Quella riga la scrivi tu, esplicita. Se non c'è, la decide il codice — e la decide in silenzio.

5. Trova i due divieti con una domanda. «Cosa farebbe di irreparabile se lo facesse da solo?» Le risposte tipiche sono tre: manda qualcosa a qualcuno, salva dati di clienti, mostra un numero provvisorio come se fosse definitivo. Scrivile come divieti, in maiuscolo, senza cortesie.

6. Calcola il caso di collaudo a mano, prima di scriverlo. È il passaggio che quasi tutti saltano ed è quello che paga: mentre lo calcoli scopri le regole che mancano, perché a un certo punto ti fermi e ti chiedi «e qui che faccio?». Quella domanda è una riga di specifica.

7. La critica non è «va bene?». Chiedere un giudizio produce complimenti. Chiedi una cosa più stretta: le ambiguità. Ogni riga che si può leggere in due modi, le due letture, quale sceglierebbe scrivendo il codice adesso e cosa cambia nel risultato. Poi decidi tu — la critica trova, non firma.

8. Fatti rifare il caso di collaudo dalle sole regole scritte. È il collaudo della specifica, non dell'app: se per arrivare al tuo numero deve aggiungere una decisione sua, quella decisione ti manca. È lì che si nascondono gli errori da quattro giorni e da quaranta euro.

9. Il verdetto. La specifica è pronta quando una persona che non conosce il tuo lavoro, con quelle quindici righe e una calcolatrice, arriva al tuo numero senza farti domande. Non prima.

Una soluzione svolta

Serena, personal trainer a Firenze, segue 120 clienti dal 2019. Fra i suoi percorsi il più venduto è quello da 10 lezioni, 450 €, e l'app copre solo quello: si parte stretti. I pacchetti li tiene su un quaderno, una pagina a testa. Quando una cliente chiede «quante me ne restano?», Serena sfoglia. Il pacchetto vale sei mesi: è una regola sua, e nessuno se la ricorda mai.

La specifica uscita dall'intervista con P245:

1. [Contesto] Sono Serena, personal trainer a Firenze; i pacchetti li tengo su un quaderno e a ogni domanda devo sfogliare.
2. [Contesto] L'app copre un formato solo: percorso da 10 lezioni, 450 € — 45 € a lezione. Un pacchetto vale sei mesi dalla data di acquisto.
3. [Obiettivo] Voglio una web app in un SOLO file HTML/JS che, data la data di acquisto e le lezioni fatte, mi dica lezioni residue, valore residuo e data di scadenza.
4. [Obiettivo] Il risultato si legge in tre righe grandi, dal telefono, in palestra, tra una cliente e l'altra.
5. [Regole] Campi: nome della cliente (facoltativo), data di acquisto (obbligatoria), lezioni fatte (obbligatoria, da 0 a 10).
6. [Regole] Lezioni residue = 10 − lezioni fatte; valore residuo = lezioni residue × 45 €, in formato italiano con due decimali: «180,00 €».
7. [Regole] Scadenza = data di acquisto + 6 mesi sul calendario. Se nel mese d'arrivo quel giorno non esiste — acquisto il 31 agosto, e il 31 febbraio non c'è — vale l'ultimo giorno del mese.
8. [Regole] I giorni alla scadenza si contano sulla data di oggi, che l'app mostra a schermo.
9. [Regole] Se la scadenza è passata, l'app scrive «scaduto il GG/MM/AAAA» e non presenta il valore residuo come spendibile.
10. [Regole] Sotto i 30 giorni alla scadenza compare l'avviso «da rinnovare entro il GG/MM».
11. [Regole] Interfaccia in italiano, leggibile da telefono con una mano.
12. [Regole — NON fare] NON manda messaggi e NON avvisa nessuno: le clienti le chiamo io.
13. [Regole — NON fare] NON salva niente: chiusa la pagina, il nome della cliente è sparito.
14. [Esempi] Collaudo: acquisto 3 marzo 2026, 6 lezioni fatte → 4 residue · 180,00 € · scade il 3 settembre 2026.
15. [Esempi] Se la data manca o le lezioni fatte sono 11, l'app lo dice e non mostra numeri.

Il prompt della critica, da incollare in una chat nuova:

Qui sotto c'è la specifica di un'app che NON devi costruire. Fai il critico e cerca solo
le ambiguità: le righe che si possono leggere in due modi.
Per ognuna dimmi: le due letture, quale sceglieresti tu se dovessi scrivere il codice
adesso, e che differenza fa nel risultato.
Poi rifai il caso di collaudo usando SOLO le regole scritte. Se per arrivare al mio
numero devi aggiungere una decisione tua, dimmi esattamente quale.
Non proporre funzionalità in più. Non scrivere codice.
La specifica:
[LE TUE QUINDICI RIGHE]

Cosa è tornato indietro, sul caso di Serena:

• Riga 6, ambigua. «Lezioni fatte»: la cliente che disdice due ore prima ha fatto la lezione o no? Le due letture cambiano il valore residuo di 45 €. Serena decide, e diventa una riga: disdetta oltre le 24 ore, non conta; sotto le 24 ore, conta come fatta.
• Riga 7, la scoperta che vale l'esercizio. Per arrivare al 3 settembre serve una decisione: sei mesi sul calendario o 180 giorni? Con 180 giorni la scadenza sarebbe il 30 agosto. Quattro giorni di differenza: abbastanza per far scadere un pacchetto la settimana prima dell'ultima lezione. Nella prima stesura la riga 7 diceva solo «+ 6 mesi»: la parola «sul calendario» è arrivata dopo la critica.
• Riga 8, un difetto silenzioso. «Oggi» è l'orologio del telefono. Se la data del telefono è sbagliata, l'app sbaglia senza dirlo. Rimedio già scritto nella riga: la data di riferimento si mostra a schermo, così l'errore si vede.

Specifica finale: sedici righe. Quindici era il tetto, non un dogma — si sfora per una regola che evita un errore, mai per una funzione in più.

Come capisci di averlo fatto bene

• Dai le righe a qualcuno che non conosce il tuo lavoro e chiedigli di calcolare il caso di collaudo con una calcolatrice: arriva al tuo numero senza farti domande?
• Conta i divieti. Se sono zero, non hai finito.
• Ogni numero del risultato ha una regola che lo produce: prendi i numeri della riga di collaudo e cercali nelle regole, uno per uno.
• La critica ha trovato almeno un'ambiguità. Zero ambiguità di solito non significa specifica perfetta: significa che hai chiesto «va bene?».
• Nessuna riga contiene un aggettivo al posto di un numero. «Veloce», «elegante», «professionale» non sono regole.

L'errore che fanno quasi tutti

Scrivere il caso di collaudo dopo aver visto l'app funzionare, copiando il numero che l'app ha prodotto. A quel punto il collaudo non collauda niente: certifica che l'app è d'accordo con sé stessa. Il caso si calcola sulla carta, prima, e il numero della riga 15 è quello della carta. Se poi l'app ne dà un altro, ha torto l'app finché non dimostra il contrario.

E adesso

Con la specifica critica alla mano, la fase 2 del capitolo costa pochi minuti: il prototipo nell'artifact e il primo giro di collaudo. I due prompt che userai subito: l'intervista P245 — go.totaliweb.com/p245 — e la verifica dei calcoli P469 — go.totaliweb.com/p469. Il modello della specifica coi segnaposto è nel kit: go.totaliweb.com/r-kit-preventifacile.