Come abbiamo automatizzato la documentazione con l'IA agentica

La maggior parte delle persone scatta migliaia di foto ogni anno senza riguardarle mai, almeno in gran parte. Popsa aiuta a individuare quelle che contano davvero e le trasforma in ricordi tangibili, oggetti che le persone conserveranno e sfoglieranno ancora e ancora.

Le nostre app mobile eseguono modelli di machine learning direttamente sui dispositivi dei clienti per analizzare le foto (senza caricarle nel cloud), individuare persone e momenti significativi e progettare un layout che racconti una storia. Dall’esterno sembra tutto molto semplice: ed è proprio questo l’obiettivo.

Dietro questa semplicità c’è una grande complessità: app iOS, Android e web, servizi backend che gestiscono pagamenti e evasione degli ordini, infrastrutture che gestiscono l'elaborazione delle immagini e le consegne in oltre 50 Paesi. Questi sistemi custodiscono le foto più personali delle persone ed elaborano i loro pagamenti. Devono restare affidabili e sicuri e la comprensione di come si collegano tra loro non può diventare obsoleta.

Questa comprensione "vive" nella documentazione, che spiega come i sistemi si integrano tra loro, quali sono le convenzioni e dove si trovano i confini sensibili. È ciò che permette a un team di gestire, proteggere e ampliare sistemi complessi senza dipendere dalla singola persona che ha creato ciascun componente. Tuttavia, mantenere aggiornata questa documentazione è un problema con cui ogni team di tecnici si è scontrato prima o poi; e noi non facciamo eccezione.

Ho lavorato in abbastanza team di sviluppo per sapere bene come vanno le cose. Uno dei membri del team decide che "Da oggi in poi la documentazione sarà sempre aggiornata!". Segue uno sforzo intenso. Vengono create pagine, registrate convenzioni, disegnati schemi di architettura. A volte si passa a un nuovo sistema (GitHub, Confluence, Coda), ridando slancio all'iniziativa. Per qualche settimana, magari un paio di mesi, tutto sembra funzionare alla perfezione.

Poi la documentazione inizia a deteriorarsi.

Non necessariamente perché i membri del team smettono di interessarsene, ma perché l’evoluzione del software non è lineare. Puoi assorbire decine di modifiche incrementali senza che la documentazione si disallinei troppo, ma poi esegui il refactoring del livello di autenticazione, migri a un nuovo framework o ristrutturi un’API. La documentazione era corretta quando è stata scritta, ma nel frattempo la codebase è cambiata. Ad esempio, abbiamo appena eseguito il refactoring della nostra app iOS passando da un flusso di navigazione lineare a uno basato su tab. Dopo una modifica di questa portata, intere sezioni della documentazione descrivono potenzialmente un sistema che non esiste più. In una parola: la documentazione può disallinearsi molto facilmente.

La maggior parte dei tecnici sa che questo può essere un problema; di recente, però, il nostro team si è fermato a riflettere su come affrontarlo considerando la documentazione come un sistema, anziché come un’attività da svolgere.

Un problema ricorrente

Naturalmente, non eravamo i primi a cercare di risolvere questo problema. Strumenti come Javadoc, Swagger e Doxygen generano documentazione direttamente dal codice. Sono utili, limitatamente alla loro funzione specifica (materiali di riferimento delle API, firme delle funzioni, schema degli endpoint), ma il risultato è procedurale e un po' arido. Ti dice cosa una funzione accetta e cosa restituisce, non il motivo per cui il sistema è progettato in quel modo, quali sono le convenzioni o come i vari elementi si collegano tra loro. La documentazione che si deteriora è quella scritta dalle persone: panoramiche architetturali, documenti sulle convenzioni. Un problema decisamente ricorrente.

Per anni, lo sforzo necessario per costruire qualcosa di meglio è stato maggiore di quello richiesto per aggiornare la documentazione manualmente; ma l'IA ha cambiato i termini dell'equazione. Il divario tra “vorremmo che la documentazione si gestisse in automatico” e “possiamo creare qualcosa che lo faccia” non esiste più.

Il nostro team lavora in modo rapido, scambiandosi informazioni in modo efficiente, eseguendo l'onboarding dei nuovi membri senza colli di bottiglia e mantenendo tutti allineati sul funzionamento dei sistemi. A rendere possibile tutto questo è la documentazione ad alto livello. Quando, di recente, abbiamo analizzato la nostra, qualsiasi team di tecnici si sarebbe ritrovato nel risultato: alcune parti erano aggiornate, altre descrivevano codebase vecchie di mesi e, in certi ambiti, la documentazione mancava del tutto.

