AGENTS.md mit dox automatisch aktuell halten

Warum Ihre AGENTS.md drei Wochen später falsch ist

Eine AGENTS.md-Datei veraltet, weil sie nicht mit dem Code verknüpft ist. Sie schreiben sie einmal von Hand, an dem Tag, an dem das Repository auf eine bestimmte Weise aussieht. Dann ändert sich der Test-Runner, ein Paket wird umbenannt, ein Dienst wird gelöscht, und die Datei beschreibt weiterhin den Stand vom Juni. Nichts schlägt fehl, weil kein Build-Schritt die Datei liest.

Der Agent liest die Datei und vertraut auf ihren Inhalt. Genau das verursacht die Probleme. In einem Repository ohne AGENTS.md sieht sich ein Coding-Agent zunächst um, bevor er handelt. In einem Repository mit einer falschen AGENTS.md hört er auf zu suchen, weil er bereits eine Antwort hat. Er führt den in Ihrer Datei genannten Befehl aus, und die Shell antwortet mit Missing script: "test". Danach beginnt der Agent zu raten. Häufig bearbeitet er package.json, um das in Ihrer Dokumentation versprochene Script hinzuzufügen. Die veraltete Datei blieb nicht unbemerkt. Sie führte zu einer Änderung, die Sie nicht wollten.

dox ist eine Antwort darauf. Es besteht aus Regeln für den Agenten, die das Aktualisieren der Dokumentation zu einem Bestandteil des Abschlusses der Arbeit machen. Dadurch wird die Datei im selben Commit wie der Code geändert, durch den sie falsch geworden ist.

Was dox ist und was es nicht ist

dox ist eine einzelne Markdown-Datei. Das Repository ist agent0ai/dox, steht unter der MIT-Lizenz und besteht am 11 August 2026 aus dem 3906-Byte-AGENTS.md, einer README, einer LICENSE und zwei Bildern. Es gibt kein zu installierendes Paket und keine Laufzeitumgebung.

Das ist wichtig, weil der Begriff Generator ein Programm nahelegt, das Ihren Code analysiert. Ihr Code wird von nichts analysiert. dox ist ein Vertrag, den Ihr Coding-Agent liest: Ihr Agent ist der Generator, und dox ist der Anweisungssatz, der ihm vorgibt, wann er die Dokumentation lesen, wann er sie neu schreiben und welche Struktur jedes Dokument haben soll.

Die Datei enthält zehn Abschnitte, von denen zwei die eigentliche Arbeit erledigen. „Read Before Editing“ weist den Agenten an, vom Repository-Root zu jedem Pfad zu gehen, den er ändern will, und entlang jedes Pfads jede AGENTS.md in der aktuellen Sitzung zu lesen, ohne sich auf sein Gedächtnis zu verlassen. „Update After Editing“ legt fest, dass jede relevante Änderung einen DOX-Durchlauf erfordert. Das bedeutet, dass vor dem Abschluss der Aufgabe ein Schritt zur Aktualisierung der Dokumentation ausgeführt werden muss. Der Durchlauf aktualisiert das nächstgelegene zuständige Dokument, wenn sich Zweck, Struktur, Arbeitsablauf, Berechtigungen oder Benutzereinstellungen geändert haben.

Im Übrigen geht es um die Struktur. Eine untergeordnete AGENTS.md hat standardmäßig die Abschnittsreihenfolge Purpose, Ownership, Local Contracts, Work Guidance, Verification und Child DOX Index. Die Datei im Root enthält die projektweiten Regeln sowie den übergeordneten Child DOX Index. Darüber findet ein Agent die untergeordneten Dokumente. „Closeout“ ist die Checkliste, die der Agent am Ende einer Aufgabe abarbeitet: die geänderten Pfade erneut mit der Kette abgleichen, die nächstgelegenen zuständigen Dokumente aktualisieren, jeden betroffenen Index aktualisieren, Widersprüche löschen, die vorhandene Verifikation ausführen und angeben, welche Dokumente er bewusst nicht geändert hat.

DOX an einen einzelnen Commit binden, nicht an main

