Context Engineering und AGENTS.md: Was der Agent wissen muss

Eine Vorlage für den Anfang und ein Blick in die Regeldatei von kopfwelt.com

Veröffentlicht
Kategorien
KI

Inhalt

Ein Coding-Agent weiß zu Beginn jeder Sitzung nichts über ein Projekt. Context Engineering heißt, festzulegen, welche Informationen er sieht, bevor er den nächsten Schritt macht: Befehle, Regeln, Dateien, Zwischenstände. Je genauer diese Auswahl, desto weniger muss ein Mensch hinterher korrigieren.

Der einfachste Einstieg ist eine AGENTS.md: eine Markdown-Datei im Wurzelverzeichnis des Repositorys, die viele Coding-Agenten automatisch lesen. Sie enthält, was ein neues Teammitglied am ersten Tag erfahren müsste, nur knapper. Eine Vorlage steht weiter unten, danach ein Beispiel aus dem Betrieb von kopfwelt.com.

Dieser Artikel gehört zur Serie über die Agentic Software Factory. Die Regeldatei ist dort ein Baustein des Harness, also der Umgebung, in der ein Agent arbeitet.

Vom Prompt zum Kontext: was sich am Begriff ändert

Prompt Engineering meint die Formulierung einer einzelnen Anweisung. Anthropic beschreibt es als Methoden, um Anweisungen an ein Sprachmodell zu schreiben und zu ordnen. Context Engineering ist weiter gefasst: Es geht um alle Informationen, die während der Arbeit im Kontextfenster des Modells liegen, und darum, diese Auswahl über viele Schritte hinweg zu pflegen.

Der Begriff wurde im Juni 2025 bekannt. Shopify-Chef Tobi Lütke beschrieb ihn als die Kunst, so viel Kontext bereitzustellen, dass eine Aufgabe für das Sprachmodell plausibel lösbar wird. Andrej Karpathy griff ihn wenige Tage später auf. Quelle: Simon Willison, Context engineering, 27. Juni 2025.

Für Coding-Agenten ist der Unterschied praktisch. Ein Agent arbeitet eine Aufgabe in vielen Schritten ab. Er liest Dateien, führt Befehle aus, sammelt Fehlermeldungen. Was davon im Kontext bleibt, entscheidet, ob er sich am Ende noch an die Regel vom Anfang hält.

Mehr Kontext ist nicht besser

Sprachmodelle haben laut Anthropic ein begrenztes Aufmerksamkeitsbudget. Mit jeder Information im Kontextfenster sinkt die Fähigkeit, sich an einzelne Inhalte genau zu erinnern. Anthropic nennt das Context Rot. Die Empfehlung lautet deshalb, die kleinste Menge an aussagekräftigen Informationen zu finden, die das gewünschte Ergebnis am wahrscheinlichsten macht. Quelle: Anthropic, Effective context engineering for AI agents, 29. September 2025.

Claude Code arbeitet nach Anthropics Beschreibung gemischt. Die Regeldatei CLAUDE.md wird zu Beginn vollständig geladen. Alles andere holt sich der Agent bei Bedarf selbst, etwa über Dateisuche. Für längere Aufgaben kommen drei Techniken dazu:

  • Verdichten: Ein fast volles Kontextfenster wird zusammengefasst, die Arbeit geht mit der Zusammenfassung weiter.

  • Notizen außerhalb des Kontexts: Der Agent schreibt Zwischenstände in eine Datei und liest sie später wieder.

  • Subagenten: Teilaufgaben laufen in eigenen Agenten mit leerem Kontext, zurück kommt nur das Ergebnis.

Die Regeldatei ist also kein Ablageort für alles Wissen über das Projekt. Sie enthält das, was in jeder Sitzung gebraucht wird und was der Agent nicht selbst im Code findet.

AGENTS.md: eine Datei, die viele Werkzeuge lesen

AGENTS.md ist laut der Projektseite ein einfaches, offenes Format, um Coding-Agenten anzuleiten. Betreut wird es von der Agentic AI Foundation unter dem Dach der Linux Foundation. Die Seite nennt mehr als 60.000 Open-Source-Projekte, die eine solche Datei verwenden. Sie listet über 20 Werkzeuge, darunter Codex von OpenAI, Cursor, GitHub Copilot, Gemini CLI, Jules, Zed und VS Code. Quelle: agents.md, Abruf 22.11.2026.

Das Format ist bewusst schlicht:

  • Keine Pflichtfelder. Es ist normales Markdown mit beliebigen Überschriften.

  • Die nächste Datei gilt. In einem Monorepo kann jedes Teilprojekt eine eigene AGENTS.md haben. Der Agent liest die, die der bearbeiteten Datei am nächsten liegt.

  • Der Chat geht vor. Eine ausdrückliche Anweisung im Gespräch überstimmt die Datei.

