Un agente AI come CMS

Gestire un sito web richiede oggi il lavoro di un developer disponibile oppure un CMS che qualcuno deve imparare a usare. Nel primo caso, ogni modifica — un testo aggiornato, una nuova pagina, un annuncio — passa da una persona con competenze tecniche. Nel secondo, chi gestisce i contenuti deve addomesticare un’interfaccia che ha la sua logica, i suoi stati, i suoi pannelli.

Websmith esplora una terza via: gestire un sito attraverso linguaggio naturale: non un editor visivo con un chatbot sopra, non un generatore di HTML da prompt, ma un sistema dove descrivi quello che vuoi — “aggiungi una pagina che presenta il workshop di dicembre con data, programma e form di iscrizione” — e l’agente AI traduce quell’intenzione in iinguaggio markdown strutturato, sceglie i componenti visivi appropriati, genera l’HTML e aggiorna il sito.

La differenza rispetto a un CMS tradizionale non è solo di interfaccia. È di modello mentale. In un CMS impari lo strumento: dove si clicca per aggiungere una sezione, come funziona la preview, dove si gestiscono le immagini. In un sistema agentico descrivi il risultato e il sistema figura il percorso. Il costo si sposta dall’apprendimento dell’interfaccia alla chiarezza dell’intenzione.

Questa modalità non è magia e non è priva di limiti. Funziona solo perché sotto la superficie c’è un sistema deterministico preciso, su cui l’agente si appoggia senza poterlo alterare. Capire come questa separazione funziona è il tema centrale di questo articolo.

Dove trovo Websmith?

Websmith è il sistema che usiamo internamente in TechReloaded per gestire il nostro sito. Non è un prodotto finito, non è open source. È un esperimento in corso che ci ha insegnato cose precise su come gli agenti AI si comportano quando li metti a lavorare su un sistema reale.

Il codice di Websmith al momento non è pubblico, ma i principi descritti in questo articolo sono applicabili a qualsiasi sistema che combina agenti AI con contenuti statici.

Domande e commenti possono essere inviati via email a info@techreloaded.it.

L’architettura: contenuto, template, componenti, renderer

Il sistema si articola su quattro livelli distinti, ognuno con una responsabilità che non si sovrappone con gli altri.

Contenuto

Il contenuto vive in file Markdown. Ogni pagina del sito corrisponde a un file .md. Il frontmatter YAML in cima al file contiene i metadati di pagina — titolo SEO, configurazione dell’hero, dati di contatto — mentre il corpo del documento contiene il testo editoriale e le direttive dei componenti visivi. L’agente scrive qui. Non tocca mai HTML.

---
title: Workshop AI-Driven Product Development
description: Un workshop pratico di due giorni per team di prodotto.
hero:
  type: hero-full-color
  title: Workshop **AI-Driven** Product Development
  subtitle: Due giorni per trasformare come il tuo team costruisce prodotti con AI.
---

<!-- component: fase-processo -->
number: 1
title: Inception
body: Definiamo insieme obiettivi, vincoli e il perimetro del prodotto.
result: PRD.md condiviso
<!-- /component -->

Template

I template sono pagine HTML WYSIWYG. Non usano placeholder tipo {{TITOLO}}. Sono file HTML apribili direttamente nel browser, che mostrano esattamente come apparirà la pagina. Lo script inietta i contenuti tramite selettori CSS stabili — .hero-title, .description-content, .contact. Chiunque può aprire un template e verificare la struttura visiva senza eseguire nulla. I template appartengono ai designer, non all’agente.

Componenti

I componenti sono HTML preconfezionati e documentati. Il design system conta 18 componenti: hero in due varianti, griglie, card con icone, liste di servizi, card del team, spacer, form di contatto, blocchi testo. Ogni componente è un file HTML autonomo che definisce la struttura visiva. L’agente non costruisce HTML, ma sceglie quale componente dichiarare nel Markdown. Questo è un confine architetturale preciso: la composizione visiva appartiene ai componenti, non all’agente.

Renderer

Il renderer è uno script Python deterministico. websmith.py legge il file Markdown, effettua il parsing del template come DOM, risolve le direttive componente nel catalogo, inietta i contenuti nei selettori giusti e scrive l’HTML finale. Lo script non decide nulla. Esegue regole.

La separazione che tiene tutto insieme: inferenza e determinismo

Questa è la scelta architetturale più importante del sistema e non era ovvia all’inizio.

Un agente AI è un motore di inferenza. Dato un prompt, produce output sulla base di pattern appresi. Due chiamate con lo stesso prompt possono dare risposte leggermente diverse. L’agente è bravo a capire l’intenzione, a scegliere il tono giusto, a strutturare contenuti complessi. È per definizione non deterministico.

Il renderer è l’opposto. Uno stesso Markdown in input produce sempre lo stesso HTML in output. Non ha “opinioni”. Non migliora, non interpreta, non inferisce. Applica regole.

