Context Engineering ist Architektur: Nach 650 Dateien

Aus dem Leitfaden: Claude Code Comprehensive Guide

Meine CLAUDE.md begann mit 50 Zeilen. Sechs Monate später war sie zu einer verteilten Architektur aus 650 Dateien über sieben Schichten angewachsen. Diese Entwicklung hat gezeigt, dass Context Engineering Software-Architektur für ein Substrat ist, dessen Gedächtnis mit jedem Token nachlässt, und nicht etwa Prompt Engineering mit mehr Dateien.

Kontext bestimmt, was ein KI-Agent denken kann, was er sich merkt und was er vergisst. Jede andere Designentscheidung leitet sich davon ab. Was folgt, sind sechs Monate produktives Context Engineering für Claude Code: die Architektur, die Fehlschläge und das System, das sie überlebt hat.

Context Engineering für KI-Agenten ist die Praxis, Systeme zu entwerfen, die dem Agenten die richtigen Anweisungen zur richtigen Zeit liefern und zugleich sicherstellen, dass irrelevante Anweisungen gar nicht erst geladen werden. Es geht über das Schreiben einer guten Prompt-Datei hinaus: Es verlangt eine geschichtete Architektur, in der Regeln, Skills, Hooks, Konfigurationen und Zustandsdateien jeweils zu bestimmten Lebenszyklus-Ereignissen geladen werden. Was ausgeschlossen bleibt, zählt ebenso viel wie das, was aufgenommen wird, denn jedes irrelevante Token verdrängt Kontext, den der Agent für korrekte Ergebnisse tatsächlich braucht.

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 verlangt. Context Engineering erfordert ein System, 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 aus sieben Schichten. Die Architektur liegt darin, welche Dateien wann geladen werden. Was ausgeschlossen bleibt, zählt ebenso viel wie das, was aufgenommen wird.


Kontext ist keine Datei

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

Was mit 50 Zeilen begann, war zu einem Monolithen angewachsen: Meine erste CLAUDE.md umfasste 200 Zeilen mit Coding-Standards, Projektstruktur, Präferenzen, Korrekturen, Philosophie, Zugangsdaten und dem Status aktiver Projekte. 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 aus Projekt A sickerte in Projekt B (iOS-spezifische Regeln verunreinigten eine Sitzung zur Webentwicklung)
  3. Der Agent verbrauchte Token für Anweisungen, 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 eigenen 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 Spezifikationen für Reviewer und Generatoren 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, Konfidenzkalibrierung, Kosten) Referenziert durch Hooks 36 Dateien

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

Ein konkretes Beispiel für jede Schicht:

Layer 1 (Core):     ~/.claude/CLAUDE.md — philosophy, active projects, corrections
Layer 2 (Rules):    ~/.claude/rules/security.md — "Validate ALL user input at boundaries"
Layer 3 (Skills):   ~/.claude/skills/fastapi/SKILL.md — endpoint patterns, Pydantic models
Layer 4 (Agents):   ~/.claude/agents/security-reviewer.md — OWASP-focused review spec
Layer 5 (Hooks):    ~/.claude/hooks/pre-commit-check.sh — blocks commits with TODO/FIXME
Layer 6 (Config):   ~/.claude/config/thresholds.json — {"max_spawn_children": 12}
Layer 7 (State):    ~/.claude/state/agent-lineage.json — tracks active agent tree

Jede Datei in der Hierarchie hat eine einzige Verantwortung und einen klaren Auslöser für das Laden. Der Hook (Schicht 5) feuert beim Pre-Commit, unabhängig vom Projekttyp. Der Skill (Schicht 3) wird nur geladen, wenn eine FastAPI-Aufgabe beginnt. Diese Unterscheidung bestimmt die Token-Kosten.


Drei Fehlschläge, die die Architektur geformt haben

Fehlschlag 1: Die monolithische CLAUDE.md

Meine ursprüngliche CLAUDE.md enthielt iOS-Regeln, Web-Regeln, Muster für API-Design, Git-Konventionen, die Verwaltung von Zugangsdaten und philosophische Grundsätze, alles in einer Datei. Der Agent las all das in jeder Sitzung, selbst beim Bau eines Webprojekts, das SwiftUI niemals berühren würde.

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

