Architettura wiki: framework interno di knowledge management AI-maintained per applicazioni di assistenza tecnica industriale

Contesto

Dopo aver lavorato su un paio di progetti di assistente AI per PMI manifatturiere, ho capito che il pattern di lavoro era sempre lo stesso: c'è un corpus di conoscenza aziendale stratificata — catalogo prodotti, manuali tecnici, regole di business, FAQ storiche — che vive frammentato tra gestionale, PDF, head di poche persone esperte, fogli Excel. Il lavoro dell'assistente AI non è "rispondere", è comporre: leggere da fonti disomogenee, organizzare in uno strato intermedio leggibile, mantenerlo coerente nel tempo, citare sempre la fonte, non allucinare quando un dato non c'è.

A forza di incontrare sempre le stesse scelte architetturali ho formalizzato un framework interno che uso come punto di partenza su ogni nuovo progetto di questo tipo.

Sfida

Evitare di ricostruire ogni volta da zero l'infrastruttura noiosa (ingest pipeline, tool contract, citation schema, queue di review, FAQ memoization, editor per il cliente, log persistenti), concentrando il lavoro sul valore verticale del singolo progetto (lo schema delle regole di dominio, l'adattamento alla fonte cliente). Senza cadere nella trappola opposta: un framework che diventa un mini-prodotto software da manutenere — non è il mio obiettivo.

Approccio

Il framework è documentato in un file PATTERN.md di riferimento e in una skill Claude Code (~/.claude/skills/wiki-model/) che si carica in automatico quando apro un progetto della famiglia. Sei scelte che distinguono questa architettura da un RAG standard.

Quattro layer persistenti con ruoli chiari

Il sistema è organizzato in quattro strati distinti. Sorgenti autoritative (PDF, export gestionale, JSON, risposte API): immutabili, mai modificate da nessuno. Wiki markdown: pagine .md con frontmatter YAML, scritte e ri-scritte dall'agente durante l'uso, lette dall'umano. Schema di istruzioni (CLAUDE.md, AGENTS.md): convenzioni, regole tipizzate R1-Rn, workflow di ingest/query/lint. Indici derivati (SQLite + sqlite-vec): mirror SQL, embedding vettoriali, FAQ persistenti, viste pre-calcolate. Ogni strato ha un ruolo preciso e uno è rigenerabile dagli altri.

Ingest a doppia passata con confidence queue

L'estrazione dalle fonti non è una chiamata sola: è double-pass — due letture indipendenti del medesimo contenuto con un modello di visione (tipicamente Gemini per i manuali PDF con tabelle di misure), confronto dei due output, assegnazione di un punteggio di confidenza da 0 a 1 in base alle divergenze rilevate. Sopra soglia 0.7 il dato entra direttamente in wiki; sotto soglia va in una cartella _review/ per validazione umana prima di diventare conoscenza ufficiale. È la barriera contro l'errore di lettura silenzioso — il dato che sembra giusto, nessuno lo verifica, e salta fuori quando un cliente contesta una misura. Sul primo progetto in produzione, il double-pass ha segnalato una percentuale a doppia cifra di letture problematiche che il single-pass avrebbe lasciato passare.

Citation per-claim inline + fallback chain esplicito

Ogni affermazione nella wiki e ogni risposta dell'agente include la fonte: "La bandella regge ottanta chili (fonte: raw/manuale_pag47.json)". Dove il dato esatto non esiste, la risposta non inventa — segue una fallback chain documentata (ID esatto → SKU sibling → variante base → mirror simmetrico → famiglia padre → "dato non disponibile"), con il campo _fallback_reason che traccia quale step ha prodotto la risposta. Il tecnico sa sempre quale inferenza l'agente ha fatto e su quale fonte — è la base della verificabilità e, in prospettiva, della compliance.

FAQ memoization con anti-fossilization schema

Le query ben risolte vengono promosse a FAQ persistenti in SQLite con embedding: alla query successiva simile, il tool search_faq è la prima mossa dell'agente e risponde senza chiamare il modello. Costo marginale zero, latenza bassa. Il rischio noto delle FAQ è che fossilizzino errori — una risposta sbagliata ripetuta all'infinito. Mitigazione: ogni FAQ ha last_reviewed_at, reviewed_by, review_note, un endpoint admin /admin/faq-stale?min_days=90 elenca quelle non revisionate da troppo tempo, ed evidenzia in rosso quelle scadute. La FAQ diventa così memoria viva con audit trail, non memoria morta.

Editor live per il cliente con hot-reload delle regole

Il tecnico interno dell'azienda cliente ha accesso a un editor admin che gli permette di modificare le regole tipizzate della knowledge base (R1-R15 tipicamente — regole come "fallback di simmetria", "priorità di marchio", "soglia minima di catalogo") via interfaccia web, layout "foglio manuale" che gli è familiare. Il volume Docker del wiki è montato :rw, ogni save scrive direttamente il .md con backup .bak-{timestamp} automatico. L'agente legge al prossimo tool call. Cambio di regola applicato in ~30 secondi, senza deploy, senza intervento mio. È la scelta che trasforma il cliente da soggetto passivo a proprietario effettivo della propria knowledge base.

Log conversazioni append-only + costi al centesimo

Ogni conversazione con l'agente finisce in un file conversations.jsonl append-only: timestamp, IP, session id, query, risposta, sequenza dei tool chiamati, token in/out, costo calcolato a tariffa del modello. Tre scopi pratici: candidate FAQ da promuovere, audit di compliance, analisi costo puntuale. Il cliente vede i numeri reali — tipicamente qualche decina di centesimi per conversazione — e sa esattamente quanto gli costa mantenere l'assistente vivo.

Risultato

Il framework ha una prima applicazione matura in produzione — la ferramenta industriale raccontata nella case study ai-knowledge-base — e un secondo verticale in sviluppo per il supporto alla conformità ISO 9001/14001, dove lo stesso pattern serve a gestire procedure, non conformità, evidenze di audit. La parte bella è che ogni nuovo progetto parte già con il 70% dell'infrastruttura pronta, le scelte di affidabilità (double-pass, citation, queue, FAQ anti-fossilization) non vengono rinegoziate ogni volta, e il tempo di discussione col cliente si concentra dove c'è valore — sulle regole di dominio, non sulla plumbing. L'altra parte bella è che ogni applicazione concreta restituisce al framework lezioni di campo: il PATTERN.md non è congelato, è un documento che cresce con i progetti.