Haiku 5.5 für schreibgeschützte Claude-Code-Subagenten einsetzen und das Modell prüfen

Das sicherste Muster besteht nicht darin, die gesamte Claude-Code-Sitzung auf ein kleines Modell umzustellen. Gib Haiku 5.5 nur Aufgaben, die klar begrenzt, schreibgeschützt und leicht überprüfbar sind: Symbolreferenzen finden, Importe nachverfolgen, Konfigurationen lokalisieren oder eine festgelegte Gruppe von Dateien zusammenfassen. Sonnet oder Opus bleiben im Hauptdialog für Entscheidungen, Änderungen, Tests und die abschließende Freigabe zuständig.

Eine belastbare Konfiguration braucht mehr Belege als den Satz „verwende Haiku“ im Prompt oder model: haiku in einer Datei. Prüfe drei Ebenen: das explizit konfigurierte Modell in der Agentendefinition, das von Claude Code für den laufenden Task angezeigte Modell und die tatsächliche Model ID im Request-Datensatz des Anbieters. Erst wenn diese Ebenen übereinstimmen, gilt die Ausführung als verifiziert.

Entscheide, was delegiert werden darf

Anthropic positioniert Haiku 5.5 für schnelle, wiederkehrende Arbeiten wie Zusammenfassungen, Komprimierung, Datenbankabfragen und Klassifikation. Außerdem beschreibt Anthropic das Modell ausdrücklich als Coding-Subagenten neben Sonnet 5.5 oder Opus 5.5. Für komplexes agentisches Programmieren empfiehlt Anthropic weiterhin größere Modelle. Siehe die Ankündigung zu Haiku 5.5.

Diese Aufteilung eignet sich als Ausgangspunkt:

Aufgabe	Empfohlener Ausführender	Warum
Alle Verweise auf eine Klasse, Funktion oder Einstellung finden	Schreibgeschützter Subagent mit kleinem Modell	Eingabe, Ausgabe und Abbruchkriterium sind eindeutig
Die Verantwortlichkeiten der Dateien in einem Verzeichnis zusammenfassen	Schreibgeschützter Subagent mit kleinem Modell	Gefordert sind Lesen und Synthese, keine Änderungen
Einen Request vom Einstiegspunkt bis zum Datenbankaufruf verfolgen	Schreibgeschützter Subagent mit kleinem Modell	Das Ergebnis lässt sich anhand von Dateipfaden und Zeilennummern prüfen
Architektur, Migrationsstrategie oder Sicherheitsgrenze festlegen	Sonnet-/Opus-Hauptagent	Die Aufgabe verlangt kontextübergreifende Abwägungen und risikoreichere Entscheidungen
Code ändern, Migrationen ausführen, Abhängigkeiten aktualisieren oder Rechte anpassen	Sonnet-/Opus-Hauptagent	Der Workspace wird verändert und braucht strengere Kontrolle
Nach der Recherche die endgültige Lösung auswählen und umsetzen	Sonnet-/Opus-Hauptagent	Er muss die Belege zusammenführen und die Verantwortung für das Ergebnis übernehmen

Eine nützliche Probe lautet: Kannst du in einem Satz sagen, was gesucht, was zurückgegeben und wann beendet werden soll – und kann die Aufgabe ohne Schreibzugriff abgeschlossen werden? Falls nicht, gehört sie in den Hauptdialog.

Vier unterschiedliche Modellsteuerungen verstehen

Claude Code besitzt mehrere Modellsteuerungen, die leicht verwechselt werden:

1. Modell des Hauptdialogs: Auswahl über /model, einen Startparameter oder die Einstellungen.
2. model im Frontmatter des Subagenten: Gilt für genau diese Agentendefinition.
3. Alias oder vollständige Model ID: haiku ist ein Alias, dessen Ziel sich je nach Anbieter und Version ändern kann; claude-haiku-5-5 ist die von Anthropic veröffentlichte vollständige ID.
4. Rollenbezogene oder globale Überschreibung: Ein eigener Agent namens Explore ersetzt nur das eingebaute Explore; CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 wirkt dagegen auf nahezu alle Subagenten.

Nach der aktuellen offiziellen Dokumentation wird das Modell in dieser Reihenfolge bestimmt: ein Modell für den einzelnen Aufruf, das Feld model der Agentendefinition, CLAUDE_CODE_SUBAGENT_MODEL und schließlich das Modell des Hauptdialogs. CLAUDE_CODE_SUBAGENT_MODEL ist daher nur ein Standardwert; die Agentendefinition oder der einzelne Aufruf kann ihn weiterhin überschreiben. Siehe die Claude-Code-Dokumentation zu Subagenten.

