Jak przygotować repozytorium do pracy agentów

Repozytorium gotowe dla agentów to takie, w którym o poprawności zmiany agenta decydują automatyczne kontrole, a nie człowiek czytający diff. Umożliwia to sześć cech: jedna komenda uruchamiająca wszystkie bramki, szybka informacja zwrotna, deterministyczne testy, ścisłe typy i lint, egzekwowane granice modułów oraz powtarzalne dane testowe. Każdą cechę ocenia się w skali 0–3 promptem audytowym.

Ta strona jest dla programistów, którzy chcą przestać czytać każdą linię napisaną przez agenta, i dla tech leadów decydujących, które repozytoria nadają się do uruchomień w tle. Dałeś agentowi dobrze opisany ticket. Zgłosił „wszystkie testy przechodzą”, a ty i tak spędziłeś 40 minut nad diffem, bo komenda, którą uruchomił, pomijała testy integracyjne, dwa testy i tak padają co piąte uruchomienie, a nic nie powstrzymałoby go przed zaimportowaniem modułu rozliczeń z warstwy UI. Ticket był w porządku; to repozytorium niczego nie potrafiło udowodnić.

Co daje audyt gotowości repozytorium

Skalę ocen 0–3 dla sześciu cech, z dowodami, które uzasadniają każdą ocenę.
Gotowy prompt audytowy, który zmusza agenta do pomiaru zamiast zgadywania.
Kolejność napraw i trzy prompty, które je wykonują: jedna komenda sprawdzająca, niestabilne testy i egzekwowane granice.
Test kanarkowy, który dowodzi, że kontrole łapią defekty, zanim dopuścisz uruchomienia bez nadzoru.
Typowe awarie, przede wszystkim agenta, który doprowadza kontrolę do zielonego wyniku, osłabiając ją.

Dlaczego to repozytorium decyduje, czy możesz przestać czytać diffy?

Deklaracja agenta, że praca jest skończona, jest warta dokładnie tyle, ile kontrola, która za nią stoi. Jeśli jedynym sposobem na stwierdzenie poprawności zmiany jest jej przeczytanie, to ją czytasz, niezależnie od jakości modelu. Każda cecha z tej strony zamienia jeden rodzaj czytania w kontrolę, która działa bez ciebie.

Najmocniejszy zewnętrzny dowód pochodzi od DORA. Raport DORA 2025 (blog Google Cloud, Nathen Harvey i Derek DeBellis, 2025-09-23) wykazał pozytywny związek między adopcją AI a przepustowością dostarczania i negatywny ze stabilnością dostarczania. Jego wyjaśnienie: „Without robust control systems, like strong automated testing, mature version control practices, and fast feedback loops, an increase in change volume leads to instability. Teams working in loosely coupled architectures with fast feedback loops see gains, while those constrained by tightly coupled systems and slow processes see little or no benefit.” Podsumowanie tego samego raportu mówi, że AI „amplifies what’s already there”, czyli wzmacnia to, co już jest.

Stripe pokazuje drugi koniec skali: jego Minions scalają ponad 1300 pull requestów tygodniowo bez kodu napisanego przez człowieka (dane wewnętrzne firmy, Alistair Gray, stripe.dev, 2026-02-19), a ich pętla kończy się po „at most two rounds of CI” (Minions, część 1, stripe.dev, 2026-02-09) i działa na „over three million” testów.

W kategoriach harnessu repozytorium leży obok siedmiu warstw harnessu, a nie w nich. Harness ogranicza, co agent może zrobić; repozytorium decyduje, czy cokolwiek potrafi sprawdzić, co zrobił.

Jakie sześć cech sprawia, że repozytorium jest gotowe dla agentów?

