Onboarding developera — udowodnij jeden bezpieczny workflow

Czas onboardingu developera, tak jak ocenia go pytanie Q19 w CTO Scorecard, to czas, w jakim nowa osoba przechodzi od czystej maszyny do zweryfikowanej zmiany próbnej w jednym zatwierdzonym workflow z agentem. Maksymalny wynik wymaga powtarzalnego fixture onboardingu, który przechodzi w ciągu jednego dnia roboczego, bez wspólnych sekretów.

Ta strona jest dla tech leada, który odpowiada za onboarding, i dla CTO, który odpowiada na Q19. Sytuacja: nowa osoba zaczęła w poniedziałek, skrypt instalacyjny skończył się po dziesięciu minutach, a w czwartek wciąż pyta na czacie, dlaczego agent ignoruje konwencje repozytorium i jakiego tokena potrzebują testy integracyjne. Instalacja zadziałała. Workflow nie.

Co daje ci fixture onboardingu

• Tabelę punktacji Q19 i jej związek z pytaniem 4 w Tech Lead Scorecard.
• Szablon karty fixture, który definiuje zadanie, dowody i sposób liczenia czasu — gotowy do wypełnienia.
• Przebieg w sześciu krokach z dokładnymi sprawdzeniami bootstrapu dla Claude Code i Codeksa oraz listą rzeczy do ręcznego sprawdzenia w Cursorze.
• Arkusz czasu, który oddziela czas pracy od czasu oczekiwania, żeby każde opóźnienie miało właściciela.
• Trzy prompty do skopiowania, sposób weryfikacji przebiegu bez patrzenia nowej osobie przez ramię i typowe awarie, przy których onboarding wygląda na rozwiązany, choć nie jest.

Jak CTO Scorecard Q19 ocenia czas onboardingu?

Scorecard pyta: „Jak długo trwa »time to productive AI workflow« dla nowego developera?” i punktuje cztery odpowiedzi.

Punkty	Odpowiedź	Dowód, który ją uzasadnia
0	Nie mierzymy, każdy radzi sobie sam	Brak.
1	Tydzień lub dłużej z dokumentacją setupu	Strona w wiki i opiekun.
2	Jeden–dwa dni ze skryptem bootstrap i dokumentacją	Skrypt, który instaluje narzędzia, i dokumentacja opisująca resztę.
3	Reprezentatywny fixture onboardingu przechodzi w jeden dzień roboczy: bezpieczny bootstrap, kontekst repozytorium, zadanie próbne, wymagane checki i brak wspólnych sekretów	Karta fixture, arkusze czasu z dwóch ostatnich przebiegów i pakiet dowodów z każdego z nich.

Liczy się przejście z 2 na 3. Skrypt bootstrap dowodzi, że narzędzia się instalują. Fixture dowodzi, że nowa osoba potrafi z agentem zaplanować, zmienić, zweryfikować i przekazać dalej pracę — i to właśnie na tej stronie znaczy „produktywny”.

Tech Lead Scorecard zadaje to samo pytanie z perspektywy zespołu („Gdy dołącza nowy dev, jak szybko jest produktywny z Waszym setupem AI?”) i najwyżej ocenia bootstrap jednym poleceniem plus ścieżkę onboardingu. Zaliczony fixture spełnia oba warunki: bootstrap to jego pierwsza połowa, zadanie próbne — druga.

Wybierz zadanie, które przechodzi przez prawdziwą ścieżkę

Fixture to jedno zadanie, które każda nowa osoba wykonuje pierwszego dnia. Musi dotykać tego samego repozytorium, tych samych bramek i granic zatwierdzeń co prawdziwa praca, a przy tym dać się bezpiecznie powtarzać.

Wybierz zadanie, które…	Unikaj zadania, które…
Zmienia jedno małe, udokumentowane zachowanie w repozytorium produkcyjnym	Żyje w repozytorium-zabawce, z którego nikt nie wdraża
Wymaga nowego lub zmienionego testu, który przed zmianą nie przechodzi	Da się zaliczyć bez żadnego testu
Uruchamia te same bramki lint, typów i testów co każdy pull request	Pomija CI, „bo to onboarding”
Kończy się draftem pull requesta z pakietem dowodów	Kończy się na „u mnie działa”
Nie dotyka danych produkcyjnych, wdrożeń ani sekretów poza własnym logowaniem	Wymaga wspólnego tokena usługi albo dostępu do produkcji
Pozostaje aktualne przez miesiące (stabilny moduł, znany przypadek brzegowy)	Zależy od backlogu bieżącego sprintu

