Wykonywalne kryteria akceptacji: od historyjki do czerwonego testu

Wykonywalne kryteria akceptacji zamieniają każdą linię historyjki użytkownika w scenariusz Given/When/Then z konkretnymi wartościami i automatyczny test, który pada, zanim powstanie jakakolwiek implementacja. Testy zatwierdza człowiek, a potem trafiają poza zasięg edycji agenta implementującego, więc zielony wynik dowodzi uzgodnionego zachowania, a nie interpretacji agenta.

Dajesz agentowi historyjkę: „użytkownicy mogą stosować kody rabatowe; nieprawidłowe kody pokazują błąd”. Czterdzieści minut później pull request jest zielony: 14 nowych testów, wszystkie przechodzą. Żaden nie sprawdza sumy koszyka, wygasły kod zwraca HTTP 200 z komunikatem, a w trzeciej iteracji jeden test po cichu zmienił się z toBe(9000) na toBe(10000). Agent zrobił to, o co go poproszono. Nikt nie zapisał, co znaczy „działa”, w formie, którą maszyna mogłaby wyegzekwować.

Ta strona jest dla programistów, którzy przekazują historyjki do Claude Code, Codeksa lub Cursora, oraz dla tech leadów, którzy chcą przenieść review z diffu na kontrakt zatwierdzany przez zespół, zanim powstanie kod.

Co dają wykonywalne kryteria akceptacji

Wzorzec przepisania mglistej historyjki na trzy do siedmiu numerowanych kryteriów Given/When/Then z konkretnymi wartościami.
Czerwone testy akceptacyjne w trzech stosach (TypeScript z Playwrightem, Python z pytest-bdd, Elixir z ExUnit), każdy w wersji „przed” i „po”.
Blokadę testów: regułę deny w Claude Code dla sesji implementującej oraz strażnika w CI i wpis w CODEOWNERS, które działają z każdym narzędziem.
Cztery prompty do skopiowania: przepytanie historyjki, napisanie czerwonych testów, implementacja pod zablokowany kontrakt i audyt słabości testów.
Model akceptacji, w którym człowiek zatwierdza kontrakt i dowody, zamiast czytać każdą zmienioną linię.

Po co agentom wykonywalne kryteria akceptacji?

Agent optymalizuje pod sprawdzenie, które może uruchomić. Jeśli jedynym sprawdzeniem jest „testy przechodzą”, a testy pisze agent, pętla nie ma punktu stałego: test i kod przesuwają się razem, a zielony kolor znaczy tylko „spójne samo ze sobą”. Kryterium opisane prozą w zgłoszeniu nie pomaga, bo agent czyta je raz, a potem interpretuje.

Rozwiązaniem jest kolejność działań. Kryteria stają się testami przed implementacją, człowiek zatwierdza je, gdy są czerwone, a sesja implementująca nie może ich zmienić. To acceptance test-driven development z jednym dodatkiem, który ma znaczenie przy agentach: autor testów i implementator to osobne sesje, a kontrakt egzekwuje narzędzie, nie instrukcja.

Ta strona dotyczy kontraktu dla jednej historyjki. Utrzymywanie długowiecznego spec.md jako źródła prawdy dla wielu historyjek opisuje spec-driven development, a pisanie i uruchamianie Gherkina z Cucumber.js – przepływy pracy BDD. Miejsce kryteriów w sekwencji intencja → specyfikacja → plan → zadania pokazuje łańcuch artefaktów.

Kiedy kryterium akceptacji jest wykonywalne?

Kryterium jest wykonywalne, gdy test może na nim polec. Prowadzą do tego cztery cechy:

Cecha	Mgliste (przed)	Wykonywalne (po)
Konkretne wartości	„prawidłowy kod obniża sumę”	„koszyk na 100,00 z kodem `SAVE10` (10%) kosztuje 90,00”
Obserwowalne na granicy systemu	„rabat jest zapisany”	„`POST /api/carts/:id/discount` zwraca 200 z `totalCents: 9000`”
Nazwana ścieżka błędu	„nieprawidłowe kody pokazują błąd”	„wygasły kod zwraca 422 `code_expired`, a suma zostaje 100,00”
Stały identyfikator	brak	`AC-2`, użyty w nazwie testu i sprawdzany przez CI

Tak wygląda historyjka o rabatach po przepisaniu. Leży w repozytorium, w specs/discount-codes.md, obok kodu, którym rządzi. Scenariusze zostają po angielsku, bo są wiązane z kodem kroków testów:

# specs/discount-codes.md — approved by: product owner, 2026-09-26
Feature: Discount codes at checkout

  # AC-1
  Scenario: A valid code takes its percentage off the cart total
    Given a cart totalling 100.00
    And an active code "SAVE10" worth 10%
    When the customer applies "SAVE10"
    Then the response is 200
    And the cart total is 90.00

  # AC-2
  Scenario: An expired code is rejected and the total is unchanged
    Given a cart totalling 100.00
    And a code "SPRING10" that expired on 2026-03-31
    When the customer applies "SPRING10"
    Then the response is 422 with error "code_expired"
    And the cart total is still 100.00

  # AC-3
  Scenario: A customer can redeem a code only once
    Given customer "c-42" has already redeemed "WELCOME15"
    And customer "c-42" has a cart totalling 80.00
    When they apply "WELCOME15"
    Then the response is 409 with error "code_already_used"
    And the cart total is still 80.00

Rozsądny zakres to trzy do siedmiu kryteriów na historyjkę. Mniej zwykle oznacza brak ścieżek błędu, więcej – że historyjkę trzeba podzielić (zobacz jak przygotować backlog dla agentów). Przypadki brzegowe, które są regułą dla wielu wejść, np. „suma nigdy nie jest ujemna”, należą do testów opartych na właściwościach, a nie do długiej listy scenariuszy.

Jak przejść od historyjki do czerwonego testu?

Przepływ ma dwie sesje i jedną bramkę ludzką między nimi. Człowiek zatwierdza mały, czytelny artefakt (scenariusze i czerwony przebieg), a nie diff z implementacją.

Przepytaj historyjkę. Daj agentowi zgłoszenie (wklej je albo pobierz przez serwer MCP trackera) i poproś o numerowane kryteria Given/When/Then oraz listę otwartych pytań. Odpowiedz na nie sam albo z product ownerem; agent, który zgaduje odpowiedź, zapisuje zgadywankę w kontrakcie.
Zacommituj kryteria. Zapisz je w specs/<feature>.md razem z identyfikatorami. Ten plik czyta product owner.
Napisz czerwone testy w osobnej sesji. Świeża sesja, bez implementacji w kontekście, pisze po jednym teście na kryterium w tests/acceptance/, nazywa każdy test jego identyfikatorem i steruje systemem przez publiczną granicę (HTTP, CLI albo UI), nigdy przez funkcje wewnętrzne.
Udowodnij, że testy są czerwone z właściwego powodu. Uruchom zestaw akceptacyjny i przeczytaj komunikaty błędów. „Expected 9000, received 404” to poprawna czerwień: trasy jeszcze nie ma. Błąd składni, błąd importu albo brakująca fikstura to zepsuty test, który później zazieleni się z niewłaściwego powodu.
Zatwierdź kontrakt. Otwórz pull request kontraktu z plikiem kryteriów, testami oznaczonymi jako oczekiwane porażki i czerwonym wynikiem wklejonym do opisu. To oznaczenie pozwala, by czerwony z założenia pull request przeszedł wymagane CI; zobacz jak czerwony kontrakt przechodzi przez CI niżej. Zatwierdza go osoba odpowiedzialna za zachowanie (product owner albo tech lead). To krótkie review, bo artefakt jest mały.
Zablokuj kontrakt. Sesja implementująca dostaje regułę deny albo instrukcję dla tests/acceptance/ i specs/, a CI odrzuca każdy pull request z implementacją, który zmienia na tych ścieżkach cokolwiek poza usunięciem oznaczeń oczekiwanej porażki. Pliki są w sekcji o blokadzie poniżej.
Implementuj do zieleni. Zanim sesja wystartuje, właściciel kontraktu (człowiek, nie agent) zakłada gałąź implementacji z jednym commitem, który wyłącznie usuwa oznaczenia oczekiwanej porażki z kroku 5, więc testy są uczciwie czerwone. Dopiero wtedy nowa sesja implementuje pod zablokowane testy i może dopisać tyle własnych testów jednostkowych, ile chce. Kończy, gdy zestaw akceptacyjny przechodzi, albo gdy uzna, że kryterium jest błędne – wtedy raportuje, zamiast edytować.
Sprawdź dowody. CI weryfikuje trzy rzeczy: zestaw akceptacyjny jest zielony, ścieżki kontraktu są niezmienione poza usuniętymi oznaczeniami, a każdy identyfikator kryterium ma test. Recenzent czyta ten wynik, a nie każdą linię diffu.

Read the story below. Do not write any code or tests.

1. Rewrite it as 3–7 acceptance criteria in Given/When/Then form, numbered AC-1, AC-2, ...
   Every criterion must use concrete values (amounts, codes, dates, status codes, error keys)
   and must be observable at a public boundary: an HTTP response, CLI output, or visible UI state.
2. Include at least one unhappy path per rule (invalid input, expired state, repeated action,
   missing permission).
3. After the criteria, list every question you had to guess an answer to, as a numbered list.
   Do not resolve them yourself.
4. Flag any criterion that is really a rule over many inputs ("never negative", "always sorted")
   as a candidate for a property-based test instead of a scenario.

Story:
<paste the ticket here>

Read specs/discount-codes.md. Write one acceptance test per criterion in tests/acceptance/.