#	Cecha	Co robi agent bez niej	Jaką kontrolę umożliwia
1	Jedna komenda sprawdzająca	Zgaduje komendę testów, uruchamia tylko testy jednostkowe i melduje „testy przechodzą”	„Gotowe” znaczy, że jedna nazwana komenda zwróciła 0, a CI uruchamia tę samą komendę
2	Szybka informacja zwrotna	Pomija wolne testy albo robi 30 edycji przed pierwszym uruchomieniem, więc błędy przychodzą późno i splątane	Agent uruchamia kontrolę po każdej istotnej edycji i naprawia błąd, gdy przyczyna jest jeszcze lokalna
3	Deterministyczne testy	Uczy się, że czerwony wynik bywa szumem, powtarza do skutku albo „naprawia” niestabilny test, edytując go	Czerwony wynik zawsze oznacza defekt, więc zielony coś znaczy
4	Ścisłe typy i lint jako bramki	Przepuszcza `any`, `None` albo niesprawdzony indeks i wymyśla metodę, którą kompilator by odrzucił	Całe klasy błędów (zły kształt danych, brakujące pole, wymyślone API) padają w sekundy, bez testu
5	Egzekwowane granice modułów	Importuje cokolwiek, co sprawia, że zmiana działa, więc diff jest dziś poprawny, a architektura się rozmywa	Naruszenie warstwy oblewa kontrolę, więc recenzujesz interfejs, a nie każdy import
6	Powtarzalne dane i konfiguracja	Potrzebuje wspólnej bazy, twoich poświadczeń albo ręcznego kroku, więc albo nie może zweryfikować, albo weryfikuje na złym stanie	Świeży klon dochodzi do zielonej kontroli jedną komendą startową: lokalnie, w worktree albo w środowisku chmurowym

Dwóch rzeczy celowo nie ma na liście. Nie ma pokrycia testami: wysoki procent przy słabych asercjach przepuszcza błędny kod, a o tym, jak mierzyć, co testy naprawdę łapią, mówi strona o sile wyroczni. Nie ma też pliku kontekstu (AGENTS.md, CLAUDE.md, Rules w Cursorze): nazywa on komendę, ale repozytorium bez powyższych cech nie naprawi się przez ich opisanie. Co powinno się tam znaleźć, opisuje strona o zwięzłych plikach AGENTS.md i CLAUDE.md.

Jak ocenić każdą cechę w skali od 0 do 3?

Oceniaj każdą cechę na podstawie dowodu, który da się wskazać: komendy, jej wyniku, czasu działania, pliku konfiguracyjnego. Ocena bez dowodu to 0. Progi czasowe są rekomendacją tej strony dla wewnętrznej pętli agenta, a nie opublikowanym benchmarkiem; dostosuj je raz, wpisz swoją wersję do karty ocen i trzymaj je stałe, żeby wyniki były porównywalne w czasie.

