Inżynieria kontekstowa wymaga pętli sprzężenia zwrotnego

Inżynieria kontekstowa to dziedzina zajmująca się dostarczaniem agentowi sztucznej inteligencji odpowiednich informacji, w odpowiedniej formie i we właściwym czasie — tak, aby wykonywał on swoją pracę prawidłowo, zamiast polegać na domysłach. W praktyce dla większości zespołów oznacza to pliki: plikCLAUDE.md w katalogu głównym repozytorium, plik AGENTS.md, folder zawierający zasady i konwencje oraz komunikat systemowy, który ktoś kiedyś dostosował. Opisują Państwo, jak działa Państwa projekt, aby agent nie musiał odkrywać tego na nowo przy każdej sesji.

To naprawdę najskuteczniejszy sposób, jaki można zastosować, aby agenci stały się użyteczni. Niemal każdy, kto to robi, boryka się z tym samym niewypowiedzianym problemem: pliki te tracą aktualność, a nikt nie wie, które ich fragmenty. Kontekst został napisany raz, kod ewoluował, a teraz połowa tych informacji jest po cichu błędna. W tej dziedzinie istnieje etap wprowadzania danych — opisywanie kontekstu — ale brakuje pętli konserwacyjnej. Właśnie tej luki dotyczy niniejszy wpis.

Kontekst to kod, a kod ulega degradacji

Wiemy już, że dokumentacja traci na aktualności. Opisany przez Państwa etap kompilacji zostaje zastąpiony, opisany folder zmienia nazwę, zapisane przez Państwa zasady zostają unieważnione — a dokumentacja nadal z przekonaniem opisuje dawny stan rzeczy. Pliki kontekstowe są pod tym względem gorsze od zwykłej dokumentacji z dwóch powodów.

Po pierwsze, agent interpretuje je dosłownie i działa zgodnie z nimi. Człowiek przegląda nieaktualny plik README, wyczuwa, że coś tu nie gra, i zwraca się z pytaniem do kogoś. Agent traktujeCLAUDE.md instrukcje dosłownie. Jeśli napisano „uruchom make setup” , a dany cel został usunięty w poprzednim kwartale, agent nie wzrusza ramionami — marnuje czas, próbując sprawić, by nieprawidłowa operacja zadziałała, albo wymyśla obejście i kontynuuje pracę, przenosząc błędną instrukcję do swoich wyników.

Po drugie, nieprawidłowy kontekst jest gorszy niż brak kontekstu. W przypadku luki agent potrafi czasem wywnioskować brakujące informacje lub je zidentyfikować. Natomiast w przypadku błędnego stwierdzenia, które wydaje się pewne, agent mu ufa. Najbardziej kosztowne wiersze w Państwa plikach kontekstowych to nie te, których brakuje — są to te, które kiedyś były prawdziwe.

Potrzebna jest więc pętla konserwacyjna. Problem polega na tym, że typowe rozwiązania nie sprawdzają się. Nie będzie Pan przeprowadzał audytuCLAUDE.mdwiersz po wierszu zgodnie z harmonogramem — nikt tego nie robi. Z zewnątrz nie zauważy Pan, że kod jest nieaktualny, ponieważ czyta się go bez zarzutu. Nieaktualność ujawnia się dopiero w momencie użycia, dla tego, kto z niej korzysta. A coraz częściej tym, kto z niej korzysta, nie jest osoba.

Jedyny świadek, który wie

Oto zasadnicza zmiana. Agent, który właśnie przeprowadził sesję w ramach Państwa projektu, jest jedynym uczestnikiem, który wie konkretnie, które elementy Państwa kontekstu okazały się pomocne, a które wprowadziły go w błąd. Wykorzystał on po prostu pliki. Wydał polecenie kompilacji, które okazało się nieaktualne. Znalazł folder, który nie istnieje. Postępował zgodnie ze wzorcem, który okazał się składać z trzech wzorców. Ta wiedza istnieje — mniej więcej tak długo, jak trwa sesja, a potem znika.

