Lassen Sie uns das Harness für Claude Code bauen (Schritt für Schritt)

Wir behandeln alles, was in den Bau eines Coding-Harness einfließt: die Agenten-Schleife, Planung, Unteragenten, Sandboxing, Speicher und Checkpointing – Schritt für Schritt aufgebaut.

Wenn du schon einmal versucht hast, deinen eigenen Coding-Agenten zu bauen, weißt du, wie das läuft. Du verbindest ein Modell mit Datei-Tools und einer Shell, richtest es auf eine echte Codebasis und es bricht innerhalb weniger Tool-Aufrufe zusammen.

Es liest die falschen Dateien, verliert das Ziel auf halbem Weg und füllt seinen Kontext mit Ausgaben, die es nicht mehr braucht.

Dann geht die gleiche Aufgabe durch Claude Code und wird sauber abgeschlossen. Der naheliegende Schluss ist, dass Anthropic einfach ein besseres Modell hat – und dieser Schluss übersieht, wo die eigentliche Arbeit stattfindet.

Der Unterschied liegt im Harness. Ein Harness ist der gewöhnliche Code, der um das Modell herum geschrieben wird, und er kümmert sich um Planung, Tool-Ausführung, Speicher und Sicherheit, während das Modell nur den nächsten Schritt entscheidet.

So sieht ein voll ausgestatteter Agent aus, wenn man ihn aufzeichnet:

GIF

Das Bild sieht komplex aus, lässt sich aber in vier Gruppen unterteilen:

• Speicher versorgt das Modell mit seinem Arbeitskontext sowie Fakten, die es über Sitzungen hinweg gelernt hat.
• Fähigkeiten kodieren, wie der Agent arbeiten soll – also die Verfahren, Einschränkungen und Heuristiken, denen er folgt.
• Protokolle verbinden den Agenten mit Benutzern, Tools und anderen Agenten.
• Der Harness-Kern verbindet alles miteinander mit Unteragenten-Orchestrierung, einer Sandbox, einem Evaluator, einem Genehmigungsablauf, Beobachtbarkeit und Kontextkompression.

Anthropic beschreibt diese Aufteilung als Gehirn und Hände. Das Modell ist das Gehirn, das jede Aktion auswählt, und der Harness sind die Hände, die sie ausführen und den Lauf auf Kurs halten.

Der Unterschied zwischen deinem Agenten und Claude Code liegt also nicht im Modell, sondern in der Maschinerie um das Modell herum.

Claude Code ist einer der leistungsfähigsten Harnesses, die derzeit im Einsatz sind, und er besteht aus einer überraschend kleinen Anzahl der Schichten in dieser Abbildung. Um zu sehen, wie viel dieser Maschinerie du selbst bauen müsstest, habe ich ihn in CrewAI nachgebaut, einem Open-Source-Framework zur Orchestrierung von Agenten.

Mehr davon ließ sich auf integrierte Funktionen abbilden, als ich erwartet hatte, und der Teil, der das nicht tut, ist der Ort, an dem die eigentliche Ingenieursarbeit steckt.

Lass es uns Schicht für Schicht aufbauen, beginnend mit der Kernschleife und dann Planung, Unteragenten, Sandboxing und Speicher darauf stapeln. Bei jedem Schritt markieren wir, wo das Framework aufhört und wo deine Aufgabe beginnt.

Wie Claude Codes Harness funktioniert

Im Zentrum von Claude Code steht eine einfache Agenten-Schleife. Du sendest eine Nachricht, das Modell entscheidet, was als Nächstes zu tun ist, und es antwortet entweder direkt oder fordert ein Tool an. Wenn es eines anfordert, wird das Tool ausgeführt, das Ergebnis fließt zurück in das Gespräch, und das Modell entscheidet erneut.

Dies wiederholt sich, bis das Modell eine endgültige Antwort ohne weitere Tool-Aufrufe zurückgibt.

Innerhalb dieser Schleife liest das Modell Dateien, bearbeitet Code, führt Shell-Befehle aus und führt Tests durch. Das sind keine separaten Modi. Es sind einfach verschiedene Tool-Aufrufe innerhalb derselben Schleife.

