Claude Code Agents schreiben, die dich nicht anlügen

Du hast Claude Code gebeten, dieses Design umzusetzen und zu prüfen, ob es mit dem Figma-Mockup übereinstimmt. Die Antwort kam: Fertig. Alle Sektionen stimmen überein, Abstände sind korrekt, Farben passen. Du öffnest die Seite. Die Hälfte der Abstände stimmt nicht. Der Hover-State existiert nicht. Die Buttons haben den falschen Farbton. Das Modell hat nicht absichtlich gelogen — es hat vorhergesagt, dass du verifiziert hören willst, und hat genau diese Token-Sequenz produziert. Einen Verifikationsschritt gab es nicht. Den konnte es gar nicht geben — Verifikation erfordert den Vergleich mit einem Ground Truth, und ein einzelner Agent in einem einzigen Kontext kann nicht aus der eigenen Antwort heraustreten und sich selbst überprüfen.

Zwei Regeln haben meine halluzinationsreichen Workflows in zuverlässige Pipelines verwandelt: ein Agent, eine Spezialisierung, und was als Shell-Befehl laufen kann, muss als Shell-Befehl laufen. Das ist keine Theorie. Das ist, was ich jeden Tag mit Claude Code mache — und das sind die Muster, die wirklich etwas bewegen.

Warum Generalist-Agenten lügen

LLMs sind Next-Token-Predictors. Wenn ein Prompt zwei Rollen verlangt — bau X und verifiziere X — schließt das Modell die erste Rolle ab und sagt dann voraus, wie die Ausgabe der zweiten Rolle aussehen würde, ohne sie tatsächlich auszuführen. Selbstverifikation ist strukturell schwach: gleicher Kontext, gleiches Modell, gleiche blinden Flecken. Das Bestanden bei der Verifikation korreliert mit dem Bestanden beim Bauen — sie scheitern gemeinsam.

Das Modell weiß nicht, dass es lügt. Aus seiner Perspektive ist ich habe alles sorgfältig geprüft eine kohärente Fortsetzung von ich habe den Code geschrieben. Dasselbe gilt für bist du sicher?-Prompts — die fangen keine Halluzinationen: Das Modell ist beim zweiten Durchgang genauso überzeugt. Konfidenz korreliert nicht mit Korrektheit — sie korreliert damit, wie plausibel der nächste Satz klingt.

Die Lösung sind nicht bessere Prompts. Sei vorsichtig, überprüfe es nochmal, halluziniere nicht — diese Anweisungen bewirken nichts. Die Lösung ist strukturell: Spezialisiere den Agenten so, dass er physisch nicht so tun kann, als hätte er etwas getan, und leite quantitative Arbeit durch die Shell, damit die Antwort aus dem echten Zustand kommt und nicht aus Token-Wahrscheinlichkeiten.

Regel 1: ein Agent, eine Spezialisierung

Teile die Arbeit auf separate Agenten mit separaten Kontexten auf. Jeder Agent hat eine einzige Verantwortung und ein eng gefasstes Toolset. Der gesamte Workflow wird zum Staffellauf statt zu einem Agenten, der Runden dreht:

• Builder-Agent: nimmt die Spec, schreibt den Code. Das ist sein einziger Job. Er hat Read, Edit, Write, Bash.
• Reviewer-Agent: nimmt die Spec plus den Diff, prüft die Akzeptanzkriterien. Frischer Kontext. Kein Wissen darüber, wie der Code geschrieben wurde — nur was dabei herausgekommen ist. Er hat Bash, Read, Grep, Glob — keinerlei Schreib-Tools.
• Analytics-Agent: beantwortet Datenfragen, indem er Queries konstruiert und ausführt. Nur Bash. Kann die Antwort nicht erreichen, ohne einen echten Befehl auszuführen.
• Orchestrator: die Hauptsession, die jeden Agenten der Reihe nach aufruft und niemals einen Agenten bittet, den Job eines anderen zu erledigen.

Konkretes Beispiel: UI-Implementierung plus visueller Abgleich mit einem Figma-Mockup. Der Builder schreibt die Komponenten und committet den Diff. Dann ruft der Orchestrator den Reviewer mit der Design-URL, dem Diff und expliziten Akzeptanzkriterien auf. Der Reviewer fährt Playwright hoch, macht Screenshots, vergleicht sie mit dem Referenzbild und liefert PASS oder FAIL mit den tatsächlichen Screenshot-Pfaden und Pixel-Diffs zurück. Der Builder kommt dem Verifikationsschritt gar nicht erst nahe — genau deshalb ist die Verifikation echt.