Cecha	0	1	2	3
1. Jedna komenda sprawdzająca	Brak jednej komendy; bramki żyją tylko w YAML-u CI albo w głowach ludzi	Komenda istnieje, ale pomija bramkę uruchamianą przez CI albo wymaga wcześniejszej ręcznej konfiguracji	Jedna komenda uruchamia każdą bramkę CI ze świeżego klona i jest nazwana w `AGENTS.md` lub `CLAUDE.md`	Do tego wariant zawężony (zmieniony pakiet lub pliki), błędy w formie, na którą agent może zareagować, i hook albo goal, który ją uruchamia, zanim agent może skończyć
2. Szybka informacja zwrotna	Kontrola dostępna dla agenta trwa ponad 15 minut albo działa tylko w CI	5–15 minut	Kontrola zawężona poniżej 2 minut; pełna poniżej 15	Kontrola zawężona poniżej 30 sekund; pełna, zrównoleglona, poniżej 10 minut
3. Deterministyczne testy	Znane niestabilne testy, domyślnie włączone ponawianie, testy sięgające do prawdziwej sieci lub zegara	Niestabilne testy są ręcznie izolowane w kwarantannie; część testów wciąż zależy od czasu, kolejności lub sieci	Trzy kolejne uruchomienia i jedno w losowej kolejności dają identyczne wyniki; zegar, losowość i sieć są w testach kontrolowane	Do tego: niestabilne wyniki na gałęzi głównej są śledzone, testy w kwarantannie mają właściciela i datę ważności, nieoczekiwane wywołanie sieci oblewa test
4. Ścisłe typy i lint	Brak typów albo tryb ścisły wyłączony, a lint daje tylko ostrzeżenia	Typy są, ale tryb ścisły jest wyłączony albo błędy typów i lintu nie oblewają CI	Tryb ścisły włączony (`"strict": true` w `tsconfig.json`, `mypy --strict` lub odpowiednik w twoim języku), a obie bramki oblewają CI	Do tego: zero ostrzeżeń, a każde wyciszenie (`@ts-expect-error`, `# type: ignore`, wyłączenia lintu) wymaga uzasadnienia i jest liczone, z limitem, który może tylko maleć
5. Granice modułów	Brak zadeklarowanych warstw; cykliczne importy; mała zmiana dotyka wielu niezwiązanych modułów	Architektura jest opisana w dokumencie, ale nic jej nie egzekwuje	Narzędzie w komendzie sprawdzającej oblewa zakazane importy (na przykład dependency-cruiser dla JavaScriptu i TypeScriptu, import-linter dla Pythona)	Do tego: każdy moduł ma publiczny interfejs z własnymi testami działającymi w izolacji, a własność jest przypisana (`CODEOWNERS`)
6. Dane i konfiguracja	Testy lub serwer deweloperski wymagają wspólnej bazy, poświadczeń kolegi albo danych produkcyjnych	Skrypt seedujący istnieje, ale uruchamia się go ręcznie i rozjeżdża się ze schematem	Jedna komenda startowa instaluje zależności, migruje i ładuje deterministyczne fixture’y ze świeżego klona, bez sekretów produkcyjnych	Do tego: izolacja per uruchomienie (blok portów i baza per worktree lub kontener), fixture’y wersjonowane razem z migracjami, atrapy usług zewnętrznych

Co oznacza wynik łączny dla autonomii

Wynik łączny jest liczony z 18, ale minimum ma większe znaczenie niż suma, bo jedna słaba cecha podważa pozostałe. Szybki, ale niestabilny zestaw testów uczy agenta ignorować czerwony wynik. Ta strona rekomenduje trzy progi:

Profil	Co oznacza	Jakie uruchomienia wspiera
Cecha 1 lub 3 na 0	Nic nie potrafi wiarygodnie powiedzieć „nie”	Tylko praca interaktywna; czytasz diff
Każda cecha co najmniej na 1, przynajmniej jedna wciąż na 1	Kontrole łapią część defektów i wiesz, których	Uruchomienia interaktywne i nadzorowane w tle; ryzykowne obszary recenzujesz, czytając
Każda cecha co najmniej na 2 (łącznie 12 lub więcej)	O większości wyników decydują kontrole	Uruchomienia w tle i nocne na ticketach niskiego ryzyka; recenzujesz dowody, nie diffy

O autonomii decyduje się dla każdej zmiany, a nie dla całego repozytorium, więc łącz ocenę z zasięgiem skutków i odwracalnością ticketu, opisanymi na stronie o przygotowaniu backlogu dla agentów, oraz z trybem uruchomienia ze strony o uprawnieniach, sandboksach i trybach zatwierdzania.

Jak przeprowadzić audyt gotowości repozytorium

Sam audyt to wynik pracy agenta, więc agent musi pokazać dowody, a ty powtarzasz to, na co się powołuje. Uruchamiaj go w trybie tylko do odczytu.

Uruchom prompt audytowy poniżej w swoim narzędziu (zobacz zakładki dla każdego). Pozwól mu uruchamiać komendy sprawdzające, testy i kontrolę typów, bo mierzenie czasu i powtarzanie ich jest tu sednem.
Weryfikuj kartę ocen, nie prozę. Dla każdej oceny 2 lub 3 uruchom ponownie wskazaną komendę i porównaj wynik oraz czas. To łapie najczęstszy błąd audytu: ocenę przyznaną, bo istnieje skrypt o właściwej nazwie.
Dodaj kartę ocen do repozytorium jako docs/agent-readiness.md, z datą, narzędziem i modelem, które ją wygenerowały, oraz z użytymi progami. Odpowiada za nią tech lead; następny audyt porównuje się z nią diffem.
Naprawiaj w tej kolejności: jedna komenda, determinizm, szybkość, typy, granice, dane. Komenda sprawdzająca czyni każdą późniejszą poprawkę weryfikowalną; niestabilna kontrola odbiera wiarygodność każdemu innemu sygnałowi.
Przeprowadź test kanarkowy (poniżej), zanim dopuścisz repozytorium do uruchomień w tle. Ocena mówi, że bramki istnieją; test kanarkowy dowodzi, że łapią defekty.
Powtarzaj audyt po każdej zmianie narzędzi, potoku CI lub domyślnego modelu, a przynajmniej raz na kwartał. Porównuj go diffem z kartą ocen zapisaną w repozytorium.

