Przejdź do głównej zawartości

Harness: wszystko, w czym pracuje agent

Harness to wszystko, w czym pracuje agent kodujący, poza samym modelem: kontekst, który czyta, narzędzia, które może wywołać, uprawnienia i sandbox, które go ograniczają, hooki sprawdzające jego działania, skille i pluginy, które ładuje, oraz środowisko, w którym się wykonuje. Każda warstwa zapobiega jednej klasie błędów, dlatego harness wersjonuje się, recenzuje i ewaluuje jak kod.

W zeszłym tygodniu twój agent wykonał git push --force, choć CLAUDE.md wielkimi literami tego zabrania. Agent kolegi formatuje pliki inaczej niż twój i nikt nie potrafi powiedzieć, które z 400 linii reguł są jeszcze aktualne. Każda dotychczasowa poprawka to kolejne zdanie w pliku reguł. Ta strona przypisuje każdy z tych problemów do warstwy, która naprawdę potrafi go zatrzymać.

  • Mapę siedmiu warstw: przed jakim błędem chroni każda i gdzie się znajduje w Claude Code, Codex i Cursorze.
  • Tabelę decyzyjną, która mówi, do której warstwy należy poprawka, żeby powtarzający się błąd nie zamieniał się w kolejną regułę.
  • Procedurę w pięciu krokach: harness w repozytorium, code review, walidacja w CI i ewaluacja zmian względem punktu odniesienia.
  • Trzy prompty do skopiowania: inwentaryzacja harnessu, skierowanie powtarzającego się błędu do właściwej warstwy i zbudowanie małego zestawu ewaluacji.
  • Tryby awarii samego harnessu, od po cichu ignorowanych ustawień po pliki reguł, które sobie przeczą.
  • Kolejność lektury ponad 20 stron o harnessie, rozrzuconych po pięciu sekcjach serwisu.

Ten sam model zachowuje się różnie w różnych harnessach. Publiczne benchmarki już dziś oceniają parę, a nie sam model: każdy wpis na oficjalnym leaderboardzie Terminal-Bench 4.0 podaje model i harness agenta, na przykład Claude Fable 5.1 (wysiłek max) z Claude Code: 57,9% ± 3,8 (leaderboard odczytany 2026-09-26). Twoje repozytorium dokłada własne warstwy do warstw dostawcy i to właśnie nimi sterujesz.

#WarstwaCo zawieraPrzed jakim błędem chroniEgzekwowanie
1KontekstInstrukcje projektu (CLAUDE.md, AGENTS.md, Rules w Cursorze), pamięćAgent na nowo odgaduje twoje konwencje, wymyśla komendę testów albo używa wzorca, z którego zrezygnowaliścieRada: model może ją zignorować
2NarzędziaSerwery MCP, CLI, subagenciAgent zgaduje na podstawie danych treningowych, jak wygląda twój schemat bazy, zgłoszenia albo aktualne API bibliotekiMożliwości: do czego agent ma dostęp
3Uprawnienia i sandboxTryby uprawnień, reguły allow/ask/deny, polityki zatwierdzania, sandbox systemu operacyjnego, ruch wychodzącyDziałania destrukcyjne lub nieodwracalne, odczyt sekretów, zapis poza przestrzenią robocząTwarde: odmawia klient albo system
4HookiSkrypty uruchamiane przy zdarzeniach cyklu życia (przed wywołaniem narzędzia, po edycji, na zakończenie)Reguła zapomniana w połowie sesji: niesformatowany kod, edycja chronionej ścieżki, „gotowe” bez testówDeterministyczne: kod wykonuje się zawsze
5SkilleProcedury ładowane na żądanie (SKILL.md plus skrypty)Ta sama procedura za każdym razem wykonana inaczej albo stałe reguły rozdymające każdą sesjęRada, ładowana tylko wtedy, gdy potrzebna
6PluginyInstalowalne pakiety skilli, hooków, subagentów i serwerów MCPOśmiu programistów z ośmioma rozjeżdżającymi się kopiami harnessuDystrybucja: jedno wersjonowane źródło
7ŚrodowiskaWorktree, kontenery, środowiska chmurowe, dane startowe, bloki portówRównolegli agenci psujący sobie nawzajem stan, weryfikacja działająca tylko na jednym laptopie, duży promień rażeniaIzolacja: osobny stan dla każdego uruchomienia

