## Harness agenta kodującego

*Agenci*

*Ostatnia zmiana: 28 września 2026*

Agent kodujący to model plus harness, czyli wszystko wokół modelu, co robi z niego działającego agenta. Model proponuje następny krok, a harness decyduje, co model widzi, co naprawdę się wykona i co da się cofnąć.

**Po ludzku:** Doświadczony fachowiec na budowie. Umiejętności ma swoje, ale resztę ustala budowa: jakie narzędzia leżą na stole, co jest w zleceniu i regulaminie, które pomieszczenia są zamknięte, kto musi się podpisać, zanim wyburzy się ścianę, i czy jest poziomica, żeby sprawdzić robotę. Ten sam fachowiec na dobrze zorganizowanej budowie i w chaosie pracuje zupełnie inaczej.

*Interaktywny widżet na stronie: Odtwórz jedno zadanie w agencie kodującym: zwroty częściowe są o 1 grosz za małe. Wyłącz jedną część harnessu, naciśnij ▶ i zobacz, co się zmienia.*

### Z czego składa się harness

- Pętla z tematu „Pętla agenta” i kilka ogólnych narzędzi: odczyt pliku, edycja przez podmianę fragmentu tekstu, komenda w powłoce, wyszukiwanie przez grep i glob. Harness waliduje każde wywołanie, wykonuje je i przycina długie wyniki: Claude Code zapisuje wynik z MCP powyżej 25 tys. tokenów do pliku i podaje modelowi ścieżkę (szczegóły Claude Code i Codex na tej stronie według stanu na wrzesień 2026).
- Instrukcje. System prompt opisuje narzędzia i zasady pracy, a na starcie każdej sesji harness wczytuje plik pamięci projektu. AGENTS.md to otwarty format, który czytają Codex, Cursor, Copilot, Jules i inne. Claude Code czyta CLAUDE.md, a AGENTS.md wtedy, gdy CLAUDE.md nie ma. Taki plik to kontekst, nie konfiguracja: model zwykle go słucha, ale nic go do tego nie zmusza.
- Planowanie. Model pisze listę zadań i je odhacza, a harness przy każdej zmianie wstawia listę na koniec kontekstu, żeby cel nie utonął w środku długiej historii. W trybie planowania agent może tylko czytać i uruchamiać komendy tylko do odczytu, dopóki nie zaakceptujesz planu.
- Zarządzanie kontekstem, opisane w temacie „Context engineering i pamięć”: czyszczenie starych wyników narzędzi, kompakcja po przekroczeniu progu i subagenci, którzy szukają we własnym oknie i oddają streszczenie. Dwa mechanizmy trzymają materiał poza oknem, dopóki nie jest potrzebny. Wyszukiwanie narzędzi zostawia w prefiksie same nazwy, a pełne definicje ładuje na żądanie; w Claude Code to ustawienie domyślne. Agent Skills, otwarty format, to katalogi z plikiem SKILL.md: w prefiksie siedzą tylko nazwa i opis, a treść dochodzi, gdy zadanie do niej pasuje (progressive disclosure).
- Uprawnienia decydują, które wywołania czekają na człowieka. W Claude Code odczyty i komendy tylko do odczytu, jak `ls`, `grep` czy `git status`, idą bez pytania, a pozostałe komendy powłoki i edycje domyślnie wymagają zgody. Do wyboru są tryby od planowania, przez akceptowanie edycji i tryb auto (każdą akcję ocenia klasyfikator), po bypass. Ograniczenia sandboksa egzekwuje system operacyjny (Seatbelt w macOS, bubblewrap w Linuksie): zapis tylko w katalogu roboczym, sieć tylko przez proxy z listą dozwolonych domen. Codex w domyślnym trybie workspace-write ma sieć wyłączoną. Potrzebne są obie warstwy: bez izolacji sieci przejęty agent wyśle twoje klucze SSH, a bez izolacji plików podrzuci coś, co później otworzy mu sieć.
- Hooki to twoje komendy w stałych punktach pętli: przed wywołaniem narzędzia (mogą je zablokować), po edycji (formatter), gdy agent chce skończyć (testy). Wykonują się zawsze, w odróżnieniu od instrukcji, którą model może pominąć. W Claude Code hook, który odrzuca wywołanie, blokuje je nawet w trybie bypass. Serwery MCP dokładają narzędzia z zewnątrz (temat „MCP”).
- Checkpointy. Claude Code zapisuje stan plików przed każdym twoim poleceniem, a `/rewind` przywraca kod, rozmowę albo jedno i drugie. Nie śledzi plików zmienionych komendami powłoki, jak `rm` czy `mv`, ani skutków poza twoim komputerem, więc prawdziwym „cofnij” zostaje git.

