← Alle Beitrage

Context Engineering ist Architektur: Nach 650 Dateien

10 Min. Lesezeit

Meine CLAUDE.md begann mit 50 Zeilen. Sechs Monate später war sie zu einer verteilten Architektur aus 650 Dateien über sieben Schichten angewachsen. Die Evolution offenbarte, dass Context Engineering nicht Prompt Engineering mit mehr Dateien ist. Es ist Software-Architektur für ein Substrat, bei dem das Gedächtnis mit jedem Token degradiert.

Kontext ist keine Konfigurationsdatei. Er ist das architektonische Substrat, das bestimmt, was ein KI-Agent denken kann, was er sich merkt und was er vergisst. Jede andere Designentscheidung leitet sich vom Kontext ab. Was folgt, sind sechs Monate produktives Context Engineering für Claude Code: die Architektur, die Ausfälle und das System, das sie überlebt hat.

TL;DR

Böckelers Artikel über Context Engineering (martinfowler.com, 2026)1 und Miesslers Framework für klares Denken2 bringen die Diskussion voran, unterschätzen aber beide, was der Produktionseinsatz erfordert. Context Engineering verlangt, ein System zu entwerfen, in dem die richtigen Anweisungen den Agenten zur richtigen Zeit erreichen und die falschen Anweisungen niemals geladen werden. Mein System verwendet neun Regeln, 40 Skills, 19 Agenten, 84 Hooks und 14 Konfigurationsdateien, verteilt über eine Hierarchie mit sieben Schichten. Die Architektur lebt nicht in den Dateien selbst, sondern darin, welche Dateien wann geladen werden und was ausgeschlossen bleibt.

Kontext ist keine Datei

Der wöchentliche „Wie schreibt man eine CLAUDE.md”-Beitrag verfehlt den Kern. Eine gute CLAUDE.md zu schreiben ist notwendig, aber nicht hinreichend – genauso wie guten Code zu schreiben notwendig, aber nicht hinreichend für ein gutes System ist. Architektur ist die Struktur, die bestimmt, wie Komponenten interagieren. In Agentensystemen ist Kontext diese Struktur.

Meine erste CLAUDE.md war ein Monolith: 200 Zeilen mit Coding-Standards, Projektstruktur, Präferenzen, Korrekturen, Philosophie, Zugangsdaten und aktivem Projektstatus. Das funktionierte einen Monat lang. Dann passierten drei Dinge gleichzeitig:

  1. Die Datei wuchs über 300 Zeilen und begann, sich selbst zu widersprechen (Regel A sagte „halte es einfach”, Regel B sagte „füge gründliche Fehlerbehandlung hinzu”)
  2. Kontext von Projekt A sickerte in Projekt B (iOS-spezifische Regeln verschmutzten eine Web-Entwicklungssitzung)
  3. Der Agent verbrauchte Token damit, Anweisungen zu lesen, die für die aktuelle Aufgabe irrelevant waren

Die Symptome weisen auf architektonische Probleme hin, nicht auf Dokumentationsprobleme: Kopplung, Scope-Leakage und Ressourcenverschwendung. Dieselben Kräfte treiben Entscheidungen in der Software-Architektur.3

Die sieben Schichten

Nach sechs Monaten Refactoring hat sich mein Kontextsystem in einer Hierarchie aus sieben Schichten eingependelt. Jede Schicht erfüllt einen bestimmten Zweck und wird zu einem bestimmten Zeitpunkt geladen:

Schicht Inhalte Wann sie lädt Anzahl
1. Kern CLAUDE.md: Philosophie, aktive Projekte, Korrekturen Bei jedem Sitzungsstart Eine Datei, 205 Zeilen
2. Regeln Domänenspezifische Einschränkungen (API-Design, Sicherheit, Testing, Git) Bei jedem Sitzungsstart Neun Dateien
3. Skills Wiederverwendbare Wissensmodule mit Prozeduren und Beispielen Bei Bedarf (aufgerufen oder automatisch durch Hooks aktiviert) 40 Verzeichnisse
4. Agenten Spezialisierte Reviewer-/Generator-Spezifikationen Bei Bedarf (über das Task-Tool) 19 Dateien
5. Hooks Automatische Kontextinjektion bei Lebenszyklus-Ereignissen Ereignisgesteuert (Sitzungsstart, Pre-Commit, Post-Tool) 84 Skripte
6. Konfiguration Numerische Parameter (Schwellenwerte, Budgets, Limits) Referenziert durch Hooks und Skills 14 JSON-Dateien
7. Zustand Live-Tracking (Agenten-Lineage, Konfidenz-Kalibrierung, Kosten) Referenziert durch Hooks 36 Dateien

