Documentazione tecnica: guida pratica per team SaaS

La documentazione tecnica di un sistema di IA non è una panoramica dell'architettura scritta a fine progetto. È il fascicolo controllato che spiega finalità, costruzione, dati e modelli, prestazioni, rischi, controlli e gestione delle modifiche successive al rilascio.

Per i provider di sistemi di IA ad alto rischio, l'articolo 11 dell'AI Act impone di prepararla prima dell'immissione sul mercato o della messa in servizio, mantenerla aggiornata e renderla abbastanza chiara da consentire ad autorità e organismi notificati di valutare la conformità. L'allegato IV indica i contenuti minimi. Un team SaaS deve quindi raccogliere evidenze di prodotto, engineering, dati, sicurezza, legal e qualità durante lo sviluppo, non ricostruirle durante un audit.

L'obbligo non vale automaticamente per ogni funzione IA. L'ambito dipende dalla classificazione e dal ruolo dell'azienda. Documenta prima entrambi, poi rendi il fascicolo proporzionato agli obblighi e ai rischi effettivi.

Perché conta nella pratica

Un buon fascicolo consente di verificare che i test corrispondano alla finalità prevista, collegare le risposte ai clienti a evidenze controllate e capire se una modifica a modello, dati, soglia o workflow richiede una nuova valutazione. Offre inoltre al valutatore una storia coerente invece di screenshot privi di contesto.

Collega requisiti di prodotto, diagrammi, model card, data lineage, valutazioni, registro dei rischi, test di sicurezza, supervisione umana, log, incidenti, approvazioni di release e monitoraggio post-market. Un indice centrale può puntare a queste fonti senza duplicarle.

Il lavoro supporta anche le nuove aspettative di AI governance per i vendor SaaS.

Confermare l'ambito

Stabilisci se il software è un sistema di IA, se è ad alto rischio e quale ruolo svolge l'azienda. Chi sviluppa e commercializza un sistema con il proprio nome può essere provider. Chi usa il sistema di un terzo può essere deployer, ma rebranding, modifiche sostanziali o nuove finalità possono cambiare l'analisi.

L'alto rischio può derivare dall'articolo 6(1) e allegato I per prodotti regolamentati o componenti di sicurezza, oppure da un caso d'uso dell'allegato III ai sensi dell'articolo 6(2). Le linee guida provvisorie pubblicate dalla Commissione nel maggio 2026 sono utili, ma non vincolanti.

Il regolamento (UE) 2026/1744 ha modificato anche le scadenze: le sezioni 1, 2 e 3 del capo III, incluso l'articolo 11, si applicano dal 2 dicembre 2027 ai sistemi dell'allegato III e dal 2 agosto 2028 ai sistemi dell'allegato I. Altre leggi, contratti o impegni con i clienti possono richiedere evidenze simili prima.

Non confondere questo fascicolo con gli obblighi separati dei provider di modelli di IA per finalità generali previsti dall'articolo 53 e allegato XI. Le informazioni del provider del modello sono un input; il provider SaaS deve documentare sistema completo, integrazione, finalità, controlli e prestazioni valutate.

Cosa richiede l'allegato IV

Usalo come matrice di copertura:

1. Identità e finalità: provider, nome, versione, utenti, scopo, modalità di distribuzione, interfacce, dipendenze e UI.
2. Sviluppo: metodi, componenti terzi o preaddestrati, selezione del modello, obiettivi, ipotesi e decisioni chiave.
3. Architettura: componenti, interazioni, risorse di calcolo e motivazione delle scelte.
4. Dati: origine, selezione, etichettatura, pulizia, governance, limiti e set di training, validazione, test o retrieval.
5. Capacità e limiti: metriche, accuratezza, robustezza, cybersecurity, esiti indesiderati prevedibili e degrado.
6. Test: protocolli, dati, soglie, date, versioni, risultati, fallimenti e correzioni.
7. Rischi e supervisione: risk management, mitigazioni, rischio residuo, controllo umano e istruzioni.
8. Ciclo di vita: versioni, logging, change management, manutenzione, incidenti e monitoraggio post-market.
9. Conformità: standard, specifiche, dichiarazione UE e documenti dell'organismo notificato, se richiesti.

Ogni affermazione deve condurre a una prova. Un riferimento preciso a report, metrica approvata, dataset, versione e limite residuo è verificabile; “il sistema è robusto” non lo è.

Workflow operativo

1. Creare un indice controllato

