Die KI dein Projekt verstehen lassen: Kontext und Regeldateien

Modul 05, Lektion 5 hat gezeigt: Das Modell selbst erinnert sich an nichts, jedes Gespräch beginnt bei null. Bei KI-Programmierwerkzeugen ist es genauso. Gestern hast du ihm eine halbe Stunde lang erklärt: „Unsere Tests laufen mit make test, nicht direkt mit pytest“, und heute, in einem neuen Gespräch, führt es wieder direkt pytest aus.

Die Lösung: Diese „Dinge, die man jedes Mal neu erklären muss“ in eine Datei schreiben, die das Werkzeug bei jedem Start automatisch in den Kontext lädt. Diese Lektion zeigt, wie man diese Datei schreibt.

Wie diese Dateien heißen

Verschiedene Werkzeuge lesen verschiedene Dateien. Stand September 2026 sagen die offiziellen Dokumentationen:

AGENTS.md ist ein offenes Format, das heute von der Agentic AI Foundation unter dem Dach der Linux Foundation gepflegt wird; die Website (agents.md) listet über zwanzig Werkzeuge, die es unterstützen. Die Positionierung ist einfach: Die README ist für Menschen, AGENTS.md für KI-Programmierwerkzeuge.

Die Dokumentation von Claude Code sagt ausdrücklich, dass es CLAUDE.md liest und nicht AGENTS.md. Hat dein Projekt bereits eine AGENTS.md, empfiehlt die offizielle Dokumentation, eine CLAUDE.md anzulegen und darin mit einer Zeile @AGENTS.md die Datei einzubinden; so lesen beide Arten von Werkzeugen denselben Inhalt, und man pflegt nicht zwei Fassungen:

@AGENTS.md

## 只对 Claude Code 生效的补充
改动 src/billing/ 下的代码之前，先进入计划模式。

Dateinamen und Regeln ändern sich mit den Versionen; wirf vor der Nutzung einen Blick in die aktuelle Dokumentation deines Werkzeugs. Die folgende Schreibweise gilt für alle Dateien dieser Art.

Wo sie liegen, und welche Vorrang hat

Solche Dateien kann man meist auf mehreren Ebenen ablegen:

• Persönlich, global: etwa ~/.codex/AGENTS.md oder ~/.claude/CLAUDE.md, für deine persönlichen Vorlieben in allen Projekten.
• Wurzelverzeichnis des Projekts: in git eingecheckt, vom ganzen Team geteilt.
• Unterverzeichnisse: In großen Repositories kann ein Teilprojekt eine eigene Datei haben, die nur bei der Arbeit an Dateien in diesem Verzeichnis gilt.

Gibt es mehrere Dateien zugleich, gilt meist: Je näher an der gerade bearbeiteten Datei, desto höher der Vorrang. Auf der AGENTS.md-Website heißt es wörtlich: „The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything“, also gilt die Datei, die der bearbeiteten Datei am nächsten liegt, und was du direkt im Gespräch sagst, hat den höchsten Vorrang. Codex und Claude Code hängen die Dateien vom Wurzelverzeichnis bis zum aktuellen Verzeichnis der Reihe nach aneinander; je näher am aktuellen Verzeichnis, desto weiter hinten, und spätere Inhalte überschreiben natürlich frühere.

Was hineingehört

Eine Frage entscheidet: Muss man das der KI jedes Mal neu erklären?

Hineinzuschreiben lohnt sich meist Folgendes:

Wie man baut, testet und prüft. Das ist der wichtigste Punkt. Hat die KI Code geändert, soll sie ihn selbst prüfen können. Die konkreten Befehle angeben:

## 命令
- 安装依赖：`uv sync`
- 运行全部测试：`uv run pytest -q`
- 只跑一个文件：`uv run pytest tests/test_retrieval.py -q`
- 代码检查：`uv run ruff check .`

Die Struktur des Projekts. Welcher Code in welchem Verzeichnis liegt, wo der Einstiegspunkt ist. Nur das, was die KI nicht aus den Dateinamen ablesen kann.

