Mapa adopcji dla jednego repozytorium: przejścia po drabinie pętla po pętli
Mapa adopcji dla jednego repozytorium przesuwa pętle dostarczania danej bazy kodu po drabinie autonomii o jeden szczebel naraz. Każda pętla, na przykład aktualizacje zależności, przechodzi z L2 na L3, L4, a czasem L5 dopiero wtedy, gdy dowody jej bramki widać w historii Gita, w CI i w pull requestach. To wycinek mapy drogi dla organizacji na poziomie repozytorium.
Ta strona jest dla tech leada, który odpowiada za jedno repozytorium. Plan organizacji mówi „pętle pilotażowe osiągają L3 w tym kwartale”, ośmiu inżynierów używa agentów na osiem różnych sposobów, a kolejka code review jest już dłuższa niż wiosną. Musisz wiedzieć, co zmienić w tym repozytorium, w jakiej kolejności i co udowadnia, że dany krok się udał.
Co daje ci mapa adopcji repozytorium
Dział zatytułowany „Co daje ci mapa adopcji repozytorium”- Rejestr
loops.yaml, który nazywa pętle repozytorium, ich obecny szczebel i następną bramkę. - Stan wyjściowy każdej pętli, policzony ze zmergowanych pull requestów, żeby każde późniejsze twierdzenie miało punkt odniesienia.
- Zmiany w repozytorium dla każdego przejścia: plik instrukcji, izolowane checkouty, chronione testy, pakiet dowodów, reguły auto-merge.
- Regułę „idziemy dalej” i „cofamy się” dla każdego przejścia, razem z tym, kto podpisuje.
- Trzy prompty: stan wyjściowy pętli, zadanie na L3 i sprawdzenie bramki pętli przed awansem.
Dlaczego repozytorium wspina się pętlami, a nie falami?
Dział zatytułowany „Dlaczego repozytorium wspina się pętlami, a nie falami?”Repozytorium nie jest na jednym poziomie. Aktualizacje zależności z testami kontraktowymi mogą bezpiecznie działać na L4, a praca nad integracją z operatorem płatności obok nich zostaje na L2, i obie odpowiedzi są jednocześnie poprawne. Jedna mapa definiuje pętlę jako powtarzalną klasę zmian z własnym wyzwalaczem, właścicielem i wyrocznią, i ocenia każdą pętlę po tym, co człowiek czyta przed merge’em.
Wcześniejsze wersje tej mapy adopcji opisywały stałe fale 0–5 dla całego repozytorium. Fale zawodziły w przewidywalny sposób: fala kończyła się według kalendarza, a wszystkie rodzaje zmian awansowały razem, więc tempo najbezpieczniejszej pętli wyznaczała ta najbardziej ryzykowna. Jeśli twój zespół wciąż używa nazw fal, przetłumacz je tą tabelą, a potem przestań ich używać.
| Wycofana fala | Co dodawała | Gdzie jest teraz |
|---|---|---|
| 0. Stan wyjściowy (Baseline) | Jedno repozytorium, bieżące metryki | Stan wyjściowy i rejestr pętli, przed pierwszym przejściem |
| 1. Najpierw artefakty | intent.md → spec.md → plan.md, tryb planowania | Dowody wejścia dla L2 → L3 |
| 2. Najpierw review | Review agentowe, chronione testy, ochrona gałęzi | L2 → L3 (ochrona gałęzi) oraz L3 → L4 (chronione testy, review agentowe) |
| 3. Bezpieczna równoległość | Jeden worktree na zadanie, zawężone poświadczenia | L2 → L3, izolowane checkouty |
| 4. Ograniczona automatyzacja | Kontrole headless, wynik czytelny maszynowo | L3 → L4, pakiet dowodów i bramka w CI |
| 5. Zamknięta pętla | Sygnał z produkcji zapisuje kolejną intencję | L4 → L5, etap utrzymania |
Przed pierwszym przejściem: wybierz repozytorium i zapisz stan wyjściowy
Dział zatytułowany „Przed pierwszym przejściem: wybierz repozytorium i zapisz stan wyjściowy”Wybierz repozytorium, które spełnia wszystkie poniższe warunki. Jeśli czegoś brakuje, napraw to najpierw, bo każda późniejsza bramka od tego zależy.
- Lokalne komendy typecheck, lint, test i build, które przechodzą na gałęzi domyślnej.
- Ochrona gałęzi z wymaganymi kontrolami statusu (required status checks) i wskazana z imienia osoba, która zatwierdza wydania na produkcję.
- Brak potrzeby dawania agentowi poświadczeń produkcyjnych.
- Co najmniej pięć zmergowanych zmian miesięcznie w pętli, którą przesuwasz jako pierwszą, żeby okno 30 dni zawierało wystarczająco dużo dowodów.
Następnie wyeksportuj historię, z której liczysz stan wyjściowy. Uruchom to w terminalu w katalogu głównym repozytorium, z zalogowanym GitHub CLI:
gh pr list --state merged --search "merged:>=$(date -d '90 days ago' +%F)" --limit 1000 \ --json number,title,labels,createdAt,mergedAt,additions,deletions,files,reviews,commits,statusCheckRollup,body \ > merged-prs.jsonForma date -d działa w GNU; na macOS wpisz $(date -v-90d +%F) albo ręcznie podaj datę sprzed 90 dni.
Zapisz pięć liczb dla każdej pętli: czas realizacji zmiany (lead time) od otwarcia pull requestu do merge’a, odsetek przebiegów CI zielonych za pierwszym podejściem, liczbę rund review, rozmiar pull requestu oraz odsetek revertów lub wdrożeń kończących się awarią (change-fail rate). Kanoniczne definicje są w ramach metryk. Celem nie jest maksymalna aktywność agentów, tylko krótszy czas realizacji przy odsetku awarii na poziomie stanu wyjściowego lub niższym.
Zarejestruj pętle repozytorium
Dział zatytułowany „Zarejestruj pętle repozytorium”Wpisz pętle do loops.yaml w katalogu głównym repozytorium i przeglądaj ten plik jak kod. Pełny schemat i prompt, który szkicuje plik z historii, znajdziesz na stronie jednej mapy; poniższy fragment pokazuje pola, z których korzysta ta mapa adopcji.
# loops.yaml (excerpt): one entry per repeatable class of change- loop: dependency-bumps owner: anna-kowalska # GitHub login of a named person, never a team alias risk_class: low # low | medium | high | critical level: L3 oracle: contract tests in tests/contract, owned in CODEOWNERS agent_can_edit_oracle: false baseline: { lead_time_days: 2.4, change_fail_rate: 0.03 } next_transition: to: L4 exit_criterion: evidence bundle on every merged PR for 30 days; 20 sampled reviews found no defect the evidence missed- loop: checkout-feature-work owner: piotr.nowak risk_class: medium level: L2 oracle: unit and integration tests in the same diff (agent-editable) agent_can_edit_oracle: true next_transition: to: L3 exit_criterion: agent runs typecheck, lint and tests before opening a PR; first-pass CI at or above baseline for 30 daysNastępnie nadaj każdej pętli etykietę pull requestu, żeby późniejsze sprawdzenia bramki mogły filtrować po pętli. Utwórz jedną etykietę na każdy wpis w loops.yaml, na przykład gh label create loop:dependency-bumps, i wymagaj jej: dodaj linię „Loop:” do szablonu pull requestu oraz kontrolę w CI, która odrzuca każdy pull request bez dokładnie jednej etykiety loop:.
Wartości stanu wyjściowego powyżej to przykłady; wstaw liczby z własnego eksportu. risk_class pętli ogranicza, jak wysoko może zajść: pętla klasy krytycznej, na przykład uwierzytelnianie albo przepływ pieniędzy, nie wychodzi ponad L3 w pierwszym roku bez względu na to, jak dobre ma dowody; pętla klasy wysokiej zostaje na L3, chyba że polityka zarządzania dopuszcza ją do L4; do L5 dochodzą tylko pętle klasy niskiej. Klasy przypisuje polityka zarządzania i autonomii.
Przez jakie przejścia przechodzi każda pętla?
Dział zatytułowany „Przez jakie przejścia przechodzi każda pętla?”Pętla wspina się o jeden szczebel naraz i nigdy nie przeskakuje z L2 na L4. Progi są zgodne z bramkami mapy drogi dla organizacji, więc twoje dowody trafiają do kwartalnego przeglądu organizacji bez przeróbek. To wartości startowe do dostosowania, a nie wyniki badań: wpisz własne do loops.yaml, zanim pętla wystartuje.
| Przejście | Co dodajesz do repozytorium | Idziemy dalej: dowody pętli | Stop: cofnij o jeden szczebel, gdy | Podpisuje |
|---|---|---|---|---|
| L1 → L2 | Wspólny plik instrukcji; reguły deny dla sekretów | Każdy inżynier w pętli używa zacommitowanego pliku; żaden sekret nie trafia do sesji agenta | Sekret lub poświadczenie produkcyjne pojawia się w sesji albo transkrypcie | Tech lead |
| L2 → L3 | Komendy kontrolne w pliku instrukcji; tryb planowania; osobny izolowany checkout na zadanie; wymagane kontrole statusu | Agent uruchamia typecheck, lint i testy, zanim otworzy PR; odsetek przebiegów CI zielonych za pierwszym podejściem na poziomie stanu wyjściowego lub wyżej przez 30 dni | Mediana czasu w review albo rozmiar PR rośnie przez cztery tygodnie; odsetek awarii (change_fail_rate) powyżej stanu wyjściowego | Tech lead (właściciel pętli) |
| L3 → L4 | Wykonywalne kryteria akceptacji; chronione testy; pakiet dowodów i jego kontrola w CI; review agentowe PR; przećwiczony rollback | Pakiet dowodów w każdym PR przez 30 dni; 20 losowych review ludzkich nie znalazło defektu, którego dowody nie wykazały | Defekt, który uciekł na produkcję i pochodzi z tej pętli; edycja chronionych testów przez agenta; zmergowany PR bez pakietu | Właściciel usługi oraz CTO lub osoba przez niego wskazana |
| L4 → L5 | Auto-merge według reguły dla klasy niskiej; progressive delivery z automatycznym rollbackiem; sygnały z produkcji zapisujące kolejną intencję | Klasa ryzyka niska; wyrocznią zarządza ktoś inny niż operator agenta; pełny kwartał na L4 z odsetkiem awarii na poziomie stanu wyjściowego lub niższym | Jakikolwiek incydent wysokiej wagi wywołany zmianą, której nikt nie przeczytał | CTO, z akceptacją zespołu bezpieczeństwa |
Przejście L1 → L2 nie ma tu osobnej sekcji: to jeden zacommitowany plik instrukcji z regułami deny dla sekretów, a opisują go wspólne reguły agentów.
Pętla, która zostaje na L3 albo L4, bo jej klasa ryzyka lub wyrocznia nie pozwala na więcej, to poprawny wynik, a nie porażka mapy adopcji.
Przesuń pętlę z L2 na L3: agent pracuje bez nadzoru, ty czytasz każdy diff
Dział zatytułowany „Przesuń pętlę z L2 na L3: agent pracuje bez nadzoru, ty czytasz każdy diff”Na L3 pracę agenta widzisz po raz pierwszy jako gotowy diff. Repozytorium musi sprawić, że ten diff przychodzi mały, odizolowany i już sprawdzony.
-
Wpisz komendy kontrolne do pliku instrukcji. Dodaj dokładne komendy typecheck, lint, test i build do
CLAUDE.mddla Claude Code,AGENTS.mddla Codeksa albo do reguły projektu w Cursorze, razem z poleceniem, żeby agent uruchomił je przed zgłoszeniem, że skończył. Wspólne reguły agentów pokazują, jak utrzymać jeden rdzeń dla wszystkich trzech narzędzi. -
Planuj przed edycją. Przy każdym zadaniu większym niż poprawka w jednym pliku agent szkicuje plan w trybie planowania, tylko do odczytu, a człowiek go akceptuje. Jeśli zadanie ma
spec.mdiplan.md, trzymaj je w gałęzi; przekazania opisuje łańcuch artefaktów. -
Daj każdemu zadaniu osobny checkout. Jeden worktree na zadanie sprawia, że dwóch agentów nie wchodzi sobie w drogę na plikach, portach ani w stanie lokalnym. Każdemu przebiegowi daj tylko poświadczenia potrzebne do zadania, nigdy produkcyjne. Limit kolejki opisuje równoległość w zespole.
-
Niech sędzią będzie CI. Oznacz typecheck, lint i testy jako wymagane kontrole statusu na gałęzi domyślnej, żeby czerwony przebieg blokował merge, a nie kończył się ostrzeżeniem.
-
Ogranicz rozmiar. Ustal maksymalny rozmiar pull requestu dla pętli, na przykład 400 zmienionych linii, i dziel wszystko, co większe. DORA wymienia pracę w małych porcjach wśród swoich zdolności AI, bo AI łatwo generuje ogromne bloki kodu, które trudno przejrzeć i przetestować (Nathen Harvey i Allison Park, Google Cloud, 10 grudnia 2025).
Przebieg bez nadzoru różni się między narzędziami; bramka pozostaje ta sama.
Uruchom zadanie w nowym worktree, headless, tylko z narzędziami, których potrzebuje. claude -p startuje w trybie Manual, a dontAsk odrzuca wszystko, czego nie ma na liście dozwolonych (sprawdzone na Claude Code v2.1.283, 2026-09-26):
claude -w orders-142 -p "$(cat .github/prompts/l3-task.md)" \ --permission-mode dontAsk \ --allowedTools "Read" "Edit" "Bash(npm run typecheck)" "Bash(npm run lint)" "Bash(npm test)" \ --max-budget-usd 5 \ > run-orders-142.mdW trybie dontAsk lista dozwolonych narzędzi dopasowuje te komendy dokładnie: wariant z potokiem albo z dodatkowymi argumentami, na przykład npm test | tail -20 lub npm test -- orders.test.ts, zostaje odrzucony. Dlatego prompt poniżej każe agentowi uruchamiać każdą kontrolę bez potoków i dodatkowych argumentów.
Końcowy raport trafia do run-orders-142.md, pod tę samą nazwę, którą zapisuje przebieg Codeksa. Przekierowanie powłoki zapisuje go w checkoucie, z którego uruchomiono komendę, a diff leży w worktree .claude/worktrees/orders-142/, na nowej gałęzi worktree-orders-142. Ten plik, z kodami wyjścia wklejonymi przez agenta, to dowód, który czyta recenzent, obok niezacommitowanego diffu w worktree. Ani przebieg Claude Code, ani przebieg Codeksa nie robi commita, więc oba narzędzia dają recenzentowi te same dwa artefakty.
Przy pracy interaktywnej zacznij od claude -w orders-142 i przełącz się w tryb planowania poleceniem /plan, zanim agent cokolwiek zmieni.
Uruchom zadanie w nowym zarządzanym worktree z profilem uprawnień workspace i zapisz końcowy raport do pliku (sprawdzone na Codex CLI 0.157.1, 2026-09-26; w tej wersji profile uprawnień są w fazie beta):
codex exec --worktree -c default_permissions=":workspace" \ -o run-orders-142.md "$(cat .github/prompts/l3-task.md)"Ścieżkę zarządzanego worktree wybiera sam Codex; checkout z diffem znajdziesz poleceniem git worktree list.
Przy pracy interaktywnej zacznij od codex --worktree i użyj /plan przed implementacją.
Zaplanuj zadanie w Plan Mode, a potem uruchom je w Worktree („izolowane checkouty Git”) albo jako Cloud Agent, który działa w izolowanej maszynie wirtualnej w chmurze. Nazwy funkcjonalności Cursora (Plan Mode, Worktrees, Cloud Agents) sprawdzone w jego dokumentacji 2026-08-28. Komendy kontrolne umieść w regule projektu, żeby widział je każdy agent; wspólne reguły agentów pokazują plik reguły Cursora obok CLAUDE.md i AGENTS.md. Bramka jest taka sama jak w dwóch pozostałych narzędziach: te same wymagane kontrole statusu i ten sam raport z kodami wyjścia obok diffu.
Zapisz ten prompt jako .github/prompts/l3-task.md, żeby powyższe komendy mogły go odczytać.
Przesuń pętlę z L3 na L4: czytasz specyfikację i dowody, nie diff
Dział zatytułowany „Przesuń pętlę z L3 na L4: czytasz specyfikację i dowody, nie diff”L4 zmienia to, co czyta recenzent. Ten krok jest bezpieczny tylko wtedy, gdy kontrole rozstrzygające o „gotowe” leżą poza zasięgiem agenta, więc na to przejście zaplanuj najwięcej czasu.
-
Napisz kryteria akceptacji, które maszyna potrafi uruchomić. Każde zadanie w pętli zaczyna się od kryteriów, które stają się testami przed implementacją. Zobacz kryteria akceptacji.
-
Chroń wyrocznię. Daj testom, plikom CI i plikowi
loops.yaml, w którym zapisana jest bramka pętli, właściciela, który nie jest operatorem agenta, i włącz „Require review from Code Owners” dla gałęzi domyślnej:# .github/CODEOWNERS/tests/contract/ @anna-kowalska/.github/ @anna-kowalska/loops.yaml @anna-kowalskaOchrona wyroczni dodaje reguły deny sesji i profile sandboxa dla każdego narzędzia, a siła wyroczni mierzy, czy testy w ogóle złapałyby błędną zmianę.
-
Wymagaj pakietu dowodów. Dodaj szablon pull requestu i kontrolę w CI opisane w pakiecie dowodów, żeby pull request bez zmiany specyfikacji, wyników akceptacji i wyjścia kontroli nie mógł zostać zmergowany.
-
Dodaj review agentowe. Uruchamiaj review PR przez agenta dla każdego pull requestu w pętli, jako drugi sygnał obok dowodów.
-
Przenoś zaufanie etapami. Najpierw dalej czytaj każdy diff, a dowody powstają równolegle (review w cieniu), potem czytaj losową próbkę, a na końcu tylko dowody. Protokół i workflow losowania próbki opisuje transfer zaufania.
-
Przećwicz rollback. Zrób revert jednej zmergowanej zmiany z pętli na stagingu i zmierz czas, zanim podpiszesz bramkę.
Przesuń pętlę z L4 na L5: nikt nie czyta kodu
Dział zatytułowany „Przesuń pętlę z L4 na L5: nikt nie czyta kodu”L5 jest rzadkie i dotyczy wyłącznie pętli o niskim ryzyku. Repozytorium dodaje trzy rzeczy. Po pierwsze, regułę auto-merge dla klasy niskiej, która zadziała tylko wtedy, gdy przechodzi kontrola pakietu dowodów i każda wymagana kontrola. Po drugie, progressive delivery z automatycznym rollbackiem po naruszeniu poziomu usług. Po trzecie, zamkniętą pętlę z dawnej fali 5: sygnał z produkcji otwiera zgłoszenie do triażu i kolejny intent.md, a poprawka nadal przechodzi zwykłe bramki merge’a i wydania, jak opisuje od intencji do produkcji. Sprawdź tę ścieżkę ćwiczeniem: syntetyczne naruszenie musi trafić do triażu z dołączonymi dowodami i bez żadnej bezpośredniej zmiany na produkcji.
Skąd wiesz, że przejście się udało?
Dział zatytułowany „Skąd wiesz, że przejście się udało?”Przejście się udało, gdy pętla przyspiesza, a jej jakość się utrzymuje, i mierzysz to w repozytorium, a nie na wyczucie. Raport DORA z 2025 roku pokazał obie strony tego bilansu: „w przeciwieństwie do zeszłego roku obserwujemy dodatni związek między adopcją AI a przepustowością dostarczania oprogramowania i wynikami produktu” oraz „adopcja AI nadal ma jednak ujemny związek ze stabilnością dostarczania oprogramowania” (Nathen Harvey i Derek DeBellis, Google Cloud, 23 września 2025; w oryginale: „Unlike last year, we observe a positive relationship between AI adoption on both software delivery throughput and product performance” oraz „However, AI adoption does continue to have a negative relationship with software delivery stability”). Przy każdym awansie sprawdzaj jedno i drugie:
- Rozkład. Raportuj udział zmergowanych zmian wytworzonych na każdym szczeblu w oknie 30 dni, tak jak definiuje to jedna mapa. Nigdy nie uśredniaj go do jednej liczby.
- Sparowana miara stabilności. Odsetek awarii albo revertów per pętla, w porównaniu ze stanem wyjściowym. Jeśli czas realizacji się skraca, a ten wskaźnik się pogarsza, przejście się nie udało.
- Audyt. Wylosuj 10 zmergowanych pull requestów z pętli i sprawdź, czy mają dowody wymagane dla deklarowanego szczebla. Nieudany audyt degraduje pętlę.
- Podpis. Tech lead podpisuje L1 → L2 i L2 → L3; właściciel usługi oraz CTO lub osoba wskazana podpisują L3 → L4; CTO i zespół bezpieczeństwa podpisują L4 → L5. Data i próbka trafiają do
loops.yaml.
Żadna z tych kontroli nie wymaga, żeby ktoś czytał każdą linię napisaną przez agenta. Czytają dowody, ochronę testów i liczby z produkcji.
Co się psuje, gdy repozytorium wspina się po drabinie?
Dział zatytułowany „Co się psuje, gdy repozytorium wspina się po drabinie?”Pętla pilotażowa jest trywialna. Poprawki literówek przechodzą każdą bramkę i niczego nie dowodzą. Jak z tego wyjść: wybierz pętlę istotną dla produkcji, z prawdziwymi testami i prawdziwym recenzentem, nawet jeśli będzie się przesuwać wolniej.
Całe repozytorium awansuje naraz. Ktoś pisze „jesteśmy już na L4” po tym, jak jedna pętla przeszła bramkę. Jak z tego wyjść: awans zawsze dotyczy jednej nazwanej pętli; rozkład pokazuje, gdzie są pozostałe.
Agent edytuje własną wyrocznię. „Poprawka” testu sprawia, że CI w pętli na L4 przechodzi na zielono. Jak z tego wyjść: cofnij pętlę na L3, dodaj ścieżki do CODEOWNERS i do reguł deny narzędzia, a okno 30 dni zacznij liczyć od zera.
Review staje się kolejką. Po wejściu na L3 pull requesty rosną i dłużej czekają. Jak z tego wyjść: egzekwuj limit rozmiaru, przestań dokładać równoległe zadania i zastosuj praktyki z kolejki code review, zanim przesuniesz jakąkolwiek pętlę dalej.
Artefakty stają się papierologią. plan.md i pakiet dowodów są wypełnione, ale nikt ich nie czyta. Jak z tego wyjść: usuń każde pole, którego nie używa żaden recenzent ani żadna kontrola, i niech kontrola w CI odrzuca puste sekcje.
Narzędzie staje się procesem. Bramki działają tylko w interfejsie jednego narzędzia. Jak z tego wyjść: trzymaj instrukcje, loops.yaml, pakiet dowodów i CODEOWNERS w repozytorium, żeby zespół mógł używać Claude Code, Codeksa albo Cursora pod tymi samymi bramkami.