Trzymaj pulę trzech–pięciu takich zadań, resetowaną skryptem, żeby dwie osoby zaczynające w tym samym tygodniu nie kopiowały od siebie odpowiedzi. Uruchamiaj fixture w narzędziu zatwierdzonym przez politykę narzędzi; nie wymagaj wszystkich trzech, jeśli zespół standaryzuje się na jednym.

Napisz kartę fixture przed pierwszym przebiegiem

Karta ustala, co liczy się jako zaliczenie, więc pomiar czasu znaczy za każdym razem to samo. Trzymaj ją w repozytorium obok dokumentacji onboardingu.

KARTA FIXTURE ONBOARDINGU — payments-api
Właściciel:              Tech lead zespołu płatności
Zatwierdzone narzędzia:  Claude Code, Codex lub Cursor (wg polityki narzędzi v3)
Warunki wstępne:         Zarządzane konto indywidualne, dostęp do repozytorium
                         i do magazynu sekretów nadane PRZED pierwszym dniem
                         (czas realizacji zapisywany osobno)
Bootstrap:               ./scripts/onboard.sh — przypięte wersje narzędzi,
                         idempotentny, przy każdym nieudanym sprawdzeniu kończy się
                         kodem niezerowym i komunikatem, jak to naprawić
Wczytany kontekst:       AGENTS.md (lub CLAUDE.md), mapa architektury
                         docs/architecture.md, lista chronionych ścieżek,
                         granice zatwierdzeń w docs/policy/
Pula zadań próbnych:     docs/onboarding/tasks/ (5 zadań, reset przez
                         scripts/reset-fixture.sh)
Kryteria zaliczenia:     1. Plan zaakceptowany przez opiekuna przed jakąkolwiek edycją
                         2. Diff ograniczony do plików wymienionych w planie
                         3. Nowy test nie przechodzi przed zmianą i przechodzi po niej
                         4. Lint, sprawdzanie typów i testy zielone w CI
                         5. Draft PR zawiera pakiet dowodów i wskazuje ludzkie bramki
                         6. Żadnego sekretu w pliku, commicie, prompcie ani na czacie
Zegar:                   Startuje, gdy nowa osoba otwiera przygotowany laptop;
                         staje, gdy opiekun akceptuje draft PR według kryteriów
Cel:                     W ciągu jednego dnia roboczego, praca plus oczekiwanie
Zapisywane:              Czas pracy, czas oczekiwania według przyczyny,
                         interwencje, nieudane kroki
Ponowny test:            Po każdej zmianie onboard.sh, AGENTS.md lub wersji narzędzi
                         i co najmniej raz na kwartał przez kogoś, kto go nie pisał

Zegar celowo startuje dopiero po provisioningu. Tożsamość, dostęp do repozytorium i do magazynu sekretów to warunki wstępne, które powinny być gotowe przed pierwszym dniem. Czas ich realizacji zapisz w arkuszu jako osobną pozycję — wtedy wolny wniosek o dostęp jest widoczny i nie chowa się w czasie fixture.

Przeprowadź fixture onboardingu w sześciu krokach

1. Nadaj tożsamość przed pierwszym dniem. Daj nowej osobie zarządzane konto indywidualne w zatwierdzonym narzędziu, dostęp do repozytorium według zasady najmniejszych uprawnień i własny wpis w magazynie sekretów. Nigdy wspólnego loginu ani zespołowego klucza API. Model kont i sekretów opisuje strona tożsamość agentów i sekrety.

2. Uruchom bootstrap i jego sprawdzenia. Bootstrap instaluje przypięte wersje, a potem sam się sprawdza: narzędzie jest w PATH, zalogowane kontem tej osoby, serwery MCP połączone, instrukcje repozytorium obecne. Każde nieudane sprawdzenie wypisuje sposób naprawy. Polecenia dla poszczególnych narzędzi są w następnej sekcji.

