dox: aggiorna AGENTS.md automaticamente

Perché il tuo AGENTS.md è errato dopo tre settimane

Un file AGENTS.md diventa obsoleto perché nulla lo collega al codice. Lo scrivi una volta, manualmente, il giorno in cui il repository ha una determinata struttura. Poi cambia il test runner, viene rinominato un package, viene eliminato un servizio e il file continua a descrivere la situazione di giugno. Non si verifica alcun errore, perché nessun passaggio della build lo legge.

L'agente lo legge e gli attribuisce valore. È questo che crea il problema. In un repository senza AGENTS.md, un agente di coding esamina l'ambiente prima di agire. In un repository con un AGENTS.md errato, smette di esaminare l'ambiente perché ha già una risposta. Esegue il comando indicato dal file, la shell restituisce Missing script: "test" e l'agente inizia a fare supposizioni. Spesso modifica package.json per aggiungere lo script promesso dalla documentazione. Il file obsoleto non ha semplicemente ignorato l'errore. Ha causato una modifica indesiderata.

dox è una soluzione a questo problema. È un insieme di regole scritte per l'agente, che rende l'aggiornamento della documentazione parte integrante della conclusione del lavoro. In questo modo il file cambia nello stesso commit del codice che lo ha reso errato.

Che cos'è dox e che cosa non è

dox è un singolo file Markdown. Il repository è agent0ai/dox, viene distribuito con licenza MIT e, all'11 agosto 2026, l'intero progetto è costituito da un unico AGENTS.md da 3906 byte, un README, una LICENSE e due immagini. Non c'è alcun pacchetto da installare né alcun runtime.

Questo è importante perché il termine generator suggerisce un programma che analizza il codice. Nulla analizza il codice. dox è un contratto che il coding agent legge: l'agent è il generator e dox è l'insieme di istruzioni che gli indica quando leggere la documentazione, quando riscriverla e quale struttura deve avere ogni documento.

Il file contiene dieci sezioni e due di esse svolgono il lavoro principale. "Read Before Editing" indica all'agent di percorrere il repository dalla root fino a ogni path che intende modificare e di leggere ogni AGENTS.md lungo ciascun percorso, nella sessione corrente, senza affidarsi alla memoria. "Update After Editing" stabilisce che ogni modifica significativa richiede un passaggio DOX, cioè un aggiornamento della documentazione da eseguire prima di considerare concluso il task. Il passaggio aggiorna il documento proprietario più vicino quando cambiano lo scopo, la struttura, il workflow, le autorizzazioni o le preferenze dell'utente.

Il resto definisce la struttura. Un AGENTS.md figlio ha un ordine predefinito delle sezioni: Purpose, Ownership, Local Contracts, Work Guidance, Verification e Child DOX Index. Il file root contiene le regole valide per l'intero progetto e il Child DOX Index di livello superiore, che consente all'agent di individuare i documenti figli. "Closeout" è la checklist che l'agent esegue al termine di un task: ricontrollare i path modificati rispetto alla catena, aggiornare la documentazione proprietaria più vicina, aggiornare ogni indice interessato, eliminare le contraddizioni, eseguire le verifiche esistenti e indicare quali documenti ha lasciato intenzionalmente invariati.

Fissa dox su un singolo commit, non su main

Il repository non contiene tag né release, quindi non esiste un numero di versione da fissare. Fissa invece il commit. Il file AGENTS.md corrente corrisponde al commit f34ec7ad1055d3393887e5a2670e8cb7320c9165, del 1 August 2026.

mkdir -p .agent
curl -fsSL -o .agent/dox-f34ec7a.md \
  https://raw.githubusercontent.com/agent0ai/dox/f34ec7ad1055d3393887e5a2670e8cb7320c9165/AGENTS.md
wc -c .agent/dox-f34ec7a.md

wc -c deve stampare 3906. Un valore diverso indica che non hai scaricato il file descritto da questa guida; leggilo prima di considerarlo attendibile. Se inserisci un hash di commit errato, -f fa terminare curl con curl: (22) The requested URL returned error: 404 e non scrive alcun contenuto, mentre wc -c stampa 0. Un file troncato è peggiore di un file assente, perché l’agent segue metà del contratto senza saperlo.

cp .agent/dox-f34ec7a.md AGENTS.md
git add AGENTS.md .agent/dox-f34ec7a.md
git commit -m "Add DOX rules (agent0ai/dox @ f34ec7a)"

Quel cp è destinato a un repository che non contiene ancora AGENTS.md. Se ne hai già uno, non sovrascriverlo. Inserisci le sezioni dox sopra il contenuto esistente, mantieni le tue regole sotto di esse e leggi il risultato una volta dall’inizio alla fine. Due documenti in contraddizione producono un agent che segue la regola che ha letto per ultima.

