Budowanie agentów Claude: jak Warp zaprojektował system, który uczy się na własnych błędach

Dlaczego większość agentów AI przestaje się rozwijać po dwóch tygodniach

Warp w swojej dokumentacji technicznej opisuje to w ten sposób: największym wąskim gardłem w tworzeniu oprogramowania nie jest pisanie kodu, tylko wszystkie aktywności wokół kodu: definiowanie produktu, weryfikacja zachowania, ludzka akceptacja. Agenci rozwiązują pierwszą część natomiast człowiek zostaje z tą trudniejszą.

Tu zaczyna się problem z typowym podejściem. Zespół wdraża agenta, agent popełnia błąd, ktoś go ręcznie poprawia… i następnym razem agent popełnia ten sam błąd. Dlaczego? Bo korekcja nie trafiła nigdzie tylko ląduje w historii chatu, nie w pamięci systemu.

Warp zmienił tę pętlę. Każda ludzka korekcja — każde miejsce, gdzie reviewer zmienił output agenta — staje się nowym przypadkiem treningowym dla skilla, który mutuje. Agent następnym razem nie popełnia tego błędu. Dokładnie to oznacza „samouczący się agent”: nie fine-tuning modelu, lecz iteracyjna aktualizacja instrukcji w kontekście.

Efekt po sześciu miesiącach? Jest imponujący.

Co się psuje w naiwnym podejściu do agentów

Większość firm buduje agentów na bazie prompta systemowego. Jeden prompt, ogólne instrukcje, brak kontekstu o projekcie. Agent działa na tyle ogólnie, że często myli konwencje nazewnictwa, ignoruje istniejące wzorce kodu i generuje PR-y, które reviewer odrzuca w 70% przypadków.

Nie jest to wina modelu. Claude 3.7 lub Claude Sonnet 4 — nie ma znaczenia który. Bez kontekstu specyficznego dla projektu każdy model będzie zgadywać. Skille rozwiązują właśnie ten problem; dają agentowi wiedzę, której nie ma w danych treningowych.

Anatomia skilla — co dokładnie czyta agent

Skill w architekturze Warp/Oz to plik Markdown z nagłówkiem YAML i treścią w naturalnym języku. Nic więcej. Agent (lokalny lub chmurowy) skanuje kilka ścieżek w repozytorium — .agents/skills/, .claude/skills/, .warp/skills/ — i automatycznie wczytuje wszystkie znalezione skille do kontekstu przed każdym uruchomieniem.

Minimalny skill wygląda tak:

---
name: pr-review
description: Weryfikuje pull requesty według standardów Warp: testy, dokumentacja, wzorce kodu
---

# PR Review

## Kiedy używać
Uruchom przy każdym nowym PR przed zaproszeniem reviewera-człowieka.

## Instrukcje
1. Sprawdź czy każda zmiana publicznego API ma zaktualizowany docstring
2. Zweryfikuj że nowe funkcje mają testy jednostkowe (minimalnie: happy path + jeden edge case)
3. Sprawdź nazewnictwo według konwencji projektu (patrz /docs/naming.md)

## Znane problemy do sprawdzania
- Funkcje async bez obsługi timeout
- Hardcodowane ścieżki plików zamiast konfiguracji

To wygląda skromnie… ale właśnie o to chodzi. Skill nie jest promptem-molochem z pięciuset linii. To precyzyjna instrukcja dla konkretnego zadania. Agenci działający na Claude wczytują dziesiątki takich skilli jednocześnie; każdy jest mały i zarządzalny. Razem tworzą pełną wiedzę o projekcie.

Jak skille żyją w repozytorium

Skille przechowywane są w gicie. To nieoczywiste, ale bardzo ważne. Oznacza to: historia zmian, code review dla skilla przed wdrożeniem, możliwość rollbacku gdy nowa wersja skilla daje gorsze wyniki. Warp traktuje skille jak kod — bo nimi są.

Struktura plików dla projektu używającego skilli wygląda zazwyczaj tak:

twoj-projekt/
├── .agents/
│   └── skills/
│       ├── pr-review/
│       │   ├── SKILL.md
│       │   └── check_conventions.py   ← skrypt weryfikacyjny
│       ├── issue-triage/
│       │   └── SKILL.md
│       └── docs-refresh/
│           ├── SKILL.md
│           └── templates/