Das Repository hat weder Tags noch Releases. Daher gibt es keine Versionsnummer, an die Sie binden können. Binden Sie stattdessen den Commit. Die aktuelle AGENTS.md entspricht dem Commit f34ec7ad1055d3393887e5a2670e8cb7320c9165 vom 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 sollte 3906 ausgeben. Eine andere Zahl bedeutet, dass Sie nicht die in diesem Leitfaden beschriebene Datei abgerufen haben. Lesen Sie sie daher, bevor Sie ihr vertrauen. Wenn Sie den Commit-Hash falsch eingeben, beendet -f curl mit curl: (22) The requested URL returned error: 404 und schreibt keinen Inhalt. Anschließend gibt wc -c 0 aus. Eine abgeschnittene Datei ist schlechter als keine Datei, weil der Agent dann nur einen Teil eines Vertrags befolgt, ohne davon zu wissen.

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

Dieses cp gilt für ein Repository ohne AGENTS.md. Wenn bereits eine vorhanden ist, überschreiben Sie sie nicht. Setzen Sie die DOX-Abschnitte vor den vorhandenen Inhalt und lassen Sie Ihre eigenen Regeln darunter stehen. Lesen Sie das Ergebnis anschließend einmal vollständig von oben nach unten. Zwei widersprüchliche Dokumente führen dazu, dass der Agent die jeweils zuletzt gelesene Regel befolgt.

Bitten Sie Ihren Agenten anschließend innerhalb des Repositorys um den ersten Durchlauf. Die README enthält die genaue Formulierung:

Initialize DOX tree for this project now.

Der Agent erstellt die untergeordneten AGENTS.md-Dateien und die darauf verweisenden Indizes. Prüfen Sie das Ergebnis, bevor Sie ihm vertrauen:

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

Jede Datei in der Ausgabe von find sollte irgendwo darüber in einem Child DOX Index aufgeführt sein. Ein untergeordnetes Dokument, auf das kein Index verweist, kann vom Agenten übersehen werden. Der Index zeigt ihm, wo er Dokumente findet, die nicht direkt auf dem von ihm durchsuchten Pfad liegen.

Was dox erkennen kann und was es nicht wissen kann

Der Agent, der Ihre Übersicht erstellt, liest das Repository. Daher kann alles, was sich im Repository befindet, in die Übersicht aufgenommen werden: die Verzeichnisstruktur, Paketmanifeste und Lockfiles, die Skripte in package.json, Makefile oder pyproject.toml, CI-Workflow-Dateien, Dockerfiles, Einstiegspunkte und CODEOWNERS, falls vorhanden. Eine aus diesen Informationen erstellte Übersicht pflegt sich tatsächlich selbst. Wenn ein Paket verschoben wird, verschiebt der nächste Durchlauf auch die Zeile, in der es beschrieben wird.

Alles Folgende müssen Sie selbst angeben, weil es nicht im Repository enthalten ist und daher nicht gelesen werden kann:

• warum eine Regel existiert; das verhindert, dass ein Agent sie als unnötige Komplexität entfernt
• welcher von zwei funktionierenden Wegen unterstützt wird und welcher gelöscht werden soll
• alles außerhalb des Repositorys, beispielsweise die Staging-Umgebung oder der Grund, warum eine Abhängigkeit zwei Versionen zurückliegt
• was Sie in der nächsten Woche vorhaben; das ist der Unterschied zwischen einer Datei, die aktuell ist, und einer Datei, die nützlich ist

dox weiß das über sich selbst. In den eigenen Regeln steht, dass Work Guidance den aktuellen Standards des Projekts oder den Anweisungen des Benutzers entsprechen muss. Wenn es noch keine solchen Vorgaben gibt, bleibt dieser Abschnitt leer. Verification muss eine vorhandene Prüfung abbilden. Wenn sich im Repository kein Test-Framework befindet, bleibt dieser Abschnitt leer, bis eines vorhanden ist. Eine generierte Datei, die einen Standard erfindet, ist schlechter als ein leerer Abschnitt, weil der Agent diese Erfindung anschließend durchsetzen wird.

Handschriftlich gepflegte Inhalte aus dem generierten Inventar heraushalten

Das ist der Fehler, wegen dem viele bei generierten Dokumenten aufgeben. Sie schreiben einen Absatz, der erklärt, dass die Jobs-Warteschlange genau einen Consumer haben muss. Drei Wochen später schreibt ein Durchlauf die Datei neu, und Ihr Absatz ist verschwunden – in einem Diff mit vierzig Zeilen, in dem größtenteils nur Dateinamen neu angeordnet wurden. Niemand bemerkt es.