Dwie rzeczy stoją obok harnessu, a nie w nim. Baza kodu (repozytorium) decyduje, czy sprawdzenie może zastąpić czytanie: testy uruchamiane jedną komendą, ścisłe typy, wyraźne granice modułów (zobacz jak przygotować repozytorium do pracy agentów). Wyrocznia to zestaw testów i bramek, który decyduje o „gotowe”, i agent nie może mieć możliwości jej edytowania (zobacz ochronę wyroczni). Jedna mapa umieszcza harness jako jedną z sześciu stacji fabryki.

Przeczytaj ostatnią kolumnę tabeli od góry do dołu. Kontekst to prośba, hook to kod, a sandbox to ściana. Zdanie w AGENTS.md „nigdy nie czytaj .env” działa przez większość czasu; reguła deny albo sandbox, który nie sięga do pliku, działa zawsze. Stąd zasada dla całej sekcji: umieszczaj każdą kontrolę w najbardziej deterministycznej warstwie, która potrafi ją wyrazić, a kontekst zostaw na to, co da się powiedzieć tylko zdaniem: konwencje nazewnictwa, intencję architektury, położenie rzeczy w repozytorium.

Ta sama logika wyznacza granice każdej warstwy. Reguła deny dla komend porównuje tekst komendy, który pisze agent, więc to samo działanie zapisane inaczej (sh -c '…', skrypt w package.json, cel w Makefile) może się prześlizgnąć. Traktuj reguły wzorców jak zabezpieczenie przed literówkami. Prawdziwą granicą jest to, do czego proces ma dostęp: sandbox systemu, ruch wychodzący i to, jakie poświadczenia w ogóle istnieją w środowisku. Klucza do wdrożeń produkcyjnych, którego nie ma na maszynie, żaden prompt nie wykorzysta.

Kiedy agent drugi raz popełnia ten sam błąd, odruchem jest dopisanie zdania do pliku reguł. Zamiast tego użyj tej tabeli. Prawa kolumna to dowód, że poprawka działa.

ObjawGdzie umieścić poprawkęDowód, że działa
Uruchamia npm test, a repozytorium używa pnpm test:unitKontekst: jedna linia z nazwą komendyNastępna sesja uruchamia właściwą komendę bez przypominania
Edytuje pliki generowane lub vendorowaneUprawnienia (deny dla zapisu w ścieżce) plus hook przed wywołaniem narzędziaPróbna edycja ścieżki zostaje zablokowana z czytelnym powodem
Mówi „gotowe”, nie uruchomiwszy testówHook na zakończenie albo warunek celu, który uruchamia sprawdzenieSesja z nieprzechodzącym testem nie może się zakończyć
Czyta .env lub inne sekretySandbox i uprawnienia; prawdziwe sekrety trzymaj poza przestrzenią robocząPróbę odczytu odrzuca klient albo system
Mógłby wdrożyć albo zapisać na produkcjiŚrodowisko: żadnych poświadczeń produkcyjnych na maszynie; wdrożenia to zadanie CIPoświadczenie nie istnieje tam, gdzie działa agent
Za każdym razem inaczej przechodzi checklistę wydaniaSkill z checklistą i skryptemTrzy uruchomienia dają te same artefakty w tej samej kolejności
Zgaduje schemat bazy danychNarzędzie: serwer MCP bazy albo CLI w trybie tylko do odczytuZapytania w transkrypcie zgadzają się z prawdziwym schematem
Dwaj równolegli agenci psują sobie serwer deweloperskiŚrodowisko: jedno worktree i jeden blok portów na agentaOba uruchomienia przechodzą, działając jednocześnie
Twój harness różni się od harnessu kolegiPlugin albo zacommitowane ustawienia projektuŚwieży klon daje ten sam wynik /context (Claude Code) albo ten sam stos warstw w /debug-config (Codex)
Reguła jest ignorowana pod koniec długich sesjiPrzenieś ją z kontekstu do hookaHook pojawia się w transkrypcie za każdym razem

Gdzie znajduje się każda warstwa w Claude Code, Codex i Cursorze?

Dział zatytułowany „Gdzie znajduje się każda warstwa w Claude Code, Codex i Cursorze?”

Wszystkie trzy narzędzia implementują każdą warstwę, ale z innymi nazwami plików i innymi zasadami zaufania. Procedura z tej strony jest taka sama dla wszystkich trzech; różnią się lokalizacje.

