Specifica tecnica di un'app: come scriverla, esempio e template

Una specifica tecnica è il documento che descrive come verrà costruita un'applicazione: ambito, requisiti funzionali e non funzionali, architettura, stack tecnologico, interfacce, milestone e criteri di qualità. Trasforma un'idea in qualcosa che un team può stimare, costruire e testare, ed è il modo più efficace per evitare le scadenze mancate e gli sforamenti di budget che nascono da un "pensavamo intendessi altro".

Questa guida spiega cosa deve contenere la specifica tecnica di un'app, in cosa differisce da un documento dei requisiti software e da una specifica funzionale, come scrivere ogni sezione e cosa cambia quando l'applicazione include funzionalità di intelligenza artificiale. Include un template sezione per sezione e un esempio compilato, per partire da una struttura e non da una pagina bianca.

TL;DR / Punti chiave

• Una specifica tecnica risponde a tre domande per ogni funzionalità: cosa fa il sistema, quanto bene deve farlo e come verrà costruito e verificato.
• I requisiti funzionali vanno scritti come user story con criteri di accettazione; i requisiti non funzionali hanno bisogno di numeri (tempi di risposta, disponibilità, volumi di dati), non di aggettivi.
• API, flusso dei dati, stack tecnologico e modello di deployment fanno parte della specifica, non sono decisioni da rimandare al primo sprint.
• Le funzionalità di IA richiedono una sezione dedicata: fonti dei dati, metodo di valutazione, guardrail e il ruolo giuridico dell'azienda ai sensi dell'AI Act.
• Gli strumenti di IA possono produrre una bozza di specifica in pochi minuti, ma ogni requisito va comunque validato da chi possiede il prodotto e da chi lo costruirà.

Cos'è una specifica tecnica e perché è importante?

Una specifica tecnica descrive come deve essere costruita un'applicazione. Definisce l'ambito, i requisiti, l'architettura e le tecnologie coinvolte, e registra le decisioni che danno forma al prodotto. Senza una specifica chiara lo sviluppo deraglia: le scadenze slittano, il budget si esaurisce e il prodotto consegnato non corrisponde a ciò che l'azienda si aspettava.

È il progetto esecutivo di un edificio. Nessuno inizia un cantiere senza disegni, e nessuno dovrebbe iniziare uno sviluppo senza un documento che tutti hanno letto e approvato. Una buona specifica previene le incomprensioni tra stakeholder e ingegneri, mantiene il team allineato quando le priorità cambiano e offre un riferimento per ogni conversazione del tipo "questo rientra nell'ambito?".

Protegge anche il budget. Le modifiche più costose in un progetto software non nascono da problemi di ingegneria difficili, ma da requisiti scoperti tardi. La specifica anticipa quella scoperta al momento più economico, prima che il codice esista. In WWG è il primo deliverable di ogni progetto di sviluppo software su misura e spesso è il risultato di un breve proof of concept quando il rischio tecnico è alto.

In cosa differisce dal documento dei requisiti e dalla specifica funzionale?

I tre documenti si sovrappongono ma rispondono a domande diverse. Il documento dei requisiti software (SRS) dice cosa deve fare il sistema dal punto di vista dell'utente. La specifica funzionale dettaglia come si comporta ogni funzione. La specifica tecnica aggiunge come verrà costruito il sistema: architettura, stack, interfacce, ambienti e test. Nei progetti piccoli si fondono in un unico documento.

La distinzione conta quando si acquista sviluppo da un partner. Un SRS basta per chiedere una stima di massima. La specifica tecnica è ciò di cui un fornitore ha bisogno per impegnarsi su ambito, tempi e prezzo, ed è il documento su cui verrà fatta l'accettazione. Se il documento che avete dice solo cosa deve fare l'app, aspettatevi una stima con una forchetta ampia.

Cosa deve contenere la specifica tecnica di un'app?

