Große Codebases mit Claude Code und Codex sicher navigieren

Wenn du eine große Codebase öffnest, ist das erste Ziel nicht, jede Datei zu verstehen. Das erste Ziel ist eine Karte: Wo startet das System, welche Ordner sind generiert, welche Dateien tragen Geschäftsrisiko, und welche Zuständigkeitsgrenzen darfst du nicht ohne Review überschreiten?

Claude Code und Codex helfen bei dieser Erkundung, aber nur mit Disziplin. Wenn du komplette Dateien, lange Logs und hunderte Suchtreffer in die Hauptunterhaltung kopierst, entsteht mehr Text, aber nicht automatisch mehr Klarheit. Kontext-Bloat bedeutet: Die Unterhaltung wird länger, während die Dichte nützlicher Entscheidungsinformationen sinkt.

Diese Anleitung übersetzt meinen Workflow für Handoffs, Audits und ClaudeCodeLab-Artikelpflege in kopierbare Befehle und Prompt-Pakete. Für Tool-Verhalten verweise ich auf offizielle Dokumentation: Claude Code common workflows, CLI reference, memory, Codex non-interactive mode und Codex AGENTS.md.

Mit Einer Repo-Karte Starten

Bevor du einen Agenten das Repository erklären lässt, reduziere zuerst selbst die äußere Form. rg steht für ripgrep. Es ist schnell, respektiert gängige Ignore-Regeln und kann generierte Ordner ausschließen, bevor sie die Analyse verunreinigen.

git status --short
git rev-parse --show-toplevel
git branch --show-current

rg --files \
  -g '!*node_modules*' \
  -g '!dist' \
  -g '!build' \
  -g '!coverage' \
  -g '!*.lock' \
  | sed 's#^[^/]*/##' \
  | sort \
  | uniq -c \
  | sort -nr \
  | head -40

find . -maxdepth 3 \( \
  -name package.json -o \
  -name pnpm-workspace.yaml -o \
  -name pyproject.toml -o \
  -name go.mod -o \
  -name Cargo.toml -o \
  -name Dockerfile -o \
  -name docker-compose.yml -o \
  -name AGENTS.md -o \
  -name CLAUDE.md \
\) -print

Danach fragst du nach einer Read-only-Karte. Die offiziellen Claude-Code-Workflows empfehlen, mit breiten Fragen zu beginnen und danach auf konkrete Komponenten einzugrenzen. Die Codex-Dokumentation beschreibt, dass codex exec standardmäßig in einer read-only sandbox läuft, also gut für die erste Repository-Zusammenfassung passt.

codex exec "Read only. Summarize the repository map: apps, packages, entrypoints, test commands, generated folders, and files that define project rules. Do not edit files."

In Claude Code nutzt du -p, wenn du eine nicht-interaktive Antwort willst. Die CLI-Referenz beschreibt das als print mode.

claude -p "
Read only. Erstelle eine Repo-Karte für diese Codebase.
Antworte in dieser Reihenfolge:
1. Apps, packages und services
2. Runtime-, Test- und Build-Entrypoints
3. Generierte Ordner und Ordner, die ignoriert werden sollten
4. Wichtigste Punkte aus AGENTS.md, CLAUDE.md, README und Designnotizen
5. Die nächsten 10 Dateien, die gelesen werden sollten, jeweils mit Grund
Schlage Edits oder Befehle nur vor; führe sie nicht aus.
"

Suche In Schichten

Ein Texttreffer ist noch kein Verständnis. Suche erzeugt Kandidaten. Nutze fünf Schichten: Struktur, Domänenvokabular, Referenzen, Konfiguration und Historie.

# 1. Entrypoint-Kandidaten
rg -n "createServer|listen\(|app\.use|router\.|main\(|bootstrap|hydrateRoot|createRoot" \
  src apps packages server web

# 2. Domänenvokabular. Passe diese Begriffe an dein Produkt an.
rg -n "Auth|Billing|Invoice|Notification|Search|FeatureFlag" \
  src apps packages test tests

# 3. Aufrufer und Referenzen für den Bereich, den du ändern könntest
rg -n "AuthService|useAuth|requireAuth|authMiddleware" \
  src apps packages test tests