Rules:
- Name every test with its criterion ID first, e.g. "AC-2: an expired code is rejected ...".
- Drive the system only through its public HTTP API. Do not import application modules,
  do not mock anything inside the application, and do not add production code.
- Assert the observable outcome in the criterion (status, error key, resulting total), not
  that some function was called.
- Seed data through the existing test fixtures. If a fixture is missing, add it under
  tests/support/ and say so.

Then run the acceptance suite and show me the failure message for each test. For each one,
tell me whether it fails because the feature is missing (correct) or because the test itself
is broken (fix it). Stop when every test is red for the correct reason.

Jak wygląda czerwony test akceptacyjny w twoim stosie?

Ta sama historyjka w trzech stosach. Każde „przed” to test, jaki agent pisze, sprawdzając po fakcie własną implementację; każde „po” to test na poziomie kryterium, napisany przed jakąkolwiek implementacją.

Przed. Agent zamockował własną funkcję wyszukującą i sprawdził, że mock został wywołany. Test przechodzi niezależnie od tego, czy suma się zmienia:

// src/lib/discounts.test.ts: written by the implementer, after the code
vi.mock('./discount-repo');

it('applies discount', async () => {
  vi.mocked(findDiscount).mockResolvedValue({ percent: 10 });
  await applyDiscount(cart, 'SAVE10');
  expect(findDiscount).toHaveBeenCalledWith('SAVE10');
});

Po. Test API w Playwrighcie (@playwright/test, fikstura request) na granicy HTTP, napisany jako pierwszy:

import { test, expect } from '@playwright/test';
import { seedCart, seedCode } from '../support/seed';

test('AC-1: a valid code takes its percentage off the cart total', async ({ request }) => {
  const cart = await seedCart(request, { totalCents: 10_000 });
  await seedCode(request, { code: 'SAVE10', percent: 10 });

  const res = await request.post(`/api/carts/${cart.id}/discount`, { data: { code: 'SAVE10' } });

  expect(res.status()).toBe(200);
  expect((await res.json()).totalCents).toBe(9_000);
});

test('AC-2: an expired code is rejected and the total is unchanged', async ({ request }) => {
  const cart = await seedCart(request, { totalCents: 10_000 });
  await seedCode(request, { code: 'SPRING10', percent: 10, expiresAt: '2026-03-31T23:59:59Z' });

  const res = await request.post(`/api/carts/${cart.id}/discount`, { data: { code: 'SPRING10' } });

  expect(res.status()).toBe(422);
  expect((await res.json()).error).toBe('code_expired');
  const after = await request.get(`/api/carts/${cart.id}`);
  expect((await after.json()).totalCents).toBe(10_000);
});

Przykład zakłada use.baseURL (i blok webServer) w playwright.config.ts; bez tego względne adresy URL padają z błędem nieprawidłowego URL-a, czyli czerwienią z niewłaściwego powodu.

Wynik przed implementacją: Expected: 200, Received: 404. To poprawna czerwień.

Przed. Zgłoszenie mówiło „kod można użyć tylko raz”; agent przetestował napisaną przez siebie klasę Redemptions w pamięci, więc test nigdy nie dotknął API ani bazy danych.

Po. pytest-bdd wiąże zatwierdzony tekst scenariusza z funkcjami kroków. Plik .feature jest dosłowną kopią kryteriów, a client to fikstura TestClient z FastAPI zdefiniowana w conftest.py:

from pytest_bdd import scenarios, given, when, then, parsers

scenarios("features/discount_codes.feature")

@given(parsers.parse('customer "{cid}" has already redeemed "{code}"'))
def already_redeemed(seed, cid, code):
    seed.redemption(customer_id=cid, code=code)

@given(parsers.parse('customer "{cid}" has a cart totalling {total:f}'), target_fixture="cart")
def cart_for(seed, cid, total):
    return seed.cart(customer_id=cid, total=total)

@when(parsers.parse('they apply "{code}"'), target_fixture="response")
def apply_code(client, cart, code):
    return client.post(f"/carts/{cart['id']}/discount", json={"code": code})

@then(parsers.parse('the response is {status:d} with error "{error}"'))
def error_response(response, status, error):
    assert response.status_code == status
    assert response.json()["error"] == error

@then(parsers.parse("the cart total is still {total:f}"))
def total_unchanged(client, cart, total):
    assert client.get(f"/carts/{cart['id']}").json()["total"] == total

Wynik przed implementacją: assert 404 == 409. Wpisz identyfikator w tytuł scenariusza (Scenario: AC-3 A customer can redeem a code only once), żeby znalazł go opisany niżej test pokrycia.

Przed. Agent wywołał Shop.Discounts.apply/2 bezpośrednio, ze strukturą zbudowaną w teście, co omija kontroler, changeset i mapowanie błędów, które widzi klient.

Po. Test ConnCase przez router, z identyfikatorem kryterium w nazwie testu:

defmodule ShopWeb.Acceptance.DiscountCodesTest do
  use ShopWeb.ConnCase, async: true
  import Shop.Fixtures

  test "AC-2: an expired code is rejected and the total is unchanged", %{conn: conn} do
    cart = cart_fixture(total_cents: 10_000)
    code_fixture(code: "SPRING10", percent: 10, expires_at: ~U[2026-03-31 23:59:59Z])

    conn = post(conn, ~p"/api/carts/#{cart.id}/discount", code: "SPRING10")

    assert %{"error" => "code_expired"} = json_response(conn, 422)
    assert Shop.Carts.get_cart!(cart.id).total_cents == 10_000
  end
end

Wynik przed implementacją: Phoenix.Router.NoRouteError dla trasy rabatu. W Elixirze zablokowany katalog to test/acceptance/, a nie tests/acceptance/; dostosuj ścieżki w blokadzie poniżej.

Testy „po” mają trzy wspólne nawyki: nazywają kryterium, przygotowują stan przez fikstury zamiast mockować aplikację i sprawdzają wynik, który widzi klient. Test wywołujący tylko funkcje wewnętrzne może przechodzić, gdy endpoint zwraca 500.

Jak trzymać testy akceptacyjne poza zasięgiem edycji agenta?

Same instrukcje nie wystarczą. Agent, który długo iteruje nad czerwonym testem, w końcu uzna, że „test jest zły”, i go zmieni. Użyj dwóch warstw: blokady w sesji implementującej tam, gdzie narzędzie ją wspiera, i strażnika w CI, który działa niezależnie od narzędzia. Pełne omówienie, łącznie ze scenariuszami holdout trzymanymi poza repozytorium, znajdziesz w artykule ochrona wyroczni.

Dodaj strażnika w CI i właścicieli kodu (wszystkie narzędzia)

Strażnik w CI sprawia, że kontrakt jest wiążący. Jeśli pull request nie ma etykiety zmiany kontraktu, strażnik odrzuca każdą zmianę na ścieżkach kontraktu poza usunięciem oznaczeń oczekiwanej porażki, a CODEOWNERS kieruje do właściciela każdy pull request, który tych ścieżek dotyka:

name: acceptance
on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  contract:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
          persist-credentials: false
      - name: Implementation PRs may only remove expected-failure markers
        if: ${{ !contains(github.event.pull_request.labels.*.name, 'acceptance-contract') }}
        env:
          BASE_REF: ${{ github.base_ref }}
        run: |
          base=$(git merge-base "origin/$BASE_REF" HEAD)
          changes=$(git diff --name-status "$base" HEAD -- specs tests/acceptance)
          bad=0
          while IFS=$'\t' read -r status path; do
            [ -n "$status" ] || continue
            if [ "$status" = M ] && [[ "$path" == tests/acceptance/* ]] &&
               git show "$base:$path" |
                 sed -E -e '/^[[:space:]]*@xfail[[:space:]]*$/d' -e 's/@xfail[[:space:]]+//g' -e 's/\btest\.fail\(/test(/g' |
                 cmp -s - <(git show "HEAD:$path"); then
              echo "$path: expected-failure markers removed, nothing else"
            else
              echo "::error::$status $path changes the contract (or leaves a marker in place)"; bad=1
            fi
          done <<< "$changes"
          if [ "$bad" -ne 0 ]; then
            echo "::error::Open a separate PR labeled acceptance-contract for the owner to approve."
            exit 1
          fi
      - name: Every criterion has a test
        run: |
          for id in $(grep -ohE '([A-Z]+-)?AC-[0-9]+' specs/*.md | sort -u); do
            grep -rqE "(^|[^A-Z-])$id([^0-9]|$)" tests/acceptance || { echo "::error::$id has no acceptance test"; exit 1; }
          done
  open-contracts:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - name: No expected-failure markers left on the default branch
        run: |
          if grep -rnE '\btest\.fail\(|@xfail\b' tests/acceptance; then
            echo "::error::A contract is merged but not implemented; its markers are listed above."
            exit 1
          fi

# .github/CODEOWNERS
/specs/            @your-org/product-owners
/tests/acceptance/ @your-org/product-owners
/pytest.ini        @your-org/product-owners
/.github/          @your-org/product-owners

Włącz Require review from Code Owners w regule ochrony gałęzi albo w rulesecie dla gałęzi domyślnej; bez tego CODEOWNERS tylko prosi o review. Zamień main na nazwę swojej gałęzi domyślnej. Sam zestaw akceptacyjny uruchamiaj w tym samym workflow albo w istniejącym jobie testowym. Identyfikatory powyżej są unikalne w całym repozytorium; jeśli numerujesz je od nowa w każdej funkcji, dodaj prefiks (DISC-AC-2). Sprawdzenie dopasowuje cały identyfikator, więc test DISC-AC-2 nie spełnia kryterium AC-2 i odwrotnie.

Typy zdarzeń labeled i unlabeled uruchamiają strażnika ponownie, gdy właściciel doda etykietę, więc nikt nie musi wypychać pustego commita. Etykieta tylko kieruje pull request: każdy, kto może dodawać etykiety, także agent z tokenem gh, może sprawić, że strażnik zostanie pominięty. Prawdziwą kontrolą jest Require review from Code Owners na ścieżkach kontraktu. To samo dotyczy samego strażnika: przy zdarzeniu pull_request GitHub uruchamia plik workflow z gałęzi pull requesta, więc pull request z implementacją może strażnika zmienić albo usunąć, a przebieg i tak będzie zielony. Dlatego /.github/ też jest w CODEOWNERS: przy wymaganym review właściciela zmieniony workflow nie wejdzie bez jego zgody. Workflow nie potrzebuje sekretów, ma token tylko do odczytu i pobiera kod z persist-credentials: false.

Jak czerwony kontrakt przechodzi przez wymagane CI?

Pull request kontraktu jest czerwony z założenia, więc jeśli zestaw akceptacyjny jest wymaganym checkiem, nie da się go scalić. Nie rozwiązuj tego, robiąc job akceptacyjny opcjonalnym na gałęzi domyślnej: opcjonalny check to także furtka, przez którą pull request z implementacją wejdzie na czerwono. Dwa wzorce zostawiają check wymagany.

Ścisłe oznaczenia oczekiwanej porażki (Playwright, pytest). Pull request kontraktu deklaruje każdy nowy test jako taki, który ma się nie udać. Wymagany job przechodzi wtedy tylko dopóty, dopóki te testy naprawdę padają, więc CI przy każdym pushu ponownie dowodzi czerwonego przebiegu. Gdy implementacja sprawi, że test przejdzie, runner zgłosi nieoczekiwany sukces jako porażkę:

// In the contract PR: same title, so the ID check still finds it
test.fail('AC-1: a valid code takes its percentage off the cart total', async ({ request }) => {
  // ...body unchanged...
});

Runner	Oznaczenie w pull requeście kontraktu	Wynik, gdy funkcja już działa
Playwright	`test.fail('AC-1: ...', async () => ...)`	`Expected to fail, but passed.`, job pada
pytest-bdd	tag `@xfail` na scenariuszu oraz `xfail_strict = true` w sekcji `[pytest]` pliku `pytest.ini`	`XPASS(strict)`, job pada

Usunięcie oznaczeń to krok człowieka i idzie na początek. Dopóki oznaczenie jest na miejscu, poprawna implementacja zmienia zestaw na czerwony (Expected to fail, but passed.), co agenta mającego dojść do zieleni popchnęłoby do cofnięcia działającej funkcji. Dlatego zanim sesja implementująca wystartuje, właściciel kontraktu zakłada gałąź implementacji z jednym commitem, który wyłącznie usuwa oznaczenia tej historyjki (test.fail( z powrotem na test(, tagi @xfail). Sesja pracuje wtedy pod uczciwie czerwone testy i kończy, gdy zestaw jest zielony, tak jak mówią prompty na tej stronie. Taki pull request nie potrzebuje etykiety: strażnik porównuje każdy zmieniony plik w tests/acceptance/ z jego wersją bazową bez oznaczeń i odrzuca każdą inną różnicę, także pozostawione oznaczenie, więc trzymaj jedną historyjkę w jednym pliku testów. CODEOWNERS i tak kieruje go do właściciela, który widzi diff testów złożony wyłącznie z usuniętych oznaczeń. Oba runnery sprawdzono 2026-10-02 (Playwright 1.63.0, pytest 9.1.1 z pytest-bdd 9.0.0): job był zielony, dopóki testy padały, i padał, gdy zaślepiona funkcja zwracała oczekiwaną wartość. Skrypt strażnika uruchomiono na zmianach: tylko usunięte oznaczenia, usunięcie częściowe, osłabiona asercja, dodany tag, nowy plik, usunięty plik i zmiana specyfikacji; przeszły tylko zmiana samych oznaczeń i zmiana samego kodu aplikacji.

Ścisłość też trzymaj poza zasięgiem implementacji. Przy xfail_strict = false w pytest.ini otagowany scenariusz zgłasza 1 xpassed, gdy funkcja działa, i 1 xfailed, gdy jest zepsuta, w obu przypadkach z kodem wyjścia 0, więc oznaczeń nigdy nie trzeba usuwać. Uruchamiaj zestaw pytest w CI jako pytest -o xfail_strict=true tests/acceptance; nadpisanie z linii poleceń wygrywa z plikiem ini (przy ini ustawionym na false działająca funkcja daje 1 failed i kod wyjścia 1). Z tego samego powodu pytest.ini jest w CODEOWNERS powyżej. Job open-contracts pada na gałęzi domyślnej, dopóki zostaje tam jakiekolwiek oznaczenie. Nie blokuje żadnego pull requesta; sprawia, że kontrakt scalony, ale jeszcze niezaimplementowany, jest widoczny jako czerwony przebieg, dopóki pull request z implementacją nie usunie jego oznaczeń.

ExUnit nie ma ścisłego trybu oczekiwanej porażki, a zwykłe wykluczenie przez @tag :pending niczego nie pilnuje (implementacja wchodzi do gałęzi, a testy ani razu się nie uruchamiają), więc projekty w Elixirze używają drugiego wzorca.

Gałąź historyjki. Pull request kontraktu celuje w story/discount-codes zamiast w gałąź domyślną, a pull requesty z implementacją celują w gałąź historyjki, więc strażnik porównuje zmiany z bazą, która już zawiera kontrakt. Daj gałęziom story/* własny ruleset z Require review from Code Owners, bo inaczej pull request kontraktu wejdzie bez właściciela. W tym rulesecie wymagaj strażnika (jobu contract), ale nie zestawu akceptacyjnego: pull request kontraktu do gałęzi historyjki jest czerwony z założenia, a wymagany zestaw zablokowałby go dokładnie tak samo jak na gałęzi domyślnej. Zestaw jest wymagany przy końcowym pull requeście z gałęzi historyjki do gałęzi domyślnej, który musi być zielony i dostaje etykietę acceptance-contract, bo wnosi ze sobą ścieżki kontraktu. Oznaczenia nie są tu potrzebne, więc sesja implementująca od razu pracuje pod czerwone testy.

Zablokuj sesję implementującą w każdym narzędziu

Claude Code sprawdza reguły Edit(path) dla każdego wbudowanego narzędzia zapisującego pliki, dla rozpoznawanych poleceń plikowych w Bashu, takich jak sed i tee, oraz dla celów przekierowań. Reguły deny z dowolnego zakresu ustawień wygrywają z regułami allow. Reguła we współdzielonym .claude/settings.json zablokowałaby też sesję piszącą testy, więc przekaż reguły jako flagi tylko sesji implementującej:

# Terminal: interactive implementation in its own worktree
claude --worktree disc-impl \
  --disallowedTools "Edit(/specs/**)" "Edit(/tests/acceptance/**)"

# Terminal or CI: headless implementation with a budget
claude -p "Implement specs/discount-codes.md until npx playwright test tests/acceptance passes." \
  --disallowedTools "Edit(/specs/**)" "Edit(/tests/acceptance/**)" \
  --permission-mode acceptEdits \
  --allowedTools "Bash(npx playwright test *)" \
  --max-budget-usd 5

Wiodący / zakotwicza wzorzec w źródle ustawień. Dla flag CLI oraz dla .claude/settings.json i .claude/settings.local.json jest nim główny katalog roboczy (tutaj worktree). Dla pliku przekazanego przez --settings <plik> jest nim katalog tego pliku, więc te same reguły w .claude/implementer.json blokowałyby .claude/specs/** i niczego by nie chroniły; jeśli wolisz plik, użyj w nim ścieżek bezwzględnych z //. Strona uprawnień Anthropic ostrzega, że te reguły nie obejmują „arbitrary subprocesses that read or write files indirectly, like a Python or Node script”; do egzekwowania na poziomie systemu użyj sandboksa Basha, a wiążącym sprawdzeniem niech zostanie strażnik w CI. Flagi sprawdzone na Claude Code 2.1.283, 2026-09-26.

Zapisz regułę w AGENTS.md, który Codex czyta przed rozpoczęciem pracy, a egzekwowanie zostaw strażnikowi w CI. Od Codeksa 0.150.0 niezaufany projekt nie dostarcza swojego projektowego AGENTS.md, więc oznacz repozytorium jako zaufane: zaakceptuj pytanie o zaufanie przy pierwszym uruchomieniu codex w repozytorium. Dodaj tę sekcję do AGENTS.md:

## Acceptance contract
- Never edit files under specs/ or tests/acceptance/. They are approved by the product owner.
- If an acceptance test looks wrong, stop and explain why in your final message.

Implementację uruchamiaj we własnym zarządzanym worktree, a audyt testów w trybie tylko do odczytu:

# Terminal (Codex CLI 0.157.1)
codex exec --worktree --approve-for-me \
  -o impl-report.md "Implement specs/discount-codes.md until the acceptance suite passes."

codex exec --sandbox read-only \
  "Audit tests/acceptance against specs/discount-codes.md. Do not modify files."

Codex 0.157.1 nie ma udokumentowanej reguły blokującej zapis dla konkretnej ścieżki (sprawdzone w codex --help i codex features list, 2026-09-26), więc blokadą jest AGENTS.md razem ze strażnikiem w CI; lokalną blokadę może dodać hook PreToolUse (jedno z 12 zdarzeń hooków Codeksa), opisany w artykule ochrona wyroczni.

Zacznij implementację w Plan Mode, który „creates detailed implementation plans before writing any code”, i sprawdź, czy plan wskazuje polecenie testów akceptacyjnych i nie dotyka specs/ ani tests/acceptance/. Te same dwie reguły co w zakładce Codex dodaj do reguły projektu (Rules), żeby widziała je każda sesja agenta; położenie i format pliku opisuje strona reguły projektu.

Hooki Cursora „can observe, block, or modify behavior” na określonych etapach pętli agenta, więc hook może odrzucić edycję ścieżek kontraktu. Ta strona nie wskazuje konkretnego zdarzenia hooka; hook blokujący zapis do ścieżek kontraktu opisuje ochrona wyroczni, a egzekwowaniem niech pozostanie strażnik w CI.

Dla Cloud Agenta (także uruchomionego przez Automation w reakcji na zdarzenie z GitHuba) ten sam strażnik w CI działa na otwartym przez niego pull requeście, więc kontrakt obowiązuje nawet bez lokalnej konfiguracji.

Jeśli historyjka żyje w Linearze albo Jirze, podłącz tracker, żeby krok 1 czytał zgłoszenie bezpośrednio: claude mcp add --transport http linear https://mcp.linear.app/mcp w Claude Code, codex mcp add linear --url https://mcp.linear.app/mcp && codex mcp login linear w Codeksie (codex mcp login linear przeprowadza logowanie OAuth wymagane przez serwer Lineara) i zdalny wpis pod mcpServers w .cursor/mcp.json w Cursorze. Przy kryteriach dotyczących UI serwer MCP Playwrighta (@playwright/mcp) pozwala sesji piszącej testy obejrzeć działającą stronę, zanim wybierze selektory; konfigurację opisują serwery MCP do automatyzacji przeglądarki.

Implement the feature described in specs/discount-codes.md.

The acceptance tests in tests/acceptance/ are an approved contract. You must not edit, skip,
rename, or delete them, and you must not change specs/. Do not special-case the codes or
amounts that appear in the tests; implement the rule for any code and any total.

Loop: run `npx playwright test tests/acceptance`, read the first failure, change application
code, run again. Add unit tests of your own under src/ where they help.

Stop when the acceptance suite is green, and report: which AC IDs pass, which files you changed,
and any criterion you believe is wrong, with the reason. If you believe a criterion is wrong,
stop and report it instead of working around it.

You are reviewing tests, not code. Read specs/discount-codes.md and tests/acceptance/.
Do not modify any file.

For each AC ID, answer:
1. Is there exactly one test that names this ID?
2. Would the test still pass if the feature were implemented wrongly in an obvious way
   (discount ignored, error returned with status 200, total changed on a rejected code)?
   Name the wrong implementation that would slip through, if any.
3. Does the test reach the system only through its public boundary, or does it import or mock
   application internals?
4. Does it assert the outcome stated in the criterion, or something weaker?

Finish with a table: AC ID | test name | weakness found | suggested stronger assertion.

Skąd wiesz, że kontrakt jest dotrzymany?

Sens kontraktu polega na tym, że nikt nie musi czytać każdej zmienionej linii, żeby ufać wynikowi. Każde sprawdzenie ma właściciela i sygnał:

Co jest sprawdzane	Jak	Kto zatwierdza
Kryteria opisują właściwe zachowanie	Pull request kontraktu: plik kryteriów, nazwy testów, czerwony wynik	Product owner albo tech lead, przed implementacją
Testy są czerwone z właściwego powodu	Czerwony przebieg wklejony do pull requesta kontraktu	Ten sam recenzent
Testy są wystarczająco silne	Prompt audytowy powyżej, potem wynik mutacyjny z artykułu jak silna jest twoja wyrocznia	Tech lead, dla całego zestawu, a nie dla każdego pull requesta
Implementacja spełnia kontrakt	Zielony zestaw akceptacyjny w CI	CI
Kontraktu nie dopasowano do kodu	Strażnik w CI na `specs/` i `tests/acceptance/` (bez etykiety przechodzi tylko usunięcie oznaczeń), `CODEOWNERS` na tych ścieżkach, `pytest.ini` i `.github/`	CI oraz właściciel kodu przy usunięciu oznaczeń i każdej zmianie kontraktu
Każde kryterium ma pokrycie	Krok sprawdzający identyfikatory	CI

Pull request z implementacją niesie potem krótkie podsumowanie dowodów: identyfikatory AC z wynikami, wynik strażnika i wszystko, co zgłosił agent. To podsumowanie jest jednym polem pakietu dowodów, a czytanie go zamiast diffu to praktyka opisana w artykule dowody zamiast diffów. Recenzent nadal czyta kod tam, gdzie wymaga tego klasa ryzyka (bezpieczeństwo, płatności, migracje); kontrakt zmienia domyślny tryb, a nie każdy przypadek.

Co się psuje przy wykonywalnych kryteriach akceptacji?

Agent edytuje albo pomija test. Sygnał: strażnik w CI pada albo w katalogu akceptacyjnym pojawia się .skip lub @pytest.mark.skip. Naprawa: odrzuć pull request, uruchom implementację od nowa w świeżej sesji z załadowaną blokadą i dopisz „do not skip” do promptu implementacyjnego. Jeśli dzieje się to dwa razy przy tym samym kryterium, kryterium jest prawdopodobnie błędne; wróć z nim do pull requesta kontraktu.

Agent robi wyjątek dla danych testowych. Kod sprawdza if (code === 'SAVE10'). Sygnał: prompt audytowy albo recenzent szukający literałów z testów. Naprawa: przez pull request kontraktu dodaj do scenariusza drugi przykład z innymi wartościami (scenario outline albo drugi test) i trzymaj jeden zestaw przykładów poza repozytorium jako holdout uruchamiany tylko w CI; zobacz ochrona wyroczni.

Testy były czerwone z niewłaściwego powodu. Brakująca fikstura albo literówka sprawiły, że wszystkie testy padały, a implementator „naprawił” kod wspierający testy, aż zrobiło się zielono. Naprawa: powtórz krok 4 i przeczytaj każdy komunikat błędu przed zatwierdzeniem; traktuj tests/support/ jako część kontraktu, jeśli implementator nie powinien go zmieniać.

Testy są sprzężone z implementacją. Importują klasę serwisu albo sprawdzają zapytanie SQL, więc każdy refaktoring je psuje, a agent ma pokusę, żeby je edytować. Naprawa: przepisz je na publiczną granicę. Jeśli zachowanie nie ma jeszcze publicznej granicy, kryterium jest na złym poziomie; przenieś je do testu jednostkowego, którego właścicielem jest implementator.

Kontrakt zmienia się w trakcie historyjki. Produkt zmienia regułę, gdy implementacja trwa. Naprawa: zatrzymaj przebieg, otwórz pull request kontraktu ze zmienionym kryterium i jego nowym czerwonym testem, zatwierdź go i dopiero wtedy wznów implementację. Nigdy nie pozwól, żeby zmianę wniosła sesja implementująca.

Zestaw akceptacyjny robi się wolny albo niestabilny. Sygnał: programiści restartują CI, aż będzie zielono. Naprawa: trzymaj trzy do siedmiu testów akceptacyjnych na historyjkę i, gdzie się da, na granicy API; przypadki kombinatoryczne przenieś do testów jednostkowych albo testów właściwości; naprawiaj niestabilne testy, zanim dodasz scenariusze, bo niestabilna wyrocznia uczy wszystkich, ludzi i agentów, ignorować czerwień.

Dokąd dalej z kryteriami akceptacji

Porządnie zablokuj testy, łącznie z holdoutami i wykrywaniem osłabiania testów: ochrona wyroczni.
Uruchom pętlę testową, w której pracuje agent implementujący: etap testowania w cyklu życia.
Zmierz, czy twoje testy akceptacyjne złapałyby prawdziwy błąd: jak silna jest twoja wyrocznia?
Utrzymuj specyfikację funkcji jako źródło prawdy dla wielu historyjek: spec-driven development.
Skonfiguruj tryby uprawnień i sandboksy, w których działa implementator: uprawnienia, sandboksy i tryby zatwierdzania.
Kształtuj zgłoszenia tak, żeby każde przychodziło z testowalnymi kryteriami: jak przygotować backlog dla agentów.

Najczęstsze pytania

Czym jest wykonywalne kryterium akceptacji?

To kryterium zapisane jako scenariusz Given/When/Then z konkretnymi wartościami, sparowane z automatycznym testem, który nie przechodzi, zanim funkcja powstanie, i przechodzi dopiero wtedy, gdy zachowanie istnieje. Ma identyfikator, np. AC-2, dzięki któremu CI sprawdza, że każde kryterium ma test.

Dlaczego testy akceptacyjne muszą być poza zasięgiem edycji agenta?

Agent, któremu każesz doprowadzić testy do zieleni, może to zrobić, zmieniając testy. Jeśli sesja implementująca nie może ich edytować, a CI odrzuca każdy pull request z implementacją, który zmienia w nich coś więcej niż usunięcie oznaczeń oczekiwanej porażki, zielony wynik oznacza, że zatwierdzone zachowanie naprawdę istnieje.

Co zatwierdza człowiek, jeśli nie diff?

Kontrakt: scenariusze, nazwy testów powiązane z identyfikatorami kryteriów i czerwony przebieg, który pokazuje, że każdy test pada z właściwego powodu. Po implementacji człowiek sprawdza dowody (zielony przebieg akceptacyjny, niezmieniony kontrakt, pokrycie identyfikatorów), a nie czyta każdej linii.