Die Schleife allein reicht jedoch nicht für einen zuverlässigen Coding-Agenten. Claude Code fügt Planung, Datei-Tools, Unteragenten, Speicher sowie ein Berechtigungs- und Sandbox-System hinzu. Diese Schichten ersetzen die Schleife nicht, sondern machen sie sicher und zuverlässig genug für echte Arbeit.

Das ist die Architektur, die wir nachbauen werden: zuerst die Kernschleife, dann jede Schicht darüber, wobei wir jede Schicht auf die CrewAI-Funktion abbilden, die sie behandelt.

Die Kern-Agenten-Schleife

Die Schleife führt die gleiche Sequenz aus, bis die Aufgabe erledigt ist:

1. Das Modell wird aufgefordert, die Aufgabe auszuführen.
2. Das Modell antwortet direkt oder fordert ein oder mehrere Tools an.
3. Werden Tools angefordert, führe sie aus und gib die Ergebnisse an das Modell zurück.
4. Wiederhole mit dem aktualisierten Gespräch.
5. Wenn das Modell antwortet, ohne Tools anzufordern, ist die Aufgabe abgeschlossen.

1while True:
2    reply = model(messages, tools)
3    calls = [b for b in reply if b.type == "tool_use"]
4    if not calls:            # plain text, no tool call: the job is done
5        return reply.text
6    messages += [reply, run_all(calls)]

Jeder Tool-Aufruf schließt einen Schritt ab, gibt dem Modell neue Informationen und fließt in die nächste Entscheidung ein. Eine einfache Frage könnte in einer Iteration erledigt sein, während die Behebung eines komplexen Fehlers oder die Umstrukturierung einer großen Codebasis Dutzende von Iterationen dauern kann, bevor das Modell genug Informationen hat, um eine endgültige Antwort zu geben.

CrewAI stellt diese Ausführungsschleife automatisch zur Verfügung, sobald du einen Agenten erstellst. Du implementierst die while-Schleife nicht selbst, sondern definierst den Agenten und weist ihm eine Aufgabe zu.

Den ersten Agenten erstellen

Erstellen wir einen einfachen Bug-Fixer-Agenten.

1from crewai import LLM, Agent, Crew, Task
2
3bug_fixer = Agent(
4    role="Bug Fixer",
5    goal="Find and describe the fix for the reported bug in the codebase.",
6    backstory="You read directories and files to build an accurate picture of the code.",
7    llm="claude-sonnet-4-6",
8)
9
10task = Task(
11    description="Find the fix for {objective}.",
12    expected_output="A short description of the fix and which file it belongs in.",
13)
14
15result = Crew(agents=[bug_fixer], tasks=[task]).kickoff(
16    inputs={"objective": "the overdraft bug in account.py"}
17)

Drei Konzepte sind hier zu verstehen:

• Ein Agent definiert, wer die Arbeit erledigt, durch seine Rolle, sein Ziel, sein LLM und seine Tools.
• Eine Aufgabe beschreibt den Auftrag.
• Ein Crew bringt Agenten und Aufgaben zusammen. Der Aufruf von kickoff() führt die gleiche Ausführungsschleife aus, die oben beschrieben wurde, unabhängig davon, ob das zugrunde liegende Modell von Anthropic, OpenAI, Google oder einem anderen Anbieter stammt.

Dem Agenten Werkzeuge geben

Werkzeuge sind das, was ein Modell, das nur Text generiert, tatsächlich an einer Codebasis arbeiten lässt. Sie lesen Dateien, schreiben sie, führen Shell-Befehle aus und rufen externe APIs auf.

CrewAI bringt Dateisystem-Tools direkt mit:

• FileReadTool liest Dateien.
• DirectoryReadTool listet Verzeichnisse auf.
• FileWriterTool schreibt Dateien.

1from crewai_tools import DirectoryReadTool, FileReadTool, FileWriterTool
2
3read_file = FileReadTool()
4write_file = FileWriterTool()
5list_dir = DirectoryReadTool()
6
7filesystem_tools = [read_file, write_file, list_dir]

Diese dienen auch als externer Speicher. Anstatt ein großes Suchergebnis im Kontextfenster des Modells zu halten, kann der Agent es in eine Datei schreiben, nur den Dateinamen behalten und es bei Bedarf zurücklesen.

