Claude-Code-Gewohnheiten als Befehle: Hook, /goal, Reviewer und Checkliste

TL;DR und Fazit

Eine Regel in der CLAUDE.md ist ein Ratschlag, den Claude abwägt. Eine Regel, die du in einen Befehl verwandelst, läuft, ob Claude sie liest oder nicht. Wir nahmen eine Rechnungs-API (Node 20, TypeScript, vitest) auf unserer eigenen Maschine, mit Claude Code 2.1.294, und ließen fünf Gewohnheiten als fünf Befehle laufen.

• Fertig: Mit /goal gab die Antwort die vollständige vitest-Ausgabe aus, "Tests 44 passed (44)", und das Ziel wurde nach 1 Turn als erreicht markiert. Ohne es sagte Claude nur "pnpm test passes (37/37)", und die Ausgabe blieb in einem Tool-Aufruf eingeklappt.
• Eine Regel, die gelten muss: Ein PreToolUse-Hook blockierte 2 Änderungen an der geschützten Migrationsdatei, und Claude bearbeitete den Rest.
• Eine Aufgabe pro Kontext: /clear senkte die Unterhaltung von 26.4k auf 130 Tokens.
• Lade, was du nutzt: /skill-doctor fand 52 Skills, die geladen, aber nie aufgerufen wurden (13 + 14 + 25).
• Frisches Review: Ein schreibgeschützter Reviewer fand denselben Sortierfehler bei Gleichstand wie die Autoren-Session, dazu einen fehlenden Test, und behauptete einen sauberen Typecheck, den er nicht hätte ausführen können.

Fazit: Richte zuerst den Hook ein, bei der Regel, die in deinem Repo schon gebrochen wurde. /clear und /skill-doctor kosten nichts. Spare dir /goal für lange Läufe und den Reviewer für den Merge auf. Das Paket liefert dir die Dateien.

Quellenbasierte Synthese

Eine CLAUDE.md-Zeile wird nicht erzwungen. Die Best Practices von Anthropic sagen, dass eine Zeile wie Always typecheck before you finish meistens funktioniert, nicht jedes Mal s1. Die Memory-Doku nennt als Richtwert unter 200 Zeilen pro CLAUDE.md, weil längere Dateien mehr Kontext verbrauchen und die Befolgung senken s6. Unsere Testdatei hatte vier Regeln, eine davon in Großbuchstaben: "NEVER edit src/store/migrations.ts".

/goal beurteilt, was auf dem Bildschirm steht. Der Prüfer führt keine Befehle aus und liest keine Dateien, also muss die Bedingung etwas sein, das Claudes eigene Ausgabe belegen kann s2. Deshalb verlangt unsere Bedingung, dass die vollständige Testausgabe in der Unterhaltung ausgegeben wird. Ein Erfahrungsbericht eines Teams mit etwa 600 PRs fand, dass sein schlimmster Bug tsc, Lint und die eigenen Tests des Agents bestand s8. Eine Fertig-Prüfung, die nie erfüllt werden kann, läuft in einer Schleife bis zu einer Blockier-Obergrenze s9.

Ein Hook mit Exit 2 blockiert den Aufruf. Im Hooks-Guide bedeutet Exit 2, die Aktion zu blockieren s3. In unserem Lauf ging Claude ohne die Regel in der CLAUDE.md zweimal an die Migrationsdatei, und beide Änderungen kamen mit unserer Meldung blockiert zurück. Mit der Großbuchstaben-Zeile lehnte Claude von selbst ab, und in 2 späteren Läufen las es zuerst das Hook-Skript und versuchte die Datei nie. Ein Thread auf Hacker News übt die schärfste Kritik: Eine Sperre ist deterministisch, was das Modell danach tut, nicht s10.

