dox: mantieni aggiornato 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, quando il repository ha una determinata struttura. Poi cambia il test runner, un pacchetto viene rinominato, un servizio viene eliminato e il file continua a descrivere la situazione di giugno. Nulla fallisce, perché nessun passaggio della build lo legge.

L'agente lo legge e gli dà credito. È questo l'aspetto che può causare problemi. In un repository senza AGENTS.md, un coding agent esamina il progetto prima di agire. In un repository con un AGENTS.md errato, smette di esaminare il progetto perché ha già una risposta. Esegue il comando indicato dal file, la shell risponde Missing script: "test" e a quel punto l'agente inizia a fare supposizioni. Spesso modifica package.json per aggiungere lo script promesso dalla documentazione. Il file obsoleto non ha semplicemente smesso di funzionare. Ha provocato una modifica che non volevi.

dox è una possibile soluzione. È un insieme di regole scritte per l'agente, che rende l'aggiornamento della documentazione parte integrante del completamento 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, è distribuito con licenza MIT e, al 13 ottobre 2026, l’intero progetto consiste in un unico AGENTS.md da 3965 byte, un README, un LICENSE e due immagini. Non è necessario installare alcun pacchetto e non esiste alcun runtime.

Questo è importante, perché il termine generatore fa pensare a un programma che analizza il codice. dox non analizza il codice. dox è un contratto che il coding agent legge: l’agent è il generatore, mentre dox è l’insieme di istruzioni che gli indica quando leggere la documentazione, quando riscriverla e quale struttura deve avere ogni documento.

Il file contiene nove sezioni e due di esse svolgono il lavoro principale. "Read Before Editing" indica all’agent di partire dalla radice del repository e attraversare ogni percorso che intende modificare, leggendo ogni AGENTS.md lungo ciascun percorso, nella sessione corrente e senza affidarsi alla memoria. "Update After Editing" indica che ogni modifica significativa richiede un passaggio DOX, ovvero un aggiornamento della documentazione da eseguire prima di considerare conclusa l’attività. Il passaggio aggiorna il documento proprietario più vicino quando cambiano finalità, struttura, flusso operativo, autorizzazioni o preferenze dell’utente.

Il resto riguarda 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 radice contiene le regole valide per l’intero progetto e il Child DOX Index di primo livello, che consente all’agent di individuare i documenti figli. "Closeout" è la checklist che l’agent esegue al termine dell’attività: ricontrollare i percorsi 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 commit, non su main

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

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

wc -c dovrebbe stampare 3965. Un numero diverso indica che non hai scaricato il file descritto da questa guida, quindi leggilo prima di considerarlo attendibile. Se inserisci in modo errato l'hash del commit, -f interrompe curl con curl: (22) The requested URL returned error: 404 e non scrive alcun contenuto, mentre wc -c stampa 0. Un file troncato è peggiore dell'assenza del file, perché l'agente segue metà del contratto senza rendersene conto.

Se hai fissato il commit precedente, f34ec7a del 1 August 2026, controlla il relativo Child DOX Index. In quella versione la sezione descrive il repository di dox: indica che non sono necessari file AGENTS.md secondari ed elenca README.md, LICENSE e le due immagini come file di proprietà di root. Copiato nel tuo progetto, quell'indice descrive il repository sbagliato. La revisione del 1 September lo ha sostituito con un segnaposto che indica che il progetto non è ancora indicizzato e ordina all'agente di analizzare il repository e creare l'albero prima di continuare. Sostituisci la vecchia sezione con l'indice effettivo oppure con il nuovo segnaposto.

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

Quel cp è destinato a un repository che non contiene ancora AGENTS.md. Se ne hai già uno, non sovrascriverlo. Inserisci le sezioni di dox prima del 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 agente che segue la riga letta per ultima.

Poi chiedi all'agente di eseguire il primo passaggio all'interno del repository. Il README riporta la formulazione esatta:

Initialize DOX tree for this project now.

Crea i file AGENTS.md secondari e gli indici che li referenziano. Chiederlo esplicitamente è comunque utile, anche se l'indice segnaposto ordina all'agente di farlo prima di qualsiasi altra attività: ottieni l'intero albero in un commit verificabile, invece di crearlo come effetto collaterale di un'attività non correlata. Controlla ciò che ha fatto prima di considerarlo corretto:

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

