AGENTS.md automatisch up-to-date houden met dox

Waarom uw AGENTS.md na drie weken verouderd is

Een AGENTS.md-bestand raakt verouderd omdat er geen koppeling is met de code. U schrijft het eenmalig, handmatig, op de dag dat de repository er op een bepaalde manier uitziet. Vervolgens verandert de test-runner, wordt een pakket hernoemd of een service verwijderd, terwijl het bestand nog steeds de situatie van juni beschrijft. Er treedt geen fout op, omdat geen enkele build-stap het bestand leest.

De agent leest het bestand en vertrouwt erop. Dat is het onderdeel dat u geld kost. Een repository zonder AGENTS.md dwingt een coding agent om eerst rond te kijken voordat deze actie onderneemt. Een repository met een onjuist AGENTS.md zorgt ervoor dat de agent stopt met zoeken, omdat deze al een antwoord heeft. De agent voert het commando uit dat in uw bestand staat, de shell antwoordt met Missing script: "test", en vervolgens begint de agent te gokken. Vaak bewerkt de agent package.json om het script toe te voegen dat uw documentatie beloofde. Het verouderde bestand faalde niet geruisloos. Het veroorzaakte een wijziging die u niet wilde.

dox is hiervoor een oplossing. Het is een set regels, geschreven voor de agent, die het bijwerken van de documentatie onderdeel maakt van het afronden van het werk. Hierdoor wordt het bestand in dezelfde commit gewijzigd als de code die het verouderd maakte.

Wat dox is, en wat het niet is

dox is een enkel Markdown-bestand. De repository is agent0ai/dox, het is MIT-gelicentieerd en per 11 augustus 2026 bestaat het gehele project uit één AGENTS.md van 3906 bytes, een README, een LICENSE en twee afbeeldingen. Er is geen pakket om te installeren en er is geen runtime.

Dat is van belang, omdat de term generator suggereert dat het een programma is dat uw code parseert. Niets parseert uw code. dox is een contract dat uw coding agent leest: uw agent is de generator, en dox is de instructieset die aangeeft wanneer de documentatie gelezen moet worden, wanneer deze herschreven moet worden en welke vorm elk document aanneemt.

Het bestand bevat tien secties en twee daarvan verrichten het werk. "Read Before Editing" instrueert de agent om vanaf de root van de repository naar elk pad te navigeren dat het van plan is te wijzigen, en om tijdens de huidige sessie elk AGENTS.md langs die route te lezen, zonder te vertrouwen op het geheugen. "Update After Editing" geeft aan dat elke betekenisvolle wijziging een DOX-pass vereist, wat betekent dat een stap voor het bijwerken van de documentatie moet worden uitgevoerd voordat de taak als voltooid wordt beschouwd. De pass werkt het dichtstbijzijnde eigendomsdocument bij wanneer het doel, de structuur, de workflow, de rechten of de gebruikersvoorkeuren zijn gewijzigd.

De rest is vorm. Een onderliggend AGENTS.md heeft een standaardvolgorde voor secties: Doel, Eigenaarschap, Lokale Contracten, Werkinstructies, Verificatie en Index van onderliggende DOX. Het root-bestand bevat projectbrede regels plus de bovenliggende Index van onderliggende DOX, waarmee een agent de onderliggende documenten ontdekt. "Closeout" is de checklist die de agent aan het einde van een taak doorloopt: controleer de gewijzigde paden opnieuw aan de hand van de keten, werk de dichtstbijzijnde eigendomsdocumenten bij, ververs elke beïnvloede index, verwijder tegenstrijdigheden, voer bestaande verificatie uit en rapporteer welke documenten bewust ongewijzigd zijn gelaten.

Pin dox aan één commit, niet aan main

De repository bevat geen tags of releases, dus er is geen versienummer om vast te pinnen. Pin in plaats daarvan de commit. De huidige AGENTS.md is commit f34ec7ad1055d3393887e5a2670e8cb7320c9165, gedateerd 1 augustus 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 hoort 3906 te tonen. Een ander nummer betekent dat u niet het bestand heeft opgehaald dat deze handleiding beschrijft; lees het dus voordat u het vertrouwt. Als u de commit-hash verkeerd typt, zorgt -f ervoor dat curl stopt met curl: (22) The requested URL returned error: 404 en geen inhoud schrijft, waarna wc -c vervolgens 0 toont. Een afgebroken bestand is slechter dan geen bestand, omdat de agent dan een half contract volgt zonder dat hij dit weet.

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