/clear ist kostenlos und leert das Richtige. Die Best Practices sagen, dass /clear zwischen unabhängigen Aufgaben nichts kostet s1. Nach unserem Feature zeigte /context 57.5k von 1m Tokens, mit Nachrichten bei 26.4k. Nach /clear zeigte es 31.1k, mit Nachrichten bei 130 Tokens. Anweisungen, Tools und Skills blieben.

/skill-doctor nennt, was du nie nutzt. Er markiert Skills in der Liste, die nie aufgerufen wurden, und sagt, wo man sie abschaltet s7. Auf unserer Maschine meldete er 13 geladene, aber nie aufgerufene Skills, 14 von claude.ai synchronisierte und 25 Plugin-Skills: insgesamt 52, dazu 4 zuletzt ungenutzte Plugins. Der Platz in der Liste ist knapp: Ein Beitrag fand, dass 267 zusätzliche Zeichen in einer Beschreibung 7 andere Skills auf bloße Namen reduzierten s12. Der Gewinn ist weniger Rauschen, kein halbierter Kontext.

Ein frischer Reviewer hilft, weil er deine Überlegungen nicht gesehen hat. Die Best Practices sagen das direkt und fügen hinzu, dass dieselbe Aufgabe an einen Subagent zu übergeben die Antwort nicht besser macht s1. Jeder Subagent startet mit einem frischen, isolierten Context Window s5. Das hat einen Preis: Ein Nutzer maß jeden Subagent beim Start auf etwa 51k Tokens s14, also rufe ihn einmal pro Feature auf. Unser Reviewer lief 28 s im Hintergrund.

Code

• goal-conditions.md

# /goal conditions

The /goal judge reads only the conversation. It does not run commands or read files, so write the condition as something Claude's own output can demonstrate. Name one end state and the proof you want printed on screen.

## 1. The one we used (overdue invoices endpoint)

```
/goal GET /invoices/overdue returns the overdue invoices with page and pageSize query params, new tests cover it, and the full pnpm test output showing every test passing is printed in this conversation
```

Result on our run: the reply printed the full vitest output, then the goal was marked achieved.

## 2. Template: a bug fix

```
/goal <the failing behaviour> no longer happens, a new test reproduces it and passes, and the full <your test command> output showing every test passing is printed in this conversation
```

## 3. Template: a refactor

```
/goal <the old name or pattern> no longer appears in the code, the output of <your search command> showing no matches is printed in this conversation, and the full <your test command> output showing every test passing is printed too
```

## Rules for all three

- One end state, not a list of wishes.
- The proof is output Claude prints (test results, a search result), never "it works".
- Do not write a condition Claude cannot meet; an unsatisfiable goal loops.
- Check it with `/goal` alone; remove it with `/goal clear`.

goal-conditions.md on GitHub

protect-migrations.sh

#!/bin/sh
# Block edits to the append-only migrations file
path=$(jq -r '.tool_input.file_path // empty')
case "$path" in
  *src/store/migrations.ts)
    echo "migrations.ts is append-only: add a new migration file instead" >&2
    exit 2 ;;
esac
exit 0

protect-migrations.sh on GitHub

settings.json

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Edit|Write",
        "hooks": [ { "type": "command", "command": ".claude/hooks/protect-migrations.sh" } ] }
    ]
  }
}

settings.json on GitHub

reviewer.md

---
name: reviewer
description: Read-only code reviewer. Use it to review the current git diff before a merge, against the conventions in README.md.
tools: Read, Grep, Glob, Bash(git diff:*), Bash(git status:*)
---

You review a diff you did not write. You never edit files.

1. Run `git diff` and read every changed file in full.
2. Read README.md and check the diff against each of its conventions.
3. Look for bugs: wrong edge cases, missing validation, untested branches, behaviour that breaks existing routes.

Report each finding with the file, the line, what is wrong and why it matters. Say plainly when you find nothing real. No style nits.

reviewer.md on GitHub

checklist.md

# Clear and skill-doctor checklist

