Sviluppo guidato da specifiche: come ottenere software migliore dall'IA scrivendo prima cosa si vuole

La risposta breve

Se chiedete a un assistente di IA "un portale clienti con le fatture", costruirà qualcosa. Deciderà da solo chi può vedere cosa, cosa succede quando un pagamento non va a buon fine, come sono le schermate e cosa fare dei vecchi dati. Ognuna di queste decisioni è un'ipotesi, e alcune saranno sbagliate in modi che scoprirete solo più tardi.

Lo sviluppo guidato da specifiche consiste nel mettere per iscritto prima quelle decisioni, in un documento che persone e assistenti di IA possano leggere, e nel trattarlo come la fonte di verità su ciò che viene costruito. L'assistente lavora allora da una descrizione condivisa invece che da un'intuizione. Non è un'idea nuova, perché i buoni gruppi hanno sempre scritto i requisiti, ma l'IA cambia i conti: l'assistente trasforma una specifica chiara in codice funzionante in pochi minuti, e così la specifica diventa la parte su cui vale la pena impegnarsi.

In cosa è diverso dal "chiedere e basta"

Lavorare con richieste brevi è veloce e dà soddisfazione, e per cose piccole e usa e getta è la scelta giusta. Il suo punto debole è che l'intenzione vive in una lunga conversazione che nessuno riesce a rileggere. Due settimane dopo nessuno ricorda perché esiste una regola, e la persona che chiede all'assistente la modifica successiva può annullarla senza accorgersene.

Lavorare da una specifica ribalta la situazione. L'intenzione vive in un file conservato accanto al codice e che cambia con lui. Quando qualcosa non è chiaro, si corregge il file, non la conversazione. Quando arriva una persona nuova, o parte una nuova sessione con l'assistente, il file spiega cosa deve fare il software e perché.

Guardate come i due approcci trattano una richiesta semplice: "I clienti devono poter scaricare le proprie fatture".

• Solo richiesta: l'assistente aggiunge un pulsante di download. Funziona con l'account di prova dello sviluppatore. Se altri clienti possano scaricare le fatture di qualcun altro non è mai stato chiesto, e quindi non è mai stato deciso.
• Con una specifica: la specifica dice che un cliente può scaricare solo le proprie fatture, che una fattura mancante o altrui restituisce un semplice "non trovata", che il file prende il nome dal numero di fattura e che ogni scaricamento viene registrato. L'assistente costruisce questo e i test verificano esattamente queste regole.

Cosa contiene una buona specifica

Una specifica non deve essere lunga né formale. Per una funzione bastano una o due pagine. Conta che risponda alle domande su cui l'assistente altrimenti farebbe ipotesi. Una struttura pratica:

• Scopo. Una o due frasi sul problema e su chi lo ha. "Chi gestisce l'ufficio deve vedere quali fatture sono scadute senza chiederlo a noi."
• Utenti e permessi. Chi la usa e chi può fare cosa. È la sezione che evita gli errori più costosi.
• Comportamento in regole semplici. Le cose che devono essere vere, scritte come brevi affermazioni che chiunque può controllare. "Una fattura è scaduta quando non è pagata dopo trenta giorni dalla data."
• Esempi e casi limite. Qualche caso concreto, compresi quelli scomodi: ancora nessuna fattura, un pagamento parziale, due clienti con lo stesso nome, un elenco molto lungo.
• Criteri di accettazione. I controlli che diranno quando è finita. "Dato un cliente con due fatture scadute, la pagina le elenca entrambe, la più recente per prima."
• Fuori ambito. Cosa non fa volutamente. Scrivere "ancora niente promemoria via email" impedisce all'assistente di inventarli con zelo.
• Dati e privacy. Cosa viene conservato, per quanto tempo e cosa non deve mai comparire nei registri o nelle schermate.
• Esigenze di sicurezza. Le regole che il codice non deve infrangere: ogni richiesta limitata al cliente collegato, niente di riservato nei messaggi di errore.
• Domande aperte. Ciò che ancora non sapete. Un elenco onesto vale molto più di un'ipotesi presentata con sicurezza.

Il metodo, passo per passo

I dettagli cambiano da un gruppo e da uno strumento all'altro, ma la forma è quasi sempre la stessa.

1. Specificare

Scrivete la specifica con chi conosce l'attività e lasciate che un assistente vi aiuti intervistandovi, individuando i vuoti e proponendo casi limite. Lo scopo non è produrre un documento ma scoprire le decisioni mancanti. Una breve sessione di domande "e se succede che…?" ne fa emergere di solito parecchie.

2. Rivedere la specifica