Chiedi quindi al tuo agent di eseguire il primo passaggio dall’interno del repository. Il README riporta la formulazione esatta:

Initialize DOX tree for this project now.

Il comando crea i file AGENTS.md per i child e gli indici che li referenziano. Controlla il risultato prima di considerarlo corretto:

git status --short
find . -name AGENTS.md -not -path './.git/*' | sort

Ogni file nell’output di find dovrebbe comparire in un Child DOX Index presente nelle sezioni precedenti. Un documento child non citato da alcun indice può sfuggire all’agent, perché l’indice è il meccanismo con cui individua i documenti che non si trovano direttamente lungo il percorso che sta analizzando.

Cosa può vedere dox e cosa non può sapere

L’agente che crea il tuo albero legge il repository. Di conseguenza, tutto ciò che si trova nel repository può essere incluso nell’inventario: la struttura delle directory, i manifest dei pacchetti e i lockfile, gli script in package.json, Makefile o pyproject.toml, i file dei workflow CI, i Dockerfile, gli entry point e CODEOWNERS, se presente. Un inventario creato a partire da questi elementi si mantiene effettivamente da solo. Quando un pacchetto viene spostato, l’esecuzione successiva sposta anche la riga che lo descrive.

Tutto ciò che segue devi dichiararlo tu, perché non si trova nel repository e l’agente non può leggerlo:

• perché esiste una regola, aspetto che impedisce all’agente di rimuoverla perché la considera una complessità inutile
• quale dei due percorsi funzionanti è supportato e quale è in attesa di essere eliminato
• qualsiasi elemento esterno al repository, ad esempio l’ambiente di staging o il motivo per cui una dipendenza è bloccata a una versione precedente di due release
• cosa prevedi di fare la prossima settimana, ovvero la differenza tra un file aggiornato e un file utile

dox lo sa. Le sue regole stabiliscono che Work Guidance deve riflettere gli standard attuali del progetto o le istruzioni dell’utente; se non esistono ancora, la sezione deve rimanere vuota. Verification deve riflettere un controllo esistente. Se nel repository non è presente alcun framework di test, questa sezione rimane vuota finché non ne viene introdotto uno. Un file generato che inventa uno standard è peggiore di una sezione vuota, perché l’agente finirà per applicare lo standard inventato.

Mantieni separate dall’inventario generato le indicazioni scritte manualmente

Questo è il problema che porta ad abbandonare la documentazione generata. Scrivi un paragrafo per spiegare che la coda dei job deve avere un solo consumer. Tre settimane dopo, un passaggio riscrive il file e il paragrafo scompare in un diff di quaranta righe, composto soprattutto da riordinamenti dei nomi dei file, senza che nessuno se ne accorga.

Servono due meccanismi, ed è necessario usarli entrambi.

Per prima cosa, sposta le indicazioni durature in un file distinto. Le decisioni progettuali e il relativo ragionamento devono stare in un DESIGN.md scritto per l'agent, mentre le note destinate alle persone devono stare dove separi HUMAN.md da AGENTS.md. AGENTS.md contiene quindi l'inventario e i contratti locali: è esattamente la parte che deve cambiare quando cambia il codice.

In secondo luogo, delimita le indicazioni che devono restare in AGENTS.md. Racchiudile tra marker e considera il blocco di proprietà delle persone:

## User Preferences

<!-- dox:keep start -->
The jobs queue stays single consumer. Ordering is the reason this service exists.
Deploys ship on Tuesday. A Friday deploy is a human decision, not an agent decision.
<!-- dox:keep end -->

I commenti Markdown non vengono visualizzati nella pagina, ma l'agent continua a leggerli. Ora rendi verificabile la permanenza del blocco, in modo che un passaggio che lo rimuove fallisca in modo evidente. Esegui questo controllo in CI (continuous integration) a ogni pull request:

git fetch -q origin main
sed -n '/dox:keep start/,/dox:keep end/p' AGENTS.md > /tmp/keep.head
git show origin/main:AGENTS.md | sed -n '/dox:keep start/,/dox:keep end/p' > /tmp/keep.base
diff -u /tmp/keep.base /tmp/keep.head

diff non stampa nulla ed esce con codice 0 quando il blocco non è stato modificato. Qualsiasi output indica che il passaggio ha riscritto testo di proprietà delle persone, che devono quindi approvarlo o ripristinarlo. Il controllo funziona senza che nessuno debba ricordarsene.

Rigenerare nella pull request, non secondo una pianificazione

