Claude Code för onboarding av kodbas: använd frågor och svar för att kartlägga moduler, viktiga flöden och risker, och förvandla sedan anteckningarna till ett kort onboarding-dokument.
Att läsa filer lite på måfå känns långsamt eftersom de flesta kodbaser inte är organiserade som en berättelse. Du öppnar en mapp, ser tio namn som verkar viktiga, klickar på en och hamnar i helpers, configs och kantfall. Efter en timme har du massor med detaljer men kan fortfarande inte förklara hur appen fungerar.
Ett bättre mål för Claude Code under onboarding är att bygga en enkel mental karta. Den kartan bör svara på tre frågor:
Tillräckligt bra onboarding på 1–2 dagar är inte "Jag kan förklara varje klass." Det liknar mer detta:
Vissa saker kan vänta. Djupa refaktorer, perfekt förståelse av varje abstraktion och att läsa gammal kod som ingen rör ger sällan snabb nytta.
Tänk på onboarding som att bygga en karta, inte memorera gator. Dina prompts bör ständigt återvända till: "Var är jag i systemet, vad händer härnäst och vad kan gå fel här?" När du har det blir detaljer enklare att lära vid behov.
Innan du börjar ställa frågor, samla det grundläggande du normalt behöver dag ett. Claude Code fungerar bäst när det kan reagera på verkliga filer, riktig konfig och verkligt beteende du kan reproducera.
Börja med åtkomst och en körbar version. Se till att du kan klona repot, installera beroenden och köra appen (eller åtminstone en liten del) lokalt. Om lokal setup är svår, få åtkomst till en staging-miljö och där loggar finns, så du kan verifiera vad koden faktiskt gör.
Sedan, hitta "source of truth"-dokumenten. Du letar efter det teamet faktiskt uppdaterar när saker förändras: en README, en kort arkitekturbeskrivning, en ADR-mapp, en runbook eller en deploymentsnotis. Även om de är röriga ger de namn på moduler och flöden, vilket gör frågor och svar mycket mer precisa.
Bestäm scope tidigt. Många repor innehåller flera appar, tjänster och delade paket. Välj gränser som "endast API:n och billing-worker" eller "endast webbappen och dess auth-flöde." Ett tydligt scope förhindrar ändlösa sidospår.
Skriv ner antaganden du inte vill att assistenten ska gissa om. Det låter trivialt, men förhindrar felaktiga mentala modeller som kostar timmar senare.
Här är en enkel förberedelselista:
Om något saknas, fånga det som en fråga till en kollega. Försök inte "arbeta runt" saknad kontext med gissningar.
En mental karta är en liten uppsättning anteckningar som svarar på: vilka är huvuddelarna i den här appen, hur pratar de med varandra och var kan saker gå fel. Gjort rätt blir onboarding mindre om att bläddra i filer och mer om att bygga en bild du kan återanvända.
Börja med att definiera dina outputs. Du vill ha en modulista som är praktisk, inte perfekt. För varje modul fånga vad den gör, vem som äger den (team eller person om du vet), och dess nyckelberoenden (andra moduler, tjänster, databaser, externa API:er). Notera också huvud-entrépunkter: UI-rutter, API-endpoints, bakgrundsjobb och schemalagda uppgifter.
Välj sedan några användarresor som spelar roll. Tre till fem räcker. Välj flöden som rör pengar, behörigheter eller datändringar. Exempel: signup och e-postverifiering, skapa en betald plan eller köp, en admin-åtgärd som ändrar användares åtkomst, och ett kritiskt dagligt flöde som de flesta användare litar på.
Bestäm hur du ska märka risk innan du börjar samla anteckningar. Håll kategorier enkla så du snabbt kan skanna senare. Ett användbart set är säkerhet, dataintegritet, driftstid och kostnad. När du markerar något som riskfyllt, lägg till en mening som förklarar varför, plus vad som skulle bevisa att det är säkert (ett test, en logg, en behörighetskontroll).
Använd ett konsekvent format så du kan göra anteckningarna till ett onboarding-dokument utan att skriva om allt:
Exempel: om Checkout kallar Billing som skriver till payments och invoices, tagga det som dataintegritet och kostnad. Notera sedan var retries sker och vad som förhindrar dubbeldebitering.
När du går med i ett nytt repo vill du ha snabb orientering, inte perfekt förståelse. Dessa prompts hjälper dig bygga en mental karta i små, säkra steg.
Börja med att ge assistenten repo-trädet (eller en inklistrad del) och be om en rundtur. Håll varje runda fokuserad, och avsluta med en fråga som säger vad du ska läsa nästa.
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."
Ett konkret exempel: om du kartlägger "user signs up and creates their first project," be om API-route handler, validering, DB-skrivning och eventuellt asynkront jobb som skickar mail eller provisionerar resurser. Kör sedan flödes-tracen igen för "user deletes project" för att hitta städningsluckor.
För att hålla svar handlingsbara, be om specifika artefakter, inte bara sammanfattningar:
Den största vinsten i onboarding är att förvandla spridda Q&A till anteckningar som en annan utvecklare kan återanvända. Om anteckningarna bara är meningsfulla för dig, kommer du att göra om samma grävande senare.
En enkel struktur slår långa sidor. Efter varje explorationssession, spara svaren i fem små artefakter (en fil eller doc räcker): en modultabell, en ordlista, nyckelflöden, okänt och ett riskregister.
Här är en kompakt mall du kan klistra in i dina anteckningar och fylla i allt eftersom:
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:
Håll nyckelflöden korta med vilja. Exempel: 1) user signs in, 2) backend skapar session, 3) klient laddar dashboard, 4) API hämtar data, 5) UI renderar och hanterar fel. Om du inte kan få plats med ett flöde på fem steg, dela upp det (login vs dashboard-laddning).
När du använder Claude Code, lägg till en rad i varje svar: "Hur skulle jag testa detta?" Denna enkla rad förvandlar passiva anteckningar till en checklista du kan köra senare, särskilt när okänt och risk börjar överlappa.
Om du bygger i en vibe-coding-plattform som Koder.ai, hjälper den här typen av anteckningsarbete dig också att se var genererade ändringar kan få sidoeffekter. Moduler med många beröringspunkter tenderar att vara förändringsmagneter.
Risk i en kodbas är sällan slumpmässig. Den klustrar där appen bestämmer vem du är, ändrar data, pratar med andra system eller kör arbete i bakgrunden. Du kan hitta det mesta med riktade frågor och några fokuserade sökningar.
Börja med identitet. Fråga var autentisering händer (login, session, tokens) och var auktorisationsbeslut görs (rollkontroller, feature flags, ägarskapsregler). En vanlig fälla är kontroller utspridda över UI, API-handlare och databasfrågor utan en enda sanningskälla.
Nästa steg, mappa skrivvägarna. Hitta endpoints eller funktioner som skapar, uppdaterar eller tar bort records, samt migrationer som förändrar data över tid. Inkludera bakgrundsjobb också. Många mystiska buggar kommer från asynkrona workers som skriver oväntade värden långt efter att en request avslutats.
Prompter som snabbt lyfter risk:
Kolla sedan konfiguration och hantering av hemligheter. Leta efter miljövariabler, runtime-konfigfiler och standardfall. Defaultar är användbara, men riskfyllda när de döljer felkonfigurationer (t.ex. att en dev-nyckel används i produktion för att ett värde saknades).
Ett snabbt exempel: i en Go-backend med PostgreSQL kan du hitta ett "send email"-jobb som retryar vid fel. Om det retryar utan idempotensnyckel kan användare få dubblettmejl. Om fel bara loggas som varningar och ingen alert finns, bryts det tyst. Det är ett högprioriterat område att dokumentera och testa tidigt.
Använd ett verkligt flöde för att bygga din första end-to-end-tråd genom systemet. Login är en bra start eftersom det rör routing, validering, sessioner eller tokens och databasläsningar.
Scenario: en React-webbapp anropar ett Go-API, och API:t läser och skriver PostgreSQL. Ditt mål är inte att förstå varje fil. Det är att svara: "När en användare klickar Login, vilken kod körs härnäst, vilken data flyttas och vad kan gå fel?" Så håller onboarding sig konkret.
Börja i UI och gå framåt, ett hopp i taget. Be om specifika filnamn, funktioner och request/response-format.
Efter varje svar, skriv en kort rad i din mentala karta: "UI-komponent -> API-endpoint -> handler -> service -> DB-query -> respons." Inkludera namnen, inte bara "någon funktion."
När du har vägen, verifiera den med ett litet testkör. Du kontrollerar att kodvägen du mappade är den väg appen faktiskt använder.
Titta på network requests i browser dev tools (path, statuskod, responsbody). Lägg till eller aktivera serverlogs runt handlern och DB-anropet (request-ID om det finns). Fråga PostgreSQL om förväntade förändringar (för login kanske last_login_at, sessions eller audit-rader). Tvinga ett fel (fel lösenord, saknat fält) och notera var felmeddelandet skapas och var det visas. Skriv ner förväntade svar för succé och fel (statuskoder och nyckelfält), så nästa utvecklare snabbt kan sanity-checka.
Detta enda flöde exponerar ofta ägargränser: vad UI litar på, vad API:t upprätthåller och var fel försvinner eller dubbels hanteras.
När du har en hygglig mental karta, frys den till en 1–2 sidors anteckning. Målet är inte att vara komplett. Det är att hjälpa nästa utvecklare svara: vad är den här appen, var tittar jag först och vad går mest sannolikt sönder?
Om du använder Claude Code, behandla dokumentet som outputen av din Q&A: tydligt, konkret och lätt att skumma.
Håll dokumentet förutsägbart så folk snabbt hittar det de behöver. En bra struktur är:
För "Var saker ligger," inkludera pekare som "Auth börjar i X, sessionlogik i Y, UI-rutter i Z." Undvik att dumpa ett komplett träd. Välj bara det folk kommer att röra.
För "Nyckelflöden," skriv 4–7 steg per flöde: trigger, controller eller handler, kärnmodul, databas-anrop och utåtverkande effekt (mail skickat, state uppdaterad, jobb i kö). Lägg filnamn vid varje steg.
För "Riskfyllda områden," namnge felmodet och den snabbaste säkerhetskontrollen (ett specifikt test, en smoke-run eller en logg att bevaka).
Avsluta med en liten första-uppgiftslista så någon kan bidra säkert:
Det snabbaste sättet att slösa på en assistent är att be om "en full förklaring av hela repot." Då får du en lång sammanfattning som låter säker men förblir vag. Välj istället en liten skiva som spelar roll (en modul + ett användarflöde), och expandera utifrån.
Nästa vanliga misstag är att inte säga vilka resor som spelar roll. Om du inte säger "checkout," "login," eller "admin edit," driver svaren in i generisk arkitekturbeskrivning. Börja varje session med ett konkret mål: "Hjälp mig förstå signup-flödet end-to-end, inklusive validering, felstater och var data lagras."
En annan fälla är att låta assistenten gissa. När något är oklart, tvinga den att märka osäkerhet. Be den separera vad den kan bevisa från kod vs vad den infererar.
Använd en enkel regel i dina anteckningar: varje påstående måste märkas som en av dessa:
Anteckningar faller också sönder när de samlas utan struktur. En hög med chattutdrag är svårt att göra till en mental karta. Håll en konsekvent mall: involverade moduler, entrépunkter, nyckelfunktioner och filer, data som påverkas, sidoeffekter, felvägar och tester att köra.
Även med Claude Code, behandla outputen som ett utkast. Verifiera nyckelflöden i den körande appen, särskilt delar som kan påverka produktion: auth, betalningar, behörigheter, bakgrundsjobb och migrationer.
Ett praktiskt exempel: om assistenten säger "password reset skickar mail via X," bekräfta det genom att trigga en reset i en dev-miljö och titta i logs eller e-postsandbox. Den här verklighetskontrollen hindrar dig från att onboarda in i en berättelse som inte är sann.
Du behöver inte memorera repot. Du behöver tillräcklig trygghet för att göra en säker ändring, debugga ett verkligt problem och förklara systemet för nästa person.
Innan du kallar dig onboardad, se till att du kan svara på dessa utan att gissa:
Om du saknar en punkt, gör en liten fokuserad pass istället för en bred sökning. Välj ett flöde, följ det till databasgränsen och stoppa sedan och skriv ner vad du lärt dig. När något är oklart, fånga det som en fråga, inte ett stycke. "Var skapas roll X?" är mer användbart än "auth är förvirrande."
Ett bra slut-test: föreställ dig att du ska lägga till en liten feature bakom en flagga. Om du kan namnge filer du skulle röra, tester du skulle köra och felsituationer att titta efter, är du tillräckligt onboardad för att bidra ansvarsfullt.
En mental karta är bara användbar så länge den matchar verkligheten. Behandla den som ett levande artefakt, inte en engångsuppgift. Det enklaste sättet att hålla den är att uppdatera den direkt efter förändringar som påverkar beteende.
En lätt rutin slår stora omskrivningar. Koppla uppdateringar till arbete du redan gör:
Håll onboarding-dokumentet nära koden och versionera det med samma disciplin som kodbasen. Små diffar blir lästa. Stora dokuments-omskrivningar brukar hoppas över.
När deployment är riskfylld, skriv ner vad som hjälper nästa person att återställa snabbt: vad som ändrades, vad att bevaka och hur man rullar tillbaka. Om din plattform stödjer snapshots och rollback, lägg till snapshot-namn, anledning och vad "bra" ser ut efter fixen.
Om du bygger med Koder.ai (koder.ai), kan planning-läge hjälpa dig skissa en konsekvent modulkarta och onboarding-notis från din Q&A, och source code-export ger granskare ett rent sätt att validera resultatet.
Slutligen, definiera en handoff-checklista nästa utvecklare kan följa utan att gissa:
Görs väl lämnar Claude Code för kodbas-onboarding en tydligare karta åt nästa person varje gång.
Sikta på en användbar mental karta, inte total förståelse.
Ett bra 1–2 dagars resultat är:
Dela konkreta artefakter så att assistenten kan peka på verklig kod istället för att gissa:
Välj en smal del med tydliga gränser.
En bra standard-scope är:
Skriv också ner vad som är uttryckligen utanför scopet (andra tjänster, legacy-moduler, sällan använda funktioner) så att assistenten inte börjar vandra iväg.
Börja från kända triggers och gå framåt:
Be om filvägar och funktionsnamn i ordning, och avsluta med: ”Hur skulle jag testa detta snabbt?”
Titta där systemet fattar beslut eller ändrar state:
Använd ett enkelt etikett-system och fäst ett verifieringssteg.
Exempel:
Tvinga assistenten att skilja bevis från antaganden.
Be den tagga varje påstående som en av:
När något är okänt, gör det till en fråga till en kollega (t.ex. ”Var definieras roll X?”) istället för att fylla luckan med en gissning.
Behåll en lätt anteckningsfil med fem sektioner:
Gå till en snabb, riktig kontroll:
Detta validerar att du mappat den väg appen faktiskt använder.
Använd plattformsfunktionerna för att minska blast radius och göra ändringar lättare att granska.
Praktiska standarder:
Sen fråga: “Vad kan gå sönder tyst, och hur skulle vi märka det?”
Håll det kort så att du faktiskt uppdaterar det när du lär dig mer.
Lägg en rad till varje flöde: ”Hur skulle jag testa detta?” så det blir en checklista.
Detta fungerar särskilt bra för onboarding-uppgifter som ”lägg till en guardrail”, ”skärp validering” eller ”förbättra ett felhanteringsfall”.