Gdzie powinna zostać wprowadzona poprawka?

Dwie drużyny, takie samo napięcie, inna kwarta

Obie drużyny zaczynają rejestrować trudności, z jakimi borykają się ich agenci sztucznej inteligencji: niejasne zapytania, nieaktualna dokumentacja, zawodne narzędzia, konieczność ponownego uruchamiania zadań.

Pierwszy zespół rozwiązuje wszystkie problemy na najbliższym poziomie. Każda powtarzająca się niedogodność staje się okazją do drobnej poprawki lub notatki przypominającej; wszystko, co wykracza poza ten zakres, staje się kolejnym akapitem w pliku kontekstowym. Trzy miesiące później ich agenci działają w oparciu o rozbudowane instrukcje, których nikt nie czyta od początku do końca, a istotne utrudnienia (szablon briefu, który nie określa zakresu zadań, konto reklamowe, którego struktura utrudnia każdą sesję) nadal istnieją, ponieważ żadna doraźna poprawka nie jest w stanie ich rozwiązać.

Drugi zespół zadaje jedno dodatkowe pytanie dotyczące każdego wzorca: gdzie właściwie należy umieścić to rozwiązanie? Klaster „agenci wciąż próbują odgadnąć, kim jest nasza grupa docelowa” przekształca się w zmianę sposobu przekazywania wytycznych dotyczących pracy: poprawkę procesową, uzgodnioną podczas spotkania zespołu. Klaster „przestarzały podręcznik operacyjny” przekształca się w poprawkę dotyczącą dokumentacji, za którą odpowiada konkretna osoba. Jednorazowa anomalia staje się jedynie notatką przypominającą i niczym więcej. Trzy miesiące później ich pliki instruktażowe są krótsze niż na początku, a liczba kategorii utrudnień, które udało się wyeliminować, wykazuje tendencję spadkową.

Różnica nie polega na dyscyplinie w prowadzeniu dziennika. Obie drużyny prowadziły dzienniki. Różnica dotyczy kwestii wytyczenia trasy, o którą pierwsza drużyna nigdy nie zapytała.

Kluczowy manewr: punkty tarcia na wysokości

Gdy sesja wspomagana przez sztuczną inteligencję napotyka przeszkodę, jej pierwotna przyczyna wskazuje na poziom, na którym znajduje się trwałe rozwiązanie. Nazywamy to poziomem rozwiązania; dostępne poziomy obejmują zarówno rozwiązania doraźne, jak i strukturalne:

pamięć → umiejętności/wskazówki → otoczenie i konfiguracja → dokumentacja → sam materiał roboczy → proces/przebieg pracy → produkt lub dostawca wyższego szczebla

Określenie zakresu problemu pozwala przekształcić skargę w zadanie, które można przyporządkować konkretnej osobie. „Agent ponownie popełnił błąd w strategii ustalania stawek” to skarga. „Decyzja dotycząca strategii ustalania stawek nie została nigdzie zapisana w sposób dostępny dla agenta: należy poprawić dokumentację, a oto podręcznik operacyjny, w którym należy ją umieścić” to zadanie z jasno określonym adresatem.

Błędne określenie zakresu ma negatywne skutki w dwóch kierunkach. Niedostateczny zakres – prywatna notatka służąca jako zastępstwo faktycznie brakującego dokumentu zespołowego – oznacza, że problem ten powraca dla wszystkich oprócz Państwa: stanowi to obciążenie związane z powtarzaniem się tego problemu dla reszty zespołu. Notatki, które już w ten sposób utknęły, można odzyskać dzięki zbiorowemu przeglądowi pamięci w całym zespole. **Nadmierne ukierunkowanie (nowa umiejętność na potrzeby jednorazowego zadania, kolejny akapit w i tak już przeładowanym pliku kontekstowym) stanowi obciążenie związane z utrzymaniem artefaktu; w branży precyzyjnie nazwano te antywzory: rozrost umiejętności (16→48 umiejętności w ciągu 15 dni: „Dodawanie umiejętności jest łatwe. … Trudne jest zarządzanie.”) oraz nadmierne rozrost pliku kontekstowego („plik pamięci, który przestał być czytany”, zgodnie z niniejszą notatką terenową). Dostawcy zbliżyli się do tego samego podejścia z drugiej strony: ograniczają znaczenie pamięci efemerycznej, promując trwałe uczenie się w ramach kontroli wersji: Windsurf/Devin („zapisz to jako regułę lub dodaj do pliku AGENTS.md… zamiast polegać na automatycznie generowanych wspomnieniach”, dokumentacja), OpenAI Codex („gdy Codex popełni ten sam błąd dwukrotnie, należy poprosić go o retrospektywę i zaktualizować plik AGENTS.md”, najlepsze praktyki), celowe 28-dniowe wygaśnięcie pamięci Copilot.

