Agentische Systeme: Wie Markdown Claude Code steuert

Kurz vorab: Wir arbeiten täglich mit Claude Code, das hier ist also keine neutrale Marktübersicht. Die technischen Angaben stammen aus der offiziellen Dokumentation, Stand November 2026, und alle Quellen stehen unten. Die Werkzeuge ändern sich schnell, schau bei Details also lieber nach. Und passend zum Thema: Dieser Text ist mit Claude Code entstanden.

Der Treffpunkt

Die meisten Erklärungen zu KI-Agenten starten mit einem falschen Bild. Da gibt es scheinbar viele kleine Dateien und Agenten, die sich gegenseitig Nachrichten schicken wie Kollegen im Büro. Die Wirklichkeit ist schlichter und deshalb viel nützlicher.

Ein Sprachmodell hat kein Gedächtnis zwischen zwei Anfragen. Es bekommt einen Stapel Text, antwortet und vergisst alles wieder. Damit es trotzdem wirkt, als wüsste es etwas, schickt das Programm drumherum bei jedem Schritt den ganzen Stapel neu mit. Dieser Stapel heißt Kontextfenster.

Das Programm drumherum heißt Harness. Claude Code ist so ein Harness: Es stellt Werkzeuge bereit und entscheidet, was das Modell zu sehen bekommt. Die kurze Formel dazu haben wir im Beitrag zum KI-Harness beschrieben: Agent = Modell + Harness.

Daraus folgt der wichtigste Satz dieses Textes:

CLAUDE.md schickt dem Skill keine Nachricht. Der Skill kennt die Rule nicht. Der Harness legt alle Texte nacheinander in denselben Stapel, und erst das Modell liest sie zusammen. Wenn zwei Dateien sich widersprechen, gibt es keinen Compiler, der meckert. Es gibt nur ein Modell, das abwägt.

Neun Quellen, ein Stapel. Die Reihenfolge entspricht einer typischen Sitzung: erst die festen Texte, dann alles, was während der Arbeit dazukommt.

Die Schleife

Was macht aus dem Sprachmodell einen Agenten? Werkzeuge und eine Schleife. Ohne Werkzeuge kann das Modell nur Text ausgeben. Mit Werkzeugen sagt es: „Lies diese Datei.“ Der Harness führt das aus, hängt das Ergebnis an den Stapel und fragt das Modell erneut.

Die Doku nennt drei Phasen: Kontext holen, handeln, Ergebnis prüfen. Sie gehen fließend ineinander über. Eine Frage zum Code braucht vielleicht nur die erste Phase, ein Bugfix läuft mehrmals durch alle drei.

Das Modell trifft dabei keine geheimen Entscheidungen im Hintergrund. Alles, was es weiß, steht im Stapel. Und alles, was es tut, ist ein Werkzeugaufruf, den der Harness prüfen, ablehnen oder protokollieren kann. Genau an dieser Stelle setzen Rechte und Hooks später an.

Jede Zeile ist ein Werkzeugaufruf. Sein Ergebnis landet im Kontext und bestimmt den nächsten Schritt. Das Beispiel folgt dem Ablauf aus der Doku.

Du bist übrigens Teil dieser Schleife. Du kannst jederzeit unterbrechen oder korrigieren, und Claude Code liest eine neue Nachricht nach dem laufenden Werkzeugaufruf. Die Schleife endet, wenn das Modell keinen Werkzeugaufruf mehr ausgibt, sondern eine Antwort.

Context Engineering

Wenn alles Wissen im Stapel liegt, ist die entscheidende Frage: Was liegt im Stapel? Genau darum geht es beim Context Engineering. Anthropic beschreibt es im September 2025 so: als Strategien, um die optimale Menge an Tokens während der Ausführung auszuwählen und zu pflegen. Ein Token ist grob ein Wortbaustein, die Mengeneinheit, in der Modelle lesen und in der du bezahlst.

Prompt Engineering fragt: Wie formuliere ich meine Anweisung gut? Context Engineering fragt: Was soll das Modell in diesem Moment überhaupt sehen? Prompts sind damit ein Teil des Kontexts, nicht das Ganze. Und die Frage stellt sich nicht einmal, sondern bei jedem einzelnen Schritt der Schleife neu.

