Wybierz główny harness do inżynierii z AI

Główny harness do inżynierii z AI to agent kodujący razem z konfiguracją repozytorium, która prowadzi zadanie od spisanej intencji do zweryfikowanego diffa: wersjonowane instrukcje, bramka planu, ograniczone uprawnienia, izolacja i powtarzalne polecenie sprawdzające. Claude Code, Codex i Cursor mogą osiągnąć maksymalną odpowiedź w pytaniu Q1 scorecardu; o wyborze decyduje próba na twoich zadaniach.

Od miesiąca używasz dwóch agentów. Jeden wydawał się szybszy, drugi zadawał mniej pytań, a kolega z zespołu przysięga na trzeciego. Nikt nie zapisał, który z nich wyprodukował pull request wycofany w zeszłym tygodniu, a repozytorium wciąż nie ma pliku instrukcji. Ta strona jest dla dewelopera, który wybiera narzędzie, i dla tech leada, który chce, żeby wybór opierał się na dowodach możliwych do powtórzenia przez zespół.

Scorecard Q1 · Plan: Jak twój główny setup AI obsługuje pracę w repozytorium?

Maksymalna odpowiedź (3 punkty): „Główny harness używa wersjonowanych instrukcji, bramek planu i artefaktów, ograniczonych narzędzi oraz powtarzalnych dowodów”.

Niższe odpowiedzi to sugestie z czatu ręcznie kopiowane do repozytorium (1 punkt) oraz agent, który edytuje repozytorium, podczas gdy workflow i weryfikacja pozostają ad hoc (2 punkty).

Co daje ci próba harnessu

• Definicję „harnessu”, którą sprawdzisz w repozytorium, a nie preferencję produktową.
• Próbę trwającą tydzień lub dwa na trzech twoich zadaniach, przeprowadzoną tak samo w każdym narzędziu.
• Arkusz ocen, który szereguje kandydatów najpierw według zaakceptowanego wyniku, a koszt bierze pod uwagę na końcu.
• Cztery prompty do skopiowania: audyt gotowości, przebieg tylko z planem, ograniczone wykonanie i porównanie próby.
• Kontrolę zakresu i bramkę CI, które weryfikują każdy przebieg bez czytania każdej linii.
• Zapis decyzji podpisany przez tech leada, z datą ponownej próby.

Co liczy się jako harness i dlaczego narzędzie nie jest wynikiem?

Q1 nie ocenia logo, nazwy modelu ani terminala w zestawieniu z edytorem. Ocenia, czy skonfigurowany setup potrafi zrobić sześć rzeczy, a każda z nich zostawia dowód w repozytorium albo w logu przebiegu.

Możliwość	Dowód, który możesz wskazać	Jak to sprawdzić
Trwałe instrukcje	Przejrzany CLAUDE.md, AGENTS.md albo Rule w Cursorze z poleceniem sprawdzającym	Plik jest w Gicie i zmienia się przez pull request
Bramka planu	Przebieg bez edycji tworzy plan.md z plikami, ryzykami i testami	Commit z planem powstaje przed pierwszym commitem z kodem
Ograniczone wykonanie	Tryb uprawnień, sandbox albo polityka zatwierdzeń odpowiadają ryzyku zadania	Log przebiegu pokazuje tryb; sekretów i produkcyjnych poświadczeń nie ma w środowisku
Izolacja	Praca równoległa lub ryzykowna działa we własnym worktree Gita albo środowisku w chmurze	git worktree list albo ID przebiegu w chmurze
Powtarzalna weryfikacja	Jedno polecenie, np. npm run typecheck && npm run lint && npm test, uruchamiane przez agenta i ponownie przez CI	Wynik CI na pull requeście
Identyfikowalny review	Diff da się odnieść do intent.md, spec.md i plan.md	Kontrola zakresu poniżej przechodzi

Łańcuch artefaktów zawiera szablony intent.md, spec.md i plan.md. Mapa narzędzi wskazuje funkcję, która realizuje każdy wiersz w każdym narzędziu, sprawdzoną na Claude Code 2.1.283 i Codex 0.157.1. Ta strona jej nie powtarza; mówi, jak wybrać.

