# Jak przygotować repozytorium do pracy agentów

URL: https://developertoolkit.ai/pl/workflows/harness/agent-ready-codebase/
Description: Sześć cech repozytorium, dzięki którym kontrole zastępują czytanie diffów agenta: ocena 0–3 dla każdej, prompt audytowy i kolejność napraw.

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](/pl/workflows/harness/), a nie w nich. Harness ogranicza, co agent może zrobić; repozytorium decyduje, czy cokolwiek potrafi sprawdzić, co zrobił. Zamienianie każdego powtarzającego się błędu agenta w stałą kontrolę, w harnessie albo w repozytorium, to [inżynieria harnessu](/pl/glossary/harness-engineering/).

## 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](/pl/workflows/test/oracle-strength/). 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](/pl/developer-scorecard-guide/claude-md-context/).

## 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](/pl/teams/agent-ready-backlog/), oraz z trybem uruchomienia ze strony o [uprawnieniach, sandboksach i trybach zatwierdzania](/pl/workflows/harness/permissions-and-sandboxing/).

## 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.

1. **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.

2. **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.

3. **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.

4. **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.

5. **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.

6. **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.

**Gotowy prompt: audyt gotowości repozytorium**

```text
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.
```

**Claude Code**

    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 (od v2.1.285 w trybie auto u zewnętrznych dostawców lub z wyłączoną telemetrią, gdzie decyduje klasyfikator), więc dodaj `--permission-mode dontAsk`, żeby wszystko, co wymagałoby pytania, zostało odrzucone, a nie zapytane, u każdego dostawcy; odczyty w katalogach roboczych i polecenia tylko do odczytu nadal działają (2.1.283; zmiana z v2.1.285: changelog Claude Code, sprawdzone 2026-10-12):

    ```bash
    # terminal, katalog główny repozytorium; readiness-audit.txt zawiera prompt powyżej
    claude -p "$(cat readiness-audit.txt)" \
      --permission-mode dontAsk \
      --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.

**Codex**

    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ą:

    ```bash
    # 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.

**Cursor**

    Zanim wkleisz prompt, ustaw Cursora tak, żeby pytał przed komendami terminala; opcje opisuje strona Run modes w dokumentacji Cursora (Agent security): Auto-review, Allowlist i Run Everything (sprawdzone 2026-10-12); pusta allowlista pyta przed każdą komendą. 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 poleceniem `agent` i trybem print (`-p, --print`) do pracy bez interfejsu (dokumentacja Cursora, sprawdzone 2026-10-12).

## 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:

```json
{
  "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:

```md
## 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.
```

**Gotowy prompt: zbuduj jedną komendę sprawdzającą**

```text
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ć.

**Claude Code**

    Hook `Stop` (model zdarzeń opisuje strona o [hookach jako deterministycznych zabezpieczeniach](/pl/developer-scorecard-guide/agent-hooks/)) 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:

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

    ```bash
    #!/usr/bin/env bash
    # .claude/hooks/require-check.sh
    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`](/pl/workflows/automate/goal-command/).

**Codex**

    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`](/pl/workflows/automate/goal-command/) 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.

**Cursor**

    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ść.

**Gotowy prompt: znajdź i napraw niestabilne testy**

```text
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](/pl/workflows/test/unit-testing/) i o [zarządzaniu danymi testowymi](/pl/workflows/test/test-data-management/).

## 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ę.

**Gotowy prompt: egzekwuj architekturę, którą już masz**

```text
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](/pl/workflows/build/large-codebases/).

## 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](/pl/workflows/test/oracle-strength/).

**Gotowy prompt: defekty kanarkowe**

```text
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](/pl/ladder/evidence-not-diffs/).

## 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](/pl/workflows/test/protect-the-oracle/).

**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](/pl/developer-scorecard-guide/git-worktrees/) i o [środowiskach efemerycznych](/pl/workflows/harness/ephemeral-environments/).

## Dokąd dalej po audycie gotowości

Audyt mówi, gdzie stoi repozytorium. Wymaganiem wstępnym jest [przegląd harnessu](/pl/workflows/harness/); tech leadzi przechodzą dalej do [wspólnych reguł agentów](/pl/cto-scorecard-guide/shared-agent-rules/), programiści do [funkcji dopasowania](/pl/workflows/test/fitness-functions/).

- [Jak przygotować backlog dla agentów](/pl/teams/agent-ready-backlog/) — Jakie tickety przyjmie gotowe repozytorium: test kwalifikacji, cięcie zadań i ścieżki uruchomień.
- [Ochrona wyroczni](/pl/workflows/test/protect-the-oracle/) — Jak nie pozwolić agentowi zazielenić kontroli przez edycję samej kontroli.
- [Środowiska efemeryczne](/pl/workflows/harness/ephemeral-environments/) — Izolowany stos z danymi dla każdego zadania agenta, czyli wersja cechy 6 na ocenę 3.
- [Uprawnienia, sandboksy i tryby zatwierdzania](/pl/workflows/harness/permissions-and-sandboxing/) — Tryb uruchomienia dopasowany do każdego profilu gotowości.
