CLAUDE.md und AGENTS.md: Deinem Agent die Regeln beibringen

Überblick

CLAUDE.md und AGENTS.md sind schlichte Markdown-Dateien, die in deinem Repository liegen und die der Agent zu Beginn jeder Session automatisch liest. Sie halten deine Axiome, deinen Stack, deine Konventionen, deine Sicherheitsregeln und deinen Ton. Eine gute zu schreiben ist der Unterschied zwischen dem ewigen Korrigieren derselben fünf Fehler und einem Agent, der dein Projekt einfach versteht. Die tiefere Idee, die sich aufaddiert, ist, die Datei als lebende Skills-Library zu behandeln: jeder Gotcha, auf den du stösst, wandert einmal in eine Markdown-Datei und kostet dich nie wieder etwas.

Was du lernst

Du lernst genau, was in eine Projektregel-Datei gehört, wie du Regeln als knackige Axiome formulierst, denen der Agent tatsächlich folgt, den Unterschied zwischen einer Root-CLAUDE.md und der AGENTS.md, die Codex und andere Harnesses lesen, und wie du aus der Datei ein kontinuierlich lernendes System machst, in dem jede wiederholte Korrektur zur dauerhaften Regel wird. Am Ende hast du eine echte Datei, die du heute in dein eigenes Projekt einfügen kannst.

Voraussetzungen

Ein funktionierendes Claude-Code-Setup und die Prompt-Engineering-Lektion aus Kurs 1, denn die Axiome, die du dort geschrieben hast, wandern direkt in diese Datei. Du solltest ausserdem ein versionskontrolliertes Projekt aus Kurs 1 haben, denn die Regel-Datei lebt im Repo und wird neben deinem Code committet, damit das ganze Projekt dieselben Standards teilt.

Das Problem

Du korrigierst den Agent. Er nutzt den falschen Paketmanager, du behebst es. Er fügt ein Em-Dash ein, du behebst es. Er überspringt den Test, du behebst es. Nächste Session, frischer Kontext, dieselben drei Fehler. Du zahlst Tokens und Aufmerksamkeit, um dieselben Lektionen immer wieder neu beizubringen, weil nichts von dem, was du gesagt hast, überdauert hat. Der Agent ist nicht dumm, er hat nur kein Gedächtnis zwischen Sessions. Eine Regel-Datei ist dieses Gedächtnis. Ohne sie startet dein Agent jeden Tag mit Amnesie und du bist sein Vollzeit-Aufpasser.

Was eine Regel-Datei tatsächlich ist

CLAUDE.md ist eine Markdown-Datei, die Claude Code automatisch lädt und als stehende Anweisung für die ganze Session behandelt. Leg sie in die Wurzel deines Repos für projektweite Regeln. Du kannst auch eine persönliche unter ~/.claude/CLAUDE.md halten für Regeln, die dir über jedes Projekt folgen, und Claude Code führt sie zusammen. AGENTS.md ist die gleichwertige Datei, die Codex und eine wachsende Zahl anderer Harnesses lesen, also hält ein tool-übergreifendes Team oft beide, oder die echten Regeln in einer und einen kurzen Verweis in der anderen. Alles, was du sonst in jeden Prompt neu tippen würdest, gehört hierher: Sprache, Framework, Paketmanager, Test-Policy, Sicherheitsregeln, Namenskonventionen und Ton.

• Root-CLAUDE.md: Projektregeln, ins Repo committet, geteilt von allen, die darin arbeiten.
• Persönliche ~/.claude/CLAUDE.md: deine eigenen projektübergreifenden Vorlieben, nicht committet.
• AGENTS.md: dieselbe Rolle für Codex und andere Harnesses, damit Multi-Tool-Setups konstant bleiben.
• Sie wird in jeder Runde geladen, also halt sie knapp - eine aufgeblähte Regel-Datei frisst dasselbe Kontextfenster, das deine Aufgabe braucht.

Regeln als Axiome schreiben

Ein Agent folgt einem knackigen Absolutum weit besser als einem Absatz voller Nuancen. Formuliere jede Regel als "Immer...", "Nie..." oder "Jedes... muss...". Gruppiere sie nach Thema, damit die Datei scanbar bleibt. Hier ist eine echte, kompakte CLAUDE.md, die du heute in ein Projekt fallen lassen könntest. Beachte, dass sie die Dinge abdeckt, die du immer wieder korrigierst, nicht alles Erdenkliche. Kurz und befolgt schlägt lang und ignoriert.

# Project Rules

## Stack
- TypeScript only. No plain JavaScript files.
- Package manager is bun. Never use npm or yarn.
- Framework is Astro for marketing pages, React for the app.

## Conventions
- Use rounded-sm for border-radius on everything.
- Never use em dashes. Use a normal "-" instead.
- Components are PascalCase, files are kebab-case.

## Quality
- Every new feature ships with a test.
- Before you say a task is done, run: bun run lint && bun run typecheck && bun run test.

## Security
- Secrets live in .env, which is gitignored. Never write a key into committed code.
- Default new repos to private.

## Tone
- Direct and concise. No filler, no apologising, no "as an AI".

Die Skills-Library-Philosophie

Das ist der Teil, der aus einer Konfigurationsdatei einen Wettbewerbsvorteil macht. Behandle CLAUDE.md als wachsende Bibliothek hart erarbeiteten Wissens, nicht als einmaliges Setup. Jedes Mal, wenn der Agent einen Fehler macht, der wiederkehren wird, behebst du ihn nicht nur im Moment - du schreibst ihn als Regel auf. Der Agent hat das falsche Verzeichnis für Tests gewählt? Ergänze eine Regel. Er hat falsch verstanden, wie dein Auth-Flow funktioniert? Ergänze eine Notiz. Über ein paar Wochen wird die Datei zu einem präzisen Modell davon, wie dein konkretes Projekt wirklich funktioniert, voller Gotchas, die kein generisches Modell kennen könnte. Der Agent braucht dann immer weniger Handführung, weil das institutionelle Wissen im Repo lebt, nicht in deinem Kopf.

