IWA — knowledge base e chatbot RAG

sicilyorganic.com è la webapp B2B di In Campagna, l'azienda alimentare biologica per cui lavoro: ordini all'estero da clienti B2B. La webapp principale l'ha sviluppata un collega; io ho seguito il suo debug e ho fatto da tester e suggeritore di funzioni durante la costruzione. IWA, il progetto che racconto qui, è quello che è nato attorno alla webapp: il sistema di formazione, supporto e documentazione che serve a farla usare bene — sia al team interno che la gestisce sia ai clienti finali che la usano per fare ordini.

Il problema era classico ma sentito poco da chi non lavora dentro. Procedure, regole, materiali di formazione vivevano sparpagliati su un Drive cresciuto negli anni: cercare una risposta specifica lì dentro è lento, leggerla è ancora più lento, e per chi si è appena unito al team il primo mese è un susseguirsi delle stesse domande poste a chi è già lì da tempo. Tre conseguenze: tempo del team senior bruciato in ripetizioni, persone nuove più lente del necessario, e — peggio — risposte sbagliate ai clienti quando chi sapeva era altrove. Sul lato clienti, il pattern era simile: ogni nuovo cliente che si affaccia alla piattaforma ha bisogno di un'introduzione, e farla a mano in tre lingue, ad ogni cliente, è impraticabile.

Per il team interno c'è un chatbot domanda-risposta che gira sul PC di chi lo usa. Lo si installa con doppio click — un installer nasconde la complessità (Python integrato nel pacchetto, librerie già pronte, shortcut sul desktop) — e da lì funziona come una qualsiasi app del computer. Risponde su procedure, regole, formazione, attingendo a una knowledge base indicizzata di oltre 260 frammenti.

Per la formazione e il supporto ci sono portali HTML auto-contenuti: pagine singole, con tutti gli screenshot già dentro, che si aprono con doppio click anche su un PC nuovo o offline. Vivono lì: niente server, niente collegamento, niente cose da aggiornare. Il portale team è in italiano; le guide e le presentazioni per i clienti sono in tre lingue (italiano, inglese, francese) — un file HTML che si manda via email, si apre, e da lì insegna da solo.

Tutto questo è cucito insieme da una pipeline di aggiornamento che parte da un punto solo: quando la webapp B2B cambia, una sessione di Claude Code aggiorna la documentazione, rigenera i portali, re-indicizza il chatbot e prepara una nuova release dell'installer. Quattro output, un solo gesto.

Il problema delle knowledge base aziendali è sempre lo stesso: la documentazione invecchia. Procedure aggiornate sul Drive ma non nelle presentazioni; presentazioni aggiornate ma non nel chatbot; chatbot aggiornato ma non nei materiali di formazione. La soluzione classica — "ricordatevi di aggiornare anche X e Y" — perde sempre, perché si appoggia alla memoria umana.

Qui ho preso un'altra strada: una sola fonte di verità in Markdown, e tutto il resto è generato. Quando aggiungo o cambio una procedura, modifico solo il file sorgente. Da lì un singolo comando rigenera i portali HTML (con gli screenshot ri-embedded come base64), ri-indicizza la knowledge base ChromaDB del chatbot, ricompone le presentazioni multilingue e prepara una nuova release dell'installer. Niente sistemi separati che vanno tenuti sincronizzati a mano: tutte le fonti hanno la stessa origine, e la coerenza è una proprietà del sistema, non della disciplina dell'autore.

Per tenere onesta la pipeline c'è uno studio di agenti specializzati dentro Claude Code. Un agente fa il *maintainer* (aggiorna la documentazione dopo un cambiamento della webapp); un *capo cantiere* coordina; tre agenti separati lavorano sui contenuti delle presentazioni — uno scrive, uno cura il layout, uno revisiona. Ogni agente vede solo le istruzioni che gli servono e produce un pezzo del lavoro. Non è automazione cieca: ogni passaggio mi torna in mano per la revisione finale.

Il chatbot non improvvisa: se la knowledge non basta, rimanda la domanda al team sviluppo. È la regola architetturale, applicata senza margine di interpretazione.

Il pattern dominante nel 2026 è il contrario: chatbot generalisti che, davanti a una domanda, tirano fuori una risposta plausibile costruita per analogia. Sul dominio sbagliato — un manuale di procedure aziendali, una regola di compliance alimentare, una guida cliente — una risposta plausibile ma sbagliata è peggio di nessuna risposta. Il valore di un assistente non è coprire ogni domanda, è non sbagliare le risposte che dà.

La disciplina si materializza in tre agenti in cascata, ognuno con un solo lavoro. Un router classifica la domanda e blocca quelle fuori tema prima ancora di consumare risorse. Un componente di recupero fa ricerca semantica sulla knowledge base in puro Python — zero chiamate AI, niente latenza di rete, niente costi. Un responder riceve solo i frammenti recuperati e un'istruzione esplicita: rispondi a partire da questi pezzi e basta. Il modello è Claude Haiku 4.5: veloce, economico, disciplinato. Per un compito che non chiede creatività ma fedeltà alla fonte, è esattamente quello che serve.

Quando i frammenti non bastano, il chatbot rimanda la domanda al team sviluppo, che la prende in carico e — quando la risposta è stabile — la aggiunge alla knowledge base. Così il "non lo so" non è una porta chiusa: è un input che fa crescere il sistema. Ogni domanda senza risposta oggi è un pezzo di knowledge che mancava, e che da domani sarà lì.

Oggi tutto il team che segue il sito B2B usa il chatbot per togliersi i dubbi ed essere autonomo. Non è "un'app che ogni tanto qualcuno apre per curiosità": è lo strumento di prima fila per chi non sa una procedura, una regola, un passaggio dell'app. Il senior non viene più interrotto da domande che la knowledge base sa già rispondere; chi è arrivato di recente diventa operativo senza dover prenotare un'oretta del collega esperto.

Lo stesso chatbot serve anche i clienti, in tutte e tre le lingue, ma con una knowledge base diversa: tolti i contenuti interni e i dati sensibili, restano solo le procedure d'uso della piattaforma. Stesso motore, due audience, due *second brain* paralleli — la disciplina del grounding del blocco precedente in azione: ognuno vede solo quello che gli compete.

La pipeline gira a ogni fix o miglioria del codice della webapp. Documentazione, portali, chatbot e installer si aggiornano in cascata — Claude Code sa a che punto è ogni audit, quindi sa cosa è cambiato e cosa va rigenerato. Prima della pipeline tenere queste cose sincronizzate a mano era un casino. Oggi è un comando. L'effetto netto: autonomia operativa ovunque — team senior che lavora a cose nuove, persone nuove che non si sentono perse, clienti che imparano la piattaforma per conto loro.