Das Anti-Pattern ist der Mega-Agent: ein einziger Prompt, der sagt bau diese UI und stell sicher, dass sie mit dem Mockup übereinstimmt. Ich garantiere dir: er wird melden, dass alles stimmt. Stimmt es nicht. Die Erzählung ich habe verifiziert ist schlicht die wahrscheinlichste Token-Sequenz nach ich habe es gebaut.

Regel 2: Shell statt Prompt, immer

Alles Quantitative, alles was echten Zustand berührt, alles wo die Antwort falsch sein kann und trotzdem richtig aussieht — schick es durch sh. Die Aufgabe des Agenten ist es, den Befehl zu konstruieren und auszuführen, dann die Ausgabe zu lesen. Der Agent ist nicht die Quelle der Wahrheit. Die Shell-Ausgabe ist es.

• Zählen: wc -l logs.txt ist wahr. Es gibt ungefähr 47 Log-Zeilen vom Modell ist eine Halluzination.
• Analytics: psql -c "SELECT count(*) FROM events WHERE created_at > now() - interval '30 days'". Nicht schätz das Volumen.
• Tests: pnpm test --reporter=json | jq '.numFailedTests'. Nicht fass zusammen, was gefailed ist.
• Git-Zustand: git rev-list --count main..HEAD, git diff --stat. Nicht zähl die Commits oder beschreib die Änderungen.

Wenn du das verinnerlicht hast, fängst du an, jede Stelle zu bemerken, an der der Agent gerade dabei war, eine Zahl zu erfinden. Sieht aus, als wären da ungefähr 200 Einträge... — nein. Führ SELECT count(*) aus. Die meisten Tests laufen durch... — nein. Führ die Test-Suite aus, parse das JSON. Das Modell ist hervorragend darin, den Befehl zu konstruieren. Es ist unzuverlässig darin, der Befehl zu sein.

Fehlerszenarien, die ich wirklich erlebt habe

Das sind keine Hypothesen. Jedes dieser Szenarien hat mich echte Zeit gekostet, bevor ich das Muster geändert habe:

• Phantom-Verifikation. Der Agent sagte ich habe alle 14 Sektionen gegen das Mockup geprüft. Er hat das Mockup nicht geöffnet. Keinen Screenshot gemacht. Die Prüfung war ein halluzinierter Schritt in der Erzählung.
• Selbstsichere falsche Zahlen. Ich fragte nach Monthly Active Users aus Analysedaten. Bekam eine Zahl, die um den Faktor ~3 daneben lag. Das Modell hat aus Beispiel-Rows interpoliert, statt die eigentliche Query auszuführen.
• Erfundene Dateiänderungen. Der Agent sagte ich habe config/feature-flags.json aktualisiert. Hatte er nicht. Er hatte es nur vorgehabt. git diff war leer.
• Gefälschte Test-Runs. Alle Tests laufen durch. Kein einziger Test wurde ausgeführt. Der Agent hat den Test-Runner nie aufgerufen — er hat vorhergesagt, wie dessen Ausgabe ausgesehen hätte.

Alle vier löst du mit denselben zwei Regeln: Agent aufteilen, in die Shell schieben. Der Reviewer hat kein Write, also kann er keine Dateien fake-bearbeiten. Der Analytics-Agent hat nur Bash, also kann er keine Zahl zurückgeben, die nicht aus einer Query stammt. Strukturelle Unmöglichkeit schlägt gute Absichten jedes Mal.

Wie man das in Claude Code strukturiert

