Czym jest AI Harness (Uprząż Agenta): Jak działa, jak oszczędzać kontekst i podnieść jakość kodu

Pułapka „Mózgu w słoiku” i bankructwo okna kontekstowego

Większość osób zaczyna pracę z AI od kopiowania kawałków kodu do okna czatu albo od wrzucenia 1500-liniowego pliku instrukcji do agenta w IDE i prowadzenia jednej tasiemcowej rozmowy przez trzy godziny. Po 40 minutach AI zaczyna zapominać o regułach projektu, zmyśla nieistniejące funkcje, psuje działające moduły i przepala budżet tokenów. Model nie stracił nagle inteligencji — zabrakło mu dobrze zaprojektowanej uprzęży (harnessu) albo jego biurko robocze zostało zasypane śmieciami kontekstowymi.

1. Czym właściwie jest AI Harness? Metafora „Mózgu w zamkniętym pokoju” vs. „Inżyniera z warsztatem”

Angielskie słowo „harness” oznacza uprząż (np. wspinaczkową albo zaprzęgową) lub kompletny kokpit, układ kierowniczy, klatkę bezpieczeństwa i hamulce, które zamieniają surowy silnik V12 na palecie w sterowny bolid Formuły 1. W inżynierii AI — zgodnie z oficjalnymi publikacjami Anthropic, OpenAI oraz Thoughtworks (Martina Fowlera) — opisuje to jedno fundamentalne równanie: `Agent = Model + Harness`.

Wyobraź sobie genialnego programistę (to Twój Model LLM — np. Claude, GPT czy Gemini), którego zamykasz w pokoju bez okien, bez komputera i bez dostępu do Twojego projektu. Jedynym kontaktem ze światem jest szpara pod drzwiami. Tak właśnie działa zwykły czat w przeglądarce: wsuwasz pod drzwiami kartkę z wycinkiem kodu i pytaniem „Czemu nie działa?”, a model z pamięci zgaduje odpowiedź na kartce. Nie widzi sąsiednich plików, nie może uruchomić kompilatora ani testów, żeby sprawdzić, czy jego pomysł ma sens, a gdy wychodzisz z pokoju — traci pamięć.

AI Harness (Uprząż Agenta) to cały warsztat, egzoszkielet i regulamin, który budujesz wokół tego mózgu. Składa się z 5 konkretnych warstw: (1) Konstytucji na ścianie (`AGENTS.md` / `CLAUDE.md`), (2) Oczu i Rąk (narzędzi do czytania plików, terminala i serwerów MCP), (3) Blatu Roboczego (zarządzanego okna kontekstowego i notatek na dysku), (4) Automatycznych Czujników Jakości (kompilatora, lintera i testów, które natychmiast wyłapują błędy) oraz (5) Hamulców Bezpieczeństwa (bramek `Prepare → Confirm`). Gdy model w uprzęży napisze kod, uprząż sama uruchamia testy i w razie błędu od razu zwraca komunikat kompilatora z powrotem do modelu — dzięki czemu agent sam naprawia swój błąd, zanim w ogóle spojrzysz na ekran.

ZŁOTA ZASADA HARNESS ENGINEERINGU

Model to wynajmowany silnik; Harness to układ kierowniczy, hamulce i warsztat, które posiadasz na własność. Dobrze skonfigurowana uprząż wokół standardowego modelu regularnie pokonuje najnowszy model działający w chaosie.