After every finished task
1. Run `/context` and read what the session carries.
2. Run `/clear` before the next unrelated task.
3. Run `/context` again; the conversation should be near empty while instructions, tools and skills stay.
4. In the middle of a task, do not clear: use `/compact` with a focus instead.

Once a month
1. Run `/skill-doctor` (needs a recent Claude Code release).
2. Skills loaded but never invoked: turn them off in `/skills` (space bar cycles).
3. Skills synced from claude.ai: switch them off on the web side, deleting them locally brings them back.
4. Plugin skills: disable the plugin in the Installed tab.
5. Keep what you use rarely but still need.

checklist.md on GitHub

Das machst du am Montag

• Öffne deine CLAUDE.md und markiere jede Zeile, die jedes Mal gelten muss, nicht nur meistens.
• Kopiere protect-migrations.sh und settings.json nach .claude/, richte den Pfad auf deine geschützte Datei und bitte Claude dann, sie zu ändern, und sieh dir die Sperre an.
• Tippe vor deinem nächsten Feature /goal mit einer Bedingung, die die Ausgabe der vollständigen Tests verlangt.
• Wenn die Aufgabe erledigt ist, führe /context aus, dann /clear, dann noch einmal /context.
• Führe /skill-doctor aus und schalte ab, was du nie aufgerufen hast. Bei synchronisierten Skills tust du das auf der Web-Seite.
• Kopiere reviewer.md nach .claude/agents/ und bitte vor deinem nächsten Merge um ein Review des Diffs.
• Führe den Typecheck nach dem Review selbst aus. Unser Reviewer behauptete einen, den er nicht ausführen konnte.

Weiterführend

Das haben wir weggelassen.

• Prompt-Audit. /doctor prompt-audit und das Argument "lautere Regel, längere Datei". Prüfe in der Befehlsreferenz die Mindestversion s4.
• Skills, die nie auslösen. Das betrifft Beschreibungen, nicht was geladen wird. Der Beitrag von primeline ist der richtige Einstieg s12.
• MCP-Bereinigung. Ein Artikel maß 12 MCP-Server bei 5.8k Tokens mit Tool-Suche und 63k ohne, es zählt also weniger als früher s13.
• Größere CLAUDE.md-Dateien. Ein Beitrag kürzte 455,530 Zeichen auf 88,584 über neun Dateien und merkt an, dass @path-Imports sofort laden, einfache Links dagegen erst bei Bedarf s11.
• /batch. Für große Refactorings nennt die Befehlsreferenz 5 bis 30 Einheiten, je ein Worktree s4. Wir haben es nicht ausgeführt.
• Manuelle /compact-Schwellen. Wir fanden keine Quelle für einen festen Prozentwert, also nennen wir keinen.

FAQ

Ersetzt /goal, dass ich die Tests selbst ausführe? Nein. Der Prüfer liest nur die Unterhaltung. Er prüft, dass die Ausgabe gezeigt wurde, nicht dass sie stimmt.

Hindert der Hook Claude daran, die Änderung zu versuchen? Nein. Er stoppt die Änderung, sobald Claude es versucht. In unserem Lauf ging Claude ohne CLAUDE.md-Regel zweimal an die Datei, und beide Änderungen wurden blockiert.

Sollte ich meine CLAUDE.md-Regeln löschen, sobald ich einen Hook habe? Nein. Mit der Großbuchstaben-Zeile lehnte Claude die Änderung von selbst ab, was einen blockierten Aufruf spart. Behalte sie für das, was Claude aus deinem Code nicht ableiten kann.

Warum nicht bei jeder Änderung den Reviewer nutzen? Jeder Subagent startet mit eigenem vollem Kontext, das kostet echte Tokens. Nutze ihn einmal pro Feature, vor dem Merge.

Läuft /skill-doctor auf meiner Version? Er hängt laut Befehlsreferenz an einem Feature-Flag und einem aktuellen Release s4. Auf 2.1.294 lief er auf unserer Maschine, aktualisiere aber zuerst Claude Code, falls er bei dir nicht läuft.