Claude Code liest standardmäßig CLAUDE.md. Fehlt sie, liest es inzwischen auch eine AGENTS.md. Gibt es beide, gilt nur die CLAUDE.md, es sei denn, sie bindet die AGENTS.md mit @AGENTS.md ein. So lässt sich eine Datei für mehrere Werkzeuge pflegen. Quelle: Anthropic, How Claude remembers your project, Abruf 22.11.2026.

Eine Vorlage für den Anfang

Die Projektseite empfiehlt Abschnitte zu Überblick, Build- und Testbefehlen, Code-Stil, Tests und Sicherheit. Die folgende Vorlage folgt dem und ergänzt zwei Abschnitte, die sich in der Praxis bewährt haben: Regeln mit Grund und den Weg, eine Änderung zu prüfen.

# AGENTS.md

## Projekt
Was die Anwendung tut, für wen, in einem Absatz.
Technik: Framework, Sprache, Datenbank, Hosting.

## Befehle
- Abhängigkeiten installieren: `pnpm install`
- Entwicklungsserver: `pnpm dev`
- Alle Tests: `pnpm test`
- Ein einzelner Test: `pnpm vitest run test/datei.test.ts`
- Linter und Typen: `pnpm lint`, `pnpm exec tsc --noEmit`

## Aufbau
Wo was liegt. Nur die Verzeichnisse, die man nicht am Namen erkennt.

## Regeln (mit Grund)
- Regel in einem Satz. Grund in einem Satz, wenn möglich mit Datum
  des Vorfalls und dem Test, der die Regel festhält.

## Eine Änderung prüfen
- Welche Befehle vor einem Pull Request grün sein müssen.
- Wie man das Ergebnis im Browser oder gegen einen Build prüft.

## Was der Agent nicht tut
- Nichts veröffentlichen, nichts auf main pushen.
- Keine Geheimnisse ausgeben; Zugangsdaten nur aus Umgebungsvariablen.

## Pull Requests
Titelformat, was in die Beschreibung gehört (Befund, Änderung, Prüfung).

Wichtiger als die Gliederung ist der Abschnitt „Regeln mit Grund“. Eine Regel ohne Grund befolgt ein Agent, solange sie passt. Eine Regel mit Grund kann er auf einen Fall übertragen, den die Regel nicht ausdrücklich nennt.

Was hineingehört und was nicht

In die Datei gehört, was der Agent nicht selbst herausfinden kann oder was er ohne Hinweis falsch machen würde:

  • Befehle, die vom Standard abweichen, zum Beispiel ein Entwicklungsserver mit HTTPS.

  • Regeln, deren Verletzung erst spät auffällt, etwa im Production-Build oder bei der Ladezeit.

  • Fallen, in die schon einmal jemand getreten ist, mit Datum und Test.

  • Wie man prüft, ob eine Änderung funktioniert.

Nicht hinein gehört, was der Linter ohnehin durchsetzt, was im Code offensichtlich ist, allgemeine Stilregeln ohne Projektbezug und jede Form von Zugangsdaten. Auch ganze Handbücher gehören nicht hinein. Ein Verweis auf die Datei genügt, der Agent liest sie, wenn er sie braucht.

Ein Beispiel: die Regeldatei von kopfwelt.com

Die Website kopfwelt.com entsteht seit Oktober 2025 mit Claude Code. Ihre CLAUDE.md hat am 22. November 2026 1.070 Zeilen in 20 Abschnitten. Die meisten Abschnitte beschreiben einen Teil der Anwendung: Caching, Rate Limits von Storyblok, Markdown für Agenten, strukturierte Daten, Übergänge. Wie der Ablauf insgesamt aussieht, zeigt der Fallbericht zu kopfwelt.com.

Drei Muster tragen die Datei. Das erste: Eine Regel steht mit ihrem Grund und dem Test, der sie festhält. Ein gekürzter Auszug:

### Bundling constraint — the most important invariant in this repo

The Storyblok component map must never be imported from the
layout's module graph. [...] Violating this pulls every client
component into the shared first-load JS.

test/server-purity.test.ts enforces this.

Das zweite Muster: Vorfälle stehen mit Datum. Eine Regel zu Builds gegen veröffentlichte Inhalte nennt den 10. November 2026, an dem der Production-Build abbrach, obwohl der Build gegen Entwürfe durchgelaufen war. Der Agent erfährt so, dass die Regel kein Stil ist, sondern einen Ausfall verhindert.