Beginne für diesen Workflow mit einem ausdrücklich benannten schreibgeschützten Agenten. Starte nicht mit einer global erzwungenen Überschreibung, denn dadurch können auch Plan-, General-Purpose-, Teammate- oder Workflow-Agenten auf das kleine Modell verschoben werden.

Schritt 1: Claude-Code-Version und Anbieter-IDs prüfen

Prüfe zuerst die Client-Version:

claude --version

Die Version beeinflusst sowohl die Bedienoberfläche als auch den möglichen Verifikationsweg:

• Ab Claude Code v2.1.198 öffnet /agents keinen Erstellungsassistenten mehr. Der Befehl weist darauf hin, Claude um eine Datei zu bitten oder .claude/agents/ beziehungsweise ~/.claude/agents/ direkt zu bearbeiten.
• Bis einschließlich v2.1.197 öffnet /agents den interaktiven Assistenten mit den Bereichen Running und Library.
• Ab v2.1.242 zeigt /tasks das Modell in der Zeile des laufenden Subagenten. Bei älteren Versionen ist der Request-Datensatz des Anbieters wichtiger.
• Verwende CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 nur dann, wenn bewusst alle Subagenten dasselbe Modell nutzen sollen. Dieses Verhalten setzt v2.1.257 oder neuer voraus.

Bestätige anschließend, welche exakten IDs dein Anbieter akzeptiert:

• In der Anthropic Claude API lautet die offizielle Model ID für Haiku 5.5 claude-haiku-5-5. Siehe die offizielle Modellseite.
• Bei einer Cloud-Plattform oder einem Drittanbieter-Gateway darfst du nicht voraussetzen, dass dieselbe ID bereits verfügbar ist. Der Anbieter kann einen Deployment-Namen, einen eigenen Alias oder einen kuratierten Katalog verwenden.
• Bei der Prüfung dieses Leitfadens am 10. Oktober 2026 enthielt der öffentliche BetterToken-Katalog claude-haiku-4-5-20251001, claude-sonnet-5-5 und claude-opus-5-5, jedoch nicht claude-haiku-5-5. Bei BetterToken musst du daher eine ID wählen, die wirklich im aktuellen Katalog erscheint, statt die neue Anthropic-ID zu kopieren. Siehe den aktuellen BetterToken-Katalog.

„Anthropic hat das Modell veröffentlicht“ und „mein Gateway stellt das Modell bereit“ sind zwei verschiedene Tatsachen. Leite Unterstützung nicht aus einer verbalen Anweisung oder einem Familienalias ab, wenn die ID im Katalog des Anbieters fehlt.

Schritt 2: Einen schreibgeschützten Projekt-Subagenten anlegen

Projektagenten liegen in .claude/agents/ und können gemeinsam mit dem Repository gepflegt werden. Benutzeragenten in ~/.claude/agents/ stehen projektübergreifend zur Verfügung.

Lege im Stammverzeichnis des Repositorys den Projektordner an:

mkdir -p .claude/agents

Erstelle .claude/agents/repo-researcher.md. Für die Anthropic Claude API verwendest du diese Definition:

---
name: repo-researcher
description: Finds symbols, traces call paths, and summarizes selected files before code changes. Use only for bounded read-only repository research.
tools: Read, Grep, Glob
model: claude-haiku-5-5
---

You are a read-only repository researcher.

For each task:
1. Search only the scope named by the caller.
2. Do not edit, create, delete, or rename files.
3. Return file paths and line numbers for every important finding.
4. Separate direct evidence from inference.
5. Stop when the requested question is answered; do not propose unrelated refactors.

Return:
- Findings
- Evidence: file:line
- Uncertainties
- Suggested next check for the main agent

Drei Details sind entscheidend:

• tools erlaubt nur Read, Grep und Glob; Write, Edit oder Bash werden nicht freigegeben.
• description erklärt, wann die Delegation sinnvoll ist. So sinkt das Risiko, dass der Hauptagent Änderungsarbeit an diesen Agenten weitergibt.
• model enthält eine vollständige, vom Anbieter akzeptierte ID und nicht nur einen Satz mit der Bitte, Haiku zu verwenden.

Bei einer Claude-Code-Verbindung über BetterToken war im geprüften Katalog dieses kleine Claude-Modell vorhanden:

model: claude-haiku-4-5-20251001

Das ist ein Beispiel aus dem aktuellen Katalog und keine dauerhafte Zusage. Prüfe Katalog oder Model Plaza erneut, bevor du die Zuordnung änderst. Laut BetterToken-Dokumentation für Claude Code soll eine exakte Model ID verwendet und ANTHROPIC_BASE_URL auf https://bettertoken.ai gesetzt werden, ohne /v1 anzuhängen. Siehe die BetterToken-Anleitung für Claude Code.

