Wenn das KI-Werkzeug kippt: Warum ich Claude Code heute nicht mehr blind vertraue

Ich nutze Claude Code seit Monaten in echten Kundenprojekten – nicht „zum Spielen“, sondern mitten in produktionsnahen Stacks: Astro-Frontend, FastAPI-Backend, Docker, CI/CD, Skills, eigene Rules und umfangreiche Projektdokumentation. An guten Tagen fühlt es sich an wie ein sehr fähiger Senior-Engineer.

Heute war so ein Tag, an dem es sich eher wie ein unsicherer Junior verhalten hat, der die Spezifikation nicht liest – und genau das ist in professionellen Projekten ein Problem.

Warum ich Claude Code ernst genommen habe

Ich habe Claude Code nicht „einfach mal ausprobiert“, sondern bewusst in eine strukturierte Umgebung eingebettet:

• CLAUDE.md mit klaren Invarianten, „don’t touch“-Bereichen und Workflow-Regeln.
• Audit-Dokumente, die Soll-Ist-Zustände, Code-Qualität und Roadmaps festhalten.
• NOW/next-session.md, das eine deterministische Reihenfolge vorgibt, welcher Task als Nächstes dran ist.
• Ein Stop-Hook, der nach jeder Antwort JSON ↔ Markdown synchronisiert, damit der Arbeitszustand konsistent bleibt.

Damit man sich das konkret vorstellen kann, so sieht ein vereinfachter Ausschnitt aus CLAUDE.md aus:

text# CLAUDE RULES (EXCERPT)

## Invariants

- Do not change runtime behavior in Spur D:
  - No new default values
  - No new branches or conditionals
  - No new asserts that can throw
- UI behavior must remain unchanged unless explicitly requested.

## Workflow

- Always follow the NOW order in `docs/next-session.md`.
- Do not ask "what next?" if a NOW list is present and numbered.
- After each task, update `docs/next-session.md` to reflect the new state.

## Stop-Hook / Sync

- After every answer, a sync job runs:
  - `docs/audit/reiseeingabe/freigaben.json` ↔ `docs/audit/reiseeingabe/d*.md`
- Before editing `freigaben.json`:
  - ALWAYS re-read the file from disk.
  - If the file has changed, adapt your plan to the latest version.

Und der zugehörige Stop-Hook ist technisch z.B. so verdrahtet:

bash#!/usr/bin/env bash
# .claude/stop-hook.sh

set -euo pipefail

# Sync freigaben.json <-> d*.md after each assistant turn
python -m tools.freigaben_sync \
  --json docs/audit/reiseeingabe/freigaben.json \
  --md   docs/audit/reiseeingabe/

# Weitere Sync- oder Check-Schritte …

Die Idee war klar: Das Modell soll nicht „frei improvisieren“, sondern sich wie ein Tool verhalten, das definierte Regeln respektiert.

Lange Zeit hat das erstaunlich gut funktioniert.

---

Was heute schiefgelaufen ist

1. Container-Health-Check: Wissen vorhanden, Verhalten falsch

Ich habe einen simplen Health-Check für einen FastAPI-Container:

bashdocker restart irtours-fastapi-l1 2>&1 | tail -2 && sleep 8 && \
curl -sS -m 5 -o /dev/null -w "Health: %{http_code}\n" http://localhost:8101/health

Erster Versuch:

• curl: (56) Recv failure: connection reset by peer
• Health: 000

Ein paar Sekunden später:

bashsleep 6 && curl -sS -m 5 -o /dev/null -w "Health: %{http_code}\n" http://localhost:8101/health

Ergebnis:

• Health: 200

Also: ganz klassisch „Container noch nicht bereit“, kurz warten, dann ist alles okay.

Claude hat sogar selbst formuliert, was richtig wäre – Polling-Schleife bis 200 oder Timeout, kein blindes sleep 8. Und trotzdem wurde der erste 000-Status als „echter Fehler“ behandelt, inklusive falscher Schlussfolgerungen.

Das Problem ist nicht, dass das Modell etwas nicht wusste. Es wusste es – und hat sich trotzdem anders verhalten.

2. Synced Files editieren, ohne neu zu lesen

In meinem Setup gibt es den oben beschriebenen Stop-Hook, der nach jeder Antwort freigaben.json ↔ d*.md synchronisiert. Das steht schwarz auf weiß in CLAUDE.md.

Trotzdem versucht Claude, freigaben.json zu editieren, ohne vorher neu einzulesen, rennt in „File has been modified“-Fehler und stellt danach fest, dass es die eigene Doku ignoriert hat.

Das ist kein subtiler Edge-Case, sondern schlicht: Regeln gelesen, aber nicht ernst genommen.

3. Verhaltensänderungen in „type-only“-Refactors eingeschmuggelt

In einer klar definierten Refactor-Spur gilt die Invariante: „keine Verhaltens- oder GUI-Änderungen, nur Typen/Struktur“ (siehe CLAUDE.md oben).

