how-claude-code-works: Architekturanalyse eines Coding-Agenten als Leseprojekt

Ein Dokumentationsprojekt über eine Codebasis, die niemand am Stück lesen kann

Die Ausgangslage beschreibt das README offen: Ein Snapshot von rund 500.000 Zeilen TypeScript war in der Community verfügbar, und die Autoren standen vor der Frage, wo man bei dieser Menge überhaupt anfängt. Ihre Antwort war, Claude Code selbst als Lesehilfe einzusetzen und den Prozess zu dokumentieren. Genau daraus ist dieses Repository entstanden. Es ist damit kein Werkzeug und keine Bibliothek, sondern eine Textsammlung über ein anderes System. Wer eine Abhängigkeit in sein Projekt einbauen will, findet hier nichts zum Einbauen. Wer verstehen will, wie ein produktionsnaher Coding-Agent aufgebaut sein könnte, findet 21 Kapitel, die jeweils einen Ausschnitt behandeln.

Die Zielgruppe benennt das README selbst: Entwickler, die einen eigenen Agenten bauen wollen, und Anwender, die Claude Code besser verstehen möchten. Die Lizenz ist MIT, was für eine Textsammlung vor allem bedeutet, dass man Passagen übernehmen darf. Der Quellcode von Claude Code steht nicht unter dieser Lizenz und wird laut Disclaimer auch nicht weitergegeben.

Der Disclaimer ist die wichtigste Zeile des Repositories

Über dem eigentlichen Inhalt steht eine Erklärung, die man beim Bewerten mitlesen muss: Alle Inhalte seien unabhängige Forschung und Schlussfolgerung, sie repräsentierten nicht Anthropics offizielles Design und es werde nicht garantiert, dass sie mit der realen internen Implementierung übereinstimmen. Das ist keine Formalie. Es verschiebt den Status jeder einzelnen Aussage in den Kapiteln von einer Beschreibung zu einer Rekonstruktion.

Für die Praxis heißt das: Wenn ein Kapitel schreibt, der Startvorgang sei in neun Phasen parallelisiert und auf etwa 235 Millisekunden verdichtet, dann ist das eine Zahl aus einer Analyse, nicht aus einer Messung, die man nachvollziehen könnte. Dasselbe gilt für Angaben wie 23 statische Sicherheitsprüfungen, sieben Continuation-Strategien oder ein Schwellenwert von 100.000 Zeichen, ab dem Tool-Ausgaben auf die Festplatte geschrieben werden. Solche Werte sind als Orientierung brauchbar, als Spezifikation nicht. Wer sie übernimmt, übernimmt eine Interpretation.

Bemerkenswert ist, dass das README diesen Vorbehalt nicht versteckt, sondern an die zweite Stelle setzt. Das unterscheidet das Projekt von Analysen, die ihre Herkunft im Unklaren lassen.

Die dokumentierte Schleife: Anfrage, Werkzeugaufruf, Rückinjektion

Das Architekturdiagramm im README zeigt einen Kreislauf, der in dieser Form in vielen Agenten steckt. Nutzereingaben landen in einer QueryEngine, die die Sitzung verwaltet. Von dort geht es in eine query-Hauptschleife, die die Claude-API aufruft. Die Antwort wird geparst und verzweigt sich: Reiner Text geht in die Streaming-Ausgabe, Werkzeugaufrufe gehen an die Ausführungsschicht. Deren Ergebnisse fließen zurück in die Schleife, und der nächste API-Aufruf beginnt.

Interessanter als der Kreislauf selbst sind die Details, die das README daneben stellt. Erstens die Tool-Pre-Execution: Das System beginnt Werkzeugaufrufe zu parsen und auszuführen, während das Modell noch ausgibt. Die Begründung im Text ist ein Zeitfenster von fünf bis dreißig Sekunden Modellgenerierung, in dem rund eine Sekunde Werkzeuglatenz verschwindet. Zweitens die Nebenläufigkeit: Nur lesende Werkzeuge laufen parallel, schreibende seriell. Drittens die Auslagerung großer Ausgaben. Diese drei Punkte sind konkreter als die Schleifenbeschreibung und auch der Teil, den man in einem eigenen Entwurf tatsächlich nachbauen könnte.

Ein vierter Punkt betrifft die Fehlerbehandlung. Das README beschreibt sieben verschiedene Fortsetzungsstrategien, die jeweils an einer anderen Stelle der Schleife greifen. Der Anspruch dahinter ist, dass behebbare Fehler den Nutzer gar nicht erreichen. Ob das in der Praxis angenehm oder undurchsichtig ist, hängt davon ab, wie viel Diagnose man sehen will. Ein System, das Fehler still auflöst, erschwert es, systematische Probleme zu erkennen.

Vierstufige Kompression und die Frage, was danach noch im Kontext steht