W branży znane są zatem oba rodzaje awarii. Brakowało jedynie urządzenia do wyznaczania tras.

Stały zestaw słów, który kieruje

Nasza propozycja robocza: przypisanie do każdego zidentyfikowanego utrudnienia dokładnie jednej przyczyny źródłowej z ustalonego zestawu dziesięciu etykiet podzielonych na pięć grup: zestaw ten jest na tyle niewielki, że można go zapamiętać; etykiety odnoszą się raczej do przyczyn niż do objawów; są one celowo niezależne od konkretnych narzędzi i dyscyplin:

• Odprawa: ambiguous-instruction, missing-context, incorrect-context, changed-requirements
• Dokumentacja: missing-documentation, incorrect-documentation
• Materiały robocze: work-material-friction
• Oprzyrządowanie: missing-access-or-tool, environment-friction
• Agent: agent-error

Grupa stanowi klucz routingu. W momencie oznaczenia wyniku jest on już w połowie skierowany:

Dominacja w grupie	Poprawka zazwyczaj znajduje się pod adresem	Typowe artefakty
Odprawa	proces (sposób przekazywania wytycznych dotyczących pracy) lub pamięć trwała	szablon krótkiego sprawozdania, lista kontrolna na rozpoczęcie projektu, plik z materiałami
Dokumentacja	dokumenty	Plik README, instrukcja postępowania/procedura operacyjna (SOP), plik kontekstowy, specyfikacja
Materiały robocze	sam materiał	kod: refaktoryzacja, na którą nieustannie wskazuje „friction”; elementy niebędące kodem: restrukturyzacja konta, tablicy lub szablonu
Oprzyrządowanie	environment/config lub upstream	ustawienia, konfiguracja MCP, zezwolenie na dostęp, zgłoszenie dostawcy
Agent	komenda, umiejętność lub zabezpieczenie	edycja umiejętności, hook, eval

Na wstępie jedna uwaga dotycząca rzetelności: grupy zostały nazwane na cześć miejsc docelowych pomiarów, więc stwierdzenie, że „etykieta w połowie wyznacza trasę pomiaru”, jest prawdziwe z samej natury rzeczy – jest to raczej wybór projektowy niż odkrycie empiryczne. Leżącym u podstaw twierdzeniem empirycznym jest to, że etykiety z czasem przechwycenia są dokładne i spójne, a właśnie tego jeszcze nie zmierzyliśmy (więcej poniżej).

Tabela nadaje poprawce jej pierwszy adres, a powtórzenie może ją przenieść. Gdy po wprowadzeniu poprawki w dokumentacji lub pliku kontekstowym ponownie pojawia się problem, prawdopodobnie tekst nie działa prawidłowo. Przenieś poprawkę do mechanizmu zabezpieczającego: haka lub kontroli CI, które zapewnią jej utrzymanie niezależnie od tego, czy ktoś ją przeczyta, czy nie. Jest to ta sama logika, co przy wyborze wyzwalacza przechwytywania: przestrzeganie konwencji zależy od tego, czy ktoś o niej pamięta, a hak – nie.

Proszę zwrócić uwagę na to, co obejmujework-material-friction to pojęcie, ponieważ właśnie w tym zakresie słownictwo to zasługuje na miano niezależnego od konkretnej dziedziny. W kodzie jest to dług techniczny: moduł, o który potyka się każda sesja. Poza światem kodu zjawisko to jest równie realne. Wyobraźcie sobie zespół marketingowy, którego pracownik przeprowadza audyt konta Google Ads, które rozrosło się w wyniku stopniowego gromadzenia się elementów: trzy generacje konwencji nazewniczych, wstrzymane kampanie, których nikt nie ma odwagi usunąć, oraz słowa kluczowe powielone w nakładających się grupach reklam. Podczas każdej sesji konsultant poświęca początkowy czas na ustalenie, która kampania jest odpowiedzialna za co, a każda rekomendacja zawiera zastrzeżenie. Żadne doraźne rozwiązanie tego nie naprawi; żadna notatka nie ułatwi zadania kolejnej osobie. Etykietą jest work-material-friction, zawsze powiązana z konkretnym materiałem, na który wskazuje (to konto), a sednem sprawy jest sam materiał: ta restrukturyzacja, na którą nieustannie wskazuje to utrudnienie. Ten sam schemat występuje w splątanych arkuszach kalkulacyjnych, chaosie szablonów CMS oraz bibliotekach makr wsparcia; pętla w postaci agenta programistycznego nie ma gdzie tego umieścić.

