Agentic-Coding-Tools

CLAUDE.md und AGENTS.md schreiben, die wirklich helfen

Eine gute CLAUDE.md oder AGENTS.md teilt einem Coding Agent die wenigen Dinge mit, die er nicht leicht aus dem Code ableiten kann: exakte Build- und Testbefehle, architektonische Orientierungspunkte, Teamkonventionen, verbotene Aktionen und wie eine Änderung verifiziert wird. Halten Sie die Datei kurz, konkret und gepflegt, dann verbessert sie jede einzelne Agenten-Session in Ihrem Repository.

neooutput Redaktion 4 Min. Lesezeit Read in English

Was sind CLAUDE.md und AGENTS.md?

Es sind Markdown-Dateien in Ihrem Repository, die Coding Agents automatisch lesen, um zu verstehen, wie in Ihrem Projekt gearbeitet wird.

Claude Code liest CLAUDE.md-Dateien, die im Root des Repositorys und in Unterverzeichnissen liegen können, und unterstützt zusätzlich persönliche Memory-Dateien, die nicht eingecheckt werden. AGENTS.md ist eine offene Konvention, die OpenAI Codex und eine wachsende Zahl weiterer Agenten lesen. Inhaltlich erfüllen beide denselben Zweck: Sie sind Onboarding-Dokumentation, geschrieben für einen Agenten, und erweisen sich oft auch für neue menschliche Teammitglieder als nützlich.

Was hineingehört

Nehmen Sie Informationen auf, die wesentlich, nicht offensichtlich und stabil sind.

  • Befehle: wie Abhängigkeiten installiert, gebaut, alle Tests ausgeführt, ein einzelner Test ausgeführt, gelintet und formatiert wird.
  • Architektonische Orientierungspunkte: wo die Hauptmodule liegen, wie Requests fließen, welche Verzeichnisse generiert sind.
  • Konventionen, die von den Standards abweichen: Fehlerbehandlung, Benennung, State Management, Logging.
  • Verifikation: was erfolgreich durchlaufen muss, bevor eine Aufgabe als erledigt gilt.
  • Harte Regeln: Dateien oder Verzeichnisse, die nie bearbeitet werden, Befehle, die nie ausgeführt werden, Abhängigkeiten, die nicht ohne Freigabe hinzukommen.
  • Bekannte Stolperfallen: instabile Tests, Eigenheiten der Umgebung, Legacy-Bereiche, die besondere Sorgfalt brauchen.

Was draußen bleiben sollte

Lassen Sie alles weg, was der Agent aus dem Code selbst lesen kann, was sich wöchentlich ändert, und allgemeine Ratschläge.

Lange Beschreibungen jedes Moduls, kopierte API-Dokumentation, motivierende Anweisungen wie „schreibe sauberen Code“ und veraltete Architekturnotizen verwässern das Signal. Jede Zeile der Datei verbraucht Kontext und konkurriert um die Aufmerksamkeit des Agenten. Eine fokussierte Datei mit ein paar Dutzend präzisen Zeilen schlägt meist ein ausuferndes Dokument. Brauchen Sie ausführliche Dokumentation, verweisen Sie aus der Datei darauf und lassen Sie den Agenten sie lesen, wenn sie relevant ist.

Eine praxistaugliche Struktur

Eine einfache, einheitliche Struktur macht die Datei für Agenten und Menschen leicht überfliegbar.

  1. Projektüberblick in einem Absatz: was es ist, Haupttechnologien.
  2. Abschnitt mit Befehlen: exakt und direkt kopierbar.
  3. Projektstruktur: wichtige Verzeichnisse und ihr Zweck.
  4. Konventionen: kurze Liste teamspezifischer Regeln.
  5. Workflow: vor großen Änderungen planen, Diffs klein halten, vor Abschluss Tests ausführen.
  6. Verboten: explizite Liste unzulässiger Aktionen.

Monorepos und verschachtelte Dateien

Nutzen Sie in Monorepos eine kurze Datei im Root für gemeinsame Regeln und verschachtelte Dateien in den Paketen für paketspezifische Befehle und Konventionen.

Claude Code berücksichtigt CLAUDE.md-Dateien in Unterverzeichnissen, wenn es dort arbeitet, und auch die AGENTS.md-Konvention erlaubt verschachtelte Dateien, wobei typischerweise die nächstgelegene Datei Vorrang hat. So bleibt jede Datei klein und relevant. Vermeiden Sie es, Inhalte aus dem Root in jeder verschachtelten Datei zu wiederholen; Wiederholungen machen Aktualisierungen fehleranfällig.

Die Datei aktuell halten

Behandeln Sie die Kontextdatei wie Code: Änderungen in Pull Requests reviewen und sie aktualisieren, sobald ein Agent wiederholt denselben Fehler macht.

Eine nützliche Gewohnheit ist eine kurze Retrospektive nach misslungenen Agenten-Sessions: Hätte ein Satz in der Kontextdatei das verhindert? Wenn ja, ergänzen Sie ihn. Ebenso sollten Zeilen, die nicht mehr gelten, entfernt werden. Manche Teams benennen pro Datei eine verantwortliche Person. Nutzen Sie sowohl Claude Code als auch Codex, pflegen Sie eine kanonische Datei und verweisen Sie aus der anderen darauf, damit nichts auseinanderdriftet.

Häufige Fehler

Die häufigsten Fehler sind Dateien, die zu lang, zu vage oder nie aktualisiert sind.

Weitere Probleme sind Anweisungen, die dem tatsächlichen Tooling widersprechen, Secrets oder interne URLs, die nicht ins Repository gehören, und Regeln, die als Wünsche statt als überprüfbare Anweisungen formuliert sind. „Führe vor Abschluss die komplette Testsuite mit diesem Befehl aus“ ist umsetzbar; „stelle sicher, dass alles funktioniert“ ist es nicht. In den Agentic Coding Workshops von neooutput schreiben und straffen Teams ihre eigenen Kontextdateien an ihrer echten Codebasis, und das ist oft die wirkungsvollste Stunde des Tages.

Häufige Fragen

Sollte ich CLAUDE.md oder AGENTS.md verwenden?

Verwenden Sie die Datei, die Ihr primäres Tool liest. Claude Code liest CLAUDE.md, Codex und mehrere andere Agenten lesen AGENTS.md. Nutzt Ihr Team beide, pflegen Sie eine kanonische Datei und verweisen Sie aus der anderen darauf.

Wie lang sollte die Datei sein?

So kurz wie möglich, solange Befehle, Struktur, Konventionen und harte Regeln abgedeckt sind. Viele wirksame Dateien liegen deutlich unter einigen hundert Zeilen; Kürze verbessert den Fokus.

Kann der Agent die Datei selbst schreiben?

Ein Agent kann durch Erkunden des Repositorys einen brauchbaren ersten Entwurf erstellen. Ein Mensch sollte ihn dann kürzen, korrigieren und um das nicht offensichtliche Wissen ergänzen, das nur das Team hat.

Gehören Secrets oder interne URLs in die Kontextdatei?

Nein. Die Datei wird ins Repository eingecheckt und von Agenten gelesen, die Kontext an Modellanbieter senden. Halten Sie Zugangsdaten vollständig heraus und verweisen Sie auf interne Systeme nur so weit wie nötig, ohne Tokens oder Passwörter.

Alle Insights