### Ten sam model, inny harness

- SWE-bench i Terminal-Bench mierzą model razem z harnessem. Anthropic pisał w styczniu 2025, że wyniki mocno zależą od harnessu nawet przy tym samym modelu. LangChain (luty 2026, raport o własnym produkcie) zostawił ten sam GPT-5.2-Codex i zmienił tylko system prompt, narzędzia i hooki, w tym wykrywanie pętli i listę kontrolną wymuszającą weryfikację przed końcem: wynik w Terminal-Bench 2.0 wzrósł z 52,8% do 66,5%. Działa to też w drugą stronę: wiosną 2026 trzy zmiany w Claude Code na kilka tygodni pogorszyły działanie tych samych modeli (temat „Czy model głupieje?”). Więcej maszynerii nie znaczy automatycznie lepiej: mini-SWE-agent, ok. 100 linijek Pythona z powłoką jako jedynym narzędziem, według autorów przekracza 74% w SWE-bench Verified. Wynik z rankingu opisuje parę model–harness, więc modele porównuj we własnym harnessie, na własnych zadaniach.
- Od harnessu zależy też większość rachunku. Każda tura wysyła cały kontekst od nowa, a w agentach tokenów wejściowych jest ok. 100 razy więcej niż wyjściowych. Dlatego harness układa request od części najstabilniejszej do najbardziej zmiennej: system prompt z definicjami narzędzi, potem pamięć projektu, potem rozmowa, która rośnie tylko na końcu. Odczyt z cache’u kosztuje ok. 10% ceny wejścia, a jedna zmiana blisko początku prefiksu sprawia, że cała historia znowu kosztuje pełną cenę (temat „Prompt caching”). Z tego powodu Claude Code dopisuje tryb planowania i skille jako wiadomości, a zmianę w CLAUDE.md stosuje dopiero po `/clear`, `/compact` albo restarcie, za to zmiana modelu czy kompakcja przebudowuje cache.

### Jak pracować z agentem kodującym

- Źródłem prawdy jest weryfikacja. Daj agentowi testy, sprawdzanie typów, linter i build, które uruchomi sam, najlepiej przez szybki cel w rodzaju `make test-fast`. „Gotowe” agenta to deklaracja, a kod wyjścia to fakt.
- AGENTS.md ma być krótki i konkretny: komendy do budowania, testów i lintera, konwencje, których nie widać w kodzie, i to, czego nie ruszać. Dokumentacja Claude Code radzi mniej niż 200 linii, bo dłuższy plik zjada kontekst i model słabiej się go trzyma. Reguły, które muszą obowiązywać, idą do uprawnień i hooków, nie do prozy.
- Plan przed edycją i wąskie zadanie: jeden błąd albo jedna funkcja na sesję, z jasnym kryterium końca, i czysty kontekst między niepowiązanymi zadaniami.
- Przeglądaj diff, nie podsumowanie. Przed większą zmianą zrób commit, żeby każdą edycję agenta dało się cofnąć jedną komendą.
- Poziom uprawnień dobieraj do ryzyka: tryb tylko do odczytu albo planowania w nieznanym repozytorium, akceptowanie edycji w sandboksie na co dzień, a pełna autonomia (bypass, danger-full-access) tylko w kontenerze albo maszynie wirtualnej bez sekretów i dostępu do produkcji.

### Typowe awarie agentów kodujących

- Zgubiony cel: po kilkudziesięciu turach zadanie z pierwszej wiadomości leży w środku kontekstu albo w streszczeniu. Pomagają lista zadań, notatki w plikach i krótsze sesje.
- Edycje bez testów: w trace’ach LangChain najczęstszą awarią był agent, który napisał rozwiązanie, przeczytał je jeszcze raz i skończył, niczego nie uruchamiając, a Anthropic (listopad 2025) widział agentów oznaczających funkcje jako gotowe bez testu end-to-end. Pomaga hook, który przed końcem pracy uruchamia testy.
- Context rot: jakość spada, gdy historia wypełnia się logami i starymi odczytami plików, na długo przed końcem okna (temat „Okno kontekstowe i agent”). Kompaktuj w naturalnych przerwach między zadaniami, a wyszukiwanie oddawaj subagentom.
- Prompt injection: README, komentarz w kodzie, zgłoszenie, dokumentacja zależności albo strona WWW to tekst w tym samym kontekście co twoje instrukcje (temat „Prompt injection”). W maju 2025 Invariant Labs pokazało zgłoszenie w publicznym repozytorium, przez które Claude 4 Opus z serwerem MCP GitHuba przeczytał prywatne repozytorium i opublikował jego zawartość w publicznym pull requeście. Obrona leży w harnessie: zgoda na akcje, lista dozwolonych adresów w sieci i tokeny o minimalnym zakresie.
- Koszt bez hamulca: agent ponawiający tę samą poprawkę, rozmnażający się subagenci, dziesiątki narzędzi ładowanych z góry, prefiks, który ciągle się zmienia. Ustaw w harnessie limity tur i budżetu i patrz na stosunek odczytów z cache’u do zapisów.