Dafür benötigen Sie zwei Mechanismen, und Sie sollten beide verwenden.

Verschieben Sie erstens dauerhaft relevante Absichten in eine andere Datei. Architekturentscheidungen und die dazugehörige Begründung gehören in eine DESIGN.md-Datei für den Agenten. Notizen für Menschen gehören dorthin, wo Sie HUMAN.md aus AGENTS.md herauslösen. AGENTS.md enthält dann das Inventar und die lokalen Verträge. Genau dieser Teil sollte sich ändern, wenn sich der Code ändert.

Sichern Sie zweitens die Absichten, die in AGENTS.md bleiben müssen. Schließen Sie sie in Marker ein und behandeln Sie den Block als von Menschen gepflegten Inhalt:

## 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-Kommentare werden auf der Seite nicht dargestellt, und der Agent liest sie trotzdem. Machen Sie nun überprüfbar, dass der Block erhalten bleibt, damit ein Durchlauf, der ihn entfernt, deutlich fehlschlägt. Führen Sie dies in der CI (Continuous Integration) bei jedem Pull Request aus:

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 gibt nichts aus und beendet sich mit 0, wenn der Block unverändert ist. Jede Ausgabe bedeutet, dass der Durchlauf von Menschen gepflegten Text neu geschrieben hat. Eine Person muss die Änderung dann freigeben oder zurücksetzen. Die Prüfung funktioniert, ohne dass sich jemand daran erinnern muss.

Bei der Pull-Anfrage regenerieren, nicht nach einem Zeitplan

Der beste Zeitpunkt zum Aktualisieren eines Dokuments ist der Commit, durch den es inkorrekt wird. Führen Sie den DOX-Durchlauf in derselben Pull-Anfrage wie die strukturelle Änderung aus. Dadurch bleibt der Diff klein genug, um ihn tatsächlich zu prüfen.

Eine blockierende Prüfung, die dies erzwingt:

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

Passen Sie die Pfade an Ihr Repository an. Der Vorteil besteht darin, dass die Prüfung im Branch fehlschlägt, wo die Korrektur kostengünstig ist, und dass sie aus einem Grund fehlschlägt, auf den ein Reviewer reagieren kann.

Ein Zeitplan ist die Rückfallebene, nicht der eigentliche Mechanismus. Ein wöchentlicher Job erkennt, was in einem Branch niemand bemerkt hat: Dateien, die durch ein Rebase verschoben wurden, ein Paket, das bei einem Merge gelöscht wurde, oder ein Dokument, das ein nicht mehr vorhandenes Verzeichnis nennt. Führen Sie ihn auf einem kleinen System aus, demselben, das Sie möglicherweise verwenden, um einen Coding-Agent auf einem VPS auszuführen, und lassen Sie ihn eine Pull-Anfrage öffnen, statt direkt in main zu 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

Dieser Kommentar ist absichtlich nur ein Platzhalter. Jeder Agent hat seine eigene CLI (command line interface) und sein eigenes Flag für den nicht interaktiven Betrieb. Ein von einer Webseite kopierter Befehl, der nicht zu Ihrer Version passt, schlägt in cron fehl, ohne dass jemand den Fehler sieht. Ergänzen Sie den Befehl und führen Sie das Skript einmal manuell aus, bevor Sie es einplanen. Auch || exit 0 ist relevant: git commit beendet sich mit nothing to commit, working tree clean mit einem Status ungleich 0, wenn der Baum bereits aktuell ist. Unter set -e würde ein erfolgreicher Durchlauf dadurch als Fehler gemeldet.

Jeder Durchlauf verbraucht Tokens, weil „Read Before Editing“ den Agenten bei jeder Aufgabe die gesamte Kette lesen lässt. Das ist der Kompromiss. Wenn Sie bereits verfolgen, welche Kosten Ihre Agent-Ausführungen verursachen, sollten Sie ihn im Blick behalten.

Monorepos: viele Verträge, ein Index