Das Leitprinzip aus Anthropics Artikel lautet im Original: find the smallest set of high-signal tokens that maximize the likelihood of your desired outcome. Auf Deutsch: Finde die kleinste Menge an aussagekräftigem Text, die dein Ergebnis wahrscheinlich macht.

Warum nicht einfach alles reinkippen? Aus drei Gründen. Der Platz ist begrenzt. Alles im Stapel wird bei jeder Anfrage wieder mitgeschickt und kostet entsprechend. Und vor allem verdünnt jede unnötige Zeile die wichtigen. Die Doku von Claude Code warnt, dass längere CLAUDE.md-Dateien die Befolgung senken. Mehr Text ist also nicht nur teurer, sondern kann das Ergebnis verschlechtern.

Anthropic nennt vier Techniken gegen das Problem, und du findest jede davon in Claude Code wieder:

• Just-in-time: Statt Daten vorab zu laden, behält der Agent leichte Verweise wie Dateipfade und lädt erst bei Bedarf.
• Compaction: Wird der Stapel zu groß, wird der Verlauf zusammengefasst.
• Strukturierte Notizen: Der Agent schreibt Wissen in Dateien außerhalb des Fensters und holt es später zurück.
• Sub-Agenten: Spezialisten arbeiten in eigenen, sauberen Fenstern und geben nur Zusammenfassungen zurück.

Der Datei-Atlas

Jetzt zu den konkreten Dateien. Der wichtigste Merksatz dazu: Sie unterscheiden sich weniger im Format als im Ladezeitpunkt. Fast alles ist Markdown, oft mit einem kleinen Kopfbereich namens Frontmatter. Entscheidend ist, wann eine Datei im Stapel landet und wie lange sie bleibt.

# Projekt
- Paketmanager: pnpm
- Tests: pnpm test, vor jedem Commit
- Design: @DESIGN.md
- API-Details: siehe docs/api.md

---
paths:
  - "**/*.tsx"
  - "**/*.css"
---
# UI-Regeln
- Klickbares ist button oder a, nie div.
- Textkontrast mindestens 4,5:1.

---
name: release
description: Baut und veröffentlicht eine
  Version. Nutzen bei "release" oder "ausliefern".
disable-model-invocation: true
---
1. Tests laufen lassen.
2. Changelog schreiben.
3. Tag setzen und pushen.

---
name: code-reviewer
description: Prüft Änderungen auf Fehler.
tools: Read, Grep, Glob
model: sonnet
---
Du bist Reviewer. Du änderst nichts.
Nenne nur Fehler mit Datei und Zeile.

- [Testaufbau](testing.md): nutzt echte DB
- [Stil](style.md): kurze Antworten bevorzugt
- [Deploy](deploy.md): nur per GitHub Action

# Antwortstil: Kurz
Ergebnis zuerst.
Standard: 1 bis 5 Zeilen.
Keine Einleitung, keine Zusammenfassung.

# In CLAUDE.md
## Design
@DESIGN.md

# Merke: DESIGN.md ist kein Feature von
# Claude Code. Sie wirkt nur durch den Import.

Pfeiltasten wechseln den Reiter. Die Beispiele sind verkürzt, die Felder im Kopfbereich sind echt.

Stapeln oder überschreiben?

Wichtig für den Alltag: Nicht jeder Dateityp reagiert gleich, wenn es ihn mehrfach gibt.

Die erste Zeile ist die gefährlichste. Eine globale Regel und eine Projektregel haben keinen festen Vorrang. Widersprechen sie sich, folgt Claude laut Doku womöglich einer davon nach Gutdünken. Regeln brauchen also Pflege wie Code: Widersprüche suchen und auflösen.

Nicht alles ist Markdown

Zwei wichtige Teile sind bewusst kein Fließtext. Hooks und Rechte stehen in settings.json, weil sie von einem Programm ausgeführt werden und nicht vom Modell gelesen. Das ist kein Zufall: Prosa ist für Modelle, JSON für Maschinen. Wir kommen darauf zurück.

Acht Kanäle

