Websmith e Git

Supponiamo di dover rifare la presentazione sul sito di un tool aziendale: ARchetipo, un workflow per lo sviluppo agentico che organizza il lavoro degli agenti AI in un percorso strutturato, dall’idea al codice. Vogliamo aggiornarne la descrizione e il riepilogo in homepage, vedere il risultato e sottoporlo a revisione prima di pubblicarlo. La richiesta all’agente potrebbe essere:

«Prepara la nuova presentazione di ARchetipo, fammela vedere insieme alla homepage e mandala in revisione a Giovanni. Per ora non pubblicare.»

Per chi gestisce contenuti, questa è una richiesta ordinaria. Contiene una fase di scrittura, una verifica del risultato e un passaggio di responsabilità. La versione online deve continuare a funzionare mentre si lavora a quella nuova.

Nella terza puntata (vedi elenco articoli a destra) abbiamo affrontato le decisioni che precedono la scrittura: un’intervista editoriale raccoglie le convenzioni del sito e le traduce in regole riutilizzabili. Ora il problema è dare al lavoro un percorso riconoscibile. Dove vive la proposta? Quale versione sta approvando Giovanni? Cosa succede se nel frattempo cambia la homepage? E come sappiamo che la versione approvata sia effettivamente online?

In Websmith, contenuti, template, componenti e configurazione sono file. Possiamo quindi usare il loro versionamento anche per organizzare il lavoro editoriale. Git offre una base per questo percorso; l’agente deve renderlo comprensibile a chi ragiona in termini di pagine, bozze e revisioni.

Una bozza può riguardare più pagine

Immaginiamo che la nuova presentazione di ARchetipo coinvolga la pagina prodotto, un riepilogo in homepage e le rispettive traduzioni. Sono sorgenti diverse, ma appartengono alla stessa proposta: presentare il prodotto con un messaggio aggiornato.

La bozza deve tenere insieme questi cambiamenti. Se revisioniamo soltanto la pagina prodotto, possiamo approvare un testo che contraddice ancora la homepage. Se pubblichiamo prima una lingua e poi l’altra, introduciamo una differenza che forse nessuno aveva intenzione di creare.

Un branch, in Git, è una linea di lavoro separata dalla versione di riferimento. Consente di preparare una modifica senza integrarla subito nel ramo da cui viene pubblicato il sito. Nel nostro esempio, il branch raccoglie l’intera proposta, incluse le traduzioni richieste dal contratto editoriale.

La corrispondenza utile è quindi fra branch e proposta editoriale. Una proposta può contenere una pagina nuova, una correzione o un aggiornamento coordinato di più pagine. Non occorre creare un branch per ogni file.

Questo non sostituisce l’eventuale stato draft nei metadati della pagina: una pagina può restare una bozza anche dentro una versione del repository già integrata. Il branch separa il lavoro in corso; lo stato del contenuto ne descrive il ciclo di vita secondo le regole del sito.

Tradurre il percorso editoriale in operazioni verificabili

La mappatura può essere descritta così:

Una pull request, o PR, è una richiesta di integrare le modifiche di un branch in un altro. In un servizio come GitHub offre anche uno spazio per descrizione, commenti e revisione. Git conserva le versioni; il servizio di collaborazione organizza la discussione intorno alla proposta.

Approvare, integrare e pubblicare sono passaggi distinti. Possono essere collegati da automazioni, ma non sono sinonimi. Un’approvazione non esegue necessariamente il merge. Un merge può avviare il deploy, ma il deploy può fallire. Il sistema deve mostrare all’editor lo stato effettivo, senza chiamare “pubblicata” una modifica soltanto perché è stata integrata.

Cosa vede l’editor

Riprendiamo la richiesta iniziale. L’agente consulta le regole concordate, individua le sorgenti interessate e prepara il lavoro nel branch della proposta. Modifica il Markdown canonico, aggiorna le traduzioni, valida le sorgenti e genera l’HTML per l’anteprima.

La risposta utile all’editor potrebbe essere:

«La proposta “Nuova presentazione di ARchetipo” è pronta per la revisione. Comprende la pagina prodotto e il riepilogo in homepage, con le traduzioni previste. Gli articoli storici mantengono la descrizione dell’epoca, secondo la regola del sito. Puoi vedere l’anteprima e il confronto dei testi. Ho richiesto la revisione a Giovanni; il sito pubblico conserva la versione precedente.»

