Architekturdoku war schon immer KI-Kontext.

Eine Studie hat 328 CLAUDE.md-Dateien aus echten Open-Source-Projekten analysiert – Repositories mit mindestens 100 Sternen auf GitHub, aktiv genutzt, echte Produktionscode. Das Ergebnis ist so wenig überraschend, dass es fast schon komisch ist.

Was steckt drin in diesen Dateien, die Entwickler für ihre KI-Coding-Agenten schreiben?

Conventions. Guidelines. Project Information. Architecture.

Klingt bekannt? Das sind exakt die Inhalte, die wir seit Jahren in arc42-Templates schreiben, in Architecture Decision Records festhalten, in C4-Diagrammen visualisieren. Wir erfinden das Rad neu – in Dateien mit anderem Namen.

Das Ökosystem der Agent-Konfigurationsdateien

Bevor wir tiefer einsteigen: ein kurzer Überblick, wovon wir reden.

CLAUDE.md ist Anthropics Format für Claude Code. Die Datei liegt im Projektroot und wird vor jeder Session automatisch geladen. Sie enthält was der Agent über das Projekt wissen muss: Verzeichnisstruktur, Coding Conventions, Build-Befehle, Architekturentscheidungen.

AGENTS.md ist das offene, toolübergreifende Äquivalent – entstanden aus einer Zusammenarbeit zwischen OpenAI Codex, Cursor, Amp und anderen. Es wird mittlerweile von der Agentic AI Foundation unter der Linux Foundation gepflegt. Das Ziel: ein Format, das mit jedem Agent funktioniert, unabhängig vom Hersteller.

Cursor Rules und GitHub Copilot Instructions sind die jeweiligen Pendants für Cursor und Copilot – konzeptionell identisch, nur anders benannt.

Der Inhalt? Überall gleich.

Was die Forschung zeigt

Die Studie “Decoding the Configuration of AI Coding Agents” von Forschern der Universität Montreal und der Polytechnique Montreal hat sich durch 328 reale CLAUDE.md-Dateien gearbeitet und kategorisiert, was Entwickler ihren Agenten mitgeben.

Das Ergebnis in Kategorien: Development Guidelines dominieren (Code Style, Conventions, Workflow), gefolgt von Project Information (Verzeichnisstruktur, Tech Stack, Domain-Konzepte) und Architecture (Modulstruktur, Entscheidungen, Constraints).

Was auffällt: Manifests are dominated by operational commands, architectural notes, and workflow conventions – eine Beobachtung, die sich mit einer zweiten Studie zu Agent-Konfigurationsdateien deckt. Beide kommen unabhängig voneinander zum selben Schluss.

Das ist keine Überraschung. Es ist eine Bestätigung von etwas, das Software-Architekten schon lange wissen: Wer Code versteht – ob Mensch oder Maschine –, braucht Kontext. Warum existiert dieses Modul? Welche Constraints gelten? Welche Entscheidungen wurden aus welchen Gründen getroffen?

”AI needs context, but so do we”

Ken Mugrage von Thoughtworks bringt es auf den Punkt: “AI needs context, but so do we.”

Der neue Entwickler im Team braucht dieselbe Information wie der KI-Agent: Wo liegt was? Warum wurde so entschieden? Welche Constraints gelten? Welche Technologien werden wie eingesetzt?

Der Unterschied ist ein einziger, aber entscheidender: Der neue Kollege fragt nach. Der Agent halluziniert.

Ein Agent ohne Kontext ist nicht einfach langsamer oder weniger präzise – er erfindet Antworten. Er wählt die Bibliothek, die er aus dem Training kennt, nicht die, die im Projekt Standard ist. Er entscheidet sich für Microservices, weil er nicht weiß, dass ihr euch bewusst für einen Modulithen entschieden habt. Er nutzt AWS, obwohl ihr aus Kostengründen bei Hetzner seid.

Das ist kein KI-Problem. Das ist ein Dokumentationsproblem.

ADRs sind das Killer-Feature

Von allen Dokumentationsformaten sind Architecture Decision Records (ADRs) für KI-Agenten besonders wertvoll – und das aus einem einfachen Grund: Sie enthalten das Warum.

Ein ADR beschreibt nicht nur, was entschieden wurde. Es beschreibt den Kontext der Entscheidung, die betrachteten Alternativen, und die Begründung warum Option A gegenüber Option B gewählt wurde. Warum Hetzner statt AWS. Warum PostgreSQL statt MongoDB. Warum ein Modulith statt Microservices.

Dieses “Warum” kann kein Agent aus dem Code ableiten. Der Code zeigt das Ergebnis einer Entscheidung, nicht ihre Begründung. Aber ein Agent, der das ADR kennt, kann bei zukünftigen Entscheidungen konsistent bleiben – und vor allem: er kann neue Entscheidungen im gleichen Geist treffen.

Ein konkretes Beispiel: Ihr habt entschieden, keine externen Abhängigkeiten für UI-Komponenten einzuführen, weil das Projekt in einer regulierten Banking-Umgebung betrieben wird und jede neue Dependency einen Sicherheits-Review erfordert. Diese Information steht nirgends im Code. Aber in einem ADR. Ohne dieses ADR im Kontext wird der Agent beim nächsten Feature munter eine neue Komponentenbibliothek installieren.

Von der Projektdoku zum wiederverwendbaren Wissen: Skills