Wenn Dateien nicht direkt reden, wie kommt dann Information von A nach B? Über acht Wege, die ich im Alltag immer wieder sehe. Klick dich durch.

Sender, Träger, Empfänger. Bis auf den Hook-Kanal läuft jeder Weg über Text, den am Ende ein Modell liest.

Drei dieser Kanäle verdienen eine eigene Erklärung, weil sie im Alltag die meiste Wirkung haben.

Das Frontmatter als Vertrag

Der Kopfbereich einer Datei spricht nicht mit dem Modell, sondern mit dem Harness. paths sagt, wann die Regel laden soll. tools sagt, was ein Subagent darf. Und die description eines Skills ist besonders heikel: Sie steht dauerhaft im Kontext, und das Modell entscheidet allein anhand dieses Satzes, ob es den Skill lädt. Ist er vage, wird der Skill nicht gefunden oder falsch benutzt. Eine Beschreibung ist also weniger Dokumentation als ein Auslöser.

Das Dateisystem als gemeinsames Gedächtnis

Der stärkste Kanal ist der unscheinbarste. Ein Agent schreibt eine Datei, ein anderer liest sie später. Die beiden müssen voneinander nichts wissen. In der Biologie heißt das Stigmergie: Ameisen koordinieren sich über Spuren in der Umgebung, nicht über Gespräche.

Das hat drei Vorteile. Es überlebt das Ende einer Sitzung, denn jede neue Sitzung startet mit leerem Fenster. Es ist für Menschen lesbar. Und mit Git ist jede Änderung nachvollziehbar. Deshalb führen wir unsere Firma aus Textdateien, das haben wir im Beitrag zum Startup Brain beschrieben.

Der Verweis statt des Inhalts

Ein Pfad im Text ist ein Lesezeichen. Schreibst du in CLAUDE.md „API-Details stehen in docs/api.md“, kostet das eine Zeile, und das Modell holt die Datei nur, wenn es sie braucht. Schreibst du dagegen @docs/api.md, wird die Datei sofort mitgeladen, bei jedem Start. Beides ist legitim, aber es ist eine bewusste Entscheidung zwischen „immer da“ und „bei Bedarf“.

Eine Sitzung live

Die folgende Animation zeigt, wie sich das Fenster füllt. Alle Zahlen sind von mir gewählte Beispielwerte, damit das Prinzip sichtbar wird. Deine echten Werte zeigt der Befehl /context.

Beispielwerte in Tausend Tokens bei einem Fenster von 200 k. Achte auf Schritt 3, 7 und 8: Dort sieht man Regel, Müll und Aufräumen.

Zwei Dinge sieht man hier gut. Die festen Dateien sind selten das Problem, die großen Brocken sind Dateiinhalte und Werkzeugausgaben. Und die Regel aus Schritt 3 verschwindet bei der Compaction und kommt erst wieder, wenn die passende Datei erneut angefasst wird. Das ist kein Fehler, sondern der Preis für das sparsame Laden.

Noch ein Detail, das viele überrascht: CLAUDE.md ist technisch nicht Teil des System-Prompts. Claude Code liefert sie laut Doku als Nutzernachricht nach dem System-Prompt aus. Praktisch heißt das: Sie ist Kontext, den Claude zu befolgen versucht, aber kein Gesetz. Dazu gleich mehr.

MCP-Server verdienen ebenfalls eine Erwähnung. MCP ist das Protokoll, über das Claude Code externe Dienste anbindet. Früher fraßen große Werkzeuglisten viel Platz, heute lädt Claude Code zunächst nur die Namen und holt die genauen Beschreibungen bei Bedarf nach. Das ist wieder dasselbe Muster: erst das Inhaltsverzeichnis, dann das Kapitel.

Die richtige Flughöhe

Wenn Platz knapp ist, zählt jede Regel. Wie schreibt man sie? Anthropic spricht von der richtigen Flughöhe, einem Mittelweg zwischen zwei Fehlern. Zu tief heißt: starre Wenn-dann-Logik, die brüchig wird, sobald etwas Unvorhergesehenes passiert. Zu hoch heißt: schöne Allgemeinplätze, mit denen niemand etwas anfangen kann.

