agents.md zu groß? MCP als Lösung

Wer KI-Agenten in der Softwareentwicklung einsetzt, kommt schnell an einen Punkt, an dem die agents.md – die zentrale Steuerdatei für den Agenten-Kontext – unhandlich groß wird. Was als kurze Übersicht begann, wächst in größeren Projekten zu einem mehrtausend Zeilen langen Dokument heran. Das Ergebnis: Der Agent wird langsamer, teurer, und trotzdem ungenauer.

Dieser Beitrag erklärt, warum das passiert – und wie man es besser löst.

Inhaltsverzeichnis

• Was ist agents.md und warum existiert es?
• Warum agents.md in großen Projekten wächst
• Das Context-Window-Problem
• Lösung 1: agents.md aufteilen
• Lösung 2: MCP-Server als Kontext-Lieferant
• Vektordatenbanken: gezieltes Retrieval statt Broadcast
• Praktisches Setup
• Fazit: Kontext ist keine Frage der Menge

Was ist agents.md und warum existiert es?

Das Format agents.md ist eine Konvention für eine Markdown-Datei, die KI-Agenten Kontext über ein Projekt, dessen Architektur, Konventionen und Workflows liefert. Sie funktioniert in VS Code Copilot als copilot-instructions.md, bei Cursor als .cursorrules, in anderen Tools je nach Implementierung unter anderem Namen.

Die Idee dahinter ist einfach: Statt dem Agenten bei jeder Frage dieselben Projektgrundlagen erklären zu müssen, packt man sie einmal in eine Datei. Der Agent liest sie, hat den Kontext, arbeitet besser.

Das funktioniert – solange das Projekt überschaubar ist.

Warum agents.md in großen Projekten wächst

In kleinen Projekten reichen 200–400 Zeilen. In größeren Projekten kommen schnell viele Schichten dazu:

• Architektur-Übersichten mehrerer Services und Subsysteme
• Coding-Konventionen für verschiedene Teams oder Module
• Domänenwissen – fachliche Regeln, die der Agent verstehen muss
• Deployment-Prozesse mit Sonderfällen und Ausnahmen
• Sicherheitsanforderungen und Compliance-Regeln
• Externe Systeme und deren Integration

Jeder Bereich fühlt sich notwendig an. Jede Ergänzung ist irgendwann durch einen Fehler motiviert worden, den der Agent ohne dieses Wissen gemacht hat. Nach einigen Monaten hat man ein Dokument von 5.000, 10.000 oder mehr Zeilen.

Das Context-Window-Problem

Große Sprachmodelle haben ein begrenztes Context-Window – den Speicher, den sie gleichzeitig verarbeiten können. Dieser Speicher ist bei modernen Modellen zwar gewachsen (128k bis 1M Tokens bei einigen Modellen), aber er ist nicht kostenlos:

Mehr Kontext = mehr Token = mehr Kosten und Latenz. Bei API-basierten Modellen steigen die Kosten linear mit dem Input. Außerdem ist empirisch belegt, dass Modelle bei sehr langen Kontexten relevante Informationen in der Mitte schlechter abrufen als am Anfang oder Ende – das sogenannte Lost in the Middle-Problem.

Eine 10.000-Zeilen-agents.md bedeutet also nicht, dass der Agent alles gleich gut nutzt. Er hat einen riesigen Kontext, aber möglicherweise den falschen Teil davon aktiv im Fokus.

Lösung 1: agents.md aufteilen

Der einfachste erste Schritt ist eine strukturierte Aufteilung nach Themen oder Zuständigkeiten:

docs/
  agents/
    architecture.md       # System-Architektur, Service-Übersicht
    conventions.md        # Coding-Standards, Namenskonventionen
    security.md           # Security-Anforderungen, Compliance
    deployment.md         # Deploy-Prozesse, Kubernetes, Helm
    domain.md             # Fachliches Domänenwissen
  agents.md               # Kurze Übersicht + Verweise auf Unterseiten

