Jak wpuścić zewnętrznych seniorów do istniejącego codebase’u bez 3 miesięcy onboardingu
Wynajmujesz seniorów z zewnątrz, bo chcesz przyspieszyć rozwój. Pierwszy miesiąc wygląda jednak inaczej, niż obiecywał budżet: nowa osoba odkrywa system. Pyta. Szpera. Czeka na dostępy. Seniorzy z Twojego zespołu odrywają się od własnej pracy, żeby tłumaczyć to samo po raz kolejny. Po trzech miesiącach wreszcie „łapie kontekst”, a właśnie wtedy miałeś już mieć efekty.
Problem rzadko leży w kompetencjach. Senior czyta kod sprawnie, ale w trzy dni nie odgadnie, czemu system ma 50 mikroserwisów zamiast 15, co działa lokalnie, a co tylko w chmurze, i do kogo iść z konkretnym problemem. Ta wiedza siedzi w głowach ludzi. Dopóki jej stamtąd nie wyciągniesz, każdy zewnętrzny senior będzie płacił ten sam podatek wdrożeniowy.
Poniżej: co konkretnie przygotować, zanim ktoś nowy wejdzie do repozytorium, na podstawie tego, czego brakuje ludziom, którzy regularnie wchodzą w istniejące projekty.
W skrócie
- Seniorowi z zewnątrz wystarczy mapa systemu, decyzje z uzasadnieniem i osoba, do której wolno napisać bez wstydu. Trzy miesiące „poznawania firmy” zwykle wynikają z braku tych trzech rzeczy.
- Najwięcej czasu zjada brak odpowiedzi na pytania: co gdzie działa, jak wdrożyć zmianę, dlaczego architektura wygląda tak, a nie inaczej, i kto za co odpowiada.
- Onboarding pack działa jako checklista checkpointów: topologia, lokalne uruchomienie, środowiska, dostępy, ADR-y, integracje, domena i krytyczne ścieżki biznesowe.
- Bez otwartości poprzedniego zespołu (albo bez spisanej wiedzy) nowi ludzie odkrywają system metodą szperania po chmurze i ticketach. To drogie i wolne.
- Testy i observability pomagają, ale dopiero po tym, gdy nowa osoba wie, po co system istnieje i gdzie może bezpiecznie coś zmienić.
Trzy miesiące onboardingu to zwykle koszt braku kontekstu
Gdy mówimy o onboardingu zewnętrznych seniorów, często myślimy o szkoleniach z procesu, HR i kulturze firmy. To ważne, ale największy koszt powstaje gdzie indziej: gdy doświadczona osoba musi samodzielnie odtworzyć obraz systemu, który ktoś inny budował latami.
W jednym z projektów, które przejmowaliśmy, Marcinowi Zającowi od pierwszego dnia pomogłoby kilka prostych rzeczy. Dokumentacja o tym, jak wygląda development: co się gdzie uruchamia, co da się postawić lokalnie, a co bierze się bezpośrednio z chmury, oraz jak wygląda ścieżka wdrożeń na środowiska. Spisane decyzje architektoniczne, bo bez nich nie wiadomo, czemu system ma akurat tyle serwisów, a nie mniej albo więcej. Możliwość konsultacji z zespołem, który wcześniej ten system budował. Oraz lista składowych systemu w jednym miejscu, zamiast odkrywania kolejnych elementów przez panel Azure.
Marcin ujął to tak:
„Pomogłaby dokumentacja o tym, jak wygląda development: co się gdzie uruchamia, co lokalnie, a co bierzemy bezpośrednio z Azure, co się da zrobić lokalnie, a co nie, jak wygląda ścieżka wdrożeń na środowiska. Architecture decision records: tutaj nie było nic, nie widzieliśmy więc, dlaczego jest 50 mikroserwisów, a nie 80 albo 15. Nie wiadomo było, dlaczego tak, a nie inaczej, co utrudniało dalszy development. Składowe systemu zebrane w jednym miejscu w dokumentacji; w praktyce mieliśmy odkrywanie, szperając po Azure i szukając kolejnych elementów systemu.”
Te elementy pozwalają seniorowi zacząć pracować nad projektem znacznie szybciej, bez długiego okresu wdrożenia.
Dominik Króliczek, który regularnie wdraża ludzi w projekty i sam wchodzi w istniejące codebase’y, idzie o krok dalej: zwykle brakuje planu wdrożeniowego. Przyda się lista miejsc i artefaktów, które nowa osoba ma poznać w konkretnej kolejności. Rozmowa z kimś doświadczonym w projekcie jest bezcenna. Ale rozmowa bez checklisty zostawia wiedzę znowu w jednej głowie.
„Zazwyczaj brakuje takiego planu wdrożeniowego. To coś, co przygotowywałem, jak onboardowałem nowe osoby: lista rzeczy albo miejsc, które powinienem poznać i przeczytać. Onboarding typu «ktoś mi opowiada o tym projekcie» jest bardzo istotny i to zaleta. Natomiast fakt, że mam listę checkpointów do sprawdzenia, czyli taki onboarding plan, to bym przygotował, gdybym miał wdrażać nowe osoby od razu.”
Onboarding pack zamiast „wdrażaj się sam”
Przygotuj dla zewnętrznego seniora zestaw startowy: prostą, klarowną mapę wejścia z listą kluczowych punktów do poznania i odhaczenia. Taki onboarding pack pozwoli mu rozpocząć efektywną pracę znacznie szybciej.
1. Topologia systemu (najlepiej C4, poziom 1 i 2)
Zanim nowa osoba zacznie zagłębiać się w konkretne repozytorium, potrzebuje spojrzenia na cały system z lotu ptaka. Powinna wiedzieć, jakie są główne elementy systemu, w jaki sposób się komunikują i gdzie przebiegają między nimi granice. W tym celu wystarczą diagramy C4 na poziomie kontekstu i kontenerów. Bez takiego ogólnego obrazu senior przez długie tygodnie będzie samodzielnie próbował odtworzyć strukturę systemu, analizując logi, nazwy serwisów i wyciągając wnioski z fragmentów kodu.
Dominik wprost wskazuje, czego szuka w takim packu:
„Dałbym odnośnik do dokumentacji: jaka jest generalna topologia systemu. Najlepiej jakieś diagramy C4 na poziomie pierwszym i drugim. Jakie są komponenty systemu i jak można taki system odpalić lokalnie. Lista środowisk, najlepiej z informacją, skąd wziąć albo jak zdobyć dostępy. Lista osób: kto za co odpowiada, z imienia, nazwiska, roli, jak długo jest w projekcie. Najlepiej, gdybym miał jedną osobę, tak zwanego buddy’ego, do którego wiem, że mogę napisać w razie każdej potrzeby. Komunikację między komponentami na poziomie C4 level 2 chciałbym znać, a nie odkrywać ją przez pierwsze trzy miesiące.”
2. Jak odpalić cokolwiek lokalnie
Pierwszy sukces nowej osoby to zwykle mała zmiana z widocznym efektem. Dlatego w packu musi być jasna odpowiedź: co da się uruchomić lokalnie, czego nie da się, co trzeba podpiąć do środowisk współdzielonych, i jak ocenić, że zmiana działa.
3. Lista środowisk i dostępów
Dev, test, staging, produkcja, plus informacja, skąd wziąć dostęp i kto go nadaje. Brzmi banalnie. W praktyce nowa osoba potrafi tydzień czekać na podstawowe uprawnienia, a dopiero potem odkrywać, że połowy systemu i tak nie da się ruszyć bez kolejnego ticketu. Dostępy są warunkiem absolutnie koniecznym.
4. Kto za co odpowiada + buddy
Imię, nazwisko, rola, za co odpowiada, ewentualnie jak długo jest w projekcie. Opcjonalnie, ale bardzo praktycznie: jedna osoba-buddy, do której wolno pisać z każdym pytaniem. Bez tego senior albo spamuje wszystkich, albo milczy zbyt długo, bo nie chce „przeszkadzać”.
5. Jak wygląda wdrożenie i infrastruktura
Najczęściej system żyje w chmurze. Najczęściej też brakuje krótkiego opisu, jak trafia na środowiska i kto za deployment odpowiada. Jeśli jest Infrastructure as Code, to plus, ale nadal warto mieć dokumentację topologii i uzasadnienie decyzji. Samo „kod infrastruktury jest w repo” nie mówi nowej osobie, czemu wygląda właśnie tak.
Dlaczego system wygląda tak, a nie inaczej: ADR i drivers
Kod pokazuje stan obecny. Uzasadnienie decyzji trzeba spisać osobno.
Bez Architecture Decision Records nowy senior widzi 50 mikroserwisów i nie wie, czy to świadomy wybór, efekt braku czasu, ograniczenie kompetencji, czy decyzja pod konkretny driver (na przykład time-to-market). Nie wie też, czy wolno to upraszczać, czy ruszenie struktury zerwie coś krytycznego. To utrudnia dalszy development bardziej niż brak ładnego diagramu.
Dominik opisuje ten moment wejścia wprost:
„Przychodzę i jestem w projekcie, który jest w obecnym stanie. Zawsze on jest nie taki, jakbym chciał, i ja nie wiem, czemu został doprowadzony do takiego stanu: czy ktoś nie miał kompetencji, czy AI generował masowo i nikt na to nie patrzył, czy może świadomie ludzie decydowali się na rozwiązania «na kolanie», bo trzeba było coś dowieźć. Nie wiadomo, czemu dana baza jest użyta. Może powodem jest to, że była to pierwsza z brzegu technologia, i okej, fajnie o tym wiedzieć.”
W ADR-ach warto zapisywać decyzję wraz z uzasadnieniem. Jeszcze lepiej, gdy zespół zna architecture drivers: czym w ogóle kierowano się przy wyborach technicznych.
„Decision log typu ADR by się przydał. Architecture drivers też, ale tego nigdy nie spotkałem w projekcie poza własnym: czym kierowały się osoby podejmujące decyzje techniczne w tym projekcie.”
Ta sama logika dotyczy listy integracji third-party: z czym system się łączy, czy piszemy, czytamy, czy obie strony, synchronicznie czy asynchronicznie, i jakie są kluczowe use case’y. Bez tego nowa osoba odkrywa zależności dopiero wtedy, gdy pierwsza zmiana coś zepsuje po drodze.
Więcej o tym, jakiej dokumentacji wymagać od dostawcy (i w jakiej formie), pisaliśmy osobno: jakiej dokumentacji wymagać od zewnętrznego dostawcy oprogramowania.
Biznes i domena: bez tego senior optymalizuje niewłaściwe rzeczy
Onboarding techniczny bez kontekstu biznesowego daje Ci kogoś, kto potrafi poprawić kod, ale nie wie, co jest krytyczne.
W packu powinny znaleźć się odpowiedzi na proste pytania:
- Na czym ten produkt zarabia?
- Jakie są krytyczne funkcjonalności i ścieżki użytkownika?
- Kim jest użytkownik i jak realnie korzysta z systemu?
- Co się stanie, gdy system padnie, i w jakich godzinach boli to najbardziej?
- Jak wygląda wizja stakeholderów: po co to wszystko w ogóle powstało?
Dominik dodaje jeszcze jedną, często pomijaną warstwę:
„Fajnie by było wiedzieć, na czym zarabia ten projekt, co jest krytyczną funkcjonalnością, kto jest użytkownikiem danego systemu i znać dokładnie, jak on jest używany. Jeszcze jedna rzecz, może trochę nieoczywista: wizja stakeholderów, po co to wszystko jest zrobione. Ludzie zazwyczaj o tym nie myślą na co dzień, więc podczas onboardingu nie zawsze to jest przekazane. Jakie są krytyczne ścieżki dla systemu, co się najgorszego może wydarzyć, co się stanie, jak system pada.”
Do tego wprowadzenie do domeny: słowniczek pojęć oraz lista ekspertów domenowych (kto od czego).
„Fajnie by było mieć też wprowadzenie do domeny. Co to za domena? Jakieś vocabulary domenowe, w sensie słowniczek, i kto jest ekspertem domenowym od czego.”
Ludzie w zespole często „wiedzą to na co dzień”, więc podczas onboardingu pomijają ten przekaz. Potem okazuje się, że nawet w istniejącym zespole nie ma wspólnego zrozumienia, co jest krytyczne.
Observability, testy i tribal knowledge
Kiedy dokumentacja i zapisane decyzje są już dostępne, dwa kolejne elementy pozwalają jeszcze szybciej wdrożyć nową osobę.
Observability. Dostęp do monitoringu oraz krótki guide: jak sprawdzić, czy produkcja nie spadła, gdzie patrzeć i co jest sygnałem alarmowym.
Testy. Unit, integracyjne, end-to-end skracają strach przed pierwszą zmianą. Senior szybciej sprawdza, czy nie zepsuł krytycznej ścieżki. Przy wdrożeniu nie zastąpią jednak mapy systemu ani ADR-ów.
Wspólnym mianownikiem jest tribal knowledge: wiedza, która żyje tylko w głowach. Cel onboardingu packa jest praktyczny: jak najwięcej z tej wiedzy ma trafić do markdowna blisko kodu (albo choćby do jednego, aktualnego miejsca w wiki), skąd da się ją przeczytać bez 15 rozmów.
„Chodzi po prostu o dobre praktyki i widoczność, żeby jak najmniej rzeczy, które są w głowach ludzi, tak zwany tribal knowledge, było wyciągnięte do markdowna albo w gorszym wypadku do Confluence, i można było zapytać, przeczytać albo choć wiedzieć, że gdzieś coś jest spisane. Fajnie by było mieć też dostęp do monitoringu i observability. Jeżeli tego nie ma w projekcie, to utrudnia. Jeżeli jest, to trzeba się często samemu rozeznać, co gdzie jest. Fajnie by było mieć guide, jak sprawdzić, czy produkcja nie spadła.”
Otwartość poprzedniego zespołu to też artefakt
Część onboardingu nie da się zapisać w pliku. Czasem nowi ludzie potrzebują po prostu móc zapytać tych, którzy system budowali.
Gdy poprzedni dostawca nie jest otwarty na konsultacje, zewnętrzni seniorzy zostają sami ze śledztwem: szukają kolejnych elementów w chmurze, odtwarzają decyzje z commitów i uczą się na błędach. Da się tak dojść do sprawności, ale zajmuje to miesiące i generuje koszt, którego nie widać w stawce godzinowej.
Przy zmianie partnera lub dołączaniu zewnętrznych seniorów konieczne jest jasne określenie: kto z poprzedniego zespołu będzie dostępny, w jakim zakresie oraz przez jaki czas. Brak takiej współpracy wydłuża okres od rozpoczęcia pracy do wykonania pierwszej wartościowej zmiany.
Jeśli przejmujesz projekt po dostawcy, który nie współpracuje albo zostawił system w złym stanie, sam pack dokumentacji może nie wystarczyć. Wtedy potrzebujesz podejścia typowego dla przejmowania projektów: najpierw odzyskać kontrolę nad produkcją, dostępami i krytycznymi flow, a dopiero potem oczekiwać tempa od nowych seniorów.
Checklista: co mieć gotowe przed day 1 zewnętrznego seniora
- [ ] Onboarding plan z kolejnością checkpointów (zamiast samego „poczytaj Confluence”)
- [ ] Diagram topologii (C4 L1/L2 albo równoważny obraz komponentów i komunikacji)
- [ ] Instrukcja lokalnego uruchomienia: co działa lokalnie, co nie, jak ocenić zmianę
- [ ] Lista środowisk + ścieżka zdobycia dostępów
- [ ] Mapa odpowiedzialności (kto za co) + wyznaczony buddy
- [ ] Opis ścieżki wdrożeń i topologii infrastruktury (oraz „dlaczego tak”)
- [ ] ADR-y / decision log dla kluczowych wyborów architektonicznych
- [ ] Lista integracji third-party i ich use case’ów
- [ ] Krótki opis biznesu: zarabianie, użytkownicy, krytyczne ścieżki, skutki awarii
- [ ] Słownik domenowy + eksperci domenowi
- [ ] Guide do observability: jak sprawdzić zdrowie produkcji
- [ ] Informacja, z kim z poprzedniego / obecnego zespołu wolno konsultować braki w wiedzy
Co zrobić, zanim zatrudnisz kolejną osobę z zewnątrz
Zanim zdecydujesz się zatrudnić kolejnego seniora, zastanów się, czy Twoje środowisko i codebase rzeczywiście pozwalają na sprawne wdrożenie kogoś nowego, niezależnie od tego, jakie ma CV.
Dobrym punktem wyjścia jest checklista stanu technicznego produktu: architektura, testy, CI/CD, observability, dane i bezpieczeństwo. Luki w tych obszarach zwykle tłumaczą, czemu onboarding trwa kwartał, mimo że na papierze bierzesz „bardzo doświadczonych ludzi”.
Jeśli nie masz dobrej dokumentacji, jasno opisanych decyzji i porządnej mapy systemu, w pierwszej kolejności zadbaj o uzupełnienie tych braków lub zaangażuj partnera, który potrafi zdobywać i spisywać wiedzę podczas pracy. W przeciwnym razie każda nowa doświadczona osoba z zewnątrz będzie musiała samodzielnie, od początku, odkrywać wszystkie istotne informacje, co generuje dodatkowe koszty i opóźnienia.
