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

Inżynieria kontekstowa to dziedzina zajmująca się dostarczaniem agentowi sztucznej inteligencji właściwych informacji, w odpowiedniej formie i we właściwym czasie, tak aby mógł on wykonywać swoją pracę prawidłowo, zamiast polegać na domysłach. W praktyce dla większości zespołów oznacza to pliki: plik CLAUDE.mdw 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 stali 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 fragmenty są nieaktualne. Kontekst został napisany raz, kod ewoluował, a teraz połowa tego tekstu jest po cichu błędna. W tej dziedzinie istnieje etap wprowadzania danych i opisywania kontekstu, ale brakuje pętli konserwacji. Właśnie o tej luce mowa w niniejszym wpisie.

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 przez Państwa folder otrzymuje nową nazwę, zapisana przez Państwa konwencja traci ważność, a dokumentacja nadal z przekonaniem opisuje przestarzałą rzeczywistość. 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 traktuje instrukcje dosłownieCLAUDE.md. Jeśli napisano „uruchom make setup” a dany cel został usunięty w poprzednim kwartale, agent nie wzrusza ramionami. Marnuje czas, próbując uruchomić nieprawidłową operację, 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 w Państwa plikach kontekstowych nie są te wiersze, których brakuje. Są to te, które kiedyś były prawdziwe.

Potrzebują Państwo zatem pętli konserwacyjnej. Problem polega na tym, że typowe rozwiązania nie sprawdzają się. Nie będą Państwo przeprowadzać audytu CLAUDE.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 problemów. Nieaktualność ujawnia się dopiero w momencie użycia, dla tego, kto z niego korzysta. A coraz częściej tym, kto z niego korzysta, nie jest osoba.

Jedyny świadek, który wie

Oto sedno sprawy. 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 oparte na nieaktualnych danych. 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 odczuł tego skutki. To właśnie pętla sprzężenia zwrotnego – znajduje się tuż obok, a nikt z niej nie korzysta. Wystarczy poprosić agenta o zapisanie tego, czego się nauczył, przed zakończeniem sesji, oraz 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 to zapewnia podsumowanie sesji generowane przez sztuczną inteligencję. Pod koniec sesji roboczej agent sporządza krótki, szczery wpis: co poszło dobrze, gdzie pojawiły się trudności oraz – co ma tutaj kluczowe znaczenie – każda trudność jest oznaczona jedną z dziesięciu ustalonych etykiet określających przyczynę źródłową, a wpis kończy się adnotacją „→ Napraw:” o rozmiarze zgłoszenia serwisowego. 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. Jest to lista zadań do uzupełnienia w Państwa pliku kontekstowym. Każda z tych pozycji stanowi wiersz, któryCLAUDE.md powinni Państwo dodać do dokumentacji.
• incorrect-documentation****: dokumentacja istniała, ale zawierała błędy lub była nieaktualna. Jest to lista 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 treść pisma procesowego lub przepisu można interpretować na więcej niż jeden sposób. Na tym polega pętla. Nie przeprowadza się audytu plików kontekstowych według harmonogramu; pozwala się agentom, którzy z nich korzystają, wskazać w momencie użycia dokładnie, które wiersze należy zmienić, wraz z dołą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 punktów, w których agent wypełnił lukę za pomocą przypuszczenia. Każdy domysł to miejsce, w którym Państwa kontekst był na tyle skąpy, że agent musiał wymyślić odpowiedź. Przejrzyj domysły z całego tygodnia, a uzyskasz listę zadań 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 format zwracanych wyników. 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ą pracownik faktycznie uruchomi, ponieważ praca związana z wykryciem problemu – czyli najbardziej czasochłonna część zadania – została już wykonana.

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

Można by spróbować aktualizować pliki kontekstowe w starym stylu: zaplanować przegląd, przeczytać je od początku do końca, zweryfikować każde stwierdzenie w świetle rzeczywistości. Tak się jednak nie dzieje, a nawet jeśli tak się dzieje, to jest to niewłaściwe narzędzie. Czytając dokument w oderwaniu od kontekstu, nie da się stwierdzić, które wiersze są nieaktualne. Wszystkie brzmią wiarygodnie. Nieaktualność ujawnia się dopiero w trakcie użytkowania. Dziennik retrospektywny to konserwacja kontekstu napędzana rzeczywistym użytkowaniem: 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 czytać to, co już jest w porządku. Jest 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 tymi kwestiamiincorrect-documentation, sesje w przyszłym tygodniu będą w mniejszym stopniu napotykać tę przeszkodę, dzięki czemu dziennik będzie się skracał, a uwaga skupi się na głębszych problemach. Państwa pliki kontekstowe stają się coraz dokładniejsze nie dlatego, że ktoś je kontrolował, ale dlatego, że osoby i agenci, którzy z nich korzystają, mieli do dyspozycji prosty, ustrukturyzowany sposób 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ący element: pętla konserwacji, 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 formie streszczenia 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 praktyki: jak zbierać informacje zwrotne od agentów AI obejmuje wszystkie dziesięć etykiet, weryfikację przez człowieka oraz sposób, w jaki wprowadzone dane są wykorzystywane w retrospektywie zespołu, a nie tylko w plikach kontekstowych.
• Przyjrzyjmy się bliżej samej pętli: pętle sprzężenia zwrotnego agentów przedstawiają całościowy obraz sytuacji: pętlę „wykrycie–naprawa”, narzędzia, które ją obsługują, oraz miejsce, jakie zajmuje w niej sesja.

Warto zwrócić uwagę na jedną kwestię. Gdy agent zgłasza, że dokumentacja jest błędna, należy to sprawdzić przed wprowadzeniem zmian, ponieważ czasami dokumentacja jest poprawna, a agent ją źle 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ę uczestnika, który sygnalizuje, co wzbudziło jego wątpliwości, ale nigdy nie jest autorytetem w kwestii tego, co powinien zawierać Państwa projekt.

Jakość Państwa plików kontekstowych zależy wyłącznie od ostatniej rzetelnej korekty. 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 zalecenia 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ół.