AGENTS.md und HUMAN.md: verständlich erklärt

Was AGENTS.md ist

AGENTS.md ist eine einfache Markdown-Datei im Stammverzeichnis eines Repositorys. Sie beschreibt für einen Coding-Agenten, wie er an diesem Projekt arbeiten soll. Die offizielle Website bezeichnet sie als „eine README-Datei für Agenten: ein dedizierter, vorhersehbarer Ort für Kontext und Anweisungen, die Coding-Agenten mit KI bei der Arbeit an Ihrem Projekt unterstützen“. Das Format wird von der Agentic AI Foundation unter dem Dach der Linux Foundation betreut. Mehr als zwanzig Agenten lesen diese Datei, darunter Codex, Cursor, Jules, Devin und GitHub Copilot (Stand: Juli 2026).

Der Grund für diese Konvention ist praktisch. Eine neue Person in Ihrem Team liest die README-Datei, rät den Build-Befehl und fragt jemanden, wenn der Versuch fehlschlägt. Ein Agent kann nicht fragen. Er rät, führt npm test in einem Projekt aus, das pnpm test verwendet, liest den Fehler und versucht etwas anderes. Sie bezahlen für jedes dieser Tokens. Wenn Sie den tatsächlichen Befehl einmal dokumentieren, vermeiden Sie diese gesamte Fehlerklasse.

Es gibt keine vorgeschriebenen Felder. Die Website stellt dies ausdrücklich klar: „AGENTS.md ist einfach standardmäßiges Markdown. Verwenden Sie beliebige Überschriften. Der Agent analysiert einfach den von Ihnen bereitgestellten Text.“ Das ist die gesamte Spezifikation. Der Nutzen liegt nicht im Format. Er liegt darin, dass sich die Datei an einem Pfad befindet, den jedes Tool bereits prüft.

Wohin die Datei kommt und welche Datei Vorrang hat

Legen Sie die erste Datei im Repository-Stammverzeichnis ab. In einem Monorepo können Sie in jedem Teilprojekt weitere Dateien hinzufügen. Die Regel ist einfach: "Agents lesen automatisch die nächstgelegene Datei im Verzeichnisbaum, daher hat die Datei mit dem kürzesten Pfad Vorrang." Ein Konflikt zwischen zwei Dateien wird zugunsten der Datei aufgelöst, die gerade bearbeitet wird. Alles, was Sie in den Chat eingeben, überschreibt beide Dateien.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

Die Verschachtelung ist sinnvoll, weil Sie nur so eine Aussage für einen Ordner als wahr und für den nächsten als falsch festlegen können. Eine Regel wie "Jeder Endpunkt validiert seine Eingaben" gehört neben die Endpunkte. In einer Datei im Stammverzeichnis wird sie bei jeder nicht verwandten Aufgabe geladen und bringt keinen Nutzen.

Was in einer AGENTS.md stehen sollte

Dokumentieren Sie, was ein Agent nicht durch das Lesen des Codes herausfinden kann. Die genauen Befehle zum Erstellen, Testen und Prüfen stehen an erster Stelle, und zwar in der Form, in der Sie sie in ein Terminal einfügen würden. Fügen Sie den Befehl zum Ausführen eines einzelnen Tests hinzu. Ein Agent, der nur weiß, wie die gesamte Testsuite ausgeführt wird, wird die gesamte Testsuite sonst vierzigmal ausführen. Nennen Sie Konventionen, die vom Standard des jeweiligen Tools abweichen. Der Agent kennt den Standard bereits und muss nur Ihre Abweichung kennen. Fügen Sie das Format der Commit-Nachricht und die Regeln für Pull Requests hinzu, sofern vorhanden.

Formulieren Sie die Angaben so konkret, dass eine Aussage überprüft werden kann. „Verwenden Sie eine Einrückung mit 2 Leerzeichen“ ist eine brauchbare Anweisung, weil eindeutig festgestellt werden kann, ob sie eingehalten wurde. „Formatieren Sie den Code ordnungsgemäß“ ist dagegen nicht brauchbar, weil sich daraus nichts überprüfen lässt. Dasselbe gilt für Verzeichnisse: „API-Handler befinden sich in src/api/handlers/“ ist besser als „Halten Sie die Dateien organisiert“.

Auch negative Regeln sind sinnvoll. „Bearbeiten Sie niemals Dateien unter dist/; sie werden von npm run build generiert“ verhindert einen konkreten Fehler. Weil die Ursache genannt wird, kann der Agent den entsprechenden Fall selbst ableiten, den Sie nicht ausdrücklich dokumentiert haben.

Was niemals hineingehört

Legen Sie niemals ein Geheimnis in einer dieser Dateien ab. Die Datei wird in git versioniert, zu Beginn jeder Sitzung in den Kontext geladen und bei jeder Anfrage an einen Modellanbieter gesendet. Ein API-Schlüssel in einer AGENTS.md steht damit in der Repository-Historie und in den Protokollen eines Drittanbieters. Verweisen Sie auf das Geheimnis, statt es einzufügen: „Das Datenbankpasswort steht in .env. Die Datei wird von git ignoriert. Fragen Sie vor dem Lesen nach.“ Die übergeordnete Vorgehensweise wird unter Anmeldedaten außerhalb der Reichweite eines Agenten halten beschrieben.