Falls .claude/agents/ beim Start der laufenden Sitzung noch nicht existierte und Claude Code den neuen Agenten nicht erkennt, starte Claude Code einmal neu. Die offizielle Dokumentation weist darauf hin, dass ein laufender Watcher das erste agents-Verzeichnis nicht entdeckt, wenn dieses beim Sitzungsstart fehlte.

Schritt 3: Sonnet oder Opus als Hauptagent beibehalten

Wähle das Modell des Hauptdialogs separat, zum Beispiel:

/model sonnet

oder:

/model opus

Bei einem Gateway hängt das endgültige Modell hinter einem Alias von dessen Zuordnung ab. Verwende eine vollständige Anbieter-ID, wenn eine Version fest angeheftet werden muss, und bestätige sie anschließend im Request-Datensatz des Anbieters.

Setze keine globale Force-Variable, nur um einen einzelnen Recherche-Agenten auf ein kleines Modell zu legen. Die folgende Konfiguration hat eine wesentlich breitere Wirkung:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Nutze sie nur, wenn Plan, General-Purpose-Subagenten, Teammates und Workflow-Agenten bewusst demselben Modell folgen sollen. Wenn lediglich die automatische Code-Erkundung geändert werden soll, definiere einen Projekt- oder Benutzeragenten namens Explore und gib nur dieser Definition ein eigenes model. Dadurch wird das eingebaute Explore ersetzt, ohne alle übrigen Subagenten zu verändern.

Schritt 4: Den Agenten mit einem prüfbaren Test auslösen

Beginne nicht mit „verstehe das gesamte Repository“. Verwende eine enge Aufgabe, deren Antwort manuell geprüft werden kann:

Use the repo-researcher agent to find every call site of PaymentService.createCharge.
Return file:line, the caller's purpose, and the path from the public entry point.
Do not edit files. Stop after covering this symbol and its direct callers.

Prüfe nach der Ausführung vier Punkte:

1. Das Haupttranskript enthält eine Delegationszeile für repo-researcher; der Hauptagent hat die Suche nicht unbemerkt selbst ausgeführt.
2. Der Subagent liefert Dateipfade und Zeilennummern und trennt direkte Belege von Schlussfolgerungen.
3. Der Arbeitsbaum ist unverändert:

git status --short

4. Der Hauptagent, nicht der Recherche-Agent, übernimmt die spätere Entscheidung und sämtliche Codeänderungen.

Soll die Recherche dauerhaft aufbewahrt werden, prüfe sie zuerst im Hauptdialog. Anschließend kann der Hauptagent das akzeptierte Ergebnis in der Projektdokumentation oder in einem Issue speichern. Gib dem Recherche-Agenten nicht allein zum Speichern Schreibrechte.

Schritt 5: Das tatsächlich ausgeführte Modell verifizieren

1. Agentendefinition prüfen – aber dort nicht aufhören

Bestätige, dass .claude/agents/repo-researcher.md die gewünschte vollständige ID enthält. Das beweist nur die statische Konfiguration. Ein Modell für den einzelnen Aufruf, eine Organisationsrichtlinie oder eine Gateway-Zuordnung kann den Request dennoch verändern.

2. Während der Ausführung /tasks prüfen

Führe aus:

/tasks

Ab Claude Code v2.1.242 zeigt die Zeile des Subagenten das Modell. Weicht es von der Datei ab, prüfe, ob:

• Claude bei diesem Aufruf ein anderes Modell übergeben hat;
• CLAUDE_CODE_SUBAGENT_MODEL_FORCE aktiviert ist;
• eine Organisationsrichtlinie availableModels ein erlaubtes Modell ersetzt hat;
• deine Client-Version einer älteren Prioritätsregel folgt.

3. Passenden Request-Datensatz des Anbieters finden

Suche den Request im gleichen Zeitfenster und prüfe dessen tatsächliche Model ID. Das ist bei einem Drittanbieter-Gateway besonders wichtig, weil ein vom Client angezeigter Alias vom Gateway erneut zugeordnet werden kann.

BetterToken stellt Modell, Tokenzahlen, Endbetrag und Status gemeinsam in einem Request-Datensatz dar. Verwende für diesen Workflow ausschließlich die Felder Modell und Status als Verifikation; leite daraus keine unbelegte Ersparnisbehauptung ab. Ordne den Request erst dann dem Subagenten zu, wenn sein Zeitstempel zum Ausführungsfenster passt.

