Claude Code für Codebase-Onboarding: Verwende Q&A-Prompts, um Module, wichtige Flüsse und Risiken zu kartieren und daraus ein kurzes Onboarding-Dokument zu erstellen.
Dateien zufällig zu lesen fühlt sich langsam an, weil die meisten Codebasen nicht wie eine Geschichte organisiert sind. Sie öffnen einen Ordner, sehen zehn Namen, die wichtig aussehen, klicken einen an und landen bei Helfern, Konfigurationen und Randfällen. Nach einer Stunde haben Sie viele Details, können aber immer noch nicht erklären, wie die App funktioniert.
Ein besseres Ziel für Claude Code beim Onboarding ist, eine einfache mentale Karte zu erstellen. Diese Karte sollte drei Fragen beantworten:
Ein "gutes genug" Onboarding in 1–2 Tagen heißt nicht: „Ich kann jede Klasse erklären.“ Es sieht eher so aus:
Einige Dinge können warten. Tiefe Refactorings, das perfekte Verständnis jeder Abstraktion und das Lesen alten Codes, den niemand anfasst, bringen selten den schnellsten Nutzen.
Betrachten Sie Onboarding als Kartenerstellung, nicht als Auswendiglernen von Straßen. Ihre Prompts sollten Sie immer wieder zurückfragen lassen: „Wo bin ich im System, was passiert als Nächstes und was könnte hier schiefgehen?“ Sobald Sie das haben, sind Details leichter on-demand zu lernen.
Bevor Sie Fragen stellen, sammeln Sie die Basics, die Sie normalerweise am ersten Tag brauchen. Claude Code funktioniert am besten, wenn es auf echte Dateien, echte Konfiguration und reproduzierbares Verhalten reagieren kann.
Beginnen Sie mit Zugang und einem laufenden System. Stellen Sie sicher, dass Sie das Repo klonen, Abhängigkeiten installieren und die App lokal (oder zumindest einen kleinen Teil davon) starten können. Wenn die lokale Einrichtung schwer ist, verschaffen Sie sich Zugriff auf eine Staging-Umgebung und dahin, wo Logs liegen, damit Sie verifizieren können, was der Code tatsächlich macht.
Finden Sie als Nächstes die „Source of truth“-Dokumente. Sie suchen nach dem, was das Team tatsächlich aktualisiert, wenn sich etwas ändert: ein README, eine kurze Architektur-Notiz, ein ADR-Ordner, ein Runbook oder eine Deployment-Notiz. Auch wenn sie unordentlich sind, geben sie Namen für Module und Flüsse, was Q&A deutlich präziser macht.
Definieren Sie den Scope früh. Viele Repos enthalten mehrere Apps, Services und Shared-Packages. Wählen Sie Grenzen wie „nur die API und den Billing-Worker“ oder „nur die Web-App und ihren Auth-Flow.“ Klarer Scope verhindert endlose Abschweifungen.
Schreiben Sie Annahmen auf, die der Assistent nicht erraten soll. Das klingt klein, verhindert aber falsche mentale Modelle, die später Stunden kosten.
Hier eine einfache Prep-Checkliste:
Wenn etwas fehlt, notieren Sie es als Frage an ein Teammitglied. Versuchen Sie nicht, fehlenden Kontext mit Vermutungen zu überbrücken.
Eine mentale Karte ist eine kleine Sammlung von Notizen, die beantwortet: Was sind die Hauptteile dieser App, wie sprechen sie miteinander und wo kann etwas schiefgehen. Gut gemachtes Onboarding geht weniger ums Durchsuchen von Dateien und mehr darum, ein wiederverwendbares Bild zu bauen.
Beginnen Sie mit der Definition Ihrer Outputs. Sie wollen eine Modul-Liste, die praktisch ist, nicht perfekt. Für jedes Modul halten Sie fest, was es tut, wer es besitzt (Team oder Person, falls bekannt) und seine wichtigsten Abhängigkeiten (andere Module, Services, Datenbanken, externe APIs). Notieren Sie auch die Haupteinstiegspunkte: UI-Routen, API-Endpunkte, Hintergrundjobs und geplante Aufgaben.
Wählen Sie als Nächstes ein paar Benutzerreisen, die wichtig sind. Drei bis fünf sind genug. Wählen Sie Flüsse, die Geld, Berechtigungen oder Datenänderungen betreffen. Beispiele: Signup und E-Mail-Verifizierung, Erstellung eines bezahlten Plans oder Kaufs, eine Admin-Aktion, die Benutzerzugang ändert, und ein kritischer, täglich genutzter Flow.
Entscheiden Sie, wie Sie Risiko labeln, bevor Sie Notizen sammeln. Halten Sie Kategorien einfach, damit Sie später scannen können. Ein hilfreiches Set ist: Sicherheit, Datenintegrität, Verfügbarkeit und Kosten. Wenn Sie etwas als riskant markieren, fügen Sie einen Satz hinzu, warum, plus was beweisen würde, dass es sicher ist (ein Test, ein Log, eine Berechtigungsprüfung).
Verwenden Sie ein konsistentes Format, damit Sie Notizen in ein Onboarding-Dokument umwandeln können, ohne alles umzuschreiben:
Beispiel: Wenn Checkout Billing aufruft, das Zahlungen und Rechnungen schreibt, kennzeichnen Sie es als Datenintegrität und Kosten. Notieren Sie dann, wo Retries passieren und was Double-Charging verhindert.
Wenn Sie in ein neues Repo kommen, wollen Sie schnelle Orientierung, kein perfektes Verständnis. Diese Prompts helfen Ihnen, die mentale Karte in kleinen, sicheren Schritten aufzubauen.
Beginnen Sie damit, dem Assistenten die Repo-Struktur (oder einen eingefügten Ausschnitt) zu geben und um eine Tour zu bitten. Halten Sie jede Runde fokussiert und schließen Sie mit einer Frage ab, die Ihnen sagt, was Sie als Nächstes lesen sollten.
1) Repo tour
"Here is the top-level folder list: \u003cpaste\u003e. Explain what each folder likely contains and which ones matter for core product behavior."
2) Entry points
"Find the app entry points and boot process. What files start the app, set up routing, configure DI/env, and start background jobs? Name the exact files and what they do."
3) Module index
"Create a module index: module name, purpose, key files, and important external dependencies. Keep it to the modules that affect user-facing behavior."
4) Data model hints
"Based on migrations/models, list the key tables/entities, critical fields, and relationships. Call out fields that look security-sensitive or used for billing/permissions."
5) Flow trace
"Trace this flow end-to-end: \u003cflow\u003e. Where does the request/event start, where does it end, and what does it call in between? List the main functions/files in order."
6) Next inspection
"What should I inspect next and why? Give me 3 options: fastest clarity, riskiest area, and best long-term payoff."
Ein konkretes Beispiel: Wenn Sie „user signs up and creates their first project“ mappen, fragen Sie nach dem API-Route-Handler, Validierung, DB-Write und jedem asynchronen Job, der E-Mails sendet oder Ressourcen provisioniert. Dann laufen Sie den Flow erneut für „user deletes project“, um Cleanup-Lücken zu finden.
Um Antworten handlungsfähig zu halten, fragen Sie nach spezifischen Artefakten, nicht nur Zusammenfassungen:
Der größte Onboarding-Gewinn ist, verstreute Q&A in Notizen zu verwandeln, die ein anderer Entwickler wiederverwenden kann. Wenn die Notizen nur für Sie Sinn ergeben, machen Sie später dieselbe Arbeit nochmal.
Eine einfache Struktur schlägt lange Seiten. Nach jeder Erkundungssession speichern Sie die Antworten in fünf kleinen Artefakten (eine Datei/Dokument ist ausreichend): eine Modultabelle, ein Glossar, Schlüsselflüsse, Unbekanntes und ein Risikoregister.
Hier eine kompakte Vorlage, die Sie in Ihre Notizen einfügen und ausfüllen können:
Module table
- Module:
Owns:
Touches:
Entry points:
Glossary
- Term:
Meaning:
Code name(s):
Key flow (name)
1.
2.
3.
Unknowns
- Question:
Best person to ask:
Where to look next:
Risk register
- Risk:
Location:
Why it matters:
How to verify:
Halten Sie Key Flows bewusst kurz. Beispiel: 1) Nutzer loggt sich ein, 2) Backend erstellt eine Session, 3) Client lädt das Dashboard, 4) API holt Daten, 5) UI rendert und behandelt Fehler. Wenn ein Flow nicht in fünf Schritte passt, teilen Sie ihn (Login vs Dashboard-Laden).
Wenn Sie Claude Code nutzen, fügen Sie jeder Antwort eine Zeile hinzu: „Wie würde ich das testen?“ Diese eine Zeile macht passive Notizen zu einer Checkliste, die Sie später abarbeiten können, besonders wenn Unbekanntes und Risiken sich überschneiden.
Wenn Sie in einer vibe-coding-Plattform wie Koder.ai arbeiten, hilft diese Art der Notizführung außerdem dabei, Stellen zu erkennen, an denen generierte Änderungen Seiteneffekte haben könnten. Module mit vielen Touchpoints sind oft Veränderungsmagneten.
Risiko in einer Codebase ist selten zufällig. Es konzentriert sich dort, wo die App entscheidet, wer du bist, Zustand ändert, mit anderen Systemen spricht oder Arbeit im Hintergrund ausführt. Du findest die meisten Risiken mit gezielten Fragen und ein paar fokussierten Suchen.
Beginne mit Identität. Frage, wo Authentifizierung stattfindet (Login, Session, Tokens) und wo Autorisierungsentscheidungen getroffen werden (Rollenprüfungen, Feature Flags, Ownership-Regeln). Eine häufige Falle sind verstreute Prüfungen über UI, API-Handler und DB-Abfragen ohne Single Source of Truth.
Als Nächstes mappe die Schreibpfade. Finde Endpunkte oder Funktionen, die Records erstellen, aktualisieren oder löschen, plus Migrations, die Daten über die Zeit umbauen. Berücksichtige auch Hintergrundjobs. Viele mysteriöse Fehler entstehen durch asynchrone Worker, die unerwartete Werte schreiben, lange nachdem eine Anfrage beendet wurde.
Prompts, die Risiko schnell sichtbar machen:
Dann prüfen Sie Konfiguration und Secret-Handling. Suchen Sie nach Environment-Variablen, Laufzeit-Konfigurationsdateien und Default-Fallbacks. Defaults sind nützlich, aber riskant, wenn sie Fehlkonfigurationen verdecken (z. B. ein Dev-Key in Produktion, weil ein Wert fehlt).
Ein schnelles Beispiel: In einem Go-Backend mit PostgreSQL finden Sie womöglich einen „send email“-Job, der bei Fehlern retried. Wenn er ohne Idempotency-Key retried, bekommen Nutzer doppelte E-Mails. Wenn Fehler nur als Warnung geloggt werden und kein Alert existiert, passiert es still. Das ist ein hohes Risiko, das es früh zu dokumentieren und zu testen gilt.
Nutzen Sie einen realen Flow, um Ihren ersten End-to-End-Faden durch das System zu bauen. Login ist ein guter Start, weil es Routing, Validierung, Sessions/Tokens und DB-Lesen berührt.
Szenario: Eine React-Web-App ruft ein Go-API auf, und das API liest und schreibt PostgreSQL. Ihr Ziel ist nicht, jede Datei zu verstehen. Es geht darum, die Frage zu beantworten: „Wenn ein Nutzer auf Login klickt, welcher Code läuft danach, welche Daten bewegen sich und was kann schiefgehen?“ So bleibt Onboarding konkret.
Beginnen Sie an der UI und gehen Sie vorwärts, Hop für Hop. Fragen Sie nach konkreten Dateinamen, Funktionen und Request-/Response-Formen.
Nach jeder Antwort schreiben Sie eine kurze Linie in Ihre mentale Karte: "UI component -> API endpoint -> handler -> service -> DB query -> response." Nennen Sie die Namen, nicht nur "irgendeine Funktion."
Sobald Sie den Pfad haben, verifizieren Sie ihn mit einem kleinen Testlauf. Sie prüfen damit, ob der gemappte Codepfad tatsächlich verwendet wird.
Beobachten Sie die Netzwerk-Anfragen in den Browser-Devtools (Pfad, Statuscode, Response-Body). Fügen Sie oder aktivieren Sie Server-Logs rund um den Handler und den DB-Call (Request-ID falls vorhanden). Queryen Sie PostgreSQL nach erwarteten Änderungen (für Login z. B. last_login_at, Sessions oder Audit-Rows). Erzwingen Sie einen Fehler (falsches Passwort, fehlendes Feld) und notieren Sie, wo die Fehlermeldung erzeugt und angezeigt wird. Dokumentieren Sie erwartete Antworten für Erfolg und Fehler (Statuscodes und Schlüsselfelder), damit der nächste Entwickler schnell sanity-checken kann.
Dieser einzelne Flow zeigt oft Besitzgrenzen: was die UI vertraut, was die API durchsetzt und wo Fehler verschwinden oder doppelt behandelt werden.
Sobald Sie eine brauchbare mentale Karte haben, frieren Sie sie in einer 1–2-seitigen Notiz ein. Ziel ist nicht Vollständigkeit. Ziel ist, dem nächsten Entwickler zu helfen: Was ist diese App, wo schaue ich zuerst hin und was geht am ehesten kaputt?
Wenn Sie Claude Code nutzen, behandeln Sie das Dokument als Output Ihrer Q&A: klar, konkret und leicht zu überfliegen.
Halten Sie das Dokument vorhersehbar, damit Leute Dinge schnell finden. Eine gute Struktur ist:
Bei „Where things live“ gebe Hinweise wie: „Auth startet in X, Session-Logik in Y, UI-Routen in Z.“ Vermeide das Dumpen eines kompletten Baums. Wähle nur, was Leute berühren werden.
Bei „Key flows“ schreibe 4–7 Schritte pro Flow: Trigger, Controller/Handler, Kernmodul, DB-Call und äußere Auswirkung (E-Mail gesendet, State aktualisiert, Job enqueued). Füge Dateinamen an jedem Schritt hinzu.
Bei „Risky areas“ nenne die Fehlerart und den schnellsten Sicherheitscheck (ein bestimmter Test, ein Smoke-Run oder ein zu beobachtendes Log).
Beende mit einer kleinen Liste erster Aufgaben, damit jemand sicher beitragen kann:
Der schnellste Weg, einen Assistenten zu verschwenden, ist zu fragen: „Erkläre mir das ganze Repo.“ Das Ergebnis ist eine lange Zusammenfassung, die zwar selbstsicher klingt, aber vage bleibt. Wähle stattdessen einen kleinen, relevanten Ausschnitt (ein Modul plus ein Flow) und weite ihn dann aus.
Der zweitgrößte Fehler ist, nicht zu benennen, welche Journeys wichtig sind. Wenn du nicht sagst „checkout“, „login“ oder „admin edit“, driftet die Antwort in generisches Architekturzeug. Beginne jede Session mit einem konkreten Ziel: „Hilf mir, den Signup-Flow End-to-End zu verstehen, inklusive Validierung, Fehlerzuständen und wo Daten gespeichert werden."
Eine weitere Falle ist, den Assistenten raten zu lassen. Wenn etwas unklar ist, lass ihn die Unsicherheit kennzeichnen. Bitte ihn, zu trennen, was er aus Code beweisen kann und was er nur vermutet.
Nutze eine einfache Regel in deinen Notizen: Jede Aussage muss markiert sein als:
Notizen zerfallen auch, wenn sie ohne Struktur gesammelt werden. Ein Haufen Chat-Ausschnitte ist schwer in eine mentale Karte zu verwandeln. Behalte eine konsistente Vorlage: Module, Entry-Point, Schlüssel-Funktionen und -Dateien, berührte Daten, Seiteneffekte, Fehlerpfade und Tests, die ausgeführt werden sollten.
Selbst mit Claude Code sind die Ergebnisse Entwürfe. Verifiziere Schlüssel-Flows in der laufenden App, besonders Teile, die Produktion gefährden: Auth, Zahlungen, Berechtigungen, Hintergrundjobs und Migrations.
Ein praktisches Beispiel: Wenn der Assistent sagt "password reset sends an email via X", bestätige das, indem du einen Reset in einer Dev-Umgebung triggerst und Logs oder das Email-Sandbox prüfst. Dieser Reality-Check verhindert, dass du in ein falsches Narrativ einsteigst.
Du musst das Repo nicht auswendig kennen. Du brauchst genug Vertrauen, um eine sichere Änderung vorzunehmen, ein echtes Problem zu debuggen und das System dem nächsten zu erklären.
Bevor du dich als onboarded betrachtest, beantworte diese Fragen ohne zu raten:
Wenn dir ein Punkt fehlt, mache einen kleinen, fokussierten Durchlauf statt einer breiten Suche. Wähle einen Flow, folge ihm bis zur Datenbank-Grenze und halte dann an und schreibe auf, was du gelernt hast. Wenn etwas unklar ist, formuliere es als Frage: „Wo wird Rolle X erstellt?“ ist nützlicher als „Auth ist verwirrend."
Ein guter Abschlusstest: Stell dir vor, du sollst ein kleines Feature hinter einer Flag hinzufügen. Wenn du die Dateien nennen kannst, die du anfassen würdest, die Tests, die du laufen lässt, und die Fehlerfälle, auf die du achten würdest, bist du genug onboarded, um verantwortungsbewusst beizutragen.
Eine mentale Karte ist nur nützlich, solange sie der Realität entspricht. Behandle sie als lebendiges Artefakt, nicht als Einmalaufgabe. Der einfachste Weg, sie ehrlich zu halten, ist, sie direkt nach Änderungen zu aktualisieren.
Eine leichte Routine schlägt große Überarbeitungen. Verknüpfe Updates mit der Arbeit, die du ohnehin machst:
Halte das Onboarding-Dokument nahe am Code und versioniere es mit derselben Disziplin wie den Code. Kleine Diffs werden gelesen. Große Doc-Überarbeitungen werden meist übersprungen.
Wenn Deployments riskant sind, notiere, was der nächsten Person beim Wiederherstellen helfen würde: was sich geändert hat, was zu beobachten ist und wie zurückgerollt wird. Wenn deine Plattform Snapshots und Rollbacks unterstützt, füge Snapshot-Name, Grund und wie „gut“ nach dem Fix aussieht hinzu.
Wenn du mit Koder.ai (koder.ai) arbeitest, kann der Planning-Modus helfen, aus deiner Q&A eine konsistente Modulkarte und Onboarding-Notiz zu erstellen, und der Source-Code-Export gibt Reviewer*innen einen sauberen Weg, die Ergebnisse zu validieren.
Abschließend: Definiere eine Handoff-Checkliste, die der nächste Entwickler ohne Rätsel befolgen kann:
Gut gemacht wird Claude Code beim Codebase-Onboarding zur Gewohnheit: Jede Änderung hinterlässt eine klarere Karte für die nächste Person.
Ziele für eine nutzbare mentale Karte, nicht vollständiges Verständnis.
Ein realistisches Ergebnis in 1–2 Tagen ist:
Gib konkrete Artefakte, damit das Modell auf echten Code zeigen kann statt zu raten:
Wähle einen engen Ausschnitt mit klaren Grenzen.
Ein guter Default ist:
Schreibe auf, was ausdrücklich außerhalb des Scopes liegt (andere Services, Legacy-Module, selten genutzte Features), damit der Assistent nicht abschweift.
Beginne bei bekannten Triggern und gehe dann Schritt für Schritt vor:
Bitte um Dateipfade und Funktionsnamen in Reihenfolge und schließe mit: „Wie würde ich das schnell testen?“
Fokus auf Stellen, an denen das System Entscheidungen trifft oder Zustand ändert:
Nutze ein einfaches Labelsystem und hänge einen Verifikationsschritt dran.
Beispiel:
Fordere den Assistenten auf, Evidenz von Vermutungen zu trennen.
Bitte ihn, jede Aussage als eines der folgenden zu kennzeichnen:
Wenn etwas unbekannt ist, formuliere es als Frage an einen Kollegen („Wo wird Rolle X definiert?“) statt die Lücke mit einer Vermutung zu füllen.
Behalte eine leichte Notizdatei mit fünf Sektionen bei:
Mach eine schnelle reale Überprüfung:
So stellst du sicher, dass der gemappte Pfad tatsächlich verwendet wird.
Nutze Plattform-Funktionen, um Blast Radius zu reduzieren und Änderungen prüfbar zu halten.
Konkrete Voreinstellungen:
Stelle dann die Frage: „Was bricht still und wie würden wir es bemerken?“
Halte es kurz, damit du es tatsächlich aktualisierst, wenn du mehr lernst.
Füge jeder Fluss-Notiz eine Linie hinzu: „Wie würde ich das testen?“, so wird es zu einer Checkliste.
Das funktioniert besonders gut für Onboarding-Aufgaben wie „Guardrail hinzufügen“, „Validation verschärfen“ oder „Fehlerpfad verbessern“.