Sprawdzone na Claude Code 2.1.283 (kanał latest).

  • Kontekst: CLAUDE.md plus auto memory. Claude Code czyta AGENTS.md, gdy projekt nie ma CLAUDE.md (od v2.1.277; 2026-09-26 tylko w kanale latest).
  • Narzędzia: serwery MCP projektu w .mcp.json (niezatwierdzone serwery czekają na twoją zgodę i nie są łączone), claude mcp add i subagenci w .claude/agents/.
  • Uprawnienia i sandbox: reguły permissions allow, ask i deny w .claude/settings.json; tryby uprawnień (Manual, acceptEdits, plan, auto, dontAsk, bypassPermissions); sandboksowany Bash na macOS, Linuksie i WSL2. auto i bypassPermissions ustawione jako defaultMode w ustawieniach projektu są ignorowane: należą do ustawień użytkownika albo zarządzanych.
  • Hooki: blok hooks w dowolnym pliku ustawień; 33 zdarzenia, typy handlerów command, http, mcp_tool, prompt i agent (eksperymentalny).
  • Skille: .claude/skills/<nazwa>/SKILL.md.
  • Pluginy: claude plugin install, marketplace’y i enabledPlugins w ustawieniach.
  • Środowiska: --worktree, środowiska chmurowe, środowiska self-hosted.

Kolejność pierwszeństwa, od najwyższego: ustawienia zarządzane, argumenty wiersza poleceń, .claude/settings.local.json, .claude/settings.json, ~/.claude/settings.json. Commituj .claude/settings.json; osobiste nadpisania trzymaj w pliku lokalnym, który zostaje poza gitem.

{
"permissions": {
"deny": ["Read(./.env)", "Read(./.env.*)", "Bash(git push *)"],
"ask": ["Bash(pnpm publish *)"]
},
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": ".claude/hooks/protect-generated.sh" }]
}
]
}
}

