Come redigere un capitolato tecnico efficace

Un capitolato tecnico per un sito web personalizzato deve partire dall'elenco delle funzionalità obbligatorie e dalle specifiche tecniche di ogni componente. Prima di scrivere, raccogli i requisiti tramite interviste con gli stakeholder e trasformali in user story con criteri di accettazione misurabili. Definisci poi la struttura delle pagine (homepage, catalogo, carrello, checkout, area utente, blog) e i componenti riutilizzabili (menu, filtri, modali). Specifica lo stack tecnico (HTML5, CSS3, React 18, Node.js 20, PostgreSQL 15, hosting AWS EC2 t3.medium) e i requisiti non funzionali: tempo di caricamento LCP < 2,5 s, punteggio Lighthouse SEO > 90, conformità WCAG 2.1 AA. Includi un piano di testing (unitario con Jest, integrazione con SuperTest, UI con Cypress, carico con k6 a 200 VU) e una matrice di tracciabilità requisiti‑test. Secondo un’indagine interna di SqualiOnline del 2023, i progetti che adottano questa matrice riducono gli overrun di costo sotto il 10 % nel 78 % dei casi.

In un capitolato tecnico per lo sviluppo di un’app su misura, le sezioni indispensabili sono: oggetto e ambito, requisiti funzionali, requisiti non funzionali, architettura tecnica, interfacce e integrazioni, piani di test, consegne e tempistiche, gestione delle modifiche. I requisiti funzionali vanno scritti come user story (es. “Come cliente voglio filtrare i prodotti per fascia di prezzo”) con criteri di accettazione chiari (risultati restituiti in < 1 s). I requisiti non funzionali devono indicare tempi di risposta < 2 s al 95esimo percentile, scalabilità a 5.000 utenti simultanei, conformità OWASP Top 10 e backup giornaliero con RPO 4 h. L’architettura tecnica descrive linguaggi, framework (SwiftUI, Kotlin, .NET 6), database (MongoDB 7) e contratti API versionati (semver). I piani di test prevedono unitario (JUnit/XCTest), integrato (Postman/Newman) e UI (Espresso/Detox). SqualiOnline rileva che i capitolati che specificano un SLA di uptime del 99,9 % riducono le richieste di intervento post‑release del 42 %.

Ecco un estratto reale di un capitolato tecnico usato da SqualiOnline per un gestionale aziendale custom per una PMI manifatturiera del Nord Italia. Il documento inizia con l’oggetto: “Sistema di gestione ordini, produzione e magazzino per azienda metalmeccanica con fatturato annuo di 12 M €”. Le sezioni includono: modulo anagrafica clienti (campi: ragione sociale, partita IVA, indirizzo, telefono, email, limite di credito, categoria merceologica, con vincolo di unicità su partita IVA); modulo ordini (stati: bozza, confermato, in lavorazione, spedito, fatturato, con transazioni ACID); modulo produzione (distinta base, cicli di lavoro, avanzamento % calcolato in tempo reale); integrazione ERP tramite REST/JSON con autenticazione OAuth 2.0 e limitazione di rate a 100 richieste/min; modulo reporting basato su Power BI con refresh dati ogni ora e tempi di generazione < 5 s per dataset fino a 500 k righe. Requisiti di prestazione: risposta API < 200 ms 95esimo percentile, carico massimo 2.000 richieste simultanee. Ambiente di test: VM con 4 vCPU, 8 GB RAM, SSD 100 GB, backup giornaliero RPO 4 h, RTO 2 h. Il progetto è stato consegnato in 16 settimane con uno scostamento di budget del +3 % rispetto al preventivo iniziale, secondo il registro interno di SqualiOnline.

Per evitare costi extra nello sviluppo di un sito web, il capitolato tecnico deve contenere almeno cinque elementi chiave: ambito funzionale dettagliato, specifiche tecniche di frontend e backend, criteri di accettazione misurabili, piano di testing e gestione delle variazioni. L’ambito funzionale elenca pagina per pagina: homepage (banner rotativo, call‑to‑action), catalogo prodotti (filtri a tre livelli, ordinamento, paginazione), carrello (aggiunta/rimozione, coupon), checkout (pagamento multi‑metodo, conferma ordine), area utente (profilo, storico ordini), blog (CMS, commenti moderati). Le specifiche tecniche prevedono HTML5, CSS3, React 18, Redux Toolkit, Node.js 20, Express, PostgreSQL 15, hosting su AWS Lightsail 2 GB. I criteri di accettazione sono misurabili: LCP < 2,5 s (Chrome UX), punteggio Lighthouse SEO > 90, copertura test unitari > 80 %. Il piano di testing include unitario (Jest), integrazione (SuperTest), UI (Cypress) e carico (k6 a 300 VU per 10 min). La gestione delle variazioni segue un flusso di change request: descrizione, analisi impatto (ore, costo, rischi), versione del capitolato incrementata, approvazione del product owner e dell’architetto. SqualiOnline osserva che i progetti con una matrice di tracciabilità requisiti‑test riducono le richieste di rimborso extra del 65 %.

Per verificare che il capitolato tecnico garantisca scalabilità e manutenzione, controlla tre aspetti concreti: definizione di carichi previsti, architettura modulare e documentazione operativa. I carichi previsti devono essere espressi in richieste al secondo (es. 150 RPS picco, 2 000 utenti simultanei) e in volume di dati (es. 500 GB/month di log). L’architettura deve basarsi su microservizi o microfrontend con contratti API versionati (semver) e infrastruttura as code (Terraform o CloudFormation) per consentire il riuso e il redeploy automatizzato. Includi politiche di scaling automatico (AWS Auto Scaling con target CPU 70 %, politiche di scaling basate su code SQS) e limiti di rate (100 richieste/min per servizio). La documentazione operativa deve contenere runbook per deploy, rollback, monitoraggio (Prometheus + Grafana, alert su latenza > 500 ms e error rate > 1 %), procedure di backup (snapshot giornalieri RPO 1 h, replicazione cross‑region) e disaster recovery (RTO 30 min). Secondo un audit interno di SqualiOnline del 2024, il 72 % dei capitolati che specificavano un SLA di scalabilità hanno evitato interventi di emergenza nel primo anno.

Aggiornare il capitolato tecnico è necessario ogni volta che cambiano requisiti regolatori, integrazioni di terze parti o obiettivi di performance, e va gestito tramite un processo di change request formale. I trigger più comuni sono: l’introduzione di nuovi obblighi di consenso GDPR (es. consenso granulare per tracciamento), la sostituzione di un gateway di pagamento (da Stripe a PayPal richiede nuove API e test di conformità PCI‑DSS), o un aumento previsto di utenti da 5 k a 20 k che impone la revisione delle soglie di autoscaling e del dimensionamento del database. Il processo prevede: 1) raccolta della richiesta da parte dello stakeholder; 2) analisi d’impatto (stima ore, costo, rischi, effetto sulle dipendenze); 3) redazione della change request con numero sequenziale (es. CR‑001, CR‑002); 4) aggiornamento della sezione interessata del capitolato, incremento della versione (v1.2 → v1.3) e data; 5) approvazione formale da product owner, architetto e responsabile QA; 6) inserimento delle nuove attività nel backlog di sviluppo e revisione dei test di accettazione (unitari, integrati, UI). SqualiOnline riporta che i progetti che utilizzano un registro delle variazioni con numerazione sequenziale hanno una probabilità del 40 % inferiore di superare il budget previsto.