AGENTS.md automatisch bijwerken met dox

Waarom uw AGENTS.md na drie weken niet meer klopt

Een AGENTS.md-bestand veroudert 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 punt dat u tijd 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 denkt al een antwoord te hebben. 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 ervoor zorgt dat het bijwerken van de documentatie onderdeel wordt van het afronden van het werk. Hierdoor wordt het bestand in dezelfde commit gewijzigd als de code die het bestand 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 de agent vertelt 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 lopen dat het van plan is te wijzigen, en om elk AGENTS.md langs die route te lezen, in de huidige sessie, 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 standaard sectievolgorde: Purpose, Ownership, Local Contracts, Work Guidance, Verification en Child DOX Index. Het root-bestand bevat projectbrede regels plus de Child DOX Index op het hoogste niveau; dit is hoe 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 heeft geen tags of releases, dus er is geen versienummer om aan 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 de melding 0 geeft. Een afgebroken bestand is slechter dan geen bestand, omdat de agent dan een half contract volgt zonder dat te weten.

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

Dat 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 boven naar beneden 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 er een die de agent kan missen, omdat de index de manier is waarop hij documenten vindt die niet direct op het pad liggen 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, pakketmanifesten 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 hiervan 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 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 van zichzelf. De eigen regels stellen dat Werkrichtlijnen de huidige standaarden van het project of de instructies van de gebruiker moeten weerspiegelen, en dat u de sectie leeg laat als er nog geen zijn. Verificatie 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 het falen 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 herschikken, en niemand merkt het op.

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

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 voor mensen bedoeld zijn, horen op de plek waar u HUMAN.md afsplitst van AGENTS.md. AGENTS.md bevat dan de inventaris en de lokale contracten; dit is precies het deel dat moet veranderen wanneer de code verandert.

Ten tweede, scherm de intentie die in AGENTS.md moet blijven staan af. Plaats deze tussen 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, en de agent leest ze nog steeds. Maak nu de overleving van het blok controleerbaar, zodat een proces dat het 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 0 wanneer het blok ongewijzigd is. Elke output betekent dat het proces door mensen beheerde tekst heeft herschreven, zodat een persoon dit moet goedkeuren of ongedaan moet maken. De controle blijft behouden zonder dat iemand eraan hoeft te denken.

Regenerate on the pull request, not on a timer

The best moment to refresh a document is the commit that makes it wrong. Put the DOX pass in the same pull request as the structural change and the diff stays small enough to actually read.

A blocking check that enforces it:

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

Adjust the paths to your repository. The value is that it fails on the branch, where the fix is cheap, and it fails for a reason a reviewer can act on.

A schedule is the backup, not the mechanism. A weekly job catches what nobody noticed on a branch: files moved by a rebase, a package deleted in a merge, a document naming a directory that no longer exists. Run it on a small box, the same one you might use to run a coding agent on a VPS, and have it open a pull request instead of pushing to 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

That comment is a placeholder on purpose. Every agent has its own CLI (command line interface) and its own non-interactive flag, and a command copied from a web page that does not match your version fails inside cron where nobody sees the error. Fill it in and run the script by hand once before you schedule it. The || exit 0 matters too: git commit exits non-zero with nothing to commit, working tree clean when the tree is already current, and under set -e that would report a healthy run as a failure.

Every pass costs tokens, because "Read Before Editing" makes the agent read the whole chain on each task. That is the trade, and it is worth watching if you are already counting what your agent runs cost.

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 doet. Het antwoord van dox is de Child DOX Index: de root bevat regels voor de gehele repository en verwijst naar de onderliggende onderdelen, waarbij elke duurzame grens zijn eigen bestand beheert. Hoe deze boomstructuur moet worden opgezet en welke tools geneste bestanden überhaupt kunnen lezen, wordt behandeld in geneste AGENTS.md bestanden voor monorepo's.

Wat dox verandert, is het oppervlak voor beoordeling. 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 weergeeft 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 gekopieerd naar elk kind. dox geeft de oplossing direct aan: brede regels horen in documenten van de parent, concrete details horen in documenten van de child. Gedupliceerde regels zorgen ervoor dat een routine-pass alles herschrijft. Als dezelfde regels daadwerkelijk van toepassing zijn op verschillende repositories, dan 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 vier zaken.

• 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 inventarisvermelding voor iets dat niet langer bestaat, wat ls in een seconde afhandelt.

Controleer vervolgens de omvang met wc -l AGENTS.md. Een root-bestand van meer dan tweehonderd regels is een signaal om het op te splitsen, omdat de waarde van de keten erin 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 aangepast 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. Omdat het bestand gegenereerd is, is de juiste oplossing 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. Zo behoudt u één bron in plaats van twee documenten die uit elkaar gaan lopen.

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 tree, 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 investering waard wanneer de repository grenzen bevat die niemand volledig in zijn hoofd heeft: meerdere pakketten met verschillende regels, of bijdragers die zonder achtergrondkennis instromen. 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; dit is de enige reden waarom een bestand in een repository actueel blijft.

FAQ

Moet ik iets installeren om dox te gebruiken?

Nee. dox is één Markdown-bestand, MIT-gelicentieerd, en per 11 augustus 2026 bevat de repository geen pakketten en geen releases. U kopieert de inhoud naar het bestand AGENTS.md van uw project en uw coding agent volgt de regels die daarin staan. 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 het 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 meegenomen.

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 dezelfde diff, omdat dat het enige moment is waarop iemand de context heeft om beide te beoordelen. Een wekelijkse geplande run dient als back-up voor afwijkingen die aan een branch zijn ontsnapt, en deze hoort een pull request te openen in plaats van direct naar main te committen.

Horen build-commando's in de root AGENTS.md of in een subdocument te staan?

In het dichtstbijzijnde document dat ze beheert. Regels voor de gehele repository en de index van subdocumenten 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 document dat het dichtstbij staat, bepaalt de lokale details, en geen enkel subdocument mag een regel van een bovenliggend document afzwakken. Het kopiëren van hetzelfde commando naar elk subdocument is precies wat ervoor zorgt dat een routine-run 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 vervalt 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, omdat de keten van documenten dan werk verricht dat geen enkel individu alleen kan doen.