Das hält das Kontextfenster kleiner und das Modell fokussierter – das nennt Anthropic Kontext-Engineering.

Integrierte Tools decken nur gängige Workflows ab. Für alles Spezifischere exponierst du eine Python-Funktion als Tool mit dem @tool-Dekorator.

Der Docstring fungiert als Bedienungsanleitung und sagt dem Modell, was das Tool tut, wann es verwendet werden soll und welche Eingaben es erwartet.

1from crewai.tools import tool
2import subprocess
3
4@tool("run_tests")
5def run_tests(path: str = "tests/") -> str:
6    """Run the pytest suite at the given path and return the result."""
7    result = subprocess.run(
8        ["pytest", path, "-q"], capture_output=True, text=True, timeout=120
9    )
10    output = result.stdout + result.stderr
11    return output[-4000:] if len(output) > 4000 else output

Planung von langlaufenden Aufgaben

Wenn Aufgaben komplexer werden, verliert eine einfache Ausführungsschleife allmählich das ursprüngliche Ziel aus den Augen. Nach genügend Tool-Aufrufen, Dateilesungen und Zwischenergebnissen füllt sich der Kontext und das Ziel wird von allem, was danach kam, verdrängt.

Diese langsame Verschlechterung wird als Kontextverfall bezeichnet.

Die Planung geht direkt dagegen vor. Der Agent erstellt einen schrittweisen Plan, bevor er mit der Arbeit beginnt, und behält diesen Plan während der gesamten Ausführung im Kontext.

Der Plan erledigt nicht die Arbeit. Er ist eine Roadmap, die das Modell mit dem ursprünglichen Ziel verbindet – dieselbe Aufgabe, die Claude Codes To-Do-Liste erfüllt.

CrewAI fügt dies auf Crew-Ebene mit planning=True hinzu. Es wird vor der Ausführung ein Plan generiert und während des Aufgabenfortschritts verfügbar gehalten.

1from crewai import Crew, LLM
2
3crew = Crew(
4    agents=self.agents,
5    tasks=self.tasks,
6    planning=True,
7    planning_llm=LLM(model="gpt-4o-mini"),
8)

Hinweis: Standardmäßig verwendet CrewAI gpt-4o-mini für die Planung; du kannst für diesen Schritt jedes beliebige LLM austauschen.

Einzelne Agenten können auch mit reasoning=True über ihre eigene Arbeit nachdenken:

1from crewai import Agent
2
3bug_fixer = Agent(
4    role="Bug Fixer",
5    goal="Find and describe the fix for the reported bug in the codebase.",
6    backstory="You read directories and files to build an accurate picture of the code.",
7    tools=[FileReadTool()],
8    reasoning=True,
9    max_reasoning_attempts=3  # Optional: Maximale Anzahl von Reasoning-Versuchen festlegen
10)

Planung und Reasoning lösen unterschiedliche Probleme. Planung erstellt eine übergeordnete Roadmap für die Gesamtaufgabe, während Reasoning einem einzelnen Agenten Zeit gibt, seinen eigenen Ansatz durchzudenken, bevor er handelt.

Wenn Reasoning aktiviert ist, tut der Agent Folgendes:

1. Er reflektiert die Aufgabe und entwirft einen Ausführungsplan.
2. Er bewertet, ob der Plan bereit ist.
3. Er verfeinert den Plan bei Bedarf, bis er zufrieden ist oder die maximale Anzahl von Reasoning-Versuchen erreicht ist.
4. Er fügt den finalisierten Reasoning-Plan vor der Ausführung in die Aufgabe ein.

Zusammen halten sie den Agenten bei langlaufenden Aufgaben auf Kurs und verringern die Abweichung vom ursprünglichen Ziel.

Delegieren mit Unteragenten

Planung hält den Agenten fokussiert, reduziert aber nicht die Informationsmenge, die das Modell behalten muss. Bei einer großen Codebasis kann selbst eine gut geplante Aufgabe ein einzelnes Kontextfenster sprengen.

Das Auffinden eines Fehlers kann das Lesen Dutzender Dateien erfordern, und der Hauptagent muss nicht alle davon im Speicher behalten.

