Der AGENTS.md-Standard für KI-Coding-Agenten

AGENTS.md ist ein Betriebsdokument für KI-Coding-Agenten. Es sagt dem Agenten, wie er in diesem Baum arbeitet: wo die Karte liegt, welche Befehle laufen, wie dieses Repo Git handhabt, und was er immer tun, zuerst fragen oder niemals tun muss.

Es ist kein zweites README. Ein README stellt das Projekt Menschen vor. Es ist kein Styleguide. Linter und die Codebasis besitzen die Coding-Standards bereits.

Das Format ist schlichtes Markdown. Es gibt kein erforderliches Schema, kein YAML-Frontmatter, keine JSON-Konfiguration. Die offene Konvention liegt unter agents.md: der Dateiname ist AGENTS.md, die nächstgelegene Datei zu den bearbeiteten Dateien gewinnt, gelistete Befehle werden ausgeführt, und eine Nachricht im Chat überschreibt die Datei immer.

Im Dezember 2025 wurde das Format an die Agentic AI Foundation (AAIF) gespendet, einen Directed Fund unter der Linux Foundation, neben Anthropics Model Context Protocol. Eine Datei, viele Agenten.

Zielen Sie auf etwa 200 Zeilen an der Wurzel. Das reicht für Karte, Git-Regeln und Grenzen. Es ist kurz genug, um es jede Session zu laden.

Was in die Datei gehört

Fünf Blöcke. Behalten Sie diese Reihenfolge.

Überblick — was dieser Baum ist, in wenigen Sätzen.

Karte und wo mehr steht — die Ordner, die zählen, und ein Zeiger auf den Index für dauerhaftes Wissen. Zeigen. Das Wiki nicht hineinkopieren.

Befehle — die exakten Install-, Test- und Lint-Befehle. Wenn Sie ihn schreiben, wird der Agent ihn versuchen.

Git-Workflow — wie dieses Repo ausliefert. Branchnamen, ob ein Pull Request geöffnet oder auf main gepusht wird, Commit-Message-Modus. Git ist repo-spezifisch, anders als Coding-Standards.

Grenzen — Always do. Ask first. Never do.

Beispiel: ein Root-AGENTS.md

Ein fiktives Billing-Monorepo. Die Namen sind illustrativ. Behalten Sie die Blöcke.

Repository-Root — fiktives Billing-Monorepo

# AGENTS.md

## Project overview
Billing platform monorepo: a Node API (`apps/api`), a React dashboard (`apps/web`), and shared libraries under `packages/`. Root rules apply unless a nested AGENTS.md says otherwise.

## Map
- `apps/api` — invoice and payment API
- `apps/web` — operator dashboard
- `packages/` — shared types and clients
- `infra/` — Terraform for staging and production
- Durable product knowledge: `docs/INDEX.md`. Open that map when you need a service, runbook, or decision.

## Commands
pnpm install
pnpm test
pnpm lint
pnpm --filter @acme/api test
docker compose up -d   # before API integration tests

## Git workflow
- Open a pull request against `main`. Do not push commits to `main`.
- Branch names: `feat/<short-name>` or `fix/<short-name>`
- Commit messages: imperative mood, complete sentences.

## Boundaries

### Always do
- Run `pnpm test` and `pnpm lint` before you consider a change done.
- Read `docs/INDEX.md` before inventing a service name or a runbook step.

### Ask first
- Changing auth, billing webhooks, or CI workflows.
- Adding a nested `AGENTS.md`.
- Touching `infra/` production modules.

### Never do
- Commit `.env`, API keys, or customer payment data.
- Invent an undocumented payment provider.

Verschachtelte Dateien

Die nächstgelegene AGENTS.md zu den bearbeiteten Dateien gewinnt. Verschachtelung ist absichtlich selten. Die meisten Unterverzeichnisse folgen der Root-Datei. Verschachteln Sie keine zweite Kopie zur Abdeckung.

Fügen Sie eine verschachtelte Datei nur hinzu, wenn dieser Teilbaum eine Root-Regel tatsächlich bricht. Die verschachtelte Datei ist ein Delta. Sie wiederholt nicht pnpm, Git oder never-commit-secrets.

infra/AGENTS.md — ein Delta, keine zweite Kopie der Root-Datei

# AGENTS.md — infra/

Root git, pnpm, and Never-secrets still apply. This file is only the delta.

## Ask first
- `terraform plan` or `terraform apply` against staging.

## Never do
- Run `terraform apply` against the production workspace.
- Edit Terraform state by hand.

Was Sie draußen lassen

Stil, den ein Linter erzwingen kann. Gehört in den Linter.

Menschliches CONTRIBUTING.md, außer den Git-Zeilen, die der Agent ausführen wird. Wenn diese Zeilen Betriebsregeln sind, gehören sie auch in AGENTS.md.

Wenn ein Tool noch CLAUDE.md liest, zeigen Sie mit dieser Datei auf AGENTS.md. Kopieren Sie die Betriebsregeln nicht.

Dauerhaftes Produktwissen — Personen, Services, Entscheidungen — gehört in die Wissenskarte, nicht in die Betriebsdatei. Siehe Wissen für KI-Agenten organisieren.

Lange Verfahren gehören in ein verlinktes Dokument oder Skill. Eine Zeile in AGENTS.md reicht: für X lies Y. Machen Sie Skills nicht zum Rückgrat der Datei.

Am Leben halten

Wenn ein Agent einen Fehler wiederholt, fügen Sie eine Grenz-Zeile hinzu. Wenn eine Zeile veraltet, löschen Sie sie. Das 200-Zeilen-Budget ist, wie Sie Aufblähung merken.

Zusammenfassung

Schreiben Sie eine Root-AGENTS.md von etwa 200 Zeilen. Geben Sie ihr eine Karte, Git-Regeln und Always / Ask first / Never. Verschachteln Sie eine weitere Datei nur, wenn ein Unterverzeichnis diese Regeln tatsächlich bricht. Der Chat überschreibt die Datei weiterhin.

Dylan Engelbrecht aktualisiert diesen Knowledge-Hub, wenn sich die Agentenpraxis weiterentwickelt. Behandeln Sie diese Artikel als lebendige Referenz — aktuelle Praxis, kein eingefrorener Schnappschuss.