Audit this repository for agent readiness. Do not edit any file. Measure; do not infer.

Score each of these six properties from 0 to 3 using the rubric below, and for every
score cite the evidence: the exact command you ran, its exit code, its wall-clock time,
and the file paths that support the score. A score with no evidence is 0.

1. One-command check. Find the command(s) CI runs (read .github/workflows, .gitlab-ci.yml
   or equivalent). Is there ONE local command that runs every one of those gates? Is it
   named in AGENTS.md or CLAUDE.md? Is there a scoped variant for changed files/packages?
   Run it and time it.
2. Fast feedback. Time the scoped check and the full check separately.
3. Determinism. Run the unit test suite three times in a row, then once in shuffled order
   if the runner supports it (e.g. `vitest run --sequence.shuffle`; for pytest, install
   pytest-randomly, which shuffles every run, and use `-p no:randomly` for the ordered
   runs). Report any test whose result differed. Search for
   retries enabled by default, sleeps, real network calls, Date.now()/datetime.now()
   without a fake clock, and unseeded randomness in tests.
4. Types and lint. Is strict mode on? Do type and lint errors fail CI? Count suppressions
   (@ts-expect-error, @ts-ignore, eslint-disable, # type: ignore, # noqa) and list the
   five directories with the most.
5. Module boundaries. Is there a tool in the check that fails on forbidden imports? If not,
   describe the layering the code actually follows and list up to ten imports that cross it,
   plus any circular imports you find.
6. Data and setup. From the README and scripts, what does a clean clone need to reach a
   green check? List every manual step, shared service, credential or production
   dependency. Is there a deterministic seed? Does it run against the current schema?

Rubric: 0 = absent; 1 = exists but incomplete or not enforced; 2 = complete and enforced in
CI; 3 = enforced, fast, and hard to bypass.
Time thresholds: full check under 15 min = 2, under 10 min parallelized = 3;
scoped check under 2 min = 2, under 30 s = 3.

Output a Markdown table (property, score, evidence), the total out of 18, the lowest-scoring
property, and a numbered fix list in this order: check, determinism, speed, types,
boundaries, data. For each fix give the files to change and how to verify it is done.

Interaktywnie: wklej prompt do sesji uruchomionej w trybie Manual (claude --permission-mode manual), żeby zatwierdzać każdą komendę audytu, albo do trybu planowania (/plan), jeśli chcesz tylko statycznej analizy, a czasy zmierzysz sam.

Bez interfejsu, dla skryptowego audytu, który co kwartał porównasz diffem, zatwierdź z góry tylko narzędzia do odczytu i komendy potrzebne audytowi. claude -p startuje w trybie Manual, więc wszystko, czego nie wymieniłeś, zostanie odrzucone, a nie zapytane (sprawdzone na Claude Code 2.1.283):

# terminal, katalog główny repozytorium; readiness-audit.txt zawiera prompt powyżej
claude -p "$(cat readiness-audit.txt)" \
  --allowedTools "Read,Grep,Glob,Bash(git log *),Bash(pnpm check),Bash(pnpm check:changed),Bash(pnpm lint),Bash(pnpm test),Bash(pnpm typecheck),Bash(time pnpm check),Bash(time pnpm check:changed)" \
  > docs/agent-readiness.new.md

Bash(time pnpm check) i Bash(time pnpm check:changed) pozwalają audytowi zmierzyć czas tych dwóch kontroli i niczego więcej; Bash(pnpm test) jest dokładną komendą, więc audyt nie dopisze argumentów, takich jak aktualizacja snapshotów. Ocenę cechy 2 bez pomiaru czasu odrzucasz. Zamień komendy pnpm na te z twojego repozytorium.

Interaktywnie: uruchom CLI z tym samym profilem tylko do odczytu, codex -c 'default_permissions=":read-only"', albo wybierz go przez /permissions w TUI, a potem wklej prompt. Domyślna polityka zatwierdzania on-request pyta tylko o działania wychodzące poza sandbox; z domyślnym profilem Codex może zapisywać w obszarze roboczym bez pytania.

Bez interfejsu codex exec czyta prompt ze standardowego wejścia, gdy podasz -, a końcową wiadomość zapisuje do pliku przez -o (sprawdzone na Codex CLI 0.157.1). Profil uprawnień :read-only (beta) pozwala mu uruchamiać komendy, ale nie zapisywać plików, co pasuje do audytu, który niczego nie zmienia; w codex exec nic nie jest zatwierdzane interaktywnie, więc komenda, która musi wyjść poza sandbox, po prostu zawodzi, a audyt powinien zgłosić ją jako niezmierzoną:

# terminal, katalog główny repozytorium
codex exec -c 'default_permissions=":read-only"' \
  -o docs/agent-readiness.new.md - < readiness-audit.txt

Narzędzia uruchamiające testy, które zapisują pamięć podręczną lub pliki pokrycia, mogą zawieść pod :read-only. Jeśli tak jest u ciebie, przełącz na :workspace, który pozwala na zapis w obszarze roboczym; przed edycjami chroni wtedy tylko polecenie „Do not edit any file” w prompcie, więc po audycie sprawdź diff drzewa.

Zanim wkleisz prompt, ustaw Cursora tak, żeby pytał przed komendami terminala; opcje opisuje strona Run modes w dokumentacji Cursora (Agent security), a nazw trybów nie zweryfikowano tu ponownie. Potem wklej prompt do Agenta i zatwierdzaj każdą komendę, gdy się pojawi. Wynikową tabelę zapisz sam jako docs/agent-readiness.md.

Cursor ma też CLI z trybem print (-p, --print) do pracy bez interfejsu (według cursor.com, sprawdzone 2026-08-28). Nazwy pliku wykonywalnego nie zweryfikowano ponownie 2026-09-26, więc przed napisaniem skryptu sprawdź dokumentację CLI Cursora.

Zacznij od jednej komendy sprawdzającej

Pierwsza poprawka to prawie zawsze jeden punkt wejścia, który uruchamia dokładnie to, co CI, plus zawężony wariant dla wewnętrznej pętli agenta. W monorepo TypeScriptu z pnpm i Vitestem:

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "lint": "eslint . --max-warnings 0",
    "boundaries": "depcruise src --ignore-known",
    "test": "vitest run",
    "check": "pnpm typecheck && pnpm lint && pnpm boundaries && pnpm test",
    "check:changed": "pnpm typecheck && vitest run --changed origin/main"
  }
}