Il momento migliore per aggiornare un documento è il commit che lo rende errato. Inserisci il passaggio DOX nella stessa pull request della modifica strutturale: il diff resta abbastanza piccolo da poter essere letto davvero.

Un controllo bloccante che lo impone:

#!/usr/bin/env bash
set -euo pipefail
git fetch -q origin main
base=$(git merge-base origin/main HEAD)
changed=$(git diff --name-only "$base" HEAD)
if grep -qE '^(src|apps|packages)/' <<<"$changed" && ! grep -q 'AGENTS\.md$' <<<"$changed"; then
  echo "Code changed but no AGENTS.md was touched. Run a DOX pass, or say why not."
  exit 1
fi

Adatta i percorsi al tuo repository. Il vantaggio è che il controllo fallisce sul branch, dove la correzione è economica, e per un motivo su cui il reviewer può intervenire.

La pianificazione è il meccanismo di riserva, non quello principale. Un job settimanale rileva ciò che nessuno ha notato su un branch: file spostati da un rebase, un pacchetto eliminato in un merge o un documento che indica una directory non più esistente. Eseguilo su una macchina di piccole dimensioni, la stessa che potresti usare per eseguire un coding agent su un VPS, e configurala per aprire una pull request invece di eseguire il push su main.

#!/usr/bin/env bash
set -euo pipefail
cd /srv/src/myapp
git fetch -q origin
git switch -c "dox/refresh-$(date +%Y%m%d)" origin/main
# Your agent CLI goes on the next line, in whatever non-interactive mode it offers.
# Prompt: "Run a DOX pass over this repository. Change AGENTS.md files only."
git add '*AGENTS.md'
git commit -m "dox: refresh AGENTS.md tree" || { echo "nothing to refresh"; exit 0; }
git push -q -u origin HEAD
gh pr create --fill

Quel commento è volutamente un segnaposto. Ogni agent ha una propria CLI (command line interface) e un proprio flag non interattivo. Un comando copiato da una pagina Web che non corrisponde alla tua versione fallisce all'interno di cron, senza che nessuno veda l'errore. Completa il comando ed esegui manualmente lo script una volta prima di pianificarlo. Anche || exit 0 è importante: git commit restituisce un codice diverso da zero con nothing to commit, working tree clean quando l'albero è già aggiornato e, con set -e, questo verrebbe segnalato come un'esecuzione non riuscita.

Ogni passaggio consuma token, perché "Read Before Editing" impone all'agent di leggere l'intera catena per ogni attività. È il compromesso da accettare e vale la pena monitorarlo se stai già calcolando quanto costano le esecuzioni del tuo agent.

Monorepository: molti contratti, un solo indice

Un unico AGENTS.md nella root di un repository con quaranta pacchetti produce un diff di rigenerazione che nessuno legge e un documento in gran parte irrilevante per l'attività che l'agente sta svolgendo in quel momento. dox risponde con il Child DOX Index: la root contiene le regole comuni all'intero repository e rimanda ai file figli, mentre ogni confine stabile ha il proprio file. La struttura di questo albero e gli strumenti che leggono effettivamente i file annidati sono descritti in file AGENTS.md annidati per i monorepository.

dox modifica la superficie di revisione. Una pull request che modifica packages/api dovrebbe produrre un diff della documentazione all'interno di packages/api e in nessun altro punto:

git diff --stat -- '*AGENTS.md'

Se quel comando elenca sei file per una modifica limitata a un pacchetto, la struttura è errata. I confini sono troppo ampi oppure una regola che dovrebbe stare nella documentazione root è stata copiata in ogni elemento figlio. dox indica direttamente la correzione: le regole generali vanno nei documenti parent, i dettagli concreti nei documenti figli. Sono le regole duplicate a fare in modo che una modifica ordinaria riscriva tutto. Se le stesse regole si applicano davvero a repository separati, il problema è diverso e condividere le competenze degli agenti tra repository è lo strumento più adatto.

Esamina il diff come codice

Un diff della documentazione generato automaticamente può essere approvato facilmente senza leggerlo. È così che viene rilasciato un file errato. Esaminalo con la stessa attenzione che useresti per il codice generato e verifica quattro aspetti.

• un comando che il file ora indica e che dovresti eseguire personalmente prima del merge. Le istruzioni di build inventate sono il problema più comune.
• una riga eliminata che conteneva informazioni sull’intento. Le aggiunte costano poco. Le eliminazioni sono il punto in cui si perde informazione.
• un percorso assoluto, un hostname, un URL interno o qualsiasi elemento che abbia la forma di una credenziale
• una voce dell’inventario relativa a qualcosa che non esiste più; ls lo verifica in un secondo