Der Abschnitt zur Kontextverwaltung ist der detaillierteste im README und beschreibt eine Kaskade. Zuerst werden große Blöcke in älteren Nachrichten gekürzt, typischerweise alte Werkzeugausgaben. Danach folgt eine Deduplizierung, die laut Text nahezu keine Kosten verursacht. Die dritte Stufe faltet inaktive Gesprächsabschnitte, ohne den Originalinhalt zu verändern, sodass sie wieder aufklappbar bleiben. Erst als letzte Möglichkeit startet ein Unteragent, der die gesamte Konversation zusammenfasst.

Die Abstufung ist der eigentliche Entwurfsgedanke: Jede Stufe kann genug Platz freigeben, sodass die folgenden nicht ausgeführt werden müssen. Das ist billiger als ein sofortiger Summarisierungsschritt und erhält mehr Originaltext. Der Preis ist Komplexität, denn vier Mechanismen müssen korrekt zusammenspielen, und ein Fehler in der Reihenfolge kann dazu führen, dass Inhalt verloren geht, der noch gebraucht wurde.

Das README nennt eine Gegenmaßnahme: Nach der Kompression werden die zuletzt bearbeiteten fünf Dateien automatisch wiederhergestellt, damit das Modell nicht vergisst, woran es gerade arbeitet. Das ist ein Eingeständnis, dass Kompression Kontext zerstört. Wer einen eigenen Agenten baut, sollte diesen Punkt nicht als Detail behandeln. Die Frage, was nach einer Kompression noch verfügbar ist, entscheidet über die Qualität der nächsten Schritte.

Sicherheit als Schichtenfolge statt als Rückfrage

Die sieben Schichten, die das README auflistet, beginnen bei der Vertrauensfrage für das Arbeitsverzeichnis. Wird ein Projekt nicht als vertrauenswürdig eingestuft, sind dessen eigene Hooks deaktiviert. Damit soll verhindert werden, dass ein fremdes Repository beim bloßen Öffnen Skripte ausführt. Darauf folgen Berechtigungsmodi, regelbasierte allow/deny/ask-Listen und eine Analyse von Shell-Befehlen, die laut Text auf Syntaxbäumen beruht und nicht auf regulären Ausdrücken.

Der Unterschied ist relevant. Eine Regex-Prüfung auf rm -rf sieht nur die Zeichenkette. Eine Syntaxbaumanalyse kann erkennen, wie ein Befehl zusammengesetzt ist, etwa ob Variablen expandiert werden oder ob mehrere Befehle verkettet sind. Das README spricht von 23 statischen Prüfungen, die unter anderem Kommandoinjektion und die Offenlegung von Umgebungsvariablen abdecken sollen. Ob diese Zahl vollständig oder aktuell ist, lässt sich aus dem Material nicht beurteilen.

Erwähnenswert ist die Beschreibung der Bestätigungsstufe: Sie konkurriert mit Hooks und einem Klassifikatormodell, und eine Nutzereingabe hat immer Vorrang. Die 200 Millisekunden Verzögerung dienen laut Text dem Schutz vor versehentlicher Doppelbestätigung. Das ist ein Beispiel für eine Designentscheidung, die sich nur aus dem Nutzungsverhalten erklärt, nicht aus der Sicherheitslogik. Man kann darüber streiten, ob eine solche Verzögerung die richtige Antwort ist. Ein System, das bei jeder gefährlichen Operation auf eine menschliche Entscheidung wartet, wird langsam; eines, das nie fragt, wird gefährlich.

Betrieb ohne Installation: Lesen im Browser oder im Repository

Es gibt keine Installationsanleitung, weil es nichts zu installieren gibt. Der Einstieg läuft über die Dokumentationsseite unter windy3f3f3f3f.github.io/how-claude-code-works oder direkt über die Markdown-Dateien im docs-Verzeichnis. Die Kapitel folgen einer Nummerierung von 01 bis 21 und decken in dieser Reihenfolge unter anderem Übersicht, Agent-Loop, Kontext-Engineering, Tool-System, Code-Editing-Strategie, Hooks, Multi-Agent-Architektur, Memory-System, Skills, Plan-Modus, Berechtigungen, Nutzererfahrung, minimale Komponenten, Observability sowie die nach dem Snapshot ergänzten Kapitel zu Autonomie und Auto-Modus ab.

Für den Einstieg ist die Reihenfolge nicht zwingend. Wer konkret an Kontextverwaltung arbeitet, kann mit Kapitel 03 beginnen und die Übersicht überspringen. Wer einen Agenten von Grund auf bauen will, findet in Kapitel 13 eine Gegenüberstellung von minimaler und produktionsnaher Implementierung, die laut README einen Pfad von 500 Zeilen zu 500.000 Zeilen skizziert. Das ist die einzige Stelle, an der das Repository eine Art Vorgehensempfehlung gibt.