Nikt nie wskaże Panu, który kontekst jest niekompletny lub błędny, z wyjątkiem samego systemu, który właśnie na tym ucierpiał. To właśnie pętla sprzężenia zwrotnego — znajduje się tuż obok, a nikt z niej nie korzysta. Wystarczy poprosić agenta, aby przed zakończeniem sesji zapisał to, czego się nauczył — i sformułować prośbę w taki sposób, aby wynik wskazywał bezpośrednio na pliki wymagające edycji.

Dziennik retrospektywny sesji stanowi pętlę konserwacyjną

Właśnie taki jest wynik podsumowania sesji generowanego przez sztuczną inteligencję. Pod koniec sesji roboczej agent sporządza krótki, szczery wpis: co poszło dobrze, gdzie pojawiły się utrudnienia oraz — co ma tutaj kluczowe znaczenie — każda z tych trudności jest oznaczona jedną z dziesięciu stałych etykiet określających przyczynę źródłową i kończy się adnotacją „→ Napraw:” wielkości zgłoszenia. Dwie z tych dziesięciu etykiet odnoszą się bezpośrednio do Państwa plików kontekstowych:

• missing-documentation**** — agent potrzebował informacji, które powinny były zostać udokumentowane w ramach projektu, a nie zostały. To jest lista zadań do wykonania zawarta w Państwa pliku kontekstowym. Każda z tych pozycji to wiersz, który powinni Państwo dodać doCLAUDE.md dokumentacji.
• incorrect-documentation**** — dokumentacja istniała, ale zawierała błędy lub była nieaktualna. Oto lista elementów do poprawienia w Państwa pliku kontekstowym. Każda z tych pozycji to nieaktualny wiersz, który agent wykrył w jedyny możliwy sposób: wykorzystując go i napotykając przeszkodę.

Dodajcie jeszcze trzeci element, a pokryjecie większość czynności konserwacyjnych, jakie kiedykolwiek będą Państwo musieli wykonać: ambiguous-instruction****, czyli sytuacje, w których instrukcję lub zasadę można interpretować na więcej niż jeden sposób. Na tym polega pętla. Nie przeprowadza się audytu plików kontekstowych zgodnie z harmonogramem; pozwala się agentom, którzy z nich korzystają, poinformować w momencie użycia, które dokładnie wiersze należy zmienić — wraz z załączonymi dowodami, ponieważ praktyka ta opiera się wyłącznie na przytoczonych dowodach.

Istnieje też czwarty sygnał, który łatwo przeoczyć: domysły. Dobry wpis zawiera wykaz wszystkich miejsc, w których agent wypełnił lukę za pomocą przypuszczenia. Każdy domysł to miejsce, w którym Państwa kontekst był na tyle ubogi, że agent musiał wymyślić odpowiedź. Przejrzyj domysły z całego tygodnia, a otrzymasz listę zadań do wykonania dotyczących plików kontekstowych, której sam nigdy byś nie sporządził — ponieważ znasz już odpowiedzi i dlatego nie dostrzegasz, gdzie ich brakuje.

Oto przykładowy wynik — jest to przykład ilustracyjny, a nie rzeczywiste dane:

## Friction
- CLAUDE.md says "run `make setup`" but that target was removed; the
  actual setup is `pnpm install && pnpm db:migrate`. Lost ~10 min.
  (incorrect-documentation)
  → Fix: Update the "Getting started" block in CLAUDE.md to the pnpm commands.
- Nothing documents that integration tests need the worker running.
  Found it by reading the CI config. (missing-documentation)
  → Fix: Add a "Running tests" note naming `pnpm worker` as a prerequisite.

## Guesses I made
- Assumed the `api/` package is the public surface and `internal/` is not,
  because nothing states it. Please confirm before I rely on it again.

Każda linia odpowiada konkretnej zmianie w konkretnym pliku. Jest to pętla konserwacyjna, którą osoba faktycznie uruchomi, ponieważ praca związana z wykryciem problemu — czyli najbardziej czasochłonna część — została już wykonana.

Dlaczego to rozwiązanie jest lepsze od ręcznego przeprowadzania audytu