Una specifica tecnica completa ha dieci sezioni: obiettivo e finalità, utenti e ruoli, requisiti funzionali, requisiti non funzionali, architettura e stack tecnologico, API e flusso dei dati, milestone, piano di test, deployment e manutenzione, assunzioni e domande aperte. La tabella che segue è il template che usiamo nei nostri progetti.

La lunghezza non è l'obiettivo. La specifica di un progetto da tre mesi può stare in quindici pagine; l'importante è che ogni sezione abbia una risposta, anche quando la risposta è "non applicabile, perché...".

Come si definiscono requisiti funzionali che gli sviluppatori possono costruire?

I requisiti funzionali descrivono cosa fa l'applicazione, scritti in modo che uno sviluppatore possa costruirli e un tester possa verificarli. Il formato affidabile è la user story con criteri di accettazione: chi vuole cosa, perché, e come si saprà che funziona. Frasi vaghe come "l'app deve essere intuitiva" non sono requisiti, sono desideri.

Partite dall'obiettivo. Supponiamo di costruire un'app per la consegna di cibo. Gli obiettivi principali potrebbero essere permettere ai clienti di ordinare rapidamente, offrire il tracciamento in tempo reale e consentire ai ristoranti di gestire gli ordini in modo efficiente. Ogni obiettivo si scompone in funzionalità concrete:

• I clienti possono creare un account con email o accesso social.
• L'app supporta metodi di pagamento sicuri, incluse carte e wallet digitali.
• I ristoranti possono aggiornare menu e disponibilità in tempo reale.

Poi scrivete ogni funzionalità come una storia con criteri. "Come cliente, voglio salvare più indirizzi di consegna per ordinare a casa o in ufficio" diventa verificabile quando aggiungete: un indirizzo ha etichetta, via, città e CAP; un cliente può salvarne fino a dieci; l'ultimo usato è preselezionato al checkout; eliminare un indirizzo non modifica gli ordini passati.

Descrivete flussi, interazioni a schermo e comportamento atteso per ogni ruolo (amministratore, cliente registrato, ospite, personale del ristorante) e i relativi permessi. Inserite i casi limite nello stesso punto: cosa succede se un pagamento fallisce, se un ristorante va offline a ordine in corso, se l'utente inserisce un CAP non valido. I casi limite scritti ora costano minuti; scoperti in produzione costano un rilascio.

Quali requisiti non funzionali vanno specificati?

I requisiti non funzionali definiscono quanto bene deve comportarsi il sistema, non cosa fa: prestazioni, sicurezza, scalabilità, disponibilità, compatibilità e conformità. Ognuno ha bisogno di un obiettivo misurabile, perché "veloce" e "sicuro" non si possono testare. Sono i requisiti più spesso saltati e quelli più spesso dietro un lancio fallito.

Scriveteli come obiettivi con un numero e una condizione:

• Prestazioni: la schermata iniziale si carica entro due secondi su rete 4G; la ricerca restituisce risultati entro 500 millisecondi su un catalogo di 50.000 articoli.
• Sicurezza: tutti i dati personali sono cifrati in transito e a riposo; l'autenticazione usa token a breve scadenza; l'applicazione rispetta il livello pertinente dell'OWASP Application Security Verification Standard, che il progetto OWASP pubblica come base per testare i controlli di sicurezza delle applicazioni web e come elenco di requisiti per lo sviluppo sicuro. (owasp.org)
• Scalabilità: il sistema supporta 100.000 utenti attivi mensili e 2.000 sessioni concorrenti senza degrado, e l'architettura può scalare orizzontalmente.
• Disponibilità: 99,9% di uptime mensile per il flusso d'ordine, con un obiettivo di ripristino di un'ora.
• Compatibilità: iOS 16 e successivi, Android 12 e successivi, le ultime due versioni dei principali browser desktop.
• Conformità: il GDPR richiede la protezione dei dati fin dalla progettazione e per impostazione predefinita (articolo 25), quindi minimizzazione, periodi di conservazione e base giuridica di ogni categoria di dati vanno nella specifica, non in una policy scritta dopo. (eur-lex.europa.eu)

