Claude Code Best Practices

Die meisten Entwickler behandeln Claude Code wie einen Chatbot. Eine vage Anfrage eintippen, ein vages Ergebnis bekommen, das Tool beschuldigen. Die Entwickler, die 10x-Ergebnisse rausholen, machen etwas anderes. Sie haben Systeme um Claude Code herum gebaut, sodass jede Session produktiver ist als die letzte.

Das sind die fünf Gewohnheiten, die Entwickler, die liefern, von denen trennen, die kämpfen. Keine Plugins, kein besonderes Setup. Nur ein besseres Betriebsmodell für die Arbeit mit agentischer KI.

1. PRD-First-Entwicklung

Der größte einzelne Fehler beim agentischen Coden ist, ohne Plan anzufangen. Du öffnest Claude Code, beschreibst ein Feature in zwei Sätzen, lässt es los. Zwanzig Minuten später bist du drei Tangenten tief in Code, der nicht dem entspricht, was du eigentlich gebraucht hättest.

Ein Product Requirements Document behebt das. Kein 50-seitiges Corporate-Spec. Eine leichtgewichtige Markdown-Datei, die fünf Minuten dauert.

# Feature: User Authentication
 
## Mission
 
Add email/password authentication with session management.
 
## In Scope
 
- Sign up, login, logout flows
- Password hashing with bcrypt
- JWT session tokens with 24-hour expiry
- Protected route middleware
 
## Out of Scope
 
- OAuth providers (Phase 2)
- Two-factor authentication (Phase 3)
- Password reset flow (separate task)
 
## Architecture
 
- Auth routes: /api/auth/signup, /api/auth/login, /api/auth/logout
- Middleware: src/middleware/auth.ts
- Database: users table with email, password_hash, created_at

Ohne PRD driftet der Context. Claude trifft Architekturentscheidungen, die du nie besprochen hast. Es fügt OAuth hinzu, weil "das die meisten Auth-Systeme beinhalten." Es baut einen Password-Reset-Flow, weil er relevant schien. Du verbringst mehr Zeit damit, gegenzusteuern als zu bauen.

Mit einem PRD hat jede Session Leitplanken. Du sagst Claude "lies das PRD, dann implementiere den Signup-Flow." Es weiß genau, was im Scope ist, was nicht, und welche Muster zu matchen sind. Wenn ein Abschnitt fertig ist, fragst du "basierend auf dem PRD, was sollen wir als nächstes bauen?" und es bleibt auf Kurs.

Das funktioniert auch auf bestehenden Projekten. Bei Greenfield-Arbeit ist das PRD dein MVP-Brief. Bei Brownfield-Arbeit dokumentiert das PRD, was du bereits hast, und legt dann fest, was du als nächstes willst. Verschiedene Ausgangspunkte, gleiche Struktur.

Das PRD löst auch das Multi-Session-Problem. Claude Code hat kein Gedächtnis zwischen Gesprächen, aber dein PRD schon. Jede neue Session öffnet sich mit demselben Dokument, sodass du genau dort weitermachst, wo du aufgehört hast.

2. Modulare Regelsarchitektur

Die meisten Entwickler machen denselben Fehler mit ihrer CLAUDE.md: sie kippen alles in eine Datei. Tech-Stack, Coding-Konventionen, Test-Regeln, Deployment-Prozeduren, API-Muster. Eine riesige Wand aus Anweisungen.

Das Problem ist Context-Verschwendung. Claude lädt deine komplette CLAUDE.md beim Session-Start, und jedes Token darin kämpft um Aufmerksamkeit. Deine React-Muster laden, während du eine Datenbank-Migration debuggst. Deine Deployment-Regeln laden, während du Unit-Tests schreibst.

Ein besserer Ansatz: CLAUDE.md schlank halten und auf aufgabenspezifische Docs verweisen.

# CLAUDE.md
 
## Tech Stack
 
- Next.js 15 with App Router
- TypeScript strict mode
- PostgreSQL with Prisma ORM
- Tailwind CSS
 
## Standards
 
- Use path aliases (@/components, @/lib, @/utils)
- All functions require explicit return types
- Error handling: guard clauses with early returns
- Tests required for business logic
 
## Reference Docs (load when relevant)
 