Dlaczego stała, a nie wyłaniająca się? Ponieważ dla zespołu taksonomia stanowi narzędzie koordynacji, a nie ćwiczenie z klasyfikacji. Stwierdzenie „Te same trudności występujące w ośmiu sesjach stanowią problem procesowy” ma sens tylko wtedy, gdy wszystkie osiem sesji zostało oznaczone w ten sam sposób; twierdzenia dotyczące rozkładu wymagają stabilnego mianownika; a linie trendów („czy trudności związane z briefowaniem zmniejszyły się od czasu ustalenia szablonu briefu?”) mają sens tylko wtedy, gdy dana etykieta oznacza to samo zarówno w marcu, jak i w lipcu. Kategorie wyłaniające się, w których każda osoba samodzielnie przypisuje etykiety, są właściwym rozwiązaniem w pracy indywidualnej, jednak w ramach zespołu ulegają one rozbieżności w zależności od osoby, a żadne dane nie mogą zostać zagregowane bez etapu uzgadniania, za który nikt nie ponosi odpowiedzialności. Utrzymujemy działanie tego mechanizmu w dwóch miejscach: w postaci notatki opartej na dowodach umieszczonej pod każdą etykietą oraz poprzez okresowy przegląd słownictwa, podczas którego zgromadzone notatki poddają etykiety testom wytrzymałościowym. Słownictwo jest wersjonowane; zostało zaprojektowane tak, by zmieniać się w oparciu o dowody, a nie by je bronić.

To, co już istnieje – rzetelne porównanie

To nie my stworzyliśmy klasyfikacje niepowodzeń, a te istniejące dobrze spełniają swoje zadanie.

MAST (arXiv 2503.13657) stanowi referencyjną, ustaloną taksonomię: 14 rodzajów awarii w 3 kategoriach, wyodrębnionych na podstawie 150 śladów zweryfikowanych przez ekspertów i zweryfikowanych w oparciu o korpus liczący ponad 1600 przypadków, przy wysokim stopniu zgodności między anotatorami (κ = 0,88). Klasyfikuje ona sposoby awarii systemów wieloagentowych; została stworzona na potrzeby badań i testów porównawczych, jest najbliższa naszej pod względem dyscypliny, ale różni się przedmiotem badań: my klasyfikujemy przyczyny wystąpienia tarć w współpracy między człowiekiem a agentem.

Szkoła analizy błędów, metodologia ewaluacji autorstwa Husaina i Shankara (FAQ dotyczące ewaluacji, styczeń 2026 r.), opowiada się przeciwko stosowaniu stałej listy: kategorie „powinny wynikać z zaobserwowanych wzorców niepowodzeń… a nie z z góry ustalonych klasyfikacji zapytań”, a swobodna interpretacja własnych śladów stanowi „najważniejsze działanie w ramach ewaluacji”. Uważamy, że mają rację w przypadku pracy indywidualnej, a w skali zespołowej sytuacja ulega odwróceniu ze względu na wspomniane powyżej kwestie związane z agregacją. Ich dyscyplina analizy stanowi w naszej propozycji podstawę w obu przypadkach; na tym właśnie polegają notatki dowodowe.

W oparciu o te filary: taksonomia czterowarstwowa (Greyling, maj 2026 r.) określa, która warstwa stosu uległa awarii, przypisując jedynie około 9,9% niepowodzeń rozumowaniu modelu: większość awarii wynika z problemów związanych z osprzętem (osprzęt stanowi szkielet otaczający model), dlatego nasza agent-erroretykieta ma charakter rezydualny i jest stosowana wyłącznie w przypadku, gdy dane wejściowe były adekwatne (szkoła inżynierii osprzętu agentów wyraźnie odrzuca domyślne obarczanie winą agenta, skupiając się na naprawie osprzętu, a nie samego agenta: Osmani, Agent Harness Engineering). TraceProbe klasyfikuje działania związane z obsługą błędów w śladach. Model „Feedback Flywheel” autorstwa Garga gromadzi cztery rodzaje sygnałów w artefaktach zespołowych, w ramach których funkcjonuje nasza struktura: jego kontekst ≈ nasze grupy briefingowe + dokumentacyjne; jego „ramie awarii” odpowiada to, co rozkłada nasza taksonomia. System „Factory Signals” klasyfikuje objawy sesji, tworząc automatycznie wypełniane zgłoszenia; „Braintrust Topics” to skomercjalizowany produkt tej szkoły, który codziennie dokonuje ponownego grupowania Państwa śladów.