Die Lösung: Domänenspezifische Inhalte in rules/-Dateien auslagern. rules/security.md wird in jeder 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 zu dieser Entscheidung geführt hat.

Fehlschlag 2: Skills, die veralteten

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 alle anderen Endpunkte. Das Muster stammte aus dem veralteten Skill, nicht aus der Codebasis.

Die Lösung: Skills verweisen auf versionierte Dokumentation und tragen ein Datum der letzten Überprüfung („last verified”). Wichtiger noch: Die Qualitätsschleife verlangt, dass generierter Code den bestehenden Mustern der Codebasis entspricht. Diese metakognitive Prüfung erkennt die Abweichung veralteter Skills unabhängig vom Inhalt des Skills.

Fehlschlag 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”. Beides war für sich genommen vernünftig. Zusammen erzeugten sie inkonsistente Ergebnisse (mal minimal, mal überdimensioniert), je nachdem, welche Anweisung der Agent in einem bestimmten Durchgang stärker gewichtete.

Die Kosten: Unvorhersehbare Ausgabequalität. Derselbe Aufgabentyp lieferte über verschiedene Sitzungen hinweg unterschiedliche Qualitätsniveaus, was das System unzuverlässig machte. Hier die tatsächlich widersprüchlichen Anweisungen:

# In CLAUDE.md (Layer 1):
- Prefer simple solutions. Avoid over-engineering.

# In skills/fastapi/SKILL.md (Layer 3):
- Add thorough error handling with retry logic and circuit breakers
  for all external API calls.

Beide sind für sich genommen korrekt. „Bevorzuge einfache Lösungen” ist ein guter allgemeiner Rat. „Füge Retry-Logik für externe Aufrufe hinzu” ist ein guter domänenspezifischer Rat. Ein Agent, der beides liest, lässt jedoch manchmal die Retry-Logik weg (dem Einfachheitsprinzip folgend) und überdimensioniert manchmal eine simple Funktion (der Anweisung zur Fehlerbehandlung folgend).

Die Lösung: Eine klare Vorranghierarchie festlegen. 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 Leitlinie eines Prinzips für die konkrete Aufgabe, die der Skill abdeckt. Diese Auflösung spiegelt wider, wie Programmiersprachen mit Scope umgehen: Lokal überschreibt global.5 Die Lösung für das obige Beispiel: Ergänzen Sie den Skill um einen Zusatz, nämlich „Füge Retry-Logik für externe API-Aufrufe hinzu (dies überschreibt das allgemeine Einfachheitsprinzip für netzwerkabhängigen Code, weil externe Aufrufe sporadisch fehlschlagen und Retries keine Überdimensionierung sind).”


Das Kontextbudget als architektonische Einschränkung

Das Kontextfenster ist nicht unendlich. Claudes standardmäßiges Kontextfenster von 200K Token6 klingt groß, bis Sie messen, was es verbraucht. (Über einen API-Header gibt es eine Beta mit 1M Token, die das Budget proportional vergrößert, die Zielkonflikte aber nicht beseitigt: 650 Dateien zu laden, würde selbst 1M Token erschöpfen.)

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-/Agentenkontext (bei Bedarf) 3.000-15.000 1,5-7,5 %

Die Messungen zum Token-Verbrauch stammen aus 50 Claude-Code-Sitzungen, die ich zwischen August 2025 und Februar 2026 aufgezeichnet habe.7 Eine intensive 90-minütige Sitzung kann das Fenster allein durch normale Datei-Lesevorgänge und Tool-Interaktionen erschöpfen. Beachten Sie, dass das 200K-Fenster die gesamte Eingabekapazität ist; die effektive Aufmerksamkeit des Modells (der Anteil, den es mit hoher Genauigkeit berücksichtigt) ist eine andere, kleinere Zahl. Disziplin beim Kontextbudget zählt auch dann, wenn der gesamte Token-Verbrauch weit unter dem Limit liegt, denn Anweisungen am Anfang eines langen Kontexts erhalten verlässlichere Aufmerksamkeit als Anweisungen in der Mitte. Das Kontextbudget erzwingt architektonische Abwägungen:

