# Harness

> Interaktywny materiał dla Łukasza Banacha o tym, jak świadomie prowadzić AIOS Brain: stawiać wymagania, rozpoznawać ryzyko i żądać dowodów zamiast wierzyć w deklaracje.

Po przejściu tej ścieżki nie będziesz pisał całego systemu sam. Będziesz wiedział, jakie decyzje należą do Ciebie, co oddelegować AI i po czym poznać, że praca została wykonana dobrze.

## Kontrakt właściciela produktu

### Ty definiujesz rezultat

Mówisz, co ma być prawdą dla użytkownika i czego system nigdy nie może zrobić.

### AI wykonuje pracę

Przygotowuje specyfikację, kod, testy, analizę błędów i dokumentację.

### Dowód zamyka zadanie

Build, test, log, zrzut lub odpowiedź systemu potwierdzają wynik. Sam komunikat nie wystarcza.

## 01. Kontrakty zamiast domysłów

Mentor: Matt Pocock

**Pytanie:** Skąd system wie, że dostał poprawne dane i konfigurację?

**Zasada:** Typ opisuje oczekiwany kształt. Walidacja sprawdza, czy rzeczywistość naprawdę do niego pasuje.

Program nie powinien zgadywać, czy dostał adres bazy, właściwy klucz albo zgodę użytkownika. Ma sprawdzić to na wejściu i zatrzymać się, jeśli coś się nie zgadza.

**Porównanie:** Lista pasażerów nie dowodzi, że wszyscy weszli do samolotu. Potrzebna jest kontrola przy bramce. TypeScript tworzy listę, a walidacja sprawdza obecność.

### W AIOS Brain

- Staging nie uruchomi się z adresem produkcyjnej bazy.
- Narzędzie zwraca jeden z jawnych stanów: wykonano i sprawdzono, potrzebna zgoda albo błąd.
- Każdy agent otrzymuje user_id, module_id i dozwolony zakres kontekstu.

### Twoje decyzje

- Jakie stany wyniku są dopuszczalne?
- Które braki mają zatrzymać system?
- Które działania zawsze wymagają zgody?

### Praca dla AI

- Tworzy schematy Zod i typy TypeScript.
- Dodaje walidację zmiennych środowiskowych.
- Pisze testy odrzucające błędne wejścia.

### Dowód wykonania

- Build celowo nie przechodzi bez wymaganej konfiguracji.
- Test pokazuje, że staging odrzuca produkcyjny adres.
- Każdy wynik narzędzia ma status i identyfikator dowodu.

### Prompt roboczy

> Zmapuj granice danych tej funkcji. Dla każdej podaj schemat wejścia, możliwe wyniki, warunki zatrzymania i test negatywny. Nie implementuj, dopóki kontrakt nie będzie jednoznaczny.

### Sprawdź rozumienie

TypeScript pokazuje, że DATABASE_URL ma typ string. Czy to dowodzi, że zmienna istnieje na serwerze?

- A. Tak, kompilator sprawdzi serwer podczas builda
- B. Nie, potrzebna jest walidacja działającej konfiguracji
- C. Tak, jeśli nazwa zmiennej jest zapisana wielkimi literami

**Poprawna odpowiedź:** B. Typ pomaga podczas pisania kodu, ale nie potwierdza stanu środowiska. Dlatego konfigurację sprawdzamy także podczas builda lub uruchomienia.