3. Wczytaj i potwierdź kontekst repozytorium. Nowa osoba prosi agenta o podsumowanie zasad repozytorium (pierwszy prompt poniżej) i porównuje odpowiedź z dokumentacją. Agent, który nie potrafi zacytować chronionych ścieżek ani wymaganych checków, nie wczytał instrukcji — niezależnie od tego, co mówi log instalacji. Co powinny zawierać te instrukcje, opisuje strona wspólne reguły agentów.

4. Zaplanuj zadanie próbne i uzyskaj akceptację planu. Agent wymienia pliki, kryteria akceptacji, testy, ryzyka i warunki zatrzymania; opiekun akceptuje lub poprawia plan przed jakąkolwiek edycją. To pierwsza ludzka bramka, którą poznaje nowa osoba.

5. Wykonaj, a potem zweryfikuj z czystego stanu. Agent najpierw pisze test, który nie przechodzi, potem wprowadza zmianę i uruchamia te same bramki co CI. Nowa osoba otwiera draft pull requesta z pakietem dowodów: polecenia, wyniki i każde kryterium zaliczenia przypisane do dowodu. Format manifestu opisuje strona pakiet dowodów.

6. Wypełnij arkusz czasu i zrób 15-minutowe podsumowanie. Zapisz czas pracy, czas oczekiwania według przyczyny, każdą interwencję i każdy krok, którego dokumentacja nie objęła. Każda luka staje się zgłoszeniem z właścicielem i datą ponownego testu.

Sprawdź bootstrap w każdym narzędziu

Skrypt bootstrap powinien kończyć się tymi sprawdzeniami i przerywać na pierwszym, które nie przejdzie. Kosztują sekundy, a wyłapują awarie, których nowa osoba nie zdiagnozuje sama.

Claude Code

Sprawdzone na Claude Code 2.1.283.

claude --version                 # porównaj z wersją przypiętą w karcie fixture
claude doctor                    # stan instalacji i ustawień
claude auth status --text        # zalogowany własnym kontem tej osoby
claude mcp list                  # serwery z projektowego .mcp.json: połączone albo czekające na zatwierdzenie

Dwie pułapki. Po pierwsze, claude mcp list pokazuje serwery z projektowego .mcp.json jako „Pending approval”, dopóki nowa osoba ich nie zatwierdzi; serwer oczekujący nie jest połączony, więc zadanie próbne wyłoży się później na brakującym narzędziu. Po drugie, Claude Code czyta AGENTS.md tylko wtedy, gdy projekt nie ma CLAUDE.md, i dopiero od v2.1.277 (od v2.1.281 na Bedrock, Google Cloud, Microsoft Foundry, bramkach LLM albo z wyłączoną telemetrią), którą mają oba kanały wydań, odkąd stable doszedł do v2.1.287 (sprawdzone 2026-10-12). Jeśli repozytorium trzyma zasady wyłącznie w AGENTS.md, utrzymuj też CLAUDE.md dla inżynierów na starszych wersjach, a prompt kontekstowy z kroku 3 niech potwierdzi, że zasady się wczytały.

Codex

Sprawdzone na Codex CLI 0.157.1.

codex --version                  # porównaj z wersją przypiętą w karcie fixture
codex doctor --json              # stan instalacji, konfiguracji, logowania i środowiska (zredagowany)
codex login status               # zalogowany własnym kontem tej osoby
codex mcp list                   # zewnętrzne serwery MCP, z którymi połączy się Codex

Pułapka. Od Codeksa 0.150.0 niezaufany projekt nie dostarcza projektowego AGENTS.md, a hooki Codeksa wymagają utrwalonego zaufania, zanim się uruchomią. Nowa osoba, która odrzuci pytanie o zaufanie, dostaje agenta bez zasad repozytorium i bez jego hooków ochronnych, a nic głośno nie zawodzi. Zrób z zaufania do repozytorium jawny krok bootstrapu i niech prompt kontekstowy z kroku 3 udowodni, że zadziałało. Raport --json z codex doctor dołącz do pakietu dowodów.

Cursor

Dokumentacja Cursora była 2026-09-26 niedostępna do weryfikacji aktualnych szczegółów setupu, więc ta zakładka nie podaje żadnego polecenia. Sprawdź ręcznie w IDE, że nowa osoba jest zalogowana zarządzanym kontem, że Rules i serwery MCP projektu są widoczne jako wczytane i że prompt kontekstowy z kroku 3 poprawnie cytuje zasady repozytorium. Ten ostatni test nie zależy od narzędzia i to on się liczy.