Immer laden: Kernphilosophie, aktive Korrekturen und Sicherheitsregeln. Alle drei sind günstig (4-6 % des Budgets) und universell anwendbar. Sie zu laden, wenn sie nicht gebraucht werden, kostet kaum etwas. Sie wegzulassen, wenn sie gebraucht werden, kostet korrekte Ergebnisse.

Bei Bedarf laden: Skills, Agentenspezifikationen und Referenzdokumentation. Jeder Skill kostet 5-15 % des Fensters und gilt für eine einzige Domäne. Sie nur bei Relevanz zu laden, bewahrt Budget für die eigentliche Arbeit. Auslöser für das Laden eines Skills ist der Aufgabentyp, nicht der Sitzungstyp: Eine Webentwicklungssitzung, die auf eine Datenbankmigration stößt, braucht den Datenbank-Skill, auch wenn er beim Start nicht geladen wurde.

Nie laden: veraltete Übergabedokumente, überholte Konfigurationen oder historischen Zustand. Jede veraltete Datei verbraucht Budget, ohne die Ausgabe zu verbessern. Schlimmer noch: Veralteter Kontext verschlechtert die Ausgabe aktiv, weil er überholte Muster lehrt. Das Muster des Compounding Engineering verlangt, Kontext regelmäßig auszumisten, der seine Token-Kosten nicht mehr rechtfertigt.

Die Budgetierung von Kontext spiegelt denselben Zielkonflikt wider, der in traditioneller Software Datenbankindizierung, Caching-Strategien und Speicherverwaltung prägt.8 Die Einschränkung ist eine andere (Token statt Bytes), die architektonische Disziplin aber dieselbe.


Kontextpropagierung in Multi-Agenten-Systemen

Wenn der Hauptagent über das Task-Tool einen Subagenten startet, bestimmt die Wahl des weiterzugebenden Kontexts jede weitere Designentscheidung. Mein Multi-Agenten-Deliberationssystem verwendet 10 Forschungsagenten. Jeder Agent braucht genug Kontext, um unabhängig zu urteilen, doch zu viel geteilter Kontext verursacht das Konvergenzproblem, das im Boids-Beitrag dokumentiert ist: Agenten, die zu viel Kontext teilen, kommen zu identischen 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) statt über Agenten (parallele Prozesse). Beide folgen demselben Prinzip: Einschränkungen und Prinzipien weitergeben, Implementierungsdetails isolieren.

Propagierung in der Praxis

Ein konkretes Beispiel macht die Abwägung deutlich. Wenn der Hauptagent einen Subagenten für das Security-Review startet, enthält der Task-Prompt Folgendes:

## Propagated Context
- Core philosophy: Quality is the only variable (from CLAUDE.md)
- Security rules: OWASP Top 10, input validation at boundaries (from rules/security.md)
- Task: Review the authentication endpoint changes in app/auth.py

## NOT Propagated
- The main agent's conversation history (50+ messages about UI layout)
- Findings from the architecture reviewer (would bias security analysis)
- The FastAPI skill (irrelevant to a security-focused review)

Der Security-Reviewer erhält 2.000 Token Kontext statt 40.000. Er bewertet den Code anhand von Sicherheitskriterien, ohne von UI-Entscheidungen abgelenkt oder von den Schlussfolgerungen eines anderen Agenten beeinflusst zu werden. Die Isolation liefert eine unabhängige Einschätzung. Melden der Security-Reviewer und der Architektur-Reviewer unabhängig voneinander dasselbe Problem, ist der Befund belastbarer, als wenn ein Reviewer den Bericht des anderen gesehen und ihm zugestimmt hätte.


Kontextqualität beobachten

Die Token-Anzahl ist eine Proxy-Metrik. Das eigentliche Maß für Kontextqualität lautet: Liefert der Agent beim ersten Versuch das richtige Ergebnis?

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

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 Umstellung auf die Architektur mit sieben Schichten 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

Hier ein repräsentatives Vorher-Nachher-Beispiel aus dem Tracking-Log. Die Aufgabe ist identisch: „Rate Limiting zu einem API-Endpunkt hinzufügen.”

