Claude Code Best Practices: eine praktische Checkliste

Die wichtigsten Claude Code Best Practices sind einfach: Halte die CLAUDE.md kurz, plane vor großen Änderungen, gib Claude einen Check, den es ausführen kann, arbeite in kleinen Aufgaben, leere den Kontext dazwischen, setze harte Regeln per Konfiguration statt per Prosa durch und lass parallele Arbeit in getrennten Git-Worktrees laufen. Danach liest du den Diff und committest oft.

Diese Seite ist eine Checkliste. Jeder Punkt sagt, was zu tun ist, zeigt den Befehl oder die Konfiguration und verlinkt auf einen ausführlicheren Leitfaden, wo es einen gibt. Alles hier folgt der offiziellen Claude-Code-Dokumentation mit Stand Oktober 2026; Details, die sich zwischen Versionen ändern, sind markiert.

Die Checkliste auf einen Blick

1. Halte die CLAUDE.md kurz und sachlich

Claude Code lädt die CLAUDE.md in jede Session, also kostet jede Zeile darin bei jeder Aufgabe ein wenig Aufmerksamkeit, ob sie relevant ist oder nicht. Die Datei funktioniert am besten, wenn sie nur enthält, was Claude nicht aus dem Code ableiten kann:

• Wie man Arbeit in diesem Repo bestätigt: die genauen Befehle für Tests, Typecheck und Lint und wie man eine einzelne Testdatei ausführt.
• Stellen, an denen der Code in die Irre führt: ein altes Muster, das neuer Code nicht kopieren soll, ein Ordner, der tot aussieht, es aber nicht ist.
• Entscheidungen, die nicht im Repo stehen: welchen Fehler-Helper das Team gewählt hat, wie Deploys ablaufen.
• Alles, was du schon zweimal korrigieren musstest.

Eine Datei, die diesen Test besteht, bleibt klein:

# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit

# Conventions
- Use the error helpers in src/lib/errors.ts, never throw raw strings
- src/legacy/ is still live but don't copy its patterns into new code

# Gotchas
- Integration tests need DATABASE_URL set, see .env.example

Deine Architektur oder Ordnerstruktur musst du nicht beschreiben; Claude liest das Repo. /init schreibt einen ersten Entwurf, und ab da besteht die Arbeit vor allem aus Löschen. Der offizielle Memory-Leitfaden empfiehlt, unter 200 Zeilen zu bleiben. /context bestätigt, dass die Datei geladen wurde, und /doctor schlägt Kürzungen vor. Persönliche Vorlieben gehören in CLAUDE.local.md, die du in die .gitignore aufnimmst.