Plik harnessu zmienia zachowanie każdej przyszłej sesji, więc jego zmiana zasługuje na takie samo traktowanie jak zmiana współdzielonej biblioteki. Poniższa procedura działa we wszystkich trzech narzędziach.

  1. Trzymaj harness w repozytorium. Commituj instrukcje projektu, ustawienia projektu, hooki i ich skrypty, skille oraz listę serwerów MCP. Osobiste nadpisania (.claude/settings.local.json, twoja konfiguracja użytkownika) zostają poza gitem. Świeży klon powinien dać nowej osobie w zespole ten sam harness, który masz ty.

  2. Daj plikom harnessu właściciela. Dopisz ścieżki do CODEOWNERS: AGENTS.md, CLAUDE.md, .claude/, .codex/, .mcp.json, skrypty hooków oraz .github/ (workflowy, które uruchamiają sprawdzenia z kroku 3). Sam CODEOWNERS tylko prosi o przegląd; scalenie blokuje dopiero wtedy, gdy reguła ochrony gałęzi domyślnej albo ruleset ma włączone „Require review from Code Owners”. W jednym zespole właścicielem jest zwykle tech lead; model operacyjny opisuje, kto odpowiada, gdy kilka zespołów dzieli jeden harness.

  3. Waliduj konfigurację w CI. Zepsuta konfiguracja najłatwiej ukrywa się w uruchomieniach bez interfejsu. Zadanie CI może przerwać build, zanim wystartuje jakikolwiek agent, a każde sprawdzenie poniżej działa w trybie fail-closed: narzędzie, które się wywróci albo nic nie wypisze, oblewa zadanie, zamiast je przepuścić.

    Okno terminala
    # CI, z katalogu głównego repozytorium. Nie wymaga klucza API ani codex login.
    set -euo pipefail
    claude doctor > doctor.txt 2>&1 || true; cat doctor.txt
    grep -q '^Claude Code doctor' doctor.txt || { echo 'claude doctor did not run'; exit 1; }
    if grep -q 'Invalid settings' doctor.txt; then echo 'Invalid Claude Code settings'; exit 1; fi
    jq -e '.permissions.deny | length > 0' .claude/settings.json # reguły deny, na których polegasz, naprawdę tam są
    claude plugin validate --strict .claude/skills # tylko skille; powtórz dla .claude/agents, jeśli istnieje
    export CODEX_HOME="$(mktemp -d)" # jednorazowy katalog Codex: bez logowania i konfiguracji użytkownika
    printf '[projects."%s"]\ntrust_level = "trusted"\n' "$(pwd -P)" > "$CODEX_HOME/config.toml" # zaufaj temu checkoutowi, żeby .codex/config.toml się wczytał
    codex doctor --json > codex-doctor.json || true
    jq -e '(.checks[] | select(.id == "config.load") | .status == "ok")
    and ([.checks[] | select(.id | test("^(config|sandbox|mcp)\\.")) | .status] | all(. != "fail"))' codex-doctor.json

    claude doctor czyta ustawienia projektu bez pytania o zaufanie i wypisuje nieprawidłowe wartości i błędne typy w sekcji „Invalid settings”; nieznanego ani błędnie zapisanego klucza nie zgłasza (sprawdzone w 2.1.283 i 2.1.287). Nawet wtedy kończy się kodem 0, więc zadanie sprawdza jego wyjście, a pierwszy grep pilnuje, żeby brakujący albo wywrócony claude nie przeszedł jako „brak nieprawidłowych ustawień”. Linia z jq wyłapuje literówkę w kluczu deny, którą claude doctor przyjmuje bez słowa. claude plugin validate sprawdza skille, agentów i komendy, a nie ustawienia; uruchomione na katalogu .claude/, w którym jest tylko settings.json, kończy się błędem „No manifest found in directory”. codex doctor zwraca kod 1 zawsze, gdy nie przejdą sprawdzenia logowania lub sieci, a na runnerze bez logowania nie przejdą, dlatego zadanie czyta raport JSON i sprawdza tylko wyniki dla konfiguracji, sandboxa i MCP (Codex 0.157.1); pusty albo uszkodzony raport oblewa jq -e.

    Dwie linie przed codex doctor są obowiązkowe. Codex wczytuje .codex/config.toml tylko dla zaufanego projektu, a świeży runner nie ma wpisu o zaufaniu, więc bez nich codex doctor w ogóle nie czyta konfiguracji repozytorium i zgłasza config.load jako ok, nawet gdy pliku nie da się sparsować. Przekazanie zaufania przez -c tego nie zmienia; zmienia to dopiero wpis o zaufaniu w konfiguracji Codex (sprawdzone w 0.157.1). Wpis używa pwd -P, bo ścieżka przez dowiązanie symboliczne do niego nie pasuje. Zaufanie do checkoutu sprawia, że Codex wczytuje konfigurację projektu z samego pull requesta, więc uruchamiaj to zadanie tylko przy wyzwalaczu pull_request, nigdy przy pull_request_target, i nie dawaj mu żadnych sekretów.

    Przy wyzwalaczu pull_request GitHub uruchamia plik workflowu z samego pull requesta, więc pull request, który zmienia .github/workflows/, może tak przerobić to zadanie, żeby przechodziło, niczego nie sprawdzając, na przykład zastępując jego kroki poleceniem exit 0. Ustaw to zadanie także jako wymagany status check: wtedy jego usunięcie zostawia sprawdzenie w stanie oczekiwania i blokuje merge. Powyższe sprawdzenie łapie pomyłki, nie manipulację; przed manipulacją chroni wymagany przegląd Code Ownera dla .github/ z kroku 2.

    W samym uruchomieniu agenta dodaj --strict-config do codex exec, żeby nierozpoznane pole w config.toml było błędem, a nie cichym brakiem efektu.

  4. Ewaluuj zmiany względem punktu odniesienia. Utrzymuj od 5 do 10 prawdziwych zadań z niedawnych pull requestów, każde z komendą sprawdzającą, która rozstrzyga zaliczenie. Uruchom je z obecnym harnessem i z proponowaną zmianą, a potem porównaj odsetek zaliczonych zadań, liczbę tur i tokenów. Dla harnessu spakowanego jako plugin Claude Code robi to za ciebie claude plugin eval: uruchamia przypadki ewaluacyjne pluginu, domyślnie dodaje ramię bazowe bez pluginu (--ablation with-without) i raportuje różnicę wyników. Plugin działa przy tym na twojej maszynie i z twoimi poświadczeniami, więc ewaluuj tylko pluginy, którym ufasz; pierwsze uruchomienie w niezaufanym katalogu pluginu prosi o potwierdzenie, a w CI odpowiada na nie --trust-plugin. Metodę opisuje strona o ciągłych ewaluacjach harnessu agentów.

  5. Zatwierdzaj wynik, nie diff. Właściciel akceptuje zmianę harnessu, gdy zestaw ewaluacji jest co najmniej tak zielony jak wcześniej, a koszt kontekstu nie urósł bez powodu. Zapisz wynik w pull requeście. To ten zapis pozwoli ci później spokojnie usunąć regułę.

Harness to oprogramowanie i psuje się jak oprogramowanie. Oto awarie, które pojawiają się najczęściej, gdy zespół zaczyna na nim polegać.

Ustawienia po cichu ignorowane w uruchomieniach bez interfejsu. W Claude Code -p pomija okno zaufania do katalogu, a „settings files that fail validation are silently ignored in this mode” (claude --help, 2.1.283). Literówka w .claude/settings.json może usunąć twoje reguły deny w CI, gdzie żadne okno z błędem cię nie ostrzeże. W Codex niezaufany projekt nie dostarcza AGENTS.md projektu (0.150.0), a hooki projektu wymagają zapisanego zaufania. Naprawa: niech CI przerywa build, gdy claude doctor zgłasza nieprawidłowe ustawienia albo gdy sprawdzenie jq nie znajduje reguł deny (krok 3), a pierwszym krokiem każdego zadania bez interfejsu niech będzie wypisanie konfiguracji, z którą ruszy: wyjścia claude doctor i jq . .claude/settings.json dla Claude Code oraz codex doctor --json i cat .codex/config.toml dla Codex.