Eine einzige AGENTS.md im Stammverzeichnis eines Repositorys mit vierzig Paketen erzeugt bei jeder Regenerierung ein Diff, das niemand liest. Außerdem enthält das Dokument überwiegend Informationen, die für die aktuelle Aufgabe des Agents irrelevant sind. dox beantwortet dieses Problem mit dem Child DOX Index: Im Stammverzeichnis stehen die repositoryweiten Regeln und Verweise auf die untergeordneten Dateien. Jede dauerhafte Grenze besitzt ihre eigene Datei. Wie dieser Baum aufgebaut wird und welche Tools verschachtelte Dateien überhaupt lesen, wird unter verschachtelte AGENTS.md-Dateien für Monorepos beschrieben.

dox verändert die zu prüfende Oberfläche. Ein Pull Request, der packages/api ändert, sollte ausschließlich innerhalb von packages/api einen Dokumentations-Diff erzeugen:

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

Wenn dieser Befehl bei einer Änderung an einem einzigen Paket sechs Dateien auflistet, ist der Baum falsch aufgebaut. Entweder sind die Grenzen zu grob, oder eine Regel, die in das Stammverzeichnis gehört, wurde in jedes untergeordnete Verzeichnis kopiert. dox formuliert die Lösung direkt: Allgemeine Regeln gehören in die übergeordneten Dokumente, konkrete Details in die untergeordneten Dokumente. Doppelte Regeln führen dazu, dass ein routinemäßiger Durchlauf alles neu schreibt. Wenn dieselben Regeln tatsächlich für mehrere separate Repositorys gelten, handelt es sich um ein anderes Problem. Dafür ist gemeinsam genutzte Agent-Skills über Repositorys hinweg das bessere Werkzeug.

Diff wie Code prüfen

Ein generierter Dokumentations-Diff lässt sich leicht ungelesen freigeben. Dadurch wird eine fehlerhafte Datei veröffentlicht. Lesen Sie den Diff mit derselben Skepsis wie generierten Code. Achten Sie auf vier Punkte.

• einen Befehl, den die Datei jetzt nennt und den Sie vor dem Merge selbst ausführen sollten. Erfundene Build-Anweisungen sind die häufigste Fehlerquelle.
• eine gelöschte Zeile, die eine wichtige Absicht enthielt. Ergänzungen sind unproblematisch. Beim Löschen geht der Informationsverlust verloren.
• einen absoluten Pfad, einen Hostnamen, eine interne URL oder etwas, das wie ein Zugangsschlüssel aussieht
• einen Inventareintrag für etwas, das nicht mehr existiert und den ls in einer Sekunde bereinigt

Prüfen Sie anschließend die Größe mit wc -l AGENTS.md. Eine Root-Datei mit mehr als 200 Zeilen ist ein Signal, sie aufzuteilen. Der gesamte Nutzen dieser Kette besteht darin, dass der Agent nur den kleinen relevanten Teil statt des gesamten Inhalts liest.

Wenn etwas fehlschlägt

Der Durchlauf hat Ihren Intent-Block gelöscht. Die Prüfung diff oben zeigt die entfernten Zeilen. Stellen Sie die Datei mit git restore --source=origin/main AGENTS.md auf den Stand des Verzweigungspunkts zurück. Führen Sie den Durchlauf anschließend mit einer engeren Anweisung erneut aus, in der Sie die Abschnitte nennen, die geändert werden dürfen.

Zwei Branches wurden beide neu generiert. Sie erhalten CONFLICT (content): Merge conflict in AGENTS.md sowie Konfliktmarker <<<<<<< HEAD in der Datei. Bearbeiten Sie die Marker nicht manuell. Die Datei wird generiert. Die korrekte Konfliktauflösung ist ein neuer Durchlauf über dem zusammengeführten Tree.

Der Agent ignoriert die Datei vollständig. Prüfen Sie, welchen Dateinamen Ihr Tool tatsächlich einliest. Wenn es eine andere Datei einliest, verweisen Sie es mit ln -s AGENTS.md CLAUDE.md auf denselben Inhalt und committen Sie den Symlink. So behalten Sie eine einzige Quelle statt zweier Dokumente, die auseinanderlaufen. Wenn der Dateiname bereits korrekt ist und die Regeln weiterhin übersprungen werden, führen Sie die Diagnose warum Coding-Agenten Ihre Anweisungen ignorieren aus, bevor Sie das Dokument erneut umschreiben.

Der Tree hat untergeordnete Dokumente erhalten, die niemand indiziert hat. Vergleichen Sie die Ausgabe von find . -name AGENTS.md mit den Indexeinträgen in den übergeordneten Dokumenten. Ein untergeordnetes Dokument, auf das kein Index verweist, kann vom Agenten direkt übersprungen werden.