Sprawdzenie bootstrapu, które potwierdza tylko instalację narzędzia, nie wystarcza. Najwięcej dni zabierają nowej osobie ciche awarie: serwer czekający na zatwierdzenie, niewczytane instrukcje, niezaufany projekt.

Mierz fixture tak, żeby każde opóźnienie miało właściciela

Pojedyncza liczba „zajęło 2 dni” nie daje się przełożyć na działanie. Rozbij ją, a każda część wskaże innego właściciela.

Pozycja w arkuszu czasu	Co mierzy	Zwykle właściciel słabego wyniku
Czas provisioningu	Od wniosku o dostęp do gotowego konta, repozytorium i magazynu sekretów	Zespół IT lub platformowy
Czas bootstrapu	Od otwarcia laptopa do zielonych sprawdzeń bootstrapu	Właściciel platformy lub developer experience
Czas kontekstu	Od zielonego bootstrapu do poprawnego podsumowania zasad repozytorium	Właściciel AGENTS.md / CLAUDE.md
Czas pracy nad zadaniem	Plan napisany, zmiana wprowadzona, checki uruchomione	Nowa osoba razem z autorem zadania fixture
Czas oczekiwania według przyczyny	Akceptacja planu, kolejka CI, review, zgłoszenia o dostęp	Właściciel danej kolejki
Interwencje	Każda pomoc poza udokumentowaną ścieżką	Dokumentacja lub skrypt, które powinny to pokryć

Raportuj medianę ostatnich przebiegów per repozytorium, nigdy ranking osób. Dowodem dla Q19 jest karta fixture, dwa ostatnie arkusze czasu i ich pakiety dowodów.

Prompty do skopiowania dla fixture onboardingu

Uruchom je w zatwierdzonym narzędziu, z katalogu głównego repozytorium, pierwszego dnia nowej osoby. Działają tak samo w Claude Code, Codeksie i Cursorze.

Prompt do skopiowania: potwierdź, że kontekst repozytorium się wczytał

Before we touch any code, read this repository's agent instructions (AGENTS.md or CLAUDE.md and any files they reference) and report, quoting the source line for each item:
1. The commands for lint, type check and tests, exactly as written.
2. The protected paths and resources you must not change.
3. The actions that need a human's approval.
4. Where two instruction sources disagree.
If you cannot find an instruction file, say so and stop. Do not infer rules from the code.

Prompt do skopiowania: zaplanuj zadanie fixture przed edycją

Read docs/onboarding/tasks/02-currency-rounding.md. Do not edit anything yet.
Write a plan with: the files you will change and why, the acceptance criteria in testable form, the test you will add and why it fails today, the commands you will run to verify, the risks, and the conditions under which you will stop and ask.
Keep the change inside the files you name. Wait for me to accept the plan.

Prompt do skopiowania: zweryfikuj wynik i zgłoś luki w dokumentacji

The change is done. From a clean state, run the repository's lint, type check and full test suite, and show that the new test fails on the base commit and passes on this branch.
Then write the evidence section for the draft pull request: each pass criterion from docs/onboarding/fixture-card.md with the command and result that proves it, the human gates still open, and a list of every step in this session that the onboarding docs did not explain, including any help I got outside the docs.
Check the diff and the session for credentials, tokens or .env values and report what you found.

Nazwę pliku zadania zastąp jednym z własnej puli. Ostatni prompt robi dwie rzeczy: tworzy pakiet dowodów i zamienia zagubienie nowej osoby w zgłoszenia do dokumentacji.

Jak zweryfikować fixture bez patrzenia nowej osobie przez ramię?

Opiekun nie powinien siedzieć obok nowej osoby ani czytać każdej linii diffu próbnego. Przebieg weryfikuje się na podstawie artefaktów.