Regler ziehen oder mit den Pfeiltasten bewegen. Das Beispiel ist von uns, die Unterscheidung stammt von Anthropic.

Mein Test für jede Regel ist simpel: Könnte jemand prüfen, ob sie eingehalten wurde? „Achte auf gute Barrierefreiheit“ fällt durch. „Textkontrast mindestens 4,5:1“ besteht. Die Doku rät genauso: Anweisungen konkret genug schreiben, dass man sie verifizieren kann.

Dazu gehören zwei Gewohnheiten. Schreib das Warum dazu, wenn es nicht offensichtlich ist, denn mit Begründung kann das Modell auch Fälle beurteilen, die niemand vorhergesehen hat. Und nenne Beispiele statt Regellisten, weil ein gutes Beispiel oft mehr erklärt als zehn Sonderfälle. Das empfiehlt auch Anthropic.

Subagenten und Teams

Bisher lief alles in einem Fenster. Jetzt die wichtigste Erweiterung. Ein Subagent ist eine eigene Schleife mit eigenem Kontextfenster, eigenem System-Prompt und eigenen Rechten. Wer dabei an einen klugen Kollegen denkt, liegt nur halb richtig. Der nützlichere Gedanke ist: Ein Subagent ist eine Kontextgrenze.

Stell dir vor, Claude soll herausfinden, wie die Anmeldung in einem großen Projekt funktioniert. Dafür liest es 40 Dateien. Für die eigentliche Aufgabe braucht es am Ende aber nur fünf Sätze. Ohne Subagent liegen die 40 Dateien im Stapel und werden bei jedem weiteren Schritt mitgeschickt. Mit Subagent bleiben sie drüben, und zurück kommen die fünf Sätze.

Prozentwerte sind Beispielwerte. Der Unterschied ist das Prinzip: Bei jedem weiteren Schritt zahlt das Hauptfenster nur für das, was bei ihm liegt.

Was ein Subagent sieht und was nicht

Hier passieren die meisten Fehler. Ein Subagent kennt dein Gespräch nicht. Er sieht nur, was der Hauptagent ihm in die Beauftragung schreibt. Das erklärt, warum eine knappe Beauftragung so oft schiefgeht.

Die Beauftragung ist der engste Flaschenhals des Systems. Alles, was dort fehlt, weiß der Subagent nicht. Eine gute Beauftragung nennt deshalb Ziel, bereits Geprüftes, relevante Dateien und das gewünschte Ausgabeformat, so wie ein gutes Briefing für eine Kollegin, die neu im Projekt ist.

Auch die Rückrichtung ist eng. Zurück kommt die Zusammenfassung, nicht die Arbeit. Du siehst also ein Ergebnis in ruhigem Tonfall, aber nicht, wie es entstanden ist. Für wichtige Aussagen gilt deshalb: nachprüfen, nicht glauben.

Mehrere Agenten: drei Stufen

Bei Agent Teams sieht man schön, wie bodenständig das alles ist. Der Briefkasten eines Agenten ist laut Doku eine JSON-Datei unter ~/.claude/teams/. Aufgaben werden per Dateisperre vergeben, damit sich zwei Agenten nicht dieselbe schnappen. Selbst der Kanal zwischen laufenden Agenten ist also am Ende das Dateisystem.

Ein Sicherheitsdetail gefällt mir besonders: Nachrichten zwischen Agenten werden dem Empfänger als solche gekennzeichnet. Ein Agent kann eine Berechtigung also nicht im Namen des Menschen erteilen. Freigaben lassen sich nicht weiterreichen wie ein Zettel.

Und noch eine Warnung, die für alle Stufen gilt: Mehr Agenten sind nicht automatisch besser. Teams kosten deutlich mehr Tokens und erzeugen Abstimmungsaufwand. Zwei Agenten, die dieselbe Datei bearbeiten, überschreiben sich gegenseitig. Fang mit einem an.

Compaction

Irgendwann ist das Fenster voll. Dann fasst Claude Code den Verlauf zusammen und macht mit der Zusammenfassung weiter. Das nennt sich Compaction. Hier zeigt sich, wie klug eine Datei platziert war, denn nicht alles überlebt gleich gut.

Stand der Doku im November 2026. Deine Version kann abweichen.

