Der Agent widerspricht nicht: Instruktionen in gewachsenen Projekten aufräumen

Projekte, die eine Weile mit Coding-Agenten arbeiten, sammeln Instruktionsdateien wie Keller Kartons: eine CLAUDE.md im Root, eine im Home-Verzeichnis, Regeln pro Unterordner, dazu Notizen, die der Agent selbst hinterlassen hat. Jede Zeile war mal eine Reaktion auf einen konkreten Fehler. Zusammen ergeben sie irgendwann etwas, das kein Mensch mehr am Stück liest. Der Agent dagegen schon, in jeder einzelnen Session.

Nur: Wenn zwei Regeln in so einer Datei einander widersprechen, entscheidet sich das Modell für eine davon. Still, ohne Warnung und ohne Hinweis darauf, dass die andere gerade wirkungslos geworden ist.

Was bei Widersprüchen tatsächlich passiert

Das ist keine Eigenheit eines einzelnen Modells, sondern gut dokumentiert, auch vom Hersteller selbst. Die Claude-Code-Dokumentation formuliert es trocken: Wenn zwei Regeln einander widersprechen, wählt das Modell unter Umständen willkürlich eine aus. Und die Best-Practices-Seite ergänzt, dass aufgeblähte Instruktionsdateien dazu führen, dass Regeln schlicht ignoriert werden.

Die Forschung zeichnet dasselbe Bild, mit Zahlen:

• Das Paper ConInstruct testet, ob Modelle Konflikte in Anweisungen erkennen. Die besten schaffen das erstaunlich gut, mit F1-Werten bis 91,5 Prozent. Nur: Sie sagen es fast nie. Kaum ein Modell weist auf den Konflikt hin oder fragt nach, was denn nun gelten soll.
• Der IH-Benchmark misst über 37 Modelle, wie zuverlässig Anweisungshierarchien eingehalten werden. Die Spannweite reicht von 98,2 bis hinunter zu 20,5 Prozent.
• OpenAIs Paper The Instruction Hierarchy beschreibt, warum Modelle überhaupt Prioritäten zwischen Anweisungsquellen lernen müssen. Der für den Alltag entscheidende Punkt steckt im Umkehrschluss: Zwei Zeilen in derselben Datei liegen auf derselben Hierarchiestufe. Für diesen Fall gibt es keine definierte Rangfolge, also muss das Modell raten.

Wie dieses Raten ausgeht, entscheidet oft die Position der Regel in der Datei. Und je konsistenter ein Modell solche Konflikte auflöst, desto weniger fällt der Widerspruch auf. Früher flackerte das Verhalten zwischen Läufen und machte damit auf sich aufmerksam. Heute verliert dieselbe Regel zuverlässig, in jeder Session, und nichts sieht mehr nach einem Problem aus.

Warum die Position so viel Gewicht hat

Dass die Platzierung einer Regel über ihr Schicksal entscheidet, passt zu einem bekannten Befund: Lost in the Middle zeigte schon 2023, dass Sprachmodelle Informationen am Anfang und Ende eines Kontexts deutlich zuverlässiger nutzen als solche in der Mitte. Anthropic beschreibt den Mechanismus dahinter im Beitrag Effective context engineering for AI agents: Modelle haben ein begrenztes Aufmerksamkeitsbudget, und jedes zusätzliche Token verdünnt es. Die Empfehlung dort ist der Leitsatz für alles Folgende: der kleinste Satz an Tokens, der das gewünschte Verhalten erzeugt.

Eine gewachsene Instruktionsdatei verstößt gegen beides gleichzeitig. Sie ist zu lang, also landet die Hälfte der Regeln in der toten Mitte. Und sie enthält Widersprüche, also entscheidet die Position, welche Hälfte gewinnt.

Das Tutorial: sechs Schritte zum Aufräumen

Schritt 1: Inventur

Finde zuerst heraus, was der Agent überhaupt liest. Bei Claude Code zeigt /context, welche Dateien in der Session geladen sind. Die Dokumentation listet die Ebenen: eine organisationsweite Datei, die persönliche im Home-Verzeichnis, die Projektdatei, lokale Notizen, Regeldateien unter .claude/rules/ und die Notizen, die der Agent sich selbst macht. In gewachsenen Projekten kommen Dateien in Unterordnern dazu, die erst beim Arbeiten dort nachgeladen werden. Erst wenn diese Liste vollständig ist, weißt du, worüber du eigentlich redest.

Schritt 2: Relational lesen, nicht sequenziell

