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
- Erstmaliges Öffnen eines Projekts mit Claude Code
- Beitritt zu einem neuen Team oder Repository
- Benutzer fragt: „Hilf mir, diese Codebasis zu verstehen“
- Benutzer möchte eine CLAUDE.md für ein Projekt generieren
- Benutzer sagt: „Onboarde mich“ oder „Führe mich durch dieses Repository“
Funktionsweise
Phase 1: Aufklärung
Sammle rohe Signale über das Projekt, ohne jede Datei zu lesen. Führe diese Prüfungen parallel aus:
1. Paketmanifest-Erkennung
→ package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml, build.gradle,
Gemfile, composer.json, mix.exs, pubspec.yaml
2. Framework-Fingerabdruck
→ next.config.*, nuxt.config.*, angular.json, vite.config.*,
django settings, flask app factory, fastapi main, rails config
3. Identifikation von Einstiegspunkten
→ main.*, index.*, app.*, server.*, cmd/, src/main/
4. Verzeichnisstruktur-Schnappschuss
→ Die oberen 2 Ebenen der Verzeichnisstruktur, 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: Architektur-Mapping
Aus den Aufklärungsdaten identifizieren:
Tech-Stack
- Sprache(n) und Versionsbeschränkungen
- Framework(s) und wichtige Bibliotheken
- Datenbank(en) und ORMs
- Build-Tools und Bundler
- CI/CD-Plattform
Architekturmuster
- Monolith, Monorepo, Microservices oder Serverless
- Frontend/Backend-Aufteilung oder Full-Stack
- API-Stil: REST, GraphQL, gRPC, tRPC
Wichtige Verzeichnisse Ordne die oberen Verzeichnisse ihrem Zweck zu:
src/components/ → React-UI-Komponenten
src/api/ → API-Routen-Handler
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, Schemas, Guards)
- Wo liegt die Geschäftslogik? (Services, Modelle, Use Cases)
- Wie erreicht sie die Datenbank? (ORM, rohe Abfragen, Repositories)
Phase 3: Konventionserkennung
Identifiziere Muster, die die Codebasis bereits befolgt:
Namenskonventionen
- Dateibenennung: kebab-case, camelCase, PascalCase, snake_case
- Komponenten-/Klassenbenennungsmuster
- Testdateibenennung:
*.test.ts,*.spec.ts,*_test.go
Codierungsmuster
- Fehlerbehandlungsstil: try/catch, Result-Typen, Fehlercodes
- Dependency Injection oder direkte Importe
- State-Management-Ansatz
- Asynchrone Muster: Callbacks, Promises, async/await, Channels
Git-Konventionen
- Branch-Namensgebung aus aktuellen Branches
- Commit-Nachrichten-Stil aus aktuellen Commits
- PR-Workflow (Squash, Merge, Rebase)
- Wenn das Repository noch keine Commits hat oder nur eine flache Historie (z.B.
git clone --depth 1), überspringe diesen Abschnitt und notiere: „Git-Verlauf 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]
## Überblick
[2-3 Sätze: Was dieses Projekt tut und für wen es gedacht ist]
## Tech-Stack
<!-- Beispiel für ein Next.js-Projekt — ersetze mit erkanntem Stack -->
| Schicht | Technologie | Version |
|---------|-------------|---------|
| Sprache | TypeScript | 5.x |
| Framework | Next.js | 14.x |
| Datenbank | PostgreSQL | 16 |
| ORM | Prisma | 5.x |
| Tests | Jest + Playwright | - |
## Architektur
[Diagramm oder Beschreibung, wie Komponenten verbunden sind]
## Wichtige Einstiegspunkte
<!-- Beispiel für ein Next.js-Projekt — ersetze mit erkannten Pfaden -->
- **API-Routen**: `src/app/api/` — Next.js-Routen-Handler
- **UI-Seiten**: `src/app/(dashboard)/` — authentifizierte Seiten
- **Datenbank**: `prisma/schema.prisma` — Quelle der Wahrheit für das Datenmodell
- **Konfiguration**: `next.config.ts` — Build- und Laufzeitkonfiguration
## Verzeichniszuordnung
[Oberes Verzeichnis → Zweck-Zuordnung]
## Anfrage-Lebenszyklus
[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 — ersetze mit erkannten Befehlen -->
- **Dev-Server starten**: `npm run dev`
- **Tests ausführen**: `npm test`
- **Linter ausführen**: `npm run lint`
- **Datenbank-Migrationen**: `npx prisma migrate dev`
- **Für Produktion bauen**: `npm run build`
## Wo suchen
<!-- Beispiel für ein Next.js-Projekt — ersetze mit erkannten Pfaden -->
| Ich möchte... | Schau in... |
|----------------|-------------|
| 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: Erste CLAUDE.md
Generiere oder aktualisiere eine projektspezifische CLAUDE.md basierend auf erkannten Konventionen. Wenn bereits eine CLAUDE.md existiert, lies sie zuerst und erweitere sie – bewahre vorhandene projektspezifische Anweisungen und hebe klar hervor, was hinzugefügt oder geändert wurde.
# Projektanweisungen
## Tech-Stack
[Zusammenfassung des erkannten Stacks]
## Codestil
- [Erkannte Namenskonventionen]
- [Erkannte zu befolgende Muster]
## Tests
- Tests ausführen: `[erkannter Testbefehl]`
- Testmuster: [erkannte Testdateikonvention]
- Abdeckung: [falls konfiguriert, der Abdeckungsbefehl]
## Build & Ausführen
- Dev: `[erkannter Dev-Befehl]`
- Build: `[erkannter Build-Befehl]`
- Lint: `[erkannter Lint-Befehl]`
## Projektstruktur
[Wichtiges Verzeichnis → Zweck-Zuordnung]
## Konventionen
- [Commit-Stil, falls erkennbar]
- [PR-Workflow, falls erkennbar]
- [Fehlerbehandlungsmuster]
Best Practices
- Nicht alles lesen — die Aufklärung sollte Glob und Grep verwenden, nicht jede Datei lesen. Lies nur selektiv bei mehrdeutigen Signalen.
- Ü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 existiert, erweitere sie anstatt sie zu ersetzen. Hebe hervor, was neu ist gegenüber dem Bestehenden.
- Kurz bleiben — der Onboarding-Leitfaden sollte in 2 Minuten überflogen werden können. Details gehören in den Code, nicht in den Leitfaden.
- Unbekanntes kennzeichnen — wenn eine Konvention nicht sicher erkannt werden kann, sage dies anstatt zu raten. „Testsuite konnte nicht ermittelt werden“ ist besser als eine falsche Antwort.
Anti-Patterns, die vermieden werden sollten
- Generierung einer CLAUDE.md, die länger als 100 Zeilen ist — halte sie fokussiert
- Jede Abhängigkeit auflisten — hebe nur die hervor, die die Art des Codenschreibens beeinflussen
- Offensichtliche Verzeichnisnamen beschreiben —
src/benötigt keine Erklärung - Die README kopieren — der Onboarding-Leitfaden fügt strukturelle Erkenntnisse hinzu, die die README nicht bietet
Beispiele
Beispiel 1: Erstmaliges Betreten eines neuen Repositorys
Benutzer: „Onboarde mich für diese Codebasis“
Aktion: Vollständigen 4-Phasen-Workflow ausführen → Onboarding-Leitfaden + Erste CLAUDE.md erstellen
Ausgabe: Onboarding-Leitfaden direkt in die Konversation ausgegeben, plus eine CLAUDE.md im Projektstammverzeichnis geschrieben
Beispiel 2: CLAUDE.md für ein bestehendes Projekt generieren
Benutzer: „Generiere eine CLAUDE.md für dieses Projekt“
Aktion: Phasen 1-3 ausführen, Onboarding-Leitfaden überspringen, nur CLAUDE.md erstellen
Ausgabe: Projektspezifische CLAUDE.md mit erkannten Konventionen
Beispiel 3: Vorhandene CLAUDE.md erweitern
Benutzer: „Aktualisiere die CLAUDE.md mit den aktuellen Projektkonventionen“
Aktion: Vorhandene CLAUDE.md lesen, Phasen 1-3 ausführen, neue Erkenntnisse zusammenführen
Ausgabe: Aktualisierte CLAUDE.md mit klar markierten Ergänzungen