Ogni file nell'output find dovrebbe comparire in un Child DOX Index in una sezione precedente. Un documento secondario non menzionato da alcun indice può sfuggire all'agente, perché l'indice è il modo in cui individua i documenti che non si trovano direttamente nel 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 inserito nell’inventario: la struttura delle directory, i manifest dei pacchetti e i lockfile, gli script in package.json o 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 aggiorna autonomamente. Quando un pacchetto viene spostato, l’esecuzione successiva sposta anche la riga che lo descrive.

Tutto ciò che segue spetta a te definirlo, perché non si trova nel repository e quindi non può essere letto:

• perché esiste una regola, cioè ciò che impedisce a un agente di rimuoverla considerandola complessità non necessaria
• 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 due versioni precedenti
• ciò che prevedi di fare la prossima settimana, che costituisce la differenza tra un file aggiornato e un file utile

dox conosce questo limite. Le sue regole stabiliscono che Work Guidance deve riflettere gli standard correnti del progetto o le istruzioni dell’utente e che, se non ne esistono ancora, la sezione deve essere lasciata vuota. Verification deve riflettere un controllo esistente. Se nel repository non è presente alcun framework di verifica, la sezione resta vuota finché non ne viene aggiunto uno. Un file generato che inventa uno standard è peggiore di una sezione vuota, perché in seguito l’agente applicherà lo standard inventato.

Non includere le intenzioni scritte a mano nell’inventario generato

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 rigenera il file e il paragrafo scompare all’interno di un diff di quaranta righe che cambia soprattutto l’ordine dei nomi dei file. Nessuno se ne accorge.

Servono due meccanismi, entrambi.

Per prima cosa, sposta le intenzioni durature in un file separato. 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 nel file in cui separi HUMAN.md da AGENTS.md. AGENTS.md contiene quindi l’inventario e i contratti locali, cioè la parte che deve cambiare quando cambia il codice.

In secondo luogo, delimita le intenzioni 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 elimini fallisca in modo evidente. Esegui questo controllo in CI (continuous integration) per 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 è invariato. Qualsiasi output indica che il passaggio ha riscritto testo di proprietà delle persone; una persona deve quindi approvare la modifica oppure ripristinarla. Il controllo funziona senza che nessuno debba ricordarsene.

Rigenera sulla pull request, non in base a un timer

Il momento migliore per aggiornare un documento è il commit che lo rende errato. Inserisci il passaggio DOX nella stessa pull request della modifica strutturale. In questo modo 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 revisore può intervenire.

La pianificazione è il piano di riserva, non il meccanismo principale. Un job settimanale rileva ciò che nessuno ha notato su un branch: file spostati da un rebase, un pacchetto eliminato durante un merge, un documento che fa riferimento a una directory non più esistente. Eseguilo su una macchina di piccole dimensioni, la stessa che potresti usare per eseguire un agente di coding su un VPS, e configuralo in modo che apra 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 agente ha una propria CLI (interfaccia a riga di comando) e un proprio flag non interattivo. Un comando copiato da una pagina web che non corrisponde alla tua versione fallisce all'interno di cron, dove nessuno vede l'errore. Completa il comando ed esegui manualmente lo script una volta prima di pianificarlo. Anche || exit 0 è importante: git commit termina con un codice diverso da zero usando 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" richiede all'agente di leggere l'intera catena a ogni attività. Questo è il compromesso. Se stai già contando quanto costano le esecuzioni del tuo agente, vale la pena monitorarlo.

Monorepository: molti contratti, un solo indice

Un unico file AGENTS.md alla radice 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. La soluzione in dox è il Child DOX Index: la radice contiene le regole valide per l'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'altra posizione:

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

Se quel comando elenca sei file per una modifica relativa a un solo pacchetto, la struttura dell'albero non è corretta. I confini sono troppo ampi oppure una regola che dovrebbe stare nella documentazione radice è stata copiata in ogni file figlio. dox indica direttamente la correzione: le regole generali vanno nei documenti parent, mentre i dettagli concreti vanno nei documenti figli. Sono le regole duplicate a fare in modo che un passaggio ordinario riscriva tutto. Se le stesse regole si applicano realmente a repository separati, si tratta di un problema diverso e condividere le competenze degli agenti tra repository è lo strumento più adatto.

Rivedi il diff come codice

Un diff della documentazione generato automaticamente è facile da approvare senza leggerlo. È così che viene pubblicato un file errato. Esaminalo con la stessa attenzione che useresti per il codice generato e cerca quattro elementi.

• un comando che ora compare nel file e che dovresti eseguire personalmente prima del merge. Le istruzioni di build inventate sono l’errore più comune.
• una riga eliminata che conteneva informazioni sull’intento. Le aggiunte costano poco. La perdita si verifica nelle eliminazioni.
• 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ù, verifica che ls risolve in un secondo

