La knowledge base che il tuo agente AI può davvero usare

La documentazione scritta per le persone non funziona con gli agenti

Quasi tutta la documentazione di progetto è scritta per persone che leggono in diagonale. Un README dà una visione d'insieme. Una pagina di wiki copre un argomento con abbastanza contesto da far orientare chi è appena arrivato. Un documento di architettura descrive il sistema a un livello di astrazione che aiuta chi sviluppa a prendere decisioni.

Gli agenti AI non leggono in diagonale. Interrogano. Cercano un'informazione precisa per portare a termine un compito preciso. Un documento di duemila parole che racconta la storia di una decisione architetturale non serve: serve il riassunto di tre frasi che dice cosa è stato deciso e perché.

Non significa che devi buttare via la documentazione che hai. Significa che la conoscenza che esponi al tuo agente va strutturata in modo diverso da quella che scrivi per i colleghi.

Cosa rende buono un Documento

Un Documento è l'unità atomica di una knowledge base. Ognuno dovrebbe rispondere a una sola domanda ben definita. Non "come funziona il progetto" ma "che database usiamo e perché". Non "chi sono i nostri utenti" ma "quali sono le tre personas e cosa interessa a ciascuna".

I Documenti che di solito sono più utili a un agente:

• Decisioni architetturali con la loro motivazione. Non solo "usiamo PostgreSQL" ma "usiamo PostgreSQL perché ci serve consistenza transazionale fra la tabella degli ordini e quella del magazzino: non cambiarlo senza parlarne con il team".
• Vincoli operativi. Le cose che l'agente non deve mai fare, o deve sempre fare, quando lavora sul progetto. Convenzioni sui file, regole di denominazione, comportamenti che cambiano da un ambiente all'altro.
• Concetti di dominio. Il vocabolario che il tuo progetto usa e cosa significa esattamente ogni termine. "Un Workspace in Meridiaan è un contenitore di Documenti, con una propria chiave API e un proprio endpoint MCP. Non è un team."
• Cambiamenti recenti. Cosa è stato costruito o deciso da poco e che l'agente non dedurrebbe dal solo codice. Serve a tenerlo orientato senza costringerlo a leggere la storia del repository.

L'approccio incrementale batte quello esaustivo

La tentazione, quando si mette in piedi una knowledge base, è scrivere tutto in anticipo. Documentare l'intero progetto prima che l'agente lo tocchi. Il risultato è uno di due: o passi giorni a scrivere documentazione prima di poter cominciare a lavorare, oppure butti giù una prima stesura grezza, troppo incompleta per essere utile, e poi abbandoni tutto.

Meglio procedere per aggiunte. Comincia dalle tre o quattro cose su cui è più probabile che un agente inciampi la prima volta che lavora sul tuo progetto. Aggiungi Documenti man mano che ti accorgi che l'agente dà per buone cose sbagliate. Quando una decisione cambia, aggiorni il Documento che la riguarda. Quando emerge un vincolo nuovo, aggiungi un Documento.

Una knowledge base che cresce insieme al progetto è più accurata di una scritta tutta in una volta. Riflette quello che conta davvero, non quello che sembrava importante prima di cominciare.

Non serve solo a chi sviluppa

La stessa knowledge base che aiuta il tuo agente di sviluppo è utile da subito a ogni altro strumento AI che il team usa. Chi si occupa di marketing e chiede al proprio assistente come è posizionato il prodotto, chi risponde alle domande dei clienti, chi deve riassumere lo stato del progetto: tutti attingono alla stessa fonte di verità.

Quando la conoscenza è centralizzata e interrogabile, il costo di tenere tutti allineati crolla quasi a zero. Scrivi un Documento una volta. Ogni persona e ogni agente che ha bisogno di quell'informazione se la prende, nel contesto giusto, quando gli serve.

È questo che separa una knowledge base che gli agenti riescono davvero a usare da una che sta lì a marcire.