# 4. Konfiguration und Umgebungsvariablen
rg -n "process\.env|import\.meta\.env|PUBLIC_|DATABASE_URL|JWT|STRIPE|OPENAI|ANTHROPIC" \
  . -g '!node_modules' -g '!dist' -g '!build'

# 5. Historie: warum dieses Design existiert
git log --oneline --decorate --date=short --max-count=30 -- src/auth packages/auth

Kopiere nicht hundert Treffer in den Agenten. Prüfe zuerst die Form und gib dann eine kleine Kandidatenliste zur Klassifikation weiter.

Du bist Reviewer für Codebase-Navigation.
Klassifiziere diese rg-Treffer als Implementierungs-Entrypoint, Aufrufer, Konfiguration, Test oder Rauschen.
Begrenze jede Klasse auf die 5 wichtigsten Dateien, die als Nächstes gelesen werden sollten.
Gib für jede gewählte Datei einen konkreten Grund.
Wenn etwas unklar ist, schreibe "braucht weitere Suche" statt zu raten.

Eine Leichte Abhängigkeitskarte Skizzieren

Bevor du ein vollständiges Analysewerkzeug installierst, kann ein kleines Node-Skript genug Signal liefern. Es ist kein TypeScript-Compiler. Es verfolgt nur lokale relative Imports, reicht aber oft für den direkten Impact-Radius.

#!/usr/bin/env node
import { execFileSync } from "node:child_process";
import { readFileSync } from "node:fs";
import path from "node:path";

const target = process.argv[2]?.replace(/\\/g, "/");
if (!target) {
  console.error("Usage: node scripts/dependency-map.mjs src/path/to/file.ts");
  process.exit(1);
}

const tracked = execFileSync("git", ["ls-files"], { encoding: "utf8" })
  .split(/\r?\n/)
  .filter(Boolean)
  .map((file) => file.replace(/\\/g, "/"));

const trackedSet = new Set(tracked);
const sourceFiles = tracked.filter((file) => /\.(mjs|cjs|js|jsx|ts|tsx)$/.test(file));
const importPattern =
  /(?:from\s+["']([^"']+)["']|import\s*\(\s*["']([^"']+)["']\s*\)|require\s*\(\s*["']([^"']+)["']\s*\))/g;

function resolveLocalImport(specifier, fromFile) {
  if (!specifier.startsWith(".")) return null;
  const base = path.normalize(path.join(path.dirname(fromFile), specifier)).replace(/\\/g, "/");
  const candidates = [
    base,
    `${base}.ts`,
    `${base}.tsx`,
    `${base}.js`,
    `${base}.jsx`,
    `${base}/index.ts`,
    `${base}/index.tsx`,
    `${base}/index.js`,
  ];
  return candidates.find((candidate) => trackedSet.has(candidate)) ?? base;
}

const incoming = [];
for (const file of sourceFiles) {
  const source = readFileSync(file, "utf8");
  for (const match of source.matchAll(importPattern)) {
    const resolved = resolveLocalImport(match[1] || match[2] || match[3], file);
    if (resolved && (resolved === target || resolved.endsWith(`/${path.basename(target)}`))) {
      incoming.push(file);
    }
  }
}

console.log(`Target: ${target}`);
console.log("Direct importers:");
for (const file of incoming.sort()) console.log(`- ${file}`);

Speichere und führe es aus.

mkdir -p scripts
$EDITOR scripts/dependency-map.mjs
node scripts/dependency-map.mjs src/services/AuthService.ts

Danach wird die Ausgabe zu einer Risikokarte.

Bewerte anhand dieser direct importers den Impact-Radius einer Änderung an AuthService.ts.
Nutze high / medium / low.
High bedeutet Authentifizierung, Billing, Autorisierung, Persistenz oder öffentliches API-Verhalten.
Liste pro Klasse Tests und Konfigurationsdateien, die vor einem Edit gelesen werden sollten.

Von Entrypoints Aus Tracen

Eine Dateiliste erklärt kein Laufzeitverhalten. Für ein Backend trace request, middleware, route, controller, service, repository, database. Für ein Frontend trace route, loader, state, API client, component und analytics.

rg -n "middleware|loader|action|controller|handler|route|repository|service" \
  src apps packages \
  -g '*.ts' -g '*.tsx' -g '*.js' -g '*.jsx'