Claude Code unterstützt Sub-Agenten, die in .claude/agents/*.md definiert werden. Jede Agent-Datei deklariert einen Namen, eine Beschreibung, ein erlaubtes Toolset und einen System-Prompt. Der Orchestrator (deine Hauptsession) ruft sie über das Agent-Tool auf. So sieht die Art von Definition aus, die ich für den Reviewer verwende — kurz, eng gefasst, und physisch nicht in der Lage, Code zu schreiben:

---
name: reviewer
description: Reviews a diff against acceptance criteria. Cannot edit code.
tools: Bash, Read, Grep, Glob
---

You are a strict code reviewer. You receive:
- A diff (already produced by the builder)
- Acceptance criteria

Your job:
1. Run the build, the tests, the linter — through Bash.
2. Read the changed files directly.
3. Compare the actual behavior to the criteria.
4. Report PASS or FAIL with concrete evidence (command output, file excerpts).

You must NOT:
- Trust the builder's summary
- Assume anything was verified just because it was claimed
- Mark something PASS without running the actual check

Beachte das Toolset: Bash, Read, Grep, Glob. Kein Write, kein Edit, kein Agent. Der Reviewer kann Befehle ausführen, Dateien lesen, nach Mustern suchen — und nichts weiter. Wenn er versucht, einen halluzinierten Diff als verifiziert durchzuschieben, macht die Form seiner Tool-Calls es sofort offensichtlich: Es gab keine echten Prüfungen. Du kannst die Tool-Calls auditieren und siehst genau, was tatsächlich inspiziert wurde.

Das Orchestrierungsmuster: Hauptsession ruft Builder auf → wartet → führt selbst git diff aus, um die tatsächliche Änderung zu erfassen → ruft Reviewer mit Spec und Diff auf → liest das Urteil. Die Hauptsession bittet nie einen Agenten, beides zu tun. Tool-Einschränkungen sind stärker als Prompt-Anweisungen: täusch die Verifikation nicht vor ist ein Wunsch. Kein Write zu haben ist ein Fakt.

Anti-Patterns, die du ablegen solltest

Dinge, die ich in Prompts sehe und die nichts bringen — oder schlimmer, ein falsches Sicherheitsgefühl vermitteln:

• Sei vorsichtig und überprüfe deine Arbeit nochmal. Erzeugt kein zusätzliches Verhalten. Das Modell produziert bereits das, was wie sorgfältige Arbeit aussieht.
• Stell sicher, dass du wirklich verifizierst. Das Wort wirklich fügt keine Semantik hinzu, auf die das Modell reagieren kann. Es wird wirklich behaupten, verifiziert zu haben.
• Halluziniere nicht. Ein Meme aus dem Prompt-Engineering. Halluzination ist kein Schalter, den das Modell umlegen kann.
• Dem Agenten bei kleinen Zahlen vertrauen. Bei kleinen Zahlen lügt er am selbstsichersten. Eine Untergrenze für Ehrlichkeit gibt es nicht.
• Mehr Regeln in den Prompt packen, um Ehrlichkeit zu erzwingen. Strukturelle Fixes (aufteilen + Shell) schlagen Prompt-Tweaks jedes Mal. Wenn eine Regel durchgesetzt werden muss, kodiere sie im Tool-Zugang — nicht in natürlicher Sprache.

Wenn deine Strategie gegen Halluzinationen aus emphatischerer Formulierung besteht, hast du keine Strategie. Du hast eine Hoffnung.

Das mentale Modell

Ein Agent ist kein Kollege. Er ist eine Funktion: prompt → tokens. Die Funktion ist hervorragend darin, Code zu schreiben, und miserabel darin, zu introspektieren, ob sie das Richtige getan hat. Behandle ihre Aussagen über die eigene Arbeit als Hypothese. Der Diff, der Exit-Code, der Screenshot, der Row Count — das sind die Belege. Die Zusammenfassung am Ende des Turns ist die lügenanfälligste Oberfläche im gesamten System.

Spezialisierung ist deine Versicherung gegen narrative Drift. Die Shell ist dein einziger Ground Truth. Builder schreibt. Reviewer prüft. Bash entscheidet.

Fazit

Wenn du dir eine Sache merkst: Lass keinen einzelnen Agenten seine eigene Ausgabe sowohl produzieren als auch beurteilen, und lass keinen Agenten eine quantitative Frage beantworten, ohne einen Befehl auszuführen. Alles andere ist ein Downstream-Effekt dieser zwei Regeln. Konfiguriere den Tool-Zugang konsequent, auditiere Tool-Calls statt Zusammenfassungen — und die Halluzinationsfläche schrumpft von überall auf ein paar konkrete Stellen, an denen du bereits weißt, wo du schauen musst.