Claude Code do onboardingu bazy kodu: używaj zapytań Q&A, by zmapować moduły, kluczowe przepływy i ryzyka, a następnie zamień notatki w krótki dokument onboardingowy.
Czytanie plików na chybił trafił jest wolne, bo większość repozytoriów nie jest uporządkowana jak opowiadanie. Otwierasz folder, widzisz dziesięć nazw, które wyglądają na ważne, klikasz jedną i kończysz w helperach, konfiguracjach i przypadkach brzegowych. Po godzinie masz masę szczegółów, ale nadal nie potrafisz wyjaśnić, jak działa aplikacja.
Lepszym celem dla Claude Code podczas onboardingu jest zbudowanie prostej mapy mentalnej. Ta mapa powinna odpowiedzieć na trzy pytania:
Wystarczająco dobre onboardowanie w 1–2 dni to nie „potrafię wyjaśnić każdą klasę.” Bardziej przypomina to:
Niektóre rzeczy mogą poczekać. Głębokie refaktory, perfekcyjne rozumienie każdej abstrakcji i czytanie starego kodu, którego nikt nie dotyka, rzadko daje najszybszą wartość.
Traktuj onboarding jak budowanie mapy, a nie zapamiętywanie ulic. Twoje zapytania powinny ciągle przypominać: „Gdzie jestem w systemie, co się dzieje dalej i co tu może pójść nie tak?” Kiedy masz to ogólne zrozumienie, szczegóły łatwiej się uczą w miarę potrzeby.
Zanim zaczniesz zadawać pytania, zbierz podstawy, których zwykle potrzebujesz pierwszego dnia. Claude Code działa najlepiej, gdy może reagować na prawdziwe pliki, faktyczne konfiguracje i zachowanie, które możesz odtworzyć.
Zacznij od dostępu i działającego uruchomienia. Upewnij się, że potrafisz sklonować repo, zainstalować zależności i uruchomić aplikację (albo przynajmniej fragment lokalnie). Jeśli lokalne uruchomienie jest trudne, uzyskaj dostęp do środowiska staging i do miejsc, gdzie są logi, aby móc zweryfikować, co kod faktycznie robi.
Następnie znajdź „źródła prawdy”. Szukasz tego, co zespół faktycznie aktualizuje, gdy coś się zmienia: README, krótkiej notatki architektury, folderu ADR, runbooka lub notatki wdrożeniowej. Nawet jeśli są nieuporządkowane, nadają nazwy modułom i przepływom, co sprawia, że Q&A jest o wiele precyzyjniejsze.
Zdecyduj o zakresie wcześnie. Wiele repozytoriów zawiera kilka aplikacji, serwisów i współdzielonych pakietów. Wybierz granice typu „tylko API i worker billing” lub „tylko aplikacja web i jej przepływ auth”. Jasny zakres zapobiega niekończącym się dygresjom.
Zapisz założenia, których nie chcesz, żeby asystent zgadywał. To wydaje się drobne, ale zapobiega błędnym modelom mentalnym, które później marnują godziny.
Oto prosta lista kontrolna przygotowania:
Jeśli czegoś brakuje, zanotuj to jako pytanie do kolegi. Nie „obejmuj” brakującego kontekstu domysłami.
Mapa mentalna to mały zestaw notatek odpowiadający na pytanie: jakie są główne części tej aplikacji, jak się komunikują i gdzie może coś pójść nie tak. Dobrze wykonane onboardowanie mniej polega na przeglądaniu plików, a bardziej na budowaniu obrazu, którego możesz użyć ponownie.
Zacznij od zdefiniowania wyników. Chcesz praktyczną listę modułów, nie perfekcyjną. Dla każdego modułu zanotuj, co robi, kto go posiada (zespół lub osoba, jeśli wiesz) oraz kluczowe zależności (inne moduły, serwisy, bazy danych, zewnętrzne API). Zanotuj też główne punkty wejścia: trasy UI, endpointy API, zadania w tle i harmonogramy.
Następnie wybierz kilka ścieżek użytkownika, które mają znaczenie. Trzy do pięciu wystarczy. Wybierz przepływy, które dotykają pieniędzy, uprawnień lub zmian danych. Przykłady: rejestracja i weryfikacja email, zakup planu lub transakcja, akcja admina zmieniająca dostęp użytkownika oraz krytyczny codzienny przepływ używany przez większość użytkowników.
Zdecyduj, jak oznaczysz ryzyko zanim zaczniesz zbierać notatki. Trzymaj kategorie proste, aby później dało się to szybko przeskanować. Przydatny zestaw to: bezpieczeństwo, integralność danych, dostępność i koszty. Gdy oznaczysz coś jako ryzykowne, dodaj jedno zdanie wyjaśniające dlaczego oraz co udowodni, że jest bezpieczne (test, log, sprawdzenie uprawnień).
Używaj spójnego formatu, żeby potem łatwo przerobić notatki na dokument onboardingowy bez przepisywania wszystkiego:
Przykład: jeśli Checkout wywołuje Billing, który zapisuje do payments i invoices, oznacz to jako integralność danych i koszty. Zanotuj, gdzie występują retry i co zapobiega podwójnemu obciążeniu.
Kiedy dołączasz do nowego repo, chcesz szybkiej orientacji, a nie perfekcyjnego zrozumienia. Te zapytania pomogą Ci zbudować mapę mentalną w małych, bezpiecznych krokach.
Zacznij od przekazania asystentowi drzewa repo (albo wklejonego podzbioru) i poproś o „tour”. Trzymaj każdą rundę skoncentrowaną, a na końcu zadawaj jedno pytanie mówiące, co czytać dalej.
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."
To konkret: jeśli mapujesz „użytkownik rejestruje się i tworzy pierwszy projekt”, poproś o handler trasy API, walidację, zapis w DB i każde zadanie asynchroniczne wysyłające emaile lub provisioning. Potem uruchom ponownie trace dla „użytkownik usuwa projekt”, żeby wypatrzyć luki w czyszczeniu zasobów.
Aby odpowiedzi były użyteczne, proś o konkretne artefakty, nie tylko podsumowania:
Największy zysk z onboardingu to zamiana rozrzuconych Q&A w notatki, których inny developer też użyje. Jeśli notatki są zrozumiałe tylko dla Ciebie, za chwilę znów odrobisz tę samą robotę.
Prosta struktura zwycięża długie dokumenty. Po każdej sesji eksploracji zachowaj odpowiedzi w pięciu małych artefaktach (jeden plik lub dokument wystarczy): tabela modułów, glosariusz, kluczowe przepływy, nieznane i rejestr ryzyk.
Oto kompaktowy szablon, który możesz wkleić do notatek i wypełniać w trakcie:
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:
Trzymaj przepływy krótkie celowo. Przykład: 1) użytkownik loguje się, 2) backend tworzy sesję, 3) klient ładuje dashboard, 4) API pobiera dane, 5) UI renderuje i obsługuje błędy. Jeśli nie możesz zmieścić przepływu w pięciu krokach, podziel go (logowanie vs ładowanie dashboardu).
Gdy korzystasz z Claude Code, dodaj do każdej odpowiedzi jedną linijkę: „Jak bym to przetestował?” Ta jedna linijka zmienia pasywne notatki w checklistę, którą możesz potem uruchomić, zwłaszcza gdy nieznane i ryzyka zaczynają się nakładać.
Jeśli budujesz w platformie vibe-coding jak Koder.ai, takie notatki pomagają też zauważyć, gdzie generowane zmiany mogą mieć efekty uboczne. Moduły z wieloma punktami styku często przyciągają zmiany.
Ryzyko w bazie kodu rzadko jest losowe. Grupuje się tam, gdzie aplikacja decyduje, kim jesteś, zmienia dane, rozmawia z innymi systemami lub uruchamia pracę w tle. Większość znajdziesz pytaniami celowanymi i kilkoma fokused searchami.
Zacznij od tożsamości. Zapytaj, gdzie odbywa się uwierzytelnianie (logowanie, sesje, tokeny) i gdzie żyją decyzje autoryzacyjne (sprawdzanie ról, feature flagi, reguły właścicielstwa). Częstym pułapkiem są rozproszone checki po UI, handlerach API i zapytaniach do DB bez jednego źródła prawdy.
Następnie zmapuj ścieżki zapisów. Znajdź endpointy lub funkcje, które tworzą, aktualizują lub usuwają rekordy, plus migracje, które zmieniają dane w czasie. Uwzględnij też zadania w tle. Wiele tajemniczych błędów pochodzi od workerów asynchronicznych zapisujących nieoczekiwane wartości długo po zakończeniu żądania.
Przykładowe zapytania odsłaniające ryzyko szybko:
Potem sprawdź konfigurację i obsługę sekretów. Szukaj zmiennych środowiskowych, plików konfiguracji runtime i domyślnych fallbacków. Fallbacki są użyteczne, ale ryzykowne, gdy ukrywają błędy konfiguracji (np. użycie klucza deweloperskiego w produkcji, bo wartość była pusta).
Krótki przykład: w backendzie Go z PostgreSQL możesz znaleźć zadanie "send email" z retry. Jeśli retry działa bez klucza idempotencji, użytkownicy mogą dostać duplikaty maili. Jeśli błędy tylko logują ostrzeżenie i nie ma alertu, awaria przebiega cicho. To obszar wysokiego ryzyka, który warto udokumentować i przetestować wcześnie.
Użyj jednego realnego przepływu, aby zbudować pierwszy wątek end-to-end przez system. Logowanie to dobry start, bo dotyka routingu, walidacji, sesji lub tokenów i odczytów z bazy.
Scenariusz: aplikacja React wywołuje API w Go, a API czyta i zapisuje PostgreSQL. Twoim celem nie jest zrozumienie każdego pliku. Chodzi o odpowiedź: „Kiedy użytkownik klika Zaloguj, jaki kod uruchamia się dalej, jakie dane się przemieszczają i co może pójść nie tak?” To utrzymuje onboarding konkretnym.
Zacznij od UI i idź krok po kroku. Proś o konkretne nazwy plików, funkcji oraz kształt requestów i response'ów.
Po każdej odpowiedzi zapisz jedną krótką linię w mapie mentalnej: "UI component -> endpoint API -> handler -> serwis -> zapytanie DB -> response." Podawaj nazwy, nie tylko "jakiejś funkcji."
Gdy masz ścieżkę, zweryfikuj ją krótkim testem. Sprawdzasz, czy odwzorowana ścieżka to ta, której aplikacja rzeczywiście używa.
Obserwuj żądania sieciowe w narzędziach deweloperskich przeglądarki (ścieżka, kod statusu, body odpowiedzi). Dodaj lub włącz logi serwera wokół handlera i wywołania DB (jeśli jest request ID, użyj go). Zapytaj PostgreSQL o oczekiwane zmiany (dla logowania może to być last_login_at, wpisy sesji lub rekordy audytu). Wymuś jedną awarię (zły password, brak pola) i zanotuj, gdzie powstaje komunikat o błędzie i gdzie jest wyświetlany. Zapisz oczekiwane odpowiedzi dla sukcesu i porażki (kody statusu i kluczowe pola), żeby następny developer mógł szybko sanity-checkować.
Ten jeden przepływ często ujawnia granice własności: czemu UI ufa, co API egzekwuje i gdzie błędy znikają lub są podwójnie obsługiwane.
Gdy masz przyzwoitą mapę mentalną, utrwal ją w 1–2 stronicowej notatce. Cel nie jest kompletny. Chodzi o to, żeby następny developer umiał odpowiedzieć: czym jest ta aplikacja, gdzie szukać na początek i co najprawdopodobniej się zepsuje.
Jeśli używasz Claude Code, traktuj dokument jako wynik twojego Q&A: jasny, konkretny i łatwy do przeskanowania.
Utrzymaj dokument przewidywalnym, żeby ludzie mogli szybko znaleźć to, czego szukają. Dobra struktura to:
Dla „Gdzie co jest”, podawaj wskazówki typu "Auth zaczyna się w X, logika sesji w Y, trasy UI w Z." Unikaj zrzutów całego drzewa. Wybierz tylko to, czego ludzie będą dotykać.
Dla „Kluczowych przepływów”, napisz 4–7 kroków na przepływ: wyzwalacz, kontroler/handler, główny moduł, zapytanie do bazy i efekt zewnętrzny (wysłano email, zaktualizowano stan, wstawiono zadanie do kolejki). Dodaj nazwy plików przy każdym kroku.
Dla „Obszarów ryzykownych”, nazwij tryb awarii i najszybszą kontrolę bezpieczeństwa (konkretny test, smoke run albo log do obserwacji).
Zakończ krótką listą pierwszych zadań, żeby ktoś mógł bezpiecznie wnieść wkład:
Najszybszy sposób zmarnować asystenta to prosić o "pełne wyjaśnienie całego repo." Dostaniesz długie podsumowanie, które brzmi pewnie, ale pozostaje ogólne. Zamiast tego wybierz mały fragment, który ma znaczenie (jeden moduł + jeden przepływ), potem rozszerzaj.
Blisko za tym jest nieokreślenie, które podróże mają znaczenie. Jeśli nie powiesz "checkout", "login" lub "admin edit", odpowiedzi dryfują w stronę ogólnej architektury. Zaczynaj każdą sesję konkretnym celem: "Pomóż mi zrozumieć proces rejestracji end-to-end, włącznie z walidacją, stanami błędów i tym, gdzie dane są przechowywane."
Inną pułapką jest pozwolenie asystentowi na zgadywanie. Kiedy coś jest niejasne, wymuś oznaczenie niepewności. Poproś o oddzielenie tego, co można udowodnić z kodu, od wniosków.
Ustal prostą zasadę: każde twierdzenie musi mieć jedną z etykiet:
Notatki też się rozlatują, gdy są zbierane bez struktury. Stosuj spójny szablon: moduły, punkty wejścia, kluczowe funkcje i pliki, dotykane dane, efekty uboczne, ścieżki błędów i testy do uruchomienia.
Nawet z Claude Code traktuj wynik jako szkic. Weryfikuj kluczowe przepływy w działającej aplikacji, szczególnie te fragmenty, które mogą zepsuć produkcję: auth, płatności, uprawnienia, zadania w tle i migracje.
Praktyczny przykład: jeśli asystent mówi "reset hasła wysyła email przez X", potwierdź to, wywołując reset w środowisku deweloperskim i sprawdzając logi lub sandbox mailowy. Ten reality check zapobiega onboardowaniu się w historię, która nie jest prawdziwa.
Nie musisz zapamiętywać całego repo. Musisz mieć wystarczającą pewność, by bezpiecznie wprowadzić zmianę, debugować realny problem i wyjaśnić system następnej osobie.
Zanim uznasz, że jesteś onboardowany, upewnij się, że potrafisz bez zgadywania odpowiedzieć na pytania:
Jeśli brakuje jednej rzeczy, zrób małe, ukierunkowane podejście zamiast szerokiego przeszukiwania. Wybierz jeden przepływ, prześledź go do granicy bazy danych, potem zatrzymaj się i zapisz, czego się nauczyłeś. Gdy coś jest niejasne, zapisz to jako pytanie, nie akapit. "Gdzie tworzona jest rola X?" jest bardziej użyteczne niż "auth jest mylący."
Dobry finalny test: wyobraź sobie, że masz dodać małą funkcję za flagą. Jeśli potrafisz nazwać pliki, które byś dotknął, testy, które byś uruchomił, i tryby awarii, które byś obserwował, to jesteś wystarczająco onboardowany, by wnieść odpowiedzialny wkład.
Mapa mentalna jest użyteczna tylko wtedy, gdy odpowiada rzeczywistości. Traktuj ją jako żywy artefakt, nie jednorazowe zadanie. Najłatwiejszy sposób, żeby pozostała aktualna, to zaktualizować ją zaraz po zmianach, które wpływają na zachowanie.
Lekka rutyna bije duże przepisy. Powiąż aktualizacje z pracą, którą już wykonujesz:
Trzymaj dokument onboardingowy blisko kodu i wersjonuj go z tą samą dyscypliną co repozytorium. Małe zmiany są czytane. Duże rewizje zwykle są pomijane.
Gdy wdrożenia są ryzykowne, zapisz, co pomoże następnej osobie szybko odzyskać sprawność: co się zmieniło, co obserwować i jak cofnąć. Jeśli platforma wspiera snapshoty i rollback, dodaj nazwę snapshota, powód i jak wygląda „dobry” wynik po naprawie.
Jeśli używasz Koder.ai (koder.ai), tryb planowania może pomóc Ci sporządzić spójną mapę modułów i notatkę onboardingową z Q&A, a eksport źródeł daje recenzentom czytelny sposób na weryfikację wyniku.
Na koniec, zdefiniuj checklistę przekazania, którą następna osoba będzie mogła wykonać bez zgadywania:
Dobrze wykonane, Claude Code do onboardingu bazy kodu staje się nawykiem: każda zmiana zostawia jaśniejszą mapę dla następnej osoby.
Celuj w użyteczną mapę mentalną, a nie całkowite zrozumienie.
Solidny efekt po 1–2 dniach to:
Przekaż konkretne artefakty, żeby asystent mógł odwołać się do rzeczywistego kodu, zamiast zgadywać:
Wybierz wąski wycinek z jasnymi granicami.
Dobry domyślny zakres to:
Zanotuj, co jest wyraźnie poza zakresem (inne serwisy, moduły legacy, rzadko używane funkcje), żeby asystent nie błądził.
Zacznij od rozpoznania punktów startowych, potem idź naprzód:
Proś o ścieżki plików i nazwy funkcji w kolejności, i zakończ pytaniem: „Jak bym to szybko przetestował?”
Szukaj tam, gdzie system podejmuje decyzje albo zmienia stan:
Użyj prostego systemu oznaczania i dołącz jedną czynność weryfikującą.
Przykład formatu:
Zmuszaj asystenta do rozdzielenia dowodów od domysłów.
Poproś, żeby oznaczał każde stwierdzenie jednym z:
Kiedy coś jest nieznane, przekształć to w pytanie do współpracownika (np. „Gdzie definiowana jest rola X?”) zamiast pozwalać asystentowi wypełniać lukę domysłami.
Trzymaj jedną lekką notatkę z pięcioma sekcjami:
Domyślnie wykonaj krótki, realny test:
To weryfikuje, że odwzorowana ścieżka to ta, której aplikacja rzeczywiście używa.
Wykorzystaj funkcje platformy, żeby zmniejszyć blast radius i utrzymać zmiany czytelnymi.
Praktyczne domyślne podejścia:
Następnie zapytaj: „Co może się zepsuć po cichu i jak byśmy to zauważyli?”
Trzymaj to krótkie, żeby faktycznie to aktualizować w miarę nauki.
Dodaj do każdego przepływu linijkę: „Jak bym to przetestował?” — wtedy notes staje się checklistą.
To działa zwłaszcza przy zadaniach onboardingu typu „dodaj guardrail”, „zaostrzyć walidację” lub „ulepszyć ścieżkę błędu”.