Come molti team, utilizziamo sempre più agenti di coding basati sull'IA nei nostri repository, e anche questi agenti hanno bisogno della stessa cosa. Con una documentazione ad alto livello possiamo eseguire l'onboarding degli agenti nel team nello stesso modo in cui lo facciamo per i tecnici: ecco come si collegano i sistemi, ecco le convenzioni, ecco ciò che conta davvero. Ma sia gli esseri umani sia le macchine possono trovarsi penalizzati dallo stesso problema: una documentazione scritta una volta e mai più aggiornata.

Persone e macchine

È stato proprio questo secondo pubblico, gli agenti IA, a cambiare di recente il nostro modo di vedere le cose. In passato la documentazione era qualcosa che mantenevamo per comodità delle persone: qualcosa di utile ma non essenziale, che i team si sentivano in colpa a trascurare. Con l’arrivo degli agenti IA, è diventata un’infrastruttura.

Quando ci siamo resi conto che le stesse convenzioni si ripetevano in più punti, abbiamo deciso di centralizzare queste conoscenze. Oggi distribuiamo file in tutti i nostri repository principali (AGENTS.md, CLAUDE.md, .cursorrules), ciascuno generato a partire da modelli e contenente un’intestazione che rimanda al nostro repository centrale della documentazione.

Quando un agente IA inizia a lavorare su una codebase Popsa, la prima cosa che vede è un riferimento alla nostra documentazione "live". Le convenzioni, gli schemi, il glossario, le decisioni architetturali e (cosa fondamentale) le conoscenze di prodotto. Senza queste ultime, come potrebbe un agente sapere che un PBK-7 è un fotolibro orizzontale, medio, con copertina rigida o che TIL-2b è un fotoquadro nero con finitura lucida?

Questo crea un ciclo molto efficace:

• i tecnici svolgono il lavoro

• gli agenti che revisionano quel lavoro utilizzano la documentazione per fornire feedback migliori e più pertinenti al contesto

• il feedback attiva le modifiche al codice

• le modifiche aprono PR di aggiornamento della documentazione, pronte per la revisione e il merge.

La documentazione aggiornata diventa quindi disponibile per la prossima persona o il prossimo agente che si occuperà di un’attività. Il sistema si autoalimenta e l’effetto si amplifica tra repository diversi. Quando nomi di prodotto, feature flag ed eventi di analisi vengono inclusi nella documentazione centrale, quelle conoscenze diventano disponibili per agenti che lavorano su codebase completamente diverse.

Il team Android rilascia una nuova funzionalità. Quando un agente revisiona la pull request equivalente su iOS settimane dopo, ha contesto sufficiente per notare che il nome della funzionalità non coincide o che gli eventi di analisi seguono convenzioni diverse. La documentazione centrale diventa una memoria condivisa per l’intera organizzazione, non solo un riferimento per il repository a cui era inizialmente destinata.

C’è anche un aspetto legato ai costi. Senza una buona documentazione, un agente che inizia a lavorare su un repository deve imparare a conoscere la codebase da zero: cercare file, leggere codice sorgente, individuare schemi. Questo processo consuma token e richiede tempo per ogni singola interazione. Con una documentazione curata e aggiornata, all’agente basta leggere un solo file per ottenere una visione completa. Una documentazione accurata riduce il costo per interazione di ogni agente che opera nella tua organizzazione.

Come funziona

Abbiamo creato una pipeline. Il concetto è semplice, anche se i dettagli hanno richiesto una progettazione molto attenta.

Quando un tecnico esegue il merge del codice nelle nostre codebase principali (servizi backend; app web, iOS o Android; repository IaC), si attiva una Action GitHub leggera; questa Action raccoglie i percorsi dei file modificati e il riferimento di commit e invia un evento repository_dispatch al repository centrale della documentazione.

A destinazione, un altro flusso di lavoro intercetta l’evento ed esegue un’operazione mirata:

L’elemento fondamentale è che non viene rigenerata ogni volta tutta la documentazione. Un file di configurazione YAML associa ogni repository sorgente agli specifici file di documentazione sui quali può avere impatto, insieme a pattern glob che definiscono quali percorsi di file monitorare. Una modifica ai moduli Terraform non attiverà un aggiornamento della documentazione sugli standard Go, così come una modifica ai file Swift non avrà effetto sulle convenzioni TypeScript. Viene analizzata solo la documentazione effettivamente pertinente alla modifica apportata al codice.

Il flusso di lavoro attiva Claude Code con un prompt creato ad hoc. Claude legge la documentazione esistente, esplora il repository sorgente in corrispondenza della commit che ha attivato l'aggiornamento, confronta il contenuto della documentazione con ciò che il codice effettivamente fa e propone modifiche. Ancora più importante, può anche segnalare che nessuna modifica è necessaria. Il prompt è molto preciso su cosa Claude deve e non deve fare: preservare la struttura esistente del documento, usare l'inglese britannico, includere riferimenti ai percorsi di file quando cita esempi, non rimuovere contenuti ancora validi, non aggiungere contenuto speculativo. Chiediamo "modifiche chirurgiche", non "riscritture".