Budowanie pętli: od jednorazowego agenta do systemu, który rośnie

Pętla samouczącego się agenta składa się z czterech faz; Warp opisuje to w dokumentacji oz-for-oss. Każda faza produkuje dane wejściowe do następnej.

Kluczowa jest: faza 2 (weryfikacja) musi być zautomatyzowana. Jeśli każdy output wymaga człowieka do oceny, nie masz systemu — masz drogiego pracownika-pośrednika. Człowiek wchodzi tylko tam, gdzie automatyka zawodzi.

Budowanie zestawu weryfikacyjnego — konkrety

Warp kategoryzuje błędy agenta według rodzaju, nie według instancji. To fundamentalna różnica w podejściu. Zamiast naprawiać konkretny błąd w konkretnym PR, Warp pyta: „Do której kategorii błędów należy ten przypadek?” Jedna zmiana w skillu może naprawić pięćdziesiąt podobnych błędów.

Przykładowe kategorie błędów dla agenta review PR: zły dobór narzędzia, nieprawidłowy format argumentu, halucynowana ścieżka pliku, zbyt wczesne porzucenie zadania. Dla każdej kategorii istnieje co najmniej jeden test automatyczny.

W praktyce weryfikacja skilla przebiega w trzech warstwach:

• Warstwa 1 — regex i parsowanie: Najszybsza. Sprawdza czy output agenta ma prawidłową strukturę — wymagane pola, format dat, poprawne URL-e. Agent PR-reviewer powinien zawsze zwracać listę issues w formacie JSON; regex sprawdza to w milisekundach.
• Warstwa 2 — testy jednostkowe logiki: Agent dostaje przygotowane przypadki testowe z oczekiwanym outputem. Testy uruchamiają się w CI (GitHub Actions lub Vercel webhook jak w oz-for-oss). Jeśli skill zmienia zachowanie agenta w nieprzewidziany sposób, CI blokuje merge.
• Warstwa 3 — LLM-as-Judge: Najtrudniejsza do oszukania. Drugi model (lub Claude z innym promptem) ocenia jakość odpowiedzi agenta według kryteriów zdefiniowanych w skillu. W oz-for-oss ta warstwa siedzi w core/ i jest wywoływana przez webhook Vercel.

Matrix agents: kiedy jeden agent to za mało

Warp opisuje konkretny przypadek z własnej historii: odtworzenie frameworka Mermaid w Rust. Zamiast jednego agenta pracującego sekwencyjnie, Warp uruchomił piętnaście agentów równolegle — jeden per typ diagramu. Każdy pracował w osobnej zakładce terminala, na osobnym klonie repozytorium.

Każdy agent używał Computer Use do porównania swojego outputu z kanonicznym wynikiem Mermaid. Człowiek patrzył na dashboard z wynikami i wchodził tylko tam, gdzie agent raportował niepewność powyżej pewnego progu.

To jest wzorzec matrix agents: wiele agentów działających równolegle na tym samym zestawie zadań, z człowiekiem w roli supervisora, nie wykonawcy. Kilka rzeczy trzeba jednak wiedzieć zanim to wdrożysz…

Gdzie człowiek naprawdę jest potrzebny

Nie wszędzie. To jest właśnie ta nieoczywista lekcja z podejścia Warpa. Ludzki reviewer jest drogi; jego czas powinien iść na zadania, których agent nie może zrobić dobrze. Są trzy takie miejsca:

Pierwsza: definicja produktu. Agent nie wie, czego chce użytkownik — wie tylko, co mu powiedziano. Spec musi napisać człowiek (lub agent pod ścisłym nadzorem człowieka). Druga: weryfikacja zachowania w edge cases, których nikt wcześniej nie przewidział — tu ludzka intuicja jest niezbędna. Trzecia: aktualizacja skilla po błędzie systemowym — bo to wymaga decyzji o architekturze, a nie tylko dodania przykładu negatywnego.

Ale uwaga: w matrycy piętnastu agentów większość pracy idzie bez ludzkiego dotyku. Warp szacuje, że agenci piszą teraz 60% ich pull requestów. Liczba rośnie tygodniowo.

Jak zbudować własny skill z repozytorium GitHub — krok po kroku