Prima che esista il codice, qualcuno che non l'ha scritta la legge e prova a metterla in difficoltà. C'è qualcosa di ambiguo? Contraddice un'altra funzione? Manca un permesso? Un malinteso corretto qui costa una conversazione. Scoperto dopo la costruzione, costa un rifacimento.

3. Pianificare

Trasformate la specifica in un breve piano tecnico: quali parti del sistema cambiano, in che ordine e cosa potrebbe andare storto. Chiedete all'assistente di proporlo e fatelo approvare o correggere da un tecnico. Qui conta il giudizio sull'architettura, che resta una responsabilità umana.

4. Dividere in piccoli compiti

Spezzate il piano in pezzi abbastanza piccoli da essere costruiti e letti in una sola seduta, ciascuno con i propri controlli. I pezzi piccoli rendono realistica la revisione e permettono di vedere subito quale passo ha introdotto un problema.

5. Costruire

L'assistente genera il codice per un compito alla volta partendo dalla specifica e dal piano. Poiché l'intenzione è scritta, passate molto meno tempo a rispiegare e il risultato è più coerente da una sessione all'altra.

6. Verificare con la specifica

Eseguite i controlli di accettazione, meglio se come test automatici scritti dagli esempi della specifica. Una persona legge la modifica, con particolare attenzione a permessi, denaro e dati personali. Se il risultato è sbagliato, chiedetevi prima se la specifica fosse poco chiara, prima di dare la colpa all'assistente.

7. Aggiornare la specifica

La realtà insegna sempre qualcosa. Quando scoprite che una regola era sbagliata o incompleta, correggete prima la specifica e poi il codice. Una specifica non aggiornata è peggio di nessuna, perché inganna.

Un piccolo esempio

Immaginate la richiesta di un cliente: "I clienti dovrebbero poter vedere cosa ci devono". Ecco come la specifica trasforma quella frase in qualcosa di costruibile. L'abbiamo accorciata per la pagina.

Scopo. Permettere a un cliente di vedere tutte le proprie fatture non pagate e il totale dovuto, così può pagare senza contattarci.

Chi e cosa può fare. Un cliente collegato vede solo le fatture della propria azienda. Il personale può vedere qualsiasi cliente. Un cliente non può mai vedere le fatture di un altro, nemmeno digitando un indirizzo.

Regole. Una fattura è "non pagata" finché non è saldata per intero. Il totale è mostrato per valuta e non si somma mai tra valute diverse. "Scaduta" significa non pagata da più di trenta giorni dalla data di fattura, ed è indicata con chiarezza.

Casi. Nessuna fattura: mostrare un messaggio cordiale. Pagamento parziale: mostrare il saldo residuo. Più di cinquanta fatture: mostrarle a pagine.

Accettazione. Un cliente con tre fatture non pagate vede tre righe e il totale corretto. Il numero di fattura di un altro cliente, digitato nell'indirizzo, restituisce "non trovata".

Fuori ambito. Pagamento online e promemoria via email arriveranno più avanti.

Per scriverla sono bastati dieci minuti. Ha stabilito chi può vedere cosa, come si sommano gli importi, cosa significa "scaduta" e cosa non fa parte del lavoro. Ognuno di questi punti sarebbe stato altrimenti un'ipotesi nel codice dell'assistente, e la regola sui permessi in particolare è esattamente il tipo di cosa che si perde in silenzio.

Perché oggi conta di più: il collo di bottiglia della revisione

L'IA sposta lo sforzo. Scrivere codice è diventato economico e rapido. Capire, rivedere e fidarsi di quel codice no. I gruppi che adottano gli assistenti scoprono spesso che il numero di modifiche cresce più in fretta della capacità di rivederle, così la revisione diventa il collo di bottiglia, e la qualità cala in silenzio quando chi controlla scorre in fretta.

Una specifica aiuta in due modi. Intercetta i malintesi presto, quando sono piccoli, e dà a chi rivede un riferimento: non "mi sembra ragionevole?" ma "fa ciò che dice la specifica, e nient'altro?". La seconda domanda è molto più facile e molto più affidabile.

I test sono l'altra metà della stessa idea. I criteri di accettazione scritti nella specifica possono diventare controlli automatici, così la specifica non è solo letta ma eseguita. Una modifica che infrange una regola fallisce subito, chiunque o qualunque cosa l'abbia scritta.

Non è il vecchio modo di lavorare?

La domanda è lecita. Scrivere i requisiti prima di costruire era il cuore dei metodi lenti e pieni di carta da cui molti gruppi si sono allontanati, e nessuno vuole tornare a mesi di documenti. Le differenze però ci sono.