Vorher (monolithische CLAUDE.md, Juli 2025). Die erste Antwort des Agenten importierte eine Rate-Limiting-Bibliothek, die im Projekt nicht verwendet wurde (er folgte einem Beispiel aus dem veralteten FastAPI-Skill, der zusammen mit iOS-Regeln, Sicherheitsregeln und 150 Zeilen themenfremden Inhalts geladen war). Die Korrektur: „Verwende die bestehende RateLimiter-Klasse in app/middleware.py.” Eine Korrektur, eingeordnet als „faktischer Fehler: fehlender Kontext aus der Codebasis”.

Nachher (Architektur mit sieben Schichten, November 2025). Gleicher Aufgabentyp, anderer Endpunkt. Die erste Antwort des Agenten nutzte die bestehende RateLimiter-Middleware, übernahm die Namenskonvention für Parameter aus den benachbarten Endpunkten und nannte die Quelle des Musters: „following the rate limiting pattern in app/middleware.py:42.” Keine Korrektur nötig. Der FastAPI-Skill (Schicht 3) wurde bei Bedarf geladen und enthielt aktuelle Muster; die iOS-Regeln wurden nicht geladen, weil die Sitzung keine iOS-Arbeit betraf.

So können Sie das selbst verfolgen: Markieren Sie jede Agentensitzung in einem Log nach der ersten Antwort mit „akzeptiert” oder „korrigiert” und berechnen Sie das Verhältnis monatlich. Die Erfassung muss nicht präzise sein; Richtungstrends über 20 und mehr Sitzungen sind nützlicher als exakte Prozentwerte.

Korrekturtyp. Wenn der Agent doch eine Korrektur braucht: Ist der Fehler faktisch (falsche API, falsches Muster) oder eine Ermessensfrage (falscher Ansatz, falsche Priorität)? Faktische Fehler deuten auf fehlenden Kontext hin: Dem Agenten fehlten die Informationen, um die richtige Antwort zu liefern. Ermessensfehler deuten auf widersprüchlichen oder mehrdeutigen Kontext hin: Der Agent hatte die Informationen, gewichtete konkurrierende Anweisungen aber falsch. Die Unterscheidung zählt, weil die Lösung jeweils eine andere ist: Faktische Fehler erfordern zusätzlichen Kontext (eine neue Regel oder einen neuen Skill), Ermessensfehler erfordern klareren Kontext (die Auflösung eines Konflikts zwischen bestehenden Schichten). Wer die Korrekturtypen verfolgt, sieht, welche Schicht Aufmerksamkeit braucht.

Kontextdruck bei Abschluss der Aufgabe. Wie viel Kontextbudget bleibt übrig, wenn die Aufgabe abgeschlossen ist? Ist das Fenster zu 90 % gefüllt, bevor die Aufgabe zur Hälfte erledigt ist, lädt die Kontextarchitektur zu viel irrelevantes Material. Mein Hooks-System enthält einen Monitor für den Kontextdruck, der warnt, sobald die Auslastung 70 % überschreitet.


Eine Sitzung im Detail: Was wann geladen wird

Ein konkreter Durchgang zeigt, wie die sieben Schichten bei einer echten Aufgabe zusammenwirken. Das Szenario: Ich bitte Claude Code im Projekt blakecrosley.com, „Rate Limiting zum Endpunkt /api/ab/event hinzuzufügen”.

Sitzungsstart (0 s). Claude Code lädt Schicht 1 (CLAUDE.md, 205 Zeilen, ~800 Token) und Schicht 2 (alle 9 Regeldateien, ~3.200 Token). Insgesamt verbrauchter Kontext: ~4.000 Token (2 % des 200K-Fensters). Der Agent kennt nun meine Coding-Philosophie, die Sicherheitsanforderungen, die Konventionen für API-Design und den Git-Workflow, ganz gleich, worum ich ihn bitte.

Aufgabenbeginn (2 s). Der Agent liest die Aufgabe und erkennt sie als Änderung an einem FastAPI-Endpunkt. Schicht 5 (Hooks) feuert: Der UserPromptSubmit-Hook injiziert das aktuelle Datum und den Sitzungskontext (~200 Token). Der Agent lädt weder den SwiftUI-Skill noch die iOS-Sicherheitsregeln oder den Midjourney-Prompt-Skill. Diese Dateien existieren, sind aber irrelevant. Sie auszuschließen, spart ~8.000 Token.