Controlla poi le dimensioni con wc -l AGENTS.md. Un file root che supera duecento righe indica che dovrebbe essere suddiviso, perché il valore principale della catena consiste nel fatto che l’agente legge solo la parte pertinente e non l’intero contenuto.

Quando si verifica un problema

Il pass ha eliminato il blocco di istruzioni. Il controllo diff riportato sopra mostra le righe rimosse. Ripristina il file dal punto di diramazione con git restore --source=origin/main AGENTS.md, quindi esegui di nuovo il pass con un'istruzione più restrittiva che specifichi le sezioni che può modificare.

Due branch sono stati rigenerati entrambi. 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 un nuovo pass sull'albero risultante dall'unione.

L'agente ignora completamente il file. Controlla quale nome file legge effettivamente lo strumento. Se ne legge uno diverso, indirizzalo allo stesso contenuto con ln -s AGENTS.md CLAUDE.md e salva il symlink nel commit, così mantieni un'unica origine invece di due documenti che si discostano nel tempo. Se il nome file è già corretto ma le regole continuano a essere ignorate, esegui la diagnosi perché gli agenti di codifica ignorano le istruzioni prima di riscrivere nuovamente il documento.

L'albero ha aggiunto elementi figli che nessuno ha indicizzato. Confronta l'output di find . -name AGENTS.md con le voci dell'indice nei documenti padre. Se nessun indice menziona un elemento figlio, l'agente può ignorarlo completamente.

Quando un generatore è eccessivo

Un solo package, 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 è tutto il lavoro di manutenzione richiesto, ed è inferiore al costo dell'apparato che lo gestisce.

Vale la pena usare dox quando il repository presenta confini che nessuna singola persona conosce completamente: diversi package con regole differenti oppure contributori che arrivano senza il contesto necessario. Il valore non sta nel testo generato. Sta nel fatto che la documentazione diventa un elemento su cui una pull request può fallire; ed è l'unico motivo per cui un file in un repository rimane aggiornato.

FAQ

Devo installare qualcosa per usare dox?

No. dox è un unico file Markdown, distribuito con licenza MIT e, al 13 ottobre 2026, il repository non contiene pacchetti né release. È sufficiente copiare il contenuto nel file AGENTS.md del progetto: l'agente di coding applicherà le regole indicate. Blocca il commit copiato, 765ae4ac02cc884eefcd41a3d0f71941721adb89 al momento della stesura, e riportalo nel messaggio di commit, così in seguito potrai identificare la versione delle regole in base alla quale è stato creato il tuo albero di lavoro.

Come posso impedire che una rigenerazione elimini le regole scritte manualmente?

Tieni separati l'intento e l'inventario. Inserisci il ragionamento duraturo in un documento separato e racchiudi in un blocco contrassegnato tutto ciò che deve rimanere in AGENTS.md. Controlla quindi il blocco in CI: estrailo dal branch e da origin/main con sed, confronta i due risultati con diff e interrompi la build se rilevi differenze. A quel punto una persona approverà o ripristinerà 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 obsoleto o non corretto. Una modifica strutturale e la relativa documentazione devono appartenere allo stesso diff, perché quello è l'unico momento in cui qualcuno dispone del contesto necessario per esaminarle entrambe. Un controllo pianificato settimanale serve come verifica aggiuntiva per il drift sfuggito a un branch e dovrebbe aprire una pull request, invece di eseguire il commit direttamente su main.

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

Nel documento più vicino all'ambito che li definisce. Le regole valide per l'intero repository e l'indice dei documenti figli si trovano nella root. Un comando applicabile a un solo pacchetto deve trovarsi nel relativo AGENTS.md. Quando i documenti sono in conflitto, dox consente al documento più vicino di controllare i dettagli del lavoro locale; l'unico elemento che un documento figlio non può indebolire è il contratto DOX. Inserisci le regole generali nei documenti padre e i dettagli concreti nei documenti figli. Copiare lo stesso comando in ogni documento figlio è ciò che fa riscrivere l'intero albero durante un normale passaggio di manutenzione.

dox è utile per un repository di piccole dimensioni?

Di solito no. Un pacchetto con un solo comando di test e un AGENTS.md di venti righe si deteriora lentamente e puoi correggerlo nel minuto successivo a quello in cui te ne accorgi. 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 lavoro che nessuna singola persona sta svolgendo.