Potem niech CI wywołuje pnpm check i nic więcej, żeby komenda lokalna i bramka nie mogły się rozjechać. (W Pythonie: cel w Makefile uruchamiający ruff check, mypy --strict, lint-imports i pytest.)

Na koniec nazwij komendę w pliku kontekstu:

## Checks
Run `pnpm check:changed` after each change and `pnpm check` before you say you are done.
Both must exit 0. Do not edit test files, tsconfig.json or .dependency-cruiser.js to make them pass.

Read every CI workflow in this repository and list each gate it runs (install, build,
type check, lint, tests, boundary checks, anything else), with the exact command.

Then add two scripts:
- `check`: runs every one of those gates locally, in the same order as CI, and fails on the
  first failure.
- `check:changed`: the fastest meaningful subset for files changed since origin/main,
  committed or not (type check plus `vitest run --changed origin/main` or your runner's
  equivalent).

Change the CI workflow to call `check` instead of the individual commands, so the two
cannot drift. Add a "Checks" section to AGENTS.md (or CLAUDE.md if that is the only
context file) naming both commands in two lines.

Verify: run `check` and `check:changed` from a clean state and report the exit codes and
timings. Then introduce a deliberate type error in one file, confirm `check:changed` fails,
revert it, and confirm it passes. Show me the output of each run.