┌─────────────────────────────────────────────────────────────────────────┐
│                    AI AGENT HARNESS (TWOJA UPRZĄŻ)                      │
│                                                                         │
│  [1. KONSTYTUCJA]     AGENTS.md / CLAUDE.md (Mapa <60 linii i zakazy)   │
│  [2. WIEDZA NA ŻĄDANIE] .agents/skills/*/SKILL.md (Ładowane w locie)    │
│                                   │                                     │
│                                   ▼                                     │
│        ┌───────────────►  🧠 MODEL LLM (MÓZG)  ────────────────┐        │
│        │                (Planuje i wybiera ruch)               │        │
│        │                                                       ▼        │
│  [4. CZUJNIKI JAKOŚCI]                                [3. RĘCE I OCZY]  │
│  • Kompilator / Typy (tsc)                            • System plików   │
│  • Testy (Playwright / Vitest)                        • Terminal / Git  │
│  • Linter Kontekstu (verify-harness.mjs)              • Narzędzia MCP   │
│        ▲                                                       │        │
│        └────────────────  Pętla Samonaprawy  ◄─────────────────┘        │
│                                   │                                     │
│                                   ▼                                     │
│  [5. HAMULEC BEZPIECZEŃSTWA] Bramka Prepare → Confirm / Zgoda Człowieka │
└─────────────────────────────────────────────────────────────────────────┘

2. Dlaczego AI „głupieje” po godzinie rozmowy? Okno kontekstowe to Blat Biurka (RAM), a nie szafa na akta

Każdy model AI posiada tzw. okno kontekstowe (np. 200 000 tokenów). Początkujący często zakładają: „Skoro mieści się tam cała książka, wrzucę tam całe repozytorium i będę pisał w jednym oknie czatu przez cały tydzień!”. W praktyce jest to główna przyczyna halucynacji, psucia działającego kodu i gigantycznych rachunków za tokeny.

Wyobraź sobie, że okno kontekstowe to blat Twojego biurka roboczego (pamięć RAM), natomiast dysk twardy i pliki projektu to szafa na dokumenty. Jeśli wysypiesz na blat biurka 80 teczek z plikami, tysiące linii logów z terminala i zapis dwugodzinnej kłótni z AI o stary błąd, uderzą w Ciebie dwa zjawiska fizyczne: (1) Gnicie kontekstu (Context Rot) i efekt „Lost in the Middle” — uwaga modelu rozprasza się w szumie informacyjnym, przez co agent przestaje przestrzegać zasad z `AGENTS.md`; oraz (2) Składany podatek tokenowy — modele są bezstanowe, więc przy każdym kolejnym pytaniu w tym samym wątku uprząż musi wysłać i przeczytać całe zaśmiecone biurko od nowa. Powyżej 55–60% zapełnienia okna jakość kodu i szybkość odpowiedzi spadają drastycznie.

PUŁAP 60% ZAPEŁNIENIA KONTEKSTU

Nigdy nie czekaj, aż pasek kontekstu dojdzie do 95%. W profesjonalnej pracy z AI próg 55–60% to czerwona lampka, przy której delegujesz badanie do subagenta, robisz kompakcję (/compact) lub otwierasz czystą sesję.

3. Cztery dźwignie oszczędzania do 80% kontekstu: Mapa `AGENTS.md`, Progressive Disclosure i Subagenci

Jak najlepsi inżynierowie utrzymują główne okno kontekstowe na poziomie zaledwie 15–25% zajętości, nawet gdy budują ogromne systemy? Stosują cztery mechanizmy wbudowane w uprząż:

Dźwignia 1: Mapa zamiast Encyklopedii (`AGENTS.md` / `CLAUDE.md` poniżej 60 linii). Ponieważ główny plik instrukcji jest wstrzykiwany do każdej tury rozmowy, wpisywanie tam 1500 linii dokumentacji to stały podatek płacony przy każdym zdaniu. Trzymaj `AGENTS.md` poniżej 60 linii: zapisz tam tylko stack, dokładne komendy budowania i testów, twarde zakazy (Red Lines) oraz drogowskazy do głębszych plików.

Dźwignia 2: Progressive Disclosure (Stopniowe odkrywanie wiedzy przez `SKILL.md`). Szczegółowe procedury — np. jak pisać testy E2E, jak robić migracje bazy czy jak stosować Brand Voice — zamknij w osobnych modułach `.agents/skills/<nazwa>/SKILL.md` (lub `.claude/skills/`). Na starcie sesji uprząż wczytuje na biurko tylko 2-liniowy opis z nagłówka YAML (~30 tokenów). Pełna instrukcja (150 linii) trafia na blat wyłącznie wtedy, gdy aktualne zadanie faktycznie jej dotyczy.

Dźwignia 3: Subagenci jako „Zwiadowcy z jednorazowym brudnopisem” (Context Isolation). Jeśli agent musi przeszukać 30 plików, by zrozumieć działanie autoryzacji, nigdy nie pozwalaj głównemu agentowi czytać ich bezpośrednio — to natychmiast zrzuci 60 000 tokenów surowego kodu na Twoje główne biurko. Zamiast tego uprząż powołuje Subagenta-Zwiadowcę (`research`). Subagent otwiera własne, tymczasowe biurko, przekopuje 30 plików i zwraca głównemu agentowi TYLKO 200 słów czystej syntezy z dokładnymi ścieżkami i numerami linii (`src/auth.ts#L40-L85`). Brudnopis subagenta znika, oszczędzając ~95% głównego kontekstu!

Dźwignia 4: Pamięć w plikach (`TODO.md` / `feature_list.json`) i zasada `1 Zadanie = 1 Sesja`. Zamiast trzymać 12-etapowy plan prac w historii czatu, każ uprzęży zapisać go w pliku na dysku. Po ukończeniu i przetestowaniu jednego zadania zrób commit do Gita i użyj `/compact` lub rozpocznij nową, czystą sesję.

# AGENTS.md — Mapa Operacyjna i Uprząż Projektu

## 1. Tożsamość Projektu i Stack
- **System:** Dwujęzyczna platforma edukacyjna i interaktywne laboratorium
- **Stack:** TypeScript, Astro 5, Playwright E2E, Node.js 22
- **Kluczowe ścieżki:** `src/content/` (dane EN/PL), `src/components/` (UI), `tests/` (E2E)

## 2. Deterministyczna Pętla Weryfikacji (Obowiązkowa przed zakończeniem zadania)
1. **Build i parzystość schematów:** `npm run build`
2. **Audyt kontraktów HTML i SEO:** `npm run verify`
3. **Testy E2E Playwright:** `npx playwright test`
4. **Linter budżetu uprzęży:** `node scripts/verify-harness.mjs`

## 3. Higiena Kontekstu i Reguły Subagentów
- **Pułap 60% kontekstu:** Utrzymuj główny wątek w czystości; czytaj wybrane zakresy linii zamiast całych plików.
- **Delegacja do Subagentów:** Gdy eksploracja wymaga sprawdzenia >4 plików, uruchom subagenta `research` i zażądaj podsumowania <250 słów z dokładnymi ścieżkami i liniami.
- **Dyscyplina sesji:** Jedna funkcjonalność na sesję; stan wieloetapowy zapisuj w `feature_list.json`.

## 4. Mapa Progressive Disclosure (Ładuj tylko w razie potrzeby)
- Oszczędzanie kontekstu i wzorce subagentów → `.agents/skills/context-hygiene/SKILL.md`
- Pętla weryfikacji Default-FAIL i ewaluator → `.agents/skills/verification-loop/SKILL.md`
- Interaktywny architekt uprzęży → `.agents/skills/harness-architect/SKILL.md`

## 5. Twarde Bezpieczniki (Czerwone Linie — Wymagają Zgody Człowieka)
- NIGDY nie wysyłaj zmian bezpośrednio na `main` ani nie mutuj zewnętrznych API bez jawnego potwierdzenia.
- NIGDY nie usuwaj asercji w testach i nie dodawaj `@ts-ignore`, aby sztucznie wymusić zielony build.

4. Matryca Kompromisów: Głębokość Testów kontra Zużycie Tokenów i Bezpiecznik 3 Prób

Dlaczego dokładnie ten sam model AI u jednego programisty generuje kod-spaghetti pełen błędów, a u innego tworzy czystą architekturę produkcyjną? W głośnym raporcie OpenAI („Harness Engineering: Leveraging Codex in an Agent-First World”) kluczem było połączenie probabilistycznego modelu z deterministycznymi czujnikami w repozytorium. Pojawia się tu jednak kluczowy dylemat inżynieryjny: jeśli każesz agentowi uruchamiać pełne testy E2E w głównym oknie czatu po każdej drobnej edycji, tysiące linii logów z terminala błyskawicznie zapchają okno kontekstowe i przepalą tokeny — z kolei brak testów oznacza ciche psucie aplikacji.

Aby rozwiązać ten problem, `agent-harness-kit` v2.0 wprowadza 4 gotowe profile Testy kontra Kontekst (skill `testing-tradeoffs`): (1) `fast-prototype` (~300–600 tokenów/turę: tylko szybkie sprawdzanie typów/składni, idealne na weekendowe PoC), (2) `smart-tiered` (~800–1 500 tokenów/turę: domyślny Złoty Środek — uruchamia `tsc` + 1 celowany test jednostkowy po edycji, a pełne E2E dopiero na koniec zadania), (3) `isolated-verifier` (~500 tokenów w głównym czacie: deleguje ciężkie testy Playwright/Docker do osobnego subagenta, który zwraca tylko `<200 słów` podsumowania) oraz (4) `mission-critical` (~3 000–8 000 tokenów/turę: pełny lint + unit + E2E + audyt bezpieczeństwa dla płatności, logowania i migracji bazy). Każdy profil zawiera też Bezpiecznik 3 Prób Naprawy (`3-Strike Circuit Breaker`): jeśli ten sam test nie przechodzi 3 razy z rzędu, agent ma zakaz dalszego zgadywania w pętli — zapisuje hipotezy w `HANDOFF.md` i prosi Cię o decyzję.

BEZPIECZNIK 3 PRÓB NAPRAWY (3-STRIKE CIRCUIT BREAKER)

Nigdy nie pozwalaj agentowi kręcić się w kółko przez 15 prób wokół jednego czerwonego testu — to pali 50 000 tokenów i psuje kod. Po 3 nieudanych próbach uprząż zatrzymuje pętlę, zapisuje stan w HANDOFF.md i oddaje głos człowiekowi.

┌─────────────────────┬────────────────────────────────────┬──────────────────────┬───────────────────────┐
│ Profil (--profile)  │ Pętla wewnętrzna (po edycji)       │ Koszt tokenów / turę │ Kiedy wybrać?         │
├─────────────────────┼────────────────────────────────────┼──────────────────────┼───────────────────────┤
│ fast-prototype      │ Tylko szybki typecheck / składnia  │ ~300–600 tokenów     │ Hackathon, szybki PoC │
│ smart-tiered ★      │ Typecheck + 1 celowany test pliku  │ ~800–1 500 tokenów   │ 90% codziennej pracy  │
│ isolated-verifier   │ Ciężkie E2E w osobnym Subagencie   │ ~500 tok (czat gł.)  │ Głośne logi E2E       │
│ mission-critical    │ Pełny lint + unit + E2E + security │ ~3 000–8 000 tokenów │ Płatności, auth, bazy │
└─────────────────────┴────────────────────────────────────┴──────────────────────┴───────────────────────┘

5. Kreator „Za Rączkę” w Dwóch Trybach (Nowy Projekt vs. Istniejące Repo) i `agent-harness-kit` v2.0

Prawdziwie użyteczny kreator uprzęży nie może traktować pustego folderu tak samo jak działającego od dwóch lat projektu. Dlatego nasz otwarty pakiet `RolePlayingTech/agent-harness-kit` v2.0 prowadzi programistę za rączkę dwiema odrębnymi ścieżkami (`harness-architect`):

Ścieżka A — Nowy Projekt od Zera (`greenfield-advisor`, na pustym repozytorium): Gdy startujesz od samego pomysłu na aplikację, żaden kod ani linter jeszcze nie istnieje. Agent pomaga Ci najpierw określić główną pętlę wartości MVP oraz listę Non-Goals (czego świadomie nie budujemy w v1), porównuje 2–3 stosy technologiczne (koszt hostingu, szybkość startu, czytelność typów dla AI), dobiera profil Testy kontra Kontekst i generuje kompletny blueprint projektu (`docs/PROJECT_BRIEF.md`, `docs/ARCHITECTURE.md`, ADR, `docs/ROADMAP.md`, `HANDOFF.md` oraz rejestr `feature_list.json` z uczciwym statusem `"pending"` na starcie).

Ścieżka B — Istniejący Projekt (`brownfield-onboarder`, na działającym repozytorium): Gdy uruchamiasz skilla w istniejącym projekcie, agent NIGDY nie zadaje leniwych pytań w stylu „jakiego frameworka używasz?”, skoro odpowiedź leży w `package.json` lub `pyproject.toml`. Najpierw wykonuje cichy skan repozytorium (`agent-harness inspect .`), prezentuje wykryte technologie, skrypty i ryzyka, bezpiecznie zachowuje Twoje dotychczasowe pliki `AGENTS.md`/`CLAUDE.md` bez ich nadpisywania i podejmuje z Tobą dyskusję wyłącznie o tym, czego nie widać w kodzie: wrażliwych folderach legacy, wolnych testach i wyborze profilu oszczędzania tokenów.

PAKIET OPEN-SOURCE · AGENT-HARNESS-KIT V2.0

Uruchom `npx github:RolePlayingTech/agent-harness-kit inspect .` oraz `init .` w dowolnym nowym lub istniejącym repozytorium — działa z Claude Code, Google Antigravity, Cursor, GitHub Copilot, Windsurf oraz OpenAI Codex.

# 1. Cichy skan dowolnego pustego (Greenfield) lub istniejącego (Brownfield) repozytorium:
npx github:RolePlayingTech/agent-harness-kit inspect .

# 2. Podgląd rekomendowanej ścieżki rozmowy i matrycy kompromisów Testy vs Kontekst:
npx github:RolePlayingTech/agent-harness-kit plan .

# 3. Bezpieczna instalacja 6 skilli + wygenerowanie uprzęży i blueprintu (bez nadpisywania Twoich plików):
npx github:RolePlayingTech/agent-harness-kit init . --profile smart-tiered --blueprint

# 4. Twarda weryfikacja deterministyczna (sprawdza schemat YAML, limit 80 linii i ścieżki plików):
npx github:RolePlayingTech/agent-harness-kit verify . --strict

Ewolucja pracy z AI: Zwykły Czat vs. Przeładowany Agent vs. Zoptymalizowany Harness