Można by spróbować aktualizować pliki kontekstowe w tradycyjny sposób: zaplanować przegląd, przeczytać je od początku do końca i zweryfikować każde stwierdzenie w świetle rzeczywistości. Tak się jednak nie dzieje, a nawet jeśli tak się stanie, to nie jest to właściwe narzędzie. Czytając dokument w oderwaniu od kontekstu, nie da się stwierdzić, które wiersze są nieaktualne — wszystkie wydają się wiarygodne. Nieaktualność ujawnia się dopiero podczas użytkowania. Dziennik retrospektywny to konserwacja kontekstu oparta na rzeczywistym użytkowaniu: oznaczane są wyłącznie te wiersze, które faktycznie spowodowały błąd agenta, dzięki czemu naprawia się to, co rzeczywiście nie działa, zamiast ponownie przeglądać to, co już działa poprawnie. To różnica między czujnikiem dymu a przemierzaniem budynku w poszukiwaniu dymu.

Efekt ten ma charakter kumulacyjny. Jeśli w tym tygodniu uporają się Państwo z tymiincorrect-documentationkwestiami, podczas sesji w przyszłym tygodniu w mniejszym stopniu napotkają Państwo tę przeszkodę, dzięki czemu protokół stanie się krótszy, a uwaga skupi się na głębszych problemach. Państwa pliki kontekstowe stają się coraz dokładniejsze nie dlatego, że ktoś je poddał audytowi, ale dlatego, że osoby — oraz agenci — korzystające z nich dysponowały prostym, ustrukturyzowanym sposobem zgłaszania odchyleń. To zdrowa współpraca między człowiekiem a sztuczną inteligencją: agent sygnalizuje odchylenie, a człowiek decyduje o wprowadzeniu poprawek.

Rozpocznij pętlę

Jeśli już inwestują Państwo w inżynierię kontekstową, oto brakująca połowa — pętla utrzymania, która zapobiega utracie wartości tej inwestycji. Jest to oprogramowanie typu open source na licencji MIT:

• Pobierz pakiet umiejętności i podpowiedzi: github.com/TeamRetroHQ/teamretro-skills — umiejętność Claude Code, która tworzy wpis podsumowujący sesję, umiejętność syntetyzująca wpisy w krótkie podsumowanie oraz pakiet podpowiedzi niezależny od narzędzia, przeznaczony dla Cursora, GitHub Copilota lub dowolnego agenta, któremu można podawać podpowiedzi.
• Zapoznaj się z pełnym opisem procedury: jak zbierać informacje zwrotne od agentów AI obejmuje wszystkie dziesięć etykiet, weryfikację przez człowieka oraz sposób, w jaki zebrane dane są wykorzystywane podczas retrospektywy zespołu — a nie tylko w plikach kontekstowych.

Warto zwrócić uwagę na jedną kwestię. Gdy agent zgłasza, że dokumentacja jest błędna, należy to sprawdzić przed wprowadzeniem zmian — czasami to dokumentacja jest poprawna, a agent ją błędnie zinterpretował. Nadal jest to przydatna wskazówka (zdanie, które łatwo błędnie zinterpretować, warto przeredagować), ale wymaga to innego rodzaju poprawki i właśnie dlatego w procesie tym nadal uczestniczy człowiek. Agent pełni rolę osoby sygnalizującej, co wzbudziło jego wątpliwości, a nigdy nie jest autorytetem decydującym o tym, co powinien zawierać Państwa projekt.

Jakość Państwa plików kontekstowych zależy wyłącznie od ostatniej rzetelnej poprawki, jaką w nich wprowadzono. Agenci korzystający z tych plików przekazują Państwu te poprawki pod koniec każdej sesji — wystarczy je tylko zapisać. A jeśli Państwa zespół chce, aby te poprawki trafiły w miejsce, które jest już przez wszystkich przeglądane, agent może przygotować swoje rekomendacje i samodzielnie opublikować je na Państwa tablicy za pośrednictwem serwera TeamRetro MCP — po potwierdzeniu przez Państwa i oznaczeniu [AI retro]symbolem obok pozostałych usprawnień zgłoszonych przez zespół.