AIDive

Ich ertappte Claude Code beim Kopieren. 5 feste Regeln

Von AIDive · Veröffentlicht am

Coding-Agents

Fünf Regeln, die Claude Code nicht umgeht

Wir haben Claude Code echte Features in unserer eigenen TypeScript-Rechnungs-API bauen lassen und es dabei ertappt, wie es einen Validator kopierte, statt ihn wiederzuverwenden. Dieser Artikel nennt fünf Regeln gegen Codebase Rot und für jede den Claude Code Hook oder die Einstellung, die sie erzwingt. Die Dokumentation von Anthropic sagt, eine CLAUDE.md-Datei sei Kontext und keine erzwungene Konfiguration. Eine Regel dort ist also ein Satz, den das Modell gegen die Aufgabe abwägt. Die Enforcer unten sind Dateien, die das Harness ausführt: ein Duplikat-Blocker, der direkt nach einer Änderung anspringt, ein Zug, der nicht enden kann, solange Tests rot sind, und Konfigurations-Gates, die der Agent nicht anfassen darf.

Eine Regel, die du schreibst, ein Check, den das Harness ausführt

Ein Claude Code Hook ist ein kleines Skript, das Claude Code selbst zu einem festen Zeitpunkt ausführt, vor oder nach einem Tool-Aufruf. Beendet sich das Skript mit einem Fehlercode, geht seine Ausgabe als Ablehnung an Claude zurück. Die Best Practices von Anthropic teilen Anweisungen in zwei Arten: die, die du schreibst und das Modell liest (ein Prompt, eine CLAUDE.md-Datei, ein Skill), und die, die du konfigurierst und das Harness ausführt (ein Hook, eine Deny-Regel, eine verwaltete Einstellung). Die Memory-Dokumentation sagt, CLAUDE.md sei für Richtlinien, und Claude könne entscheiden, dass eine Richtlinie nicht gilt.

Wir haben diese Trennung an einer kleinen Rechnungs-API ohne geschriebene Regeln getestet und Claude um wiederkehrende Zeitpläne und einen CSV-Export des Berichts über offene Posten gebeten. Claude meldete grün: Typecheck bestanden, alle Tests bestanden. Ein Duplikat-Detektor erzählte etwas anderes: Der Rechnungs-Parser war Zeile für Zeile in den neuen Zeitplan-Parser kopiert worden, und die Kundensuche des Handlers in den neuen Handler.

Setup Features Gefundene exakte Klone Bestandene Tests
Regeln als Prosa in CLAUDE.md 1 0 45
Keine Regeln geschrieben 1, dann ein zweites obendrauf 3, weiter 3 47, dann 55

Die Klone blieben in Claudes Bericht bei beiden Features unsichtbar. Jeder Enforcer in diesem Artikel steht in einer einzigen Settings-Datei im Ordner .claude, mit einem Hooks-Block und einer Deny-Liste.

Regel eins: erst wiederverwenden, dann schreiben

Der Enforcer ist ein PostToolUse-Hook auf den Tools Edit und Write. Das Skript liest den Pfad der geänderten Datei aus seiner Eingabe, startet jscpd auf dem Quellordner und vergleicht die Klon-Anzahl mit einer Baseline im Repo, sodass alte Duplikate die heutige Arbeit nicht blockieren. Steigt die Anzahl, gibt das Skript die Regel und die Fundstelle des Zwillings aus und beendet sich mit Code 2. Die Hooks-Referenz sagt, dass nach einem ausgeführten Tool der Exit-Code 2 Claude die Meldung zeigt. Ein Skript, das mit 0 endet, wird nie gesehen, egal was es ausgibt.

Beim Replay des Zeitplan-Features mit installiertem Hook schrieb Claude den neuen Handler, und der Hook sprang sofort an und nannte die Kundensuche im Rechnungs-Handler als Zwilling. Claudes nächste Zeile war, die Prüfung stehe jetzt in beiden Handlern, und es werde sie als eine Methode ins Kunden-Repository verschieben, die von beiden Stellen aufgerufen wird. Am Ende war der Detektor sauber, und die gemeinsame Prüfung lag an einer einzigen Stelle.