Unteragenten lösen dies durch Delegation. Der Hauptagent übergibt eine bestimmte Aufgabe an einen Hilfsagenten, der in seinem eigenen Kontext arbeitet und eine kurze Zusammenfassung zurückgibt. Der Hauptagent sieht das Ergebnis, nicht die Zwischenschritte.

CrewAI unterstützt dies durch hierarchische Workflows, bei denen ein Manager-Agent an spezialisierte Agenten delegiert und deren Ergebnisse kombiniert.

In unserem vorherigen Setup hat ein einzelner Bug-Fixer-Agent die ganze Arbeit erledigt. Teilen wir die Arbeit auf einen Manager und drei Spezialisten auf:

• Codebase Explorer erkundet den Code und kartiert das Repository.
• Software Engineer implementiert die gewünschte Änderung.
• Test Runner führt die Tests in der Sandbox aus und meldet Bestehen oder Nichtbestehen.
• Engineering Lead beaufsichtigt die drei Spezialisten.

1from crewai import Crew, Agent, Task, Process
2
3explorer = Agent(
4    role="Codebase Explorer",
5    goal="Map the repository and surface the files relevant to the task.",
6    backstory="You read directories and files to build a picture of the code.",
7    tools=[read_file, list_dir],
8    llm=llm,
9)  # Gleiches für die anderen beiden Spezialisten-Agenten
10
11manager = Agent(
12    role="Engineering Lead",
13    goal="Break the request into steps and delegate each to the right specialist.",
14    backstory="You decide who does what, review tests, finish once change is done.",
15    llm=llm,
16    allow_delegation=True,
17)
18
19crew = Crew(
20    agents=[explorer, coder, tester],
21    tasks=[task],
22    manager_agent=manager,
23    process=Process.hierarchical,
24)

Beachte, dass allow_delegation standardmäßig deaktiviert ist, also muss es beim Manager explizit aktiviert werden.

Sandboxing: Agentenausführung sichern

Ein Agent mit Shell-Zugriff kann einen destruktiven Befehl ausführen, und dem Modell zu sagen, es solle etwas nicht tun, ist keine Sicherheitsmaßnahme.

Echter Schutz kommt von zwei Schichten:

1. Ein Berechtigungssystem, das für sensible Aktionen eine Genehmigung erfordert.
2. Eine Sandbox, die die Ausführung isoliert, sodass selbst genehmigte Befehle das Host-System nicht berühren können.

Anthropic verwendet denselben Ansatz. Die Verlagerung der Codeausführung in eine Sandbox reduziert, wie oft ein Benutzer Aktionen genehmigen muss, während das Host-System weiterhin geschützt bleibt.

Sandboxing in CrewAI

Das Ausführen von Code in einer Sandbox anstatt auf dem Host-Rechner wendet diese zweite Schicht an. In diesem Setup läuft Code innerhalb von E2B, das pro Sitzung eine frische VM startet und sie danach zerstört.

Shell-Befehle und Python laufen vollständig in dieser isolierten Umgebung.

1from crewai_tools import E2BExecTool, E2BPythonTool
2sandbox_tools = [E2BExecTool(), E2BPythonTool()]  # run tests / run code

Human-in-the-Loop-Genehmigung

Das Setzen von human_input=True bei einer Aufgabe pausiert die Crew, nachdem sie eine Antwort generiert hat. Du überprüfst die Ausgabe und genehmigst sie oder sendest sie für eine weitere Iteration zurück.

Wenn die Ausführung diese Aufgabe erreicht, wartet CrewAI über die Standardeingabe auf dein Feedback.

1from crewai import Task
2
3task = Task(
4    description=(
5        "In the working directory ./workspace, {objective}. "
6        "Explore the code first, make the change, then run the tests and report."
7    ),
8    expected_output="A summary of the files changed and the final test output.",
9    human_input=True,
10)

Wenn deine Crew hinter einer Web-App oder einer Chat-Oberfläche statt einem Terminal läuft, übernimmt das webhook-basierte Human-in-the-Loop-System von CrewAI denselben Überprüfungsschritt.

Speicher und Checkpointing