L’agente può dichiarare di aver richiesto la revisione soltanto dopo averlo effettivamente fatto. Se “Giovanni” non identifica un collaboratore in modo univoco, deve risolvere quell’ambiguità prima di inviare la richiesta. Il nome comprensibile all’editor e l’account del revisore devono essere collegati nella configurazione del workflow.

Il punto non è mostrare una sequenza di comandi Git. L’editor deve conoscere la proposta, il suo contenuto, chi deve intervenire e il prossimo passaggio. Può chiedere «A che punto siamo?» e ottenere «In attesa della revisione di Giovanni», oppure «Approvata, ma la pubblicazione è fallita», con il motivo e l’azione necessaria.

L’agente può nascondere la sintassi tecnica. Deve rendere visibili le conseguenze delle operazioni.

Una revisione utile contiene testi e anteprima

Il confronto fra versioni, chiamato diff, mostra cosa è stato aggiunto, rimosso o modificato. Per il contenuto Markdown è uno strumento prezioso: permette di distinguere una correzione di etichetta da una riscrittura della descrizione.

Ma il diff non basta a valutare una pagina. Un titolo corretto può diventare troppo lungo nella card. Una traduzione può spostare il bottone fuori dall’allineamento previsto. Un’immagine può esistere nel repository e avere comunque un percorso errato nell’output.

La proposta dovrebbe quindi presentare tre elementi complementari:

• un riepilogo editoriale del risultato e delle pagine coinvolte;
• il confronto delle sorgenti, per vedere esattamente cosa è cambiato;
• un’anteprima generata da quella stessa versione, con l’esito delle verifiche.

Il riepilogo orienta la lettura, il confronto permette di controllare le modifiche e l’anteprima mostra il risultato composto. Un messaggio dell’agente che dice «Ho sistemato tutto» non sostituisce nessuno dei tre.

La revisione deve riferirsi a una versione precisa. Se dopo l’approvazione vengono cambiati il testo o il template che determina il risultato, la vecchia anteprima non rappresenta più la proposta corrente. Il flusso deve aggiornare l’anteprima e richiedere la revisione delle modifiche successive secondo la politica concordata.

Contenuto e design possono essere verificati insieme

Uno dei vantaggi del modello emerge quando cambiano contemporaneamente testo e presentazione.

Un editor allunga il titolo del prodotto. Un designer riduce la larghezza del riquadro che lo ospita. Presi separatamente, i due interventi possono sembrare corretti. Insieme, possono produrre un titolo distribuito su troppe righe.

Git potrebbe integrare senza difficoltà queste modifiche, perché una riguarda il Markdown e l’altra il CSS. L’assenza di conflitti nei file non garantisce la compatibilità del risultato. Per vedere il problema serve un’anteprima costruita sulla combinazione delle modifiche.

Avere contenuto e design nello stesso repository permette di ricostruire quella combinazione e sottoporla a revisione. Possiamo mantenere commit distinti per responsabilità — uno per il testo, uno per lo stile — dentro una proposta coordinata, quando i due interventi fanno parte dello stesso risultato richiesto.

Se invece sono lavori indipendenti, restano proposte separate. Prima di integrare quella ancora aperta, bisogna verificarla sulla versione aggiornata del ramo di destinazione. La separazione del lavoro non elimina la necessità di controllare come le modifiche convivono.

Due editor sulla stessa pagina

Supponiamo che una proposta riscriva l’introduzione di ARchetipo e un’altra corregga un’informazione nello stesso paragrafo. Quando viene integrata la prima, la seconda può richiedere di risolvere un conflitto.

L’editor non dovrebbe ricevere un blocco di testo con marcatori Git da interpretare. L’agente dovrebbe spiegare il problema in termini editoriali:

«Nel frattempo l’introduzione è stata riscritta. La tua correzione riguarda una frase che nella nuova versione è stata riformulata. Ecco il testo corrente e una proposta che conserva la correzione: il significato è quello desiderato?»

Se la soluzione discende chiaramente dalla richiesta e dalle regole del sito, l’agente può applicarla e verificarla. Se le due versioni esprimono informazioni incompatibili, deve chiedere quale sia corretta. La capacità tecnica di risolvere un conflitto non autorizza a scegliere un fatto di prodotto.

Dopo la risoluzione, le sorgenti devono essere nuovamente validate e l’anteprima rigenerata. Si revisiona il risultato finale della combinazione, non soltanto quello preparato prima dell’altro intervento.

Le regole di pubblicazione nascono nell’intervista