Aggiungete il disaster recovery: cosa viene salvato, con quale frequenza, dove, e quanto tempo richiede un ripristino. Se l'applicazione gestisce pagamenti o dati sanitari, indicate gli standard aggiuntivi applicabili e chi è responsabile dell'audit.

Come si specificano stack, API, milestone e test?

La parte tecnica del documento trasforma i requisiti in un piano di ingegneria. Specificate lo stack con le motivazioni, descrivete ogni API e il flusso dei dati tra i componenti, suddividete il lavoro in milestone con deliverable e definite come ogni livello di test dimostrerà i requisiti. Sono queste quattro sezioni a permettere a un team di stimare con sicurezza.

Stack tecnologico. Elencate linguaggi, framework, database, hosting e servizi di terze parti, e spiegate perché ognuno è stato scelto. Per esempio: React Native per un client mobile multipiattaforma; Node.js con un framework tipizzato per il backend; PostgreSQL per i dati transazionali e Redis per la cache; un provider cloud con auto-scaling per l'hosting. Supporto della community, reperibilità delle competenze, scalabilità e costo di manutenzione sono i criteri che contano; la novità no.

API e flusso dei dati. Definite endpoint, formati di richiesta e risposta, autenticazione (JWT, OAuth 2.0), codici di errore, limiti di frequenza, regole di validazione e comportamento in caso di ripetizione. Descrivete come i dati si muovono tra client, backend, database e servizi esterni come pagamenti o mappe. La OpenAPI Specification è il formato standard, indipendente dal linguaggio, per descrivere le API HTTP; scrivere il contratto API in questo formato permette a frontend e backend di lavorare in parallelo sulla stessa definizione. (spec.openapis.org)