[Źródło: How To Strongly Type process.env](https://www.totaltypescript.com/how-to-strongly-type-process-env)

## 02. Testuj zachowanie, nie liczbę linijek

Mentor: Kent C. Dodds

**Pytanie:** Jak sprawdzić, czy produkt naprawdę działa dla użytkownika?

**Zasada:** Największą pewność dają testy obejmujące współpracę kilku części systemu, uzupełnione małą liczbą krytycznych testów od początku do końca.

Nie chodzi o tysiąc drobnych testów. Chodzi o potwierdzenie całej ważnej historii: użytkownik pisze, agent rozumie kontekst, wybiera narzędzie, wykonuje zadanie i pokazuje prawdziwy rezultat.

**Porównanie:** Możesz osobno sprawdzić silnik, hamulce i światła. Klient nadal potrzebuje jazdy próbnej całym samochodem.

### W AIOS Brain

- Test integracyjny sprawdza chat, bazę, RAG i zapis historii razem.
- Playwright przechodzi krytyczne ścieżki tak jak użytkownik.
- RLS jest testowane na prawdziwej bazie stagingowej, nie tylko przez mock.

### Twoje decyzje

- Jakie trzy historie użytkownika są krytyczne?
- Jaki błąd niszczy zaufanie do produktu?
- Co musi działać przed każdym wdrożeniem?

### Praca dla AI

- Pisze testy jednostkowe dla czystej logiki.
- Buduje testy integracyjne dla pełnych przepływów.
- Automatyzuje kilka najważniejszych ścieżek E2E.

### Dowód wykonania

- Raport pokazuje nazwę i wynik każdej krytycznej ścieżki.
- Test potrafi wykryć celowo wprowadzony błąd.
- Wdrożenie jest blokowane, gdy krytyczny test nie przechodzi.

### Prompt roboczy

> Zaprojektuj Testing Trophy dla tej funkcji. Zacznij od zachowania użytkownika. Wskaż testy statyczne, jednostkowe, integracyjne i maksymalnie dwa E2E. Uzasadnij, jaki rodzaj ryzyka łapie każdy test.

### Sprawdź rozumienie

Który test daje najlepszy dowód, że użytkownik odzyska kontekst rozmowy z Telegrama w aplikacji webowej?

- A. Test jednej funkcji formatującej tekst
- B. Test koloru przycisku w przeglądarce
- C. Test integracyjny całego przepływu Telegram, baza i web

**Poprawna odpowiedź:** C. Ryzyko znajduje się na styku kilku systemów. Test jednej funkcji nie potwierdzi, że cały przepływ działa.

[Źródło: The Testing Trophy and Testing Classifications](https://kentcdodds.com/blog/the-testing-trophy-and-testing-classifications)

## 03. Evale są testami jakości AI

Mentor: Hamel Husain i Shreya Shankar

**Pytanie:** Jak mierzyć odpowiedzi, które za każdym razem mogą wyglądać trochę inaczej?

**Zasada:** Najpierw analizujesz prawdziwe błędy, potem tworzysz z nich zestaw przypadków i dopiero wtedy mierzysz poprawę.

Klasyczny test wie, czy dwa plus dwa daje cztery. Eval sprawdza bardziej ludzkie kryteria: czy odpowiedź użyła właściwego kontekstu, podała źródło, wykonała zadanie i nie zmyśliła rezultatu.

**Porównanie:** To nie egzamin z jedną odpowiedzią. To karta oceny rozmowy sprzedażowej: kilka kryteriów, przykłady dobrych i złych zachowań oraz człowiek kalibrujący ocenę.

### W AIOS Brain

- Każdy agent ma własny zestaw realnych scenariuszy regresyjnych.
- Błędy trafiają do taksonomii, a nie do folderu z przypadkowymi promptami.
- Zmiana modelu lub promptu jest porównywana z poprzednią wersją.

### Twoje decyzje

- Jak wygląda dobra odpowiedź w tym zadaniu?
- Które błędy są krytyczne, a które tylko irytujące?
- Jaki minimalny wynik pozwala wdrożyć zmianę?

### Praca dla AI

- Buduje zestaw evali z realnych przypadków.
- Grupuje porażki według przyczyn.
- Uruchamia porównanie starej i nowej wersji.

### Dowód wykonania

- Każdy scenariusz ma oczekiwane zachowanie i kryteria oceny.
- Raport pokazuje regresje, nie tylko średnią ocenę.
- Ocena automatyczna jest okresowo porównywana z oceną człowieka.

### Prompt roboczy

> Zbuduj pierwszy eval set dla tego agenta na podstawie 20 realnych zadań. Najpierw zaproponuj taksonomię błędów i rubrykę oceny. Nie używaj jednej ogólnej oceny jakości.

### Sprawdź rozumienie

Agent uzyskał średnio 92 procent, ale dwa razy wysłał wiadomość bez zgody. Czy może wejść na produkcję?

- A. Tak, średnia przekracza 90 procent
- B. Nie, krytycznego błędu nie wolno ukrywać w średniej
- C. Tak, jeśli wiadomości były krótkie

**Poprawna odpowiedź:** B. Metryka zagregowana może ukryć rzadki, ale katastrofalny błąd. Krytyczne klasy porażek potrzebują osobnego progu równego zero.

[Źródło: Your AI Product Needs Evals](https://hamelhusain.substack.com/p/evals)

## 04. Przerwij niebezpieczne połączenie

Mentor: Simon Willison

**Pytanie:** Kiedy agent z dostępem do danych staje się realnym zagrożeniem?

**Zasada:** Największe ryzyko powstaje, gdy jeden agent widzi prywatne dane, czyta niezaufaną treść i może wysyłać informacje na zewnątrz.

Złośliwa instrukcja może być ukryta w mailu, dokumencie albo stronie. Model może potraktować ją jak polecenie. Sam lepszy prompt nie jest wystarczającą barierą.

**Porównanie:** Nie dajesz jednej osobie klucza do sejfu, prawa do czytania anonimowych poleceń i możliwości wysyłania paczek bez kontroli.

### W AIOS Brain

- Dostęp do danych jest ograniczony przez module_id i RLS przed wywołaniem modelu.
- Narzędzia zapisu mają poziom ryzyka i bramkę zatwierdzenia.
- Agent czytający niezaufane treści nie otrzymuje nieograniczonej komunikacji wychodzącej.

### Twoje decyzje

- Jakie dane są prywatne lub wrażliwe?
- Które źródła są niezaufane?
- Jakie działania zewnętrzne mają wymagać zatwierdzenia?

### Praca dla AI

- Tworzy threat model dla funkcji.
- Klasyfikuje narzędzia według ryzyka.
- Pisze testy odmowy dostępu i prób prompt injection.

### Dowód wykonania

- Test pokazuje odmowę dostępu do obcego modułu.
- Wysokie ryzyko nie może ominąć approval gate.
- Audit log zapisuje próbę oraz ostateczną decyzję.

### Prompt roboczy

> Przeprowadź threat model tej funkcji metodą Lethal Trifecta. Zmapuj prywatne dane, niezaufane wejścia i kanały wyjściowe. Zaproponuj zmianę architektury, która przerywa co najmniej jedno połączenie.

### Sprawdź rozumienie

Agent czyta maile klientów, widzi CRM i może sam wysyłać wiadomości. Co jest właściwą ochroną?

- A. Dłuższy system prompt z zakazem wycieku
- B. Rozdzielenie uprawnień i approval przed wysyłką
- C. Wyższa temperatura modelu

**Poprawna odpowiedź:** B. Bezpieczeństwo musi wynikać z uprawnień i architektury. Prompt może pomóc, ale nie jest granicą bezpieczeństwa.

[Źródło: The lethal trifecta for AI agents](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/)

## 05. Workflow przed agentem

Mentor: Anthropic Engineering

**Pytanie:** Kiedy potrzebujesz autonomii, a kiedy zwykłego procesu?

**Zasada:** Jeśli znasz kolejne kroki, zapisz je w kodzie. Agent jest potrzebny tam, gdzie droga zależy od nieprzewidywalnej sytuacji.

Agent brzmi atrakcyjnie, ale kosztuje więcej, działa wolniej i trudniej go przewidzieć. Faktura, usunięcie danych lub wysłanie maila powinny przejść przez określony proces, nawet jeśli AI pomaga podjąć część decyzji.

**Porównanie:** Pociąg jedzie po torach, gdy cel i trasa są znane. Terenówka ma sens dopiero tam, gdzie drogi naprawdę nie ma.

### W AIOS Brain

- Import pliku jest deterministycznym pipeline z retry i idempotency.
- Model klasyfikuje intencję, ale kod sprawdza uprawnienia i wykonuje mutację.
- Agent-builder może proponować, lecz użytkownik zatwierdza utworzenie i harmonogram agenta.

### Twoje decyzje

- Gdzie elastyczność modelu tworzy realną wartość?
- Gdzie rezultat musi być zawsze przewidywalny?
- Jaki jest maksymalny koszt i czas wykonania?

### Praca dla AI

- Rozpisuje proces na kroki deterministyczne i probabilistyczne.
- Dodaje retry, timeout oraz idempotency key.
- Ogranicza liczbę narzędzi dostępnych agentowi.

### Dowód wykonania

- Diagram pokazuje, które decyzje podejmuje model, a które kod.
- Ponowne uruchomienie nie wykonuje tej samej mutacji drugi raz.
- Przekroczenie czasu lub budżetu kończy zadanie kontrolowanym błędem.

### Prompt roboczy

> Rozdziel ten proces na workflow i decyzje modelu. Wszystkie znane kroki zapisz deterministycznie. Autonomię zostaw tylko tam, gdzie nie da się z góry opisać właściwej ścieżki.

### Sprawdź rozumienie

Który element powinien być deterministycznym workflow?

- A. Rozpoznanie niejasnej intencji użytkownika
- B. Wystawienie zatwierdzonej faktury dokładnie jeden raz
- C. Zaproponowanie tematów do dalszej rozmowy

**Poprawna odpowiedź:** B. Wystawienie faktury ma znany proces i konsekwencje finansowe. Model może przygotować dane, ale wykonanie powinien kontrolować kod.

[Źródło: Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)

## 06. Zobacz całą drogę zadania

Mentor: Charity Majors i OpenTelemetry

**Pytanie:** Jak znaleźć przyczynę błędu, którego wcześniej nie przewidziałeś?

**Zasada:** Każde wykonanie powinno zostawiać spójny ślad od intencji użytkownika do zweryfikowanego rezultatu.

Gdy agent zawiedzie, nie wystarczy informacja, że API zwróciło błąd. Musisz zobaczyć: jaki agent działał, jaki miał zakres, co pobrał, jakie narzędzie wybrał, ile to kosztowało i gdzie dokładnie zatrzymał się proces.

**Porównanie:** Numer przesyłki pozwala prześledzić całą drogę paczki. Trace ID robi to samo z zadaniem agenta.

### W AIOS Brain

- Jeden trace_id łączy chat, retrieval, model, narzędzia, Inngest i finalną weryfikację.
- Każdy agent_run zapisuje wersję promptu, modelu i użytych źródeł.
- Logi nie przechowują sekretów ani pełnej treści wrażliwych danych.

### Twoje decyzje

- Jakie pytania chcesz móc zadać po awarii?
- Które dane wolno logować?
- Jak długo przechowujemy ślady wykonania?

### Praca dla AI

- Dodaje trace i span do kolejnych etapów.
- Buduje dashboard kosztu, czasu i skuteczności agentów.
- Redaguje wrażliwe pola przed zapisem.

### Dowód wykonania

- Z jednego trace_id można odtworzyć pełną historię zadania.
- Dashboard rozdziela wyniki według agenta, modelu i środowiska.
- Test potwierdza, że sekret nie trafia do logów.

### Prompt roboczy

> Zaprojektuj ślad wykonania dla tego agent_run. Pokaż span dla retrieval, wywołania modelu, każdego narzędzia, approval i verification. Wskaż pola, które trzeba zredagować ze względu na prywatność.

### Sprawdź rozumienie

Co jest najlepszym punktem startu po zgłoszeniu: agent czasem odpowiada źle?

- A. Dodać więcej losowych logów tekstowych
- B. Odtworzyć konkretny agent_run po trace_id
- C. Od razu zmienić model na droższy

**Poprawna odpowiedź:** B. Najpierw trzeba zobaczyć pełną drogę konkretnego zadania. Dopiero wtedy wiadomo, czy zawiódł retrieval, model, narzędzie czy weryfikacja.

[Źródło: OpenTelemetry JavaScript](https://opentelemetry.io/docs/languages/js/)
[Źródło: Observability is a Many-Splendored Definition](https://charity.wtf/2020/03/03/observability-is-a-many-splendored-thing/)

## 07. Reguły architektury muszą działać automatycznie

Mentor: Google SRE i Martin Fowler

**Pytanie:** Skąd wiesz, że system jest gotowy do dalszego rozwoju?

**Zasada:** Ustal poziom niezawodności, mierz go i zamień najważniejsze decyzje architektoniczne w automatyczne testy.

Dokument z zasadami jest dobrym początkiem. Profesjonalny system sam blokuje zmianę, która łamie izolację danych, używa produkcyjnego klucza na stagingu albo pozwala narzędziu ominąć zatwierdzenie.

**Porównanie:** Przepisy budowlane są skuteczne dopiero wtedy, gdy konstrukcja przechodzi pomiary i odbiór. Sama deklaracja architekta nie utrzyma budynku.

### W AIOS Brain

- SLO obejmują dostępność, czas pierwszego tokenu, skuteczność agent_run i opóźnienie kolejki.
- Error budget określa, kiedy zatrzymujemy nowe funkcje i naprawiamy niezawodność.
- Fitness functions sprawdzają RLS, module_id, approval, staging isolation i verification.

### Twoje decyzje

- Jaki poziom jakości obiecujesz użytkownikowi?
- Które naruszenie blokuje wszystkie wdrożenia?
- Kiedy zespół przestaje rozwijać funkcje i naprawia fundament?

### Praca dla AI

- Automatyzuje SLI i raport SLO.
- Tworzy fitness functions dla reguł architektury.
- Przygotowuje rollback, runbook i szablon postmortem.

### Dowód wykonania

- Dashboard pokazuje aktualne SLO i pozostały error budget.
- Złamanie inwariantu blokuje merge lub deploy.
- Rollback został przećwiczony, a nie tylko opisany.

### Prompt roboczy

> Zamień zasady tej funkcji na mierzalne SLI, jedno realistyczne SLO i automatyczne fitness functions. Dodaj warunek zatrzymania wdrożeń oraz procedurę rollbacku.

### Sprawdź rozumienie

System przekroczył error budget przez powtarzające się błędy. Co robimy?

- A. Kontynuujemy roadmapę, bo błędy są już znane
- B. Zatrzymujemy zwykłe wdrożenia i przywracamy niezawodność
- C. Ukrywamy metrykę do końca miesiąca

**Poprawna odpowiedź:** B. Error budget ma wpływać na decyzje. Po jego przekroczeniu priorytetem staje się niezawodność, z wyjątkiem krytycznych poprawek.

[Źródło: Google SRE Error Budget Policy](https://sre.google/workbook/error-budget-policy/)
[Źródło: Building Evolutionary Architectures](https://martinfowler.com/articles/evo-arch-forward.html)

## Plan na 30 dni

### Tydzień 1: Zamknij kontrakty

Wybierz jeden przepływ AIOS Brain. Opisz oczekiwany rezultat, granice danych, stany wyniku oraz działania wymagające zgody.

### Tydzień 2: Zdefiniuj dowody

Wskaż trzy krytyczne historie użytkownika. Dla każdej określ test, eval i dowód zamykający zadanie.

### Tydzień 3: Przerwij ryzyko

Zrób threat model Lethal Trifecta. Rozdziel dostęp do danych, niezaufane wejścia i komunikację zewnętrzną.

### Tydzień 4: Uruchom pętlę jakości

Podłącz trace, wybierz pierwsze SLO i ustal jedną fitness function, która automatycznie blokuje złamanie architektury.

## Słownik

- **Kontrakt:** Jawna umowa o tym, jakie dane wchodzą, co może się wydarzyć i jaki wynik wychodzi.
- **Walidacja:** Sprawdzenie, czy prawdziwe dane spełniają kontrakt.
- **Test integracyjny:** Test sprawdzający współpracę kilku części systemu.
- **Eval:** Powtarzalna ocena jakości odpowiedzi lub działania AI.
- **RLS:** Reguły bazy danych ograniczające rekordy widoczne dla danego użytkownika.
- **Workflow:** Z góry określona sekwencja kroków wykonywana przez kod.
- **Agent:** Model, który sam wybiera kolejne kroki i narzędzia w ramach nadanych granic.
- **Trace:** Połączony zapis całej drogi jednego zadania przez system.
- **SLI:** Metryka pokazująca rzeczywiste zachowanie systemu.
- **SLO:** Docelowy poziom tej metryki, który obiecujemy utrzymać.
- **Error budget:** Dopuszczalna ilość zawodności wynikająca z przyjętego SLO.
- **Fitness function:** Automatyczny test sprawdzający, czy architektura nadal spełnia swoje zasady.