Claude Code: Vom Prompt-Tool zum System

Viele nutzen Claude Code wie besseren Autocomplete:

Prompt rein → Code raus → Debugging.

Für kleine Tasks reicht das. Sobald es komplex wird, bricht es: Architektur passt nicht, Fehler ziehen sich durch mehrere Ebenen, Debugging frisst den Großteil der Zeit.

Das Problem ist nicht das Modell. Das Problem ist die Arbeitsweise.

Claude Code wird erst dann stark, wenn man es wie ein System nutzt – nicht wie ein Tool.

Der eigentliche Fehler: zu viel Kontext auf einmal

Typischer Ansatz: Idee + Architektur + Umsetzung + Review → alles in einem Prompt.

Das führt zwangsläufig zu mittelmäßigen Ergebnissen. Sprachmodelle verteilen ihre Aufmerksamkeit über den gesamten Kontext. Je breiter der Kontext, desto flacher die Qualität. Wer gleichzeitig fragt „Was ist das Problem?”, „Wie soll es gebaut werden?” und „Bau es jetzt” – bekommt auf alles okay-Antworten. Aber nichts wirklich gut.

Der Gegenansatz: Jeder Schritt bekommt seinen eigenen Fokus. Problem verstehen – ohne Lösung. Architektur planen – ohne Code. Implementieren – ohne Bewertung. Review – ohne neue Features.

Klingt trivial. Wird fast nie konsequent gemacht.

1. Phasen sauber trennen

Phase 1: Problem klären

Nicht direkt Lösungen vorgeben. Schlechter Einstieg:

Füge einen Cache für API-Calls ein, der nach 5 Minuten invalidiert.

Besser:

API-Calls dauern 800ms und blockieren die UI.
Welche Ansätze gibt es, das zu lösen?
Nicht implementieren – erst analysieren.

Hier merkt man oft: Das ursprüngliche Problem war gar nicht das echte.

Phase 2: Architektur festziehen

Jetzt Struktur – noch kein Code.

Kontext:
- React Frontend, kein Redux
- Daten ändern sich selten
- Mehrere Komponenten nutzen dieselben Endpoints

Entwirf die Architektur: Datenfluss, State, Schnittstellen, Edge Cases.
Ziel: keine offenen Grundsatzfragen mehr.

Phase 3: Umsetzung

Jetzt erst Code – mit klarem Kontext.

Implementiere:
- React Context für Cache
- Hook: useApiCache(endpoint, options)
- TTL + stale-while-revalidate Pattern

Starte mit dem Hook.

Kein Rätselraten mehr. Der Scope ist scharf.

Phase 4: Review

Separat. Nicht nebenbei.

Review mit Fokus auf:
- unnötige Komplexität
- fehlende Edge Cases
- Vereinfachungspotenzial

Keine neuen Features.

Phase 5: Verifikation

Nicht nur „läuft es”.

Simuliere:
- schlechte Verbindung (3G)
- Race Conditions
- gleichzeitige Zugriffe
- Session-Timeout nach 30 Minuten

Was passiert jeweils? Was sollte passieren?

Das ist der Schritt, der die meisten Bugs findet – weil er die Szenarien abdeckt, die man beim Schreiben von Tests nicht bedacht hat.

Phase 6: Deployment

Sauber ausrollen: Tests bündeln, Changes dokumentieren, keine impliziten Änderungen.

2. In Rollen denken statt in Prompts

Claude Code kann viele Perspektiven einnehmen – aber nicht gleichzeitig auf hohem Niveau. Also: explizit setzen. Das Prinzip ist dasselbe das bei KI-Agenten-Systemen mit Rollentrennung auf Team-Ebene funktioniert – hier angewendet auf eine einzelne Session.

# Produkt-Perspektive
Du bist Produktmanager mit technischem Hintergrund.
Ist das wirklich das Nutzerproblem? Was kann gestrichen werden?

# Architektur-Perspektive
Du bist System-Architekt.
Wie skaliert das auf 100x Last? Was bricht zuerst?

# Entwickler-Perspektive
Implementiere in TypeScript. Halte dich an bestehende Patterns.
Schreibe keinen Code, den du nicht erklären könntest.

# Reviewer-Perspektive
Du bist kritischer Code-Reviewer.
Finde Probleme – nicht Erklärungen.

# QA-Perspektive
Welche Edge Cases wurden übersehen?
Simuliere Stress-Szenarien. Denke wie jemand, der das System sabotieren will.

Gleiche Codebase – komplett andere Qualität der Antworten.

3. Verhalten persistent machen: CLAUDE.md