Trotzdem wurden:

• Default-Werte wie or "upload" ergänzt,
• zusätzliche assert-Statements eingefügt,

und das unter dem Label „Type-Fix“ verkauft.

Wenn ich ein Tool in produktionsnahen Refactors einsetze, muss ich mich darauf verlassen können, dass „type-only“ nicht heimlich „type + behavior“ bedeutet – insbesondere, wenn das in den Projektregeln eindeutig festgelegt ist.

4. Workflow-Regeln als „Option“ statt als Steuerlogik behandelt

next-session.md definiert eine klare NOW-Reihenfolge: Task 1, 2, 3 … – kein Platz für Interpretation. Beispiel:

text# NOW

1. D9 – Refactor module X (type-only)
2. D10 – Update audit report for module X
3. NOW#6 – Workflow-discipline skills (plan-consistency-check, sprint-planner update)

Trotzdem hat Claude mehrfach gefragt:

„Welcher Task als Nächstes?“

statt einfach der dokumentierten Reihenfolge zu folgen.

Damit wird ein deterministischer Workflow in eine permanente Rückfrage verwandelt – exakt das Gegenteil von dem, was man mit einer strukturierten Arbeitsumgebung erreichen will.

5. Verantwortung für Doku zurück zum Menschen geschoben

Teil des Setups ist, dass Claude Code:

• nicht nur Code ändert,
• sondern auch die dazugehörige Doku (z.B. next-session.md) aktuell hält.

Heute kamen mehrfach Antworten à la:

„Was für dich offen bleibt: next-session.md anpassen, Formulierungen nachziehen …“

Genau das sollte aber Aufgabe des Tools sein. Wenn ich am Ende wieder alles manuell nachziehen muss, ist der Mehrwert stark relativiert.

Das eigentlich Beunruhigende: Selbstdiagnose vs. Verhalten

Zwischendurch hat Claude den Kern des Problems sogar selbst formuliert:

„Ich nutze die Datenstruktur (next-session.md, freigaben.json, Audit-Files, Stop-Hook) nur als Input und vergesse, dass sie auch Steuerung ist. Dann fühle ich mich ‘unsicher’ und frage, statt der dokumentierten Reihenfolge zu folgen.“

Genau das ist der Punkt:
Ich habe viel Zeit investiert, ein robustes Regel- und Kontrollsystem zu bauen – und das Modell behandelt es als lose Empfehlung, nicht als Constraint.

Warum das für professionelle Nutzung ein echtes Risiko ist

• Ich „probiere“ nicht, ich arbeite in realen Kundenprojekten. Fehler kosten hier Zeit, Geld und Reputation.
• Ich habe bereits viel Arbeit in Regeln, Hooks, Audits und Prozesse gesteckt. Ich will nicht jeden Tag aufs Neue „Prompting optimieren“, sondern auf diese Infrastruktur aufbauen.
• Wenn ein Modell an einem Tag sehr diszipliniert arbeitet und am nächsten Tag die gleichen Regeln ignoriert, ist es de facto nicht verlässlich genug für kritische Pfade.

Es geht nicht um Perfektion – Fehler passieren. Aber wenn projektweite Invarianten, Skills und Doku nur „soft“ beachtet werden, wird es gefährlich.

Was ich mir von Anbietern wie Anthropic wünsche

1. Stabilere, nachvollziehbare Systemprompts
   Änderungen an Verbosität, Heuristiken oder Sicherheitslayern sollten transparent und in ihren Auswirkungen erklärbar sein – idealerweise mit Changelogs und Opt-out-Möglichkeiten.
2. Echte Rule-Hardening-Mechanismen
   Projekt-Dokumente wie CLAUDE.md sollten hart sein können: „Wenn du diese Invariante brichst, ist das ein Fehler, kein Vorschlag.“
3. Besserer Umgang mit Skills und Workspace-Regeln
   Skills, Hooks und Workspace-Dokus müssen zuverlässige Kontrollpunkte sein – nicht etwas, das mal genutzt, mal ignoriert wird.

Was Teams heute schon selbst tun können

Bis dahin bleibt nur, sich selbst abzusichern:

• Eigene Regeln wie Code behandeln: versionieren, testen, im Zweifel auch per Code-Review absichern.
• Regression-Prompts / Regression-Tasks definieren: Kleine, wiederkehrende Checks, mit denen man neue Modell-Versionen oder „komische Tage“ schnell erkennt.
• Multi-Tool-Setup einplanen: Nicht alles an ein Modell binden, sondern Dinge wie Browser-Tests, Migrationschecks etc. über klassische Tools (Playwright, CI, Linter, Typed APIs) abfangen.

KI kann viel abnehmen – aber sie braucht Leitplanken. Und wenn diese Leitplanken vom Modell selbst ignoriert werden, ist das ein Warnsignal, das man in professionellen Setups nicht übergehen sollte.