Dwie rzetelne interpretacje tego porównania. Po pierwsze, większość z nich klasyfikuje objawy, warstwy lub miejsca docelowe; nasza klasyfikacja dotyczy przyczyn, co sprawia, że etykieta pełni rolę klucza routingu i stanowi rzeczywistą nowość, taką jaka jest. Po drugie, co ważniejsze: MAST dokonał pomiaru rzetelności etykietowania, a my nie. Rzetelność międzyoceniająca w odniesieniu do naszych dziesięciu etykiet nie została zmierzona, a traktujemy to jako warunek wstępny, a nie jedynie przypis: eksperyment (niezależni oceniający dokonujący ślepej klasyfikacji tych samych rzeczywistych wpisów, przy czym zgoda jest raportowana niezależnie od jej wyniku) jest obecnie prowadzony na podstawie wpisów z naszego własnego badania w warunkach rzeczywistych, przy czym za punkt odniesienia przyjęto współczynnik κ = 0,88 określony przez MAST. Dopóki nie zostaną opublikowane wyniki tego badania, niniejsza taksonomia stanowi roboczą propozycję z etykietami w różnych wersjach, a nie zatwierdzone narzędzie. Wolimy poinformować Państwa o tym, niż pozwolić, by sami Państwo to odkryli.

Popieramy również wszystkie już działające cykle: Loop Engineering, Compound Engineering, agent-retro, retrospektywy AGENTS.md, systemy pamięci dostawców oraz zautomatyzowane raporty z sesji. Prosimy zachować je wszystkie; żadne z przedstawionych tutaj rozwiązań ich nie zastępuje.

Dlaczego wysokość nad poziomem morza jest kwestią dotyczącą całego zespołu

Oto wspólna cecha istniejących obecnie pętli: niemal wszystkie z nich mają charakter indywidualny (jeden programista i jego agent lub jeden dostawca i jego flota). Z danych branżowych wynika, że kosztownym etapem nie jest monitorowanie: około 90% zespołów wdraża śledzenie działania agentów, ale jedynie około 37–52% systematycznie je ocenia (LangChain State of Agent Engineering, czerwiec 2026 r.). Niewykorzystaną warstwą jest synteza na poziomie zespołu i właśnie w tym miejscu znaczenie zaczyna nabierać szersza perspektywa, z dwóch powodów.

Agregacja zmienia priorytety. Dziesięciominutowa niedogodność dla jednej osoby to tylko szum; nikt rozsądnie nie zajmuje się jej usuwaniem. Ta sama etykieta pojawiająca się w ośmiu sesjach i u pięciu osób stanowi jeden z największych kosztów zespołu, a dostrzec to można jedynie w ujęciu zbiorczym. Agregacja jest również tym, co zapewnia ustalone słownictwo: liczby sumują się tylko wtedy, gdy wszyscy używają tych samych etykiet.

Najwyższe szczeble decyzyjne należą do zespołu. Poszczególne osoby mogą samodzielnie dostosowywać swoje zasoby pamięci, wskazówki i ustawienia. Jednak zmiany procesów, decyzje wymagające oceny w kontekście wielu narzędzi, budżet na oprogramowanie, eskalacje do wyższych szczebli – czyli te szczeble, na których zazwyczaj pojawiają się największe powtarzające się tarcia – to decyzje, których żadna osoba nie może podjąć samodzielnie. To właśnie dlatego uważamy, że udział człowieka w procesie syntezy pozostaje niezbędny, niezależnie od tego, jak dobre będą modele: poprawki trafiają do artefaktów, za które odpowiadają ludzie i za które ponoszą odpowiedzialność: briefy, procesy, budżety, porozumienia zespołowe. Jest to stwierdzenie dotyczące autorytetu organizacyjnego, a nie możliwości modeli. Jest to miejsce w pętli decyzyjnej, a nie punkt kontrolny w procesie: agenci powinni swobodnie wykrywać, rejestrować, grupować i tworzyć projekty; ludzie natomiast dodają osąd dotyczący dalszego postępowania i ponoszą odpowiedzialność.