Die Grenzen: jscpd findet eine exakte Kopie, keinen von Grund auf neu geschriebenen Helfer, und ein Hook, der nach der Änderung läuft, kann sie nicht rückgängig machen. Er gibt Feedback.

Regel zwei: kein Modul, das niemand wollte

Der Enforcer ist ein PreToolUse-Hook auf dem Tool Write. Das Skript prüft nur eines: Liegt der Pfad unter dem Quellordner, und existiert die Datei noch nicht? Wenn ja, gibt es eine JSON-Entscheidung mit ask und einer Begründung aus, und Claude Code macht daraus eine Berechtigungsabfrage. Die Hooks-Referenz nennt für einen PreToolUse-Hook vier mögliche Entscheidungen: allow, deny, ask oder defer.

Beim Replay hielt Claude Code vor jedem neuen Modul des Zeitplan-Features an und fragte nach. Das Feature brauchte wie der Rest des Repos ein Zeitplan-Modul, einen Store und einen Handler, also wurde jedes genehmigt. Eine spätere Bitte, die CSV-Helfer in ein neues Utils-Modul zu verschieben, löste dieselbe Abfrage aus, und sie wurde abgelehnt: Claude Code verwarf beide Schreibvorgänge dieses Stapels, der Zug endete ohne geschriebene Datei, und Claude versuchte es nicht erneut.

Zwei Grenzen der Version, die wir genutzt haben, 2.1.294: Die Abfrage zeigt den Dateinamen, und die Begründung geht ins Transkript von Claude, nicht in den Dialog. Und eine Datei, die per Shell-Befehl angelegt wird, ist kein Write-Tool-Aufruf und rutscht an diesem Hook vorbei.

Regel drei: Konventionen sind Lint, keine Prosa

Der Enforcer ist der Linter des Projekts, per Hook auf jeder geänderten Datei ausgeführt. Die Konventionen (Type-Aliase statt Interfaces, keine Enums, kein any, eine Domain-Schicht ohne Ein- und Ausgabe) wandern aus der Prosa in die ESLint-Konfiguration: Eine Restricted-Syntax-Regel lehnt ein Interface oder ein Enum mit der eigenen Meldung des Projekts ab, und eine Restricted-Imports-Regel hält den Dateizugriff aus dem Domain-Ordner heraus. Ein PostToolUse-Hook auf Edit und Write startet ESLint auf der gerade geänderten Datei und beendet sich bei einem Fehler mit Code 2, sodass der Verstoß Claude an der genauen Zeile erreicht.

Die Worte der Konvention bleiben in einer Rules-Datei unter .claude/rules/ mit einem paths-Header, der die Datei nur lädt, wenn Claude diesen Ordner anfasst. Die Memory-Dokumentation sagt, eine pfadbezogene Regel werde geladen, wenn Claude eine passende Datei liest, schreibt oder ändert, und warnt, dass ein Header, der nicht geparst werden kann, die Regel überall laden lässt.

Als wir Claude baten, eine Status-Union in ein Enum und einen Typ in ein Interface umzuwandeln, änderte es nichts. Es sagte, der Umbau würde die eigenen Regeln des Projekts verletzen, nannte die Lint-Konfiguration und den Hook, die die Änderung markieren würden, und bot stattdessen ein Const-Objekt an. Bei einem Feature für Feiertage, das zu einem Dateizugriff in der Domain verleitete, reichte Claude die Liste von außen herein, weil die Domain keine Ein- und Ausgabe machen darf. Der Hook musste nie anspringen. Mit einer von Hand eingespeisten fehlerhaften Datei lieferte er die Fehler an ihren Zeilen und die Ablehnung.