Inserisci una riga per ogni elemento dell'allegato IV: requisito, applicabilità, artefatto fonte, owner, versione, approvazione, ultimo riesame e prossimo trigger. “Non applicabile” richiede motivazione e approvazione. Accessi, cronologia e riferimenti stabili sono essenziali.

2. Assegnare le evidenze a chi le produce

Product copre finalità, utenti, contesto e usi impropri prevedibili. Engineering copre architettura, dipendenze, versioni e modifiche. Data o ML copre lineage, sviluppo, valutazioni e limiti. Security copre minacce, accessi, resilienza e vulnerabilità. Legal e compliance coprono classificazione, ruoli, mapping normativo e governo documentale. Un owner centrale coordina senza riscrivere fatti non verificati.

3. Fissare la baseline prima dei test

Definisci finalità e versione prima di accettare i risultati. Registra modelli, prompt rilevanti, fonti retrieval, feature flag, soglie, dipendenze e ambiente. Per sistemi probabilistici conserva versione del dataset, metodo, soglia di accettazione, data, risultati riproducibili e limiti.

4. Collegare rischi, controlli e test

Ogni rischio materiale deve portare a una mitigazione, un owner e una prova di efficacia. Se il controllo è umano, descrivi chi verifica, quali informazioni riceve, se può ignorare l'output, come avviene l'escalation e come se ne prova l'esecuzione.

5. Integrare il fascicolo nelle release

Ogni release sostanziale deve valutarne l'impatto documentale. Cambi a finalità, modello, dati, soglie, utenti, paesi, integrazioni, supervisione o sicurezza possono richiedere nuovi test e aggiornamenti a rischi, istruzioni e analisi di conformità.

Checklist minima

Il team deve poter recuperare: descrizione, finalità, ruolo e classificazione approvati; architettura e data flow con versioni; registro di modelli, librerie, API e dipendenze; origine e governance dei dati; piani, metriche, soglie, risultati e limiti delle valutazioni; rischi collegati a controlli e approvazioni; prove di supervisione umana; registri di sicurezza, robustezza, log, incidenti e monitoraggio; istruzioni allineate al sistema testato; cronologia delle release e documenti di conformità.

Errori comuni

Un template vuoto genera testo generico senza prove. Una model card non descrive l'intero workflow SaaS. I documenti dei vendor sono input, non sostituti dell'analisi dell'integrazione. Nascondere i limiti è meno difendibile che spiegarli con i controlli. Un calendario non basta: release, incidenti, nuovi dati, usi e novità normative attivano un riesame. Questionari clienti, pagine prodotto, istruzioni, rischi e fascicolo devono descrivere lo stesso sistema.

Esempio: screening dei candidati assistito da IA

Per una funzione che ordina candidature, il fascicolo include finalità, usi non supportati, workflow cliente, persone interessate, dati, logica di ranking, versioni, gruppi valutati, metriche, soglie, revisione umana, log, sicurezza e monitoraggio.

Se un test mostra recall inferiore per un gruppo rilevante, conserva risultato, analisi, mitigazione, nuovo test e decisione sul rischio residuo. Una modifica successiva di modello o soglia deve riaprire questi elementi.

FAQ

Ogni azienda SaaS necessita di un fascicolo dell'allegato IV?

No. Articolo 11 e allegato IV riguardano i sistemi ad alto rischio e l'obbligo principale del provider. Un fascicolo proporzionato resta utile per governance e verifiche dei clienti.

Si possono riusare documenti di engineering?

Sì, se controllati e aggiornati, con un indice che dimostra la copertura. Evita copie divergenti.

Chi deve esserne responsabile?

Un owner nominato coordina; product, engineering, ML/data, security, legal e compliance restano owner delle proprie evidenze.

Quando va aggiornato?

Quando cambiano finalità, versioni, dati, integrazioni, utenti, prestazioni, rischi, controlli o risultati di monitoraggio, prima di release sostanziali e dopo incidenti.

È disponibile il modulo semplificato per PMI?

L'articolo 11 prevede un modulo semplificato. Verifica sempre le risorse ufficiali correnti prima di usare un template. Fino ad allora, mantieni una matrice completa dell'allegato IV con evidenze proporzionate.

Fonti

• Regolamento (UE) 2024/1689, in particolare articoli 6, 9–17 e 43, e allegato IV.
• Regolamento (UE) 2026/1744 con le scadenze modificate.
• Bozza di linee guida della Commissione sulla classificazione ad alto rischio, maggio 2026.
• Linee guida della Commissione per provider di modelli di IA per finalità generali.