• Il ciclo è breve. Dalla specifica al codice funzionante passano minuti o ore, non mesi, quindi imparate subito dal risultato e correggete la specifica.
• La specifica è viva. Sta nello stesso posto del codice, cambia con lui ed è abbastanza piccola da essere mantenuta.
• È proporzionata. Una piccola modifica richiede poche righe. Una modifica rischiosa una o due pagine. Nessuno scrive un documento di cento pagine.

Anche le critiche meritano rispetto. Le specifiche possono gonfiarsi e gli assistenti non sempre seguono fedelmente un documento lungo, soprattutto se è vago. Il rimedio è tenerle concrete e contenute, dividere le funzioni grandi in piccole specifiche e verificare il risultato rispetto alla specifica invece di dare per scontato che sia stata seguita.

Quando non vale la pena

La specifica ha un costo, e a volte il costo supera il beneficio.

• Esperimenti usa e getta. Se state esplorando un'idea e pensate di scartare il risultato, chiedete liberamente. Una specifica rallenterebbe proprio l'apprendimento che cercate.
• Modifiche minuscole e reversibili. Correggere un refuso o cambiare un colore non richiede un documento.
• Lavoro svolto da soli e senza conseguenze durature. Uno script personale richiede solo un'idea chiara in testa.

Il criterio che usiamo è semplice: se costruire l'interpretazione sbagliata significherebbe un rifacimento serio, o toccherebbe permessi, denaro o dati personali, scrivete la specifica. Altrimenti tenetela leggera. La profondità della specifica deve seguire il costo di un malinteso.

Come cominciare in una piccola azienda

Non servono uno strumento nuovo né un nuovo reparto. Un buon primo passo è un piccolo esperimento.

• Scegliete una funzione vera, di dimensione media e non critica per l'attività, e scrivete la sua specifica in un semplice file di testo conservato col codice.
• Concordate un modello semplice. I titoli elencati sopra sono un buon inizio. Evitate di aggiungerne finché non ne sentite il bisogno.
• Fate rivedere la specifica da qualcuno che non l'ha scritta, prima di costruire.
• Trasformate i criteri di accettazione in test e lasciate che l'assistente costruisca contro di essi, a piccoli passi.
• Misurate con onestà. Annotate quanto tempo è servito, quanto rifacimento c'è stato, quanto è durata la revisione e cosa ha sbagliato l'assistente. Confrontate con come lavoravate prima. Se ancora non avete numeri, ditelo e cominciate a raccoglierli.
• Correggete, poi estendete alla funzione successiva. Lasciate crescere il modello solo dove si dimostra utile.

Diversi strumenti sostengono ormai questa pratica: alcuni aiutano a strutturare la specifica, altri eseguono la realizzazione a partire da essa. Gli strumenti contano meno dell'abitudine, e l'abitudine può partire da un file di testo e da una revisione.

Cosa significa se siete il cliente

Se commissionate un software, lavorare per specifiche è una buona notizia, perché rende il progetto più comprensibile e più controllabile. Potete leggere la specifica, nella vostra lingua, e dire "sì, è quello che intendevo" oppure "no, non è giusto" prima di spendere denaro per costruire la cosa sbagliata. Rende chiaro l'ambito, quindi è più facile concordare cosa è incluso e cosa no e giudicare se un preventivo è realistico. E vi dà un criterio di accettazione: i controlli scritti nella specifica sono il modo di decidere che il lavoro è finito.

Rende anche il software più facile da mantenere a distanza di anni. Il ragionamento dietro le decisioni sopravvive nel documento, invece che nella memoria di chi c'era in quel momento.

Come lo usiamo noi

Costruiamo il nostro software con assistenti di IA e scriviamo specifiche per tutto ciò che tocca permessi, denaro o dati personali. Per le piccole modifiche restiamo leggeri: poche righe nel compito stesso. Rivediamo la specifica prima della realizzazione, verifichiamo il risultato rispetto a essa e la aggiorniamo quando impariamo qualcosa. Non abbiamo misurato quanto questo ci renda più veloci o più lenti rispetto ad altri modi di lavorare, e preferiamo dirlo piuttosto che citare un numero che non possiamo sostenere. Possiamo dirvi che ha reso le nostre revisioni più serene e i passaggi di consegne più chiari.

Se avete un'idea per un'applicazione e volete vedere com'è fatta una prima specifica prima di impegnarvi in qualsiasi cosa, la scriviamo volentieri insieme a voi. Spesso è l'ora più utile di tutto il progetto.

Domande frequenti

Foto: Lucas Kepner su Unsplash