Regel vier: fertig heißt, die Checks sind bestanden

Der Enforcer ist ein Stop-Hook, ein Skript, das läuft, wenn Claude seinen Zug beenden will, und mit "noch nicht" antworten kann. Das Skript führt Typecheck und die Testsuite aus. Ist irgendetwas rot, gibt es die fehlschlagende Ausgabe aus und beendet sich mit Code 2. Es vergleicht außerdem die Zahl der bestandenen Tests mit einer gespeicherten Baseline, sodass eine Suite, die nur grün aussieht, weil ein Test gelöscht wurde, trotzdem als rot zählt. Es prüft das in der Dokumentation beschriebene Flag stop_hook_active, das true ist, wenn Claude gerade wegen des Hooks weitermacht, und beendet sich in dem Fall mit 0, damit der Hook nie in eine Schleife gerät.

Wir spielten den gehetzten Entwickler, baten um ein schnelles Umbenennen eines Berichtsfelds und sagten Claude, es solle die Tests nicht ausführen. Claude machte die Änderung per Shell-Befehl, sagte, die Suite werde jetzt fehlschlagen, und versuchte, den Zug zu beenden. Der Hook führte die Tests aus und lehnte mit "Rule 4: tests fail. Not done yet." ab, gefolgt von den fehlschlagenden Assertions. Claudes nächste Zeile war, der Stop-Hook des Projekts verlange grüne Tests, also werde es die veralteten Erwartungen aktualisieren. Die Tests blieben an ihrem Platz.

Die Dokumentation begrenzt die Schleife auf 8 aufeinanderfolgende Ablehnungen, danach endet der Zug trotzdem. Ein Test, der so umgeschrieben wurde, dass er besteht, wird nicht erkannt, ein gelöschter schon. Eine Falle: Ein viel geteilter Thread beklagte, Claude ignoriere Stop-Hooks, und das Skript darin endete mit 0, sodass das Harness nie etwas blockierte. Der blockierende Code ist 2, mit der Begründung auf dem Fehlerkanal.

Regel fünf: der Agent kann seine eigenen Gates nicht lockern

Jeder Check oben hat eine Abkürzung: strict in der Compiler-Konfiguration ausschalten, den fehlschlagenden Test in der Runner-Konfiguration ausschließen, den Hook aus der Settings-Datei löschen. Der Enforcer ist eine Deny-Liste im Permissions-Block der Settings-Datei, eine Zeile Edit(...) pro Datei: die Compiler-Konfiguration, die Test-Konfiguration, die Lint-Konfiguration und alles im Ordner .claude. Die Permissions-Dokumentation sagt, Deny-Regeln würden zuerst ausgewertet, und eine Allow-Regel könne keine Ausnahme aus einer Deny-Regel herausschneiden.

Als wir Claude baten, den Stop-Hook zu entfernen, weil er alles verlangsamt, las es die Settings und versuchte es nicht: Es sagte, die Datei trage eine Deny-Regel auf den Ordner .claude, es könnte sie mit einem Shell-Befehl umgehen, und das würde einen Schutz aushebeln, den das Team bewusst eingerichtet hat. Als wir darum baten, strict auszuschalten, lehnte es unter Berufung auf die geschriebene Regel ab und führte den Typecheck stattdessen mit einem Flag aus. Als wir sagten, es solle die Änderung trotzdem machen, griff Claude zu einem Shell-Befehl auf der Datei, und das Harness antwortete, die Erlaubnis für diesen Befehl sei verweigert worden. Claudes Antwort war, es habe keinen anderen Umweg versucht, weil das aushebeln würde, was auch immer den Block gesetzt hat.

Auch die Grenze ist dokumentiert: Eine Deny-Regel deckt kein Skript ab, das die Datei selbst öffnet, und die Datei lässt sich weiterhin von Hand bearbeiten. Genau das ist der Punkt.

Welche Regel zuerst installieren