### Sprawdź się

**Pytanie:** Co harness dokłada do modelu w agencie kodującym i czemu ten sam model wypada różnie w dwóch harnessach?

**Krótka odpowiedź:** Harness to wszystko wokół modelu, co robi z niego agenta: pętla, kilka ogólnych narzędzi (odczyt, edycja, powłoka, wyszukiwanie), system prompt i plik projektu, np. AGENTS.md, lista zadań, zarządzanie kontekstem (czyszczenie starych wyników, kompakcja, subagenci, wyszukiwanie narzędzi), skille ładowane na żądanie, uprawnienia i sandbox, hooki oraz checkpointy. Model tylko proponuje wywołania, a harness decyduje, co model widzi, co się wykona i co da się cofnąć. Dlatego narzędzia, prompty i pętla weryfikacji zmieniają wyniki: LangChain podaje 13,7 punktu więcej w Terminal-Bench 2.0 po zmianie samego harnessu. Harness trzyma też stały prefiks pod prompt caching, a od tego zależy większość rachunku.

### Pytania pogłębiające

- **Czemu „nigdy nie rób git push” w AGENTS.md cię nie chroni?** Plik to kontekst, nie konfiguracja. Model zwykle go słucha, ale długa sesja, niejasne polecenie albo wstrzyknięty tekst mogą przeważyć. Regułę, która musi obowiązywać, egzekwuje harness: reguła deny, hook blokujący wywołanie przed wykonaniem (w Claude Code działa nawet w trybie bypass), sandbox albo token bez prawa do push.
- **Sandbox jest włączony. Jak agent może zniszczyć twoją pracę?** Sandbox ogranicza zapis do katalogu roboczego, a sieć do dozwolonych domen, i repozytorium leży w tych granicach, więc git clean -fdx albo rm -rf src przejdą. Checkpointy Claude Code nie śledzą zmian robionych komendami powłoki. Pomagają częste commity, reguła ask albo deny dla komend niszczących i osobny worktree lub kontener do ryzykownych zadań.
- **Agent melduje sukces, a CI pada. Co zmieniasz w harnessie?** Szybkie sprawdzenie, które agent uruchomi sam, z komendą wpisaną w AGENTS.md. Hook na moment, gdy agent chce skończyć: uruchamia testy i odsyła błędy modelowi jako informację zwrotną. Wynik ocenia się po kodzie wyjścia i diffie, nie po podsumowaniu. Anthropic i LangChain opisują przedwczesne „gotowe” jako jedną z najczęstszych awarii agentów kodujących.
- **Po podłączeniu trzech serwerów MCP koszt się podwoił. Czemu i co robisz?** Definicje narzędzi siedzą w prefiksie, więc płacisz za nie w każdej turze, a w harnessie, który ładuje je z góry, podłączenie serwera w trakcie sesji unieważnia cache. Pomagają wyszukiwanie narzędzi (w prefiksie zostają same nazwy), tylko serwery potrzebne do zadania i stały zestaw narzędzi przez całą sesję. Skutek sprawdza się w usage: stosunek odczytów z cache’u do zapisów.
- **Kiedy subagent jest lepszy niż praca w głównej sesji?** Przy zadaniach pobocznych, które polegają głównie na czytaniu: przeszukanie repozytorium, lektura logów, przegląd diffu. Subagent zużywa tokeny we własnym oknie i oddaje krótkie streszczenie, więc główny kontekst zostaje krótki. Edycje zależne od decyzji z głównego wątku zostają w głównej sesji, bo subagent tych decyzji nie widzi, a w Claude Code jego edycje zwykle nie trafiają do checkpointów. Łącznie subagenci zużywają więcej tokenów, nie mniej.

### Źródła

- [Sebastian Raschka: Components of a Coding Agent (kwiecień 2026)](https://magazine.sebastianraschka.com/p/components-of-a-coding-agent)
- [Anthropic: Effective harnesses for long-running agents (2025)](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Dokumentacja Claude Code: How Claude Code uses prompt caching](https://code.claude.com/docs/en/prompt-caching)
- [Dokumentacja OpenAI Codex: Agent approvals and security](https://learn.chatgpt.com/docs/agent-approvals-security)
- [LangChain: Improving Deep Agents with harness engineering (2026)](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering)

Strona interaktywna: https://howaiworks.dev/pl/harness/