CLAUDE.md und ADRs dokumentieren dieses Projekt. Es gibt aber eine Ebene drüber – Wissen, das projektübergreifend gilt und trotzdem strukturiert verfügbar sein soll.

Genau das ist das Konzept hinter Skills.md-Dateien, wie sie Claude Code und ähnliche Agenten unterstützen. Eine Skill-Datei ist kein Projektkontext, sondern kondensiertes Fachwissen: “Wie generieren wir barrierefreie Navigationskomponenten”, “Wie bauen wir GDPR-konforme Analytics-Integrationen”, “Wie erstellen wir DOCX-Dokumente mit python-docx”.

Der entscheidende Unterschied zu CLAUDE.md: Skills werden lazy-loaded. Der Agent liest beim Start nur den Namen und die kurze Beschreibung jeder Skill-Datei. Den vollständigen Inhalt lädt er erst, wenn er ihn für die aktuelle Aufgabe braucht. Das hält den Kontext schlank und die Qualität hoch.

.claude/
  skills/
    barrierefreiheit-navigation.md   <- wird geladen wenn Navigation gebaut wird
    analytics-gdpr.md                <- wird geladen wenn Tracking implementiert wird
    docx-generierung.md              <- wird geladen wenn Dokumente erstellt werden
CLAUDE.md                            <- wird immer geladen
docs/decisions/                      <- ADRs, werden bei Bedarf referenziert

Was das für die These bedeutet: Nicht nur Architekturdokumentation ist KI-Kontext. Auch das implizite Fachwissen eures Teams – die Patterns, die jeder kennt aber niemand aufgeschrieben hat – kann als Skill formalisiert werden. Einmal dokumentiert, steht es jedem Agenten im Team konsistent zur Verfügung.

Der neue Kollege profitiert genauso. Denn eine gut geschriebene Skill-Datei ist gleichzeitig eine Anleitung für Menschen.

Was das konkret bedeutet

Wer bereits Architekturdokumentation pflegt, hat den halben Weg schon hinter sich. Was fehlt, ist oft keine neue Arbeit – sondern eine andere Ablage.

Doku muss im Repository liegen. Nicht in Confluence. Nicht in Notion. Nicht im Kopf des Lead-Architekten. Nicht in einem Visio-Diagramm, das auf einem SharePoint liegt. Der Agent liest das Repository – und nur das.

Doku muss maschinenlesbar sein. Markdown, AsciiDoc, PlantUML – alles was Text ist. Mermaid für Diagramme direkt im Markdown. Ein PNG-Export eurer Architekturübersicht bringt dem Agenten nichts.

Doku muss aktuell sein. Ein veraltetes ADR, das eine längst revidierte Entscheidung dokumentiert, ist schlimmer als gar kein ADR – weil der Agent ihm vertraut. Das gilt für menschliche Leser genauso, aber bei Menschen gibt es einen Abgleich mit der Realität. Beim Agenten nicht.

Ein pragmatischer Einstieg

Ihr müsst nicht sofort arc42 vollständig einführen. Ein pragmatischer Einstieg:

Legt eine CLAUDE.md oder AGENTS.md im Projektroot an. Schreibt rein, was ein neuer Entwickler am ersten Tag wissen müsste: Tech Stack, Verzeichnisstruktur, wie man baut und testet, welche Conventions gelten.

Legt ein /docs/decisions/-Verzeichnis an. Schreibt das nächste Mal, wenn ihr eine nicht-triviale Architekturentscheidung trefft, ein kurzes ADR dazu. Drei Abschnitte reichen: Kontext, Entscheidung, Begründung.

Das ist kein Aufwand, der zusätzlich zum Projekt kommt. Das ist Aufwand, der das Projekt langfristig günstiger macht – für neue Entwickler, für zukünftige Wartung, und jetzt auch für eure KI-Agenten.

Fazit

Die KI-Coding-Tools haben ein neues Bewusstsein für ein altes Problem geschaffen: Dokumentation, die nicht gepflegt wird, bremst das Team. Nur ist der Schmerz jetzt schneller spürbar.

Ein Mensch überbrückt fehlende Doku mit Nachfragen, mit Code-Lesen, mit Erfahrung. Ein Agent überbrückt sie mit Halluzinationen. Das macht das Problem sichtbarer – und den Anreiz zur Lösung größer.

Wer seine Architekturdokumentation ernst nimmt, wird feststellen: Sie war schon immer KI-Kontext. Nur hieß die KI bisher “der neue Kollege”.

Quellen & weiterführende Links

• Studie: Castellucci et al. – Decoding the Configuration of AI Coding Agents: Insights from Claude Code Projects (2025) · arxiv.org/abs/2511.09268
• Studie: Ferreira et al. – On the Use of Agentic Coding Manifests: An Empirical Study of Claude Code (2025) · arxiv.org/abs/2509.14744
• Ken Mugrage / Thoughtworks: Technology Radar Vol. 32 – Eintrag zu “AI-assisted architecture documentation”
• arc42: Dokumentationstemplate für Softwarearchitektur · arc42.org
• ADRs: Michael Nygard – Documenting Architecture Decisions (2011) · cognitect.com
• AGENTS.md: Offenes Format für Agent-Konfigurationsdateien · agents.md
• Anthropic: Using CLAUDE.md files · claude.com/blog