Standardmäßig vergisst ein Agent alles, sobald ein Durchlauf endet. Kommst du morgen zurück, um einen weiteren Fehler im selben Projekt zu beheben, fängt er bei null an.

Zwei Mechanismen ermöglichen es einem Agenten, Informationen über Durchläufe hinweg zu tragen, und jeder dient einem anderen Zweck:

• Checkpointing speichert den Zustand des Agenten während eines Durchlaufs, sodass er nach einer Unterbrechung fortgesetzt oder vom selben Punkt aus einem anderen Pfad folgen kann.
• Persistenter Speicher speichert Fakten über separate Gespräche hinweg, einschließlich Projektpräferenzen wie „formatiere den endgültigen Code immer, bevor du fertig bist."

Speicher in CrewAI

CrewAI bietet ein einheitliches Memory-Interface anstelle separater Kurzzeit-, Langzeit-, Entitäts- und externe Speichertypen. Beim Speichern verwendet es ein LLM, um wichtige Details zu identifizieren, zu organisieren und später abrufbar zu machen.

Das Setzen von memory=True bei der Crew gibt ihr einen Speicher über Durchläufe hinweg. Nach jeder Aufgabe extrahiert CrewAI nützliche Fakten aus der Ausgabe und speichert sie; in zukünftigen Durchläufen ruft es relevante Erinnerungen ab und fügt sie dem Aufgaben-Prompt hinzu.

1from crewai import Crew
2
3crew = Crew(
4    agents=[explorer, coder, tester],
5    tasks=[task],
6    memory=True,
7)

Alle Agenten in einer Crew teilen sich ihren Speicher, es sei denn, einem Agenten wird ein eigener zugewiesen.

Checkpointing in CrewAI

Ein Checkpoint ist ein Schnappschuss des Fortschritts eines Agenten, einschließlich seiner Konfiguration, des Aufgabenstatus, des Speichers, der Zwischenergebnisse, der Eingaben und des Ausführungsverlaufs.

Standardmäßig erstellt CrewAI einen Checkpoint, sobald eine Aufgabe abgeschlossen ist, sodass der Workflow bei einer Unterbrechung von diesem Punkt aus fortgesetzt werden kann.

Checkpoints können in einem von zwei integrierten Speichern leben:

• JsonProvider speichert jeden Checkpoint als separate JSON-Datei, die einfach zu lesen und manuell zu überprüfen ist.
• SqliteProvider speichert alle Checkpoints in einer einzigen SQLite-Datenbank, die bei häufigem Checkpointing und größeren Workloads besser funktioniert.

1from crewai import Crew
2
3crew = Crew(
4    agents=[explorer, coder, tester],
5    tasks=[task],
6    checkpoint=True,
7)

Crew, Flow und Agent akzeptieren alle ein checkpoint-Argument, und Kinder erben von ihrem Elternteil, es sei denn, sie setzen einen eigenen Wert.

Alles zusammenfügen

Hier ist der vollständige Harness für eine Aufgabe, bei dem die Ausführungsschleife, Tools, Planung, Unteragenten, Sandboxing und Speicher zusammenarbeiten:

1from crewai import Agent, Crew, LLM, Process, Task
2from crewai.tools import tool
3from crewai_tools import (DirectoryReadTool, FileReadTool, FileWriterTool,
4E2BExecTool, E2BPythonTool)
5
6llm = LLM(model="anthropic/claude-sonnet-4.6")
7
8list_dir = DirectoryReadTool(directory="./workspace")
9filesystem_tools = [FileReadTool(), FileWriterTool(), list_dir]
10sandbox_tools = [exec_tool, E2BPythonTool()]
11
12@tool("run_tests")
13def run_tests(path: str = "tests/") -> str:
14    """Sync ./workspace into the sandbox, then run pytest there."""
15    return E2BExecTool().run(command=sync_and_test_command(path))
16
17explorer = Agent(role="Codebase Explorer", goal="Map repo, surface relevant files.",
18    tools=[read_file, list_dir], llm=llm)
19coder = Agent(role="Software Engineer", goal="Implement requested change.",
20    tools=filesystem_tools, reasoning=True, llm=llm)
21tester = Agent(role="Test Runner", goal="Run tests in sandbox, report pass/fail.",
22    tools=sandbox_tools + [read_file] + [run_tests], llm=llm)
23manager = Agent(role="Engineering Lead", goal="Delegate steps, finish once tests pass.",
24    allow_delegation=True, llm=llm)
25
26task = Task(
27    description="In ./workspace, {objective}. Explore, edit, test, report.",
28    expected_output="Summary of changes and test output.", human_input=True,
29)
30crew = Crew(
31    agents=[explorer, coder, tester], tasks=[task],
32    manager_agent=manager, process=Process.hierarchical,
33    planning=True, memory=True, checkpoint=True,
34)
35result = crew.kickoff(inputs={"objective": "fix failing tests in account.py"})