Nel sistema queste due parti non si mescolano mai.

L’agente fa la parte inferenziale: capisce la richiesta, sceglie quali componenti usare, scrive il contenuto, ordina le sezioni, propone il tono editoriale. Tutto questo avviene nel Markdown, il file che l’agente produce o modifica.

Il renderer fa la parte deterministica: legge il Markdown, applica le regole dei componenti, inietta nel template, genera HTML. Non decide mai. Se un campo non è nel Markdown, non compare nell’output. Se un componente non è nel catalogo, il renderer segnala un errore invece di inventare un sostituto.

Perché questa separazione è critica?

Primo: gli errori dell’agente sono editoriali: campo mancante, componente sbagliato, tono fuori registro. Sono rilevabili, correggibili, localizzati. Gli errori del renderer sarebbero bug software: riproducibili, sistematici, difficili da attribuire. Tenendo il renderer semplice e deterministico, gli unici errori possibili sono nell’HTML dei componenti o nelle regole dello script. Non nell’output di una sessione specifica.

Secondo: puoi cambiare l’agente senza toccare il renderer. Quando Claude viene aggiornato a una versione nuova, quando si passa da un modello a un altro, quando si affianca un secondo agente con un profilo diverso, il renderer rimane identico. Il sistema non deve essere ricalibraro ogni volta che l’AI evolve.

Terzo: la parte deterministica è testabile in modo tradizionale. Puoi scrivere test per il renderer: dato questo Markdown, aspettati questo HTML. Non puoi fare lo stesso per l’output di un LLM. Separare le due parti significa poter verificare sistematicamente almeno metà del sistema.

La tentazione di sfumare questo confine è reale. “Se il titolo supera un certo numero di caratteri, il renderer potrebbe ridurre il font-size automaticamente”. “Se ci sono solo due item in una griglia, il renderer potrebbe centrare le card”. Ogni comportamento implicito aggiunto al renderer è una variabile che l’agente non può prevedere. Il risultato è output che dipende da condizioni invisibili nel Markdown, che producono sorprese al prossimo render.

La regola che applichiamo è: il renderer non inventa nulla. Tutto ciò che compare nell’HTML deve essere dichiarato nel Markdown o definito nel template.

Il problema che non avevamo previsto

Dopo qualche settimana di utilizzo, abbiamo incontrato un problema che non avevamo previsto nella progettazione.

Un collaboratore stava iterando velocemente su un aspetto visivo della pagina prodotto. Invece di modificare il Markdown e rigenerare, ha modificato direttamente l’HTML generato: più rapido, più immediato, vedevi subito il risultato nel browser. Niente di strano: è quello che farebbe chiunque quando vuole verificare un’idea visiva.

Il problema è emerso la settimana dopo, quando abbiamo rigenerato la pagina per aggiungere una nuova sezione. Il renderer ha sovrascritto l’HTML con la versione generata dal Markdown, che non conteneva la modifica della settimana precedente. La modifica era sparita, e nessuno se n’era accorto perché era sottile: un titolo leggermente diverso, un ordine di elementi cambiato.

Questo episodio ci ha insegnato una cosa precisa: in un sistema basato su generazione, la sorgente deve essere sempre autorevole. Non puoi avere due fonti di verità. O comanda il Markdown, o comandal’HTML: non possono coesistere in modo ambiguo.

La soluzione che abbiamo adottato è diventata una regola esplicita nel file AGENTS.md, il contratto operativo del sistema:

“Se un collaboratore ha modificato l’HTML generato, l’agente deve identificare il cambiamento, riportarlo nel Markdown o nel template, rigenerare la pagina e verificare che il risultato preservi la modifica. Non lasciare mai una correzione solo nel file generato.”

La regola sembra ovvia a posteriori. Prima di quell’episodio non lo era.

AGENTS.md: il contratto per gli agenti

Uno degli aspetti di Websmith che si è rivelato più utile nel tempo è l’uso di un unico file AGENTS.md come contratto operativo condiviso tra tutti gli agenti che lavorano sul repository.

La maggior parte dei sistemi di questo tipo usa file separati per ogni tool: .cursorrules per Cursor, CLAUDE.md per Claude Code, un system prompt per Codex. Il risultato è che ogni agente sviluppa comportamenti leggermente diversi sullo stesso codebase, divergenza silenziosa che emerge solo quando due agenti hanno toccato gli stessi file in modi incompatibili.

Il nostro AGENTS.md è condiviso. CLAUDE.md contiene una riga sola: “segui AGENTS.md”. Qualsiasi tool usi, legge le stesse regole. Il file definisce:

• l’architettura del sistema (dove vivono i file, come si chiama il renderer);
• il workflow standard per modifiche a pagine e contenuti;
• la sintassi canonica dei componenti;
• le responsabilità di ogni tipo di file;
• le regole di qualità prima di chiudere un task.