Das dritte: Die Datei sagt, was der Agent nicht „reparieren“ soll. Über die Tests heißt es, die meisten hielten einen früheren Fehler fest, und der Kopfkommentar nenne ihn. Man solle ihn lesen, bevor man eine fehlschlagende Prüfung anpasst. Auch der Umgang mit Zugangsdaten steht dort: Ein Token wird innerhalb des Befehls aus der Datei gelesen und nie ausgegeben.

Gepflegt wird die Datei im selben Pull Request wie der Code. Wer eine Regel ändert, ändert ihren Abschnitt mit.

Wo eine Regeldatei an Grenzen stößt

Die Dokumentation von Claude Code empfiehlt weniger als 200 Zeilen je CLAUDE.md. Längere Dateien verbrauchen mehr Kontext und werden weniger zuverlässig befolgt. Die Datei von kopfwelt.com liegt mit 1.070 Zeilen weit darüber. Sie funktioniert, aber sie zeigt das Problem: Jede Sitzung lädt Wissen über Übergänge, auch wenn es um einen Tippfehler im Footer geht.

Für diesen Fall gibt es Werkzeuge. In Claude Code lassen sich Regeln in .claude/rules/ auf bestimmte Pfade beschränken, sodass sie nur geladen werden, wenn der Agent dort arbeitet. Anleitungen für seltene Aufgaben passen besser in Skills, die nur bei Bedarf geladen werden. Wie man fremde Skills prüft, bevor man sie einsetzt, steht im Artikel Agent Skills prüfen.

Die zweite Grenze ist grundsätzlich. Eine Regeldatei ist Kontext, keine Durchsetzung. Anthropic schreibt das ausdrücklich: Was unabhängig von der Entscheidung des Agenten verhindert werden soll, gehört in eine technische Sperre, etwa einen Hook vor dem Werkzeugaufruf oder eine Rechte-Einstellung. Was ein Agent dürfen sollte und was nicht, behandelt der Artikel zum Agent Harness.

Wie wir Regeldatei, Tests und Freigabe für ein Team zusammen einrichten, steht auf der Seite zu KI-gestützter Softwareentwicklung.

Häufige Fragen zu Context Engineering und AGENTS.md

Was ist der Unterschied zwischen Prompt Engineering und Context Engineering?

Prompt Engineering formuliert eine einzelne Anweisung. Context Engineering legt fest, welche Informationen ein Modell während der ganzen Arbeit sieht: Regeldateien, gelesene Dateien, Werkzeugergebnisse, Notizen und Zusammenfassungen. Bei Agenten, die viele Schritte machen, ist das zweite die größere Aufgabe.

Was gehört in eine AGENTS.md?

Was ein Agent nicht selbst im Code findet: abweichende Befehle, Regeln mit ihrem Grund, bekannte Fallen und der Weg, eine Änderung zu prüfen. Die Projektseite agents.md nennt Überblick, Build- und Testbefehle, Code-Stil, Tests und Sicherheit als typische Abschnitte. Zugangsdaten gehören nie hinein.

Brauche ich AGENTS.md und CLAUDE.md?

Nicht zwingend. Claude Code liest eine AGENTS.md, wenn keine CLAUDE.md vorhanden ist. Wer beide Werkzeugwelten bedienen will, pflegt die Inhalte in der AGENTS.md und bindet sie in der CLAUDE.md mit @AGENTS.md ein. Dann gibt es eine Quelle für alle Agenten.

Wie lang darf eine Regeldatei sein?

Die Dokumentation von Claude Code nennt weniger als 200 Zeilen als Ziel. Was nur für einen Teil des Codes gilt, gehört in pfadbezogene Regeln, was nur selten gebraucht wird, in Skills. Eine längere Datei funktioniert, kostet aber in jeder Sitzung Kontext.

Hält sich der Agent immer an die Regeldatei?

Nein. Die Datei ist Kontext und wird meistens befolgt, aber sie ist keine Sperre. Was auf keinen Fall passieren darf, etwa ein Push auf den Hauptzweig oder eine Veröffentlichung, wird technisch verhindert: über Rechte, Hooks oder Schutzregeln im Repository.

Quellen

  1. Anthropic: Effective context engineering for AI agents, 29. September 2025.

  2. Simon Willison: Context engineering, 27. Juni 2025. Mit den Zitaten von Tobi Lütke und Andrej Karpathy.

  3. AGENTS.md, Projektseite des Formats, Abruf 22.11.2026.

  4. Anthropic: How Claude remembers your project, Dokumentation zu CLAUDE.md, AGENTS.md und Regeln, Abruf 22.11.2026.

  5. Anthropic: Hooks, Dokumentation zu Claude Code, Abruf 22.11.2026.

  6. Regeldatei CLAUDE.md von kopfwelt.com (privates Repository), Stand 22.11.2026.