Jede Regel ist eine Datei zum Kopieren, kein Satz, von dem du hoffst, dass Claude ihn liest. Mit den Regeln als Prosa verletzte ein Feature keine davon. Ohne geschriebene Regeln hinterließen die nächsten Features drei exakte Klone, die blieben. Mit den eingeschalteten Enforcern lehnte jeder eine echte Änderung ab.

Wenn du nur eins installierst Warum
Den Stop-Hook Der meiste Schutz bei geringstem Aufwand
Dann die Deny-Liste Vier Zeilen in der Settings-Datei
Nichts Bei einem Wegwerf-Prototyp

Wenn die Suite Minuten braucht, lass den schnellen Teil im Hook und verschiebe den Rest in die Pipeline. Die ehrliche Grenze stammt aus einem langen Issue im Claude Code Repository: Ein Hook erzwingt, was ein Tool-Aufruf zeigen kann, und ob eine Abstraktion richtig ist, bleibt eine menschliche Entscheidung. Die Faustregel der Dokumentation selbst: Wenn du eine Zeile in CLAUDE.md immer weiter betonst und Claude sie trotzdem verfehlt, gehört diese Zeile in einen Hook.

Kostenlose Ressourcen

Quellen

Häufige Fragen

Erzwingt Claude Code die Regeln in CLAUDE.md?
Nein. Die Dokumentation von Anthropic sagt, CLAUDE.md und Rules-Dateien würden als Kontext geladen, nicht als erzwungene Konfiguration, und Claude könne entscheiden, dass eine Richtlinie nicht gilt. Eine Regel, die keine Ausnahmen haben darf, gehört in einen Hook, eine Deny-Regel oder eine verwaltete Einstellung.
Was ist ein Claude Code Hook?
Ein Skript, das Claude Code zu einem festen Zeitpunkt ausführt, vor oder nach einem Tool-Aufruf oder wenn Claude seinen Zug beenden will. Beendet sich das Skript mit Code 2, geht seine Ausgabe auf stderr als Ablehnung an Claude zurück. Ein Skript, das mit 0 endet, wird nie gesehen.
Wie verhindert man, dass Claude Code Helfer per Copy-Paste dupliziert?
Mit einem PostToolUse-Hook auf Edit und Write, der einen Duplikat-Detektor wie jscpd auf dem Quellordner startet, die Klon-Anzahl mit einer gespeicherten Baseline vergleicht und sich mit Code 2 und der Fundstelle des Zwillings beendet, wenn die Anzahl steigt. Er findet exakte Kopien, keine umgeschriebenen Helfer.
Wie bringt man Claude Code dazu, die Tests auszuführen, bevor es fertig sagt?
Mit einem Stop-Hook, der Typecheck und Testsuite ausführt und sich mit Code 2 und der fehlschlagenden Ausgabe beendet, solange etwas rot ist. Prüfe das Flag stop_hook_active und beende dich mit 0, wenn es true ist, damit der Hook nie in eine Schleife gerät. Claude Code begrenzt die Schleife auf 8 aufeinanderfolgende Ablehnungen.
Kann Claude Code seine eigenen Hooks abschalten oder tsconfig.json ändern?
Nicht mit einer Deny-Liste. Edit(path)-Deny-Regeln in der Settings-Datei auf tsconfig.json, die Test- und Lint-Konfiguration und den Ordner .claude werden vom Harness angewendet: In unserem Test wurde ein sed über Bash auf tsconfig.json verweigert, bevor das Modell die Datei anfasste. Ein Skript, das die Datei selbst öffnet, ist nicht abgedeckt, und du kannst weiterhin von Hand bearbeiten.
Warum blockiert mein Stop-Hook nie?
Meist, weil er mit 0 endet. Blockieren braucht Exit-Code 2 mit dem Grund auf stderr. Ein Skript, das auf cat mit Exit 0 endet, lässt den Zug jedes Mal enden.

Ähnliche Videos