Wie Claude Code wirklich funktioniert: Die offizielle Architektur

Anthropic hat mit "How Claude Code works" und "Best Practices" zwei ausfuehrliche Dokumentationsseiten veroeffentlicht, die erstmals aus erster Hand erklaeren, was unter der Haube passiert. Waehrend der Source Leak im Maerz unfreiwillige Einblicke lieferte und Victor Dibias Analyse der Agent-Loop-Architektur die Theorie beleuchtete, legt Anthropic jetzt selbst die Karten auf den Tisch.

Dieser Artikel konzentriert sich auf das, was in den bisherigen Radar-Beitraegen nicht behandelt wurde: die offizielle Sicht auf Session-Lifecycle, Kontextfenster-Management als zentrale Designentscheidung und die Scaling-Muster fuer parallele Arbeit.

Die Drei-Phasen-Schleife

Claude Code arbeitet in drei Phasen, die ineinander uebergehen: Kontext sammeln, handeln, Ergebnis pruefen. Das klingt linear, ist es aber nicht. Claude entscheidet nach jedem Schritt, was der naechste erfordert -- basierend auf dem, was es im vorherigen gelernt hat. Dutzende Aktionen koennen sich so verketten, mit Kurskorrektur unterwegs.

Zwei Komponenten treiben die Schleife an: Modelle (die denken) und Tools (die handeln). Claude Code selbst ist der "Agentic Harness" -- die Orchestrierungsschicht, die Werkzeuge, Kontextmanagement und Ausfuehrungsumgebung bereitstellt.

Die Tools fallen in fuenf Kategorien:

Entscheidend: Tools sind nicht nur Helfer, sie sind der Grund fuer Agentic Behavior ueberhaupt. Ohne Tools kann Claude nur Text zurueckgeben. Erst durch Tools wird aus einem Sprachmodell ein handelnder Agent.

Das Kontextfenster als knappe Ressource

Die wichtigste Erkenntnis aus der Best-Practices-Dokumentation ist ungewoehnlich ehrlich formuliert: LLM-Leistung degradiert, wenn der Kontext sich fuellt. Anthropic schreibt das nicht als Fussnote, sondern als zentrales Designprinzip.

Das Kontextfenster enthaelt alles: Nachrichtenverlauf, gelesene Dateien, Kommando-Ausgaben, CLAUDE.md, Auto Memory, geladene Skills und Systemanweisungen. Eine einzige Debugging-Session kann zehntausende Token erzeugen und verbrauchen.

Daraus ergeben sich konkrete Konsequenzen:

Compaction ist automatisch, aber steuerbar. Wenn der Kontext sich fuellt, loescht Claude zuerst aeltere Tool-Ausgaben, dann fasst es die Konversation zusammen. Anfragen und zentrale Code-Snippets bleiben erhalten; detaillierte Anweisungen vom Anfang der Session koennen verloren gehen. Deshalb gehoeren persistente Regeln in die CLAUDE.md, nicht in die Konversation.

/compact mit Fokus. Statt blind zu komprimieren, kann man /compact Focus on the API changes ausfuehren. Oder in der CLAUDE.md einen "Compact Instructions"-Abschnitt definieren, der steuert, was bei der Komprimierung erhalten bleibt.

Sub-Agenten als Kontext-Isolation. Jeder Sub-Agent bekommt ein eigenes, frisches Kontextfenster. Seine Arbeit belastet den Hauptkontext nicht. Wenn er fertig ist, liefert er eine Zusammenfassung zurueck. Anthropic formuliert es pragmatisch: "Subagents are one of the most powerful tools available" -- nicht wegen ihrer Rechenleistung, sondern wegen der Kontext-Isolation.

Sessions: Fortsetzen, Forken, Zurueckspulen

Sessions sind persistent und umkehrbar. Jede Aktion erzeugt einen Checkpoint -- ein Snapshot der betroffenen Dateien vor der Aenderung. Geht etwas schief: zweimal Esc druecken oder /rewind ausfuehren, und Claude stellt einen frueheren Zustand wieder her.

Drei Operationen auf Sessions:

• Resume (claude --continue): Gleiche Session-ID, neue Nachrichten werden angehaengt. Der vollstaendige Konversationsverlauf wird wiederhergestellt, Session-Permissions muessen erneut bestaetigt werden.
• Fork (claude --continue --fork-session): Neue Session-ID, aber der bisherige Konversationsverlauf wird uebernommen. Die Original-Session bleibt unberuehrt. Nuetzlich, um einen alternativen Ansatz zu testen.
• Rewind (Esc+Esc oder /rewind): Stellt Konversation, Code oder beides auf einen frueheren Checkpoint zurueck.

Anthropics Empfehlung zum Umgang mit Sessions:

"Treat sessions like branches: different workstreams can have separate, persistent contexts."