Ecco alcuni dettagli su come è strutturato il sistema. Il repository della documentazione non effettua polling né pianificazioni. I repository sorgente inviano eventi quando vengono apportate modifiche, il che significa che è possibile includere eventuali nuovi repository semplicemente aggiungendo un flusso di lavoro di notifica e una voce nel file di configurazione. Viene eseguito un solo aggiornamento della documentazione per repository sorgente per volta. Se viene eseguito il merge di due PR (pull request) in rapida successione, il secondo aggiornamento attende che il primo venga completato oppure rifiutato; Claude può restituire NO_CHANGES_NEEDED e la pipeline si chiude. Non tutte le modifiche al codice influiscono sulle convenzioni documentate, e il sistema lo riconosce in modo efficiente.

Un dettaglio che ci piace particolarmente è che, durante lo sviluppo, Bugbot di Cursor (un revisore di codice basato sull'IA) ha individuato sei bug nell’implementazione iniziale della pipeline. Un’IA revisiona il codice utilizzato per eseguire un’altra IA. Non è bellissimo?

Abbiamo reso la pipeline open source, così puoi adattarla ai tuoi repository.

Revisioni, non approvazioni automatiche

Anche se tutto quello che ci aiuta a lavorare più velocemente ci entusiasma, monitoriamo e testiamo questi processi con attenzione. Il flusso di auto-documentazione apre una pull request, il che significa che i tecnici possono rivederla, verificare che le modifiche proposte riflettano davvero ciò che è cambiato nel codice e valutarne la verosimiglianza ("Adesso il codice fa davvero questo?").Il nostro team può approvarla, richiedere modifiche oppure chiuderla completamente. La fase di revisione della PR fa sì che i tecnici mantengano il controllo: restiamo consapevoli di come evolve la documentazione e manteniamo famigliarità con le convenzioni. Conserviamo il controllo sulla knowledge base anche se non svolgiamo direttamente le attività di manutenzione più ripetitive.

Nell’era dell’IA, sempre di più è così che concepiamo la divisione del lavoro:

Creare il sistema è compito del tecnico, così come revisionare l’output. La parte ripetitiva nel mezzo è compito dell’IA. Analizzare un diff delle modifiche al codice sorgente, capire quali sezioni della documentazione sono interessate, scrivere i paragrafi aggiornati, eseguire il linter, aprire la PR: questo è il lavoro di dettaglio per cui oggi l’IA è davvero efficace.

Lo schema di fondo

Anche se abbiamo costruito questo sistema per migliorare la qualità della documentazione, ci siamo imbattuti in uno schema valido per il lavoro tecnico in generale. Pensa alle attività che ogni team sa essere importanti, ma di cui nessuno vuole davvero assumersi la responsabilità:

• Mantenere significativa la copertura di test man mano che il codice evolve.

• Tenere aggiornate le voci del changelog in modo che descrivano effettivamente le modifiche.

• Verificare che i contratti API corrispondano ancora alle implementazioni.

• Verificare le versioni delle dipendenze.

• Aggiornare gli Architecture Decision Record (ADR).

Tutte queste attività condividono la stessa struttura: c’è uno stato attuale e uno stato desiderato, e il lavoro consiste nel confrontare i due stati e suggerire eventuali aggiornamenti. Rivedere lo stato attuale, consultare la fonte di verità, confrontarli e produrre una modifica mirata, da sottoporre a revisione umana. È uno schema che l’IA gestisce bene, a un costo quasi nullo (una volta completata la configurazione).

Questo ci riporta al nostro punto di partenza. I nostri utenti affidano a Popsa le loro foto più intime e i ricordi relativi a persone e luoghi cari. I sistemi che rendono possibile questa esperienza devono essere compresi e gestiti e rimanere sicuri, non solo a opera di chi li ha creati, ma anche di chi ci lavorerà successivamente. A rendere possibile tutto questo è la documentazione e, per la prima volta, abbiamo un modo per mantenerla aggiornata senza che diventi un secondo lavoro per qualcuno.

Il risultato è un team che dedica meno tempo alla manutenzione della conoscenza e più tempo a migliorare l’esperienza: migliore selezione delle foto, maggiore tutela della privacy, prodotti migliori. I tecnici possono concentrarsi sul lavoro che conta davvero per le persone, anziché sulle attività di manutenzione invisibile "sotto il cofano".

È per questo che abbiamo creato il sistema. Non per la documentazione in sé, ma per quello che ci permette di fare: creare qualcosa all’altezza dei ricordi che le persone ci affidano.