Daraus folgen vier praktische Regeln:

1. Was dauerhaft gelten soll, gehört in eine Datei, nicht in den Chat. Eine Anweisung vom Anfang des Gesprächs kann nach der Compaction weg sein.
2. Pfad-Regeln verschwinden zeitweise. Muss eine Regel immer gelten, nimm paths raus oder schreib sie in die CLAUDE.md im Projekt-Hauptordner.
3. Das Wichtigste nach oben. Skill-Inhalte werden nach der Compaction auf 5.000 Tokens pro Skill gekürzt, und zwar vom Anfang her.
4. Steuere selbst. Mit /compact Fokus auf den Login-Bug sagst du, was bleiben soll. Mit /clear startest du bei neuem Thema frisch.

Die letzte Regel unterschätzen viele. Altes Gespräch verdrängt nicht nur Platz, es kostet bei jeder Nachricht. Ein neues Thema verdient ein neues Fenster. Die Erinnerung liegt ja in den Dateien.

Bitten und Befehlen

Jetzt der Teil, der mir am wichtigsten ist. Bis hierhin haben wir nur über Text geredet, den ein Modell liest. Und Text ist immer eine Bitte.

Die Doku sagt es deutlich: Eine Anweisung wie „bearbeite nie die .env“ in CLAUDE.md ist eine Bitte, keine Garantie. Soll eine Regel jedes Mal gelten, gehört sie in einen Hook.

Ein Hook ist ein Programm, das der Harness bei einem festen Ereignis startet, zum Beispiel direkt vor einem Werkzeugaufruf. Das Modell entscheidet nicht darüber, ob er läuft. Der Hook bekommt per Standardeingabe JSON mit den Details und antwortet über seinen Exit-Code. Exit 0 heißt: weiter. Exit 2 heißt: blockiert. Der Text aus der Fehlerausgabe geht zurück an Claude, das daraufhin umplanen kann.

Vorsicht bei einer Falle: Exit 1 blockiert nicht. Es gilt als nicht blockierender Fehler, auch wenn 1 sonst überall „Fehler“ heißt. Wer eine Regel durchsetzen will, braucht Exit 2.

Wähle einen Befehl.

Vereinfachte Vorführung. Der echte Hook bekommt mehr Felder und ist dein eigenes Skript. Schalte den Hook aus und vergleiche.

#!/bin/bash
# Blockiert gefährliche Bash-Befehle, Exit 2 ist die Sperre
befehl=$(jq -r '.tool_input.command')

if [[ "$befehl" == *"rm -rf"* ]]; then
  echo "Gesperrt: rm -rf ist hier nicht erlaubt." >&2
  exit 2
fi
exit 0

Hooks können auch Text zurückgeben. Über das Feld additionalContext landet er als Erinnerung im Kontext. So kommt zum Beispiel ein Lint-Ergebnis nach jeder Änderung beim Modell an. Hier treffen sich beide Welten: Das Programm läuft garantiert, und das Modell reagiert klug auf das Ergebnis.

Hooks sind außerdem kostenlos im Kontext, solange sie nichts zurückgeben. Das macht sie attraktiv, um CLAUDE.md schlank zu halten: Eine Regel, die ein Linter prüft, muss nicht mehr im Text stehen.

Neben Hooks gibt es die Berechtigungen. Sie legen fest, welche Werkzeuge ohne Rückfrage laufen, welche nachfragen und welche verboten sind. Und es gibt die Checkpoints: Vor jeder Bearbeitung sichert Claude Code den Dateistand, sodass du zurückspringen kannst. Das gilt aber nur für Dateien. Eine verschickte Mail, ein Datenbankbefehl oder ein Deployment lässt sich so nicht rückgängig machen. Darum bleibt bei allem nach außen ein Mensch im Ablauf.

Wie groß die Lücke zwischen Text und Durchsetzung in der Praxis ist, zeigt eine Auswertung von 481 öffentlichen CLAUDE.md-Dateien: Laut Marmelab waren nur 4,4 % der Sicherheitsregeln durch eine echte Kontrolle gedeckt. Der Rest war gut gemeinter Text.

Zehn Design-Prinzipien