Niech „gotowe” znaczy, że kontrola przeszła

Linia w pliku kontekstu to rada. Żeby kontrola była nie do obejścia, uruchamiaj ją w momencie, gdy agent próbuje skończyć.

Hook Stop (model zdarzeń opisuje strona o hookach jako deterministycznych zabezpieczeniach) uruchamia się za każdym razem, gdy Claude próbuje zakończyć turę; Stop nie przyjmuje matchera. Kod wyjścia 2 blokuje zakończenie tury: Claude pracuje dalej, więc wypisz wynik nieudanej kontroli na stderr, żeby mógł na niego zareagować (według dokumentacji hooków Claude Code, sprawdzone 2026-09-26). Zapisz go w .claude/settings.json i zacommituj:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/require-check.sh" }]
      }
    ]
  }
}

#!/usr/bin/env bash
input=$(cat)
# Avoid an endless loop: if a Stop hook already kept Claude going, let it stop.
if echo "$input" | grep -q '"stop_hook_active": *true'; then exit 0; fi
if ! out=$(pnpm check:changed 2>&1); then
  echo "pnpm check:changed failed. Fix the cause, not the test:" >&2
  echo "$out" | tail -n 60 >&2
  exit 2
fi

Nadaj mu prawo wykonywania: chmod +x .claude/hooks/require-check.sh.

Zabezpieczenie przed pętlą jest ważne: bez niego kontrola, której agent nie potrafi naprawić, blokuje zakończenie tury, dopóki Claude Code nie zignoruje hooka po więcej niż ośmiu kolejnych blokadach (domyślny limit, CLAUDE_CODE_STOP_HOOK_BLOCK_CAP) i nie zakończy tury. Z nim Claude dostaje jedną ponowną próbę; jeśli kontrola wciąż jest czerwona, tura się kończy, a zabezpieczeniem pozostaje CI. Przy długich uruchomieniach tę samą rolę pełni warunek /goal.

Codex ma zdarzenie Stop wśród swoich 12 zdarzeń hooków, a hooki wymagają utrwalonego zaufania, zanim się uruchomią; przejrzysz je przez /hooks (Codex CLI 0.157.1). Skieruj hook na tę samą komendę check:changed. Przy uruchomieniach bez nadzoru /goal z warunkiem zatrzymania „pnpm check kończy się kodem 0” utrzymuje Codex w pętli, dopóki jego ewaluator nie uzna warunku za spełniony; ocenia to model, więc CI i tak uruchamia komendę. Zanim użyjesz skryptu z zakładki Claude Code, sprawdź pola wejściowe w dokumentacji hooków Codex; nie zakładaj, że oba formaty danych są takie same.

Umieść obie komendy sprawdzające w regule projektu (Rules), żeby Agent ładował je w każdej sesji. Hooks w Cursorze to „spawned processes that communicate over stdio using JSON in both directions”, które „can observe, block, or modify behavior” (cursor.com, sprawdzone 2026-08-28). Nazw zdarzeń nie zweryfikowano ponownie 2026-09-26, więc zdarzenie wywoływane po zakończeniu pracy agenta wybierz z dokumentacji hooków Cursora i uruchamiaj w nim check:changed.

Najpierw determinizm, potem szybkość

Niestabilny test szkodzi agentowi bardziej niż człowiekowi. Ty pamiętasz, że checkout.spec.ts bywa kapryśny; agent widzi czerwony wynik i przepisuje działający kod albo edytuje test, aż przejdzie. Dlatego izoluj niestabilne testy, zanim zaczniesz stroić szybkość.

Find the non-deterministic tests in this repository. Do not change application code yet.

