Szybka odpowiedź: czym jest harness engineering?
- Harness engineering to projektowanie środowiska wokół modelu AI, czyli danych, narzędzi, ograniczeń i kontroli, przez które przechodzi jego praca.
- Agent to model razem z harnessem, dlatego ten sam model w dwóch środowiskach daje bardzo różne wyniki.
- W tym artykule dzielę harness na trzy warstwy, czyli dane i kontekst, narzędzia i działania oraz kontrolę i walidację.
- Każdy powtarzający się błąd agenta powinien prowadzić do trwałej zmiany w środowisku, np. testem, blokadą albo nową regułą.
Co to jest harness engineering i co oznacza słowo harness?
Harness po angielsku oznacza uprząż, a inżynieria harnessu (harness engineering) to projektowanie wszystkiego, co otacza model językowy w systemie z . Skupia się na tym, skąd agent bierze dane, jakich narzędzi może użyć, czego mu nie wolno i jak sprawdzana jest jego praca. Sam model przetwarza dane wejściowe i generuje odpowiedzi, a odczyt pliku, zapytanie do API, uruchomienie testów czy wysłanie zmian do repozytorium dzieją się w oprogramowaniu, które go otacza.
Programiści znają pokrewne pojęcie test harness, czyli środowisko, które uruchamia testowany kod, podaje mu dane i sprawdza wynik. Harness agenta działa podobnie, tyle że zamiast funkcji obsługuje model, który sam decyduje o kolejnych krokach. Właśnie dlatego ten sam model potrafi w jednym projekcie pracować niezawodnie, a w innym narobić sporego bałaganu. Ostatecznie o skuteczności systemu decyduje to, jakimi danymi zasilono model i jakie mechanizmy go kontrolują.
Kto wymyślił harness engineering i skąd wziął się ten termin?
Sam termin jest stosunkowo świeży i wywodzi się od Mitchella Hashimoto (współzałożyciela HashiCorp, autora Terraform i Ghostty), który 5 lutego 2026 opisał na blogu swoją drogę do pracy z agentami AI. Piąty etap nazwał w swoim wpisie „Engineer the Harness”, a sama zasada jest dość prosta. Sprowadza się do tego, by za każdym razem, gdy agent popełnia błąd, poświęcać czas na takie zmiany w środowisku, żeby ten błąd już się nie powtórzył. Według Hashimoto to właśnie fundament pracy z AI. W tym samym artykule Hashimoto opisuje dwie formy takich poprawek: lepsze instrukcje w pliku AGENTS.md oraz zaprogramowane narzędzia, np. skrypty do zrzutów ekranu czy filtrowanego uruchamiania testów.
Sześć dni później, 11 lutego 2026 roku, OpenAI opublikowało artykuł Ryana Lopopolo z zespołu Codex. Autor opisał w nim, jak zaledwie trzech inżynierów w pięć miesięcy zbudowało wewnętrzny produkt, którego repozytorium liczyło około miliona linii kodu (wliczając testy, infrastrukturę i dokumentację). Choć z czasem zespół urósł do siedmiu osób, to niemal cały kod wygenerował Codex. Inżynierowie nie pisali kodu ręcznie. Projektowali środowisko, precyzowali cele i budowali pętle informacji zwrotnej.
Z kolei 10 marca 2026 roku Vivek Trivedy w publikacji LangChain zatytułowanej „The Anatomy of an Agent Harness” sprowadził tę dynamikę do prostego równania: Agent = Model + Harness.
Prompt engineering, context engineering i harness engineering: czym się różnią?
Te podejścia nie konkurują ze sobą, tylko nakładają się na siebie warstwami. Każde kolejne obejmuje poprzednie i dokłada do niego nowe pytanie:
- Prompt engineering, czyli jak sformułować polecenie,
- Context engineering, czyli co model powinien zobaczyć,
- Harness engineering, czyli czemu konkretnie system ma zapobiegać, co mierzyć i co korygować.
Dobry prompt oczywiście nadal ma znaczenie, ale to dopiero pierwszy krok. Agent, który wykonuje dziesiątki kroków i dotyka plików, baz danych czy zewnętrznych usług, potrzebuje czegoś więcej. Liczy się to, jakie dane agent zobaczy w każdym kroku, co może zrobić z ich pomocą i co zatrzyma go, zanim błąd dotrze do produkcji.
Z czego składa się harness agenta AI?
Harness najprościej opisać trzema warstwami, które porządkują to, co opisują Hashimoto, zespół Codex i LangChain.
| Warstwa | Za co odpowiada | Przykłady |
|---|---|---|
| Dane i kontekst | Fakty, których model nie ma w wagach | MCP, RAG, bazy wektorowe, zewnętrzne API, pliki instrukcji w repozytorium |
| Narzędzia i działania | Działanie poza rozmową | wywoływanie funkcji, uruchamianie kodu w piaskownicy, zapis plików |
| Kontrola i walidacja | Poprawność wyniku i przebieg całej pętli pracy | walidacja schematów (Zod, Pydantic), testy, limity, zatwierdzanie, logi |
W konkretnej dziedzinie warto te warstwy rozbić na nieco drobniejsze. W artykule o harness engineeringu w SEO dzielę kontrolę na ograniczenia, weryfikację i obserwowalność, ponieważ w przypadku pozycjonowania każda z nich wymaga innych narzędzi.
Dane i kontekst: skąd agent AI bierze wiedzę o projekcie?
Trzeba pamiętać, że model zna tylko to, czego nauczył się podczas treningu, a jego wiedza kończy się w dniu zamknięcia danych treningowych. Na temat projektu, nad którym pracujesz, nie wie praktycznie nic, chyba że dostarczysz mu odpowiedni kontekst. Mogą to zrobić serwery , które łączą agenta z zewnętrznymi usługami (szerzej opisuję to w artykule co to jest MCP), wyszukujący pasujące fragmenty dokumentów w bazie wektorowej, zwykłe API albo pliki w repozytorium, takie jak AGENTS.md czy CLAUDE.md. Zespół odpowiedzialny za Codex radzi dać agentowi prostą mapę zamiast wielkiej instrukcji, a generalną zasadą jest, by model AI pracował na aktualnych danych. To wszystko składa się na sprawny ekosystem ściśle powiązany z modelem.
Kontekst jest zasobem ograniczonym. Okno kontekstowe ma swój limit, a przy dużej ilości danych model radzi sobie gorzej, nawet jeśli dane się w nim mieszczą. Dlatego eksport z dziesiątkami tysięcy wierszy czy pełny log z serwera nie powinny trafiać do rozmowy w całości. Dobry harness przekazuje agentowi tylko dane potrzebne w danym kroku, np. rekordy jednego klienta albo wycinek logu z konkretnej godziny. W związku z powyższym wąskie narzędzia służą także ochronie kontekstu.
Przy długich zadaniach szczegółową historię zastępuje zwięzłe podsumowanie postępów, podjętych decyzji i otwartych spraw. Claude Code i Codex robią to automatycznie, kompresując rozmowę, gdy zbliża się do limitu okna. Zachowanie wiedzy między sesjami wymaga już mechanizmów pamięci zapewnianych przez środowisko, takich jak pliki instrukcji czy automatycznie zapisywane notatki. Rozwiązaniem, jakie proponuję, jest prosty plik postępu zapisywany po każdym etapie, z liczbą przetworzonych elementów, ostatnim identyfikatorem i listą spraw do przeglądu. Kolejna sesja wczytuje go na starcie i kontynuuje pracę. Stosuję taką praktykę od dłuższego czasu, a wzięło się to z wygody – niektóre zadania były po prostu zbyt długie i jednocześnie potrzebowałem dokumentacji, co zostało zrobione, dlaczego i jak. Takie pliki powinny być jak najbardziej konkretne i rzeczowe, by ich niepotrzebnie nie wydłużać.
Narzędzia i działania: jak agent AI wykonuje zadania?
Ta warstwa pozwala modelowi odczytywać dane i zlecać działania. Model w żadnym momencie niczego nie wykonuje sam. Przykładowo, przy wywoływaniu funkcji zwraca ustrukturyzowaną prośbę z nazwą narzędzia i argumentami, harness ją wykonuje, a sam wynik wraca do modelu jako kolejna porcja kontekstu. Tak samo działa uruchamianie kodu w piaskownicy czy zapis plików. Każde działanie agenta przechodzi więc przez kod, który kontrolujesz, i to właśnie tam ustawiasz odpowiednie granice.
Dwie zasady projektowania narzędzi sprawdzają mi się najlepiej:
- Wąskie narzędzia zamiast ogólnych. Narzędzie do jednego konkretnego celu daje agentowi mniej okazji do pomyłki niż ogólny dostęp do terminala czy bazy.
- Odczyt oddzielony od zapisu. Agent czyta dane w zakresie uprawnień projektu, z limitami zapytań i czasu pracy, a zmiany wprowadza osobną ścieżką, np. przez gałąź i pull request.
Odczyt musi wynikać z odpowiednich uprawnień dostosowanych do tego, co model ma robić. Sprawdź, czy nie udostępniasz mu zbędnych danych wrażliwych i czy zakres uprawnień odpowiada powierzonym zadaniom.
Kontrola i walidacja: jak sprawdzać wyniki agenta AI?
Ta warstwa sprawdza, czy wynik jest poprawny, i pilnuje, żeby agent nie utknął w ślepej uliczce. Najprostszy mechanizm to walidacja schematu. Gdy agent ma zwrócić dane w JSON-ie, harness sprawdza je biblioteką w TypeScripcie albo Pydantic w Pythonie, a przy błędzie odsyła modelowi konkretny opis problemu. Poniższy przykład wymaga Zod 4 i przyjmuje adresy stron HTTP/HTTPS:
Agent musi dostawać szybką i jednoznaczną informację o błędzie, by móc go poprawić, a potem sprawdzić wynik ponownie. Na tej samej zasadzie działają testy uruchamiane po każdej zmianie, a część braków, których nie da się zapisać regułą, wyłapie drugi model w roli recenzenta (). Testy deterministyczne zawsze dają ten sam wynik, a recenzent wyłapuje problemy trudne do sformalizowania, więc najlepiej łączyć oba typy kontroli. Pamiętaj też, że recenzent potrzebuje przeglądu użytkownika, dlatego jego oceny regularnie porównuj z własnymi.
Jak ograniczyć pętlę agentową i uprawnienia agenta AI?
Agent pracuje w pętli, w której model wybiera narzędzie, harness je wykonuje, wynik wraca do modelu i tak aż do końca zadania. W tym układzie to harness decyduje, kiedy pętla się kończy. Ustala limit kroków, czasu i kosztu, wykrywa powtarzające się wywołania tego samego narzędzia z tymi samymi argumentami i po wyczerpaniu limitu każe agentowi zgłosić blokadę, zamiast próbować w nieskończoność.
Ograniczenie podane w formie promptu jest prośbą i agent zwykle jej posłucha, ale znam przypadki, że nie posłuchał i przykładowo sam ustawiał przekierowania, bez mojego polecenia, a czasem nawet wbrew wyraźnemu zakazowi. Twardą granicą są uprawnienia zapisu, piaskownica, ochrona gałęzi i testy przed scaleniem. Na przykład w Claude Code dodatkową kontrolą są hooki, które uruchamiają skrypt przed użyciem narzędzia i mogą je także zatrzymać. Poza tym chroń też same zabezpieczenia, czyli konfigurację hooków, CI i testy, aby agent nie mógł sam zdjąć nałożonych na niego ograniczeń.
Uprawnienia mają dwie warstwy. Reguły dostępu określają, co agent może otworzyć, czyli które repozytoria, eksporty i konta. Reguły zatwierdzania określają, które działania czekają na zgodę człowieka. Przy zatwierdzaniu łatwo przesadzić z liczbą pytań. Jeśli agent pyta o każdy drobiazg, ludzie zaczynają klikać „zatwierdź” bez czytania i zgoda przestaje cokolwiek chronić. Dlatego osobnej zgody wymagaj tylko przy działaniach trudnych do cofnięcia, a resztę zatwierdzaj partiami albo zostaw testom.
Ostatni element tej warstwy stanowią logi, w których należy zapisywać, jakich danych agent użył, jakie narzędzia wywołał i co zmienił, razem z identyfikatorem modelu oraz wersją instrukcji i narzędzi. W ten sposób odtworzysz przebieg pracy agenta i łatwiej zbadasz przyczyny błędu. Same logi nie wyjaśniają jednak w pełni, dlaczego model podjął daną decyzję.
Jak zamieniać błędy agenta AI w testy i reguły?
Zasada Hashimoto zmienia odruch, z którym większość osób pracuje z AI. Zamiast poprawić błąd ręcznie albo dopisać zdanie do promptu, zmieniasz środowisko tak, żeby ten błąd stał się niemożliwy albo natychmiast wykrywalny. Jeśli agent w repozytorium z yarnem instaluje pakiety przez npm, dopisujesz regułę do pliku instrukcji, a gdy to nie pomaga, dodajesz hook blokujący npm install. Gdy agent zgłasza koniec pracy bez uruchomienia testów, harness odpala je sam i odsyła wynik. Z czasem repozytorium gromadzi wiedzę o tym, jak w danym projekcie można się pomylić, i ta wiedza nie znika, gdy zmienia się model albo narzędzie.
Żeby wiedzieć, czy poprawka harnessu pomaga szerzej niż w jednym przypadku, potrzebujesz stałego zestawu zadań z oczekiwanym wynikiem. Uruchamiaj go wielokrotnie na tych samych danych, także po zmianie modelu, instrukcji lub narzędzi. Mierz odsetek poprawnych wykonań, niedozwolonych zmian i fałszywych alarmów, czas przeglądu oraz koszt zadania. Kryteria sukcesu i testy zatwierdzaj niezależnie od agenta, który wykonuje zadanie, bo inaczej agent może poprawić wynik, osłabiając sam test.
Kiedy budować harness dla agenta AI?
Musimy pamiętać, że harness to kod, który trzeba stworzyć, ale także utrzymywać. O ile przy jednorazowym zapytaniu do czatu nie ma to sensu, o tyle przy zadaniach powtarzalnych, skalowalnych lub podatnych na ukryte błędy inwestycja błyskawicznie się zwraca. Harness opłaci się w projekcie, gdy zadanie spełnia choć jeden z tych warunków:
powtarza się co tydzień albo przy każdej zmianie w projekcie, więc każda poprawka środowiska pracuje wielokrotnie,
obejmuje setki podstron, rekordów albo plików, gdzie jeden błąd szybko się powiela,
błędy wychodzą z opóźnieniem i bez automatycznej kontroli zauważysz je dopiero po tygodniach,
agent ma prawo zapisu w repozytorium, bazie danych albo zewnętrznej usłudze, a nie tylko czyta i raportuje.
Dobrym przykładem jest tutaj SEO, czyli optymalizacja strony pod wyszukiwarki – jeden błąd w szablonie powiela się na setkach podstron, a jego skutki widać w Search Console z mniejszym lub większym opóźnieniem. Konkretny harness dla pozycjonowania, z kodem hooka, testami na wdrożeniu podglądowym i klasami zatwierdzania, pokazuję w artykule o harness engineeringu w SEO. Podobnie działa agent w potoku CI, który opisuję w tekście o agentach AI w CI/CD.
Pamiętaj jednak, że przegląd zmian nadal kosztuje czas, a więcej pracy od agenta to więcej pracy do przejrzenia, choć testy wyraźnie zmniejszają ten koszt – decyzje o strategii, priorytetach i jakości zostają po stronie człowieka.