Ein Detail, das leicht uebersehen wird: Wenn dieselbe Session in mehreren Terminals geoeffnet wird, schreiben beide in dieselbe Session-Datei. Nichts geht kaputt, aber die Nachrichten werden vermischt. Fuer parallele Arbeit vom selben Ausgangspunkt: --fork-session verwenden.

Die haeufigsten Fehler

Anthropic benennt fuenf Anti-Patterns explizit:

Kitchen-Sink-Session. Eine Aufgabe anfangen, dann etwas Unzusammenhaengendes fragen, dann zur ersten Aufgabe zurueckkehren. Der Kontext ist voller irrelevanter Informationen. Loesung: /clear zwischen unzusammenhaengenden Aufgaben.

Endlos-Korrekturen. Claude macht etwas falsch, man korrigiert, es ist immer noch falsch, man korrigiert erneut. Der Kontext ist mit fehlgeschlagenen Ansaetzen verschmutzt. Anthropics Faustregel: Nach zwei missglueckten Korrekturen /clear ausfuehren und einen besseren initialen Prompt schreiben, der das Gelernte einbezieht.

Ueberladene CLAUDE.md. Wenn die Datei zu lang ist, ignoriert Claude die Haelfte. Jede Zeile sollte den Test bestehen: "Wuerde Claude ohne diese Anweisung Fehler machen?" Wenn nicht, streichen.

Trust-then-Verify-Luecke. Claude liefert eine plausibel aussehende Implementierung, die Edge Cases nicht abdeckt. Loesung: Immer Verifikation mitliefern -- Tests, Skripte, Screenshots. Was nicht verifiziert werden kann, nicht ausliefern.

Endlose Exploration. Claude soll "etwas untersuchen", ohne Scoping. Es liest hunderte Dateien und fuellt den Kontext. Loesung: Untersuchungen eng scopen oder an Sub-Agenten delegieren.

Scaling: Vom Einzelgespraech zur Parallelarbeit

Fuer Aufgaben, die ueber eine einzelne Session hinausgehen, dokumentiert Anthropic drei Scaling-Muster:

Non-Interactive Mode (claude -p "prompt"): Claude laeuft ohne Session, integrierbar in CI-Pipelines, Pre-Commit-Hooks oder Skripte. Ausgabeformate: Plain Text, JSON oder Streaming JSON.

Fan-Out ueber Dateien: Eine Aufgabenliste generieren, dann per Schleife claude -p fuer jede Datei aufrufen. Mit --allowedTools lassen sich die verfuegbaren Werkzeuge fuer Batch-Operationen einschraenken. Anthropics Empfehlung: erst an 2-3 Dateien testen, den Prompt verfeinern, dann auf den gesamten Bestand skalieren.

Agent Teams: Mehrere Claude-Code-Instanzen arbeiten koordiniert. Eine Session fungiert als Team Lead, Teammates bekommen eigene Kontextfenster. Der Lead verteilt Aufgaben, Teammates bearbeiten und liefern ab, blockierte Aufgaben werden automatisch entsperrt wenn Abhaengigkeiten fertig sind.

Ein weiteres Scaling-Muster ist das Writer/Reviewer-Pattern: Session A implementiert, Session B reviewt mit frischem Kontext (kein Bias gegenueber dem eigenen Code). Oder: Eine Session schreibt Tests, eine andere schreibt den Code der sie bestehen soll.

Einordnung

Drei Dinge fallen an der offiziellen Dokumentation auf.

Erstens die Ehrlichkeit ueber Limitierungen. Anthropic warnt explizit vor Kontextdegradation und benennt Anti-Patterns im eigenen Produkt. Das ist ungewoehnlich fuer Produktdokumentation.

Zweitens die Architektur-Transparenz. Die Unterscheidung zwischen "Agentic Harness" (Claude Code) und Modell (Claude) macht klar, dass Claude Code kein Chat-Wrapper ist, sondern eine eigenstaendige Orchestrierungsschicht mit eigenem Design-Raum.

Drittens die Session-als-Branch-Metapher. Sessions sind nicht Gespraeche, die man fuehrt und vergisst. Sie sind persistente, forkbare, zurueckspulbare Arbeitskontexte. Wer sie wie Git-Branches behandelt -- benennen, forken, bei Bedarf verwerfen -- arbeitet deutlich effektiver.

Fuer alle, die Claude Code taeglich nutzen: Die Best-Practices-Seite ist die nuetzlichste der beiden Quellen. Sie kodifiziert Muster, die viele durch Trial-and-Error selbst entdeckt haben, und benennt die Fehler, die fast jeder am Anfang macht.

Quellen

• How Claude Code works | Anthropic (abgerufen April 2026)
• Best Practices for Claude Code | Anthropic (abgerufen April 2026)
• Inside Claude Code: The Architecture Behind Tools, Memory, Hooks, and MCP | Penligent (abgerufen April 2026)