- Frontend conventions: .claude/skills/react/SKILL.md
- API patterns: .claude/skills/api/SKILL.md
- Database rules: .claude/skills/postgres/SKILL.md
- Deployment: .claude/skills/infra/SKILL.md

Etwa 15 Zeilen. Es deckt die universellen Regeln ab, die für jede Aufgabe gelten. Detailwissen lebt in separaten Dateien, die Claude nur lädt, wenn die Aufgabe es erfordert.

Die Ordnerstruktur:

.claude/
├── skills/
│   ├── react/          # Component patterns, hooks, state
│   ├── api/            # Route conventions, validation, auth
│   ├── postgres/       # Schema patterns, query optimization
│   └── infra/          # Docker, CI/CD, deployment
└── CLAUDE.md           # Lightweight global rules

Vergleich das mit der "alles in eine Datei"-Gewohnheit, bei der 200+ Zeilen Anweisungen in CLAUDE.md sitzen. Diese Datei verbrennt bei jeder Session Context, relevant oder nicht. Der modulare Ansatz lädt Domain-Wissen bei Bedarf.

3. Alles in Commands verwandeln

Wenn du etwas zweimal promptest, sollte es ein Command sein.

Ein Command in Claude Code ist eine Markdown-Datei in .claude/commands/, die einen wiederverwendbaren Workflow definiert. Wenn du /commit tippst, liest Claude die Command-Datei und folgt den Anweisungen. Kein erneutes Eintippen. Keine vergessenen Schritte.

So sieht ein einfacher Command aus:

# /commit
 
Review all staged changes with `git diff --cached`.
Write a commit message that:
 
- Starts with a verb (add, fix, update, remove)
- Summarizes the WHY, not the WHAT
- Stays under 72 characters
- Uses lowercase
 
Create the commit. Do not push.

Speichere das als .claude/commands/commit.md und du schreibst nie wieder Commit-Anweisungen.

Fünf Starter-Commands, die sich lohnen zu bauen:

• /commit für konsistente, gut formatierte Git-Commits
• /review für Code-Reviews gegen die Standards deines Projekts
• /plan für das Erstellen eines strukturierten Implementierungsplans vor dem Code-Schreiben
• /prime für das Laden von Session-Context am Anfang jedes Gesprächs
• /execute für das Ausführen eines Plan-Dokuments, das in einer vorherigen Session erstellt wurde

Jeder Command braucht fünf Minuten zum Schreiben und spart Hunderte von Prompts über die Lebensdauer eines Projekts. Sie erzwingen auch Konsistenz. Deine Commits folgen immer demselben Format. Deine Code-Reviews prüfen immer dieselben Dinge. Der Zinseszins-Effekt ist real.

4. Der Context-Reset

Das ist die eine Gewohnheit, die sich kontraintuitiv anfühlt: Planen und Ausführen sollten in separaten Gesprächen stattfinden.

Der Ablauf:

1. Plan-Session: Problem erforschen, Tradeoffs diskutieren, Ansätze erkunden. Claude gibt ein strukturiertes Plan-Dokument aus (eine Markdown-Datei, die in deinem Projekt gespeichert wird).
2. Context leeren: Das Gespräch komplett beenden. Die Session beenden.
3. Ausführungs-Session: Frisch starten. Claude nur das Plan-Dokument aus Schritt eins geben. Nichts anderes.

Warum dieser Aufwand? Weil Context-Window-Degradation real ist.

Nach einem langen Planungsgespräch ist Claudes Context voll von Erkundungs-Tangenten, verworfenen Ansätzen und Zwischenüberlegungen, die nicht mehr zutreffen. Wenn du dann "okay, jetzt baue es" sagst, nimmt Claude all den Lärm in die Ausführung mit. Es könnte einen Ansatz vermeiden, den du diskutiert und verworfen hast, auch wenn dein endgültiger Plan ihn empfiehlt. Es könnte Annahmen aus dem frühen Gespräch mitschleppen, die du später korrigiert hast.

Ein frischer Context mit nur dem Plan bedeutet, dass Claude die Ausführung mit einem sauberen Kopf beginnt. Kein Gepäck aus der Planungsphase. Keine veralteten Annahmen. Nur das Spec. Und weil du keine Tokens für die Planungsgeschichte verbrennst, hat Claude mehr Raum, über Implementierungsdetails nachzudenken und seine Arbeit selbst zu überprüfen.

