Come è costruito questo sito

Gestisco questo sito con contratti espliciti tra agenti. Ogni modifica a copy, contenuti o codice passa per un task di ambito ristretto e con un nome preciso, con il proprio contesto, i percorsi consentiti e i gate associati. I modelli linguistici aiutano dentro i loop di automazione schedulati, mai dentro la build di produzione. Il loro output raggiunge il sito solo tramite pull request: i controlli deterministici verificano ogni proposta e ciò che viene segnalato aspetta la mia revisione. Quello che segue è il meccanismo reale, nell’ordine in cui una modifica lo attraversa.

Principi

Il minimo contesto sufficiente

Assegno a ogni task il minimo contesto di cui ha bisogno, generato dal manifest, così un’esecuzione ragiona su pochi file invece che sull’intero repository.

Una build deterministica

La build di produzione non chiama mai un modello. Con gli stessi input versionati e la stessa toolchain produce lo stesso output, così un deploy è riproducibile e più facile da verificare.

La generazione è una proposta

Il copy scritto da un modello è una bozza, non un commit. Sono i gate deterministici a decidere se può andare online. Ciò che segnalano resta nella pull request finché non lo revisiono.

Il merge lo decidono i gate

Una pull request di automazione viene unita solo con tutti i gate deterministici verdi, e solo finché l’interruttore di auto-merge è attivo. Ciò che un gate segnala — un articolo bocciato dal giudice, un fix di rescue — si ferma su una PR etichettata e aspetta me.

Una voce, due lingue

Il copy del sito resta in prima persona. Inglese e italiano vanno online insieme sulle superfici abbinate; il gate di parità registra anche le eccezioni deliberate, come il registro pubblico di audit disponibile solo in inglese.

Workflow

Gli otto workflow che una modifica può attraversare, dal contratto al deploy in produzione.

01

Contratti tra agenti

Un manifest, un insieme di ruoli e un file per ogni task definiscono chi fa cosa, dove può scrivere e quando deve fermarsi.

  1. Il manifest elenca lo stack, la proprietà delle sorgenti, i ruoli, i task e i gate in un unico posto.
  2. Ogni task indica i percorsi consentiti, i suoi comandi e le condizioni che fermano l’esecuzione.
  3. Un controllo valida il manifest, i ruoli, i task e le regole di marca prima che il lavoro inizi.
npm run agent:checknpm run agent:context

02

Copy e tono di voce

Il linting deterministico mantiene la scrittura nella mia voce; un passaggio opzionale di modello rende più naturali le bozze, e sono i gate a decidere cosa resta.

  1. Il controllo del copy applica regole a pattern singolo più un audit anti-slop pesato sulla densità, in inglese e italiano.
  2. Un passaggio di fix applica le sostituzioni sicure e deterministiche senza toccare il significato.
  3. Nella revisione AI un modello propone riscritture; copy-lint, frontmatter e parità decidono se tenerle.
npm run copy:checknpm run copy:ai-review -- --changed --write

03

Loop di automazione completa

Job GitHub Actions schedulati aggiornano i contenuti, abbozzano articoli e propongono cambi SEO. Aprono pull request — mai commit diretti su main.

  1. Il refresh settimanale traduce gli articoli mancanti, compila le chiavi dell’interfaccia in italiano, genera FAQ e takeaway ancorati al testo, rende più naturali le bozze, rigenera i feed e controlla la salute dei contenuti sul sito buildato.
  2. I loop mensili abbozzano un articolo ancorato dietro gate di originalità e un giudice consultivo, e trasformano le query di Search Console in proposte SEO e brief sui temi mancanti.
  3. Un loop showcase propone schede progetto da repository pubblici e ne unisce una solo con tutti i gate verdi; il rescue CI tenta fix sulle issue ci-failure con Codex e non unisce mai il proprio lavoro.
  4. L’automazione pusha con un token GitHub App così Flash CI gira sulla PR; le esecuzioni sporche ricevono needs-human, e ogni PR di automazione porta needs-translation-review.
npm run content:mapnpm run copy:ai-review:full -- --writenpm run article:judge

04

Pipeline di pubblicazione