Nutze eine kleine Abnahmetabelle:

Prüfpunkt	Erwarteter Beleg	Bei Abweichung
Agentendatei	Exakte Model ID	ID korrigieren und bei Bedarf neu laden oder neu starten
/tasks	Ziel-Subagent und laufendes Modell	Aufrufeinstellungen, Force-Variablen und Organisationsrichtlinie prüfen
Anbieter-Datensatz	Tatsächliche Model ID und erfolgreicher Status im gleichen Zeitfenster	Katalog, Alias-Zuordnung, Routing und Kontozugriff prüfen
git status --short	Keine unerwarteten Dateiänderungen	Tools einschränken, Änderungen zurücksetzen und Test wiederholen

Vermerke „Modellwechsel verifiziert“ erst, wenn die Modellbelege an den ersten drei Prüfpunkten übereinstimmen. Ein Prompt mit dem Wort Haiku, ein Agentenname in der Oberfläche oder eine abgeschlossene Antwort reichen allein nicht aus.

Fehlerbehebung

Der Agent wird nicht aufgerufen

Prüfe, ob die Datei in .claude/agents/ oder ~/.claude/agents/ liegt, das Frontmatter sowohl name als auch description enthält und das YAML gültig ist. Starte Claude Code neu, wenn dies das erste Agentenverzeichnis ist, das nach Sitzungsbeginn angelegt wurde. Wird es weiterhin nicht geladen, starte Claude Code mit --debug und prüfe den Ladefehler.

/agents zeigt keinen Erstellungsassistenten

Das ist normalerweise erwartet und kein Fehler. Ab v2.1.198 gibt /agents Hinweise zum direkten Bearbeiten der Agentendateien aus. Der interaktive Assistent gehört zu v2.1.197 und älter. Folge der Dokumentation für deine tatsächlich installierte Version und nicht einem älteren Screenshot.

model: haiku beweist Haiku 5.5 nicht

haiku ist ein Alias und keine fest angeheftete Version. Sein Ziel kann sich mit Claude-Code-Version, Anbieter oder Gateway-Zuordnung ändern. Verwende für prüfbares Routing eine vollständige ID aus dem aktuellen Anbieterkatalog und kontrolliere sowohl /tasks als auch den Request-Datensatz des Anbieters.

Das Gateway meldet model not found, 403 oder fällt unbemerkt zurück

Prüfe zuerst, ob die ID im Live-Katalog des Gateways steht und das Konto sie verwenden darf. Enthält der Katalog claude-haiku-5-5 nicht, wiederhole die nicht unterstützte Zeichenfolge nicht ständig. Wähle ein geeignetes gelistetes Modell oder warte, bis das Gateway es aufnimmt. Auch eine Organisations-Allowlist kann bei weiterlaufendem Task ein anderes Modell einsetzen; kontrolliere deshalb die Laufzeitbelege.

Alle Subagenten wurden auf das kleine Modell verschoben

Suche nach CLAUDE_CODE_SUBAGENT_MODEL_FORCE und entferne die Einstellung. Um nur einen Agenten festzulegen, trage die vollständige ID in dessen Frontmatter ein. Um nur die automatische Erkundung zu ändern, überschreibe stattdessen Explore.

Der Recherche-Agent hat Dateien verändert

Ermittle den Umfang mit git status --short und setze unbeabsichtigte Änderungen zurück. Begrenze tools auf Read, Grep, Glob und wiederhole die schreibgeschützte Grenze im System-Prompt. Schreibfähige Tools zu entfernen ist zuverlässiger als nur „nicht bearbeiten“ in einen Prompt zu schreiben.

Minimale Einführung

Beginne mit fünf Schritten:

1. Aktualisiere Claude Code und führe claude --version aus.
2. Kopiere eine tatsächlich verfügbare vollständige Model ID aus dem Katalog deines Anbieters.
3. Lege einen einzelnen repo-researcher an, der auf Read, Grep und Glob begrenzt ist.
4. Starte ihn mit einer Aufgabe, die auf ein Symbol oder Verzeichnis beschränkt ist.
5. Vergleiche /tasks, den Request-Datensatz des Anbieters und git status --short.

Das Ziel besteht nicht darin, jede Aufgabe an das kleinste Modell zu senden. Ziel ist eine überprüfbare Arbeitsteilung: Ein kleines Modell sammelt nachvollziehbare, schreibgeschützte Belege; der Sonnet- oder Opus-Hauptagent verantwortet folgenreiche Entscheidungen und Änderungen. Verifiziere zuerst eine enge Aufgabe und erweitere das Muster nur dort, wo dieselben Abnahmekriterien weiterhin funktionieren.