Lassen Sie alles weg, was der Agent durch Nachsehen ableiten kann. Eine eingefügte Verzeichnisliste, eine Kopie Ihrer Abhängigkeitsliste oder eine Architekturübersicht, die lediglich die Verzeichnisnamen wiederholt: All das ist bereits in der Woche nach dem Erstellen veraltet und verbraucht bis dahin bei jeder Sitzung Kontext. Behalten Sie die Problemstellen und die Gründe. Lassen Sie die Bestandsaufnahme weg.

CLAUDE.md ist die Claude-Code-Variante derselben Idee

Claude Code liest CLAUDE.md und liest AGENTS.md nicht selbstständig. Eine Projektdatei liegt unter ./CLAUDE.md oder ./.claude/CLAUDE.md. Persönliche Einstellungen für jedes Projekt gehören in ~/.claude/CLAUDE.md. Eine Organisation kann unter Linux eine systemweite Datei nach /etc/claude-code/CLAUDE.md verteilen. Erkannte Dateien werden vom Stammverzeichnis des Dateisystems bis zu Ihrem Arbeitsverzeichnis zusammengeführt. Die Datei, die dem Verzeichnis am nächsten liegt, in dem Sie die Sitzung gestartet haben, wird zuletzt gelesen.

Wenn Ihr Repository bereits eine AGENTS.md enthält, verwalten Sie keine zweite Kopie. Importieren Sie sie und fügen Sie anschließend nur Claude-spezifische Inhalte hinzu:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Ein symbolischer Link funktioniert, wenn Sie nichts zusätzlich hinzufügen müssen:

ln -s AGENTS.md CLAUDE.md

Der Befehl gibt bei Erfolg nichts aus. Führen Sie in Ihrer nächsten Sitzung /context aus und bestätigen Sie, dass CLAUDE.md unter Speicherdateien angezeigt wird. Fehlt die Datei in dieser Liste, wurde sie nicht geladen und ihr Inhalt hatte keine Wirkung. Wenn Sie stattdessen einen ersten Entwurf erzeugen möchten, führen Sie /init aus. Der Befehl liest die Codebasis und erstellt eine Ausgangsdatei. Wenn bereits eine CLAUDE.md vorhanden ist, schlägt er Verbesserungen vor, anstatt sie zu überschreiben.

Halten Sie jede Datei unter etwa 200 Zeilen. Längere Dateien belegen mehr Kontext und verringern die Befolgung der Anweisungen. Wenn Sie sehen möchten, welche anderen Inhalte diesen Platz beanspruchen, erläutert was den Kontext eines Agenten tatsächlich füllt die Aufteilung.

Ein Punkt ist besonders wichtig. Eine AGENTS.md enthält Anweisungen, ist aber kein Berechtigungssystem. Ihr Inhalt wird als gewöhnlicher Kontext übergeben. Das Modell liest ihn und befolgt ihn normalerweise. Nichts verhindert jedoch eine Aktion, die diesen Anweisungen widerspricht. Für eine Regel, die jedes Mal gelten muss, etwa „niemals nach main pushen“, verwenden Sie einen Hook oder eine Berechtigungseinstellung. Diese werden als Code ausgeführt und hängen nicht davon ab, ob das Modell sich entscheidet, die Regel zu befolgen.

Tools, die diese Dateien für Sie erstellen

Zwei Projekte aus der GitHub-Trendliste vom 30. Juli 2026 zeigen, in welche Richtung sich diese Konvention entwickelt.

agent0ai/dox (1,368 Sterne im Juli 2026) ist ein Framework, das einen Verzeichnisbaum mit AGENTS.md-Dateien aktuell hält. Es enthält kein Paket und keine Laufzeitumgebung. Sie kopieren den Inhalt seiner AGENTS.md in Ihre eigene AGENTS.md im Stammverzeichnis. Damit ist die Installation abgeschlossen. Bei einem bereits vorhandenen Projekt weisen Sie Ihren Agenten an:

Initialize DOX tree for this project now.

Der Agent erstellt anschließend die untergeordneten AGENTS.md-Dateien und deren Indizes. Vor jeder Änderung durchläuft er diesen Verzeichnisbaum. Nach einer Änderung aktualisiert er die betroffene Dokumentation. Dahinter steht die Annahme, dass Dokumentation, die ein Agent als Nebenwirkung seiner Arbeit pflegt, korrekt bleibt. Dokumentation, die eine Person manuell aktualisiert, bleibt dagegen nicht zuverlässig korrekt.

HUMAN.md, derselbe Ansatz für Sie

