Was macht codebase-onboarding?
Analysiere systematisch eine unbekannte Codebasis und erstelle einen strukturierten Onboarding-Leitfaden. Entwickelt für Entwickler, die einem neuen Projekt beitreten oder Claude Code zum ersten Mal in einem bestehenden Repository einrichten.
Wann verwenden
- Erstes Öffnen eines Projekts mit Claude Code
- Beitritt zu einem neuen Team oder Repository
- Benutzer fragt: „Hilf mir, diese Codebasis zu verstehen“
- Benutzer fragt: „Generiere eine CLAUDE.md für ein Projekt“
- Benutzer sagt: „Onboarde mich“ oder „Führe mich durch dieses Repo“
Wie es funktioniert
Phase 1: Aufklärung
Sammle rohe Signale über das Projekt, ohne jede Datei zu lesen. Führe diese Prüfungen parallel durch:
1. Paketmanifest-Erkennung
→ package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml, build.gradle,
Gemfile, composer.json, mix.exs, pubspec.yaml
2. Framework-Fingerprinting
→ next.config.*, nuxt.config.*, angular.json, vite.config.*,
django settings, flask app factory, fastapi main, rails config
3. Einstiegspunkt-Identifizierung
→ main.*, index.*, app.*, server.*, cmd/, src/main/
4. Verzeichnisstruktur-Schnappschuss
→ Die obersten 2 Ebenen des Verzeichnisbaums, ignoriere node_modules, vendor,
.git, dist, build, __pycache__, .next
5. Konfigurations- und Tool-Erkennung
→ .eslintrc*, .prettierrc*, tsconfig.json, Makefile, Dockerfile,
docker-compose*, .github/workflows/, .env.example, CI-Konfigurationen
6. Teststruktur-Erkennung
→ tests/, test/, __tests__/, *_test.go, *.spec.ts, *.test.js,
pytest.ini, jest.config.*, vitest.config.*
Phase 2: Architekturzuordnung
Aus den Aufklärungsdaten identifizieren:
Tech-Stack
- Sprache(n) und Versionsbeschränkungen
- Framework(s) und Hauptbibliotheken
- Datenbank(en) und ORMs
- Build-Tools und Bundler
- CI/CD-Plattform
Architekturmuster
- Monolith, Monorepo, Microservices oder serverlos
- Frontend/Backend-Aufteilung oder Full-Stack
- API-Stil: REST, GraphQL, gRPC, tRPC
Schlüsselverzeichnisse Ordne die obersten Verzeichnisse ihrem Zweck zu:
src/components/ → React-UI-Komponenten
src/api/ → API-Routenhandler
src/lib/ → Gemeinsame Hilfsprogramme
src/db/ → Datenbankmodelle und Migrationen
tests/ → Testsuiten
scripts/ → Build- und Bereitstellungsskripte
Datenfluss Verfolge eine Anfrage vom Einstieg bis zur Antwort:
- Wo tritt eine Anfrage ein? (Router, Handler, Controller)
- Wie wird sie validiert? (Middleware, Schemata, Guards)
- Wo befindet sich die Geschäftslogik? (Services, Modelle, Use Cases)
- Wie erreicht sie die Datenbank? (ORM, rohe Abfragen, Repositories)
Phase 3: Konventionserkennung
Erkenne Muster, denen die Codebasis bereits folgt:
Namenskonventionen
- Dateibenennung: kebab-case, camelCase, PascalCase, snake_case
- Komponenten-/Klassenbenennungsmuster
- Testdateibenennung:
*.test.ts,*.spec.ts,*_test.go
Codemuster
- Fehlerbehandlungsstil: try/catch, Result-Typen, Fehlercodes
- Abhängigkeitsinjektion oder direkte Importe
- State-Management-Ansatz
- Asynchrone Muster: Callbacks, Promises, async/await, Channels
Git-Konventionen
- Branch-Namensgebung anhand aktueller Branches
- Commit-Nachrichten-Stil anhand aktueller Commits
- PR-Workflow (Squash, Merge, Rebase)
- Wenn das Repo noch keine Commits oder nur eine flache Historie hat (z. B.
git clone --depth 1), überspringe diesen Abschnitt und vermerke: „Git-Historie nicht verfügbar oder zu flach, um Konventionen zu erkennen“
Phase 4: Onboarding-Artefakte generieren
Erzeuge zwei Ausgaben:
Ausgabe 1: Onboarding-Leitfaden
# Onboarding-Leitfaden: [Projektname]
## Übersicht
[2-3 Sätze: Was dieses Projekt tut und für wen es gedacht ist]
## Tech-Stack
<!-- Beispiel für ein Next.js-Projekt – durch erkannten Stack ersetzen -->
| Ebene | Technologie | Version |
|-------|-------------|---------|
| Sprache | TypeScript | 5.x |
| Framework | Next.js | 14.x |
| Datenbank | PostgreSQL | 16 |
| ORM | Prisma | 5.x |
| Testen | Jest + Playwright | - |
## Architektur
[Diagramm oder Beschreibung, wie Komponenten verbunden sind]
## Wichtige Einstiegspunkte
<!-- Beispiel für ein Next.js-Projekt – durch erkannte Pfade ersetzen -->
- **API-Routen**: `src/app/api/` — Next.js-Routenhandler
- **UI-Seiten**: `src/app/(dashboard)/` — authentifizierte Seiten
- **Datenbank**: `prisma/schema.prisma` — Datenmodell-Quelle der Wahrheit
- **Konfiguration**: `next.config.ts` — Build- und Laufzeitkonfiguration
## Verzeichniszuordnung
[Top-Level-Verzeichnis → Zweck-Zuordnung]
## Anfragelebenszyklus
[Verfolge eine API-Anfrage vom Einstieg bis zur Antwort]
## Konventionen
- [Dateibenennungsmuster]
- [Fehlerbehandlungsansatz]
- [Testmuster]
- [Git-Workflow]
## Häufige Aufgaben
<!-- Beispiel für ein Node.js-Projekt – durch erkannte Befehle ersetzen -->
- **Dev-Server starten**: `npm run dev`
- **Tests ausführen**: `npm test`
- **Linter ausführen**: `npm run lint`
- **Datenbankmigrationen**: `npx prisma migrate dev`
- **Für Produktion bauen**: `npm run build`
## Wo suchen
<!-- Beispiel für ein Next.js-Projekt – durch erkannte Pfade ersetzen -->
| Ich möchte... | Schauen Sie bei... |
|--------------|-------------------|
| Einen API-Endpunkt hinzufügen | `src/app/api/` |
| Eine UI-Seite hinzufügen | `src/app/(dashboard)/` |
| Eine Datenbanktabelle hinzufügen | `prisma/schema.prisma` |
| Einen Test hinzufügen | `tests/` entsprechend des Quellpfads |
| Build-Konfiguration ändern | `next.config.ts` |
Ausgabe 2: Starter-CLAUDE.md
Generiere oder aktualisiere eine projektspezifische CLAUDE.md basierend auf erkannten Konventionen. Wenn CLAUDE.md bereits existiert, lies sie zuerst und erweitere sie – behalte vorhandene projektspezifische Anweisungen bei und kennzeichne deutlich, was hinzugefügt oder geändert wurde.
# Projektanweisungen
## Tech-Stack
[Erkannter Stack – Zusammenfassung]
## Codestil
- [Erkannte Namenskonventionen]
- [Erkannte Muster, die zu befolgen sind]
## Testen
- Tests ausführen: `[erkannter Testbefehl]`
- Testmuster: [erkannte Testdateikonvention]
- Abdeckung: [falls konfiguriert, der Abdeckungsbefehl]
## Build & Ausführung
- Dev: `[erkannter Dev-Befehl]`
- Build: `[erkannter Build-Befehl]`
- Lint: `[erkannter Lint-Befehl]`
## Projektstruktur
[Schlüsselverzeichnis → Zweck-Zuordnung]
## Konventionen
- [Commit-Stil, falls erkennbar]
- [PR-Workflow, falls erkennbar]
- [Fehlerbehandlungsmuster]
Best Practices
- Nicht alles lesen – Aufklärung sollte Glob und Grep verwenden, nicht Read auf jeder Datei. Lies nur selektiv, wenn Signale mehrdeutig sind.
- Überprüfen, nicht raten – Wenn ein Framework anhand der Konfiguration erkannt wird, der tatsächliche Code aber etwas anderes verwendet, vertraue dem Code.
- Vorhandene CLAUDE.md respektieren – Wenn bereits eine vorhanden ist, erweitere sie, anstatt sie zu ersetzen. Kennzeichne, was neu ist vs. vorhanden.
- Kurz und bündig bleiben – Der Onboarding-Leitfaden sollte in 2 Minuten durchsuchbar sein. Details gehören in den Code, nicht in den Leitfaden.
- Unbekanntes kennzeichnen – Wenn eine Konvention nicht sicher erkannt werden kann, sag es, anstatt zu raten. „Test-Runner konnte nicht ermittelt werden“ ist besser als eine falsche Antwort.
Zu vermeidende Antipatterns
- Eine CLAUDE.md generieren, die länger als 100 Zeilen ist – konzentriert bleiben
- Jede Abhängigkeit auflisten – nur die hervorheben, die die Art und Weise der Codeentwicklung prägen
- Offensichtliche Verzeichnisnamen beschreiben –
src/braucht keine Erklärung - Die README kopieren – der Onboarding-Leitfaden bietet strukturelle Einblicke, die der README fehlen
Beispiele
Beispiel 1: Zum ersten Mal in einem neuen Repository
Benutzer: „Onboarde mich in diese Codebasis“
Aktion: Führe vollständigen 4-Phasen-Workflow aus → produziere Onboarding-Leitfaden + Starter-CLAUDE.md
Ausgabe: Onboarding-Leitfaden direkt in die Konversation ausgegeben, plus eine CLAUDE.md, die in das Projektstammverzeichnis geschrieben wird
Beispiel 2: CLAUDE.md für ein bestehendes Projekt generieren
Benutzer: „Generiere eine CLAUDE.md für dieses Projekt“
Aktion: Führe Phasen 1-3 aus, überspringe Onboarding-Leitfaden, produziere nur CLAUDE.md
Ausgabe: Projektspezifische CLAUDE.md mit erkannten Konventionen
Beispiel 3: Vorhandene CLAUDE.md erweitern
Benutzer: „Aktualisiere die CLAUDE.md mit den aktuellen Projektkonventionen“
Aktion: Lies vorhandene CLAUDE.md, führe Phasen 1-3 aus, füge neue Erkenntnisse zusammen
Ausgabe: Aktualisierte CLAUDE.md mit deutlich gekennzeichneten Ergänzungen