Agent-Friendly Codebase

Wie große, organisch gewachsene Codebases für KI-Coding-Agenten navigierbar werden

Recherche auf Basis von Primärquellen (offizielle Doku, Specs, First-Party-Blogs, arXiv-Paper) · 28. August 2026

agents.mdCLAUDE.mdRepo MapCode-Graphtree-sitter

TL;DR — Was Agenten am meisten brauchen

Das Kontextfenster ist die harte Währung. Jedes untersuchte System kappt auf ein Token-Budget (aider --map-tokens ≈ 1k, Claude MEMORY.md ≤ 200 Zeilen/25 KB, Cody „first N snippets"). Daraus folgt: Der Wissens-Layer muss rankbar und komprimierbar sein, nicht nur vollständig. Priorisiert, konkret:

Eine vorhersagbare Entry-Instruktionsdatei am Repo-Root (AGENTS.md/CLAUDE.md): Build, Test, Konventionen, Projekt-Layout. Billigster, höchster Hebel.
Conventions/Regeln mit Scope (per-Verzeichnis oder per-Glob), damit Kontext nur bei Bedarf geladen wird — das skaliert den Layer über Monolithen/Monorepos.
ADRs / Architektur-Rationale als Text: nur das „Warum" und die Pitfalls, nicht das, was der Code selbst schon sagt.
Tests als ausführbare Spec (Test-Befehle liegen in der Entry-Datei; Agenten führen sie aus).
Symbol-Index / Repo-Map (tree-sitter): Datei → Symbole → Signaturen; zeigt die zentralen Definitionen des Repos.
Dependency-/Call-Graph mit Graph-Ranking (PageRank-artig), um die wichtigsten Knoten ins Kontextfenster zu heben — nicht alles.
Abfragbarer Graph (Go-to-Definition / Find-References, z. B. SCIP), damit der Agent gezielt navigiert statt zu raten.
Retrieval für NL-Fragen: Code erst in Natural Language übersetzen und funktionsfein chunken (nicht dateiweise) — das entscheidet über die Suchqualität.

1. agents.md — der entstehende offene Standard

Quelle: https://agents.md

Definition: „AGENTS.md is a README for agents" — ein dedizierter, vorhersagbarer Ort für Agenten-Kontext; ergänzt die menschliche README. Über 60k Open-Source-Projekte nutzen es bereits.
Was hinein gehört: Project overview, Build-/Test-Kommandos, Code-Style, Testing-Anleitung, Security-Überlegungen, PR-Regeln.
Nesting: „Large monorepo? Use nested AGENTS.md files for subprojects." Das OpenAI-Hauptrepo trägt zum Erfassungszeitpunkt 88 AGENTS.md-Dateien.
Precedence: „The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything."
Tests als Spec: gelistete Test-Kommandos werden vom Agenten ausgeführt und Fehler vor Abschluss behoben.
Kein Schema, reines Markdown; Interop mit Aider und Gemini CLI dokumentiert.
Stewardship: Agentic AI Foundation / Linux Foundation; u. a. OpenAI Codex, Amp, Jules (Google), Cursor, Factory.

2. Anthropic CLAUDE.md / Agent-Memory

Quelle: https://docs.anthropic.com/en/docs/claude-code/memory

Zwei Gedächtnissysteme, beide bei Session-Start geladen: CLAUDE.md (Mensch schreibt) und Auto memory (Agent schreibt, in ~/.claude/projects/<project>/memory/).
Scopes (breit → spezifisch): managed policy → user → project → local (CLAUDE.local.md).
Wann hineinschreiben: wiederholte Fehler, Review-Monita, wiederkehrende Korrekturen. Nicht hinein: „architecture, file paths, or debugging fixes" — das leitet der Agent aus dem Code ab. → Der Layer speichert Delta-Wissen (Warum, Konventionen, Pitfalls).
Größe: Ziel < 200 Zeilen pro Datei; längere Dateien senken Adhärenz.
Path-scoped Rules (.claude/rules/*.md): YAML-Frontmatter paths: lädt Regeln nur bei passendem Glob — das Mittel gegen Kontext-Rauschen in großen Repos.
Interop mit AGENTS.md: empfohlen @AGENTS.md-Import in CLAUDE.md (oder Symlink).

3. Aider Repository Map

Quellen: https://aider.chat/docs/repomap.html · https://aider.chat/2023/10/22/repomap.html

Was: eine kompakte Karte des gesamten Git-Repos — Dateien plus die wichtigsten Klassen, Funktionen, Typen und Call-Signaturen; wird bei jeder Änderungsanfrage mitgesendet.
Nutzen: Das LLM sieht Signaturen aus dem ganzen Repo und erkennt selbst, welche Dateien es gezielt nachladen muss.
Substrat: automatisch mit tree-sitter gebaut — AST → Definitionen und Referenzen.
Optimierung = Graph-Ranking: Für große Repos wird gekappt: „a graph ranking algorithm … where each source file is a node and edges connect files which have dependencies." Budget --map-tokens (Default 1k).

4. Repository-Level Code Understanding (arXiv)

RepoGraph (arXiv:2410.14684, ICLR 2025): „a plug-in module that manages a repository-level structure" — repository-wide navigation; hebt auf SWE-bench alle getesteten Systeme und erreicht neuen SOTA unter Open-Source-Frameworks.
CodePlan (arXiv:2309.12499): Repo-Level-Aufgaben als Planning-Problem; Kern: incremental dependency analysis + change may-impact analysis. 5/6 Repos bestehen Validity-Checks, Baselines 0/6.
RepoCoder (arXiv:2303.12570, EMNLP 2023): iteratives Retrieval-Generation; +10 % über In-File-Baseline.
RepoBench (arXiv:2306.03091): Benchmark für Repository-Level-Completion (R/C/P).

Gemeinsamer Nenner: Repository-Level-Erfolg hängt an strukturiertem Kontext aus dem ganzen Repo — Graphen, Abhängigkeiten, Retrieval.

5. Code-Wissensgraphen in Produkten

Quellen: Greptile 2.0 · Greptile Semantic Search · Sourcegraph Cody

Greptile

„Greptile … generates a detailed codegraph of how each function, class, file, and directory is connected."
Semantic-Search-Erkenntnis: NL-Query vs. Natural-Language-Beschreibung des Codes schlägt NL-Query vs. Code (Similarity 0.815 vs. 0.728, +12 %).
Funktionsfeines Chunking gewinnt gegen dateiweises Chunking.

Sourcegraph Cody

Kontext-abhängige Fragen sind der Alltag; RAG statt Fine-tuning, weil Code sich schnell ändert.
Retrieval über Code-Intelligence-Plattform: Query → Ranking (adaptiertes BM25 + Signale) → „first N snippets".
Autocomplete: tree-sitter klassifiziert die Absicht und wählt lokale Kontextquellen.
Embeddings bewusst verlassen zugunsten von lexikalisch/symbolischer Suche (Skalierung bei >100k Repos).

6. tree-sitter / SCIP als Substrat

Quellen: tree-sitter · SCIP

tree-sitter: „a parser generator tool and an incremental parsing library" — baut pro Datei einen Concrete Syntax Tree und aktualisiert ihn inkrementell beim Editieren. Dependency-frei, robust bei Syntaxfehlern. Ideales Extraktions-Substrat für Symbole/Signaturen/Referenzen.
SCIP: „a language-agnostic protocol for indexing source code" — treibt Go-to-definition, Find-references, Find-implementations. Protobuf-Schema + Bindings + CLI; Indexer für Java/Scala/Kotlin, TypeScript/JS, Rust, C++/C, Ruby, Python, C#/VB, Dart, PHP.

Synthese — Was KI-Agenten am ehesten brauchen

Priorisiert nach Hebel/Kosten. P0 = billig & sofort, P1 = maschinell generiert & wiederkehrend, P2 = aufwändig & für NL-Zugriff.

P0 — Statische Textschicht (menschengeschrieben, sofort wirksam)

Entry-Point-Map: eine AGENTS.md/CLAUDE.md am Root mit Build-/Test-Kommandos, Projekt-Layout, Konventionen.
Per-Verzeichnis-AGENTS.md für Module; Präzedenz „closest wins" bzw. path-scoped Rules.
Conventions-Datei / Coding-Standards (spezifisch & prüfbar).
ADRs / Architektur-Rationale: nur Warum/Pitfalls/Trade-offs.
Tests als Spec: Test-Befehle zentral ablegen.

P1 — Maschinell generierter Code-Graph

Symbol-Index (tree-sitter): Datei → Klassen/Funktionen/Typen/Signaturen.
Dependency-Graph auf Datei- und Symbol-Ebene; Kanten = Referenzen/Abhängigkeiten.
Graph-Ranking (PageRank-artig), um die wichtigsten Knoten auf ein Token-Budget zu komprimieren.
Change/Impact-Analyse für mehrstufige Edits.
Abfragbarer Graph: Go-to-definition / Find-references als SCIP-Index.

P2 — Retrieval-/NL-Schicht

NL-Index über Code: Code vor dem Embedding in Natural Language übersetzen und funktionsfein chunken.
Hybrides Ranking: lexikalisch/symbolisch (BM25-artig) + Struktur statt reiner Vektor-Suche.
Benchmarks: RepoBench (R/C/P), RepoEval/CrossCodeEval als Messlatte.

Der kleinste tragfähige Kern (Empfehlung)

Root-AGENTS.md mit Build/Test/Conventions + ADRs (P0, quasi kostenlos, sofort).
tree-sitter-basierter Symbol-Index + Datei-Dependency-Graph mit PageRank-Ranking (P1).
Abfragbar machen: Go-to-def/Find-refs über SCIP oder einen eigenen Index auf denselben tree-sitter-Daten (P1).
Erst danach NL-Retrieval mit funktionsfeinen, code→NL übersetzten Chunks (P2).

Quellenübersicht

#	Thema	Quelle
1	AGENTS.md Standard	https://agents.md
2	Claude Code Memory	https://docs.anthropic.com/en/docs/claude-code/memory
3	Aider Repo Map (Doku)	https://aider.chat/docs/repomap.html
3	Aider Repo Map (Blog/Konstruktion)	https://aider.chat/2023/10/22/repomap.html
4	RepoGraph	https://arxiv.org/abs/2410.14684
4	CodePlan	https://arxiv.org/abs/2309.12499
4	RepoCoder	https://arxiv.org/abs/2303.12570
4	RepoBench	https://arxiv.org/abs/2306.03091
5	Greptile 2.0 (Codegraph)	https://www.greptile.com/blog/greptile-2
5	Greptile Semantic Search	https://www.greptile.com/blog/semantic-codebase-search
5	Sourcegraph Cody Kontext	https://sourcegraph.com/blog/how-cody-understands-your-codebase
6	Tree-sitter	https://tree-sitter.github.io/tree-sitter/
6	SCIP	https://raw.githubusercontent.com/sourcegraph/scip/main/README.md