Aus all dem lassen sich Grundsätze ableiten, die für agentische Systeme generell gelten. Das sind unsere, formuliert aus dem Alltag.

1. Kontext ist Budget. Jede Zeile muss sich lohnen. Frag bei jeder Regel: Würde das Modell ohne sie einen Fehler machen?
2. Lade so spät wie möglich. Erst das Inhaltsverzeichnis, dann das Kapitel. Das Prinzip heißt Progressive Disclosure: Beschreibungen vor Skill-Inhalten, Pfade vor Dateien, Namen vor Schemata.
3. Trenne Fakten, Abläufe und Durchsetzung. Fakten gehören in CLAUDE.md, Abläufe in Skills, Durchsetzung in Hooks.
4. Eine Wahrheit pro Thema. Doppelte Regeln driften auseinander und werden zu Widersprüchen. Verweise lieber, als zu kopieren.
5. Schreib prüfbar. Eine Regel, die niemand überprüfen kann, ist ein Wunsch.
6. Mach die Datei zur Schnittstelle. Was jemand anderes wissen muss, gehört auf die Platte, in lesbarer Form, unter Versionskontrolle.
7. Trenne Fenster nach Aufgaben. Neue Aufgabe, neues Fenster. Lärm in den Subagenten.
8. Schließe die Schleife. Gib dem Agenten eine Möglichkeit, sein Ergebnis selbst zu prüfen: Tests, Screenshots, Linter. Ohne Prüfung gibt es nur Hoffnung.
9. Enge Rechte, klare Grenzen. Der Agent darf viel lesen und wenig nach außen. Riskantes braucht eine Freigabe.
10. Fang klein an und miss. Ergänze Regeln nur, wenn ein Fehler passiert ist. Entferne sie, wenn sie nichts mehr bewirken.

Das letzte Prinzip ist das am wenigsten intuitive. Es ist verlockend, vorab alles aufzuschreiben, was einem einfällt. Besser ist es umgekehrt: Claude macht denselben Fehler zweimal, dann kommt eine Zeile in die CLAUDE.md. So empfiehlt es auch die Doku.

Unser Fallbeispiel

Das klingt jetzt alles sehr aufgeräumt. Wie es in der Praxis aussieht, zeigt ein Beispiel von heute. Wir wollen unsere Entwicklung so einstellen, dass in jedem Projekt feste Gebote gelten. Angefangen haben wir mit UI und UX, auf Basis des Workshops mit unserer UX-Beraterin Tine.

Die Frage: System-Prompt oder Skill?

Beides wäre falsch gewesen. Ein großer System-Prompt lädt UI-Regeln auch dann, wenn jemand nur eine Datenbank-Migration schreibt. Ein Skill wirkt erst beim Aufruf, und wer ihn nicht aufruft, hat keine Regeln. Für ein Gesetz ist das zu wenig.

Unsere Lösung sind vier Schichten:

Was wir dabei gefunden haben

Beim Zusammenschreiben kamen drei Fehler in unserem eigenen Setup heraus, und alle drei passen genau zu diesem Artikel:

• Die Regel war nur auf einem Laptop. Sie lag seit Tagen in meinem globalen Ordner, aber in keinem Projekt. Die Agenten aller anderen im Team kannten sie nicht. Eine Regel außerhalb des Repositorys ist privat.
• Zwei Dateien widersprachen sich. Unser Stil sagt „so wenig Text wie möglich“, die Barrierefreiheit verlangt Namen für jedes Bedienelement. Niemand hatte festgelegt, was gewinnt. Das Modell hätte also im Einzelfall geraten. Jetzt steht es drin: Sichtbaren Text kürzen ja, zugängliche Namen streichen nein.
• Unsere Tokens brachen die eigene Regel. Die Regel verlangte 3:1 für Feldgrenzen, unsere Linienfarbe schaffte 1,3:1. Das fiel erst auf, als wir nachgerechnet statt nachgelesen haben. Eine prüfbare Regel hat sich hier also selbst bezahlt gemacht.

Ein Vorbehalt gehört dazu: Das System ist frisch. Ob die Gebote die Qualität wirklich messbar heben, wissen wir noch nicht. Schicht 3 ist für die UI noch nicht gebaut, und das Ausrollen in die Projekte steht aus.

