Sviluppo guidato dalle specifiche per progetti di IA

L’IA rende molto piu facile produrre codice rapidamente. Rende altrettanto facile produrre rapidamente il codice sbagliato. Per questo motivo lo sviluppo guidato dalle specifiche e piu importante, non meno importante, nei progetti assistiti dall’IA.

Quando un team sviluppa senza una specifica chiara, il prodotto si allontana col tempo dal suo scopo. Quando l’IA partecipa al processo, questo scostamento puo verificarsi in un solo pomeriggio. Il codice puo compilare, l’interfaccia puo apparire curata e i test possono perfino passare. Il prodotto puo comunque essere sbagliato.

Perché l’IA cambia il profilo di rischio

L’IA accelera il ritmo dell’interpretazione. Un solo prompt puo produrre architettura, testo, validazione, naming e flusso utente. Questo e utile, ma anche pericoloso quando la fonte della verita non e abbastanza chiara.

In pratica l’IA tende spesso a ottimizzare cio che in quel momento e piu visibile:

• l’ultimo prompt
• il file piu vicino
• il percorso implementativo piu facile
• il modello generico piu noto

Nulla di tutto questo equivale automaticamente alla giusta decisione di prodotto.

Sono scorciatoie utili per la generazione. Ma non sostituiscono il giudizio di prodotto.

Cosa fa una buona specifica

Una buona specifica svolge almeno quattro funzioni:

• definisce lo scopo
• fissa i confini
• stabilisce lo standard di revisione
• funge da memoria del team

Primo, definisce lo scopo. Il team può capire se una funzionalità sostiene il prodotto reale o aggiunge semplicemente output.

Secondo, definisce i confini. Chiarisce che cosa è nell’ambito, che cosa è fuori ambito, che cosa è opzionale e che cosa deve funzionare anche quando i sistemi opzionali falliscono.

Terzo, definisce lo standard di revisione. Invece di chiedersi solo se una modifica funziona tecnicamente, i revisori possono chiedersi se corrisponde al flusso di lavoro previsto e agli impegni di prodotto.

Quarto, agisce come memoria. I sistemi di IA non mantengono da soli una memoria istituzionale stabile. Una specifica nel repository sì.

Questo e molto chiaro in Let Books. AGENTS.md sottolinea piu volte che il flusso manuale deve restare utile anche senza servizi di IA a pagamento e che le copie fisiche dei libri non sono la stessa cosa dei record bibliografici. Questi non sono dettagli tecnici, ma confini di prodotto.

Non sono dettagli di implementazione. Sono confini di prodotto. Se un assistente IA genera un flusso che blocca l’inserimento manuale o fonde i dati della copia fisica nei metadati dell’edizione, il problema non è lo stile. Il problema è la deriva di prodotto.

Perché la documentazione non deve aspettare

Se la documentazione e vecchia o poco chiara, persone e strumenti diversi ricaveranno prodotti diversi dallo stesso repository. Uno seguira la demo, un altro un vecchio README, un altro ancora il file piu vicino.

Senza documentazione aggiornata:

• i prompt diventano incoerenti
• la revisione diventa soggettiva
• le demo iniziano per errore a ridefinire il prodotto
• i futuri collaboratori ereditano comportamenti senza sapere se fossero intenzionali

Per questo la documentazione non e solo una spiegazione successiva. E parte del sistema operativo del progetto. In questo repository README.md descrive lo stato attuale, AGENTS.md l’intento di prodotto, AGENTS-Implementation.md le regole tattiche e docs/ le regole di pubblicazione e tracciabilita.

Il ruolo delle demo

Una demo e utile perché mostra cosa esiste e rivela problemi nel flusso utente. Non dovrebbe però diventare in silenzio la specifica di prodotto.

Le regole del repository distinguono gia tra specifiche e documentazione canoniche da una parte e stato di implementazione dall’altra. Se una demo rivela un flusso migliore, vanno aggiornate specifica e documentazione, invece di lasciare che la demo vinca da sola.

Se una demo rivela un flusso di lavoro migliore, la risposta non è lasciare che vinca in silenzio. La risposta è aggiornare la specifica, la documentazione e lo standard di revisione in modo che quel flusso migliore diventi intenzionale.

Markdown, test e CI formano una catena

In uno sviluppo guidato dalle specifiche questi livelli non stanno separati.

• Markdown conserva l’intento in forma revisionabile.
• La documentazione spiega come interpretarlo.
• I test verificano aspettative eseguibili.
• Le regole di validazione catturano la deriva strutturale.
• La CI applica le regole in modo regolare.

Insieme creano una memoria di prodotto che sopravvive alla velocita di sviluppo.

Ogni livello è incompleto da solo. Insieme creano una memoria di prodotto che sopravvive a velocità, iterazione e cambi di team.

Cosa significa questo per i team che usano l’IA

I team che usano bene l’IA non eliminano il processo. Spostano il processo piu vicino alla fonte della generazione.

Di solito questo significa:

• scrivere specifiche di prodotto piu chiare prima di chiedere l’implementazione
• mantenere esplicite le linee guida di implementazione
• aggiornare la documentazione quando cambia il comportamento del prodotto
• verificare i demo rispetto alle specifiche invece di presupporre la parita
• aggiungere gradualmente regole di validazione, in modo che la coerenza non dipenda solo dalla memoria umana

Questo non e anti-IA. E il modo in cui l’IA diventa affidabile.

La lezione durevole

L’IA puo produrre rapidamente codice, contenuti e interfacce. Da sola non puo garantire che tutti questi output descrivano ancora lo stesso prodotto.

Lo sviluppo guidato dalle specifiche e il modo con cui un team impedisce che la velocita si trasformi in deriva.

Nei progetti assistiti dall’IA, la specifica non e burocrazia a posteriori. E il confine, la memoria e lo standard di revisione che rendono affidabile una consegna veloce.

Letture correlate

• ../../wiki/spec-driven-development.md
• ../../wiki/validation-layers.md
• ai-as-an-oracle.md
• spec-driven-development-in-let-books.md