Intuition-Lab/personal-model (1,260 Sterne im Juli 2026) überträgt das Muster auf eine Person statt auf ein Repository. Das Projekt beschreibt Ihre HUMAN.md als Ausgabe des Systems und nicht als Datei, die Sie selbst schreiben: „ein lebendes Modell dessen, was jetzt wichtig ist, wie Sie normalerweise Entscheidungen treffen und wohin sich Ihre Aufmerksamkeit bewegt“. Es läuft lokal unter macOS 13 oder höher, erfasst Aktivitäten, nachdem Sie macOS die erforderlichen Berechtigungen erteilt haben, und stellt das Ergebnis Agents über MCP (model context protocol) bereit. Der kurze Installationsweg:

uv tool install personal-model
persome onboard
persome model open --after 30

Sie benötigen davon nichts, um den größten Teil des Nutzens zu erhalten. Eine von Hand geschriebene HUMAN.md umfasst etwa zwanzig Zeilen: Ihre Rolle, Ihre Zeitzone, den Stack, den Sie tatsächlich verwenden, bereits getroffene Entscheidungen, die Sie nicht erneut infrage stellen möchten, und wie ausführlich die Antworten sein sollen. Sie erspart dieselben wiederholten Erklärungen, die eine Projektdatei einspart, nur auf einer übergeordneten Ebene.

Ein Hinweis zur Sicherheit: Eine HUMAN.md ist ein Profil einer Person und daher grundsätzlich sensibel. Halten Sie sie aus einem öffentlichen Repository heraus. Legen Sie sie in ~/.claude/CLAUDE.md oder in einer von git ignorierten CLAUDE.local.md im Projektstammverzeichnis ab. Diese Datei wird zusammen mit der versionierten Datei geladen und auf dieselbe Weise behandelt.

Eine Vorlage zum Einstieg, die Sie kopieren können

Diese Vorlage ist absichtlich kurz. Löschen Sie die Abschnitte, die nicht zutreffen, und fügen Sie keine Abschnitte hinzu, die Sie nicht aktuell halten können.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

Schreiben Sie die Information auf und korrigieren Sie sie direkt an dieser Stelle. Ein Signal dafür, eine Zeile hinzuzufügen, ist, dass Sie dieselbe Korrektur zweimal in den Chat eingegeben haben. Diese eine Regel hält die Datei nützlich und verhindert, dass sie zu einem Dokument anwächst, das niemand liest, auch keine Maschinen. Sobald sie stabil ist, bleibt sie im Repository und wird mit diesem weitergegeben. Das ist besonders wichtig, wenn der Agent an einem anderen Ort als auf Ihrem Laptop ausgeführt wird: einen Coding-Agent auf dem eigenen Server ausführen behandelt diese Einrichtung.

FAQ

Ist AGENTS.md dieselbe Datei wie CLAUDE.md?

Beide verfolgen dasselbe Konzept, verwenden aber unterschiedliche Dateinamen. Claude Code liest CLAUDE.md und ignoriert AGENTS.md, sofern Sie die Dateien nicht miteinander verknüpfen. Verwenden Sie eine Datei als maßgebliche Quelle und verknüpfen Sie die andere damit, entweder mit einer Zeile @AGENTS.md am Anfang Ihrer CLAUDE.md oder mit ln -s AGENTS.md CLAUDE.md. Zwei vollständige, separat gepflegte Kopien weichen innerhalb eines Monats voneinander ab.

Garantiert das Schreiben einer AGENTS.md, dass der Agent sie befolgt?

Nein. Der Inhalt wird als Kontext übergeben. Das Modell liest ihn und hält sich im Allgemeinen daran. Eine Aktion, die dagegen verstößt, wird jedoch nicht blockiert. Vage Anweisungen werden am unzuverlässigsten befolgt. Zwei Dateien mit widersprüchlichen Vorgaben überlassen dem Agenten die beliebige Auswahl einer davon. Für eine Regel, die jedes Mal gelten muss, verwenden Sie einen Hook oder eine Berechtigungsregel. Diese werden vom Client unabhängig von der Entscheidung des Modells erzwungen.

Sollte AGENTS.md in git eingecheckt werden?

Ja, für alles, was für das Projekt gilt: Build-Befehle, Struktur und Konventionen. Das ist der Zweck der Datei. Die Agenten Ihrer Teammitglieder beginnen dann mit demselben Kontext wie Ihrer. Persönliche Angaben oder Angaben, die nur für einen Rechner gelten, gehören in eine separate gitignored-Datei. Zugangsdaten gehören in keine der beiden Dateien.

Was ist HUMAN.md, und benötige ich eine solche Datei?

HUMAN.md ist ein maschinenlesbares Profil einer Person und nicht eines Projekts. Es enthält Ihre Rolle, Ihre Einschränkungen und bereits getroffene Entscheidungen, damit diese nicht in jeder Sitzung erneut hinterfragt werden. Sie benötigen keine speziellen Werkzeuge für den Anfang. Zwanzig selbst verfasste Zeilen in Ihrer benutzerspezifischen Anweisungsdatei bieten bereits den größten Teil des Nutzens. Behandeln Sie die Datei als personenbezogene Daten und legen Sie sie in keinem Repository ab, das Sie veröffentlichen.