1. Run the full unit suite five times, then twice in shuffled order
   (e.g. `vitest run --sequence.shuffle`; for pytest, install pytest-randomly, which
   shuffles every run, and use `-p no:randomly` for the ordered runs). Record every test
   whose result differed across runs.
2. For each flaky test, find the cause and classify it: wall-clock time, unseeded
   randomness, test-order dependency (shared state), real network, real filesystem or
   database state left by another test, timing/sleep, concurrency.
3. Propose the smallest fix per test: a fake clock, a fixed seed, per-test setup and
   teardown, a stubbed network call, an isolated temp directory. Do not add retries and
   do not delete or weaken assertions.
4. Apply the fixes one test at a time. After each, run that test file 20 times and show
   that every run passes.
5. If a test cannot be fixed now, mark it skipped with a comment naming the cause, an
   owner placeholder and an expiry date, and list it in docs/agent-readiness.md.

Report: a table of test, cause, fix, and runs passed out of 20.

Gdy zestaw testów jest już deterministyczny, szybkość to zwykle kwestia zakresu: uruchamiaj tylko to, na co zmiana może wpłynąć (vitest run --changed origin/main, które obejmuje zmiany zatwierdzone, dodane do indeksu i niedodane na gałęzi, a także nowe pliki, których Git nie ignoruje, albo cele testowe per pakiet w monorepo), wolne testy end-to-end trzymaj w pełnej kontroli i w CI, a pełną kontrolę zrównoleglij. Wzorce po stronie testów szczegółowo opisują strony o testach jednostkowych z agentami i o zarządzaniu danymi testowymi.

Zamień architekturę w egzekwowane granice

Agenci idą przez twoje importy drogą najmniejszego oporu: jeśli warstwa UI może zaimportować klienta bazy danych, prędzej czy później któraś zmiana to zrobi. Reguła granic zamienia komentarz w recenzji w oblaną kontrolę.

Describe the layering this codebase actually follows, from the directory structure and
the import graph, not from any README. Name each layer and which layers it may import.

Then encode it as boundary rules:
- TypeScript/JavaScript: install dependency-cruiser as a dev dependency, run
  `npx dependency-cruiser --init`, and add forbidden rules for each disallowed direction
  plus no circular dependencies.
- Python: install import-linter and add a layers contract in pyproject.toml, run with
  `lint-imports`.

Run the tool. Existing violations must not block the first commit: record them as a
known-violations baseline (dependency-cruiser ships `depcruise-baseline` for this) and run depcruise with
--ignore-known so only NEW violations fail. Add the boundary check to the `check` script.

Verify: add a deliberate forbidden import in a scratch file, show the check fails with a
readable message, remove it, show the check passes. List the baseline violations grouped
by module so we can schedule them.

Komendy instalacji, których oczekuje prompt, to pnpm add -D dependency-cruiser (z npm: npm i -D dependency-cruiser; wersja 18.4.0 w npm, sprawdzone 2026-09-26) oraz pip install import-linter albo uv add --dev import-linter (wersja 2.15 w PyPI, sprawdzone 2026-09-26).

Ścisłe typy działają według tej samej logiki zapadki. Włączenie "strict": true w dużym kodzie TypeScriptu potrafi naraz wygenerować tysiące błędów, więc włączaj je katalog po katalogu (ostrzejszy tsconfig.json dla nowych lub zmigrowanych pakietów) i licz wyciszenia w kontroli, żeby ich liczba mogła tylko maleć. Podział tej pracy na sesje agenta opisuje strona o dużych bazach kodu.

Udowodnij testem kanarkowym, że kontrole łapią defekty

Wysoka ocena mówi, że bramki istnieją i działają. Nie mówi, że cokolwiek łapią. Zanim dopuścisz repozytorium do uruchomień w tle, podłóż znane defekty i sprawdź, że kontrola zmienia się na czerwono przy każdym z nich. To mała, ręczna forma testowania mutacyjnego; wersję automatyczną opisuje strona o sile wyroczni.