Stop and report

C’è una regola in particolare che ci ha sorpreso per la sua utilità: la direttiva “stop and report”. Se l’agente trova un componente ambiguo o mancante, si ferma e segnala il problema invece di inventare un sostituto.

Questa è l’opposto del modo in cui di solito si configura un agente AI al quale spesso si chiede di essere il più autonomo possibile, e di risolvere i problemi invece di interrompersi. Ma, per la gestione di contenuti visivi, l’inventiva dell’agente è un problema, non un vantaggio. Un componente inventato rompe la coerenza del design system. Un’interruzione che chiede chiarezza non rompe nulla.

Il catalogo semantico dei componenti

Il sistema ha 18 componenti visivi di vario tipo: hero, griglie, card, liste, spacer, form di contatto, blocchi testo. Fino a poco tempo fa, la conoscenza di questi componenti viveva distribuita tra AGENTS.md, i file HTML di ogni componente e la memoria contestuale dell’agente nella sessione.

Il problema: se chiedi a un agente “aggiungi una sezione che presenta il team”, quale componente usa? griglia-celle con item di tipo team-avatar? Il componente team-member-list? Qualcosa che inventa?

Senza contesto semantico, l’agente indovina. Indovinare produce output imprevedibili che richiedono correzione manuale.

La soluzione che abbiamo implementato è un file catalog.yaml nella cartella dei componenti. Ogni componente ha un’entrata strutturata che non descrive solo i campi accettati, ma il suo scopo semantico: quando usarlo, quando non usarlo, con quali altri componenti è compatibile.

- name: team-avatar
  category: team
  purpose: >
    Avatar card for a person or virtual role: photo, name, role label,
    short bio and skill tags.
  when_to_use: >
    Use inside griglia-celle to present team members or virtual personas.
  do_not_use_when: >
    Presenting real company team members on the Chi Siamo page — use
    team-member-list instead, which has a different layout.
  fields:
    required: [name, image, role, body, skills]

La differenza rispetto a documentazione tradizionale è che questa struttura è interrogabile. L’agente non deve ricordare tutti i componenti a memoria, ma può cercare nel catalogo per scopo (“component per presentare persone”), per categoria (“team”), per vincoli (“non usare con X”). Il catalogo diventa il vocabolario attraverso cui l’agente parla il design system.

Cosa abbiamo imparato

Tre mesi di uso quotidiano hanno prodotto alcune conclusioni che non erano ovvie quando abbiamo iniziato.

Gli agenti AI scrivono bene Markdown, male HTML a mano. Il Markdown è nel training di qualsiasi LLM moderno: la probabilità di errori è bassa, la struttura è prevedibile. L’HTML scritto a mano da un agente tende ad avere tag non chiusi, classi leggermente sbagliate, nesting errato. Separare il contenuto (Markdown) dalla struttura (template) non è solo buona pratica di ingegneria: è una precondizione per usare agenti in modo affidabile.

La documentazione delle regole è parte del sistema, non un accessorio. AGENTS.md non è un README da leggere una volta. È un file che l’agente carica ad ogni sessione come contesto operativo. Se il file è lungo, il contesto rilevante si perde nel rumore. La regola che applichiamo: se AGENTS.md supera tre pagine, contiene troppo e va potato.

Un renderer deterministico è più utile di uno flessibile. La tentazione è sempre di aggiungere comportamenti impliciti: “se c’è solo un item, usa layout diverso”, “se il titolo è lungo, riduci il font-size”. Ogni comportamento implicito è un caso che l’agente non sa prevedere e che produce output inaspettati. La semplicità prevedibile batte la flessibilità intelligente.

La sorgente di verità deve essere una sola. Sembra ovvio. Non lo è nella pratica, specialmente quando stai iterando velocemente su aspetti visivi. Il costo di disciplinare questo aspetto è reale: qualche minuto in più per ogni modifica visiva che va riportata nel Markdown. Il beneficio è che il sistema rimane coerente nel tempo, senza sorprese al prossimo render.

La domanda che rimane aperta

Websmith funziona bene per chi lo ha costruito. Funziona perché chi lo usa conosce il sistema, sa scrivere componenti in Markdown, sa quando il renderer si aspetta un campo obbligatorio.

La domanda che teniamo aperta per le prossime parti di questa serie è diversa: cosa manca perché un sistema del genere sia usabile da chi non ha costruito il sistema?

Non è una domanda tecnica. I pezzi tecnici ci sono tutti. È una domanda di design del prodotto: quale interfaccia, quale layer di astrazione, quale feedback loop rende questo tipo di workflow accessibile a qualcuno che non sa cos’è il Markdown e non vuole saperlo?

La risposta probabilmente passa per un design system come vocabolario dell’agente, per git come workflow editoriale nativo, per preview istantanee senza dover aprire il terminale. Questi sono i temi dei prossimi articoli.