Zwei verwandte Werkzeuge halten die Hauptdatei schlank. Regeln, die nur in einem Bereich zählen, kommen in .claude/rules/*.md mit einem paths:-Filter, sodass sie nur geladen werden, wenn Claude dort arbeitet. Team-Abläufe wie eine Release-Checkliste kommen in einen Skill unter .claude/skills/<name>/SKILL.md; Claude sieht nur Name und Beschreibung, bis es den vollen Text braucht. Die vollständige Anleitung steht in CLAUDE.md und AGENTS.md schreiben.

Wenn Claude eine Zeile immer wieder ignoriert, hilft es selten, IMPORTANT in Großbuchstaben zu schreiben. Entweder ist die Datei zu lang, oder die Zeile ist eine Regel ohne Ausnahmen, und die gehört in einen Hook (siehe Punkt 6).

2. Schreib Prompts, die sagen wo, was und wie geprüft wird

Ein vager Prompt lässt Claude raten. Ein konkreter nennt das Symptom, wo zu suchen ist und wie die Lösung bewiesen wird:

Nutzer melden, dass der Login nach Ablauf der Session fehlschlägt. Sieh dir den Token-Refresh in src/auth/ an, schreib einen fehlschlagenden Test, der das Problem reproduziert, und behebe es dann.

Verweise mit @ auf Dateien, füge Screenshots ein und leite Logs per Pipe hinein, statt sie zu beschreiben. Wenn du noch nicht weißt, was du willst, lass dich zuerst von Claude interviewen:

Ich möchte der öffentlichen API Rate Limiting hinzufügen, habe es aber noch nicht durchdacht. Interviewe mich, bis du die Spec schreiben könntest, und schreib sie dann in SPEC.md.

Starte danach eine frische Session, die aus SPEC.md baut. Der Bau beginnt mit einem sauberen Kontext und einer schriftlichen Definition von „fertig“, und gegen die Spec prüft später auch der Reviewer. Mehr Prompt-Muster findest du in Gute Prompts für KI-Coding-Agenten schreiben.

Zwei Gewohnheiten kannst du ablegen: Formulierungen wie „think hard“ erhöhen den Reasoning-Aufwand nicht (nutze /effort high oder schreib ultrathink in einen einzelnen Prompt), und Betonung in GROSSBUCHSTABEN führt vor allem dazu, dass Claude eine Regel übertrieben anwendet.

3. Plane vor mehrstufigen Änderungen

Bei allem, was mehrere Dateien berührt, trenne Denken vom Bearbeiten. Im Plan Mode liest Claude den Code und schlägt einen Plan vor, ohne etwas zu ändern. Du kannst mit Shift+Tab hineinwechseln oder eine Session direkt darin starten:

claude --permission-mode plan

Lies den Plan, korrigiere ihn und lass Claude erst dann bauen. Eine falsche Annahme, die du im Plan erwischst, kostet eine Nachricht; im Diff erwischt, kostet sie eine Neufassung. Kleine, offensichtliche Fixes brauchen keinen Plan. Die Details, einschließlich wie du einen Plan vor der Freigabe bearbeitest, stehen in Claude Code Plan Mode.

4. Gib Claude einen Check, den es ausführen kann

Das ist die Gewohnheit mit dem größten Nutzen. Claude kann nur wissen, dass es fertig ist, wenn es etwas zum Ausführen hat: eine Testsuite, einen Typecheck, einen Lint-Befehl, den Exit-Code eines Builds, ein Skript, das eine Ausgabe gegen eine Fixture vergleicht. Wenn dein Repo so etwas hat, ist die nützlichste Zeile in der CLAUDE.md der Befehl, der es ausführt.

Du entscheidest, wie streng der Check angewendet wird:

• Im Prompt. „Führ danach die Auth-Tests aus und mach weiter, bis sie grün sind.“ Funktioniert für jede Aufgabe ohne Einrichtung.
• Als Ziel. /goal all tests in tests/auth pass and lint is clean setzt eine Bedingung, die ein separates Modell nach jedem Turn prüft. Am nützlichsten bei langen Läufen.
• Als Stop-Hook. Claude Code führt dein Skript aus, wenn Claude seinen Turn beenden will, und schickt es zurück an die Arbeit, wenn das Skript mit Code 2 endet.
• Mit einem unabhängigen Reviewer. /code-review prüft den Diff in einem frischen Subagent, der deine Unterhaltung nie gesehen hat.

Die Stop-Hook-Variante von „Typecheck muss durchlaufen“ steht in .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
        ]
      }
    ]
  }
}

Stderr geht als Grund, warum es noch nicht aufhören darf, an Claude zurück; deshalb wird die Compiler-Ausgabe dorthin umgeleitet. Blockiert der Hook acht Stopps hintereinander ohne Tool-Aufruf dazwischen, beendet Claude Code den Turn trotzdem; CLAUDE_CODE_STOP_HOOK_BLOCK_CAP hebt diese Grenze an.

Was du auch wählst, verlange Belege: den Befehl, den Claude ausgeführt hat, und seine Ausgabe. „Alle Tests bestehen“ allein sagt dir wenig. Nach einer UI-Änderung lässt /verify Claude die App bauen, starten und sich das Ergebnis ansehen.

5. Halte Aufgaben klein und den Kontext sauber

Eine Session, ein Ziel. Eine Unterhaltung, die drei unabhängige Aufgaben angesammelt hat, schickt bei jedem Turn der vierten alle drei erneut mit; das kostet mehr und macht die Antworten weniger fokussiert.

• /clear zwischen unabhängigen Aufgaben. /clear oauth-migration benennt außerdem die Session, die du verlässt, damit du zu ihr zurückkehren kannst.
• /compact keep the API changes and the test commands kürzt eine lange Session und behält dabei, was zählt. Bei einer langen Session ist /compact selbst eine große Anfrage.
• /usage zeigt, wohin deine Nutzung geht, in Abo-Tarifen auch nach Subagent, Skill und MCP-Server aufgeschlüsselt.

Mit Stand Oktober 2026 haben die meisten aktuellen Modelle ein Fenster von 1M Tokens, und die Kompaktierung läuft von selbst, sodass dir der Kontext selten ausgeht. Beim Leeren geht es um Fokus und Kosten, nicht ums Überleben. Der Prompt-Cache hält im Abo etwa eine Stunde und mit einem API-Key etwa fünf Minuten, also ist eine Session, die über die Mittagspause liegen geblieben ist, teurer fortzusetzen als eine frische. Die Mechanik steht in Claude Code Kontextfenster.

6. Leg Regeln, die nicht nachgeben dürfen, in die Konfiguration

Die CLAUDE.md enthält Richtlinien, und Claude darf entscheiden, dass eine Richtlinie gerade nicht passt. Für die wenigen Regeln, bei denen „fast immer“ nicht reicht, nutze Kontrollen, die Claude Code selbst durchsetzt.

Berechtigungsregeln. Erlaube, was sicher und häufig ist, frag bei Riskantem nach, verbiete, was nie passieren darf:

{
  "permissions": {
    "allow": ["Bash(pnpm tsc --noEmit)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
  }
}

Deny-Regeln gelten in jedem Berechtigungsmodus, und die Read-Regel erfasst auch gängige Shell-Befehle zum Lesen von Dateien wie cat .env. Ein Skript, das die Datei öffnet, erfasst sie nicht; für sicherheitskritische Arbeit schalte deshalb zusätzlich mit /sandbox die Sandbox ein, die Shell-Befehle unter macOS, Linux und WSL2 auf Betriebssystemebene einschränkt.

Hooks. Ein Formatter, der nach jeder Bearbeitung läuft, hängt nicht mehr davon ab, dass Claude daran denkt:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\"" }
        ]
      }
    ]
  }
}

Nutze Hooks nur für Regeln ohne jede Ausnahme; „bevorzuge Named Exports“ bleibt in der CLAUDE.md. Der Leitfaden zu Claude Code Hooks behandelt jedes Event und jeden Exit-Code.

Berechtigungsmodi. Mit Stand Oktober 2026 starten neue interaktive Sessions im Auto-Modus, in dem ein Klassifikator riskante Aktionen prüft, statt dich bei jeder einzelnen zu fragen. Das ist gut, aber es ist eine Einschätzung, also gehören deine „niemals“-Regeln weiterhin in Deny-Regeln und Hooks. Wenn du lieber jeden Schritt freigibst, wechselt Shift+Tab zu Manual, oder du startest mit claude --permission-mode manual. Wenn Manual zu oft fragt, nimmt /fewer-permission-prompts deine häufigen Nur-Lese-Befehle in eine Allowlist auf. Warum das komplette Überspringen der Berechtigungen ein schlechter Tausch ist, steht in Claude Code Berechtigungen überspringen.

7. Früh gegensteuern, zurücksetzen statt diskutieren

Beobachte die erste Minute einer Aufgabe. Die Bedienelemente sind überschaubar:

• Esc stoppt Claude mitten in einer Aktion und behält alles Bisherige, sodass du umlenken kannst.
• /rewind, oder zweimal Esc bei leerem Prompt, setzt den Code, die Unterhaltung oder beides auf einen früheren Prompt zurück.
• /clear fängt von vorn an. Nach zwei gescheiterten Korrekturen fügt eine dritte meist nur einen weiteren Fehlversuch hinzu, den Claude erneut lesen muss. Leere den Kontext und schreib einen besseren Prompt, der enthält, was du gelernt hast.

Checkpoints decken Dateien ab, die Claude mit seinen eigenen Bearbeitungswerkzeugen geändert hat; eine Datei, die nur ein Bash-Befehl angefasst hat, wird nicht wiederhergestellt. Sie arbeiten neben Git, nicht an seiner Stelle. Für Arbeit über mehrere Tage benennt /rename oauth-migration die Session, und claude --resume oauth-migration nimmt sie später wieder auf.

8. Setze Subagents mit Absicht ein

Claude Code delegiert schon von selbst: Breite Suchen gehen an den eingebauten Explore-Agent, und Subagents laufen standardmäßig im Hintergrund. Jeder Subagent schickt eigene Anfragen, kostet also Tokens, und er macht eine Antwort nicht klüger. Nutze sie für:

• Unabhängige Arbeitspakete, die gleichzeitig laufen können.
• Lange Ausgaben, etwa einen kompletten Testlauf, aus der Hauptunterhaltung herauszuhalten.
• Einen Reviewer, der nicht gesehen hat, wie der Code geschrieben wurde.
• Eine Aufgabe, die weniger Tools haben soll als die Hauptsession.

Ein Nur-Lese-Reviewer ist eine kurze Datei unter .claude/agents/reviewer.md:

---
name: reviewer
description: Reviews changed files against the spec they were built from. Use after implementing a feature, before opening the PR.
tools: Read, Grep, Glob
---
You're reviewing code you didn't write. Compare the changed files against the spec you're given,
check that every requirement is implemented and the listed edge cases have tests,
and report only the gaps that affect correctness. Skip style.

Für einfache Aufgaben wie das Sammeln der Dateien, die ein Modul importieren, ergänze model: haiku in der Definition. Dann bitte:

Lass den Reviewer den Rate Limiter mit SPEC.md vergleichen.

Weitere Muster findest du in Claude Code Subagents.

9. Lass parallele Arbeit in Worktrees laufen

Zwei Sessions, die einen Checkout bearbeiten, überschreiben sich gegenseitig. Gib jeder einen eigenen Git-Worktree:

claude -w feature-auth

Ein Worktree ist ein frischer Checkout, also fehlen gitignorierte Dateien wie .env, und Abhängigkeiten sind nicht installiert. Trag kleine gitignorierte Dateien in .worktreeinclude im Repo-Root ein, und Claude Code kopiert sie in jeden Worktree, den es anlegt:

.env
.env.local
config/dev-credentials.json

Leg node_modules dort nicht hinein; es wird kopiert statt verlinkt. Schreib stattdessen den Installationsbefehl in die CLAUDE.md oder nutze die Einstellung worktree.symlinkDirectories. Wenn du eine unbenannte Worktree-Session ohne Änderungen verlässt, entfernt Claude Code sie; andernfalls fragt es nach. Für eine große mechanische Änderung teilt /batch die Arbeit in Einheiten auf, führt jede in einem eigenen Worktree aus und öffnet pro Einheit einen PR. Mehr dazu in Git Worktrees für parallele KI-Agenten.

10. Diff lesen, klein committen, selbst pushen

Der Agent schreibt; du gibst frei. Bevor du einen Turn akzeptierst, lies git diff, nicht die Zusammenfassung. Committe nach jedem funktionierenden Schritt, damit ein schlechter nächster Schritt nur ein git reset entfernt ist. Pushes, Merges und Deploys bleiben bei einem Menschen: Die ask-Regel für git push * oben macht genau das. Eine zweite Session, die @src/middleware/rateLimiter.ts prüft, ohne beim Schreiben zugesehen zu haben, ist der günstigste unabhängige Reviewer, den du hast.

Bonus: bevor du Claude unbeaufsichtigt lässt

Die offizielle Dokumentation nennt fünf Fragen für jeden Lauf, dem niemand zusieht. Sie sind ein guter letzter Check:

1. Weiß es, wie „fertig“ aussieht? Ein Ziel, eine Spec-Datei, ein fehlschlagender Test.
2. Kann es die eigene Arbeit prüfen? Tests, ein Stop-Hook, ein Review-Schritt.
3. Was darf es anfassen? Berechtigungsregeln, dontAsk, die Sandbox, ein Worktree.
4. Was hält es an? --max-turns, --max-budget-usd, ein Ausgabenlimit.
5. Wohin geht das Ergebnis, und wer zeichnet es ab? Ein PR und ein Mensch, der den Merge freigibt.

Für geskriptete Läufe und CI siehe Claude Code Headless-Modus.

So geht es mit AgentVera

Der Großteil dieser Checkliste ist Disziplin; AgentVera macht einige Punkte leichter, wenn du mehr als eine Session laufen lässt. Jedes Pane im Workspace ist das echte Claude-Code-Terminal, also funktionieren Shift+Tab, Plan Mode, Hooks und deine CLAUDE.md wie gewohnt. Im Git-Panel kannst du pro Agent einen Worktree anlegen, und die Agent-Koordination warnt, wenn zwei Agenten dieselbe Datei bearbeiten.

Zu Punkt 4: Beim automatischen Code-Review prüft ein Claude-Modell deiner Wahl die Änderungen jedes Turns, listet Funde mit Schweregrad und file:line auf und kann sie an den Agenten zurückgeben. Verify (Pro und Team) macht aus deiner Nachricht Abnahmekriterien und lässt einen separaten Prüfer sie am Ende des Turns mit Belegen abhaken. Zu Punkt 7: Checkpoints halten jeden Turn in einer versteckten Git-Ref fest und behalten die letzten 60 pro Agent. Grid, Worktrees, Code-Review und Checkpoints sind im kostenlosen Plan enthalten; lade AgentVera herunter, um sie auszuprobieren.

Fazit

Wenn du nur drei Punkte übernimmst, dann diese: eine kurze CLAUDE.md mit deinen echten Befehlen, ein Check, den Claude ausführt, bevor es „fertig“ sagt, und /clear zwischen Aufgaben. Ergänze Deny-Regeln und Hooks für die Dinge, die nie passieren dürfen, Worktrees, sobald du Sessions parallel laufen lässt, und behalte das letzte Review und den Push für dich.