Datei-Lesevorgänge (5-30 s). Der Agent liest app/main.py, den bestehenden Endpunkt-Code und die Testdatei. Jeder Lesevorgang verbraucht 5.000-15.000 Token Kontext. Nach drei Dateien sind ~30.000-50.000 Token verbraucht (15-25 % des Fensters).

Skill-Aktivierung (falls nötig). Braucht der Agent FastAPI-spezifische Muster, lädt er Schicht 3 (skills/fastapi/SKILL.md, ~2.500 Token). Der Skill wird geladen, weil die Aufgabe ihn erfordert, nicht weil die Sitzung begonnen hat. Ginge es um eine reine CSS-Aufgabe, würde der FastAPI-Skill nie geladen.

Implementierung und Verifikation (30 s bis 5 min). Der Agent schreibt Code, führt Tests aus und berichtet die Ergebnisse. Bei Abschluss der Aufgabe liegt der Kontextverbrauch typischerweise bei 60.000-100.000 Token (30-50 % des Fensters). Das verbleibende Budget reicht für Rückfragen, Korrekturen oder eine zweite Aufgabe in derselben Sitzung.

Die zentrale Beobachtung: Schicht 1 und Schicht 2 verbrauchen 2 % des Fensters und gelten für jede Aufgabe. Die Inhalte der Schichten 3 bis 7 werden selektiv geladen und verbrauchen 5-25 %, und zwar nur, wenn sie relevant sind. Würden alle 650 Dateien beim Sitzungsstart geladen, verbrauchten sie etwa 150.000-200.000 Token und ließen kaum Raum für die eigentliche Arbeit.


Das Muster der verteilten Architektur

Nichts am System mit sieben Schichten 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, in sich geschlossen)
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) führen zu identischen architektonischen Entscheidungen.10 Context Engineering ist Software Engineering für ein Substrat, in dem „Gedächtnis” eine knappe, verschleißende Ressource ist statt einer reichlich vorhandenen, dauerhaften.11

Eine unabhängige Bestätigung dieser Architektur liefert das Projekt obra/superpowers, das unabhängig davon eine ähnliche mehrschichtige Struktur für den Kontext von Claude Code entwickelt hat: Kernprinzipien in einer globalen Datei, Domänen-Skills, die bei Bedarf geladen werden, und Verifikationsprozeduren, die von Verhaltensanweisungen getrennt sind.12 Diese Konvergenz legt nahe, dass die geschichtete Architektur keine eigenwillige Designentscheidung ist, sondern eine natürliche Antwort auf die Einschränkungen des Substrats.


Zentrale Erkenntnisse

Für Ingenieure, die Agentensysteme bauen:

  • Entwerfen Sie Kontext wie Software-Architektur, nicht wie Dokumentation. Was wann geladen wird, was was überschreibt und was an Subagenten weitergegeben wird, bestimmt das Verhalten des Agenten stärker als jede einzelne Anweisung. Wenden Sie dieselbe Disziplin der Trennung von Zuständigkeiten an, die Sie auch für Code nutzen.

  • Trennen Sie Schichten nach Lebenszyklus. Universelle Regeln werden in jeder Sitzung geladen. Domänenspezifisches Wissen wird bei Bedarf geladen. Sitzungsbezogener Zustand bleibt flüchtig. Wer Lebenszyklen in einer Datei vermischt, erzeugt genau 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 Fenster von 200K Token. Jede dauerhafte Anweisung konkurriert mit dem Arbeitsgedächtnis. Messen Sie, was Sie laden, und entfernen Sie, was seine Token nicht rechtfertigt.

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

Übung: Prüfen Sie Ihr Kontextsystem. Legen Sie diese Verzeichnisstruktur an und füllen Sie sie mit Ihren bestehenden Anweisungen:

mkdir -p .claude/{rules,skills,agents,hooks,config,state}
# Move domain-specific sections from CLAUDE.md into rules/
# Move reusable procedures into skills/
# Move agent specs into agents/

Beantworten Sie dann: Welche Dateien werden in jeder Sitzung geladen, sollten aber nur bei Bedarf geladen werden? Welche Dateien für den Bedarfsfall fehlen? Halten Sie die Antworten in einem einfachen Log fest: Markieren Sie jede Sitzung mit „beim ersten Versuch korrekt” oder „Korrektur nötig” und prüfen Sie das Verhältnis nach 20 Sitzungen.