Dlaczego nie wybierać z macierzy funkcji ani z dema?

Z dwóch powodów. Po pierwsze, każdy wiersz powyżej jest dostępny we wszystkich trzech narzędziach, więc macierz funkcji rzadko rozróżnia je dla twojego repozytorium. Po drugie, wrażenia mylą. W randomizowanym badaniu METR z udziałem doświadczonych deweloperów open source (opublikowanym 2025-07-10, narzędzia z początku 2025 roku) deweloperzy spodziewali się, że AI przyspieszy ich o 24%, a po zmierzonym spowolnieniu nadal wierzyli, że przyspieszyło ich o 20%. To samo badanie zmierzyło, że pracowali o 19% dłużej. Mierz na własnych zadaniach.

Narzędzia różnią się miejscem pracy, a nie tym, co potrafią udowodnić:

Jeśli twój zespół głównie…	Zacznij próbę od	Dlaczego
Pracuje w IDE i przegląda zmiany wizualnie	Cursor	IDE-first: Agent, Plan Mode, Worktrees, Cloud Agents i Bugbot na pull requestach
Pisze skrypty, uruchamia agentów headless w CI albo egzekwuje politykę hookami	Claude Code	CLI-first: tryby uprawnień, hooki, claude -p z wynikiem JSON, subagenty
Przechodzi między aplikacją desktopową, CLI, IDE i zadaniami w chmurze	Codex	Wiele powierzchni: codex exec, profile uprawnień, --worktree, codex review, zadania w chmurze

Traktuj tabelę jako kolejność testowania, nie werdykt. Zawsze dołącz narzędzie, którego zespół używa dziś, jako punkt odniesienia.

Przeprowadź próbę harnessu na własnych zadaniach

Zaplanuj tydzień lub dwa. Próba porównuje harnessy, więc każdy kandydat dostaje te same zadania, te same instrukcje i tę samą bramkę. Wybór modelu to osobna decyzja: uruchom każde narzędzie na jego domyślnym modelu, zapisz, którego użyło, a routing zostaw stronie routing modeli na podstawie dowodów. Aktualne modele domyślne i ceny są w przewodniku po modelach.

1. Wybierz trzy reprezentatywne zadania. Każde dotyka kilku plików, ma obserwowalny wynik i nie wymaga dostępu do produkcji. Dobry zestaw to poprawka błędu z czerwonym testem, mała funkcja za flagą i refaktoryzacja bez zmiany zachowania. Dla każdego zachowaj commit bazowy.

2. Zapisz akceptację, zanim uruchomisz jakiekolwiek narzędzie. Dla każdego zadania zacommituj intent.md z ownerem i tym, co jest poza zakresem, oraz grader: testy, których agent nie widzi, i polecenie sprawdzające. O „zaakceptowaniu” decyduje grader, nie osoba prowadząca próbę.

3. Przygotuj repozytorium dla agenta raz. Zacommituj jeden plik instrukcji z dokładnym poleceniem sprawdzającym, krokami budowania i zakazanymi ścieżkami. Treść trzymaj w AGENTS.md i dodaj jednolinijkowy CLAUDE.md z @AGENTS.md, żeby Claude Code na obu kanałach wydań go czytał; to samo polecenie sprawdzające umieść w Rule Cursora. Treść opisują strony repozytorium gotowe dla agenta i zwięzły kontekst repozytorium.

4. Skonfiguruj każdego kandydata z tą samą granicą. Tylko zapis w workspace, żadnych produkcyjnych poświadczeń w środowisku, sieć wyłączona, chyba że zadanie jej wymaga. Uprawnienia i sandboxing porównuje te kontrolki wiersz po wierszu.

5. Najpierw sam plan, potem wykonanie w worktree. Zacommituj zaakceptowany plan.md przed jakimkolwiek kodem. Wykonaj każde zadanie raz w każdym narzędziu, każde we własnym worktree, z promptami poniżej. Polecenia dla każdego narzędzia są pod tymi krokami.

6. Zweryfikuj kontrolą zakresu i CI. Wypchnij każdy przebieg jako draft pull request. CI uruchamia polecenie sprawdzające i ukryte testy; kontrola zakresu wskazuje każdy plik, którego plan nie wymienił.