On a new branch named readiness-canary, plant five independent defects, one commit each,
and do not tell me which is which until the end:
1. a type error in a function that is called from at least two modules;
2. a forbidden import across a layer boundary;
3. an off-by-one error in business logic that has unit tests;
4. a removed null/None check on a path that has tests;
5. a change to a seed fixture that breaks an assumption a test relies on.

After each commit, run `check` and record whether it failed and which gate caught it.
Report a table: defect, caught (yes/no), gate that caught it, time to fail.
Then delete the branch. Do not modify any test, config or check script.

Każdy defekt, który przetrwał, wskazuje zawyżoną ocenę: obniż ją i zamknij lukę, zanim zwiększysz autonomię. Powtarzaj test kanarkowy co kwartał; kontrola, która w marcu złapała pięć defektów, może przestać łapać jeden, gdy ktoś w czerwcu doda --passWithNoTests.

Kto zatwierdza. Za kartę ocen i wynik testu kanarkowego odpowiada tech lead. Repozytorium przechodzi do wyższego profilu autonomii dopiero wtedy, gdy karta spełnia próg z tabeli powyżej, a ostatni test kanarkowy złapał każdy podłożony defekt. Od tego momentu zmiany przyjmuje się na podstawie dowodów, jak opisuje strona dowody zamiast diffów.

Co się psuje, gdy przygotowujesz repozytorium dla agentów?

Agent doprowadza kontrolę do zielonego wyniku, osłabiając ją. Dodaje @ts-expect-error, oznacza test jako .skip albo edytuje konfigurację lintu lub granic; egzekwowana kontrola staje się celem. Jak naprawić: zablokuj agentowi zapis do konfiguracji testów, lintu, granic i CI; licz wyciszenia; kieruj te pliki do recenzji człowieka przez CODEOWNERS. Pełny wzorzec opisuje strona o ochronie wyroczni.

Audyt podaje oceny, których nie zmierzył. Skrypt test:e2e, który od miesięcy nie przeszedł, dostaje 2. Jak naprawić: odrzucaj każdy wiersz bez kodu wyjścia i czasu, a wskazane komendy uruchamiaj sam (krok 2 audytu).

Tryb ścisły daje tysiące błędów i praca staje. Jak naprawić: włączaj ścisłość po jednym pakiecie, zapisz istniejące naruszenia granic jako bazę odniesienia i niech agent porządkuje jeden moduł na sesję.

Kontrola zawężona przechodzi, a CI pada. check:changed pominął konsumenta w innym pakiecie. Jak naprawić: przy zmianach we wspólnych pakietach trzymaj pełne check w hooku Stop lub w celu i dodaj pominiętą ścieżkę zależności do zawężonego wyboru.

Kwarantanna testów zamienia się w cmentarz. Dwadzieścia pominiętych testów bez właściciela, a agent dodaje dwudziesty pierwszy. Jak naprawić: każde pominięcie ma właściciela i datę ważności; przeterminowane ograniczają determinizm do 1.

Dane seedujące rozjeżdżają się ze schematem. Jak naprawić: komenda startowa migruje świeżą bazę przed seedowaniem, w ramach pełnej kontroli, więc rozjazd oblewa kontrolę, zamiast się ukrywać.

Dwóch agentów dzieli jedną bazę albo jeden port. Jak naprawić: jeden worktree i jeden blok portów na agenta; zobacz strony o równoległych agentach w worktree i o środowiskach efemerycznych.

Dokąd dalej po audycie gotowości

Audyt mówi, gdzie stoi repozytorium. Wymaganiem wstępnym jest przegląd harnessu; tech leadzi przechodzą dalej do wspólnych reguł agentów, programiści do funkcji dopasowania.

Jak przygotować backlog dla agentów Jakie tickety przyjmie gotowe repozytorium: test kwalifikacji, cięcie zadań i ścieżki uruchomień.

Ochrona wyroczni Jak nie pozwolić agentowi zazielenić kontroli przez edycję samej kontroli.

Środowiska efemeryczne Izolowany stos z danymi dla każdego zadania agenta, czyli wersja cechy 6 na ocenę 3.

Uprawnienia, sandboksy i tryby zatwierdzania Tryb uruchomienia dopasowany do każdego profilu gotowości.