rg -n "fetch\(|axios|graphql|trpc|prisma|drizzle|sequelize|typeorm" \
  src apps packages \
  -g '*.ts' -g '*.tsx' -g '*.js' -g '*.jsx'

Bitte den Agenten um eine Flow-Tabelle, nicht um einen Absatz.

Perspektive	Starke Ausgabe	Schwache Ausgabe
Einstieg	POST /login -> auth route -> AuthService.login	”Auth ist wichtig”
Zustand	Cookie, session, DB, cache oder queue Mutation	Keine Zustandsänderungen
Fehler	Error response, logging, audit event, retry	Nur happy path
Tests	Existierende Tests und fehlende Fälle	Generisches “Tests hinzufügen”

Trace den Login-Flow vom Entrypoint bis zur Persistenz.
Gib eine Tabelle zurück mit: Reihenfolge, Datei, Funktion/Klasse, Zustandsänderung, Fehlerverhalten, Tests zum Lesen.
Fülle Lücken nicht mit Vermutungen. Wenn ein Schritt unklar ist, nenne die nächste Datei zur Prüfung.

Ownership Und Risiko Kartieren

In einem großen Repository lautet die erste Frage nicht “läuft es?”, sondern “wessen Grenze ist das?”. Ownership-Grenzen können Team-, Daten-, Release-, Compliance- oder Umsatzgrenzen sein.

find . -maxdepth 4 \( \
  -name CODEOWNERS -o \
  -name OWNERS -o \
  -name README.md -o \
  -name AGENTS.md -o \
  -name CLAUDE.md \
\) -print

rg -n "owner|maintainer|deprecated|legacy|do not edit|generated|migration|rollback|release" \
  . -g '!node_modules' -g '!dist' -g '!build'

Codex liest offiziell AGENTS.md, daher lohnt es sich, Projektregeln dort abzulegen. Claude Code kann CLAUDE.md und memory nutzen, um spätere Sessions kürzer zu machen. Für eine ausführlichere Vorlage siehe CLAUDE.md Best Practices.

## Codebase map

### Entry points
- Web: apps/web/src/main.tsx
- API: services/api/src/server.ts
- Jobs: services/jobs/src/index.ts

### Ownership boundaries
- services/payments: owned by payments team; never change schema without migration review.
- packages/ui: shared design system; visual regression test required.
- legacy/: read-only unless the issue is production severity.

### High-risk files
- services/api/src/auth/AuthService.ts: login, session rotation, audit log.
- packages/db/schema.ts: migrations affect API and jobs.
- apps/web/src/routes/checkout.tsx: revenue path and analytics.

### Handoff notes
- Always start with rg search, then read top files.
- Prefer small diffs with tests.
- Do not paste large logs into the main conversation; summarize first.

Read-only Explorer Prompts Nutzen

Für die erste Erkundung sollte der Agent beratend bleiben. Du brauchst Karte, Hypothesen und Unbekannte, bevor Dateien geändert werden.

Untersuche read-only. Bearbeite keine Dateien, füge keine Abhängigkeiten hinzu, formatiere keinen Code und führe keine Tests aus.

Ziel:
Implementierungsumfang und Änderungsrisiko für [Feature-Name] verstehen.

Gib zurück:
1. Entrypoint-Dateien
2. Zentrale Datenmodelle
3. Direkte und indirekte Abhängigkeiten
4. Ownership-Grenzen
5. Risikokarte: high / medium / low
6. Dateien für die nächste Inspektion
7. Noch nicht bestätigte Hypothesen

Regeln:
Kennzeichne Vermutungen als Hypothesen.
Nenne Dateinamen und Evidenz.
Zitiere keine großen Dateikörper.

Claude-Code-Subagents sind nützlich, wenn Exploration die Hauptunterhaltung mit File Reads füllen würde. Die offizielle Dokumentation beschreibt, dass Subagents in ihrem eigenen Kontext arbeiten und nur eine Zusammenfassung zurückgeben. Codex dokumentiert subagents ebenfalls für parallele Codebase-Erkundung. Setze enge Grenzen, weil auch Subagents Tokens verbrauchen. Praktische Muster stehen in Subagent Patterns.

Starte drei read-only Subagents:
1. API-Entrypoints und Auth-Grenzen
2. DB-Schema und Migration-Grenzen
3. UI-Routen und Umsatzpfad