7. Wypełnij arkusz i zdecyduj. Uzupełnij zapis próby, zastosuj regułę decyzji i otwórz pull request, który dodaje decyzję do docs/ai/primary-harness.md.

Polecenia planu i wykonania różnią się między narzędziami. Każdy blok uruchamiasz w terminalu w katalogu głównym repozytorium; polecenie headless uruchom wewnątrz worktree utworzonego w kroku planu.

Claude Code

# Plan only: plan mode reads and proposes, it does not edit
claude --permission-mode plan -w trial-task-1

# Headless alternative for the execute step: run it inside the plan worktree
cd "$(git worktree list | awk '/trial-task-1/ {print $1}')"
# Cost ceiling and JSON result
claude -p "$(cat trial/task-1/execute-prompt.md)" \
  --permission-mode acceptEdits \
  --allowedTools "Bash(npm test *)" "Bash(npm run *)" \
  --max-budget-usd 5 \
  --output-format json > trial/runs/task-1-claude.json

W Claude Code 2.1.283 lub nowszym (oba kanały wydań na 2026-10-12) interaktywne sesje w terminalu startują w trybie auto, a claude -p startuje w trybie Manual (od v2.1.285 w trybie auto u zewnętrznych dostawców lub z wyłączoną telemetrią), więc zapisuj, w jakim trybie działał każdy przebieg. Zapisuj też kanał wydań i wersję: 2026-10-12 stable to v2.1.287, a latest to v2.1.296.

Codex

# Plan only: read-only permission profile, then type /plan in the session
codex --worktree -c default_permissions=":read-only"

# Execute headless in a managed worktree with workspace writes, JSONL events
codex exec --worktree -c default_permissions=":workspace" --json \
  -o trial/runs/task-1-codex-final.md \
  "$(cat trial/task-1/execute-prompt.md)" > trial/runs/task-1-codex.jsonl

Profile uprawnień są w wersji beta (Codex CLI 0.138.0 i nowsze) i nie łączą się z --sandbox; używaj jednego albo drugiego systemu. Od wersji 0.150.0 niezaufany projekt nie dostarcza swojego AGENTS.md, więc przed pierwszym przebiegiem oznacz repozytorium próby jako zaufane.

Cursor

Otwórz zadanie w Agencie, przełącz na Plan Mode i wklej prompt „tylko plan”. Po zaakceptowaniu plan.md uruchom prompt wykonania w Worktree, żeby próba nie trafiła do twojej kopii roboczej. Cloud Agents uruchamiają ten sam prompt w izolowanej maszynie wirtualnej w chmurze. Zapisz model, który pokazuje picker: Cursor nie wskazuje jednego modelu domyślnego (jego strona modeli i cen, sprawdzone 2026-10-12), a jego funkcje sprawdzono ostatnio w dokumentacji Cursora 2026-08-28.

Nie poszerzaj uprawnień, żeby ratować kandydata

Jeśli narzędzie nie potrafi dokończyć zadania we wspólnej granicy, zapisz to jako wynik. Danie jednemu kandydatowi --dangerously-skip-permissions, --dangerously-bypass-approvals-and-sandbox albo produkcyjnych poświadczeń sprawia, że próba mierzy granicę, a nie harness. Te flagi należą wyłącznie do jednorazowego sandboxa z ograniczoną siecią.

Prompty do skopiowania na czas próby

Prompty są takie same we wszystkich narzędziach, więc różnice w wyniku pochodzą z harnessu. Wklej je w okno promptu agenta.

Prompt do skopiowania: audyt gotowości harnessu (tylko odczyt)

Do not edit any file. Audit this repository as a harness for coding agents.
Report, with file paths as evidence:
1. Which instruction files exist (AGENTS.md, CLAUDE.md, Cursor Rules) and
   whether they name one exact check command.
2. Whether that check command runs green right now. Run it and paste the tail.
3. Paths an agent must never edit (migrations, generated code, secrets, CI).
4. Credentials or production endpoints reachable from this shell's environment.
5. The three gaps that would stop an agent's diff from being verified by CI alone.
End with a proposed AGENTS.md diff, but do not apply it.

