Zadanie. Kontekst.
Testy. Odbiór.Zadanie, kontekst, testy, odbiór

Dobre zadanie dla agenta wygląda jak dobre zadanie dla człowieka, tylko bardziej dosłowne. Ma cel (po co to robimy), zakres (co wchodzi, a co nie), kryteria odbioru (po czym poznamy, że jest gotowe) i listę rzeczy, których nie wolno ruszać.

Przykład, z którym pracujemy na webinarach:

Cel: filtrowanie listy zgłoszeń po statusie i przypisanym techniku.
Zakres: endpoint GET /tickets z parametrami status i technicianId,
        filtr w widoku listy. Bez zmian w modelu danych.
Kryteria: lista reaguje na oba filtry łącznie, puste wyniki mają komunikat,
        istniejące testy przechodzą.
Testy: testy jednostkowe filtra, jeden test e2e listy.
Nie ruszać: uprawnień, eksportu do CSV.

Zadanie, które nie mieści się w takim opisie, jest za duże. Dzielimy je na dwa, zanim oddamy agentowi. To najczęstsza poprawka, jaką robimy w zespołach na starcie.

Kontekst to wszystko, co agent musi wiedzieć o projekcie, a czego nie wyczyta z jednego pliku. Struktura katalogów, konwencje nazw, jak uruchomić testy, jakie biblioteki są w użyciu i dlaczego, czego nie wolno robić. Trzymamy to w krótkim pliku w głównym katalogu repozytorium, czytanym przez agenta na starcie każdego zadania.

Do tego dochodzą umiejętności: opisane krok po kroku sposoby wykonywania powtarzalnych czynności, na przykład „jak dodać nową migrację” albo „jak napisać nowy endpoint w tym projekcie”. Agent sięga po nie, gdy zadanie tego wymaga, zamiast wymyślać sposób od nowa.

Testy to umowa między Wami i agentem o tym, co znaczy „gotowe”. Bez nich agent kończy pracę, gdy kod wygląda dobrze. Z nimi kończy, gdy kod działa.

W praktyce: część testów pisze się przed oddaniem zadania (te, które opisują oczekiwane zachowanie), część dopisuje agent (te, które pokrywają jego rozwiązanie). Agent uruchamia komplet, a wynik dostaje od razu. Czerwony test to informacja zwrotna szybsza niż jakikolwiek przegląd kodu.

Projekt bez testów nie jest gotowy na agentów. Nie dlatego, że agent nie napisze kodu, tylko dlatego, że nikt nie będzie wiedział, czy ten kod czegoś nie zepsuł. Pierwszym zadaniem dla agenta w takim projekcie często jest dopisanie testów do tego, co już jest.

Odbiór to moment, w którym człowiek czyta zmianę i decyduje, czy trafia do głównej gałęzi. Agent otwiera pull request, opisuje, co zrobił i dlaczego, załącza wynik testów. Recenzent sprawdza to, czego testy nie sprawdzą: czy rozwiązanie pasuje do reszty systemu, czy nie ma skrótów, czy nie dopisało się coś poza zakresem.

Trzymamy się kilku zasad:

• Mała zmiana, szybki odbiór. Pull request na kilkaset linii czyta się w kwadrans, na kilka tysięcy nikt nie czyta.
• Recenzent nie poprawia ręcznie. Jeśli coś jest nie tak, wraca to do agenta jako uwaga, tak jak do kolegi z zespołu.
• Każda uwaga, która się powtarza, trafia do kontekstu albo do testów. Odbiór ma uczyć proces, nie tylko łapać błędy.

1. Ktoś z zespołu pisze opis zadania i sprawdza, czy mieści się w jednym pull requeście.
2. Agent czyta zasady projektu, sięga po potrzebne umiejętności, zakłada gałąź.
3. Agent pisze kod i testy, uruchamia komplet testów, poprawia, aż wszystko przechodzi.
4. Agent otwiera pull request z opisem. Człowiek czyta, komentuje albo scala.
5. Zespół zapisuje liczbę poprawek i czas. To dane do następnej rozmowy o kontekście.

Przy dobrze przygotowanym zadaniu całość trwa kilkadziesiąt minut, a większość tego czasu agent pracuje sam. Człowiek jest potrzebny na początku i na końcu. Jak mierzymy, czy to działa, opisujemy na stronie Mierzymy.