Come scrivere un brief per uno sviluppatore: requisiti, vincoli e criteri di accettazione

Due sviluppatori che ricevono lo stesso brief vago produrranno due preventivi incomparabili, perché ognuno ha riempito i vuoti con le proprie ipotesi. Il brief serve a ridurre le ipotesi: non a descrivere la soluzione, ma a definire il problema, i vincoli e come si capirà che il lavoro è finito. Lo scrivo da chi i brief li riceve ogni settimana, soprattutto dalle agenzie.

Problema, non soluzione

L'errore più frequente è un brief che descrive l'implementazione: «serve un plugin che faccia X», «vogliamo un'app». Meglio partire dall'obiettivo misurabile e dal contesto: chi usa il sistema, che problema ha oggi, cosa deve succedere dopo. La soluzione tecnica è il lavoro dello sviluppatore, e un brief che la impone spesso impone quella sbagliata.

Le sezioni che servono

Contesto e obiettivo

Chi è il cliente finale (se scrive un'agenzia), che attività svolge, perché il progetto nasce adesso. Un obiettivo verificabile: «ridurre le richieste telefoniche sugli orari», non «migliorare la comunicazione».

Utenti e ruoli

Chi userà il sistema e con quali permessi: visitatori, clienti registrati, redattori, amministratori. Ogni ruolo in più è complessità in più, ed è bene saperlo subito.

Requisiti funzionali, con priorità

Elenco delle funzioni, divise in indispensabili, importanti e desiderabili. Questa divisione permette di stimare un perimetro minimo e di ragionare per fasi invece che per tutto o niente.

Requisiti non funzionali

Sono quelli che mancano quasi sempre e che generano le discussioni a fine progetto:

• obiettivi di prestazione (per esempio Core Web Vitals «buoni» sui template principali);
• livello di accessibilità (WCAG 2.1 AA o 2.2 AA);
• lingue e gestione delle traduzioni;
• browser e dispositivi supportati;
• requisiti di sicurezza e privacy, inclusi i dati personali trattati.

Sistemi esistenti e integrazioni

Cosa c'è già: sito, hosting, dominio, gestionale, CRM, piattaforma di pagamento. Per ogni integrazione: esiste un'API documentata? Chi fornisce l'accesso? C'è un ambiente di prova? Un'integrazione senza documentazione è la prima fonte di sforamento dei tempi.

Contenuti e materiali

Chi fornisce testi, immagini, traduzioni, e quando. Se il design esiste, in che formato e con quale grado di completezza: un file Figma con componenti e stati è un'altra cosa rispetto a tre schermate statiche (ne parlo in Da Figma a WordPress).

Tempi, budget, decisioni

Scadenze reali e il motivo (un evento, una campagna), una forbice di budget, e chi approva. Un solo referente che decide accorcia i progetti più di qualunque scelta tecnica.

Proprietà e consegna

Di chi è il codice, dove vive il repository, chi detiene gli account (hosting, dominio, store), cosa si consegna a fine lavoro: documentazione, accessi, ambiente di staging.

Criteri di accettazione

Come si stabilisce che il lavoro è concluso. Per ogni funzione indispensabile, una frase verificabile: «l'utente registrato vede solo le proprie prenotazioni», «il modulo invia la richiesta e mostra conferma anche senza JavaScript». Sono il contratto tecnico tra le parti.

Un modello

• Contesto e obiettivo misurabile: …
• Utenti e ruoli: …
• Funzioni indispensabili / importanti / desiderabili: …
• Requisiti non funzionali (prestazioni, accessibilità, lingue, sicurezza): …
• Sistemi esistenti e integrazioni, con documentazione: …
• Contenuti e design disponibili: …
• Scadenza e motivo: …
• Budget (forbice): …
• Referente che decide: …
• Proprietà del codice e degli account: …
• Criteri di accettazione: …

Come leggere le risposte

Un buon preventivo restituisce il brief con domande, ipotesi esplicite ed esclusioni. Diffiderei di chi risponde in un'ora con una cifra secca su un progetto complesso: non ha letto, o ha riempito i vuoti a modo suo. Il confronto tra preventivi ha senso solo se le ipotesi sono le stesse.

Gli errori più comuni

• Descrivere la soluzione invece del problema: «serve un plugin», «serve un'app», senza dire per fare cosa.
• Nessuna priorità: tutte le funzioni sembrano indispensabili, e la stima diventa un tutto o niente.
• Requisiti non funzionali assenti: velocità, accessibilità e lingue scoperte a fine progetto.
• Integrazioni date per scontate: «si collega al gestionale», senza sapere se il gestionale ha un'API.
• Contenuti «in arrivo»: testi e immagini che arrivano a progetto finito e cambiano il layout.
• Troppi decisori: ogni revisione apre un nuovo giro di opinioni.
• Budget taciuto: lo sviluppatore propone una soluzione fuori scala, in un senso o nell'altro.
• Scadenze senza motivo: una data arbitraria impedisce di ragionare per fasi.

Se il progetto è ancora vago, la scelta più onesta è una fase di analisi separata e pagata, che produce il brief e una stima affidabile. Costa poco rispetto al progetto e riduce molto il rischio di entrambe le parti.

Come la vedo io

Il brief migliore che ricevo è quello che ammette ciò che non sa. Lavorando soprattutto con agenzie, preferisco un documento breve con obiettivi e vincoli chiari a un capitolato lungo che descrive già la soluzione. Poi lavoro per anteprime: ogni settimana una versione online consultabile (con Netlify ogni modifica ne genera una), così il brief si verifica sul prodotto vero e non sulla carta.

E chiedo sempre di mettere per iscritto proprietà del codice e degli account: non per sfiducia, ma perché è la domanda che, fatta tardi, crea più problemi.

Un brief onesto, per me, vale più di un capitolato perfetto.

Perché affidarlo a me

Programmo dal 1999, ho consegnato più di 300 progetti e lavoro come sviluppatore esterno con circa 30 agenzie, da Roma e da remoto. Rispondo a un brief con domande, ipotesi esplicite e una stima per fasi, non con una cifra secca.

Se hai un progetto da impostare, scrivimi: in una chiacchierata di circa 20 minuti trasformiamo l'idea in un brief che regge. Il servizio è in Sviluppo software su misura.