Prompt do skopiowania: tylko plan, stop do zatwierdzenia

Read the repository instructions and trial/task-1/intent.md. Do not edit code.
Write plan.md with: the exact files you will change and why, assumptions,
risks, a rollback step, the tests you will add or change, and the command
whose output proves the task is done. List anything in intent.md you find
ambiguous as a question instead of guessing. Stop after writing plan.md.

Prompt do skopiowania: wykonanie zaakceptowanego planu z dowodami

Execute plan.md exactly. Change only the files it lists; if you need another
file, stop and explain why instead of editing it. Run the repository check
command after each logical step and fix what fails. When done, report:
the final check command output, `git diff --stat`, every deviation from
plan.md, and anything a human must decide before merge. Do not commit.

Prompt do skopiowania: porównanie przebiegów próby

Read trial/record.yaml and the draft pull requests it links. Do not edit.
For each candidate harness, compute: tasks accepted by CI and hidden tests,
human corrections per task, review minutes per task, and cost per accepted
task. Flag any run that used a wider permission boundary than the others,
and any metric with fewer than three data points. Recommend a primary
harness only if one candidate leads on accepted tasks; otherwise say which
extra task would separate them.

Jak zweryfikować przebieg próby bez czytania każdej linii?

O akceptacji decydują grader i CI. Człowiek czyta dowody, nie diff:

• CI jest rozstrzygające. Agent uruchamia polecenie sprawdzające w trakcie sesji, ale liczy się wynik z CI. To działa tylko wtedy, gdy agent nie może zmienić pipeline’u: przy pull_request GitHub uruchamia plik workflow z samego pull requesta, więc każda zmiana w .github/ wykracza poza zakres zadania próbnego, a /.github/ powinien być objęty CODEOWNERS z wymaganą akceptacją właściciela kodu. Ukryte testy leżą poza worktree agenta, dopóki nie uruchomi ich CI.
• Kontrola zakresu łapie ciche rozrastanie się zmian. Uruchom ją na każdym draft pull requeście:

# Terminal, in the run's worktree: flag files the plan did not name
git diff --name-only main...HEAD | while read -r f; do
  case "$f" in plan.md|*/plan.md|intent.md|*/intent.md) continue;; esac
  grep -qF "$f" plan.md || echo "OUT OF PLAN: $f"
done

• Raport z dowodami porównujesz z planem. Każde odstępstwo zgłoszone przez agenta musi zaakceptować owner zadania albo trzeba je wycofać.
• Agent recenzent czyta diff pierwszy. Uruchom review wbudowany w narzędzie (/code-review w Claude Code, codex review --base main w Codeksie, Bugbot w Cursorze), a człowiek czyta tylko uwagi oznaczone jako ważne. Konfigurację opisuje warstwowy review pull requestów.
• Owner zadania podpisuje akceptację. Owner wskazany w intent.md akceptuje wynik; tech lead podpisuje decyzję o harnessie.

Każdy przebieg zapisuj w jednym arkuszu. Wartości poniżej to wypełniacze pokazujące kształt.

trial/record.yaml

date: 2026-09-26
tasks: [task-1-bugfix, task-2-flagged-feature, task-3-refactor]
boundary: workspace writes, no network, no production credentials
candidates:
  - harness: claude-code 2.1.283 (latest), default model, CLAUDE.md -> @AGENTS.md
    accepted_by_ci_and_hidden_tests: 3/3
    out_of_plan_files: 0
    human_corrections_per_task: 1
    review_minutes_per_task: 12
    cost_per_accepted_task_usd: 2.10
  - harness: codex 0.157.1, default model, AGENTS.md, profile :workspace
    accepted_by_ci_and_hidden_tests: 2/3
    out_of_plan_files: 1
    human_corrections_per_task: 2
    review_minutes_per_task: 18
    cost_per_accepted_task_usd: 1.60
decision: primary harness = <tool>; re-run trial on 2026-12-26 or on a major release
signed_off_by: tech lead, 2026-09-26