Plik reguł rośnie, aż zaczyna sobie przeczyć. Każdy incydent dodaje linię, nikt żadnej nie usuwa, a agent wykonuje tę instrukcję, którą przeczytał ostatnią. Naprawa: przenieś reguły, które da się egzekwować, do hooków i uprawnień, procedury do skilli, a resztę przytnij protokołem ablacji i swoim zestawem ewaluacji.

Hook przepuszcza wszystko albo wszystko blokuje. Hook, który wywraca się na nieoczekiwanym wejściu, może przepuścić działanie; hook z szerokim matcherem może zablokować każdą edycję. Naprawa: trzymaj testy na przykładowych danych dla każdego hooka, blokuj przy błędzie (fail closed) tylko w bramkach bezpieczeństwa i oddziel formatery od bramek. Zobacz hooki jako deterministyczne zabezpieczenia.

Regułę deny da się obejść innym zapisem. Reguła zatrzymuje git push --force, a agent uruchamia skrypt, który robi push. Naprawa: przesuń granicę do sandboksa, ruchu wychodzącego i poświadczeń; zobacz uprawnienia, sandboksy i tryby zatwierdzania.

Domyślny model zmienił się pod tym samym harnessem. 2026-09-26 kanał stable Claude Code (2.1.274) nadal dawał stanowiskom Pro i Team Standard domyślnie Sonnet 5, podczas gdy kanał latest od v2.1.280 domyślnie używał Opus 5.5. Dwie osoby z identycznymi ustawieniami repozytorium mogą pracować na różnych modelach. Naprawa: w ustawieniach zarządzanych przypnij kanał przez autoUpdatesChannel: "stable", a dozwolone modele przez availableModels i enforceAvailableModels, a przed zmianą któregokolwiek ponownie uruchom zestaw ewaluacji. Aktualne wartości domyślne są w hubie modeli.

Zewnętrzny skill, plugin albo serwer MCP działa z twoimi uprawnieniami. Instalując go, oddajesz mu swoją powłokę, pliki i tokeny. Naprawa: instaluj z przejrzanego wewnętrznego marketplace’u, przypinaj wersje i najpierw czytaj kod. Zobacz bezpieczeństwo skilli i bezpieczeństwo MCP.

Nie wiesz, czy winny jest harness, czy model. Naprawa: uruchom zadanie ponownie bez dostosowań. claude --safe-mode startuje Claude Code z wyłączonymi CLAUDE.md, skillami, pluginami, hookami i serwerami MCP, a polityka zarządzana nadal obowiązuje; w Codex codex exec --ignore-user-config pomija twój osobisty config.toml. Jeśli przebieg bez dostosowań się udaje, szukaj winnej warstwy metodą bisekcji.

Dobry harness jest konieczny, ale niewystarczający. Wystąpienie Dexa Horthy’ego na AI Engineer World’s Fair w lipcu 2026 roku nosi tytuł „Harness Engineering is not Enough: Why Software Factories Fail”. Harness czyni przebiegi przewidywalnymi; o tym, czy wynik jest poprawny, nadal decydują wyrocznia, dowody i code review.

Strony o harnessie są rozrzucone po pięciu sekcjach serwisu. Czytaj je w tej kolejności: najpierw ta sekcja, potem kontekst, potem warstwy z ekosystemu, a strony zespołowe i organizacyjne wtedy, gdy harness dzieli więcej niż jedna osoba.

WarstwaZacznij tutajPotem
KontekstZarządzanie kontekstemZwięzłe AGENTS.md i CLAUDE.md · Wspólne reguły agentów
NarzędziaSerwery MCPSubagenci o wąskim zakresie · Wewnętrzne serwery MCP
Uprawnienia i sandboxUprawnienia, sandboksy i tryby zatwierdzaniaPolityka zarządzana
HookiHooki jako deterministyczne zabezpieczeniaZarządzanie wspólnymi hookami
SkilleSkille agentówEkosystem skilli · Wspólne skille
PluginyPluginyMarketplace zespołu
ŚrodowiskaRównolegli agenci w worktreeŚrodowiska efemeryczne · Porównanie sandboksów dla agentów
EwaluacjaCiągłe ewaluacjeEwaluacje agentów kodujących