Ein Hinweis zur Sprache: Das README ist überwiegend chinesisch, eine englische Fassung liegt als README_EN.md daneben. Ob alle 21 Kapitel in beiden Sprachen vorliegen, geht aus dem Material nicht hervor.

Die Grenze des Projekts und die Alternative daneben

Die offensichtliche Einschränkung ist, dass nichts hier ausführbar ist. Man kann keine Behauptung nachprüfen, indem man sie startet. Bei einem System, dessen Verhalten von Timing, Nebenläufigkeit und Modellausgaben abhängt, ist das ein erheblicher Unterschied zu einer Bibliothek mit Tests. Die Autoren benennen die Unsicherheit selbst, was die Lektüre ehrlicher macht, aber nichts an der Prüfbarkeit ändert.

Die naheliegende Alternative nennt das README im ersten Absatz: das Schwesterprojekt claude-code-from-scratch, das laut Beschreibung rund 4.300 Zeilen TypeScript und Python in zwei Fassungen umfasst, in 13 Kapiteln schrittweise aufgebaut wird und als Clean-Room-Umsetzung eines von Claude Code inspirierten Agenten gedacht ist. Der Unterschied liegt nicht im Umfang, sondern in der Richtung. Dieses Repository erklärt ein bestehendes System von außen nach innen und bleibt beschreibend. Das Schwesterprojekt konstruiert von innen nach außen und liefert lauffähigen Code, der zwangsläufig einfacher ist als das Original, aber überprüfbar. Wer lernen will, wie etwas funktioniert, liest hier. Wer lernen will, wie man es baut, schreibt dort Code.

Eine zweite Abgrenzung betrifft den Gegenstand selbst. Wer einen Agenten für einen anderen Anbieter oder mit einem anderen Modell baut, kann die beschriebenen Mechanismen übernehmen, aber nicht die Begründungen. Die Kompressionskaskade ist an ein Kontextfenster und an Preise gebunden, die sich ändern können. Die Sicherheitsschichten sind an die Annahme geknüpft, dass das Modell beliebige Shell-Befehle vorschlagen darf. Beides sind Annahmen, die man in einem eigenen Entwurf neu prüfen muss.

Pflegeaufwand, Lizenz und was man vor der Übernahme prüfen sollte

Der Pflegeaufwand liegt beim Lesen, nicht beim Integrieren. Es gibt keine Versionen, keine Abhängigkeiten und keine Upgrades. Das Repository wird laut README laufend erweitert, insbesondere um Kapitel zu Funktionen, die nach dem Quellcode-Snapshot erschienen sind, darunter /goal, /loop und der Auto-Modus. Diese Kapitel sind als Reverse Engineering gekennzeichnet, also als Analyse von außen ohne Quellcode. Ihre Aussagekraft ist damit eine andere als die der Kapitel, die auf dem Snapshot beruhen. Wer zitiert, sollte diesen Unterschied kennen.

Lizenzseitig steht das Projekt unter MIT, was Weitergabe und Bearbeitung der Texte erlaubt. Das betrifft ausdrücklich nur die hier verfassten Inhalte. Der Disclaimer stellt klar, dass kein Quellcode von Anthropic weitergegeben wird und dass Claude Code eine Marke von Anthropic ist. Wer Passagen in eigene Dokumentation übernimmt, übernimmt damit auch die Unsicherheit über die Richtigkeit. Eine Gewährleistung gibt es nicht, und bei einer Rekonstruktion ohne Zugriff auf das Original wäre alles andere auch überraschend.

Vor einer Übernahme einer konkreten Designentscheidung lohnt sich ein Blick in die jeweilige Datei unter docs, etwa 03-context-engineering.md für die Kompressionsstufen oder 11-permission-security.md für die Sicherheitsschichten. Dort steht, ob ein Kapitel einen benannten Mechanismus beschreibt oder eine allgemeine Behauptung aufstellt. Dieser Unterschied ist im README nicht immer erkennbar.

Redaktionelles Fazit

Wer einen eigenen Coding-Agenten plant oder Claude Code bewusst einsetzen will, findet hier die detailliertesten öffentlich zugänglichen Beschreibungen zu Kompression, Tool-Pipeline und Berechtigungsschichten. Wer lauffähigen Code oder eine verifizierte Referenzimplementierung sucht, ist falsch: Das Repository liefert ausschließlich Prosa, und die Autoren räumen selbst ein, dass die Aussagen nicht mit der realen Implementierung übereinstimmen müssen. Vor jeder Übernahme einer Designentscheidung sollte man die betreffende Kapiteldatei im docs-Verzeichnis direkt öffnen und prüfen, ob sie einen konkreten Mechanismus benennt oder nur eine Behauptung aufstellt.

Offizielle Quellen

1. Issues
2. License: MIT
3. Project website
4. README
5. Windy3f3f3f3f/how-claude-code-works on GitHub