17 giugno 2026Aggiornato il Fathy Shalaby13 min di lettura
Template di specifica tecnica: scrivi una spec che gli ingegneri leggono davvero
Un template di specifica tecnica da copiare, le pratiche di design doc e RFC da cui prende spunto e un metodo passo passo per scrivere una spec che gli ingegneri leggono fino in fondo.
Un template di specifica tecnica dovrebbe mettere le decisioni rischiose in prima pagina: il problema e i suoi vincoli, il design proposto, le alternative scartate e ciò che potrebbe andare storto, in una o tre pagine per la maggior parte delle modifiche. I design doc di Google e le RFC di Uber seguono questa forma. Il template da copiare qui sotto aggiunge un riassunto in una frase e una tabella delle decisioni, così chi fa la revisione trova le scelte difficili in meno di un minuto.
Punti chiave
I design doc di Google hanno cinque sezioni centrali e arrivano a 10–20 pagine per i grandi progetti, ma restano a 1–3 pagine per il lavoro incrementale (Malte Ubl, 2020).
I lettori leggono circa il 20% delle parole di una pagina web media, al massimo il 28% (Nielsen Norman Group, 2008). Le spec si leggono allo stesso modo: si scorrono in cerca delle parti che potrebbero essere sbagliate.
Il 61% degli sviluppatori passa più di 30 minuti al giorno a cercare risposte (Stack Overflow, 2024). Una spec che registra le decisioni risponde a quelle domande una volta sola.
I team con documentazione di alta qualità hanno 3,8 volte più probabilità di adottare le best practice di sicurezza (DORA, 2021).
«Alternative considerate» è la sezione di cui i revisori si fidano di più, perché mostra che hai cercato un motivo per non costruirlo così.
Che cos'è una specifica tecnica e in cosa si differenzia da un PRD?
Una specifica tecnica (detta anche design doc o documento di progettazione tecnica) spiega come un team costruirà qualcosa e quali compromessi accetta. Un PRD spiega quale problema vale la pena risolvere, per chi e come si misurerà il successo. Prima viene il PRD; la specifica tecnica ne è la risposta.
I team usano quattro documenti affini. Confonderli è il motivo più comune per cui una spec arriva a 15 pagine che nessuno finisce.
Quale problema, per chi e come sapremo che ha funzionato?
Product manager
2–5 pagine
Specifica tecnica / design doc
Come lo costruiremo e a cosa rinunciamo?
Tech lead o ingegnere
1–3 pagine (10–20 per i sistemi grandi)
RFC (request for comments)
L'organizzazione più ampia è d'accordo con questo piano prima che il lavoro inizi?
Autore più approvatori indicati
Come una spec, con una scadenza per la revisione
ADR (architecture decision record)
Perché abbiamo preso questa singola decisione e cosa ne consegue?
Ingegnere che ha deciso
1–2 pagine
La guida di Google descrive il design doc come il luogo in cui documentare la strategia di implementazione di alto livello e le decisioni di progettazione chiave, con enfasi sui compromessi. Il formato ADR di Michael Nygard, pubblicato nel 2011, lo restringe a una singola decisione in cinque parti: titolo, contesto, decisione, stato e conseguenze (Michael Nygard, 2011). Se vuoi partire dal lato prodotto, comincia dalla guida alla scrittura di un PRD.
Perché gli ingegneri saltano la maggior parte delle specifiche tecniche?
Gli ingegneri saltano le spec che rispondono a domande che nessuno ha posto e nascondono quelle che contano. Tre schemi spiegano la maggior parte dei casi.
Sono scritte per essere complete, non per decidere. L'analisi di Jakob Nielsen del 2008 ha rilevato che, su una pagina media di 593 parole, i lettori avevano il tempo di leggere al massimo il 28% delle parole, e il 20% era più probabile. Solo sulle pagine di 111 parole o meno i lettori arrivavano a metà del contenuto. Un revisore con sei spec in coda legge allo stesso modo: riassunto, diagramma, testo in grassetto, poi la sezione con cui non è d'accordo.
Nascondono la scelta rischiosa in una prosa uniforme. Se la decisione irreversibile è al nono paragrafo, ogni revisore deve ricavarla di nuovo. È proprio lo spreco che una spec dovrebbe evitare.
Diventano obsolete. La Stack Overflow Developer Survey 2024 ha rilevato che il 61% degli intervistati passa più di 30 minuti al giorno a cercare risposte e che il 30% dice che i silo di conoscenza danneggiano la propria produttività 10 o più volte a settimana. Una spec che non corrisponde più al codice diventa un'altra fonte di risposte sbagliate.
Il vantaggio di farlo bene è misurabile. La ricerca DORA del 2021 ha mostrato che i team con documentazione di alta qualità avevano 3,8 volte più probabilità di adottare le best practice di sicurezza e 2,5 volte più probabilità di sfruttare appieno il cloud.
Che cosa deve contenere una specifica tecnica?
Includi solo ciò che cambia il modo in cui qualcuno costruirebbe o revisionerebbe il lavoro. Due pratiche pubblicate offrono una buona base.
Le sezioni del design doc di Google
Il testo di Malte Ubl del 2020 sui design doc in Google elenca le sezioni che la maggior parte dei documenti ha in comune:
Contesto e ambito: l'ambiente in cui vive il sistema, in pochi paragrafi.
Obiettivi e non-obiettivi: cosa il sistema deve fare e cosa esplicitamente non farà.
Il design vero e proprio: diagramma del sistema, API, archiviazione dei dati e codice o pseudocodice solo dove chiarisce un algoritmo nuovo.
Alternative considerate: altri design e perché hanno perso.
Aspetti trasversali: sicurezza, privacy e osservabilità.
Le sezioni delle RFC di Uber
Il processo RFC di Uber è cresciuto con l'azienda, da qualche decina di ingegneri a un paio di migliaia, secondo Gergely Orosz, che ci ha lavorato (The Pragmatic Engineer, 2018). Il template per il backend si apriva con un elenco di approvatori, poi copriva modifiche all'architettura, SLA dei servizi, dipendenze, load test, aspetti multi-data-center, sicurezza, test e rilascio, metriche e monitoraggio, e supporto clienti. Il template mobile aggiungeva UI e accessibilità. Le sezioni sono state aggiunte man mano che l'azienda scopriva cosa continuava a trascurare.
La lezione di entrambi: un template di specifica tecnica è una checklist di errori passati. Parti in piccolo e aggiungi una sezione solo quando la sua assenza ha causato un problema reale.
Template di specifica tecnica (da copiare e adattare)
Questo template di specifica tecnica combina le sezioni di Google, l'abitudine di Uber di mettere gli approvatori in testa e il formato di decisione di Nygard. Elimina ogni sezione che direbbe solo «N/D».
# [Nome della funzionalità o del sistema]: specifica tecnica
**Riassunto:** Facciamo [X] per ottenere [Y], accettando il compromesso di [Z].
**Autore:** [nome] · **Approvatori:** [2–3 nomi] · **Revisione entro:** [data]
**Stato:** Bozza | In revisione | Approvata | Sostituita da [link]
**PRD / ticket collegato:** [link]
## 1. Problema e vincoli
- Cosa non funziona, chi ne risente e cosa diventa possibile una volta risolto.
- Vincoli rigidi: budget di latenza, residenza dei dati, retro-
compatibilità, lo SLA che non puoi violare.
## 2. Obiettivi e non-obiettivi
- Obiettivi (misurabili, ove possibile).
- Non-obiettivi: cose che un lettore ragionevole potrebbe aspettarsi e che non faremo.
## 3. Decisioni chiave (leggi prima questa)
| # | Decisione | Reversibile? | Rischio se sbagliata | Fiducia |
|---|----------|-------------|---------------|------------|
| 1 | | Porta a senso unico / a doppio senso | | Alta / Media / Bassa |
## 4. Design proposto
- Un diagramma. Modifiche alle API e al modello dei dati. Pseudocodice solo per
ciò che è nuovo.
## 5. Alternative considerate
- Opzione A: perché ha perso.
- Opzione B: perché ha perso.
- Non fare nulla: cosa succede se non lo costruiamo.
## 6. Rischi e domande aperte
- Ipotesi portanti e come le verificheremo.
- Domande a cui serve risposta prima o durante la realizzazione.
## 7. Aspetti trasversali
- Sicurezza e privacy · Osservabilità · Accessibilità · Costi.
## 8. Rilascio, validazione e rollback
- Feature flag / piano di rilascio graduale.
- Metriche che provano che funziona e soglia che fa scattare il rollback.
## 9. Registro delle decisioni
- [data] Modificata [decisione] perché [motivo]. (Aggiorna qui, non in un commento alla PR.)
La tabella delle decisioni della sezione 3 è la parte che dà valore al template. Segnare ogni decisione come porta a senso unico o a doppio senso dice ai revisori dove concentrare l'attenzione. Il framework delle decisioni reversibili e irreversibili spiega come giudicare quale sia quale.
Quanto deve essere lunga una specifica tecnica?
Tanto breve quanto lo permette la decisione più rischiosa. La guida di Google colloca i design doc dei grandi progetti intorno alle 10–20 pagine e ritiene adatti i «mini design doc» di 1–3 pagine per il lavoro incrementale. Gli ADR di Nygard sono di una o due pagine. Amazon sostituisce le slide con «memo di sei pagine a struttura narrativa», letti in silenzio all'inizio di ogni riunione, e Jeff Bezos ha scritto che uno davvero buono richiede probabilmente una settimana o più per essere scritto (Amazon, 2018).
Una regola pratica, in base alla dimensione della modifica:
Modifica
Formato
Lunghezza
Revisione
Correzione di un bug, modifica di un testo, ritocco di configurazione
Descrizione del ticket
Un paragrafo
Solo code review
Nuovo endpoint o componente dentro un servizio
Mini spec
1 pagina
Un approvatore, in asincrono
Funzionalità che tocca 2–3 servizi o un'API pubblica
Specifica tecnica (template qui sopra)
2–3 pagine
2–3 approvatori, finestra di 2–3 giorni
Nuovo sistema, migrazione dei dati o confine di sicurezza
Design doc completo o RFC
5–20 pagine
Riunione formale di revisione
La guida di Google dice anche quando non scriverne una: quando la soluzione è inequivocabile e il documento sarebbe solo un manuale di implementazione senza compromessi da discutere.
Come scrivi una spec che gli ingegneri leggono davvero?
Scrivila in quest'ordine. Gran parte del lavoro sta nel decidere cosa lasciare fuori.
Scrivi prima il riassunto in una frase. «Facciamo X per ottenere Y, accettando il compromesso di Z.» Se non riesci a scriverlo, non sei pronto per scrivere la spec, e nemmeno i tuoi revisori sapranno riassumerla.
Apri con il problema, non con la soluzione. Gli ingegneri non possono giudicare un design finché non conoscono i vincoli a cui risponde. Enuncia i punti non negoziabili prima del diagramma di architettura.
Compila la tabella delle decisioni. Elenca ogni decisione su cui un revisore potrebbe ragionevolmente dissentire. Metti in grassetto le porte a senso unico.
Scrivi le alternative con onestà. Includi «non fare nulla». Una spec senza opzioni scartate sembra una decisione già presa.
Indica due o tre approvatori e una scadenza per la revisione. Uber elencava gli approvatori in cima a ogni RFC. Una spec senza chi decide e senza una data tende a restare in revisione all'infinito.
Rivedi in asincrono, incontrati solo sui disaccordi. I commenti sul documento gestiscono la maggior parte del feedback. Se vi incontrate, copia Amazon e dedica i primi dieci minuti alla lettura in silenzio.
Aggiorna la spec quando la realizzazione la cambia. Nel ciclo di vita di Google il documento si rivede durante l'implementazione. Registra le modifiche nel registro delle decisioni, non in un commento a una pull request che nessuno troverà.
Orosz osserva che, una volta che il team concorda su un piano, metterlo per iscritto richiede di solito poche ore. Se ci vogliono giorni, il disaccordo è la vera scoperta.
Esempio svolto (a titolo illustrativo)
Supponiamo che un team di sei persone debba impedire che i webhook lenti dei clienti mandino in timeout il checkout. La loro frase di riassunto: «Spostiamo l'invio dei webhook su una coda in modo che il checkout non aspetti mai il server di un cliente, accettando fino a 60 secondi di ritardo nella consegna.»
#
Decisione
Reversibile?
Rischio se sbagliata
Fiducia
1
Passare alla consegna at-least-once; i clienti devono deduplicare per ID evento
Porta a senso unico (contratto pubblico)
Ordini duplicati nei sistemi dei clienti
Media
2
Usare il database Postgres esistente come coda invece di un nuovo broker
Porta a doppio senso
Tetto di throughput nei picchi; migrare più avanti
Alta
3
Riprovare cinque volte in 24 ore, poi segnare come fallito
Porta a doppio senso
Alcuni clienti perdono eventi durante interruzioni lunghe
Alta
I revisori vedono in 30 secondi che la decisione 1 merita il dibattito: cambia un contratto API pubblico, richiede una nota di migrazione per i clienti e non si può annullare in silenzio. Le decisioni 2 e 3 si possono approvare con un commento.
Quali sono gli errori più comuni con le specifiche tecniche?
Scrivere la spec dopo il codice. Una spec scritta per giustificare una pull request già finita non ha alternative e non intercetta nulla.
Cinque diagrammi invece di uno. Un diagramma del sistema con la modifica evidenziata batte cinque che mostrano tutto.
Trattare il template come un modulo. Le sezioni «N/D» vuote insegnano ai lettori a scorrere. Eliminale.
Nessun responsabile per le domande aperte. Ogni domanda aperta ha bisogno di un nome e di una data, altrimenti diventa un incidente in produzione.
Congelare il documento. Una spec che non corrisponde più alla realizzazione è peggio di nessuna spec, perché la gente ci crede.
Usare una spec dove un prototipo risponderebbe più in fretta. Se la domanda rischiosa è «questa libreria reggerà il nostro carico?», uno spike di un giorno batte cinque pagine di argomentazioni.
Come cambiano le specifiche tecniche con gli agenti di coding AI?
Gli agenti di coding leggono le spec alla lettera. L'ambiguità che un ingegnere umano risolverebbe su Slack diventa codice che un agente scrive sbagliato con grande sicurezza. Le parti del template che contano di più per un agente sono i non-obiettivi, i vincoli e i criteri di accettazione verificabili. Il template di PRD per agenti di coding AI mostra come renderli espliciti. Una volta approvata la spec, il passo successivo è scomporre il PRD in user story, e una pre-mortem di lancio mette alla prova il piano di rilascio prima della release.
Dove si inserisce Specky?
Il divario tra intento documentato e realtà rilasciata si apre di solito quando requisiti, decisioni e ticket vivono in strumenti diversi. Specky redige i PRD in un editor con citazioni in linea che rimandano alle evidenze dei clienti, genera ticket con criteri di accettazione verificabili e registra le decisioni in un Product Graph perché il «perché» resti legato al lavoro. Gli agenti di coding possono leggere quel contesto tramite un server MCP. Il design tecnico lo scrive sempre l'ingegnere; il contesto di prodotto intorno resta aggiornato. Se trovare il tempo per scrivere è il collo di bottiglia, l'esempio di settimana di un PM protegge un blocco di concentrazione per farlo.
Domande frequenti
Qual è la differenza tra un PRD e una specifica tecnica?
Un PRD definisce il problema, gli utenti e come si misurerà il successo; una specifica tecnica definisce come il team costruirà la soluzione e quali compromessi accetta. Di solito il PRD è del product manager e la spec del tech lead. Scrivi prima il PRD e poi collegalo dalla spec, così i revisori possono confrontare il design con l'obiettivo originale.
Chi dovrebbe scrivere la specifica tecnica?
La specifica tecnica dovrebbe scriverla l'ingegnere o il tech lead che sarà responsabile della realizzazione, con il product manager che la rivede rispetto al PRD. L'autore risponde delle decisioni, non del fatto di digitare ogni sezione. In un team piccolo, il PM può abbozzare le sezioni su problema, obiettivi e non-obiettivi, e l'ingegnere completa design, alternative e piano di rilascio.
Quanto deve essere lungo un documento di progettazione tecnica?
La maggior parte dei documenti di progettazione tecnica dovrebbe essere di una o tre pagine. Nella pratica di Google i mini design doc di 1–3 pagine sono normali per le modifiche incrementali e le 10–20 pagine sono riservate ai grandi sistemi nuovi. Se la tua spec supera le tre pagine per una funzionalità dentro servizi esistenti, probabilmente mescola più decisioni che dovrebbero essere ADR separati.
Che cos'è una RFC nell'ingegneria del software?
Una RFC (request for comments) è un piano scritto condiviso con l'intera organizzazione di ingegneria prima dell'inizio del lavoro, perché gli altri possano segnalare i rischi. Uber ha usato le RFC mentre passava da qualche decina a un paio di migliaia di ingegneri, elencando in cima a ciascuna gli approvatori per nome. Una RFC è una specifica tecnica più un processo di revisione, una scadenza e chi decide.
Quando non bisogna scrivere una specifica tecnica?
Salta la spec quando la soluzione è inequivocabile e non ci sono compromessi significativi da discutere, che è la linea tracciata dalla guida di Google. Correzioni di bug, piccole modifiche all'interfaccia e aggiornamenti di configurazione vanno in un ticket. Se la principale incertezza è la fattibilità tecnica, fai prima uno spike a tempo limitato e scrivi la spec quando sai cosa funziona.
Che cos'è un architecture decision record (ADR)?
Un ADR è un documento di una o due pagine che registra una singola decisione architetturale. Il formato di Michael Nygard del 2011 ha cinque parti: titolo, contesto, decisione, stato e conseguenze. Molti team tengono gli ADR nel repository del codice, così i futuri ingegneri vedono perché qualcosa è stato costruito in un certo modo. Usa gli ADR per le decisioni che sopravvivono a una singola spec.
GDPR-aligned. EU workspace data is stored in Frankfurt, Germany. GDPR and EU data Built in Vienna, Austria. A product of influence solutions fm GmbH (FN 675374y). Imprint 14-day trial. Card required, and nothing is charged until day 14. 30-day refund after subscribing. See pricing