Die entscheidende Erkenntnis ist die Schichtentrennung. Regeln werden jede Sitzung geladen, weil sie universell gelten. Skills werden bei Bedarf geladen, weil sie domänenspezifisch sind. Hooks feuern bei Ereignissen, weil das Timing wichtig ist. Alle 650 Dateien beim Sitzungsstart zu laden würde das Kontextfenster erschöpfen, bevor der Agent die erste Benutzernachricht gelesen hätte.4

Drei Ausfälle, die die Architektur formten

Ausfall 1: Die monolithische CLAUDE.md

Meine ursprüngliche CLAUDE.md enthielt iOS-Regeln, Web-Regeln, API-Design-Muster, Git-Konventionen, Zugangsdatenverwaltung und philosophische Grundsätze – alles in einer Datei. Der Agent las alles davon in jeder Sitzung, selbst wenn ein Web-Projekt gebaut wurde, das niemals SwiftUI berühren würde.

Die Kosten: Irrelevanter Kontext verbrauchte pro Sitzung etwa 4.000 Token. Über 50 Sitzungen summiert sich das auf 200.000 Token, die für Anweisungen ausgegeben wurden, die der Agent nie nutzte.

Die Lösung: Domänenspezifische Inhalte in rules/-Dateien auslagern. rules/security.md wird jede Sitzung geladen (Sicherheit gilt überall). rules/ios-security.md wird nur geladen, wenn die Sitzung iOS-Projekte betrifft. Der Beitrag zum Kontextfenster-Management dokumentiert die Token-Ökonomie, die diese Entscheidung vorangetrieben hat.

Ausfall 2: Skills, die veraltet waren

Ich erstellte einen fastapi-Skill mit Beispielen aus FastAPI 0.109. Drei Monate später verwendete das Projekt FastAPI 0.115 mit anderen Mustern. Der Skill lehrte stillschweigend veraltete Konventionen. Der Agent produzierte funktionierenden Code, der nicht zur aktuellen Codebasis passte.

Die Kosten: Eine 45-minütige Debugging-Sitzung, um nachzuvollziehen, warum ein neuer Endpunkt ein anderes Dependency-Injection-Muster verwendete als jeder andere Endpunkt. Das Muster stammte aus dem veralteten Skill, nicht aus der Codebasis.

Die Lösung: Skills referenzieren versionierte Dokumentation und enthalten ein „Zuletzt-verifiziert”-Datum. Wichtiger noch: Die Qualitätsschleife verlangt, dass generierter Code den bestehenden Mustern der Codebasis entspricht – eine metakognitive Prüfung, die veraltete Skill-Abweichungen unabhängig vom Skill-Inhalt erkennt.

Ausfall 3: Widersprüchliche Regeln auf verschiedenen Schichten

CLAUDE.md sagte „bevorzuge einfache Lösungen”. Ein Skill sagte „füge gründliche Fehlerbehandlung mit Retry-Logik und Circuit Breakern hinzu”. Beide waren isoliert betrachtet vernünftig. Zusammen produzierten sie inkonsistente Ausgaben (mal minimal, mal überengineert), abhängig davon, welche Anweisung der Agent in einem bestimmten Durchgang stärker gewichtete.

Die Kosten: Unvorhersehbare Ausgabequalität. Derselbe Aufgabentyp produzierte über verschiedene Sitzungen hinweg unterschiedliche Qualitätsniveaus, was das System unzuverlässig machte.

Die Lösung: Eine klare Vorranghierarchie etablieren. CLAUDE.md setzt Prinzipien („bevorzuge Einfachheit”). Regeln setzen Einschränkungen („validiere alle Benutzereingaben”). Skills setzen Prozeduren („so baut man einen FastAPI-Endpunkt”). Bei Konflikten gewinnt die spezifischere Schicht: Die Prozedur eines Skills überschreibt die Anleitung eines Prinzips für die konkrete Aufgabe, die der Skill abdeckt. Die Auflösung spiegelt wider, wie Programmiersprachen Scope handhaben: Lokal überschreibt Global.5

Das Kontextbudget als architektonische Einschränkung

Das Kontextfenster ist nicht unendlich. Claudes 200K-Token-Kontextfenster6 klingt groß, bis Sie messen, was es verbraucht:

Verbraucher Typische Token % des Fensters
System-Prompt + CLAUDE.md + Regeln 8.000–12.000 4–6 %
Gesprächsverlauf 20.000–80.000 10–40 %
Datei-Lesevorgänge (pro Datei) 5.000–20.000 2,5–10 %
Tool-Ausgaben (pro Aufruf) 1.000–10.000 0,5–5 %
Skill-/Agenten-Kontext (bei Bedarf) 3.000–15.000 1,5–7,5 %

