Saison 2026: täglich aktualisiert 💡 Eigene App, Webseite, KI-Agenten oder Digital-Idee? Das Team hinter BreisgauStraussen entwickelt sie für dich!💡 Eigene App oder KI-Agenten? Wir entwickeln sie für dich!

Agentic-Coding-Tools: Ratgeber

AGENTS.md schreiben: Vorlage und Best Practices für Repos

Von John Caffier, Lead AI Code Engineer bei jocapps3 Min. Lesezeit

Eine README richtet sich an Menschen. Eine AGENTS.md richtet sich an Coding-Agenten und beantwortet die Fragen, die sie bei jeder Aufgabe brauchen: Wie wird gebaut, wie getestet, welche Konventionen gelten, was ist tabu? Das offene Format wird von OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI und vielen weiteren Werkzeugen unterstützt. Gut geschrieben, spart die Datei unzählige Korrekturschleifen. Schlecht geschrieben, wird sie ignoriert oder führt den Agenten in die Irre. Hier finden Sie eine erprobte Gliederung und konkrete Formulierungsregeln.

Was in eine AGENTS.md gehört

Die Datei liegt im Wurzelverzeichnis des Repositorys und ist reines Markdown ohne Pflichtfelder. Inhaltlich sollte sie alles enthalten, was ein Agent nicht zuverlässig aus dem Code ableiten kann: die exakten Befehle für Installation, Build, Tests und Linting, die Struktur des Projekts in wenigen Sätzen, Code-Konventionen, die vom Standard der Sprache abweichen, Regeln für Commits und Pull Requests sowie Bereiche, die nicht verändert werden dürfen.

Nicht hinein gehören allgemeine Programmierweisheiten, die jedes Modell kennt, lange Architekturdokumente oder veraltete Hinweise. Jede Zeile kostet Kontext und konkurriert um Aufmerksamkeit.

Eine bewährte Gliederung

Viele Teams fahren gut mit sechs kurzen Abschnitten. Projektüberblick: zwei bis drei Sätze zu Zweck und Stack. Setup und Befehle: genaue Kommandos, die ohne Rückfrage funktionieren. Code-Stil: nur die Abweichungen und Besonderheiten. Tests: welche Suite wann läuft und was vor einem Commit grün sein muss. Sicherheit: Umgang mit Secrets, gesperrte Verzeichnisse, verbotene Abhängigkeiten. Pull Requests: Titelformat, Beschreibung, Umfang.

Ergänzen Sie bei Bedarf einen Abschnitt mit bekannten Stolpersteinen, etwa einen Test, der nur mit laufender Datenbank funktioniert, oder ein Modul, das bewusst veralteten Code enthält. Genau solche Hinweise sparen in der Praxis die meiste Zeit.

Verwenden Sie klare Überschriften und kurze Listen statt langer Fließtexte. Agenten lesen die Datei bei jeder Aufgabe, und eine eindeutige Struktur hilft ihnen, die relevante Regel schnell zu finden. Wiederholen Sie Informationen nicht, die bereits in Konfigurationsdateien stehen, sondern verweisen Sie auf die Datei, etwa die Linter-Konfiguration oder die Workflow-Definition Ihrer CI.

Formulierungsregeln, die wirken

Schreiben Sie Anweisungen konkret und prüfbar. Statt achte auf gute Tests besser: Jede neue öffentliche Funktion braucht mindestens einen Unit-Test im Ordner tests. Nennen Sie Befehle exakt so, wie sie ausgeführt werden. Begründen Sie Verbote kurz, denn Agenten halten sich zuverlässiger an Regeln, deren Zweck sie kennen.

Halten Sie die Datei kurz und aktuell. Als grobe Orientierung sollte sie auf wenige Bildschirmseiten passen. Wenn Sie merken, dass der Agent einen Fehler wiederholt, ergänzen Sie eine präzise Regel. Wenn eine Regel nie gebraucht wird, streichen Sie sie.

Vermeiden Sie Widersprüche zwischen AGENTS.md, README und Konfiguration. Wenn die Datei einen anderen Testbefehl nennt als die CI tatsächlich nutzt, folgt der Agent der falschen Quelle und produziert Ergebnisse, die lokal grün und in der Pipeline rot sind. Ein kurzer Abgleich bei jedem Release verhindert das zuverlässig.

Monorepos und mehrere Werkzeuge

In größeren Repositories können Sie in Unterordnern eigene AGENTS.md-Dateien ablegen. Die Datei, die der bearbeiteten Stelle am nächsten liegt, hat Vorrang, ergänzt also die übergeordneten Regeln um paketspezifische Details. So bleibt die Wurzeldatei schlank.

Nutzt Ihr Team zusätzlich Claude Code, liest dieses Werkzeug die CLAUDE.md. Um doppelte Pflege zu vermeiden, verweisen Sie in der CLAUDE.md per Import auf die AGENTS.md und ergänzen dort nur Claude-spezifische Hinweise.

  1. Legen Sie eine AGENTS.md im Wurzelverzeichnis mit den sechs Kernabschnitten an.
  2. Testen Sie jeden Befehl in einer frischen Umgebung, bevor er in die Datei kommt.
  3. Ergänzen Sie paketspezifische Dateien nur dort, wo sich Befehle oder Regeln wirklich unterscheiden.
  4. Prüfen Sie die Datei bei jeder größeren Änderung an Build oder Tests im Rahmen des Pull Requests.

Unterstützung beim Playbook

Eine gute AGENTS.md ist Teamarbeit, denn sie bündelt implizites Wissen, das oft nur in einzelnen Köpfen steckt. Die AI Code Engineers von neooutput erarbeiten mit Ihnen Playbooks für AGENTS.md und CLAUDE.md, testen sie an realen Aufgaben und schulen Ihr Team in der Pflege. Ob sich das für Ihr Repository lohnt, klären wir gern in einem kostenlosen 15-Minuten-Erstgespräch.

Häufige Fragen

Welche Werkzeuge lesen AGENTS.md?

Unter anderem OpenAI Codex, Cursor, GitHub Copilot, Jules, Aider und weitere Agenten unterstützen das Format oder lassen sich entsprechend konfigurieren. Claude Code liest die CLAUDE.md, die per Verweis auf die AGENTS.md zurückgreifen kann.

Wie lang darf eine AGENTS.md sein?

Es gibt kein festes Limit, aber kürzer ist meist besser. Konzentrieren Sie sich auf Informationen, die der Agent nicht selbst aus dem Code ableiten kann. Lange Hintergrunddokumente legen Sie besser als eigene Datei im Repository ab und verweisen darauf.

Ersetzt AGENTS.md die README?

Nein. Die README erklärt Menschen das Projekt, die AGENTS.md gibt Agenten präzise Arbeitsanweisungen. Beide ergänzen sich und dürfen sich gern aufeinander beziehen.