Der zentrale Handgriff: Lies die Dateien nicht von oben nach unten, sondern nach Themen. Sammle alle Regeln, die dasselbe betreffen (Tests, Formatierung, Verzeichnisse, Sprache), egal wo sie stehen und wie sie formuliert sind. Dann stelle für jedes Paar die eine Frage: Können beide gleichzeitig wahr sein? Diese Prüfung braucht kein Modell und keinen Testlauf, nur einen Nachmittag und Ehrlichkeit. Konflikte verstecken sich dabei gern hinter unterschiedlichem Vokabular: „Kommentare“, „Dokumentation“ und „Erläuterungen“ können dieselbe Sache meinen und trotzdem drei verschiedene Regeln tragen.

Schritt 3: Kürzen, bis es wehtut

Für jede verbliebene Zeile die Frage aus den Best Practices: Würde der Agent ohne diese Zeile Fehler machen? Wenn nein, weg damit. Verzeichnisstruktur, Abhängigkeiten, Standardkonventionen der Sprache: Alles, was das Modell aus dem Code selbst ablesen kann, kostet Aufmerksamkeit, ohne etwas zu kaufen. Die Dokumentation nennt als Zielgröße unter 200 Zeilen pro Datei. Achte dabei auf die Flughöhe: Regeln, die konkret genug sind, um sie zu überprüfen („2 Leerzeichen Einrückung“), aber nicht so kleinteilig, dass sie zu einer brüchigen Sammlung von Sonderfällen werden.

Schritt 4: Ein Thema, eine Stelle

Jedes Thema bekommt genau eine Überschrift und ein Vokabular. Eine Ausnahme gehört in denselben Satz wie ihre Regel („jede Funktion braucht einen Test, außer unter scratch/“), nicht drei Absätze weiter unten als eigene Anweisung. Getrennt formuliert sind Regel und Ausnahme für das Modell zwei konkurrierende Regeln, und welche gewinnt, entscheidet die Position.

Schritt 5: Verbindlichkeit sortieren

Instruktionsdateien sind Kontext, keine Konfiguration; das Modell versucht sie zu befolgen, mehr nicht. Für alles, was immer gelten muss, ist Prosa das falsche Werkzeug. Claude Code bietet dafür Hooks, die deterministisch ausgeführt werden, egal was das Modell entscheidet. Wissen, das nur manchmal gebraucht wird, gehört in Skills oder pfadgebundene Regeln, die erst laden, wenn sie relevant sind. Übrig bleibt der kleine Kern, der wirklich in jede Session gehört. Der ist dann kurz genug, um befolgt zu werden.

Schritt 6: Wie Code behandeln

Eine Instruktionsdatei, die niemand wartet, verrottet wie Code, den niemand wartet, nur leiser. Wenn der Agent trotz Regel wiederholt dasselbe falsch macht, ist der erste Verdächtige nicht das Modell, sondern die Datei: zu lang, zu vage oder in sich widersprüchlich. Prüfe Änderungen wie Codeänderungen: Verschiebt sich das Verhalten tatsächlich? Und wiederhole Schritt 2 in Abständen, denn jede hastig ergänzte Zeile nach einem Vorfall ist ein Kandidat für den nächsten Widerspruch.

Fazit

Unbequem an diesem Thema ist nicht, dass Modelle mit Widersprüchen schlecht umgehen. Unbequem ist, wie gut sie darin geworden sind, sie geräuschlos aufzulösen. Die Forschung zeigt Modelle, die Konflikte erkennen und trotzdem schweigen, und die Praxis zeigt Regeln, die je nach Zeilennummer gelten oder nicht. Darauf zu warten, dass der Agent sich beschwert, ist keine Strategie. Die Datei relational zu lesen, kostet einen Nachmittag. Der stille Verlust einer Regel, von der du dachtest, sie gilt, kostet mehr.

Quellen

• Claude Code: How Claude remembers your project, offizielle Dokumentation zu CLAUDE.md, Regeln und Auto-Memory
• Claude Code: Best practices, offizielle Empfehlungen zu Instruktionsdateien, Hooks und Kontext
• Anthropic: Effective context engineering for AI agents, Aufmerksamkeitsbudget, Flughöhe von Regeln, minimaler Kontext
• Liu et al.: Lost in the Middle: How Language Models Use Long Contexts, Positionsbias in langen Kontexten (TACL 2023)
• Wallace et al.: The Instruction Hierarchy, warum Modelle Prioritäten zwischen Anweisungsquellen brauchen (OpenAI, 2024)
• IH-Benchmark: A Conflict-Centered Benchmark for Instruction-Hierarchy Robustness, Hierarchie-Compliance von 37 Modellen im Vergleich
• He et al.: ConInstruct: Evaluating LLMs on Conflict Detection and Resolution, Modelle erkennen Konflikte, melden sie aber selten