Le release software archiviate vivono in un repository separato. Il sito consuma i DOI concetto Zenodo tramite un registry, uno script di sync e un gate di deriva — mai aggiornati in automatico in build.

  1. Il repository software pubblica una release GitHub, riserva un nuovo DOI versione Zenodo e sincronizza CITATION.cff da release.toml.
  2. publications.json è il registry del sito: DOI concetto per il copy pubblico, DOI versione e publishedVersion per i controlli di deriva.
  3. publication:sync aggiorna il registry da Zenodo e GitHub, propaga i DOI concetto nel catalogo e nel copy dei progetti, e rigenera il JSON-LD della landing.
  4. publication:check blocca la CI quando github-stats, i file consumer o i metadati Zenodo divergono; una persona revisiona la PR prima del merge.
npm run publication:syncnpm run publication:check

05

SEO e GEO

La sitemap e l’indice llms.txt derivano dal registro delle route. I dati strutturati combinano quei percorsi canonici con i registri di identità, pubblicazioni e progetti; controlli deterministici mantengono allineate le superfici.

  1. Le route statiche vivono in un’unica lista condivisa che alimenta sia la sitemap sia l’indice llms.txt.
  2. Ogni pagina porta con sé JSON-LD: una persona, la traccia di breadcrumb e un tipo adatto alla pagina.
  3. Un loop su Search Console e un report sui temi mancanti mi indicano cosa scrivere dopo; una baseline GEO manuale traccia menzioni e citazioni nelle risposte AI.
npm run seo:checknpm run topic:gap

06

Gate di qualità

Un comando esegue l’intero gate pre-merge: tipi, lint, formato, test, salute dei contenuti, parità e deriva dell’output generato.

  1. Il controllo di qualità è l’equivalente locale del gate che la CI esegue a ogni modifica.
  2. I file generati vengono rigenerati e confrontati, così l’output vecchio blocca la build invece di passare inosservato.
  3. Un controllo di governance protegge la documentazione pubblica da affermazioni che non faccio più.
npm run quality:check

07

Build deterministica

La build di produzione è pura: pre-renderizza ogni route, scrive mirror markdown per lettori e modelli, e non chiama alcun modello esterno.

  1. Vite costruisce l’app, poi un passaggio di prerender scrive HTML statico per ogni route localizzata.
  2. I mirror markdown di ogni articolo vengono pubblicati accanto all’HTML per i lettori automatici.
  3. Il container serve il risultato; niente su questo percorso dipende da una chiave API.
npm run build

08

CI e deploy

Flash CI builda il sito, scansiona le pagine renderizzate ed esegue i controlli browser; un run verde su main attiva un deploy in produzione con controllo di supersede.

  1. Dopo i gate pre-merge, la CI esegue una build di produzione, content:scan su dist/ e un controllo sul budget di bundle.
  2. Un job browser separato scarica quella build ed esegue controlli di contrasto e regressione visiva prima che il merge sia consentito.
  3. Il deploy segue un Flash CI riuscito su main, pubblica immagini arm64 su GHCR e verifica che la produzione serva il commit nuovo.
npm run buildnpm run content:scannpm run perf:budget

Gate di qualità

Ogni modifica supera i gate pre-merge prima del merge. Flash CI ripete lo stesso insieme, poi esegue i controlli post-build sul dist/ scaricato.

Pre-merge

Contratti agentiagent:checkFrontmattervalidateTempo di letturareadtime:checkAsset OGog:checkParità EN/ITi18n:check:strictStruttura articolii18n:articlesTono di vocecopy:checkSalute contenuticontent:healthDeriva pubblicazionipublication:checkSchema showcaseshowcase:checkDeriva generatigenerated:checkSEOseo:checkLedger SEOseo:ledger:checkGovernancegovernance:checkTipitypecheckLintlintLint CSSlint:cssLint workflowlint:actionsFormatoformat:checkTesttest:run

Post-build (CI)

Scan pagine renderizzatecontent:scanBudget bundleperf:budgetContrasto + regressione visivabrowser checks

Hai un progetto in mente?

Scrivi a info@gianlucamazza.it il problema operativo e i sistemi coinvolti. Quando c’è già un prototipo funzionante, il primo passo è la review di production readiness. Quella review non include modifiche al codice.

Scrivi via email