Agenten-Harnesses lassen sich am einfachsten evaluieren, wenn der Erfolg automatisch überprüft werden kann. Eine Testsuite gibt dem Agenten ein konkretes Ziel, sodass er planen, bearbeiten, testen und wiederholen kann, bis alles bestanden ist.

Das wurde also gegen eine kleine Codebasis getestet, eine BankAccount-Klasse mit zwei echten Fehlern und fünf Tests, von denen drei fehlschlugen. Die Regel war, nur die Implementierung zu korrigieren, nicht die Tests.

Dies spiegelt wider, wie Anthropic Coding-Agenten intern evaluiert. Ein veröffentlichtes Beispiel zeigt, wie Claude eine Kopie der claude.ai-Oberfläche gegen eine große Suite fehlschlagender Tests neu aufbaut.

Hier brachte der Harness das Projekt von 3 fehlschlagenden und 2 bestandenen auf alle 5 bestandenen Tests, wobei die Regel „nur Implementierung" die Abkürzung verhinderte, die fehlschlagenden Tests zu bearbeiten oder zu entfernen.

Was bleibt deine Aufgabe

Einige Teile des Systems baut das Framework nicht für dich:

• Die Prompts. Das Verhalten jedes Agenten ergibt sich aus seiner Rolle, seinem Ziel und seiner Hintergrundgeschichte. Diese richtig hinzubekommen, erfordert Tests und Iteration – kein Konfigurationsflag ersetzt das.
• Die Ausführungsumgebung. Die Sandbox, ob E2B oder eine selbstverwaltete VM, muss eingerichtet und angebunden werden.
• Die Tool-Auswahl. Welche Tools jeder Agent bekommt und welcher Agent Zugriff auf was haben sollte, ist eine Designentscheidung, die das Framework nicht trifft.

Es gibt auch Kosten für den Harness selbst. Planung, Unteragenten und Schleifen verursachen zusätzliche API-Aufrufe, sodass ein komplexes Agenten-Setup am Ende teurer sein kann als eine Aufgabe, die ein einzelner Modell-Aufruf direkt gelöst hätte.

Und es gibt eine langfristige Einschränkung, die man im Hinterkopf behalten sollte. Mit verbesserten Modellen wird ein Teil des Gerüsts überflüssig, weil manches, was heute in einen Harness eingebaut wird, eher eine Problemumgehung für heutige Modellgrenzen ist als eine dauerhafte Anforderung.

Anthropic verwendete ursprünglich Kontext-Resets, um Claude Sonnet 4.5 davon abzuhalten, Aufgaben zu früh zu beenden – und mit dem leistungsfähigeren Claude Opus 4.5 waren sie nicht mehr nötig.

Zusammenfassung

Das ist die ganze Erkenntnis. Die Leistungsfähigkeit eines Coding-Agenten steckt größtenteils im Harness, und ein Orchestrierungs-Framework gibt dir mehr von diesem Harness in die Hand, als du denkst.

Die Schleife, Planung, Delegation, Sandboxing und Speicher sind alle als Konfiguration verfügbar, während die Prompts, die Ausführungsumgebung und die Tool-Auswahl deine Aufgabe bleiben.

Wenn du das gegen deine eigene Codebasis ausführen möchtest, decken die CrewAI-Dokumentation alle hier verwendeten Funktionen ab, und das Framework ist vollständig Open Source.

CrewAI-Dokumentation ansehen →

Den gesamten Code hier finden →

Danke fürs Lesen!

Viele Grüße! :)