Häufige Fragen

Wie sollte ich Kontextdateien für KI-Coding-Agenten strukturieren?

Lagern Sie domänenspezifische Inhalte in eigene Dateien aus, sobald sie 20-30 Zeilen überschreiten und zumindest in manchen Sitzungen irrelevant wären. Wenn Sie iOS-spezifische und webspezifische Regeln in dieselbe CLAUDE.md schreiben, liest der Agent beide, unabhängig vom aktuellen Projekt. Behalten Sie universelle Einschränkungen (Sicherheitsregeln, Coding-Standards, philosophische Grundsätze) in der Kerndatei. Verschieben Sie domänenspezifische Muster (FastAPI-Endpunkte, SwiftUI-Konventionen, Datenbankabfragen) in Dateien, die nur dann geladen werden, wenn die Aufgabe sie erfordert.

Woran erkenne ich, dass ein Skill veraltet ist?

An zwei Signalen: Der Agent produziert Code, der funktioniert, aber nicht zu den aktuellen Mustern der Codebasis passt, oder der Agent verweist auf APIs oder Muster aus einer älteren Version eines Frameworks. Versehen Sie jeden Skill mit einem Datum der letzten Überprüfung und kontrollieren Sie es vierteljährlich. Wichtiger noch: Die Qualitätsschleife (entspricht generierter Code den bestehenden Mustern?) erkennt die Abweichung veralteter Skills unabhängig vom Inhalt des Skills.

Wie groß sollte ein Kontextbudget sein?

Reservieren Sie bei einem Fenster von 200K Token 4-6 % für System-Prompt und Regeln (immer geladen), lassen Sie 40-60 % für Gesprächsverlauf und Datei-Lesevorgänge (die eigentliche Arbeit) frei und planen Sie 10-15 % für Skills und Agentenkontext ein, die bei Bedarf geladen werden. Übersteigt der Kontextdruck 70 %, bevor die Aufgabe zur Hälfte erledigt ist, laden Sie zu viel irrelevantes Material. Die konkreten Prozentwerte hängen von der Komplexität der Aufgabe ab: Ein Refactoring über mehrere Dateien verbraucht mehr Kontext als die Behebung eines Fehlers in einer einzelnen Funktion.

Wie gehe ich mit widersprüchlichen Anweisungen zwischen Schichten um?