• Der Auslöser ist Wiederholung: jede Korrektur, die du dir zweimal vorstellen kannst, wird beim ersten Mal zur Regel.
• Halt Gotchas fest, nicht nur Stil: "der Convex-Dev-Server muss vor den Tests laufen" ist mehr wert als eine Namensregel.
• Du kannst es dem Agent auftragen: "Ergänze eine Regel in der CLAUDE.md, damit du diesen Fehler nie wieder machst" funktioniert und ist eine Gewohnheit, die man pflegen sollte.
• Die Datei wird geteilt und committet, also ist ein Gotcha, den du entdeckt hast, jetzt für jede künftige Session und jedes Teammitglied gelöst.

Sie lebendig halten, nicht abgestanden

Eine Regel-Datei verrottet, wenn du immer nur ergänzt. Überprüf sie nach grossen Aufgaben. Streiche Regeln, die nicht mehr gelten, weil sich der Stack geändert hat. Befördere eine nützliche Einmal-Anweisung, die du ständig einfügst, zur dauerhaften Regel. Teile eine riesige Datei in verlinkte Unterdateien, wenn sie unhandlich wird, denn du kannst aus der CLAUDE.md auf andere Markdown-Dateien verweisen und die Wurzel schlank halten. Die Investition zahlt sich auf die befriedigendste Art aus: jede künftige Aufgabe startet von einer schlaueren Basis, und der Abstand zwischen dir und jemandem, der einen nackten Agent fährt, wird jede Woche grösser. Das ist dieselbe Schleife kontinuierlichen Lernens, die sich durch den restlichen Kurs zieht - die Lektion einmal festhalten, für immer profitieren.

Typische Fehler

Die häufigen Fehler: eine 500-zeilige Regel-Datei schreiben, die die wichtigen Regeln vergräbt und dein Kontextfenster frisst; Regeln als sanfte Vorschläge formulieren ("es wäre schön, wenn..."), die der Agent als optional behandelt; sie einmal einrichten und nie aktualisieren, sodass sie langsam aus dem Takt mit dem echten Projekt gerät; und Regeln über CLAUDE.md und AGENTS.md duplizieren, bis sie sich widersprechen. Halt sie knapp, halt sie absolut, halt sie aktuell und halt eine einzige Quelle der Wahrheit.

Business-ROI

Eine gute Regel-Datei ist das günstigste Qualitäts- und Konstanz-Upgrade, das du je kaufen wirst. Sie verwandelt dein persönliches Wissen in einen Vermögenswert, der im Repo lebt, sodass eine neue Agent-Session - oder eine neue Einstellung, oder ein Freelancer - sofort produktiv und auf Standard ist, statt erst nach einer Woche Korrekturen. Für eine Gründerin ist das der Weg, aufzuhören, der Flaschenhals zu sein. Das institutionelle Wissen, das früher nur in deinem Kopf lebte und mit jedem Session-Ende zur Tür hinausging, addiert sich jetzt in einer Datei, die dein ganzes Business teilt. Das ist Hebelwirkung, die du für immer behältst.

Checkliste

Du bist bereit weiterzugehen, wenn jedes davon stimmt. Überspring die Punkte zur lebenden Datei nicht - dort steckt der echte Wert.

• Du hast eine Root-CLAUDE.md in deinem Projekt committet, mit Regeln zu Stack, Konventionen, Qualität und Sicherheit.
• Deine Regeln sind als Absolute formuliert, nicht als Vorschläge.
• Du hast mindestens einen echten Gotcha festgehalten, den du vorher von Hand korrigiert hast.
• Du weisst, wie du den Agent bittest, eine neue Regel zu ergänzen, wenn er ausrutscht.

Ressourcen

Halt die offizielle Dokumentation zu Claude-Code-Memory und CLAUDE.md als Lesezeichen für das genaue Lade- und Merge-Verhalten, denn die Details entwickeln sich. Die Axiome, die du in der Prompting-Lektion aus Kurs 1 gespeichert hast, sind der Keim dieser Datei - füge sie als deine ersten Regeln ein. Das Agent-Task-Brief-Template in der Ressourcen-Bibliothek passt gut zu einer Regel-Datei: die Regeln decken die konstanten Standards ab, das Brief die Besonderheiten je Aufgabe.

Deine Aufgabe

Erstelle eine CLAUDE.md in der Wurzel eines echten Projekts. Füll sie mit deinem Stack, drei Konventionen, die du ständig korrigierst, deinem Quality-Gate-Befehl und deiner Secret-Handling-Regel. Das nächste Mal, wenn der Agent einen Fehler macht, behebst du ihn nicht nur, sondern trägst ihm auf, eine Regel zu ergänzen, damit es nie wieder passiert. Sieh zu, wie die Datei zu etwas wächst, das nur dein Projekt haben könnte.

Nächste Lektion

Mit den Regeln an Ort und Stelle kennt der Agent deine Standards. Die nächste Lektion verpackt deine tatsächlichen Workflows: Skills und Slash Commands, die aus einem bewährten mehrschrittigen Prozess einen einzigen wiederverwendbaren Auslöser machen, sodass häufige Arbeit jedes Mal gleich läuft, ohne dass du das Brief neu tippst.