Brief brzmi: „popraw formularz, żeby był nowoczesny”. Agent zmienia kolory, bibliotekę, walidację i trzy komponenty obok. Interfejs rzeczywiście wygląda nowocześniej. Formularz przestał wysyłać zgłoszenia. Zadanie było krótkie, ale zakres nieograniczony.
Agent kodujący potrzebuje wyniku, granic i testów. Nie musi znać całej historii projektu, ale musi wiedzieć, czego nie wolno zmienić i jak udowodnić skutek. Brief jest kontraktem pracy, nie życzeniem.
Zacznij od skutku dla użytkownika
Zapisz, co ma działać po zmianie: poprawne zgłoszenie z polskimi znakami, szybsze wyszukiwanie, działający eksport, brak duplikatu. „Popraw UX” nie jest kryterium. Opisz rzeczywisty przypadek i wynik.
Podaj kontekst użytkownika i urządzenia, jeżeli wpływa na zadanie. Formularz mobilny z klawiaturą ma inne ryzyko niż tabela administracyjna. Nie wymagaj pełnej dokumentacji produktu, gdy wystarczy konkretna ścieżka.
Oddziel wymagane rezultaty od preferencji. Może animacja jest opcjonalna, ale dostępność i brak błędów są warunkiem. Agent powinien wiedzieć, czego nie wolno poświęcić dla efektu wizualnego.
W przykładzie formularza opisz też, co użytkownik powinien zobaczyć po błędzie wysyłki i co stanie się z wpisanymi danymi.
Ogranicz zakres plików i decyzji
Wypisz komponenty lub moduły kandydackie i te, których nie wolno zmieniać. Nie ograniczaj sztucznie, jeżeli zależności są nieznane. Zaznacz, że nowe pliki wymagają uzasadnienia i pozostają w zakresie zadania.
Zapisz, które decyzje należą do człowieka: zmiana modelu danych, API, biblioteki, uprawnień, publikacji. Agent może zaproponować, ale nie wykonywać ich automatycznie. Bez tego „mała poprawka” rozrasta się w migrację.
Dodaj warunek zatrzymania przy konflikcie lub braku źródła. Agent powinien zgłosić pytanie zamiast zgadywać oczekiwane zachowanie. Pytanie jest wynikiem roboczym, nie porażką.
Podaj źródła prawdy
Dołącz aktualny kod, kontrakt API, przykładowe dane, zasady projektu i właściwą dokumentację. Oznacz wersje. Nie przesyłaj losowego folderu z nadzieją, że agent wybierze właściwe pliki.
Jeżeli istnieją testy i konwencje, wskaż je. Agent powinien używać istniejących wzorców zamiast wprowadzać nowe dla jednej funkcji. Przy zmianie konwencji wymagaj osobnej decyzji.
Ogranicz sekrety i dane produkcyjne. Użyj fikcyjnych tokenów, kont i danych testowych. Przy poufności pomocne są zasady z artykułu o bezpiecznych uprawnieniach agentów AI.
Zdefiniuj przypadki przed kodem
Zapisz poprawny, błędny, graniczny i dostępnościowy przypadek. Dla formularza: typowe zgłoszenie, błędny e-mail, polskie znaki, timeout, podwójne kliknięcie, klawiatura. Każdy ma oczekiwany skutek.
Nie opisuj tylko ścieżki szczęśliwej. Agent może zoptymalizować kod pod demo i zostawić awarie. Test powinien obejmować rzeczywiste źródło błędów i skutek zewnętrzny.
Przy zadaniu integracyjnym dodaj idempotencję i wersję kontraktu. Zasady opisuje przewodnik o ponowieniach integracji AI. Bez nich test jednostkowy może przechodzić przy duplikatach produkcyjnych.
Ustal komendy i środowisko
Podaj sposób instalacji, lint, testy, build i uruchomienie. Zapisz wymagane wersje narzędzi bez sekretów. Agent nie powinien zmieniać konfiguracji projektu tylko po to, by przechodzić lokalny build.
Nie pozwalaj na instalowanie nowych zależności bez uzasadnienia. Każda zwiększa koszt utrzymania i powierzchnię ryzyka. Przy konieczności zapisz powód, licencję i skutek.
Test ma być wykonany na rzeczywistym środowisku projektu, nie tylko na fragmencie w odpowiedzi modelu. Agent powinien raportować wyniki i ograniczenia, a nie pisać „powinno działać”.
Przykład briefu: formularz zgłoszenia
Cel: poprawne jednokrotne zgłoszenie z polskimi znakami i jasnym błędem integracji. Zakres: komponent formularza i endpoint, bez zmiany design systemu. Dane: fikcyjne konto i przykładowy payload. Zgody analityczne bez PII pozostają bez zmian.
Testy: desktop, telefon, klawiatura, błędny e-mail, długi opis, 400, 401, 429, 500, timeout i podwójne kliknięcie. Oczekiwany skutek: jeden rekord, czytelny status, brak fałszywego sukcesu, brak duplikatów zdarzeń.
Odbiór: diff, testy zależne, pełna ścieżka publiczna i sprawdzenie skrzynki. Nowe zależności wymagają decyzji człowieka. To jest konkretne zadanie, nie „ulepsz formularz”.
Odbiór kodu według zakresu
Najpierw sprawdź, czy agent zmienił tylko uzgodnione elementy i zachował cudzą pracę. Duży diff z wieloma plikami wymaga uzasadnienia. Nie akceptuj refaktoryzacji przy okazji bez decyzji.
Potem przeczytaj krytyczne decyzje: dane, uprawnienia, błędy, format, skutki uboczne. Nie zakładaj, że testy obejmują wszystko. Przegląd kodu AI powinien być równie dokładny jak innych autorów.
Po testach sprawdź publiczny wynik. Build i lint nie wystarczają przy interakcji i integracjach. Zasady opisuje także przewodnik o odbiorze kodu z AI, ale odbiór zawsze kończy się rzeczywistym zachowaniem.
Zachowaj mały eksperyment
Przy nowym agencie zacznij od ograniczonego zadania bez dostępu do produkcji. Sprawdź jakość briefu, zakres zmian i wynik. Nie dawaj od razu migracji całego systemu. Pierwszy brief powinien być odwracalny.
Zapisz, gdzie agent zgadywał i jakich informacji brakowało. Popraw brief lub źródło, nie tylko kod. Jeżeli zadanie było niejasne, nowy model może popełnić podobny błąd.
Po sukcesie zwiększ jeden wymiar: zakres plików lub trudność przypadku. Nie zmieniaj wszystkiego naraz. To pozwala ocenić proces zamiast przypisywać sukces ogólnej „inteligencji”.
Czego nie wpisywać do briefu
Nie dodawaj życzeń „zrób dobrze”, „bądź kreatywny”, „nie zepsuj niczego”. Nie opisują skutku ani ograniczenia. Zastąp je konkretnymi warunkami i testami.
Nie wpisuj sekretów, haseł, prywatnych danych i pełnej historii klientów. Brief może być współdzielony i wersjonowany. Powinien zawierać minimum potrzebne do pracy.
Nie wymagaj pełnej analizy wszystkich możliwych rozwiązań przy małym zadaniu. To zwiększa koszt i tworzy niepotrzebne zmiany. Brief ma ograniczać decyzje do właściwego procesu.
Kiedy zatrzymać agenta
Zatrzymaj przy żądaniu nowych uprawnień, konflikcie źródeł, zmianie kontraktu, niejasnym skutku i niemożności wykonania testów. Agent powinien opisać blokadę i możliwe pytania. Nie pozwól mu obejść problemu nowym założeniem.
Przy błędzie nie żądaj automatycznej serii poprawek bez oceny. Każda może zmieniać kolejne pliki i zwiększać zakres. Ogranicz zadanie albo przygotuj cofnięcie wyłącznie własnych zmian po sprawdzeniu różnic. Zachowaj wcześniejszą pracę innych osób i uzgodnij zakres odtworzenia.
Jeżeli kod działa przypadkowo, ale nikt nie rozumie decyzji, nie publikuj. Odbiór powinien wyjaśnić zachowanie i koszt utrzymania. To jest wymóg dla kodu ludzkiego i generowanego.
Warunki odbioru briefu przed wdrożeniem
Zapisz zakres diff, wykonane testy, przypadki niezależne, ograniczenia i wersję środowiska. Dodaj link do briefu i źródeł. Osoba odbierająca powinna widzieć, co było celem i co zostało sprawdzone.
Przy wdrożeniu zachowaj rollback i właściciela. Publikacja nie kończy briefu; kończy go rzeczywisty wynik i brak regresji. Nowe błędy trafiają do kolejnych przypadków testowych.
Jak opisać to, czego nie wolno zmienić
Wypisz stabilne kontrakty: format API, zachowanie użytkownika, pola danych, uprawnienia i istniejące testy. Nie wystarczy „nie zepsuj reszty”. Agent powinien wiedzieć, które zachowania są chronione nawet jeśli kod wygląda na przestarzały.
Jeżeli obejście wymaga zmiany kontraktu, przygotuj osobny proces decyzji. Nie ukrywaj go w zadaniu poprawki. To pomaga zachować zakres i pozwala właścicielowi ocenić koszt migracji.
Dodaj przypadki, które mają pozostać identyczne. Na przykład stary klient API nadal otrzymuje tę samą odpowiedź, a nowa funkcja działa tylko za zgodą. Test powinien potwierdzić brak zmiany, nie tylko nową funkcję.
Kiedy agent proponuje większy zakres
Traktuj propozycję jako osobny wynik do oceny, nie jako automatyczną zgodę. Może refaktoring jest sensowny, ale wymaga innego briefu i testów. Zapisz go do późniejszej decyzji i ogranicz obecną pracę.
Jeżeli bez większej zmiany zadanie nie ma sensu, zatrzymaj i omów koszt. Nie pozwól, by agent udowadniał konieczność przez wykonanie połowy migracji. Zakres powinien zostać zmieniony przed kodem.
Przy odbiorze porównaj wynik z pierwotnym briefem. Nowe pliki i zależności muszą mieć uzasadnienie. Nie akceptuj rozszerzenia tylko dlatego, że kod już istnieje.
Jak ocenić sam brief
Po wykonaniu zadania zapisz, które pytania zadał agent i gdzie zgadywał. To wskazuje braki w źródłach i warunkach. Popraw je przed kolejnym zadaniem zamiast tylko dopisywać nowe ograniczenia.
Poproś inną osobę o opisanie oczekiwanego wyniku na podstawie briefu. Jeżeli rozumie go inaczej, tekst jest niejednoznaczny. Model nie jest dobrym jedynym recenzentem, bo może dopowiadać intencję autora.
Sprawdź długość i koszt przygotowania. Brief nie może być większym projektem niż zadanie. Jeżeli wymaga tygodnia analizy dla prostej poprawki, ogranicz go do kluczowych ryzyk i źródeł.
Przy kolejnych zadaniach zachowaj wspólny szablon bez danych i osobne wersje briefu. Nie kopiuj poprzedniego dokumentu z nieaktualnymi warunkami. Każdy powinien wskazywać źródło, wersję kodu i właściciela odbioru. Zmiana jednego wymagania powinna być widoczna w historii.
Jeżeli agent wykonuje pracę dobrze bez dużego briefu, nie rozbudowuj go dla zasady. Dopisz tylko ograniczenia wymagane przy nowym ryzyku. Dobry dokument jest tak krótki, jak pozwala na bezpieczny odbiór.
Przy zakończeniu zadania zapisz nowe przypadki do testów i decyzje odrzucone. To jest materiał dla kolejnego briefu. Dzięki temu zespół nie zaczyna od pustej strony ani nie powtarza wykluczonych rozwiązań bez powodu.
Przy odbiorze briefu przed uruchomieniem sprawdź, czy każda reguła ma źródło i właściciela. Nie przepisuj niejasnych uwag z kanału jako wymagań. Jeżeli coś jest preferencją, oznacz ją inaczej niż warunek odbioru.
Zachowaj wersję kodu przed startem i sposób powrotu. Agent powinien pracować na kontrolowanej kopii bez wpływu na produkcję. Po zadaniu porównaj zmianę z bazą i zachowaj niezależne poprawki zespołu.
Przy nowym właścicielu oddaj brief i wynik poprzedniego zadania. To pozwala zachować zakres decyzji i nie zmieniać procesu tylko z powodu nowej osoby lub nowego modelu.
Przy odbiorze końcowym sprawdź, czy raport agenta nie obiecuje więcej niż wykonane testy. Jeżeli jakiegoś przypadku nie uruchomiono, zapisz go jako ograniczenie. Nie akceptuj „wszystko działa” na podstawie samego buildu.
Zachowaj dowody komend i skutku dla właściciela. Brief powinien prowadzić do wyniku, a nie zostać jedynym źródłem wiedzy o wykonanej pracy.
Przy odbiorze końcowym porównaj wynik z briefem i ograniczeniami. Zapisz niewykonane przypadki jako otwarte, a nie jako zaliczone.
Aeneia Audit pomaga ograniczyć zakres i uprawnienia. Przy pracy agentów pomocny jest przewodnik Aeneia Signal o odbiorze kodu.
Przed przekazaniem zadania wskaż bazową wersję kodu i sposób sprawdzenia wyniku. Po odbiorze zachowaj dowody wykonanych prób, a przypadki pominięte zapisz jako otwarte. Nie dopisuj testom wyniku, którego nie potwierdzono uruchomieniem.
Sprawdź nas. To zdrowe.
Temat zmienia się szybko. Linki prowadzą do źródeł pierwotnych i stron, na których możesz zweryfikować kontekst.