Die besonderen Regeln dieses Projekts. Was vom üblichen Vorgehen abweicht, lohnt sich am meisten:

## 约定
- 所有调用大模型的代码都通过 `llm.py` 里的函数，不要直接 new 一个 OpenAI 客户端。
- 价格表在 `llm.PRICES`，改价格只改这一处。
- 用户能看到的文字一律用中文。

Fallen, in die man schon getreten ist. Einen Fehler, den die KI einmal gemacht hat, aufschreiben, damit sie ihn nicht wiederholt:

## 注意
- 检索器里调用本地模型必须持有 `_MODEL_LOCK`，多线程同时调用会互相争抢到几乎卡死。
- `data/httpx-docs/` 是第三方文档的副本，不要修改里面的文件。

Was nicht hineingehört

• Was die KI selbst aus dem Code erfährt. Welche Dateien im Verzeichnis liegen, welche Abhängigkeiten genutzt werden, sieht sie selbst. Das hineinzuschreiben verschwendet nur Kontext.
• Allgemeine Grundsätze. „Qualitativ hochwertigen Code schreiben“, „auf Sicherheit achten“ enthalten nichts Überprüfbares; geschrieben ist so gut wie nicht geschrieben.
• Sehr lange Arbeitsschritte. Lange Abläufe, die nur bei einer bestimmten Art von Aufgabe gebraucht werden, gehören nicht in eine Datei, die jedes Mal gelesen wird. Manche Werkzeuge haben eigene Mechanismen, die bei Bedarf geladen werden (etwa die Skills von Claude Code oder bedingt geltende Regeln in Cursor).
• Geheimnisse. Schlüssel, Passwörter, interne Adressen gehören nie hinein. Diese Datei wird in git eingecheckt und landet im Kontext des Modells.

Die Dokumentation von Claude Code empfiehlt, eine CLAUDE.md unter 200 Zeilen zu halten. Der Grund ist einfach: Die Datei wird jedes Mal komplett in den Kontext geladen; je länger, desto mehr Platz nimmt sie ein, und je mehr Regeln, desto schwerer kann das Modell alle einhalten.

Nur Konkretes wird eingehalten

Zwei Schreibweisen im Vergleich:

Die konkreten Schreibweisen haben etwas gemeinsam: Sie sind überprüfbar. Ob die KI es getan hat, siehst du sofort. Bei vagen Formulierungen glaubt die KI, sie habe es schon getan.

Regeln dürfen sich nicht widersprechen. Sagt die Datei im Wurzelverzeichnis „mit 2 Leerzeichen einrücken“ und die im Unterverzeichnis „mit 4 Leerzeichen“, wählt das Modell womöglich willkürlich eine. Lies diese Dateien regelmäßig durch und streiche Veraltetes und Widersprüchliches.

Regeldateien sind Kontext, kein Zwang

Dieser Punkt ist sehr wichtig und wird am leichtesten missverstanden.

Die offizielle Dokumentation von Claude Code sagt es klar: CLAUDE.md wird dem Modell als Kontext übergeben; das Modell bemüht sich, sie einzuhalten, aber strikte Einhaltung ist nicht garantiert. Es ist keine erzwungene Regel. Schreibst du in die Datei „die Datei .env nicht ändern“, hält sich das Modell meistens daran, aber es gibt immer Ausnahmen.

Das Experiment aus Modul 05, Lektion 8 ist ein guter Vergleich: Sicherheitsregeln, die glasklar im Prompt standen, verletzte das stärkere Modell trotzdem in 4 von 5 Fällen. Regeldateien und Prompts sind im Kern dasselbe.

Was wirklich tabu ist, muss man deshalb mit den Zwangsmechanismen des Werkzeugs beschränken, statt es in die Regeldatei zu schreiben und auf die Einsicht des Modells zu hoffen:

