10 listopada 2025 — Jon Udell
Gdy musiałem przygotować dokumentację opisującą konfigurację środowiska na Macu z Node.js i runtime’em .NET, stanąłem przed nietypową sytuacją: nigdy wcześniej nie używałem .NET na Macu, więc pierwszym „klientem” tej instrukcji byłem ja sam. Zamiast działać w pojedynkę, zaangażowałem zespół asystentów AI, którzy wspólnie tworzyli instrukcje, a ja wdrażałem je praktycznie, zgłaszałem napotkane problemy i razem iterowaliśmy do działającego rozwiązania.
W trakcie pracy uświadomiłem sobie, że asystenci AI mogą nie tylko pisać dokumentację, lecz także czytać ją i pomagać w jej odtwarzaniu — proces, który nazwałem efektem „flywheel” (koło zamachowe). Nie jest to w pełni zautomatyzowany mechanizm: wymaga ludzkiego udziału i koordynacji. Ale celem nie jest wyłączenie człowieka z pętli, lecz umożliwienie mu efektywnego działania: wprawić „koło” w ruch, a następnie strategicznie je podbijać, by nabrało rozpędu.
Rola serwera MCP w workflow z AI
Krytycznym elementem tego procesu był serwer MCP (Model Context Protocol), implementujący dostęp do systemu plików, co pozwoliło agentom takim jak Claude i Cursor czytać i zapisywać pliki z rozwijającą się dokumentacją. Referencyjna implementacja Anthropic udostępniła potrzebny dostęp do odczytu i zapisu dokumentów, lecz nie pozwalała agentom na wykonywanie poleceń systemowych. W praktyce oznaczało to, że pozostawałem w pętli: kopiowałem proponowane przez asystentów polecenia, uruchamiałem je lokalnie, wklejałem wynik i omawiałem z agentami kolejne kroki.
Takie rozwiązanie sprawdzało się dobrze, choć napotkałem trudności związane z zarządzaniem konfiguracjami MCP w zespole. Każdy asystent miał swój plik konfiguracyjny; choć sam protokół MCP był standardowy, miejsca i formaty tych plików różniły się w praktyce, co komplikowało pracę zespołową i wymagało dodatkowego nadzoru.
Testowanie dokumentacji przez AI
Alternatywne podejście polegało na użyciu Claude Code lub Codex do bardziej bezpośredniego testu instrukcji. W ramach eksperymentu usunąłem wcześniejszą instalację i poprosiłem Claude Code, by przeczytał instrukcje, wykonał kolejne kroki (za moją zgodą uruchamiając polecenia), ocenił wyniki oraz sporządził końcowy raport. Efekt był udany: wszystko zostało zainstalowane, serwer backend wystartował, a aplikacja frontend działała poprawnie — raport końcowy został przygotowany (dostępny jako Gist).
Ta praktyka rzuca nowe światło na dokumentację: może ona stać się równie istotną dyscypliną inżynierii oprogramowania jak kod, ponieważ asystenci AI potrafią nie tylko tworzyć treść, lecz także automatycznie ją testować. Dla każdego, kto zmagał się z nietrwałymi, niedokładnymi instrukcjami instalacji, potencjał tej pętli poprawy jest oczywisty.
Iteracje serwera MCP z wykorzystaniem informacji zwrotnej od AI
Przy budowie pierwszej wersji serwera XMLUI MCP korzystałem z pomocy Claude — i odkryłem interesujący efekt: Claude, będąc klientem serwera, mógł analizować odpowiedzi zwracane przez narzędzia MCP i sugerować zmiany w kodzie serwera, które poprawiały te odpowiedzi. Jednym z priorytetów było „zakotwiczenie” agentów w faktach: wprowadziłem rygorystyczne wytyczne zabraniające wymyślania składni, nakazujące stosowanie technik popartych przykładami w dokumentacji oraz obowiązek cytowania adresów URL źródeł, z których czerpano rozwiązania.
Choć takie wskazówki poprawiały zachowanie agentów, często nadal wymagały interaktywnego przypominania, ponieważ serwer MCP sam w sobie nie ma niezależnej „agencji” — może wpływać na wybór i użycie narzędzi przez agenta, ale nie kontroluje go. Stąd wniosek, że serwer MCP mógłby zyskać cechy bardziej „agentskie”, by współpracować z asystentami na równych zasadach. Możliwa przyszłość to architektura agent‑to‑agent, w której serwer i asystenci wymieniają się rolami i odpowiedzialnościami w bardziej autonomiczny sposób.
Optymalizowanie komunikatów i oszczędność tokenów
Członkowie mojego zespołu AI zgłosili, że nadmiernie rozbudowane wytyczne (tzw. „MANDATORY” guidance block) marnują tokeny. Przy jednym z błędów blok ten zużywał około ~2k tokenów, co były kosztowne i nieefektywne. Poprosiłem asystenta Kiro o uproszczenie komunikatów, przebudowałem serwer, a następnie poprosiłem o ponowną ocenę scenariuszy, które wcześniej generowały zbyt obszerne odpowiedzi. Efekty oceniono następująco:
– komunikaty o błędach są teraz zwięzłe: trzy punkty zamiast ponad 20 ostrzeżeń „MANDATORY” (oszczędność ~1,5k tokenów na błędzie),
– przycinanie wyników wyszukiwania: pokazanie 20 wyników z komunikatem „… X dodatkowych wyników pominięto …” (czytelniejsze niż poprzednie „użyj JSON, by zobaczyć pełną listę”),
– przycinanie fragmentów: długie linie są obcinane do 200 znaków z oznaczeniem „…”,
– zmiany dotyczą wszystkich narzędzi: xmlui_search, xmlui_search_howto oraz xmlui_examples.
Następnie poprosiłem Cursor o niezależną ocenę. Cursor zwrócił uwagę, że gdy nie ma wyników wyszukiwania, kod wciąż zamieszcza przypomnienia o cytowaniu źródeł, które w takim przypadku są nieprzydatne. To trafne spostrzeżenie — przypomnienia powinny pojawiać się tylko wtedy, gdy istnieją źródła do zacytowania. Przekazałem uwagi Kiro, wprowadzono sugerowane poprawki, a zmiany zweryfikowano z udziałem całego zespołu AI.
Rola człowieka w cyrkulacji poprawy
Mimo że rozwój protokołów agent‑to‑agent może w przyszłości zwiększyć autonomię takich procesów, ja osobiście chętnie pełnię rolę koordynatora i nie sądzę, bym kiedykolwiek chciał całkowicie z niej zrezygnować. W tej pracy łączę role pilota i mechanika: wykrywam problemy, ustalam cele, buduję zespoły, wprawiam „koło zamachowe” w ruch i strategicznie je podbijam, by przyspieszyć korzystną pętlę ulepszeń.
W praktyce oznacza to, że dokumentacja przestaje być tylko biernym opisem — staje się częścią aktywnego procesu inżynieryjnego, w którym asystenci AI pomagają ją tworzyć, testować i usprawniać, a człowiek pełni funkcję menedżera procesu, dbając o jakość, wiarygodność i kierunek rozwoju.
