Governance IA Multi-Repo

Ho passato settimane a costruire file di contesto per l'IA. Metà mentivano.

Non intenzionalmente. I file erano accurati quando li ho scritti. Poi le cose sono cambiate — aggiornamenti dello stack, migrazioni di schema, pivot di business — e nessuno ha aggiornato la documentazione.

L'IA continuava a leggere il vecchio contesto. Io continuavo a ricevere risposte sicure ma sbagliate.

La parte peggiore: non me ne sono accorto subito. I risultati sembravano ragionevoli. Gli errori erano sottili. Quando li ho scoperti, avevo già costruito sopra una base falsa.

Questo è il fallimento di cui nessuno parla. Non "l'IA ha allucinato" — non l'ha fatto. Ha letto esattamente quello che le ho dato. Il problema è che quello che le ho dato era obsoleto.

All'epoca gestivo cinque progetti in parallelo — un sito di ospitalità, un'app di gestione finanziaria, un sito aziendale, un pitch deck, un portfolio personale. Ognuno aveva il proprio contesto IA. Ognuno derivava al proprio ritmo. Non c'era alcun sistema a collegare tutto questo.

La prima cosa che ho costruito era quella sbagliata: più documentazione.

Più dettaglio, più struttura, più copertura. Ha aiutato per una settimana. Poi anche quei file hanno iniziato a derivare.

La seconda cosa che ho costruito si è avvicinata di più: una matrice di trigger. Ogni tipo di cambiamento — nuova rotta, aggiornamento di schema, nuova dipendenza, cambiamento del modello di business — mappato al documento esatto che deve essere aggiornato. Nella stessa PR. Non come follow-up. Il compito non è completo finché la documentazione non riflette la realtà.

Questo ha fermato la deriva sui singoli progetti.

Ma propagarlo su cinque repository ha esposto il problema successivo. Le regole generiche non sopravvivono al contatto con domini specifici. L'app finanziaria aveva bisogno di un documento sul modello dei dati. Il sito di ospitalità aveva bisogno di una specifica del portale. Il pitch deck aveva bisogno di un livello di affermazioni verificate — perché un investitore che chiede "da dove viene questo numero?" non è il momento di scoprire che il tuo file di contesto era ottimista.

Quello che alla fine ho capito: esistono due tipi di contesto. Contesto che appartiene a un template condiviso — regole di base, pattern architetturali, cadenza dei controlli di salute. E contesto che appartiene al repository — decisioni di dominio, anomalie dei dati, affermazioni verificate. Mescolarli rompe entrambi.

La maggior parte delle persone che incontra questo problema presume di aver bisogno di strumenti IA migliori. Quello di cui di solito ha bisogno è una migliore disciplina di manutenzione.

Il file di contesto non è documentazione. È un contratto tra te e il modello. Quando si rompe, il modello non avvisa. Continua e basta.

Se stai costruendo con assistenti IA su più di un progetto, la domanda che vale la pena porsi ora — prima che ti costi caro — è: chi aggiorna il contesto quando qualcosa cambia, e come sanno che deve essere aggiornato?

Il template è open source — link nei commenti.

---

Sources

• ai-product-architecture-template (open source, GitHub): https://github.com/gtcuco-personal/ai-product-architecture-template