Claude Code voor onboarding van codebases: gebruik Q&A-prompts om modules, belangrijke flows en risico's in kaart te brengen en maak er een korte onboarding-notitie van.
Bestanden willekeurig lezen voelt traag omdat de meeste codebases niet als een verhaal zijn georganiseerd. Je opent een map, ziet tien namen die belangrijk lijken, klikt er één aan en belandt in helpers, configs en randgevallen. Na een uur heb je veel details maar kun je nog steeds niet uitleggen hoe de app werkt.
Een beter doel voor Claude Code tijdens onboarding is het bouwen van een eenvoudige mentale kaart. Die kaart moet drie vragen beantwoorden:
Goede genoeg onboarding in 1–2 dagen is niet "Ik kan elke klasse uitleggen." Het lijkt er meer op dat:
Sommige dingen kunnen wachten. Diepe refactors, perfect begrip van elke abstractie en het lezen van oude code die niemand aanraakt, levert zelden de snelste bruikbare inzichten op.
Zie onboarding als het bouwen van een kaart, niet als het oefenen van straatnamen. Je prompts moeten je steeds terughalen naar: "Waar ben ik in het systeem, wat gebeurt er daarna, en wat kan hier misgaan?" Zodra je dat hebt, worden details makkelijker om on demand te leren.
Voordat je begint met vragen, verzamel de basis die je normaal op dag één nodig hebt. Claude Code werkt het beste wanneer het kan reageren op echte bestanden, echte config en gedrag dat je kunt reproduceren.
Begin met toegang en een werkende run. Zorg dat je de repo kunt klonen, dependencies kunt installeren en de app lokaal kunt draaien (of in ieder geval een klein deel). Als lokaal opzetten lastig is, krijg toegang tot een staging-omgeving en tot waar logs staan, zodat je kunt verifiëren wat de code daadwerkelijk doet.
Zoek vervolgens de "source of truth" docs. Je zoekt wat het team echt bijwerkt als dingen veranderen: een README, een korte architectuurnota, een ADR-map, een runbook of een deployment-notitie. Zelfs als ze rommelig zijn, geven ze namen aan modules en flows, wat Q&A veel nauwkeuriger maakt.
Bepaal scope vroeg. Veel repos bevatten meerdere apps, services en gedeelde pakketten. Kies grenzen zoals "alleen de API en de billing worker" of "alleen de webapp en zijn auth-flow." Duidelijke scope voorkomt eindeloze zijpaden.
Schrijf aannames op die je niet wilt dat de assistent raadt. Dit klinkt klein, maar het voorkomt verkeerde mentale modellen die later uren kosten.
Hier is een eenvoudige voorbereidingschecklist:
Als iets ontbreekt, noteer het als een vraag voor een collega. Probeer ontbrekende context niet "op te lossen" met gissingen.
Een mentale kaart is een kleine set notities die antwoord geeft op: wat zijn de hoofdonderdelen van deze app, hoe praten ze met elkaar, en waar kan het misgaan. Goed gedaan wordt onboarding minder een kwestie van bestanden bladeren en meer van het bouwen van een beeld dat je kunt hergebruiken.
Begin met het definiëren van je outputs. Je wilt een modulelijst die praktisch is, niet perfect. Voor elke module noteer wat het doet, wie het beheert (team of persoon als je het weet) en de belangrijkste afhankelijkheden (andere modules, services, databases, externe APIs). Noteer ook de hoofdentrypoints: UI-routes, API-endpoints, background jobs en geplande taken.
Kies vervolgens een paar gebruikersreizen die ertoe doen. Drie tot vijf is genoeg. Kies flows die geld, permissies of dataveranderingen raken. Voorbeelden: signup en e-mailverificatie, het aanmaken van een betaald plan of aankoop, een admin-actie die toegang van een gebruiker verandert, en een kritieke dagelijkse flow waar de meeste gebruikers op vertrouwen.
Bepaal voordat je notities gaat verzamelen hoe je risico labelt. Houd categorieën simpel zodat je later snel kunt scannen. Een nuttige set is security, data-integriteit, uptime en kosten. Wanneer je iets als risicovol markeert, voeg dan één zin toe die uitlegt waarom, plus wat zou aantonen dat het veilig is (een test, een log, een permissie-check).
Gebruik een consistent format zodat je notities kunt omzetten in een onboarding-doc zonder alles te herschrijven:
Voorbeeld: als Checkout Billing aanroept die schrijft naar payments en invoices, tag het als data-integriteit en kosten. Noteer vervolgens waar retries gebeuren en wat dubbele afschrijving voorkomt.
Als je een nieuwe repo betreedt, wil je snelle oriëntatie, geen perfect begrip. Deze prompts helpen je een mentale kaart in kleine, veilige stappen op te bouwen.
Begin met het geven van de assistent van de repo-boom (of een geplakte subset) en vraag om een rondleiding. Houd elke ronde gefocust en eindig met één vraag die je vertelt wat je daarna moet lezen.
1) Repo tour
"Here is the top-level folder list: <paste>. 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: <flow>. 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."
Een concreet voorbeeld: als je "user signs up and creates their first project" in kaart brengt, vraag dan naar de API-route handler, validatie, DB-write en elke async job die e-mails verstuurt of resources provisioneert. Rerun vervolgens de flow trace voor "user deletes project" om cleanup-gaten te vinden.
Om antwoorden bruikbaar te houden, vraag om specifieke artefacten, niet alleen samenvattingen:
De grootste onboardingwinst is het omzetten van verspreide Q&A in notities die een andere ontwikkelaar kan hergebruiken. Als de notities alleen voor jou logisch zijn, ga je later hetzelfde werk opnieuw doen.
Een eenvoudige structuur verslaat lange pagina's. Sla na elke verkennende sessie de antwoorden op in vijf kleine artefacten (één bestand of doc is prima): een moduletabel, een glossary, key flows, unknowns en een risk register.
Hier is een compact sjabloon dat je in je notities kunt plakken en tijdens het werk invult:
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:
Houd key flows bewust kort. Voorbeeld: 1) gebruiker logt in, 2) backend creëert een sessie, 3) client laadt het dashboard, 4) API haalt data op, 5) UI rendert en behandelt fouten. Als je een flow niet in vijf stappen kunt proppen, splits het (login vs dashboard load).
Bij gebruik van Claude Code voeg één regel toe aan elk antwoord: "How would I test this?" Die regel verandert passieve notities in een checklist die je later kunt uitvoeren, vooral wanneer unknowns en risico's elkaar overlappen.
Als je bouwt op een vibe-coding platform zoals Koder.ai, helpt dit soort notities ook om te zien waar gegenereerde wijzigingen bijwerkingen kunnen hebben. Modules met veel raakvlakken trekken vaak veranderingen aan.
Risico in een codebase is zelden willekeurig. Het clustert waar de app bepaalt wie je bent, data verandert, met andere systemen praat of werk op de achtergrond draait. Je vindt het grootste deel met gerichte vragen en een paar gerichte zoekacties.
Begin met identiteit. Vraag waar authenticatie plaatsvindt (login, sessie, tokens) en waar autorisatiebeslissingen liggen (role checks, feature flags, ownership rules). Een veelgemaakte val is checks verspreid over UI, API-handlers en database-queries zonder één enkele bron van waarheid.
Vervolgens, map de schrijfpaths. Zoek endpoints of functies die records aanmaken, bijwerken of verwijderen, plus de migrations die data over tijd veranderen. Neem ook background jobs mee. Veel mysteries komen van async workers die onverwachte waarden schrijven lang nadat een request is afgerond.
Prompts die risico snel blootleggen:
Controleer daarna configuratie en secrets-handling. Zoek naar environment variables, runtime configbestanden en default fallbacks. Defaults zijn handig, maar riskant als ze misconfiguraties verbergen (bijv. het gebruiken van een dev-key in productie omdat een waarde ontbrak).
Een kort voorbeeld: in een Go-backend met PostgreSQL vind je mogelijk een "send email" job die opnieuw probeert bij falen. Als het opnieuw probeert zonder idempotency-key, kunnen gebruikers dubbele e-mails krijgen. Als falen alleen als waarschuwing wordt gelogd en er geen alert bestaat, breekt het stilletjes. Dat is een hoog risico dat je vroeg moet documenteren en testen.
Gebruik één echte flow om je eerste end-to-end draad door het systeem te bouwen. Login is een goede starter omdat het routing, validatie, sessies of tokens en database-reads raakt.
Scenario: een React-webapproept een Go API aan, en de API leest en schrijft PostgreSQL. Je doel is niet elk bestand te begrijpen. Het doel is te beantwoorden: "Wanneer een gebruiker op Login klikt, welke code draait daarna, welke data beweegt en wat kan er misgaan?" Zo blijft onboarding concreet.
Begin bij de UI en loop vooruit, één hop tegelijk. Vraag naar specifieke bestandsnamen, functies en request- en response-shapes.
Na elk antwoord schrijf je één korte regel in je mentale kaart: "UI component -> API endpoint -> handler -> service -> DB query -> response." Voeg namen toe, niet alleen "een functie."
Zodra je het pad hebt, verifieer het met een kleine testrun. Je controleert dat het pad dat je in kaart bracht ook daadwerkelijk het pad is dat de app gebruikt.
Bekijk netwerkverzoeken in de browser devtools (pad, statuscode, response body). Zet tijdelijke serverlogs rond de handler en DB-call (request ID als beschikbaar). Query PostgreSQL voor verwachte wijzigingen (voor login bijvoorbeeld last_login_at, sessions of audit-rows). Forceer één fout (verkeerd wachtwoord, ontbrekend veld) en noteer waar het foutbericht gemaakt wordt en waar het getoond wordt. Leg verwachte responses vast voor succes en fout (statuscodes en belangrijke velden), zodat de volgende ontwikkelaar snel kan sanity-checken.
Deze ene flow onthult vaak eigendomsgrenzen: wat de UI vertrouwt, wat de API afdwingt en waar fouten verdwijnen of dubbel worden afgehandeld.
Als je een redelijke mentale kaart hebt, zet deze dan vast in een 1–2 pagina's durende notitie. Het doel is niet compleet te zijn. Het doel is de volgende ontwikkelaar te helpen beantwoorden: wat is deze app, waar kijk ik eerst en wat breekt het meest waarschijnlijk?
Als je Claude Code gebruikt, behandel het document als de output van je Q&A: duidelijk, concreet en makkelijk scanbaar.
Houd het document voorspelbaar zodat mensen snel dingen kunnen vinden. Een goede structuur is:
Bij "Waar dingen wonen" geef aanwijzingen als "Auth begint in X, sessielogica in Y, UI-routes in Z." Vermijd het dumpen van een volledige boom. Kies alleen wat mensen zullen aanraken.
Bij "Key flows" schrijf 4–7 stappen per flow: trigger, controller of handler, core module, database call en het uitgaande effect (e-mail verzonden, status geüpdatet, job in wachtrij). Voeg bestandsnamen toe bij elke stap.
Bij "Risky areas" benoem je de faalmode en de snelste veiligheidscheck (een specifieke test, een smoke-run of een log om te monitoren).
Eindig met een kleine lijst met eerste taken zodat iemand veilig kan bijdragen:
De snelste manier om een assistent te verspillen is vragen om "een volledige uitleg van de hele repo." Je krijgt een lange samenvatting die zelfverzekerd klinkt maar vaag blijft. Kies in plaats daarvan een klein relevant onderdeel (één module plus één gebruikersflow) en breid stapsgewijs uit.
Een tweede fout is niet duidelijk maken welke journeys belangrijk zijn. Als je niet zegt "checkout," "login" of "admin edit," dwaalt het antwoord af naar generieke architectuurbesprekingen. Begin elke sessie met één concreet doel: "Help me de signup-flow end-to-end te begrijpen, inclusief validatie, foutstatussen en waar data wordt opgeslagen."
Nog een valkuil is de assistent laten gissen. Zodra iets onduidelijk is, laat het labelen als onzeker. Vraag het onderscheid te maken tussen wat het uit code kan bewijzen en wat het afleidt.
Gebruik een simpele regel in je notities: elke bewering moet getagd zijn als één van deze.
Notities vallen ook uit elkaar als ze zonder structuur worden verzameld. Een stapel chatfragmenten is moeilijk om te zetten in een mentale kaart. Houd een consistent sjabloon: betrokken modules, entry point, sleutel functies en bestanden, data die geraakt wordt, bijwerkingen, foutpaden en tests om uit te voeren.
Zelfs met Claude Code, behandel de output als een concept. Verifieer sleutelflows in de draaiende app, vooral de onderdelen die productie kunnen breken: auth, betalingen, permissies, background jobs en migrations.
Een praktisch voorbeeld: als de assistent zegt "password reset verstuurt een e-mail via X," bevestig dat door een reset te triggeren in een dev-omgeving en de logs of de e-mail-sandbox te controleren. Die reality-check voorkomt dat je je inwerkt in een verhaal dat niet klopt.
Je hoeft de repo niet te memoriseren. Je hebt genoeg vertrouwen nodig om een veilige wijziging te maken, een echt probleem te debuggen en het systeem aan de volgende persoon uit te leggen.
Voordat je jezelf ingewerkt noemt, zorg dat je deze zonder te gokken kunt beantwoorden:
Als er één item mist, doe dan een kleine gerichte pass in plaats van een brede zoektocht. Kies één flow, volg die tot aan de databasegrens en stop dan en schrijf op wat je geleerd hebt. Als iets onduidelijk is, vast het als een vraag in plaats van een paragraaf. "Waar wordt rol X aangemaakt?" is bruikbaarder dan "auth is verwarrend."
Een goede eindtest: stel je voor dat je gevraagd wordt een kleine feature achter een flag toe te voegen. Als je de bestanden kunt noemen die je zou aanraken, de tests die je zou draaien en de faalmodi die je zou monitoren, ben je genoeg ingewerkt om verantwoord bij te dragen.
Een mentale kaart is alleen nuttig zolang hij de realiteit weerspiegelt. Behandel het als een levend artefact, niet als een eenmalige klus. De makkelijkste manier om het eerlijk te houden is het direct bijwerken na veranderingen die gedrag beïnvloeden.
Een lichte routine verslaat grote herschrijvingen. Koppel updates aan werk dat je toch al doet:
Houd de onboarding-doc dicht bij de code en versioneer het met dezelfde discipline als de codebase. Kleine diffs worden gelezen. Grote doc-herschrijvingen worden meestal overgeslagen.
Als deploys risicovol zijn, noteer wat de volgende persoon snel zou helpen herstellen: wat veranderde, wat te monitoren en hoe terug te draaien. Als je platform snapshots en rollback ondersteunt, voeg de snapshotnaam, reden en wat "goed" eruitziet na de fix toe.
Als je bouwt met Koder.ai (koder.ai), kan de planning-modus helpen bij het opstellen van een consistente moduulekaart en onboarding-notitie vanuit je Q&A, en source code export geeft reviewers een schone manier om het resultaat te valideren.
Tot slot, definieer een overdrachts-checklist die de volgende ontwikkelaar kan volgen zonder te moeten raden:
Goed uitgevoerd wordt Claude Code voor codebase-onboarding een gewoonte: elke wijziging laat een duidelijkere kaart achter voor de volgende persoon.
Aim for a usable mental map, not total understanding.
A solid 1–2 day outcome is:
Give it concrete artifacts so it can point to real code instead of guessing:
Pick a narrow slice with clear boundaries.
A good default scope is:
Write down what’s explicitly out of scope (other services, legacy modules, rarely used features) so the assistant doesn’t wander.
Start from known triggers, then walk forward:
Ask for file paths and function names in order, and end with: “How would I test this quickly?”
Look where the system makes decisions or changes state:
Use a simple label system and attach one proof step.
Example format:
Force the assistant to separate evidence from inference.
Ask it to tag each claim as one of:
When something is unknown, turn it into a teammate question (“Where is role X defined?”) instead of filling the gap with a guess.
Keep one lightweight note file with five sections:
Default to a quick, real check:
This validates you mapped the path the app actually uses.
Use platform features to reduce blast radius and keep changes reviewable.
Practical defaults:
Then ask: “What breaks silently, and how would we notice?”
Keep it short so you actually update it as you learn.
Add one line to each flow: “How would I test this?” so it becomes a checklist.
This works especially well for onboarding tasks like “add a guardrail,” “tighten validation,” or “improve an error path.”