Die Token-Verbrauchsmessungen stammen aus 50 Claude-Code-Sitzungen, die ich zwischen August 2025 und Februar 2026 aufgezeichnet habe.7 Eine intensive 90-Minuten-Sitzung kann das Fenster allein durch normale Datei-Lesevorgänge und Tool-Interaktionen erschöpfen. Das Kontextbudget erzwingt architektonische Kompromisse:

Immer laden: Kernphilosophie, aktive Korrekturen und Sicherheitsregeln. Alle drei sind günstig (4–6 % des Budgets) und universell anwendbar.

Bei Bedarf laden: Skills, Agentenspezifikationen und Referenzdokumentation. Jedes Element kostet 5–15 % des Fensters pro Skill und gilt für eine einzelne Domäne. Sie nur bei Relevanz zu laden, bewahrt das Budget für die eigentliche Arbeit.

Nie laden: Veraltete Übergabedokumente, überholte Konfigurationen oder historische Zustände. Jede veraltete Datei verbraucht Budget, ohne die Ausgabe zu verbessern. Das Muster des Compounding Engineering erfordert regelmäßiges Ausmisten von Kontext, der seine Token-Kosten nicht mehr rechtfertigt.

Die Kontextbudgetierung spiegelt den gleichen Kompromiss wider, der Datenbankindizierung, Caching-Strategien und Speicherverwaltung in traditioneller Software antreibt.8 Die Einschränkung unterscheidet sich (Token statt Bytes), aber die architektonische Disziplin ist identisch.

Kontextpropagierung in Multi-Agenten-Systemen

Wenn der Hauptagent über das Task-Tool einen Subagenten startet, bestimmt die Wahl des zu propagierenden Kontexts jede weitere Designentscheidung. Mein Multi-Agenten-Deliberationssystem verwendet 10 Forschungsagenten. Jeder Agent braucht genug Kontext, um unabhängig zu evaluieren, aber zu viel geteilter Kontext verursacht das Konvergenzproblem, das im Boids-Beitrag dokumentiert ist: Agenten, die zu viel Kontext teilen, produzieren identische Schlussfolgerungen.

Die Propagierungsregeln:

Kontexttyp Propagiert? Warum
Kernphilosophie Ja Konsistenz über alle Agenten hinweg
Domänenregeln Ja Gemeinsame Qualitätsstandards
Aufgabenspezifische Anweisungen Ja Die eigentliche Arbeit
Gesprächsverlauf Nein Unabhängigkeit erfordert Isolation
Ergebnisse anderer Agenten Nein (bis zur Synthese) Verhindert vorzeitige Konvergenz
Skill-Prozeduren Selektiv Nur Skills, die für die Rolle des Agenten relevant sind

Die Ralph-Architektur löst ein verwandtes Problem: Kontextpropagierung über die Zeit (Iterationen), nicht über Agenten (parallele Prozesse). Beide teilen dasselbe Prinzip: Einschränkungen und Prinzipien propagieren, Implementierungsdetails isolieren.

Kontextqualität messen

Die Token-Anzahl ist eine Proxy-Metrik. Das wahre Maß für Kontextqualität ist: Produziert der Agent beim ersten Versuch die richtige Ausgabe?

Nach der Auswertung von 50 Sitzungen identifizierte ich drei Qualitätssignale:

Erfolgsrate beim ersten Versuch. Wie oft erfordert die erste Antwort des Agenten keine Korrektur? Mit der monolithischen CLAUDE.md lag die Rate bei etwa 60 %. Nach der Sieben-Schichten-Architektur stieg sie auf ungefähr 80 %. Die Verbesserung kam durch das Entfernen irrelevanten Kontexts (weniger Ablenkung) und das Hinzufügen domänenspezifischer Skills (mehr relevantes Wissen).9

Korrekturtyp. Wenn der Agent doch eine Korrektur benötigt, ist der Fehler faktisch (falsche API, falsches Muster) oder eine Ermessensfrage (falscher Ansatz, falsche Priorität)? Faktische Fehler deuten auf fehlenden Kontext hin. Ermessensfehler deuten auf widersprüchlichen oder mehrdeutigen Kontext hin. Die Nachverfolgung der Korrekturtypen zeigt, welche Schicht Aufmerksamkeit braucht.