Die cp is bedoeld voor een repository die nog geen AGENTS.md heeft. Als u er al een heeft, overschrijf deze dan niet. Plaats de dox-secties boven uw bestaande inhoud, behoud uw eigen regels daaronder en lees het resultaat één keer van begin tot eind door. Twee documenten die elkaar tegenspreken, resulteren in een agent die de regel volgt die hij als laatste heeft gelezen.

Vraag uw agent vervolgens, binnen de repository, om de eerste pass. De README bevat de exacte bewoording:

Initialize DOX tree for this project now.

Dit creëert de onderliggende AGENTS.md-bestanden en de indexen die ernaar verwijzen. Controleer wat er is gebeurd voordat u het resultaat vertrouwt:

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

Elk bestand in die find-output hoort ergens daarboven in een Child DOX Index voor te komen. Een onderliggend document dat in geen enkele index wordt genoemd, is een document dat de agent kan missen, omdat de index de manier is waarop hij documenten vindt die niet direct op het pad staan dat hij doorloopt.

Wat dox kan zien en wat het niet kan weten

De agent die uw boomstructuur opbouwt, leest de repository. Alles in de repository kan daarom in de inventaris terechtkomen: de mappenstructuur, package manifests en lockfiles, de scripts in package.json of Makefile of pyproject.toml, CI-workflowbestanden, Dockerfiles, entry points en CODEOWNERS als u die heeft. Een inventaris die op basis daarvan is opgebouwd, onderhoudt zichzelf oprecht. Wanneer een pakket wordt verplaatst, verplaatst de volgende run de regel die het beschrijft.

Alles hieronder moet u zelf aangeven, omdat het niet in de repository staat om gelezen te worden:

• waarom een regel bestaat; dit voorkomt dat een agent deze verwijdert als zijnde onnodige complexiteit
• welk van twee werkende paden wordt ondersteund en welke wacht op verwijdering
• alles buiten de repository, zoals de staging-omgeving of de reden waarom een dependency twee versies terug is vastgezet
• wat u volgende week van plan bent; dit is het verschil tussen een bestand dat actueel is en een bestand dat nuttig is

dox weet dit over zichzelf. De eigen regels stellen dat Work Guidance de huidige standaarden van het project of de instructies van de gebruiker moet weerspiegelen, en dat u de sectie leeg laat als er nog geen zijn. Verification moet een bestaande controle weerspiegelen; als er geen testframework in de repo aanwezig is, blijft die sectie leeg totdat er een is. Een gegenereerd bestand dat een standaard verzint, is slechter dan een lege sectie, omdat de agent het verzinsel vervolgens zal afdwingen.

Houd handgeschreven intentie buiten de gegenereerde inventaris

Dit is de fout waardoor mensen afhaken bij gegenereerde documentatie. U schrijft een alinea waarin wordt uitgelegd dat de takenwachtrij een single-consumer moet blijven. Drie weken later herschrijft een proces het bestand en is uw alinea verdwenen, verborgen in een diff van veertig regels die voornamelijk bestandsnamen husselen, en niemand merkt het op.

Er zijn twee mechanismen nodig, en u wilt ze allebei gebruiken.

Ten eerste, verplaats duurzame intentie naar een ander bestand. Ontwerpbeslissingen en de redenering daarachter horen thuis in een DESIGN.md geschreven voor de agent, en de notities die bedoeld zijn voor mensen horen thuis waar u HUMAN.md afsplitst van AGENTS.md. AGENTS.md bevat vervolgens de inventaris en de lokale contracten; dit is precies het deel dat moet veranderen wanneer de code verandert.

Ten tweede, scherm de intentie af die in AGENTS.md moet blijven staan. Omvat het blok met markers en behandel het blok als eigendom van de mens:

## 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 -->

Markdown-commentaren worden niet weergegeven op de pagina, maar de agent leest ze nog steeds. Maak het behoud van het blok controleerbaar, zodat een proces dat het blok verwijdert, luidruchtig faalt. Voer dit uit in CI (continuous integration) bij elke 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 print niets en sluit af met status 0 wanneer het blok ongewijzigd is. Elke output betekent dat het proces door mensen beheerde tekst heeft herschreven, waardoor een persoon het moet goedkeuren of ongedaan moet maken. De controle blijft behouden zonder dat iemand eraan hoeft te denken.

Regenereren via de pull request, niet op basis van een timer

Het beste moment om een document te verversen is bij de commit die het document onjuist maakt. Voeg de DOX-stap toe aan dezelfde pull request als de structurele wijziging; zo blijft de diff klein genoeg om daadwerkelijk te kunnen lezen.

Een blokkerende controle die dit afdwingt:

