Specifica prima del codice: un documento vivo con confini a tre livelli

Perché scrivere una specifica prima di costruire: obiettivo, comandi, struttura, test, confini a tre livelli e un flusso a fasi con un controllo per ciascuna.

Metodologiametodologiaspecificherequisitiingegneria del software19 novembre 2026 · 3 min di lettura

"È ovvio che cosa va costruito" è la frase che precede molte revisioni a fine progetto. Scrivere una specifica prima di iniziare non è burocrazia: è il momento in cui scopri che due persone, convinte di aver capito, avevano capito cose diverse.

Un flusso a fasi con un punto di controllo ciascuna

Fase 1, specificare. Si scrive che cosa si costruisce e perché. Fase 2, pianificare. Si decide come, con quali scelte architetturali. Fase 3, scomporre. Si divide il lavoro in attività verificabili. Fase 4, realizzare. Si costruisce un'attività per volta. Non si passa alla fase successiva finché la precedente non è stata rivista da chi decide.

Che cosa contiene una specifica

Sei elementi, in poche pagine:

  1. Obiettivo. Che cosa si costruisce e perché, per chi, e che cosa significa che è riuscito.
  2. Comandi. I comandi completi con le opzioni per costruire, provare, avviare: non solo i nomi degli strumenti.
  3. Struttura del progetto. Dove vive il codice, dove i test, dove la documentazione.
  4. Stile del codice. Un esempio reale vale più di tre paragrafi di descrizione: nomi, formattazione, convenzioni.
  5. Strategia di test. Quale framework, dove stanno i test, che copertura ci si aspetta, quali livelli di test per quali rischi.
  6. Confini a tre livelli. Che cosa si fa sempre, che cosa si chiede prima, che cosa non si fa mai.

Si aggiungono i criteri di successo (condizioni verificabili) e le domande aperte, finché qualcuno non le chiude.

I confini a tre livelli

Sono la parte che più spesso manca e che più spesso salva. "Sempre" sono le azioni sicure da fare senza chiedere (eseguire i test prima di consegnare). "Chiedi prima" sono quelle con conseguenze (modificare lo schema dei dati, aggiungere una dipendenza). "Mai" sono quelle vietate (scrivere segreti nel repository, toccare la produzione). Un collaboratore, umano o agente, sa così dove può muoversi da solo.

Una specifica viva

La specifica non si scrive una volta e si archivia. Quando una decisione cambia, si aggiorna il documento; quando il codice diverge, si decide quale dei due ha ragione. Una specifica ferma al primo giorno diventa un'altra fonte di errori.

Le scuse più comuni

ScusaRealtà
"È una modifica piccola"Le modifiche piccole con requisiti ambigui sono quelle che tornano indietro. Basta una specifica corta.
"È ovvio che cosa serve"Se è ovvio, scriverlo costa dieci minuti. Se non lo è, hai appena trovato il problema.
"Intanto comincio, poi vedo"Va bene per esplorare, non per consegnare: si butta via il codice di esplorazione.

Segnali d'allarme

  • Si scrive codice senza alcun requisito scritto.
  • Si chiede "posso iniziare?" prima di aver chiarito che cosa significa "finito".
  • Si realizzano funzionalità che non compaiono in nessuna specifica o elenco di attività.
  • Decisioni architetturali prese e non documentate.
  • Specifica saltata perché "è ovvio".

Un esempio

Una richiesta: "aggiungi l'esportazione dei report". Una specifica di mezza pagina chiede: in quale formato, per chi, con quali dati, entro quanto tempo deve arrivare il file, chi può esportare. Due righe sui confini: sempre filtrare per i permessi dell'utente, chiedi prima di includere dati personali, mai esportare l'archivio completo. Le risposte cambiano la soluzione prima che esista una riga di codice.

Quando usarla

All'inizio di un progetto, di una funzionalità o di una modifica significativa quando non esiste una specifica, i requisiti sono ambigui o esistono solo come idea.

Questo metodo deriva dalla famiglia di skill open source agent-skills di Addy Osmani (licenza MIT), riscritta e adattata.

Questo articolo è una skill di OIAR

Quello che hai letto è il contenuto di una skill del catalogo OIAR, scritto per le persone. Una conoscenza come questa ma più ricca e profonda, scritta per gli agenti, guida le interviste, l'analisi e il report dentro la piattaforma. Le skill si usano in OIAR: per provarla su un tuo progetto serve un account.

spec-driven-developmentMetodo per scrivere una specifica breve e viva prima di costruire: obiettivo, comandi, struttura, stile, strategia di test, confini a tre livelli (sempre, chiedi prima, mai), criteri di successo, domande aperte; flusso a fasi specificare, pianificare, scomporre, realizzare. Usarla all'inizio di un progetto o di una funzionalità senza specifica, o con requisiti ambigui.