Da Q&A bot a piattaforma multi-catalogo: il design dei tre strati

Avevo in produzione un Q&A bot interno per il catalogo di un grosso brand di ferramenta — uno strumento che tecnici e venditori interrogavano per cercare codici, leggere distinte, capire compatibilità. Funzionava bene: ~4000 chunk indicizzati, prompt caching, router Haiku/Sonnet, costo medio per conversazione sotto i dieci centesimi.

La sessione doveva essere una mezza giornata — solo "fare un diagramma di flusso del funzionamento attuale". È durata otto ore, è finita con tre design doc (~6500 righe), due poster A3 stampabili e una rivelazione poco confortante: il bot era il 10% del problema reale.

I tre strati

Disegnando i flussi è emerso che il bisogno non è "consultare un catalogo" — è assistere un agente commerciale a costruire una proposta (per esempio una cucina completa) che attraversa una trentina di cataloghi eterogenei, verificando vincoli e compatibilità tra prodotti di brand diversi.

Lo strato A è quello che avevo già. Lo strato B esisteva a frammenti, sparso in regole markdown. Lo strato C — l'orchestratore commerciale che accumula vincoli del cliente e propone due-tre configurazioni — non esisteva proprio.

La pipeline di auto-curation

Onboardare trenta cataloghi a mano è infattibile. La proposta è una pipeline a sette step con un AI curator-as-reviewer: un modello propone, un altro modello rivede, e solo quello che passa entrambi entra nel ramo wiki/; il resto resta in draft/ finché un umano non firma.

Tre modi operativi: Bootstrap (catalogo nuovo da zero), Refresh (nuova edizione manuale dello stesso brand), Reactive cascade (un editor cambia una regola — il sistema propaga in cascata sulle distinte e schede impattate, in modalità draft).

La parte più scomoda

A metà sessione mi sono fermato a fare una review architetturale comparativa: per ogni componente che stavo per scrivere custom, esiste già qualcosa di SOTA? Risultato:

• Promptfoo per gli eval (niente runner custom)
• DoIt per il cascade engine
• LangGraph per l'orchestratore di Strato C

Cinque altri framework parcheggiati con trigger di re-evaluation. Il principio è banale ma facile da dimenticare quando il prototipo funziona: scrivere meno codice possibile, soprattutto quando esistono primitive collaudate.

I documenti

Per fissare il pattern in un colpo d'occhio ho prodotto due poster A3 stampabili (HTML standalone, CSS print-ready, niente dipendenze):

• Poster — Catalog · Agent design pattern — la versione generica, riutilizzabile
• Poster — la piattaforma concreta — la versione istanziata sull'azienda per cui lavoro

Sotto ai poster ci sono i tre design doc che hanno guidato la sessione, più l'handoff aggiornato a fine giornata:

• Design Doc Piattaforma (~1600 righe) — il "perché" dei tre strati, dei vincoli operativi e dell'integrazione gestionale progressiva
• Playbook P-1 — Refactor side-by-side (~620 righe) — il "come" del cutover senza downtime
• Playbook — Onboarding catalogo (~420 righe) — i cinque stage per portare un brand nuovo dentro la piattaforma
• Handoff di fine sessione (~600 righe) — stato puntuale, decisioni aperte, prossimi step

Sono pubblicati così come sono usciti, ad eccezione di un'email di un rivenditore che ho rimosso. Tutto il resto è il working draft reale: contiene tabelle di decisioni con default suggerito da confermare, sezioni da chiudere, gate per stage. È un esempio onesto di quanto un design doc utile assomigli più a una checklist di domande aperte che a una specifica chiusa.

La cosa che mi porto a casa

Il diagramma di flusso fatto bene non documenta — interroga. Costringe a chiedere chi fa cosa, quando, e ti restituisce in cambio l'onestà brutale di vedere quanto del problema il prototipo non stava risolvendo. In questo caso, il 90%.

Niente di tutto questo è in produzione: il bot esistente continua a girare invariato. Il design vive su un branch separato in attesa di sign-off. Ma adesso so cosa sto costruendo, e non è quello che pensavo di star costruendo stamattina.