Wer mit KI-Agenten arbeitet, kennt das Problem: Der Agent liefert beim ersten Versuch gute Ergebnisse – beim zweiten leicht andere – beim dritten wieder anders. Konsistenz ist die größte Herausforderung beim Agenten-Einsatz. Eine gut strukturierte Agents.md-Datei ist eine der wirksamsten Lösungen.
Was ist eine Agents.md? Im Kontext von KI-Agenten-Frameworks – vor allem Claude Code, aber auch anderen – ist die Agents.md eine Konfigurationsdatei in natürlicher Sprache, die dem Agenten erklärt: Wer er ist, was sein Ziel ist, welche Regeln er befolgt, welche Werkzeuge er nutzt und wie er mit verschiedenen Situationen umgeht.
Anders als reine System-Prompts ist die Agents.md eine lebende Dokumentation – sie wird mit dem Projekt eingecheckt, versioniert und von Menschen gelesen. Sie ist gleichzeitig Konfiguration für den Agenten und Dokumentation für das Team.
Die wichtigste Grundregel: Schreibe für den Agenten, nicht für einen Menschen. Das klingt trivial, ist es aber nicht. Wenn du für einen Menschen schreibst, lässt du implizites Wissen weg – du gehst davon aus, dass der Leser Kontext hat. Ein KI-Agent hat keinen impliziten Kontext. Alles, was für ihn wichtig ist, muss explizit stehen.
Struktur einer guten Agents.md: Der erste Abschnitt ist die Rollen-Definition. Wer ist dieser Agent? Was ist sein Kernzweck? Zum Beispiel: 'Du bist ein SEO-Texter für derprozessmeister.de. Du schreibst Blogartikel auf Deutsch über KI-Themen für mittelständische Unternehmen.' Diese Einführung gibt dem Agenten einen stabilen Identitätsrahmen.
Der zweite Abschnitt dokumentiert den Kontext: Projekt-Überblick, Tech-Stack, kritische Abhängigkeiten. Wo liegt der Code? Welche Datenbank wird genutzt? Was sind bekannte Fallstricke? Je mehr relevanter Kontext, desto besser die Agentenleistung.
Dritter Abschnitt: Verhaltensregeln. Das ist der kritischste Teil. Hier definierst du, wie der Agent handeln soll – und was er nicht tun darf. Gute Verhaltensregeln sind: konkret statt abstrakt ('Schreibe immer auf Deutsch' statt 'Sei sprachlich konsistent'), positiv formuliert ('Prüfe immer gegen die echten DB-Spalten') und vollständig ('Verwende niemals organization_id – immer org_id').
Vierter Abschnitt: Tools und Ressourcen. Welche Werkzeuge hat der Agent zur Verfügung? Wann soll er welches nutzen? Wie sind die Prioritäten? Ein Agent mit zehn Tools, aber ohne Anleitung zur Toolwahl, wird ineffizient arbeiten.
Fünfter Abschnitt: Entscheidungslogik. Wie soll der Agent vorgehen, wenn er unsicher ist? Beispiel: 'Bei Unklarheiten zum Datenbankschema immer ~/.claude/context/database-tables.md konsultieren, nicht raten.' Das verhindert Halluzinationen in kritischen Bereichen.
Sechster Abschnitt: Stil und Format. Wie sollen Ausgaben aussehen? Welche Markdown-Struktur wird erwartet? Welcher Ton ist gewünscht? Für Content-Agenten ist das essenziell – ohne Stil-Vorgaben ist jede Ausgabe anders.
Häufige Fehler bei Agents.md-Dateien: Zu abstrakt. 'Sei professionell' bedeutet für einen Agenten nichts. 'Verwende Siezen-Form, vermeide Umgangssprache, halte Sätze unter 25 Wörtern' bedeutet etwas.
Zu lang und unstrukturiert. Eine Agents.md, die unkontrolliert wächst und hunderte von Regeln in Fließtext enthält, wird vom Agenten schlechter verarbeitet als eine kurze, gut strukturierte. Weniger ist oft mehr – aber jede Zeile muss präzise sein.
Veraltete Informationen. Eine Agents.md, die nicht gepflegt wird, wird zur Fehlerquelle. Wenn sich das Datenbankschema ändert, muss die Agents.md aktualisiert werden. Wenn sich der Tech-Stack ändert, muss die Agents.md das reflektieren. Veraltete Konfiguration ist schlimmer als keine Konfiguration.
Best Practices aus der Praxis: Verwende Hierarchien – Abschnitte mit klaren Überschriften, die der Agent parsen kann. Nutze Tabellen für strukturierte Informationen (Datenbankfelder, Tool-Übersichten, Fehler-Log). Markiere kritische Regeln mit WICHTIG oder anderen Signalindikatoren. Füge Beispiele ein – 'richtig/falsch' Beispiele sind besonders wertvoll.
Versionierung der Agents.md ist wichtig. Füge einen Zeitstempel ein ('Stand: 2026-06-07') und dokumentiere wichtige Änderungen. Wenn ein Bug durch eine veraltete Regel in der Agents.md verursacht wurde, ist das wertvolles Lernmaterial.
Multi-Agenten-Systeme brauchen multiple Agents.md-Dateien. Der Orchestrator-Agent hat eine Agents.md, die die Koordinationslogik beschreibt. Jeder Sub-Agent hat eine eigene, spezialisierte Agents.md. Die Hierarchie und die Kommunikationsprotokolle zwischen Agenten sollten dokumentiert sein.
Fazit: Eine Agents.md ist kein lästiges Dokument – sie ist der Kernhebelungspunkt für konsistente, hochwertige Agenten-Ausgaben. Investiere Zeit in eine gute Agents.md. Sie zahlt sich aus, indem sie teure Korrekturen, Inkonsistenzen und Halluzinationen reduziert. Behandle sie wie Code – versioniere sie, pflege sie, verbessere sie iterativ.
