Kiedy dokumentacja zamienia się w składnicę chaosu

Wyobraź sobie taką sytuację: zaczynasz nowy projekt z czystym plikiem CLAUDE.md. Wrzucasz kilka przydatnych wskazówek. Dodajesz notatkę o kontekście. Uwagę o tym dziwnym przypadku brzegowym w mechanizmie autoryzacji. Miesiące później otwierasz plik i widzisz tomisko pełne sprzecznych instrukcji, przestarzałych przypomnień i rozpaczliwych załączników, których nikt już nie rozumie.

To nie jest tylko twoje doświadczenie. To zjawisko powszechne.

Badania analizujące 247 694 cykle życia instrukcji w 1 867 repozytoriach ujawniają zaskakujący wzorzec: prompty agentowe nie tylko rosną — rosną bez żadnych ograniczeń, potrajając się w trakcie życia projektu (+226%). Średnio takie pliki zyskują +4,9 czystych instrukcji z każdym commitem. Plik nigdy się nie kurczy. Tylko się rozrasta.

A co najciekawsze: im starsza instrukcja, tym mniejsze prawdopodobieństwo, że zostanie usunięta. Dane pokazują log-hazard na poziomie -0,032 na commit, co oznacza, że instrukcje stają się coraz bardziej nieśmiertelne, im dłużej sobie siedzą. Problem nie polega na tym, że nikt nie chce posprzątać — chodzi o to, że nikt nie wie, czy może bezpiecznie cokolwiek usunąć.

Problem O(2^|D|)

Dlaczego tak się dzieje? Badacze nazywają to „katastrofalnym zapamiętywaniem" — odwrotnością dobrze znanego problemu „katastrofalnego zapominania" w uczeniu maszynowym. Ale nie potrzebujesz doktoratu, żeby zrozumieć, dlaczego tak się dzieje.

Pomyśl o kalkulacji kosztów: dodanie nowej instrukcji jest tanie. Widzisz problem, piszesz rozwiązanie, idziesz dalej. Natychmiastowy koszt jest niski, a odczuwalna korzyść oczywista.

Ale usunięcie instrukcji? To zupełnie inna bestia. Musisz zrozumieć każde miejsce, gdzie ta instrukcja może mieć znaczenie. Musisz przemyśleć interakcje ze wszystkimi pozostałymi instrukcjami. Musisz zweryfikować, że jej usunięcie nie zepsuje czegoś subtelnego i ważnego. Badacze obliczyli ten koszt poznawczy jako O(2^|D|) w prompcie zawierającym |D| instrukcji — czyli rośnie wykładniczo wraz z liczbą istniejących instrukcji.

Więc programiści robią to, co robią racjonalni ludzie: przestają próbować. Nowe instrukcje są dopisywane. Stare zostają. Plik rośnie.

Komentarze: Niezawodny bohater

I tutaj badania stają się naprawdę fascynujące. Rozwiązanie nie polega na lepszych technikach promptowania ani mądrzejszych modelach. Chodzi o coś, czego programiści używają od zarania dziejów programowania: komentarze.

Badacze przyjęli ciekawą strategię — odwrócili IFEval, standardowy benchmark, tworząc „weryfikowalne światy", gdzie optymalne prompty są faktycznie znane. Kiedy dodali komentarze enkodujące ukryte rozumowanie do promptów, nadmierny przyrost instrukcji spadł z +211,3% do zaledwie +1,4%.

To redukcja o 99,3%.

Ale prawdziwy gwóźdź do trumny? Te komentarze nie tylko kontrolowały wzrost — poprawiły faktyczną wydajność podążania za instrukcjami o nawet 23,1% w realnych zadaniach. Komentarze to nie jest organizacyjny bałagan. To konstrukcje nośne, które pomagają asystentom AI w prawidłowym rozumowaniu o kontekście.

Dlaczego to jest ważne teraz

Żyjemy w czasach fundamentalnej zmiany tego, co oznacza „kod". Badacze zadają provokacyjne pytanie: „Jeśli angielski jest nowym kodem, dlaczego nie mamy jeszcze komentarzy?"

To uczciwe pytanie. Od dziesięcioleci programiści rozumieją, że kod bez komentarzy to dług techniczny. Komentarze wyjaśniają „dlaczego", nie tylko „co". Przechwytują intencje, przypadki brzegowe i wiedzę instytucjonalną, której nie można wywnioskować z samej składni.

A jednak w naszej gorączce przekazywania coraz więcej zadań asystentom programistycznym AI, traktowaliśmy instrukcje w języku naturalnym jakby były czymś innym. Piszemy imperatywy — zrób to, nie rób tamtego, pamiętaj o sprawdzeniu X — bez wyjaśniania naszego rozumowania.

Rezultatem jest to, co widzimy w tych rozrastających się plikach CLAUDE.md: instrukcje, których nikt do końca nie rozumie, które mogą ze sobą kolidować, i które rosną bez żadnego mechanizmu racjonalizacji.

Droga do przodu

Jeśli utrzymujesz plik CLAUDE.md lub podobny prompt agentowy, oto co sugerują badania:

1. Komentuj swoje instrukcje, nie tylko swój kod. Wyjaśniaj, dlaczego dana reguła istnieje. Dokumentuj przypadki brzegowe. Przechwytuj rozumowanie stojące za decyzjami.

2. Przyjmij okresową racjonalizację. Nie tylko dopisuj — przepisuj. Badania wyraźnie zaznaczają, że całkowite przepisanie pliku to jedna z niewielu rzeczy, która powstrzymuje wzrost.

3. Traktuj swoje instrukcje dla AI jak dokumentację wdrożeniową. Czy powierzyłbyś nowemu programiście 400-linijkowy plik niezróżnicowanych reguł? Twój asystent AI zasługuje na tę samą jasność.

Kierunek, w którym zmierzamy, nie jest zrównoważony. Każdy nowy projekt zaczyna się z dobrymi intencjami, a kończy nieutrzymywalnym bałaganem. Ale poprawka może być prostsza, niż myśleliśmy: pisz dla człowieka (lub AI), który przeczyta twoje instrukcje za sześć miesięcy, nie tylko dla tego, który odpowiada na twoje pytanie dzisiaj.

Komentarze to nie zaśmiecony element. To architektura zrozumienia.