Kontextdruck bei Aufgabenabschluss. Wie viel Kontextbudget bleibt übrig, wenn die Aufgabe abgeschlossen ist? Wenn das Fenster zu 90 % voll ist, bevor die Aufgabe zur Hälfte erledigt ist, lädt die Kontextarchitektur zu viel irrelevantes Material. Mein Hooks-System enthält einen Kontextdruckmonitor, der warnt, wenn die Auslastung 70 % überschreitet.

Das Muster der verteilten Architektur

Nichts im Sieben-Schichten-System ist einzigartig für KI-Agenten. Es spiegelt etablierte Software-Muster wider:

Software-Muster Kontext-Äquivalent
Umgebungsvariablen Kern-CLAUDE.md (immer geladen, global)
Konfigurationsdateien Regeln (beim Start geladen, domänenspezifisch)
Bibliotheken/Module Skills (bei Bedarf geladen, eigenständig)
Microservices Agenten (isoliert, kommunizieren über Protokolle)
Event-Handler Hooks (durch Lebenszyklus-Ereignisse ausgelöst)
Datenbank Zustandsdateien (persistent, abfragbar)
API-Verträge Konfigurationsschemata (gemeinsame numerische Parameter)

Die Parallele ist nicht metaphorisch. Dieselben Kräfte (Kopplung, Kohäsion, Scope, Lebenszyklus) treiben identische architektonische Entscheidungen.10 Context Engineering ist Software Engineering für ein Substrat, bei dem „Gedächtnis” eine knappe, degradierbare Ressource ist statt einer reichlich vorhandenen, persistenten.11

Zentrale Erkenntnisse

Für Ingenieure, die Agentensysteme bauen:

  • Entwerfen Sie Kontext wie Software-Architektur, nicht wie Dokumentation. Was wann lädt, was was überschreibt und was an Subagenten propagiert wird, bestimmt das Agentenverhalten mehr als jede einzelne Anweisung. Wenden Sie dieselbe Separation-of-Concerns-Disziplin an, die Sie für Code verwenden.

  • Trennen Sie Schichten nach Lebenszyklus. Universelle Regeln laden jede Sitzung. Domänenspezifisches Wissen lädt bei Bedarf. Sitzungsbezogener Zustand bleibt transient. Die Vermischung von Lebenszyklen in einer Datei erzeugt die Kopplungsprobleme, zu deren Lösung Software-Architektur existiert.

Für Teams, die KI-Workflows skalieren:

  • Behandeln Sie das Kontextfenster als Budget. System-Prompts, Datei-Lesevorgänge und Tool-Ausgaben verbrauchen das 200K-Token-Fenster. Jede persistente Anweisung konkurriert mit dem Arbeitsspeicher. Messen Sie, was Sie laden, und entfernen Sie, was seine Token nicht rechtfertigt.

  • Propagierungsregeln bestimmen die Multi-Agenten-Qualität. Subagenten brauchen gemeinsame Prinzipien für Konsistenz und isolierten Zustand für Unabhängigkeit. Zu viel propagierter Kontext verursacht Konvergenz. Zu wenig propagierter Kontext verursacht Inkohärenz.