Il workflow completa l’intervista descritta nella terza puntata. Oltre al tono e all’ambito degli aggiornamenti, Websmith deve raccogliere alcune decisioni organizzative:

Le risposte diventano configurazione del sito e controlli nel processo di collaborazione e deploy. Scrivere «serve un’approvazione» in un file non basta: il percorso di pubblicazione deve verificare che quell’approvazione esista e riguardi la versione da pubblicare.

Anche l’apertura di una proposta deve essere coerente con questo percorso. Se qualsiasi push pubblicasse direttamente il sito, salvare una bozza remota potrebbe metterla online prima della revisione. Occorre distinguere i rami di lavoro dal ramo o dall’azione destinati alla pubblicazione. Questa configurazione tecnica dà sostanza alla promessa fatta all’editor: «Puoi preparare una proposta senza modificare il sito pubblico».

L’urgenza cambia il percorso, non il significato degli stati

«La data del workshop è sbagliata: correggila subito.»

Una procedura pensata soltanto per revisioni lunghe diventa un ostacolo. Serve un percorso rapido, concordato in anticipo: chi può autorizzarlo, quali modifiche comprende e cosa succede se il revisore abituale non è disponibile.

Una correzione urgente può avere una proposta piccola, un riepilogo essenziale e un’approvazione immediata da parte del referente previsto. Restano necessarie le verifiche pertinenti: la nuova data deve essere coerente nelle traduzioni e nelle parti del sito che il contratto richiede di mantenere allineate.

L’agente non dovrebbe inserire nella stessa pubblicazione una riscrittura che era ancora in revisione. Preparare la correzione dalla versione corrente destinata alla pubblicazione permette di evitare che l’urgenza trascini con sé lavoro non approvato.

Anche qui, «corretto nei file» e «corretto online» sono stati diversi. Il lavoro si chiude quando il sistema ha verificato il risultato pubblicato, oppure ha segnalato chiaramente cosa ne impedisce la pubblicazione.

Tornare indietro senza perdere ciò che è successo dopo

Il versionamento offre un modo per annullare una modifica conservandone la storia. Un revert crea una nuova modifica che annulla gli effetti di un cambiamento precedente; non cancella quel cambiamento dalla cronologia.

Per un editor la richiesta può essere «Ripristina la descrizione di ieri». L’agente deve identificare quale modifica riguarda la descrizione e verificare cosa è successo dopo. Ripristinare un’intera vecchia versione del sito potrebbe cancellare anche correzioni successive che devono restare.

Il ripristino va quindi preparato con un ambito preciso, applicato alle sorgenti e seguito da validazione, generazione e pubblicazione. Sovrascrivere soltanto l’HTML online lascerebbe nel Markdown il testo da eliminare: alla generazione successiva ricomparirebbe.

Non sempre un revert è immediato. Un componente usato dalla vecchia pagina potrebbe essere cambiato, oppure altre modifiche potrebbero dipendere dal testo introdotto. In questi casi l’agente deve preparare un ripristino compatibile con lo stato corrente e mostrarne il risultato.

Il vantaggio della cronologia è poter ricostruire e correggere il percorso. Non rende ogni operazione automaticamente reversibile senza valutazione.

Il lavoro dell’agente è rendere il processo leggibile

Branch, commit, revisioni e deploy non devono diventare un corso obbligatorio per chi gestisce il sito. Le informazioni essenziali possono essere espresse nel linguaggio del lavoro editoriale: proposta in preparazione, pronta da rivedere, modifiche richieste, approvata, in pubblicazione, pubblicata o pubblicazione fallita.

Questi stati devono corrispondere a eventi verificati. Una proposta non è approvata perché l’agente interpreta il silenzio come assenso. Una pagina non è pubblicata perché il comando che avvia il deploy è stato accettato. L’interfaccia può essere semplice proprio perché il sistema tiene distinte queste condizioni.

Git fornisce la cronologia e la separazione del lavoro. La piattaforma di collaborazione raccoglie discussioni e approvazioni. La pipeline valida, genera e pubblica. Il compito di Websmith è collegare questi strumenti alle decisioni dell’editor, rendendo chiaro cosa è stato fatto e chi deve intervenire dopo.

Conclusioni

Il prossimo articolo allarga il perimetro oltre il sito: come usare contenuti e decisioni editoriali per preparare uscite su canali diversi, mantenendo riconoscibile la fonte da cui derivano. Quando una descrizione diventa anche una newsletter o un post, serve la stessa cura nel distinguere ciò che può essere adattato da ciò che deve restare fedele all’originale.

Nota

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