Wenden Sie einen Vorrang nach Scope an: Die spezifischere Schicht gewinnt. Skills (lokaler Scope) überschreiben Regeln (Modul-Scope), die wiederum CLAUDE.md (globaler Scope) überschreiben. Wenn Sie einen Konflikt entdecken, machen Sie die Auflösung explizit, statt sich darauf zu verlassen, dass das Modell ihn probabilistisch auflöst. Ergänzen Sie in der spezifischeren Schicht einen Hinweis: „Dies überschreibt für diesen konkreten Kontext das allgemeine Prinzip X, weil Y.”


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



  1. Birgitta Böckeler, “Context Engineering for Coding Agents,” martinfowler.com, Februar 2026. martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html. Böckelers Kollege Bharani Subramaniam definiert Context Engineering als “curating what the model sees so that you get a better result.” Die Definition ist korrekt. Der vorliegende Beitrag argumentiert, dass die Struktur, in der diese Informationen organisiert und bereitgestellt werden, eine architektonische Disziplin ist und keine Dokumentationsübung. ↩

  2. Daniel Miessler, “How to Talk to AI,” danielmiessler.com, Juni 2025. danielmiessler.com/blog/how-to-talk-to-ai. Miessler argumentiert, dass die eigentliche Fähigkeit hinter Prompt Engineering und Context Engineering klares Denken ist: die Fähigkeit, genau zu formulieren, was man erreichen will. Dieser Ansatz ergänzt den vorliegenden Beitrag, der sich auf die strukturelle Disziplin der Kontextorganisation konzentriert statt 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, Teil III (Design Principles) und Teil V (Architecture). Martin identifiziert dieselben Kräfte: Kopplung, Kohäsion und die Trennung von Zuständigkeiten. Der Unterschied bei KI-Kontextsystemen besteht darin, dass „Gedächtnis” flüchtig und begrenzt ist, was eine Einschränkung hinzufügt, der traditionelle Architektur nicht begegnet. ↩

  4. Die Zahl von 650 Dateien ist die Messung des Autors mit 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). Pro Sitzung wird nur ein Bruchteil geladen. ↩

  5. Die direkte Analogie ist die Auflösung von Variablen-Scopes in Programmiersprachen (lokal, umschließend, global, eingebaut). Pythons LEGB-Regel definiert dieselbe Hierarchie: lokaler Scope, Scope der umschließenden Funktion, 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 hinkt leicht, weil LLMs Anweisungen probabilistisch und nicht deterministisch befolgen, doch 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 Kontextfenster von 200K Token, wobei Opus 4.6 und Sonnet 4.6 in der Beta 1M Token unterstützen. ↩

  7. Messungen zum Token-Verbrauch aus 50 Claude-Code-Sitzungen, die ich zwischen August 2025 und Februar 2026 aufgezeichnet habe. Die vollständige Methodik steht in Kontextfenster-Management. ↩

  8. Die Analogie zwischen Token-Budgets und Speicherhierarchien folgt dem Rahmen in Hennessy, J.L. und Patterson, D.A., Computer Architecture: A Quantitative Approach, 6. Auflage, Morgan Kaufmann, 2017, Kapitel 2 (Memory Hierarchy Design). Wie Hennessy und Patterson Cache-Hierarchien, Lokalität von Speicherzugriffen und die Kosten des Speicherzugriffs auf verschiedenen Ebenen behandeln, lässt sich direkt auf Context Engineering übertragen: Häufig benötigter Kontext (L1-Cache / Kernregeln) lädt am schnellsten, selten benötigter Kontext (Festplatte / Skills auf Abruf) lädt nur, wenn er referenziert wird. ↩

  9. Die Erfolgsrate beim ersten Versuch ist eine grobe Metrik, die auf der subjektiven Einschätzung des Autors beruht, ob die erste Antwort eine Korrektur erforderte. Es handelt sich nicht um ein kontrolliertes Experiment. Die Richtung der Verbesserung (von 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 “a suite of small services, each running in its own process and communicating with lightweight mechanisms.” Die Kräfte, die sie benennen (unabhängiges Deployment, dezentrale Governance, abgegrenzte Kontexte), entsprechen direkt der Agentenisolation und der protokollbasierten Kommunikation in der hier beschriebenen Kontextarchitektur. ↩

  11. Die Sicht auf „Kontext als Architektur” stützt 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 zur Verwaltung von Kontext in generativen KI-Systemen vor, die vielfältige Wissensartefakte, Gedächtnis und Tools innerhalb von Token-Grenzen als Kontext behandelt. Dieser theoretische Rahmen stützt die hier beschriebene praktische Architektur. ↩

  12. obra/superpowers, github.com/obra/superpowers. Das Projekt superpowers organisiert Agentenkontext in Kerninstruktionen, Skills auf Abruf und Verifikationsprozeduren, eine Struktur, die trotz unabhängiger Entwicklung mit der hier beschriebenen Architektur aus sieben Schichten übereinstimmt. Diese Konvergenz stützt die These, dass geschichteter Kontext eine natürliche architektonische Antwort auf begrenzte Kontextfenster ist. ↩

Verwandte Beiträge

Der Ralph-Loop: Wie ich autonome KI-Agenten über Nacht betreibe

Ich habe ein autonomes Agentensystem mit Stop-Hooks, Spawn-Budgets und Dateisystem-Speicher gebaut. Die Fehlschläge und …

11 Min. Lesezeit

Multi-Agent-Deliberation: Wenn Übereinstimmung der Fehler ist

Multi-Agent-Deliberation erkennt Fehler, die Einzelagenten-Systeme übersehen. Die Architektur, die Sackgassen und was si…

19 Min. Lesezeit

Das Protege-Pattern

Ein 7B-Modell mit sparsem Expertenzugang erreicht Agenten 50-facher Groesse. Routinearbeit an kleine Modelle, Urteile an…

12 Min. Lesezeit