Najszybsza ścieżka do pierwszego działającego skilla to adaptacja istniejącego wzorca. Warp utrzymuje publiczne repozytorium warpdotdev/oz-skills z gotowymi skillami do issue triage, review kodu, odświeżania dokumentacji i regularnego sprzątania dead code.

1. Sklonuj repozytorium źródłowe i znajdź skill do adaptacji.
   Użyj formatu owner/repo:skill-name żeby wywołać skill z zewnętrznego repo bez kopiowania: oz agent run --skill "warpdotdev/oz-skills:pr-review". Obserwuj co robi agent przez pierwsze kilka uruchomień.
2. Skopiuj SKILL.md do .agents/skills/nazwa-twojego-skilla/ i zacznij adaptować.
   Zmień sekcję „Znane problemy” na problemy specyficzne dla twojego projektu. Dodaj konwencje nazewnictwa. Linkuj do plików dokumentacji w repo (patrz /docs/api.md) — agent sam je wczyta.
3. Napisz skrypt weryfikacyjny jako plik Python lub Bash w tym samym katalogu.
   Minimalny skrypt: sprawdza czy output agenta jest poprawnym JSONem i zawiera wymagane pola. Odwołaj się do niego w SKILL.md w sekcji instrukcji.
4. Dodaj 3-5 przypadków testowych do CI.
   Każdy przypadek: input (opis zadania) + oczekiwany output (lub warunki które musi spełniać). Uruchom je w GitHub Actions przy każdym PR modyfikującym SKILL.md.
5. Po pierwszym tygodniu produkcyjnym: przejrzyj logi błędów i zaktualizuj skill.
   Skategoryzuj błędy. Dodaj przykłady negatywne do sekcji „Znane problemy”. Zrób PR do repo z nową wersją skilla — tak żeby cały team widział zmianę i mógł ją zaakceptować.

Skrypty weryfikacyjne: co warto sprawdzać automatycznie

Warp w architekturze oz-for-oss trzyma logikę weryfikacji w katalogu core/, a webhooki w api/. Wariant minimalistyczny — bez Vercela, bez webhooków — to proste skrypty Pythona uruchamiane w CI.

Oto co sprawdzają skrypty weryfikacyjne w typowym projekcie budującym agenty na Claude:

import re
import json

def verify_pr_review_output(agent_output: str) -> dict:
    """
    Sprawdza output agenta review PR.
    Zwraca dict z wynikiem i listą błędów.
    """
    errors = []

    # Warstwa 1: czy output jest JSON
    try:
        data = json.loads(agent_output)
    except json.JSONDecodeError:
        return {"pass": False, "errors": ["Output nie jest poprawnym JSON"]}

    # Warstwa 1: wymagane pola
    required_fields = ["issues", "severity", "recommendation"]
    for field in required_fields:
        if field not in data:
            errors.append(f"Brak wymaganego pola: {field}")

    # Warstwa 1: regex na format severity
    valid_severity = re.compile(r"^(critical|high|medium|low|info)$")
    if "severity" in data and not valid_severity.match(data["severity"]):
        errors.append(f"Nieprawidłowy format severity: {data['severity']}")

    # Warstwa 2: sprawdzenie czy issues nie jest pustą listą przy recommendation != 'approve'
    if data.get("recommendation") == "request_changes" and not data.get("issues"):
        errors.append("recommendation=request_changes wymaga niepustej listy issues")

    return {
        "pass": len(errors) == 0,
        "errors": errors,
        "issues_count": len(data.get("issues", []))
    }

Warstwa 3 (LLM-as-Judge) to osobne wywołanie API — Claude dostaje output agenta i zestaw kryteriów oceny. Ocena jest binarna lub skalowana (0-10). Przy wyniku poniżej progu (zazwyczaj 7/10) output trafia do kolejki ludzkiego reviewera. Nie jest odrzucany automatycznie; jest flagowany.

Jednak nie wszystko da się sprawdzić automatycznie. Skrypt nie wykryje sytuacji, gdzie agent napisał technicznie poprawny kod… który rozwiązuje nie ten problem. To nadal wymaga człowieka. Dobra architektura weryfikacji nie eliminuje ludzkiego nadzoru; redukuje go do przypadków, gdzie naprawdę jest potrzebny.