Typische Fehler

So fängst du an

Du brauchst das nicht alles auf einmal. Die Doku hat eine schöne Reihenfolge: Jede Erweiterung hat einen erkennbaren Auslöser.

Ein gutes Grundgerüst für ein Projekt sieht so aus:

mein-projekt/
├── CLAUDE.md              # immer: Befehle, Konventionen, Verweise
└── .claude/
    ├── settings.json      # Hooks und Rechte, im Git
    ├── rules/
    │   ├── ui.md          # paths: Frontend-Dateien
    │   └── api.md         # paths: Backend-Dateien
    ├── skills/
    │   └── release/
    │       └── SKILL.md   # Ablauf, /release
    └── agents/
        └── reviewer.md    # liest nur, eigene Rolle

Alles davon gehört ins Git. Dann bekommt jede Person im Team denselben Agenten, und Änderungen an den Regeln sind so nachvollziehbar wie Änderungen am Code.

So gehst du konkret vor:

1. Starte mit /init und streiche danach alles, was nicht zwingend nötig ist.
2. Prüfe mit /context, was wirklich Platz belegt.
3. Sammle Fehler eine Woche lang und mach aus jedem wiederholten eine prüfbare Zeile.
4. Sichere Riskantes zuerst ab: Secrets, Löschen, Pushen auf den Hauptzweig.
5. Lass prüfen: Tests und Linter machen aus dem Agenten erst einen, der seine Arbeit selbst kontrolliert.
6. Räum regelmäßig auf. /doctor hilft dabei, zu lange oder widersprüchliche Anleitungen zu finden.

Dasselbe gilt übrigens für andere Agenten. Die Begriffe unterscheiden sich, aber AGENTS.md liest Claude Code ebenfalls, und Schleife, Kontextfenster, Werkzeuge, Durchsetzung findest du in jedem ernsthaften Harness wieder.

Was belegt ist

Ehrlich gesagt: Vieles rund um Context Engineering ist Erfahrungswissen. Es gibt erste Studien, und die Ergebnisse sollten nachdenklich machen.

• Kontextdateien sind kein Selbstläufer. Die ETH Zürich fand, dass Kontextdateien die Erfolgsquote im Allgemeinen nicht verbessern, die Kosten aber um über 20 % erhöhen. Das spricht für kurze Dateien und gegen automatisch erzeugte Regelwerke.
• Der Harness zählt. Laut Composio erreichte dasselbe Modell mit acht Harnesses bei denselben 25 Aufgaben 68 bis 88 % Erfolg. Das ist eine Herstellerangabe, die Richtung aber passt.
• Mehr Agenten sind nicht besser. Ein Team aus vier Rollen schaffte 72,2 %, der beste Einzelagent 71,8 %. Der Aufwand für die Abstimmung stand kaum im Verhältnis zum Gewinn.

Das sind Einzelergebnisse, keine Naturgesetze. Sie zeigen aber in dieselbe Richtung wie dieser Text: weniger, gezielter und mit Prüfung. Modelle werden außerdem besser, sodass manche Regel von heute morgen überflüssig ist. Darum gehört zu jedem System auch das Löschen.

Du willst das für dein Team aufsetzen? Wir bauen solche Systeme für uns selbst und für Unternehmen. Schreib uns, dann schauen wir, was sich bei dir lohnt.

Quellen

• Claude Code Docs: How Claude Code works
• Claude Code Docs: How Claude remembers your project
• Claude Code Docs: Extend Claude Code
• Claude Code Docs: Explore the context window
• Claude Code Docs: Skills
• Claude Code Docs: Subagents
• Claude Code Docs: Agent teams
• Claude Code Docs: Hooks reference
• Anthropic: Effective context engineering for AI agents (29.09.2025)
• Marmelab: The State Of AI Harness Engineering 2026
• Gloaguen u. a.: Evaluating AGENTS.md (ETH Zürich)

Die Serie

• KI-Harness 2026: Stand und Prognosen
• Unser Startup Brain
• Die neuesten Ansätze für KI-Agenten
• KI-Agenten und KI-Automatisierung 2026