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. Jak Uprząż bezpośrednio podnosi jakość kodu: Probabilistyczny Mózg + Deterministyczne Czujniki

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”, opisującym budowę systemu o milionie linii kodu w 100% przez agentów Codex bez ręcznego pisania kodu przez ludzi) kluczem okazało się połączenie probabilistycznego modelu z deterministycznymi czujnikami w repozytorium.

Model LLM przewiduje kolejne słowa z pewnym prawdopodobieństwem — zawsze może pomylić nazwę importu albo zapomnieć o jednym polu w tłumaczeniu. Silny harness sprawia, że błędy nie mogą przejść niezauważone, dzięki trzem filarom: (1) Czytelności repozytorium dla AI (Repo Legibility) — ścisłym typom TypeScript, przewidywalnej strukturze katalogów i jawnym walidatorom kontraktów (jak funkcja `assertLocaleParity` w kodzie tej Akademii); (2) Szybkim pętlom zwrotnym — testom i skryptom weryfikacyjnym działającym w kilka sekund i zwracającym dokładny numer linii błędu; oraz (3) Twardym zakazom negatywnym — blokującym obchodzenie testów na skróty.

5. Wzorce zaawansowane (Anthropic Initializer + Evaluator) i nasz pakiet Open-Source `agent-harness-kit`

Gdy zadanie trwa wiele godzin lub dni, nawet najczystsza pojedyncza sesja napotyka ograniczenia. W publikacji „Effective harnesses for long-running agents” inżynierowie Anthropic przedstawili dwa wieloagentowe wzorce architektoniczne, które rozwiązują problem amnezji między sesjami:

Wzorzec A: Initializer Agent + Incremental Worker Loop. Zamiast prosić jednego agenta o zbudowanie całej aplikacji w jednym ciągu (co kończy się tzw. „early victory” — przedwczesnym ogłoszeniem sukcesu, gdy połowa funkcji to puste zaślepki), jako pierwszy uruchamia się Agent Inicjujący (`Initializer`). Tworzy on skrypt startowy środowiska oraz plik `feature_list.json`, w którym każde wymaganie ma na starcie status `"failing"`. Następnie w kolejnych, czystych sesjach budzą się Agenci Kodujący — każdy bierze dokładnie jedno zadanie z listy, pisze kod, przechodzi deterministyczne testy, zmienia status na `"passed"`, robi commit w Gicie i kończy zmianę.

Wzorzec B: Generator vs. Fresh-Context Evaluator (Kontrakt Default-FAIL). Agent, który przez 20 minut pisał kod, ulega efektowi potwierdzenia — „widzi” w kodzie to, co chciał napisać, a nie to, co faktycznie napisał. Zaawansowana uprząż powołuje osobnego Agenta-Recenzenta (`Evaluator`) w zupełnie czystym oknie kontekstowym, z uprawnieniami tylko do odczytu i uruchamiania testów. Ewaluator dostaje wyłącznie specyfikację oraz `git diff` i ocenia każdy punkt według rygorystycznej zasady Default-FAIL (każde kryterium jest niezaliczone, dopóki test nie udowodni inaczej).

Abyś nie musiał budować takiej uprzęży ręcznie od zera w każdym nowym projekcie, przygotowaliśmy otwarte repozytorium na GitHubie: `RolePlayingTech/agent-harness-kit`. Wystarczy pobrać pakiet jedną komendą na starcie projektu i poprosić swojego agenta o uruchomienie skilla `harness-architect`. Agent sam przeskanuje Twój projekt, zada Ci 5 krótkich pytań architektonicznych i wygeneruje skrojony na miarę plik `AGENTS.md` (<60 linii), `CLAUDE.md`, modułowe skille `context-hygiene` oraz `verification-loop`, a także skrypt `verify-harness.mjs` pilnujący budżetu tokenów.

PAKIET OPEN-SOURCE · AGENT-HARNESS-KIT

Wygeneruj kompletną, dopasowaną do Twojego stacku uprząż AI w 30 sekund z repozytorium https://github.com/RolePlayingTech/agent-harness-kit — działa natywnie w Google Antigravity, Claude Code, OpenAI Codex oraz Cursor.

# 1. Zainstaluj uniwersalne skille (.agents/skills i .claude/skills) + Linter Budżetu Kontekstu
git clone https://github.com/RolePlayingTech/agent-harness-kit.git /tmp/agent-harness-kit \
  && node /tmp/agent-harness-kit/scripts/install-harness-kit.mjs .

# 2. Wydaj polecenie swojemu agentowi AI (Antigravity, Claude Code, Cursor lub Codex):
# "Użyj skilla harness-architect — przeanalizuj ten projekt, zadaj mi pytania i przygotuj nasz harness."

# 3. W dowolnej chwili sprawdź, czy AGENTS.md / CLAUDE.md mieści się w budżecie <80 linii:
node scripts/verify-harness.mjs

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