CLAUDE.md und AGENTS.md: Regeln für KI-Code im Team

CLAUDE.md und AGENTS.md sind Dateien im Repository, aus denen ein KI-Agent bei jeder Aufgabe die Regeln des Teams lädt. Regeln für KI-Code im Team gehören genau dorthin, nicht in den Kopf eines Seniors. Eine kurze Datei für den Agenten, CLAUDE.md oder AGENTS.md, sagt, wie Arbeit geprüft wird und was der Agent nicht darf. Das Wichtigste sollte aber kein Text sein. Es sollten Lint, Tests oder CI sein, die eine schlechte Änderung von selbst stoppen.

KI schreibt heute unseren gesamten Code, und für das Ergebnis haftet ein Senior. Seit 2023 haben wir 15+ Produktionsprojekte geliefert. Davor war Filip 7 Jahre im Produktteam eines SaaS, das täglich über 60.000 Menschen nutzten. Die Regeln unten haben wir bei diesen Projekten gelernt, meist aus eigenen Fehlern.

Was gehört in CLAUDE.md oder AGENTS.md?

Was der Agent nicht aus dem Code herausfindet, und was Sie anders machen als andere. Konkret:

• Wie man Projekt und Tests startet. Am besten mit einem Befehl, den der Agent kopieren kann.
• Was der Agent nicht darf. Produktionsdatenbank, geheime Schlüssel, Migrationen ohne Freigabe, direkter Push auf den Hauptbranch.
• Wo was liegt. Wo die Geschäftslogik ist, wo die Tests, was generiert ist und nicht von Hand geändert werden darf.
• Unübliche Konventionen. Wie Sie Dinge benennen, wie Sie Fehler behandeln, wo Übersetzungen liegen.
• Wie fertige Arbeit aussieht. Was durchlaufen muss, bevor der Agent einen Pull Request öffnet.

Was nicht hineingehört: Stil, den der Formatter schon überwacht. Lange Essays über Architektur. Regeln, die nur in einem Ordner gelten.

CLAUDE.md oder AGENTS.md?

Claude Code liest CLAUDE.md. Viele andere Tools, etwa Codex, lesen AGENTS.md. Nutzt Ihr Team mehrere Tools, schreiben Sie die Regeln nicht zweimal.

Pflegen Sie sie in AGENTS.md und verweisen Sie aus CLAUDE.md mit der Zeile @AGENTS.md darauf. Claude Code lädt die Datei dann selbst. Zwei getrennte Kopien laufen auseinander, bevor es jemand merkt.

Wie viele Regeln sind zu viele?

Die Grenze kommt früher, als Sie denken. Der Agent lädt die Regeln bei jedem Start. Je mehr Text er im Kontext hat, desto schlechter hält er sich an das Wesentliche.

Bewährt hat sich bei uns eine Aufteilung in drei Ebenen. Im Root des Repositorys steht das Minimum, das überall gilt. Die Regeln eines Moduls liegen in einer Datei direkt in seinem Ordner, und der Agent lädt sie erst, wenn er dort arbeitet. Das Wichtigste ist Lint oder ein Test: Niemand muss es lesen, es stoppt eine schlechte Änderung selbst.

Ehrlich gesagt: Eine perfekte Antwort haben wir nicht. Mit jedem Fehler kommen Regeln dazu. Deshalb räumen wir sie regelmäßig auf und verschieben alles, was geht, in Lint.

Woher nimmt man Regeln, wenn man noch keine hat?

Aus dem Review. Ein Kommentar, der im Review zum zweiten Mal fällt, ist kein Fehler des Entwicklers. Er ist eine Lücke in den Regeln. Das Vorgehen ist einfach:

Wir empfehlen oft, den Agenten alte Review-Kommentare durchgehen und Regeln daraus ziehen zu lassen. Das funktioniert nur, wenn es die Kommentare gibt. Läuft das Review nur mündlich im Call, kommt nichts in die Pull Requests. Dann hat der Agent nichts, woraus er schöpfen kann.

Deshalb erst die Gewohnheit, dann das Tool. Schreiben Sie Feedback in den Pull Request, nicht nur mündlich.

Wohin gehört welche Regel?

Ein Verbot, das nur als Satz dasteht, kann ein Agent umgehen. Er öffnet die Datei nicht, schreibt aber ein Skript, das sie ausgibt. Deshalb notieren wir zu jeder Regel, wodurch sie erzwungen wird.

Der Agent, der bei uns selbstständig arbeitet, läuft in einer getrennten virtuellen Maschine. Von dort erreicht er weder den Livebetrieb noch geheime Schlüssel. Ein Hook, der gefährliche Befehle ablehnt, ist ein guter erster Schritt. Er ist aber eine Bremsschwelle, keine Wand: Ein findiger Agent sucht sich einen anderen Weg. Kein Satz „sei vorsichtig“ ersetzt eines davon.