#!/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

Pas de paden aan naar uw repository. Het voordeel is dat het proces faalt op de branch, waar de correctie eenvoudig is, en het faalt om een reden waar een reviewer actie op kan ondernemen.

Een planning is de back-up, niet het mechanisme. Een wekelijkse taak vangt op wat niemand op een branch heeft opgemerkt: bestanden die zijn verplaatst door een rebase, een pakket dat is verwijderd tijdens een merge, of een document dat verwijst naar een directory die niet meer bestaat. Voer dit uit op een kleine server, dezelfde als die u wellicht gebruikt om een coding agent op een VPS te draaien, en laat deze een pull request openen in plaats van direct naar main te pushen.

#!/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

Dat commentaar is bewust een tijdelijke aanduiding. Elke agent heeft zijn eigen CLI (command line interface) en zijn eigen non-interactive flag. Een commando dat van een webpagina is gekopieerd en niet overeenkomt met uw versie, faalt binnen cron waar niemand de fout ziet. Vul het in en voer het script eenmaal handmatig uit voordat u het inplant. De || exit 0 is ook van belang: git commit sluit af met een non-zero status met nothing to commit, working tree clean wanneer de tree al up-to-date is, en onder set -e zou dat een geslaagde run als een fout rapporteren.

Elke run kost tokens, omdat "Read Before Editing" de agent de hele keten bij elke taak laat lezen. Dat is de afweging, en het is de moeite waard om dit in de gaten te houden als u al bijhoudt wat uw agent kost.

Monorepo's: veel contracten, één index

Eén root AGENTS.md in een repository met veertig pakketten produceert een regeneratie-diff die niemand leest, en een document dat grotendeels irrelevant is voor wat de agent op dat moment uitvoert. Het antwoord van dox is de Child DOX Index: de root bevat repository-brede regels en verwijst naar de onderliggende onderdelen, waarbij elke duurzame grens zijn eigen bestand beheert. Hoe u die boomstructuur opzet en welke tools geneste bestanden überhaupt lezen, wordt behandeld in geneste AGENTS.md bestanden voor monorepo's.

Wat dox verandert, is het beoordelingsoppervlak. Een pull request dat packages/api wijzigt, zou een documentatie-diff moeten produceren binnen packages/api en nergens anders:

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

Als dat commando zes bestanden vermeldt voor een wijziging in één pakket, dan is de boomstructuur onjuist. Of de grenzen zijn te grofmazig, of een regel die in de root thuishoort is naar elk kind gekopieerd. dox geeft de oplossing direct aan: brede regels horen in ouder-documenten, concrete details in kind-documenten. Gedupliceerde regels zorgen ervoor dat een routine-pass alles herschrijft. Als dezelfde regels daadwerkelijk van toepassing zijn op verschillende repositories, is dat een ander probleem, en is agentvaardigheden delen tussen repositories daarvoor de betere tool.

Controleer de diff als code

Een gegenereerde documentatie-diff wordt gemakkelijk goedgekeurd zonder deze te lezen, waardoor een onjuist bestand wordt uitgebracht. Lees de diff met dezelfde argwaan als bij gegenereerde code en let op de volgende vier punten:

• een commando dat in het bestand wordt genoemd; voer dit zelf uit voordat u de wijzigingen samenvoegt. Verzonnen bouwinstructies zijn de meest voorkomende fout.
• een verwijderde regel die een specifieke bedoeling had. Toevoegingen zijn eenvoudig. Bij verwijderingen treedt het verlies op.
• een absoluut pad, een hostnaam, een interne URL of iets dat lijkt op een inloggegeven.
• een inventarisitem voor iets dat niet langer bestaat, wat ls in een seconde oplost.

Controleer vervolgens de omvang met wc -l AGENTS.md. Een root-bestand van meer dan tweehonderd regels is een teken dat het gesplitst moet worden, omdat de waarde van de keten er juist in ligt dat de agent het kleine, relevante deel leest in plaats van alles.

Wanneer het misgaat

De pass heeft uw intentieblok verwijderd. De diff-controle hierboven toont de verwijderde regels. Herstel het bestand vanaf het branch-punt met git restore --source=origin/main AGENTS.md en voer de pass opnieuw uit met een specifiekere instructie die de secties benoemt die gewijzigd mogen worden.

Twee branches zijn beide opnieuw gegenereerd. U krijgt CONFLICT (content): Merge conflict in AGENTS.md en conflictmarkeringen <<<<<<< HEAD in het bestand. Bewerk de markeringen niet handmatig. Het bestand wordt gegenereerd, dus de juiste oplossing is een nieuwe pass over de samengevoegde boomstructuur.