Jeder Subagent darf maximal 8 Dateien lesen und gibt nur finale Findings zurück.
Danach führt der Parent-Agent Duplikate, Konflikte und Unbekannte zusammen.

Kontext-Bloat Vermeiden

Die einfache Regel: Trenne Evidenz von Entscheidungen. Ganze Dateien, lange Logs und hundert Suchtreffer sind zu schwer. Erst filtern, dann entscheiden lassen.

OpenAIs compaction ist eine API-Funktion, aber das Betriebsprinzip passt auch hier: Notwendige Zusammenfassung behalten, veraltete Details fallen lassen.

Komprimiere die Untersuchung auf unter 300 Wörter, damit die nächste Person weiterarbeiten kann.
Behalte:
- Bestätigte Entrypoints
- High-risk Dateien
- Grenzen, die nicht überschritten werden dürfen
- Unbestätigte Hypothesen
- Nächster auszuführender Befehl

Entferne:
- Bereits widerlegte Hypothesen
- Lange Logs
- Generierte Dateien, die nicht gelesen werden müssen

Handoff-Notizen sind für Entwicklung und Content-Betrieb wichtig. Bei mehrsprachigen Artikeln notiere die eigenen Locale-Dateien. Bei App-Arbeit notiere den getraceten Entrypoint. Bei Bugs notiere verworfene Hypothesen. Kombiniere das mit Claude Code Testing Strategies und dem Approval- und Sandbox-Guide.

Drei Konkrete Use Cases

Erstens: SaaS-Handoff. Am ersten Tag kartierst du Login, Billing, Admin und Notifications. Finde Importers von AuthService und BillingService, dann trace Checkout von der Route bis zur Datenbank. Noch nicht editieren. Das Ergebnis ist eine Risikokarte und Lesereihenfolge.

Zweitens: Legacy-Migration. Suche nach legacy, deprecated und migration, bevor du Ersatzcode anforderst. Frage nach Kompatibilitätsrisiken. DB-Migrationen, öffentliche APIs, Batch Jobs und Cron verdienen besondere Vorsicht, weil Rollback teuer ist.

Drittens: Eine Content- und Monetarisierungsseite wie ClaudeCodeLab. Artikel, CTA-Komponenten, interne Links, Produktseiten und Übersetzungen liegen in verschiedenen Ordnern. Arbeite pro Slug. Der Agent soll nur einen Slug besitzen und andere Artikel nur zur Linkprüfung nutzen.

Häufige Fehler

• Nur dem README vertrauen. Echte Entrypoints driften oft von alter Doku weg.
• Suchtreffer als Execution Flow behandeln. Ein Treffer ist ein Kandidat, kein Beweis.
• Den Agenten editieren lassen, bevor Ownership klar ist.
• Generierte Ordner, Lockfiles, Coverage oder dist in die Unterhaltung geben.
• Subagents mit zu breitem Scope starten.
• “Sicher fixen” sagen, ohne high / medium / low zu definieren.

CTA Für Teams

Navigation in großen Codebases beeinflusst auch Umsatzarbeit. Checkout, Lead-Formulare, Paid Content, Analytics und Ads liegen hinter Risiko- und Ownership-Grenzen. Eine Karte vor dem Edit reduziert Nacharbeit.

Wenn dein Team Claude Code oder Codex einführt, starte mit einer Repo-Map-Vorlage, AGENTS.md/CLAUDE.md-Regeln, Review-Kriterien und Read-only-Prompts. Einzelne Entwickler können mit dem kostenlosen Cheat Sheet beginnen. Für Training an echten Repositories gibt es Claude Code Training und Consulting.

Praxisnotiz

Wenn ich diesen Workflow nutze, werden spätere Implementierungs-Prompts stabiler als beim Start mit großen eingefügten Dateien. Die nützlichsten Artefakte sind Repo-Karte, klassifizierte rg-Ergebnisse, eine kleine Abhängigkeitstabelle und die high / medium / low Risikokarte. Wenn ich diese Schritte überspringe, landen generierte Ordner, alte Tests und Module anderer Teams in der Unterhaltung. Vor Veröffentlichung habe ich Befehle, Prompt-Pakete und Node-Skript auf Kopierbarkeit und grundlegende JavaScript-Struktur geprüft.