Przeglądając wpisy różnych osób i repozytoria, można również natrafić na wzajemnie sprzeczne wskazówki. Należy stosować zasadę zastępowania, a nie nadpisywania: nowa wskazówka zostaje dodana jako wpis opatrzony datą, odwołujący się do starej wersji, a stara wersja pozostaje dostępna do wglądu, dzięki czemu nikt nie wywnioskuje później błędnego przekonania. Aby dokonać wyboru między nimi, należy najpierw sprawdzić pochodzenie (dowody z pierwszej ręki przeważają nad wskazówką, która została jedynie powtórzona), a następnie aktualność, sprawdzając rzeczywiste znaczniki czasu. Jeśli żadna z tych informacji nie rozstrzyga sprawy, należy oznaczyć tę parę jako nierozstrzygniętą, zamiast na siłę wyłaniać zwycięzcę. Należy również sprawdzić zakres zastosowania. W jednym z naszych repozytoriów znajdowała się wskazówka, że nigdy nie należy tworzyć dowiązania symbolicznego do katalogu roboczegonode_modules; w innym stwierdzono, że należy je utworzyć, w przeciwnym razie kompilacja zakończy się niepowodzeniem. Każda z tych wskazówek była prawdziwa w swoim repozytorium. Późniejsza wspólna poprawka, polegająca na utworzeniu kopii z dowiązaniem stałym, zadziałała w obu przypadkach, więc wskazówka dotycząca dowiązania symbolicznego została zastąpiona.

Jeśli Państwa zespół organizuje już spotkanie poświęcone ciągłemu doskonaleniu, to rozwiązanie idealnie się w nie wpisuje: pojawia się zbiorczy obraz tarcia, zespół zadaje pytanie „gdzie trafia każde poprawki?”, a każdy wzorzec opuszcza spotkanie z przypisanym poziomem priorytetu i osobą odpowiedzialną. Nie jest to nowy rytuał, a jedynie retrospektywa oparta na lepszych danych wejściowych. Inżynierowie zajmujący się uczeniem maszynowym nazywają to analizą błędów odczytu; zespoły nazywają to spotkanie „retro”.

Co mogłoby skłonić nas do zmiany zdania?

Ponieważ jest to dokument do dyskusji, poniżej przedstawiamy kwestie, co do których naprawdę nie mamy pewności:

• Wiarygodność. Jeśli wyniki eksperymentu porównawczego między oceniającymi wskazują na niską zgodność, oznacza to, że reguły wyznaczania granic (lub same etykiety) są błędne i dokonamy ich korekty w ramach danej wersji, zamiast ich bronić.
• Wielkość. Liczba dziesięciu etykiet jest wartością odziedziczoną, a nie wyprowadzoną. W modelu MAST występuje 14 etykiet, a w modelu Four-Layer – 4. Rozkład naszych etykiet po przetworzeniu jednej czwartej rzeczywistych wpisów stanowi dowód, który potwierdza lub zmienia tę wartość.
• Brakujące tryby. Tarcia między agentami (utrata kontroli nad podagentami, awarie koordynacji) są obecnie klasyfikowane w kategorii environment-friction; rzeczywiste przypadki mogą wymagać utworzenia odrębnej kategorii.
• Zakres przeglądów nieobejmujących kodu. Zakres przeglądów określamy na podstawie miejsca, w którym wprowadzane są poprawki: w repozytorium w przypadku większości prac programistycznych; poza nim – w obszarach „konto”, „środowisko pracy” lub „zlecenie”. Te granice dotyczące elementów innych niż kod stanowią propozycje, które chcemy przetestować w praktyce z udziałem rzeczywistych zespołów.
• Wykonalność w momencie rejestracji. Czy zapracowane zespoły są w stanie przypisywać przyczyny od razu, czy też należy to zrobić dopiero podczas przeglądu? Zespoły, które spróbują tego rozwiązania, rozstrzygną tę kwestię szybciej niż nasze teoretyczne rozważania.

Jeśli korzystają Państwo z jakiejkolwiek wersji tego cyklu (kategorie wyłaniające się, proces dostawczy, zwykły arkusz kalkulacyjny), chcielibyśmy dowiedzieć się, w którym miejscu tabela routingu zawodzi. Szczególnie jeśli mogą Państwo wskazać nam schemat utrudnień, który w ogóle nie wskazuje na wysokość: ai-discussion@teamretro.com.

---

Następny rozdział: Raport istnieje. Pomieszczenie nie.: dlaczego przydzielanie zadań związanych z usunięciem problemów jest decyzją zespołową oraz co robi zespół po otrzymaniu raportu dotyczącego tarć. Fragment przewodnika po retrospektywach agentów AI.