Milestone. Suddividete il progetto in fasi con deliverable chiari, per esempio: settimane 1–2 approvazione dei requisiti e design UX; settimane 3–6 servizi backend e database; settimane 7–10 frontend e integrazione delle API; settimane 11–12 test, correzioni e deployment. Aggiungete le dipendenze (il design prima del frontend, l'account del provider di pagamento prima del checkout) e una riserva per le incognite elencate nella sezione 10.

Test e quality assurance. Indicate quali livelli di test si applicano e cosa significa superarli: test unitari per le singole funzioni, test di integrazione per i componenti che lavorano insieme, test end-to-end per i percorsi principali, test di carico per gli obiettivi di prestazione e test di accettazione con utenti reali. Nominate strumenti e ambienti. Una funzione di chat, per esempio, non è finita finché non è stata provata con 10.000 messaggi simultanei tenendo l'obiettivo di latenza. Questa è la sezione che un team di QA userà per pianificare il proprio lavoro: scrivetela insieme a loro.

Deployment e manutenzione. Descrivete la pipeline CI/CD, il modello di hosting, monitoraggio e alert (crash, prestazioni, uptime), la cadenza dei rilasci, la procedura di rollback e chi si occupa dei bug dopo il lancio. Un'applicazione senza un responsabile della manutenzione accumula debito tecnico dal primo giorno.

Come si presenta un esempio compilato?

Un esempio compilato mostra il livello di dettaglio che raggiunge una buona specifica. L'estratto che segue riguarda una funzionalità dell'app di consegna cibo, il tracciamento dell'ordine in tempo reale, scritta nel formato descritto sopra. Ogni requisito ha un numero, una condizione e un modo per verificarlo; il contratto API e il test che lo dimostra stanno accanto al requisito.

Moltiplicate questo per il numero di funzionalità in ambito e avrete il corpo del documento. Gran parte del valore è nella riga "domande aperte": è lì che le conversazioni che altrimenti avverrebbero al terzo mese avvengono nella prima settimana.

Come si gestiscono le funzionalità di IA e le specifiche scritte con l'IA?

L'IA cambia la specifica in due modi. Se l'applicazione include funzionalità di IA, serve una sezione su dati, valutazione, guardrail e ruolo giuridico, perché una funzione di IA senza criteri di accettazione non può essere approvata. Se usate l'IA per scrivere la specifica, la bozza è una prima versione rapida che product ed engineering devono comunque validare.

Specificare una funzionalità di IA. Per ogni funzione basata su IA (una raccomandazione, un classificatore, un assistente) scrivete: i dati che usa e da dove provengono; la qualità attesa, espressa come valutazione misurabile su un set di test e non come "accurata"; il comportamento di riserva quando il modello non è disponibile o è incerto; i guardrail su input e output; i log necessari per spiegare una decisione in seguito; il tetto di costo per richiesta. Poi classificate la funzionalità ai sensi dell'AI Act, il Regolamento (UE) 2024/1689, i cui obblighi dipendono dal fatto che la vostra azienda sia fornitore o utilizzatore del sistema e dalla categoria di rischio del caso d'uso. (eur-lex.europa.eu) La nostra guida agli obblighi dell'AI Act per gli utilizzatori riepiloga le scadenze in vigore dal 2026.

Usare l'IA per scrivere la specifica. I modelli linguistici sono bravi a trasformare un brief strutturato in una prima bozza delle dieci sezioni, a proporre casi limite non ancora elencati e a convertire i requisiti in user story con criteri di accettazione. Sono deboli nel conoscere i vostri vincoli: il sistema legacy con cui integrarsi, il regime di conformità, il budget e il team reale. Lo schema che funziona è generare, poi rivedere ogni requisito con il product owner e il tech lead, e applicare la stessa revisione a tutto ciò che il modello ha aggiunto di sua iniziativa. Una specifica è un insieme di impegni; un modello non può prenderli al posto vostro.

Quali sono gli errori più comuni in una specifica tecnica?

Gli errori più comuni sono requisiti vaghi, requisiti non funzionali assenti, nessun controllo di versione sul documento, sviluppatori coinvolti troppo tardi, documenti troppo lunghi che nessuno legge, e casi limite e gestione degli errori lasciati fuori. Ognuno costa poco da correggere in fase di scrittura e molto una volta che il codice esiste.

• Requisiti vaghi. "User-friendly" e "veloce" non sono criteri. Definite l'aspettativa esatta e come verrà misurata.
• Ignorare i requisiti non funzionali. I team che specificano solo le funzionalità scoprono prestazioni, sicurezza e scalabilità in produzione.
• Nessun controllo di versione. La specifica è un documento vivo. Tenetela in un repository o in un wiki versionato, con un registro delle modifiche, così tutti sanno quale versione è stata stimata e quale costruita.
• Sviluppatori coinvolti troppo tardi. Coinvolgete chi costruirà il sistema mentre il documento viene scritto: individuerà requisiti irrealizzabili e lavoro di integrazione nascosto.
• Complicazione eccessiva. Il dettaglio è utile; gergo e ripetizioni no. Se una sezione non aiuta nessuno a costruire o testare, va tagliata.
• Saltare casi limite e gestione degli errori. Descrivete sempre cosa succede con input non validi, un pagamento fallito, una connessione persa o un server fuori servizio.
• Nessun responsabile per le domande aperte. Ogni incognita ha bisogno di un nome e di una data, altrimenti diventa una sorpresa.

Se un'applicazione esistente non ha alcuna specifica, la via più rapida per tornare in controllo è di solito un software audit: ricostruisce requisiti e architettura reali a partire dal codice e vi consegna il documento da cui avreste dovuto partire.

Contattateci se volete far scrivere o revisionare una specifica tecnica prima di impegnare un budget nello sviluppo.

Fonti

• OWASP Foundation, pagina del progetto Application Security Verification Standard: https://owasp.org/www-project-application-security-verification-standard
• OpenAPI Initiative, OpenAPI Specification (ultima versione): https://spec.openapis.org/oas/latest.html
• EUR-Lex, Regolamento (UE) 2016/679 (Regolamento generale sulla protezione dei dati), articolo 25: https://eur-lex.europa.eu/eli/reg/2016/679/oj
• EUR-Lex, Regolamento (UE) 2024/1689 (Regolamento sull'intelligenza artificiale): https://eur-lex.europa.eu/eli/reg/2024/1689/oj