• Berechtigungseinstellungen: Die meisten Werkzeuge lassen sich so konfigurieren, dass bestimmte Befehle und Dateien deine Bestätigung brauchen oder direkt verboten sind. Claude Code etwa kann in den Einstellungen Verbotsregeln haben, Codex eine Sandbox, die nur liest oder nur im Arbeitsbereich schreibt.
• Hooks: Manche Werkzeuge führen zu bestimmten Zeitpunkten automatisch deine Skripte aus, etwa nach jeder Dateiänderung die Formatierung oder vor jedem Befehl eine Prüfung, ob er gefährlich ist. Hooks führt das Programm aus; sie hängen nicht vom Urteil des Modells ab.
• git und Code-Review: Alle Änderungen der KI werden per git eingecheckt, und du siehst sie vor dem Mergen durch. Das ist die letzte und verlässlichste Kontrolle.

In einem Satz: Regeldateien sagen der KI, „wie es besser geht“; Zwangsmechanismen garantieren, „was auf keinen Fall passieren darf“.

Mit einer leeren Datei anfangen

Schreib nicht gleich zu Beginn eine riesige, allumfassende Regeldatei. Besser:

1. Mit dem eingebauten Initialisierungsbefehl des Werkzeugs einen ersten Entwurf erzeugen. Claude Code und Codex haben beide einen Befehl /init, der dein Projekt analysiert und Grundinformationen wie Build-Befehle und Verzeichnisstruktur aufschreibt.
2. Streichen, was die KI selbst aus dem Code erfährt, und ergänzen, was sie nicht weiß: Teamabsprachen, Fallen, in die man getreten ist.
3. Jedes Mal, wenn die KI denselben Fehler zum zweiten Mal macht oder du merkst, dass du im Gespräch wieder dasselbe erklärst, einen Eintrag hinzufügen.

Regeldateien wachsen wie Evaluationsdatensätze nach und nach im Gebrauch.

Übungen

1. Schreib für eines deiner Projekte eine AGENTS.md (oder CLAUDE.md) mit höchstens 50 Zeilen. Geh sie danach mit dem Abschnitt „Was nicht hineingehört“ dieser Lektion durch und streiche.
2. Such eine Regel, die die KI strikt einhalten soll (etwa „das Verzeichnis migrations darf nicht geändert werden“), und prüfe, ob dein KI-Programmierwerkzeug sie zu einer erzwungenen Beschränkung machen kann, statt sie nur in die Regeldatei zu schreiben.
3. Schreib eine AGENTS.md für RepoBot v4 aus diesem Kurs. Überleg: Welche Dinge muss ein KI-Programmierwerkzeug, das dieses Projekt zum ersten Mal öffnet, am dringendsten wissen?

Selbsttest

1. Das Projekt hat bereits eine AGENTS.md. Wie bringt man Claude Code dazu, denselben Inhalt zu lesen?

Claude Code liest CLAUDE.md, nicht AGENTS.md. Laut offizieller Dokumentation legt man eine CLAUDE.md an und bindet mit einer Zeile @AGENTS.md die Datei ein; darunter kann man Inhalte nur für Claude Code ergänzen. Braucht man keine zusätzlichen Inhalte, geht auch ein symbolischer Link auf AGENTS.md.

2. In der Regeldatei steht „die Datei .env nicht ändern“. Ist damit garantiert, dass die KI sie nicht ändert?

Nein. Die Regeldatei wird dem Modell als Kontext übergeben; es bemüht sich, sie einzuhalten, garantiert ist das nicht. Was wirklich tabu ist, muss man mit Zwangsmechanismen wie Berechtigungseinstellungen und Hooks beschränken und jede Änderung per git prüfen.

3. Was lohnt sich in einer Regeldatei am meisten, und was gehört am wenigsten hinein?

Am meisten lohnen sich Informationen, die die KI nicht selbst erkennt, aber jedes Mal braucht: wie man baut und testet (konkrete Befehle), projektspezifische Absprachen, Fallen, in die man getreten ist. Am wenigsten gehören hinein: Dinge, die die KI aus dem Code erfährt, nicht überprüfbare allgemeine Grundsätze und jegliche Schlüssel und Passwörter.