Wenn ein Generator überdimensioniert ist

Ein Paket, ein Testbefehl und zwei Personen, die das Repository beide kennen: Schreiben Sie die zwanzig Zeilen von Hand. Eine zwanzigzeilige AGENTS.md veraltet nicht schnell genug, um einen Baum, einen Index, eine CI-Prüfung und einen wöchentlichen Job zu rechtfertigen. Lesen Sie die Datei erneut, wenn Sie den Build ändern. Das sind die gesamten Wartungskosten. Sie sind geringer als die Kosten für die umgebende Infrastruktur.

dox lohnt sich, wenn das Repository Grenzen enthält, die niemand vollständig im Kopf hat: mehrere Pakete mit unterschiedlichen Regeln oder Mitwirkende, die ohne den nötigen Hintergrund dazukommen. Der Wert liegt nicht im generierten Text. Entscheidend ist, dass die Dokumentation so zu einem Bestandteil wird, an dem ein Pull Request scheitern kann. Nur dann bleibt eine Datei im Repository aktuell.

FAQ

Muss ich etwas installieren, um dox zu verwenden?

Nein. dox besteht aus einer Markdown-Datei, steht unter der MIT-Lizenz, und das Repository enthält am 11. August 2026 weder ein Package noch Releases. Sie kopieren den Inhalt in die AGENTS.md Ihres Projekts, und Ihr Coding Agent befolgt die darin enthaltenen Regeln. Fixieren Sie den kopierten Commit, f34ec7ad1055d3393887e5a2670e8cb7320c9165 zum Zeitpunkt der Erstellung, und nennen Sie ihn in Ihrer Commit-Nachricht. So können Sie später feststellen, unter welcher Regelversion Ihr Arbeitsbaum erstellt wurde.

Wie verhindere ich, dass eine Neugenerierung meine selbst geschriebenen Regeln löscht?

Trennen Sie Zweck und Bestandsaufnahme. Dauerhafte Begründungen gehören in ein separates Dokument. Alles, was in der AGENTS.md erhalten bleiben muss, gehört in einen markierten Block. Prüfen Sie den Block anschließend in CI: Extrahieren Sie ihn aus dem Branch und aus origin/main mit sed, vergleichen Sie beide mit diff, und lassen Sie den Build bei jeder Abweichung fehlschlagen. Anschließend genehmigt eine Person die Änderung oder setzt sie zurück. So bleibt sie nicht unbemerkt in einem großen Diff.

Wie oft sollte ich die AGENTS.md neu generieren?

Bei dem Pull Request, durch den sie falsch wird. Eine strukturelle Änderung und die zugehörige Dokumentation gehören in denselben Diff. Nur dann hat jemand den nötigen Kontext, um beides zu prüfen. Ein wöchentlicher geplanter Lauf dient als Absicherung gegen Drift, die einen Branch passiert hat. Er sollte einen Pull Request öffnen, statt direkt in main zu committen.

Sollten Build-Befehle in der AGENTS.md im Root-Verzeichnis oder in einer untergeordneten Datei stehen?

In dem Dokument, dem sie am nächsten sind und das für sie zuständig ist. Repository-weite Regeln und der Index für untergeordnete Dokumente gehören ins Root-Verzeichnis. Ein Befehl, der für ein einzelnes Package gilt, gehört in die AGENTS.md dieses Packages. dox löst Konflikte anhand der Entfernung: Das näher gelegene Dokument steuert lokale Details, und kein untergeordnetes Dokument darf eine Regel des übergeordneten Dokuments abschwächen. Wenn Sie denselben Befehl in jedes untergeordnete Dokument kopieren, schreibt ein regulärer Lauf den gesamten Baum neu.

Lohnt sich dox für ein kleines Repository?

In der Regel nicht. Ein Package mit einem Testbefehl und einer zwanzigzeiligen AGENTS.md veraltet langsam. Sie können sie in der Minute korrigieren, in der Sie das Problem bemerken. dox lohnt sich, wenn das Repository mehrere Bereiche mit unterschiedlichen Regeln oder Mitwirkende ohne den nötigen Hintergrund hat. Dann übernimmt die Kette der Dokumente Arbeit, die sonst keine einzelne Person erledigt.