De agent negeert het bestand volledig. Controleer welke bestandsnaam uw tool daadwerkelijk leest. Als deze een ander bestand leest, verwijs dan naar dezelfde inhoud met ln -s AGENTS.md CLAUDE.md en commit de symlink, zodat u één bron behoudt in plaats van twee documenten die uit elkaar gaan lopen. Als de bestandsnaam correct is en de regels nog steeds worden overgeslagen, voer dan de diagnose uit voor waarom coding agents uw instructies negeren voordat u het document opnieuw schrijft.

De boomstructuur heeft kinderen gekregen die niemand heeft geïndexeerd. Vergelijk de find . -name AGENTS.md-uitvoer met de indexvermeldingen in de bovenliggende documenten. Een kind dat in geen enkele index wordt genoemd, is een kind waar de agent simpelweg aan voorbijloopt.

Wanneer een generator overbodig is

Eén pakket, één testcommando, twee personen die de repository kennen: schrijf de twintig regels met de hand. Een AGENTS.md van twintig regels veroudert niet snel genoeg om een boomstructuur, een index, een CI-check en een wekelijkse taak te rechtvaardigen. Lees het opnieuw wanneer u de build aanpast. Dat zijn de enige onderhoudskosten, en deze zijn lager dan de kosten van de infrastructuur eromheen.

dox is de moeite waard wanneer de repository grenzen heeft die niemand volledig in zijn hoofd heeft: meerdere pakketten met verschillende regels, of bijdragers die zonder achtergrondkennis beginnen. De waarde zit niet in de gegenereerde tekst. De waarde zit in het feit dat de documentatie iets wordt waarop een pull request kan falen, wat de enige reden is waarom een bestand in een repository actueel blijft.

FAQ

Moet ik iets installeren om dox te gebruiken?

Nee. dox is één Markdown-bestand, uitgebracht onder de MIT-licentie, en sinds 11 augustus 2026 bevat de repository geen pakketten en worden er geen releases uitgebracht. U kopieert de inhoud naar het bestand AGENTS.md van uw project en uw coding agent volgt vanaf dat moment de regels. Pin de commit die u heeft gekopieerd, f34ec7ad1055d3393887e5a2670e8cb7320c9165 op het moment van schrijven, en vermeld deze in uw commit-bericht zodat u later kunt achterhalen met welke versie van de regels uw tree is gebouwd.

Hoe voorkom ik dat een regeneratie mijn handgeschreven regels verwijdert?

Houd intentie en inventaris gescheiden. Duurzame redeneringen horen in een apart document, en alles wat in AGENTS.md moet blijven staan, plaatst u binnen een gemarkeerd blok. Controleer dit blok vervolgens in CI: extraheer het uit de branch en uit origin/main met sed, vergelijk beide met diff, en laat de build falen bij elk verschil. Een persoon keurt de wijziging vervolgens goed of draait deze terug, in plaats van dat deze onopgemerkt in een grote diff wordt doorgevoerd.

Hoe vaak moet ik AGENTS.md regenereren?

Bij de pull request die de inhoud onjuist maakt. Een structurele wijziging en de bijbehorende documentatie horen in één diff, omdat dat het enige moment is waarop iemand de context heeft om beide te beoordelen. Een wekelijkse geplande taak dient als back-up voor afwijkingen die aan een branch zijn ontsnapt, en deze moet een pull request openen in plaats van direct naar main te committen.

Moeten build-commando's in de root AGENTS.md staan of in een onderliggend bestand?

In het dichtstbijzijnde document dat ze beheert. Regels voor de gehele repository en de index van onderliggende bestanden staan in de root. Een commando dat van toepassing is op één pakket staat in het AGENTS.md van dat pakket. dox lost conflicten op basis van afstand op: het dichtstbijzijnde document bepaalt lokale details, en geen enkel onderliggend document mag een regel van een bovenliggend document afzwakken. Het kopiëren van hetzelfde commando naar elk onderliggend bestand is precies wat ervoor zorgt dat een routine-pass de hele tree herschrijft.

Is dox de moeite waard voor een kleine repository?

Meestal niet. Eén pakket met één testcommando en een AGENTS.md van twintig regels veroudert langzaam, en u kunt dit binnen een minuut herstellen zodra u het opmerkt. dox verdient zijn investering wanneer de repository meerdere grenzen met verschillende regels heeft, of bijdragers die de achtergrond missen; in dat geval doet de keten van documenten werk dat geen enkel individu in zijn eentje kan doen.