Die Tabelle und die Verbote samt dem, was sie durchsetzt, stehen in der Vorlage. Vorlage herunterladen: Regeln für KI im Team (PDF).

Wie teilt man Regeln über mehrere Repositories?

Durch Verteilung, nicht durch Disziplin. Unsere Regeln lagen im Haupt-Repository, die anderen sahen sie nicht. Einige haben sie kopiert. Ein paar Monate später gab es mehrere Versionen, keine zwei waren gleich.

Heute haben wir ein Regelpaket, das in jedem Repository geladen wird. Es ist versioniert und ändert sich nur per freigegebenem Pull Request. Kopien gibt es nicht, also kann auch nichts auseinanderlaufen. Persönliche Regeln sind der Arbeitsstil jedes Entwicklers. Gemeinsame Regeln gehören der Firma, und sie müssen an einem Ort leben. Dasselbe Regelpaket richten wir bei Teams ein, die wir im Rahmen von AI-native SDLC für Entwicklerteams unterstützen. Fehlen Ihrem Team eher Hände als Regeln? Sehen Sie sich einen Senior-Entwickler für Ihr Team an.

Review und Tests: Regeln, die nicht in der Datei stehen

Manche Regeln gehören nicht dem Agenten, sondern dem Prozess um ihn herum. Was davon hat Ihr Team schon?

Ein Test, der nie fehlgeschlagen ist, beweist nur, dass der Agent mit sich selbst einverstanden ist. Und eine Pipeline, die nur meldet, ist Dekoration.

Wie Sie diese Regeln im ganzen Team Schritt für Schritt einführen, beschreiben wir im Artikel Wie führt man KI im Entwicklungsteam ein?. Warum der Rahmen wichtiger ist als das Modell, erklärt Agent = Modell + Rahmen. Wenn das Team noch ein Werkzeug auswählt, lesen Sie Cursor vs Claude Code.

Wann wir davon abraten

• Sie sind ein oder zwei Entwickler in einem Repository. Eine kurze CLAUDE.md oder AGENTS.md reicht. Schreiben Sie sie selbst nach der Liste oben.
• Sie haben keine Tests und kein CI, das blockiert. Regeln für den Agenten ändern dann wenig. Erst Tests und CI, dann Regeln.

• Sie erwarten, dass eine Vorlage Ihre Reviews ersetzt. Das tut sie nicht. Regeln entstehen aus Ihren Reviews, beginnen Sie mit Feedback in Pull Requests.

Möchten Sie die Regeln mit jemandem aufsetzen, der täglich damit arbeitet?

Wir schauen uns Ihre Repositories an und schlagen eine erste Version der Regeln und der CI-Prüfungen vor. Ein Senior klinkt sich ab dem ersten Tag in Ihr Repository und Ihre Pull Requests ein.

Wir melden uns innerhalb von zwei Arbeitstagen und wählen gemeinsam, was wir zuerst lösen.

Wenn Sie lieber zuerst sprechen möchten, buchen Sie ein 15-Minuten-Meeting mit Filip.

Wo leben die Regeln Ihres Teams heute?

Häufige Fragen

Was ist CLAUDE.md?

Eine Datei im Repository, die Claude Code bei jedem Start lädt. Darin stehen die Regeln für den Agenten: wie man Tests startet, was er nicht darf und wie fertige Arbeit aussieht. Andere Tools lesen eine ähnliche Datei namens AGENTS.md.

CLAUDE.md oder AGENTS.md?

Nutzt das Team nur Claude Code, reicht CLAUDE.md. Bei mehreren Tools pflegen Sie die Regeln in AGENTS.md und verweisen aus CLAUDE.md mit der Zeile @AGENTS.md darauf. Zwei getrennte Kopien laufen mit der Zeit auseinander.

Wie viele Regeln sollte CLAUDE.md haben?

So wenige wie möglich. Der Agent lädt sie bei jedem Start, und zu viel Text verschlechtert sein Ergebnis. Im Root bleibt nur, was überall gilt. Der Rest gehört in Ordner, das Wichtigste in Lint oder Tests.

Wem sollten die Regeln für KI im Team gehören?

Einer benannten Person, die Änderungen freigibt. Schreiben kann sie jeder per Pull Request. Ohne Verantwortlichen passt sie jeder nach eigenem Geschmack an, und die gemeinsame Schicht zerfällt.

Reicht es, dem Agenten zu schreiben, was er nicht darf?

Nein. Ein schriftliches Verbot kann der Agent umgehen. Was wirklich wichtig ist, erzwingen Sie über Zugriffsrechte, einen Hook, Lint oder CI. Notieren Sie zu jeder Regel, wodurch sie erzwungen wird.