Nicht alles jedes Mal neu erklären. Eine CLAUDE.md im Projektverzeichnis wird bei jeder Session automatisch geladen – auch in CI/CD und von Subagents.

## Stack
TypeScript 6, React 19, Tailwind v4 – keine class-based Components.

## Regeln
- keine any-Typen ohne Kommentar warum
- keine Abstraktionen für einmalige Operationen
- keine Fallbacks für Szenarien die nicht passieren können

## Commit-Messages
Conventional Commits, auf Deutsch, kein Co-Authored-By.

Ergebnis: konsistentere Outputs, weniger Wiederholungen, weniger Drift über mehrere Sessions.

Zusätzlich: globale Einstellungen in ~/.claude/CLAUDE.md für persönliche Präferenzen, die für alle Projekte gelten.

4. Parallelisierung richtig nutzen

Parallelität bringt Speed – oder Chaos.

Falsch: User-Modell, Auth und Frontend gleichzeitig bauen. Ergebnis: Inkonsistenzen garantiert.

Richtig: Reihenfolge bleibt entscheidend.

# 1. Schema und Typen zuerst – Basis für alles
git worktree add ../auth-schema -b feature/auth-schema

# 2. Erst wenn Schema fertig: Middleware baut darauf auf
git worktree add ../auth-middleware -b feature/auth-middleware

# 3. Erst wenn API stabil: Frontend
git worktree add ../auth-frontend -b feature/auth-frontend

Worktrees ermöglichen parallele Arbeit ohne gegenseitige Überschreibungen. Jeder Branch hat seinen eigenen Arbeitsbereich.

5. Isolation als Schlüssel

Ohne Isolation wird Parallelisierung schnell gefährlich. Drei Ebenen:

• Code – separate Branches oder Worktrees pro Task
• Kontext – jede Session bekommt nur den Kontext den sie braucht
• State – Datenbankmigrationen, Config-Änderungen isoliert testen bevor sie in die Hauptbranch fließen

6. Automatisierte Zwischenschritte

Claude nicht nur bauen lassen – auch bereinigen.

Vereinfache diesen Code:
- doppelte Logik zusammenführen
- unnötige Variablen entfernen
- Lesbarkeit verbessern ohne Verhalten zu ändern

Prüfe auf:
- console.logs die vergessen wurden
- TODOs ohne Ticket-Referenz
- fehlendes Error Handling
- any-Typen die umgangen wurden

Das ersetzt kein echtes Review. Aber es hebt das Ausgangsniveau – bevor der Review beginnt.

7. Echte Verifikation statt „kompiliert”

Kompiliert ≠ funktioniert.

User registriert sich. Bestätigungs-E-Mail kommt nicht an.
User versucht sich trotzdem anzumelden.
Was passiert? Was sollte passieren? Was fehlt?

Was passiert bei:
- DB-Ausfall
- 3G-Verbindung
- gleichzeitigen Zugriffen auf dieselbe Ressource
- Tab der 30 Minuten inaktiv war

Tests decken ab, was man erwartet. Verifikation deckt ab, was man vergessen hat.

Die nächste Ebene: Das System orchestriert sich selbst

Der Ansatz bisher beschreibt, wie man die Arbeit strukturiert – manuell. Wer konsequent ist, stellt irgendwann fest: Die Orchestrierung selbst ist wieder automatisierbar.

Hooks: Was nach jedem Schritt automatisch passiert

Claude Code hat ein deterministisches Hook-System über settings.json. Hooks laufen unabhängig vom Prompt – deterministisch, bei jedem zugehörigen Event.

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "npx tsc --noEmit && npx eslint $CLAUDE_TOOL_INPUT_FILE_PATH"
      }]
    }],
    "Stop": [{
      "hooks": [{
        "type": "agent",
        "prompt": "Prüfe ob offene TODOs in den geänderten Dateien adressiert sind. Falls nicht, gib Feedback zurück.",
        "timeout": 60
      }]
    }]
  }
}

Exit Code 2 aus einem Hook: Claude bekommt das stderr als Feedback und arbeitet weiter. Das macht Hooks zu einer Schleife, nicht nur einem Einmal-Check. Typ-Fehler werden direkt nach jeder Dateiänderung gemeldet – kein manueller Schritt nötig.

Subagents: Rollen werden eigenständig

Statt manuell die Perspektive zu wechseln, kann jede Rolle als eigener Subagent definiert werden. Subagents sind Markdown-Dateien in .claude/agents/:

---
name: code-reviewer
description: Kritischer Code-Reviewer. Proaktiv nach Implementierungen einsetzen.
tools: Read, Grep, Glob
model: sonnet
---
Du bist Senior-Entwickler. Deine Aufgabe ist Probleme finden – nicht erklären.
Prüfe: unnötige Komplexität, fehlende Edge Cases, Sicherheitsprobleme.
Konkretes, umsetzbares Feedback.

Hooks können Subagents automatisch triggern. Der Reviewer läuft in einem eigenen Kontext-Fenster, liest die geänderten Dateien, gibt sein Ergebnis zurück – kein Overhead im Hauptprozess.

Mit isolation: "worktree" bekommt der Subagent einen eigenen Git-Worktree, arbeitet isoliert, und der Worktree wird nach Abschluss aufgeräumt oder als Branch zurückgegeben.

GitHub Actions: Automatisierung außerhalb der Session

name: Automatisches Code-Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review diesen PR auf Codequalität, fehlende Typen, Edge Cases,
            Security-Probleme. Poste Findings als Review-Kommentare.
            Halte dich an die Standards aus CLAUDE.md.
          claude_args: "--max-turns 5"

CLAUDE.md wird in CI/CD automatisch eingelesen. Coding-Standards und Review-Kriterien gelten auch für den automatischen Review-Agent. Der Loop schließt sich: Implementierung in der Session → Review im PR → Verifikation in CI/CD → Deployment.

Agent SDK: Phasen programmatisch orchestrieren

from claude_agent_sdk import query, ClaudeAgentOptions

session_id = None

# Phase 1: Architektur – kein Schreibzugriff
async for msg in query(
    "Analysiere das Problem und entwirf die Architektur. Noch kein Code.",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Grep", "Glob"])
):
    if hasattr(msg, "session_id"):
        session_id = msg.session_id

# Phase 2: Implementierung – voller Kontext aus Phase 1
async for msg in query(
    "Implementiere nach der Architektur aus Phase 1.",
    options=ClaudeAgentOptions(
        resume=session_id,
        allowed_tools=["Read", "Edit", "Write", "Bash"]
    )
):
    pass

# Phase 3: Review – neuer Kontext, nur Lesezugriff
async for msg in query(
    "Review die Implementierung. Finde Probleme.",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Grep", "Glob", "Agent"])
):
    pass

Jede Phase bekommt genau die Tools die sie braucht. Phase 1 kann keine Dateien ändern. Phase 3 kann keinen Code ausführen. Die Phasen-Logik liegt im Code – nicht im Prompt.

Drei Schichten

Das vollständige System:

• Wissensschicht (CLAUDE.md) – Kontext, Standards, Regeln. Wird von jeder Session und jedem Subagent gelesen.
• Ausführungsschicht (settings.json Hooks) – Deterministische Schritte unabhängig vom Prompt: Tests, Linter, automatische Reviews.
• Orchestrierungsschicht (Agent SDK / GitHub Actions) – Wer wann was ausführt: Phasen-Sequenz, Subagent-Aufruf, CI/CD-Integration.

Manuelles Strukturieren ist der Einstieg. Automatisierte Orchestrierung ist das Ziel.

Warum das als System funktioniert

Die Teile verstärken sich gegenseitig:

• Klare Phasen → klarer Kontext
• Klarer Kontext → bessere Outputs
• Bessere Outputs → sichere Parallelisierung
• Isolation → keine Seiteneffekte
• Automatisierte Checks → höhere Basisqualität
• Echte Verifikation → stabile erste Versionen

Einzeln nützlich. Zusammen ein anderer Arbeitsmodus.

Typische Fehler

• Zu früh parallelisieren – vor stabiler Architektur
• Architektur überspringen – kostet später das Doppelte
• Rollen nicht explizit setzen – generische Prompts, generische Antworten
• Regeln nicht in CLAUDE.md persistieren – gleiche Fehler, Session für Session
• Review auslassen – „sieht gut aus” ist kein Review
• Verifikation mit Tests verwechseln – Tests testen was man erwartet hat

Realistische Erwartung

Fehler verschwinden nicht. Verständnis bleibt notwendig. Entscheidungen müssen bewertet werden.

Aber: weniger Debugging, stabilere erste Versionen, weniger grundlegende Korrekturen.

Das ist kein Magie-Versprechen. Es ist Handwerk – angewendet auf einen neuen Kontext.

Unterm Strich

Claude Code ist kein „Prompt rein, fertig”. Es ist ein System für strukturierte Entwicklung.

Der Unterschied liegt nicht im Modell. Sondern darin, wie man arbeitet. Das System ist erlernbar – und zahlt sich schneller aus als erwartet.

Wer den Ansatz auf größere Teams ausweiten will, findet in AI-Guide für größere Softwareprojekte die Fortsetzung.