Strona główna / Rozdział 5 · Agenci
Ostatnia zmiana 28 września 2026 · 9 min czytania

Harness agenta kodującego

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

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

tura agenta

tokenów w tym wywołaniu

tokenów wejściowych od startu

Liczby poglądowe: okno 200 tys. tokenów, system prompt z wbudowanymi narzędziami 12 tys., pamięć projektu 3 tys., ok. 5 tys. tokenów historii na turę, kompakcja przy 80% okna, 50 tys. za definicje wszystkich narzędzi MCP ładowane z góry. Własne tokeny subagenta nie są wliczone. Repozytorium, komendy i zachowanie modelu są zmyślone, żeby pokazać typowe awarie.

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ę

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

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.

In English

A harness is everything around the model that makes it an agent: the loop, a few general tools (read, edit, shell, search), the system prompt and a project file such as AGENTS.md, a todo list, context management (clearing old results, compaction, subagents, tool search), skills loaded on demand, permissions and a sandbox, hooks and checkpoints. The model only proposes calls; the harness decides what the model sees, what runs and what can be undone. So tools, prompts and a verification loop move scores: LangChain reports 13.7 more points on Terminal-Bench 2.0 after changing only the harness. The harness also keeps the prefix stable for prompt caching, which largely determines the bill.

Pytania pogłębiające (5)

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

Zgłoś błąd · Zaproponuj poprawkę