Przejdź do treści

Czym jest harness engineering? Architektura środowiska agenta AI

Maciej Sala

Founder StriveLab

11 min czytaniaOpublikowano

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:

  1. Prompt engineering, czyli jak sformułować polecenie,
  2. Context engineering, czyli co model powinien zobaczyć,
  3. 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.

WarstwaZa co odpowiadaPrzykłady
Dane i kontekstFakty, których model nie ma w wagachMCP, RAG, bazy wektorowe, zewnętrzne API, pliki instrukcji w repozytorium
Narzędzia i działaniaDziałanie poza rozmowąwywoływanie funkcji, uruchamianie kodu w piaskownicy, zapis plików
Kontrola i walidacjaPoprawność wyniku i przebieg całej pętli pracywalidacja 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:

  1. 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.
  2. 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:

checkProposal.ts
Code
import { z } from 'zod'
 
const Proposal = z.object({
  url: z.url({ protocol: /^https?$/ }),
  title: z.string().trim().min(10).max(70),
  reason: z.string().trim().min(1),
})
 
type ProposalResult =
  | { ok: true; data: z.infer<typeof Proposal> }
  | { ok: false; feedback: string }
 
export function checkProposal(raw: string): ProposalResult {
  let data: unknown
  try {
    data = JSON.parse(raw)
  } catch {
    return { ok: false, feedback: 'Odpowiedź nie jest poprawnym JSON-em.' }
  }
 
  const result = Proposal.safeParse(data)
  if (!result.success) {
    // opis błędów wraca do modelu jako informacja zwrotna
    return { ok: false, feedback: z.prettifyError(result.error) }
  }
  return { ok: true, data: result.data }
}

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

Diagram
Pętla agentowa: harness wykonuje każde wywołanie narzędzia, sprawdza wynik i pilnuje limitów

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.

Raporty, treści i monitoring SEO w n8n, z agentami AI i kontrolą człowieka.
Automatyzacja SEO i marketingu

Często zadawane pytania

Czym harness engineering różni się od context engineering?

Context engineering odpowiada na pytanie, co model powinien zobaczyć, natomiast harness engineering idzie krok dalej – obejmuje kontekst, ale dodaje do niego narzędzia, ograniczenia, weryfikację oraz logowanie, odpowiadając na pytania, czemu system ma zapobiegać, co mierzyć i co w nim optymalizować.

Co oznacza słowo harness?

Po angielsku harness to uprząż. W programowaniu od dawna używa się też pojęcia test harness, czyli środowiska, które uruchamia testowany kod, podaje mu dane i sprawdza wynik. Harness agenta AI pełni podobną rolę wobec modelu językowego.

Czy harness to to samo co framework agentowy?

Nie. Framework, np. LangChain albo AI SDK, daje klocki do budowy agenta. Harness to konkretna konfiguracja wokół agenta w danym projekcie: jego instrukcje, narzędzia, uprawnienia, testy i logi. Gotowe narzędzia, takie jak Claude Code czy Codex, mają własny harness, który rozbudowujesz o pliki instrukcji, hooki i testy projektu.

Czy lepsze modele sprawią, że harness przestanie być potrzebny?

Nie, choć zakres potrzebnych instrukcji może się zmniejszyć. Lepsze modele potrzebują mniej podpowiedzi krok po kroku, więc część instrukcji może zniknąć. Model nadal jednak przetwarza dane wejściowe i generuje odpowiedzi, a dostęp do danych, wykonywanie działań, blokady i zatwierdzanie zmian dzieją się w otaczającym go oprogramowaniu. Nawet rzadki błąd lepszego modelu, powtórzony przy setkach zadań, wymaga testów i blokad.

Czy harness engineering dotyczy tylko programistów?

Termin wyrósł z programowania, ale zasada działa wszędzie, gdzie agent pracuje na danych i wykonuje działania. Przykład z pozycjonowania opisuję w artykule o harness engineeringu w SEO.

O autorze

Maciej Sala

Maciej Sala — konsultant technologiczny produktów cyfrowych i web developer z bogatym doświadczeniem w marketingu internetowym oraz SEO. Na co dzień pracuje z Reactem, Next.js i TypeScriptem, a ostatnio także z Astro i narzędziami do automatyzacji procesów AI. Sprawnie łączy perspektywę produktową z praktycznym podejściem do kodu. Przez kilka lat był związany z branżą gier wideo jako project manager i game designer. Absolwent historii na Uniwersytecie Jagiellońskim oraz studiów podyplomowych z marketingu internetowego na AGH w Krakowie. Po godzinach trenuje na siłowni, maluje figurki i rozwija własne projekty.

Pomagam przekładać takie tematy na konkretne wdrożenia w frontendzie, SEO, analityce i procesie produktowym.

Skontaktuj się ze mną
LH.pl – Hosting Mango

Biblioteka wiedzy na temat AI

Czytaj dalej

Zobacz więcej wpisów
Harness engineering w SEO: jak kontrolować agentów AI

Ten sam model AI potrafi w jednym projekcie pracować niezawodnie, natomiast w innym wprowadzać nie lada bałagan. Skąd bierze się taka różnica w działaniu? Najkrócej rzecz ujmując, chodzi o środowisko wokół modelu, czyli dane, które dostaje, narzędzia, których może użyć, zakazy, których nie obejdzie, i kontrole, przez które przechodzi jego praca, zanim zobaczy ją człowiek. Projektowanie odpowiedniego dla AI środowiska nazywa się harness engineering, a termin zyskał popularność w lutym 2026 roku wśród zespołów budujących oprogramowanie z agentami AI. W SEO to podejście ma szczególny sens i właśnie o tym chcę napisać więcej w poniższym artykule.

Maciej Sala

Maciej Sala

Founder StriveLab

Czym jest agent AI i co odróżnia go od asystenta

Aktualnie agentem AI nazywa się niemal wszystko, co korzysta z modelu językowego – od widżetu do obsługi klienta po proste makro w arkuszu. Marketingowy szum wokół „agentic AI” sprawia, że pod jedną nazwą lądują narzędzia o zupełnie innej złożoności i poziomie autonomii. Poniżej rozkładam ten temat na czynniki pierwsze: sprawdzamy, czym agent różni się od promptu, asystenta i zwykłej automatyzacji, jakie przyjmuje formy, ile realnie kosztuje oraz gdzie najłatwiej o kosztowną pomyłkę – na konkretnych przykładach, w tym z mojej pracy.

Maciej Sala

Maciej Sala

Founder StriveLab

Agent AI w GitHub Actions: testy automatyczne i review kodu

Agenty AI w terminalu pomagają pojedynczemu deweloperowi, ale już agenty AI w CI/CD pomagają całemu zespołowi: po otwarciu PR mogą wskazać brakujące testy, potencjalne regresje i niespójność z konwencjami projektu. W tym wpisie pokazuję, jak przejść od sugestii agenta do testu automatycznego, który rzeczywiście wykrywa błąd, oraz jak rozdzielić analizę AI od uruchamiania testów w GitHub Actions.

Maciej Sala

Maciej Sala

Founder StriveLab

LH.pl – Cloud Server 1C4G