Die Haupt-agents.md wird zur Navigationsdatei – sie enthält nur das Nötigste und verweist auf spezialisierte Dateien. Werkzeuge wie VS Code Copilot erlauben es, einzelne Dateien gezielt als Kontext beizufügen (#file: oder @workspace).

Vorteile:

• Jede Datei bleibt wartbar und überschaubar
• Teams können ihren Bereich eigenständig pflegen
• Agenten erhalten nur den für ihre Aufgabe relevanten Kontext

Grenzen: Selbst aufgeteilte Dateien müssen noch manuell beim Agenten eingebunden werden. Bei sehr großen Codebasen mit viel proprietärem Wissen stößt man weiterhin an Grenzen.

Lösung 2: MCP-Server als Kontext-Lieferant

Das Model Context Protocol (MCP) ist ein offenes Protokoll, das KI-Agenten ermöglicht, strukturiert externe Datenquellen abzufragen. Statt alles statisch in eine Datei zu schreiben, fragt der Agent zur Laufzeit einen MCP-Server an – und bekommt genau das zurück, was er für die aktuelle Aufgabe braucht.

Ein MCP-Server kann sein:

• Ein lokaler Prozess, der auf einem Verzeichnis oder einer Datenbank läuft
• Ein API-Gateway zu internen Wissensdatenbanken
• Ein Retrieval-Service, der semantisch sucht

Das Ergebnis: Die agents.md wird zur dünnen Konfigurationsdatei, die dem Agenten erklärt, welche MCP-Server er wofür nutzen soll. Das eigentliche Wissen liegt im MCP-Backend – abrufbar, durchsuchbar, versionierbar.

Vektordatenbanken: gezieltes Retrieval statt Broadcast

Der entscheidende Baustein für skalierendes Agenten-Wissen ist ein semantisches Retrieval-System. Vektordatenbanken wie Chroma, Qdrant, Weaviate oder pgvector speichern Texte als hochdimensionale Vektoren und ermöglichen semantische Ähnlichkeitssuche.

Das Prinzip:

1. Indexierung: Eigene Dokumentation, Architektur-Entscheidungen (ADRs), Code-Kommentare, Runbooks, interne Wikis werden in Chunks aufgeteilt und als Vektoren gespeichert.
2. Retrieval: Der Agent stellt eine Anfrage – z.B. “Wie deployen wir Service X in Produktion?” – der MCP-Server sucht semantisch die relevantesten Chunks und gibt nur diese zurück.
3. Nutzung: Der Agent erhält 3–10 hochrelevante Abschnitte statt tausenden Zeilen irrelevanten Kontexts.

Warum das besser skaliert:

Ein praktisches Beispiel: Ein monorepo mit 15 Services hat Architektur-Dokumentation, API-Spezifikationen und sicherheitsrelevante Richtlinien für jeden Service. Statt alles in eine Datei zu laden, indexiert man alle Dokumente in eine Vektordatenbank. Der Agent fragt den MCP-Server: “Zeig mir die API-Spezifikation von Service Y und die zugehörigen Sicherheitsanforderungen.” Er bekommt präzise die 5 relevanten Abschnitte – aus einem Korpus, der 50.000 Seiten umfassen könnte.

Praktisches Setup

Ein einfacher Einstieg ohne eigene Vektordatenbank-Infrastruktur:

Schritt 1: agents.md strukturieren
Trennen nach: Architektur, Konventionen, Deployment, Domain, Security. Jeder Bereich bekommt eine eigene Datei.

Schritt 2: MCP-Server lokal einbinden
VS Code Copilot, Cursor und andere Tools unterstützen MCP. Ein einfacher Filesystem-MCP-Server gibt dem Agenten Zugriff auf strukturierte Dokumentation ohne statischen Upload.

Schritt 3: Vektordatenbank aufbauen (optional, für größere Teams)
Mit Chroma oder Qdrant lokal oder on-premise kann man eigene Dokumente indexieren. Ein Python-Script mit langchain oder llama-index reicht für einen ersten Prototyp.

Schritt 4: MCP-Referenz in agents.md
Die agents.md erklärt dem Agenten, welche MCP-Tools für welche Aufgaben zuständig sind. Statt Inhalt transportiert sie Routing-Wissen.

Fazit: Kontext ist keine Frage der Menge

Eine große agents.md ist kein Zeichen von Reife – sie ist ein Zeichen, dass man das Skalierungsproblem noch nicht gelöst hat. Je größer ein Softwareprojekt wird, desto wichtiger wird gezieltes Kontext-Retrieval statt vollständiger Kontext-Übertragung.

Die Aufteilung nach Themen ist der erste Schritt. MCP-Server mit semantischer Suche über Vektordatenbanken sind der nächste – und sie ermöglichen, dass KI-Agenten auch in sehr großen Projekten präzise und kosteneffizient arbeiten.