• Kryteria zaliczenia sprawdzają systemy. CI uruchamia te same bramki co przy każdym pull requeście. Test, który przed zmianą nie przechodzi, a po niej tak, dowodzi, że zmiana robi to, co zapowiadał plan.
• Plan jest punktem ludzkiego review. Opiekun ocenia plan względem zadania, a potem pakiet dowodów względem planu — nie diff linia po linii.
• Higienę sekretów się skanuje, a nie zakłada. Skaner sekretów repozytorium i hooki pre-commit działają na gałęzi fixture; każde trafienie oblewa przebieg, niezależnie od reszty.
• O wczytanym kontekście świadczy odpowiedź agenta. Wynik promptu kontekstowego, z zacytowanymi liniami źródłowymi, trafia do pakietu dowodów. Jeśli agent przekręci regułę, krok kontekstu nie przeszedł.
• Druga osoba powtarza przebieg. Raz na kwartał ktoś, kto nie pisał fixture, uruchamia go na świeżej maszynie lub w kontenerze. To wyłapuje wiedzę, którą autorzy dokładają, nie zauważając tego.
• Nazwany właściciel zatwierdza. Tech lead akceptuje każdy przebieg względem karty i odpowiada za zgłoszenia z podsumowania.

Co idzie nie tak przy mierzeniu czasu onboardingu?

Bootstrap uchodzi za dowód. Instalator jest zielony po dziesięciu minutach, wynik skacze na 3, a nowe osoby nadal nie odróżniają sandboksa od produkcji. Wyjście: zatrzymuj zegar na zaakceptowanym drafcie pull requesta, nie na końcu skryptu.

Wspólny token siedzi w dokumentacji onboardingu. Przyspieszył pierwszy dzień, a teraz leży w wiki, w pliku konfiguracyjnym i w kilku historiach czatu. Wyjście: zrotuj token dziś, daj każdej osobie własny dostęp przez magazyn sekretów i dodaj regułę skanera dla formatu tego tokena.

Agent działa bez zasad repozytorium. Oczekujący serwer MCP, niezaufany projekt w Codeksie albo Claude Code na kanale, który nie czyta AGENTS.md, zostawiają agenta w domysłach, a nowa osoba obwinia siebie. Wyjście: zrób z promptu kontekstowego kryterium zaliczenia i dodaj odpowiednie sprawdzenie do bootstrapu.

Fixture zalicza opiekun. Pomoc na czacie nigdzie się nie odnotowuje, a przebieg wygląda na szybki. Wyjście: zapisuj każdą interwencję w arkuszu czasu i traktuj przebieg z niezapisaną interwencją jako niezaliczony.

Fixture się starzeje. Wersje narzędzi zmieniają się co tydzień, moduł z zadania przechodzi refaktoryzację, a następna osoba trafia na błędy, których karta nie opisuje. Wyjście: testuj ponownie po każdej zmianie bootstrapu, instrukcji lub przypiętych wersji, a resztę niech wyłapie kwartalny przebieg osoby z zewnątrz. Jak nadążać za wydaniami narzędzi, opisuje strona bycie na bieżąco w zespole.

Zadanie jest zbyt proste, żeby czegoś nauczyć. Poprawka literówki przechodzi w 20 minut i nie dowodzi niczego o planowaniu ani weryfikacji. Wyjście: wymagaj nieprzechodzącego testu i akceptacji planu w każdym zadaniu z puli.

Czas oczekiwania ginie w sumie. Trzy godziny w kolejce CI wyglądają jak powolna osoba. Wyjście: raportuj czas oczekiwania według przyczyny i kieruj każdą przyczynę do właściciela danej kolejki.

Dokąd dalej po onboardingu developera

Gdy nowe osoby zaliczają fixture, zmierz, czy dalej korzystają z workflow, i zamieniaj luki z każdego przebiegu we wspólną wiedzę. Warunkiem szybkiego fixture jest repozytorium, w którym agent potrafi pracować — zobacz jak przygotować repozytorium dla agentów.

Q20 · Dzielenie się wiedzą Zamień luki z fixture w wersjonowaną wiedzę operacyjną.

Q1 · Adopcja w zespole Mierz ukończone workflow po pierwszym dniu.

Onboarding i adopcja w zespole Szerszy rollout, w który wpisuje się fixture.

Rozwój juniorów Czego uczy się nowa osoba, gdy kod piszą agenci.

Odpowiedzi na pozostałe pytania scorecardu znajdziesz w kluczu odpowiedzi CTO Scorecard.