Reguła decyzji. Szereguj najpierw według zaakceptowanych zadań. Wśród kandydatów z równą akceptacją wybierz tego z mniejszą liczbą plików spoza planu i poprawek, potem z krótszym czasem review, a na końcu z niższym kosztem zaakceptowanego zadania. Tańszy przebieg, który trzeba powtórzyć, nie jest tańszy. Dobór planu i liczby miejsc to kolejne pytanie scorecardu: dobierz plan AI na podstawie zmierzonego obciążenia.

Co psuje się przy wyborze głównego harnessu?

Zespół ocenia kategorię produktu. Spór o terminal kontra edytor zastępuje pomiar. Wyjście: przypomnij sześć możliwości, uruchom te same trzy zadania w każdym kandydacie i pozwól zdecydować arkuszowi.

Agent edytuje, zanim zrozumie repozytorium. Kod pojawia się przed jakimkolwiek planem, a diff dotyka plików, których nikt się nie spodziewał. Wyjście: zaczynaj każde zadanie w trybie planu albo w Plan Mode, commituj plan.md i oznaczaj przebieg jako nieudany, gdy kontrola zakresu wypisze OUT OF PLAN.

Plik instrukcji nie jest czytany. Codex pomija projektowy AGENTS.md w niezaufanym projekcie (od 0.150.0), Claude Code czyta AGENTS.md tylko wtedy, gdy nie ma CLAUDE.md, i dopiero od v2.1.277 w sesjach first-party (v2.1.281 na Bedrocku, Google Cloud i Foundry), na obu kanałach wydań, odkąd stable doszedł do v2.1.287 (sprawdzone 2026-10-12), a Cursor dołącza reguły projektu z .cursor/rules (pliki .mdc) i obsługuje też AGENTS.md w katalogu głównym projektu i w podkatalogach (dokumentacja Cursora, sprawdzone 2026-10-12). Wyjście: przed pierwszym zadaniem zapytaj każdego agenta: „Które pliki instrukcji wczytałeś i jakie jest polecenie sprawdzające?” i poprawiaj setup, aż wszystkie trzy odpowiedzą tak samo.

Zielony test ukrywa zły wynik. Agent dopasował test do swojego kodu. Wyjście: trzymaj testy akceptacyjne poza worktree agenta, dopóki nie uruchomi ich CI, i powiąż każdy test z linią w intent.md.

Jeden kandydat działał z szerszymi uprawnieniami. Ukończył więcej zadań, bo mógł sięgnąć dalej. Wyjście: odrzuć jego przebiegi, przywróć wspólną granicę i powtórz próbę. „Nie potrafi skończyć w granicy” zapisz jako wynik.

Decyzja nigdy nie wygasa. Harness wybrany w maju nadal jest główny we wrześniu, po trzech dużych wydaniach. Wyjście: datuj zapis decyzji, powtarzaj trzy zadania przy każdym dużym wydaniu głównego narzędzia albo co kwartał i trzymaj instrukcje w AGENTS.md, żeby zmiana narzędzia kosztowała jedną linię importu.

Czy twój setup osiąga maksymalną odpowiedź w Q1?

• Jeden plik instrukcji wskazuje dokładne polecenie sprawdzające i zmienia się wyłącznie przez pull requesty.
• Nietrywialna praca zaczyna się od intent.md i zaakceptowanego plan.md zacommitowanego przed kodem.
• Przebiegi działają w jawnej granicy uprawnień, bez produkcyjnych poświadczeń w środowisku.
• Praca równoległa lub ryzykowna działa we własnym worktree albo środowisku w chmurze.
• CI ponownie uruchamia polecenie sprawdzające i ukryte testy na każdym pull requeście agenta.
• Datowany zapis decyzji wskazuje główny harness, dowody z próby i datę kolejnej próby.

Dokąd dalej po wyborze głównego harnessu

Mapa narzędzi Funkcja realizująca każdy etap cyklu w Claude Code, Codeksie i Cursorze.

Dobierz plan AI do zmierzonego obciążenia Scorecard Q2: zamień dane o kosztach z próby na wybór planu i liczby miejsc.

Wybierz agenta kodującego Czym różnią się trzy narzędzia i jak porównać je na podstawie dowodów.

Cykl AI-native Wspólny cykl, który realizuje każdy harness, etap po etapie.

Potem otwórz adapter wybranego harnessu: Claude Code, Codex albo Cursor.