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

Für CTOs, Tech-Leads und Entwickler. Ihr Team nutzt bereits Claude Code, Codex, Cursor oder Copilot. Bisher arbeitet jeder nach eigenen Regeln. Diese Vorlage macht daraus eine gemeinsame Ebene.

KI schreibt heute unseren gesamten Code. Für das Ergebnis bürgt ein Senior-Entwickler. Seit 2023 haben wir 15+ Produktionsprojekte ausgeliefert. Diesen Rahmen nutzen wir dabei.

1. Warum Textregeln nicht reichen

Sie verbieten dem Agenten, eine Datei zu öffnen. Er öffnet sie nicht. Er schreibt sich ein Skript, das den Inhalt ausgibt.

Das ist keine böse Absicht. Der Agent hat eine Aufgabe und sucht Wege. Ein Satz im Prompt ist für ihn ein Hindernis, keine Mauer. Jede Regel unten enthält eine Spalte, die den meisten „KI-Richtlinien“ fehlt. Sie zeigt, was ihn wirklich stoppt.

Wurde eine Regel zweimal gebrochen, reicht ein reiner Satz nicht mehr. Stufen Sie diese Regel eine Ebene höher.

2. Acht Dinge, die der Agent nicht darf

Beim achten Punkt schreiben wir ehrlich „nur ein Satz“. Mechanisch hält diesen Punkt heute noch kein Werkzeug zuverlässig auf. Eine Regel, die ihre Schwäche zugibt, schlägt jede vorgetäuschte Stärke.

Wie viele Ihrer Regeln sind nur ein Satz? Genau so viele Lücken haben Sie.

3. Wohin welche Regel gehört

Der Agent lädt die Regeldatei bei jedem Start. Je mehr Text er liest, desto schlechter beachtet er das Wesentliche. Deshalb nutzen wir drei Ebenen:

1. Repository-Root: Kurze CLAUDE.md oder AGENTS.md. Klärt Zweck des Repos, Testbefehle, Verbote und Definition fertiger Arbeit.
2. Ordner: Modulregeln in einer Datei direkt im jeweiligen Ordner. Der Agent lädt sie erst bei der Arbeit dort.
3. Lint oder Test: Das Wichtigste. Niemand muss das lesen. Es stoppt fehlerhafte Änderungen automatisch.

Nutzen Sie mehrere Werkzeuge? Pflegen Sie Regeln in AGENTS.md. In CLAUDE.md verweisen Sie mit der Zeile @AGENTS.md darauf. Zwei Kopien driften auseinander, bevor es jemand bemerkt.

Dateistruktur

CLAUDE.md  oder  AGENTS.md    kurz: Repo, Befehle, Links
.claude/
  settings.json               Verbote in maschinenlesbarer Form
  hooks/push-gate.sh          was Einstellungen nicht abdecken
  rules/
    00-never.md               8 Verbote + Spalte „was ihn stoppt“
    10-task.md             was eine Aufgabe braucht, bevor der Agent startet
    20-gates.md               Lint, Typecheck, Tests: blockiert ja/nein
    30-review.md              wer reviewt und was geliefert wird
    90-ownership.md         wer die Regeln besitzt und wie neue entstehen

4. Vorlagen für das Repository

Die Beispiele gelten für Claude Code. Das Prinzip aus Verbot, Hook, CI und Lint gilt für alle Werkzeuge. Nur die Schreibweise unterscheidet sich.

Verbote in den Einstellungen (Punkte 1 bis 5)

{
  "permissions": {
    "deny": [
      "Bash(psql:*)",
      "Bash(git push --force:*)",
      "Bash(git reset --hard:*)",
      "Read(.env.prod*)",
      "Read(**/*.pem)"
    ],
    "ask": [
      "Read(**/.env*)",
      "Bash(npx prisma migrate deploy:*)"
    ]
  }
}

Achtung: Die Regel prüft den Befehlstext, nicht die Absicht. Darf der Agent cat nutzen, umgeht cat .env das Leseverbot. Secrets gehören deshalb außerhalb des Repositories. Skripte laden sie, geben sie aber niemals aus.

Hook gegen Push auf Main (Punkt 5)

#!/bin/bash
# .claude/hooks/push-gate.sh  (PreToolUse, Bash)
# exit 0 = erlauben, exit 2 = stoppen
CMD=$(jq -r '.tool_input.command // empty')
[[ "$CMD" != *"git push"* ]] && exit 0
case "$CMD" in
  *" main"*|*" master"*)
    echo "Push auf Main ist verboten. Eröffnen Sie einen PR." >&2
    exit 2 ;;
esac
exit 0

Zwei typische Fehler setzen den Hook heimlich außer Kraft. Ein || true hinter dem Hook überschreibt Exit 2 zu 0. Ein 2>/dev/null verwirft die Fehlermeldung. Der Agent versteht dann nicht, warum der Befehl scheitert. Testen Sie den Hook einmal unter realen Bedingungen. Aktivieren Sie serverseitigen Branch-Schutz. Der Hook greift schließlich nur dort, wo er auch installiert ist.

Tests und Review (Punkte 6 und 7)

• Der Test muss zuerst fehlschlagen. Und zwar auf dem Originalcode. Sonst bestätigt der Agent nur sich selbst.
• Tests aus der Aufgabenstellung genehmigt ein Mensch. Die CI warnt, wenn ein PR Tests und Code gleichzeitig anfasst. Der Reviewer entscheidet.
• Wer geschrieben hat, reviewt nicht. Starten Sie das Review in einem frischen Kontext, idealerweise mit einem anderen Modell. Es erhält das Diff und Ihre Regeln, keinen Chatverlauf.
• Die CI muss blockieren. Eine Pipeline, die nur warnt, dient bloß als Dekoration.

5. Woher neue Regeln kommen

Direkt aus dem Review. Ein Kommentar, der zum zweiten Mal fällt, ist kein Entwicklerfehler. Er markiert eine Lücke in Ihren Regeln.

Die Bedingung: Reviews werden im Pull Request dokumentiert, nicht bloß mündlich im Call. Aus mündlichen Gesprächen lässt sich später keine Regel ableiten.

6. Verantwortung und Messung

Regeln ohne festen Verantwortlichen veralten innerhalb weniger Monate. Der Agent befolgt sie weiter, obwohl sie längst ungültig sind. Kopieren Sie folgende Struktur in 90-ownership.md:

Verantwortlicher: [Name]
Neue Regel: PR in .claude/rules/, Freigabe durch den Verantwortlichen.
Bereinigung: erster Montag im Monat, 30 Minuten.
Eskalation: zweimal verletzt -> eine Stufe höher
  nur ein Satz -> Einstellung oder Hook -> CI -> Lint
Monatliche Notiz: Wie viele Regeln noch reiner Satz sind.

Drei Kennzahlen sollten Sie jeden Monat im Blick behalten:

• Review-Kommentare pro PR. Funktionieren die Regeln, sinkt diese Zahl kontinuierlich.
• Wie oft ein Gate die Änderung gestoppt hat. Und wie oft der Agent sie danach selbst reparierte.
• Wie viele Regeln noch reine Sätze sind. Das ist Ihr Arbeitsplan für den kommenden Monat.

Messen Sie weder Commit-Zahlen noch Codezeilen. Die KI bläht beides in Sekundenschnelle auf.

7. Arbeitsblatt für das Team (45 Minuten)

Ausdrucken, auf den Tisch legen und gemeinsam ausfüllen.

Sie sind fertig, wenn jede Zeile eine klare Durchsetzung und einen Verantwortlichen hat.