Das Plan-Dokument muss für sich allein stehen. Ein guter Plan enthält die Feature-Beschreibung, User-Story, Architecture-Context, Verweise auf die relevanten Komponenten und eine aufgabenweise Aufschlüsselung. Wenn Claude während der Ausführung klärende Fragen stellen muss, hat dein Plan Lücken.

In der Praxis:

# Planning session
claude "Research auth patterns for our Next.js app and create
an implementation plan. Save it to docs/auth-plan.md"
 
# (exit, start new session)
 
# Execution session
claude "Read docs/auth-plan.md and implement Phase 1"

Das Plan-Dokument fungiert als Übergabe zwischen deinem Planungs-Gehirn und deinem Ausführungs-Gehirn. Beide Sessions sind schärfer, weil keine versucht, beide Jobs gleichzeitig zu erledigen.

5. System-Evolutions-Denkweise

Jeder Bug ist ein Systemversagen, kein einmaliger Fehler. Der Unterschied zwischen gutem und großartigem agentischem Engineering liegt darin, ob du die Instanz oder das System behebst.

Drei echte Beispiele:

Falscher Import-Stil. Claude verwendet weiterhin relative Imports (../../components/Button) anstelle deiner Pfad-Aliase. Du könntest jeden einzeln von Hand fixen. Oder du fügst eine Zeile zu CLAUDE.md hinzu: "Always use @ path aliases for imports, never relative paths." Der Bug kommt nie wieder.

Vergessen, Tests auszuführen. Du beendest ein Feature, pushst in CI, Tests schlagen fehl, weil Claude sie nie lokal ausgeführt hat. Anstatt daran zu denken, jedes Mal "Tests ausführen" zu prompten, aktualisierst du deine /execute-Command-Vorlage um einen obligatorischen Test-Schritt am Ende jeder Implementierung. Jetzt endet jede Ausführungs-Session standardmäßig mit einem Test-Run.

Falscher Auth-Flow. Claude baut JWT-Auth mit Cookies, wenn dein Projekt Bearer-Tokens in Headern verwendet. Es ist passiert, weil es kein Referenzdokument für deine Auth-Muster gibt. Du erstellst .claude/skills/auth/SKILL.md mit deinem Token-Format, Header-Konventionen und Middleware-Mustern. Wenn das nächste Mal jemand (einschließlich deines zukünftigen Ichs) an Auth arbeitet, lädt Claude automatisch die richtigen Muster.

Das Muster ist immer dasselbe: etwas geht schief, du verfolgst es zurück zu einer fehlenden Anweisung oder einer fehlenden Referenz, und du fügst es deinem System hinzu. Über Wochen wird deine Konfiguration enger. Claude macht weniger Fehler, weil dein System weniger Lücken hat.

Ein praktischer Weg, die Gewohnheit aufzubauen: Frage nach jedem Feature Claude, deine Regeln und Commands zu überprüfen, die Ausführung mit dem Plan zu vergleichen und Verbesserungsvorschläge zu machen. "Lies CLAUDE.md und die Commands, die wir verwendet haben. Welche Regeln oder Prozessänderungen hätten die Probleme verhindert, auf die wir gestoßen sind?" Das verwandelt System-Evolution von einem Nachgedanken in einen Routine-Schritt.

Das ist, was einen Claude Code-Nutzer von einem Claude Code-Praktiker trennt. Der Nutzer behebt Bugs. Der Praktiker behebt das System, das den Bug produziert hat.

Alles zusammenbringen

Diese fünf Gewohnheiten sind keine unabhängigen Tipps. Sie bilden ein System.

Das PRD begrenzt deine Arbeit. Modulare Regeln halten den Context sauber. Commands beseitigen Wiederholung. Context-Resets halten Sessions scharf. System-Evolution verbessert das Ganze mit der Zeit.

Nichts davon braucht neue Tools oder teure Setups. Es ist eine Reihe von Gewohnheiten, die sich mit jedem Projekt, das du baust, verstärken. Fang mit der an, die heute deinen größten Schmerzpunkt angeht, und füge die anderen nach und nach hinzu.