Salta al contenuto

Come è costruito questo sito

Questo sito è governato da contratti tra agenti espliciti. Ogni modifica a copy, contenuti o codice passa per un task piccolo e con un nome preciso, con il proprio contesto, i percorsi consentiti e i suoi gate. I modelli linguistici aiutano dentro l’automazione, mai dentro il build di produzione, e il loro output arriva online solo dopo una pull request revisionata. Quello che segue è il meccanismo reale, nell’ordine in cui una modifica lo attraversa.

Principi

Il minimo contesto sufficiente

Dai 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.

Un build deterministico

Il build di produzione non chiama mai un modello. Lo stesso input produce sempre lo stesso output, così un deploy è riproducibile e senza sorprese.

La generazione è una proposta

Il copy scritto da un modello è una bozza, non un commit. Sono i gate deterministici a decidere se va online, e una persona lo revisiona prima in una pull request.

Una voce, due lingue

Tutto ciò che pubblico resta in prima persona, e inglese e italiano vanno online insieme. Un controllo di parità blocca il build quando una lingua resta indietro.

Workflow

I sei passaggi che una modifica può attraversare, dal contratto al deploy.

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 voce di marca

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. Una revisione AI lascia che un modello proponga riscritture; copy-lint, frontmatter e parità scelgono se tenerle.
npm run copy:checknpm run copy:ai-review -- --changed --write

03

Automazione dei contenuti

Un job settimanale aggiorna il sito e abbozza articoli; un giudice fa da gate a tutto ciò che viene generato prima che possa entrare.

  1. Una mappa dei contenuti costruisce un inventario deterministico di articoli, progetti, lingue e feed.
  2. Un passaggio di salute trasforma quella mappa in esiti pass o fail, mai in deriva silenziosa.
  3. Il refresh settimanale e la generazione di articoli eseguono il modello, poi aprono una pull request per la revisione.
npm run content:check

04

SEO e GEO

La sitemap, l’indice llms.txt e i dati strutturati derivano tutti da un’unica tabella di route, così la superficie leggibile dalle macchine non si discosta mai dal sito.

  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.
npm run seo:checknpm run topic:gap

05

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 il build invece di passare inosservato.
  3. Un controllo di governance protegge la documentazione pubblica da affermazioni che non faccio più.
npm run quality:check

06

Build deterministico

Il build di produzione è puro: 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

Gate di qualità

Ogni modifica supera questo gate completo prima del merge. Lo stesso insieme di controlli gira in CI.

Contratti agentiagent:checkFrontmattervalidateParità EN/ITi18n:check:strictVoce di marcacopy:checkSalute contenuticontent:healthDeriva generatigenerated:checkSEOseo:checkGovernancegovernance:checkTipitypecheckLintlintFormatoformat:checkTesttest:run