Dieser Beitrag baut auf Kontextfenster-Management (Token-Ökonomie) und Das Ralph-System (Dateisystem-Gedächtnis) auf. Das Claude Code Hooks-System implementiert die Automatisierungsschicht. Für Koordinationsmuster bei Agenten siehe Multi-Agenten-Deliberation und Boids zu Agenten.

  1. Birgitta Böckeler, “Context Engineering for Coding Agents,” martinfowler.com, February 2026. martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html. Böckelers Kollegin Bharani Subramaniam definiert Context Engineering als „kuratieren, was das Modell sieht, um ein besseres Ergebnis zu erzielen”. Die Definition ist korrekt. Der vorliegende Beitrag argumentiert, dass die Struktur, wie diese Informationen organisiert und bereitgestellt werden, eine architektonische Disziplin ist und keine Dokumentationsübung. ↩

  2. Daniel Miessler, “How to Talk to AI,” danielmiessler.com, June 2025. danielmiessler.com/blog/how-to-talk-to-ai. Miessler argumentiert, dass die eigentliche Kompetenz hinter Prompt Engineering und Context Engineering klares Denken ist: die Fähigkeit, genau zu artikulieren, was man erreichen möchte. Der Ansatz ergänzt den vorliegenden Beitrag, der sich auf die strukturelle Disziplin der Kontextorganisation konzentriert, nicht auf das klare Denken darüber. ↩

  3. Die Parallele zur Software-Architektur ist beabsichtigt. Robert C. Martin, Clean Architecture: A Craftsman’s Guide to Software Structure and Design, Prentice Hall, 2017. Martin identifiziert dieselben Kräfte: Kopplung, Kohäsion und die Trennung von Zuständigkeiten. Der Unterschied bei KI-Kontextsystemen ist, dass „Gedächtnis” ephemer und begrenzt ist – eine Einschränkung, der traditionelle Architektur nicht begegnet. ↩

  4. Die Zahl von 650 Dateien ist die Messung des Autors vom Stand Februar 2026. Globaler Kontext: ~400 Dateien (Regeln, Skills, Agenten, Hooks, Konfigurationen, Zustand, Dokumentation, Übergaben). Projektspezifischer Kontext (blakecrosley.com): ~250 Dateien (PRDs, Dokumentation, Pläne, Workflows, i18n-Konfigurationen). Nur ein Bruchteil wird pro Sitzung geladen. ↩

  5. Die Variablen-Scope-Auflösung in Programmiersprachen (lokal, umschließend, global, eingebaut) ist die direkte Analogie. Pythons LEGB-Regel definiert dieselbe Hierarchie: lokaler Scope, umschließender Funktions-Scope, globaler Scope, eingebauter Scope. Siehe Python Software Foundation, „Execution Model”, Abschnitt 4.2.2, „Resolution of names.” docs.python.org/3/reference/executionmodel.html. Skills (lokaler Scope) überschreiben Regeln (Modul-Scope), die wiederum CLAUDE.md (globaler Scope) überschreiben. Die Analogie bricht leicht zusammen, da die Anweisungsbefolgung von LLMs probabilistisch und nicht deterministisch ist, aber das architektonische Prinzip gilt. ↩

  6. Anthropic, „Models overview,” platform.claude.com, 2025. platform.claude.com/docs/en/docs/about-claude/models. Alle aktuellen Claude-Modelle (Opus 4.6, Sonnet 4.6, Haiku 4.5) spezifizieren ein 200K-Token-Kontextfenster, wobei Opus 4.6 und Sonnet 4.6 in der Beta 1M Token unterstützen. ↩

  7. Token-Verbrauchsmessungen aus 50 Claude-Code-Sitzungen, die ich zwischen August 2025 und Februar 2026 aufgezeichnet habe. Siehe Kontextfenster-Management für die vollständige Methodik. ↩

  8. Die Analogie zwischen Token-Budgets und Speicherhierarchien folgt dem Framework in Hennessy, J.L. und Patterson, D.A., Computer Architecture: A Quantitative Approach, 6. Auflage, Morgan Kaufmann, 2017. Hennessy und Pattersons Behandlung von Cache-Hierarchien, Zugriffslokalität und den Kosten des Speicherzugriffs auf verschiedenen Ebenen bildet sich direkt auf Context Engineering ab: häufig benötigter Kontext (L1-Cache / Kernregeln) lädt am schnellsten, während selten benötigter Kontext (Festplatte / On-Demand-Skills) nur bei Referenzierung lädt. ↩

  9. Die Erfolgsrate beim ersten Versuch ist eine grobe Metrik, die auf der subjektiven Einschätzung des Autors basiert, ob die erste Antwort eine Korrektur erforderte. Es handelt sich nicht um ein kontrolliertes Experiment. Die richtungsweisende Verbesserung (60 % auf 80 %) ist über alle Sitzungstypen hinweg konsistent, sollte aber nicht als präzise Messung zitiert werden. ↩

  10. James Lewis und Martin Fowler, „Microservices,” martinfowler.com, März 2014. martinfowler.com/articles/microservices.html. Lewis und Fowler definieren Microservices als „eine Suite kleiner Dienste, die jeweils in ihrem eigenen Prozess laufen und über leichtgewichtige Mechanismen kommunizieren”. Die von ihnen identifizierten Kräfte (unabhängiges Deployment, dezentrale Governance, begrenzte Kontexte) bilden sich direkt auf die Agentenisolation und protokollbasierte Kommunikation in der hier beschriebenen Kontextarchitektur ab. ↩

  11. Das „Kontext als Architektur”-Framing bezieht sich auf Xu et al., „Everything is Context: Agentic File System Abstraction for Context Engineering,” arXiv, Dezember 2025. arxiv.org/abs/2512.05470. Das Paper schlägt eine Dateisystem-Abstraktion für die Verwaltung von Kontext in generativen KI-Systemen vor, die diverse Wissensartefakte, Gedächtnis und Tools als Kontext innerhalb von Token-Beschränkungen behandelt. Das theoretische Framework unterstützt die hier beschriebene praktische Architektur. ↩