Controlla quindi le dimensioni con wc -l AGENTS.md. Un file root che supera duecento righe indica che deve essere suddiviso, perché il valore dell’intera catena consiste nel fatto che l’agente legge solo la parte pertinente e non tutto il contenuto.

Quando si verificano problemi

Il pass ha eliminato il blocco di istruzioni. Il controllo diff riportato sopra stampa le righe rimosse. Ripristina il file dal punto di diramazione con git restore --source=origin/main AGENTS.md, quindi esegui nuovamente il pass specificando in modo più restrittivo le sezioni che può modificare.

Entrambi i branch sono stati rigenerati. Nel file trovi CONFLICT (content): Merge conflict in AGENTS.md e i marcatori di conflitto <<<<<<< HEAD. Non modificare manualmente i marcatori. Il file viene generato, quindi la risoluzione corretta consiste nell'eseguire nuovamente il pass sull'albero risultante dal merge.

L'agent ignora completamente il file. Verifica quale nome file legge effettivamente lo strumento. Se ne legge uno diverso, indirizzalo allo stesso contenuto con ln -s AGENTS.md CLAUDE.md e esegui il commit del symlink, così mantieni un'unica origine invece di due documenti che divergono nel tempo.

L'albero ha aggiunto elementi che nessuno ha indicizzato. Confronta l'output di find . -name AGENTS.md con le voci dell'indice nei documenti padre. Un elemento figlio non citato da alcun indice è un elemento che l'agent può ignorare completamente.

Quando un generatore è eccessivo

Un solo pacchetto, un solo comando di test e due persone che conoscono entrambe il repository: scrivete a mano le venti righe. Un file AGENTS.md di venti righe non diventa obsoleto abbastanza rapidamente da giustificare un albero, un indice, un controllo CI e un job settimanale. Rileggetelo quando modificate la build. Questo è l'intero costo di manutenzione ed è inferiore al costo dell'infrastruttura che lo circonda.

dox è utile quando il repository presenta confini che nessuna singola persona conosce a memoria: diversi pacchetti con regole differenti oppure contributor che iniziano a collaborare senza conoscere il contesto. Il valore non sta nel testo generato. Sta nel fatto che la documentazione diventa un elemento su cui una pull request può fallire, che è l'unico motivo per cui un file in un repository rimane aggiornato.

FAQ

Devo installare qualcosa per usare dox?

No. dox è un singolo file Markdown con licenza MIT e, all'11 agosto 2026, il repository non contiene package né release. Copiate il suo contenuto nel file AGENTS.md del progetto e il vostro coding agent seguirà le regole definite al suo interno. Fissate il commit copiato, f34ec7ad1055d3393887e5a2670e8cb7320c9165 al momento della stesura, e indicatelo nel messaggio di commit, così potrete determinare in seguito quale versione delle regole era applicata al vostro albero.

Come posso impedire che una rigenerazione elimini le regole scritte a mano?

Tenete separati intenti e inventario. Inserite il ragionamento che deve durare in un documento separato e racchiudete in un blocco contrassegnato tutto ciò che deve restare in AGENTS.md. Controllate quindi il blocco in CI: estraetelo dal branch e da origin/main con sed, confrontate i due risultati con diff e interrompete la build se rilevate differenze. Una persona approverà o revocherà quindi la modifica, invece di lasciarla passare inosservata all'interno di un diff esteso.

Con quale frequenza devo rigenerare AGENTS.md?

Nella pull request che lo rende errato. Una modifica strutturale e la relativa documentazione devono appartenere allo stesso diff, perché quello è l'unico momento in cui qualcuno dispone del contesto per esaminarli entrambi. Un'esecuzione pianificata settimanale è il meccanismo di riserva per il drift sfuggito a un branch e deve aprire una pull request invece di eseguire il commit su main.

I comandi di build devono trovarsi nel AGENTS.md radice o in un documento figlio?

Nel documento più vicino che li gestisce. Le regole valide per l'intero repository e l'indice dei documenti figli si trovano nella radice. Un comando applicabile a un solo package deve trovarsi nel relativo AGENTS.md. dox risolve i conflitti in base alla distanza: il documento più vicino controlla i dettagli locali e nessun documento figlio può indebolire una regola del padre. Copiare lo stesso comando in ogni documento figlio è ciò che porta un'esecuzione ordinaria a riscrivere l'intero albero.

dox è utile per un repository piccolo?

Di solito no. Un package con un solo comando di test e un AGENTS.md di venti righe si deteriora lentamente e può essere corretto nel minuto successivo alla rilevazione del problema. dox giustifica il proprio costo quando il repository presenta diversi confini con regole differenti o contributori privi del contesto necessario, perché in quel caso la catena di documenti svolge un'attività che nessuna singola persona sta svolgendo.