AGENTS.md pflegen
AGENTS.md ist die kanonische agentenorientierte Dokumentation. Halte sie minimal – Agenten sind fähig und brauchen keine Bevormundung. Ziel: unter 60 Zeilen; niemals 100 überschreiten. Die Befolgungsqualität von Anweisungen nimmt mit zunehmender Dokumentenlänge ab.
Wann verwenden
- Der Nutzer bittet darum,
AGENTS.mdoderCLAUDE.mdzu erstellen, zu aktualisieren oder zu prüfen. - Das Projekt benötigt präzise, signalstarke Agentenanweisungen, die aus der tatsächlichen Toolchain und dem Repository-Layout abgeleitet sind.
- Vorhandene Agentendokumentation ist zu lang, doppelt vorhanden oder weicht von den tatsächlichen Projektkonventionen ab.
Dateieinrichtung
- Erstelle
AGENTS.mdim Projektstammverzeichnis - Erstelle symbolischen Link:
ln -s AGENTS.md CLAUDE.md
Vor dem Schreiben
Analysiere das Projekt, um zu verstehen, was in die Datei gehört:
- Paketmanager – Prüfe auf Sperrdateien (
pnpm-lock.yaml,yarn.lock,package-lock.json,uv.lock,poetry.lock) - Linter-/Formatierer-Konfigurationen – Suche nach
.eslintrc,biome.json,ruff.toml,.prettierrcusw. (nicht in AGENTS.md duplizieren) - CI-/Build-Befehle – Prüfe
Makefile,package.json-Skripte, CI-Konfigurationen auf kanonische Befehle - Monorepo-Indikatoren – Prüfe auf
pnpm-workspace.yaml,nx.json, Cargo-Workspace oderpackage.json-Dateien in Unterverzeichnissen - Vorhandene Konventionen – Prüfe auf bestehende CONTRIBUTING.md, docs/ oder README-Muster
Schreibregeln
- Überschriften + Aufzählungspunkte – Keine Absätze
- Codeblöcke – Für Befehle und Vorlagen
- Verweisen, nicht einbetten – Auf vorhandene Dokumente verweisen: „Siehe
CONTRIBUTING.mdfür Einrichtung“ oder „Muster insrc/api/routes/befolgen“ - Kein Fülltext – Keine Einleitungen, Schlussfolgerungen oder Höflichkeiten
- Fähigkeiten vertrauen – Offensichtlichen Kontext weglassen
- Dateibezogene Befehle bevorzugen – Pro-Datei-Test-/Lint-/Typcheck-Befehle statt projektweiter Builds
- Linter nicht duplizieren – Codestil lebt in Linter-Konfigurationen, nicht in AGENTS.md
Erforderliche Abschnitte
Paketmanager
Welches Werkzeug und nur die wichtigsten Befehle:
## Paketmanager
Verwende **pnpm**: `pnpm install`, `pnpm dev`, `pnpm test`
Dateibezogene Befehle
Pro-Datei-Befehle sind schneller und günstiger als vollständige Projekt-Builds. Immer einfügen, wenn verfügbar:
## Dateibezogene Befehle
| Aufgabe | Befehl |
|---------|--------|
| Typcheck | `pnpm tsc --noEmit path/to/file.ts` |
| Lint | `pnpm eslint path/to/file.ts` |
| Test | `pnpm jest path/to/file.test.ts` |
Commit-Attribution
Diesen Abschnitt immer einfügen. Agenten sollten ihre eigene Identität verwenden:
## Commit-Attribution
KI-Commits MÜSSEN enthalten:
Co-Authored-By: (Name und Attributionszeile des Agentenmodells)
Beispiel: `Co-Authored-By: Claude Sonnet 4 <[email protected]>`
Wichtige Konventionen
Projektspezifische Muster, die Agenten befolgen müssen. Kurz halten.
Optionale Abschnitte
Nur bei tatsächlichem Bedarf hinzufügen:
- API-Routenmuster (Vorlage zeigen, keine Erklärung)
- CLI-Befehle (Tabellenformat)
- Dateibenennungskonventionen
- Projektstrukturhinweise (auf kritische Dateien verweisen, veralteten Code markieren, der vermieden werden sollte)
- Monorepo-Überschreibungen (
AGENTS.md-Dateien in Unterverzeichnissen überschreiben das Stammverzeichnis)
Anti-Patterns
Diese weglassen:
- „Willkommen zu…“ oder „Dieses Dokument erklärt…“
- „Du solltest…“ oder „Denke daran…“
- Linter-/Formatierer-Regeln, die bereits in Konfigurationsdateien vorhanden sind (
.eslintrc,biome.json,ruff.toml) - Auflistung installierter Skills oder Plugins (Agenten entdecken diese automatisch)
- Vollständige projektweite Build-Befehle, wenn dateibezogene Alternativen existieren
- Offensichtliche Anweisungen („Tests ausführen“, „sauberen Code schreiben“)
- Erklärungen, warum etwas getan wird (einfach sagen, was zu tun ist)
- Lange Prosa-Absätze
Beispielstruktur
# Agentenanweisungen
## Paketmanager
Verwende **pnpm**: `pnpm install`, `pnpm dev`
## Commit-Attribution
KI-Commits MÜSSEN enthalten:
Co-Authored-By: (Name und Attributionszeile des Agentenmodells)
## Dateibezogene Befehle
| Aufgabe | Befehl |
|---------|--------|
| Typcheck | `pnpm tsc --noEmit path/to/file.ts` |
| Lint | `pnpm eslint path/to/file.ts` |
| Test | `pnpm jest path/to/file.test.ts` |
## API-Routen
[Vorlagen-Codeblock]
## CLI
| Befehl | Beschreibung |
|--------|--------------|
| `pnpm cli sync` | Daten synchronisieren |
Einschränkungen
- Verwende diese Skill nur, wenn die Aufgabe eindeutig dem oben beschriebenen Umfang entspricht.
- Behandle die Ausgabe nicht als Ersatz für umgebungsspezifische Validierung, Tests oder fachliche Prüfung.
- Halte inne und bitte um Klärung, wenn erforderliche Eingaben, Berechtigungen, Sicherheitsgrenzen oder Erfolgskriterien fehlen.