Mit AGENTS.md obalony? Dodatkowy kontekst często szkodzi autonomicznym programistom

W środowisku inżynierów oprogramowania pracujących z agentami AI utarło się przekonanie, że im więcej informacji dostarczymy modelowi na starcie, tym lepiej. Pliki takie jak AGENTS.md miały pełnić rolę mapy drogowej, pomagając algorytmom odnaleźć się w strukturze projektu i szybciej rozwiązywać problemy. Najnowsze badania przeprowadzone przez zespół z ETH Zurich rzucają jednak na tę praktykę zupełnie nowe, krytyczne światło. Okazuje się, że karmienie agentów automatycznie generowanym kontekstem to w wielu przypadkach prosta droga do marnowania zasobów.

Więcej danych, gorsze wyniki

Badacze stworzyli własny benchmark oparty na 138 zadaniach z 12 repozytoriów open source oraz wykorzystali popularny zestaw testowy SWE-bench Lite. Przetestowano cztery wiodące modele kodujące, w tym Claude Code, Codex i Qwen Code, w trzech scenariuszach: bez plików kontekstowych, z plikami wygenerowanymi przez LLM oraz z dokumentacją przygotowaną ręcznie przez człowieka.

Wyniki są rozczarowujące dla entuzjastów automatyzacji dokumentacji. W pięciu na osiem scenariuszy testowych pliki wygenerowane przez sztuczną inteligencję doprowadziły do pogorszenia wyników agentów. Co więcej, nawet ręczne przygotowanie plików kontekstowych przyniosło jedynie marginalną poprawę skuteczności – średnio o zaledwie 4 punkty procentowe w porównaniu do pracy „na czysto”.

Pozorne zrozumienie i realne koszty

Problem nie leży w tym, że modele ignorują dostarczone im instrukcje. Analiza behawioralna wykazała, że agenci faktycznie podążają za wytycznymi z plików kontekstowych: uruchamiają więcej testów, przeszukują więcej plików i częściej korzystają z narzędzi specyficznych dla danego repozytorium. Paradoksalnie, to właśnie ta nadgorliwość staje się przeszkodą.

Dodatkowe wymagania generują „obciążenie poznawcze” (ang. cognitive load). Agenci zużywają znacznie więcej tokenów na procesy wnioskowania (ang. reasoning tokens), próbując zadowolić narzucone reguły, zamiast skupić się na najprostszym rozwiązaniu problemu. W przypadku słabszych modeli, takich jak GPT-5.1 Mini, automatycznie generowany kontekst wręcz wydłużył drogę do odnalezienia właściwego pliku w kodzie. Skutkiem ubocznym jest drastyczny wzrost kosztów wnioskowania – badanie wskazuje na skok o ponad 20 procent, co w skali dużych projektów komercyjnych jest wartością niebagatelną.

Kiedy kontekst ma sens?

Czy to oznacza, że powinniśmy całkowicie zrezygnować z plików pomocniczych? Niekoniecznie, ale ich rola musi zostać zredefiniowana. Badanie z Zurychu nie stoi w całkowitej sprzeczności z głośnymi testami firmy Vercel, która chwaliła się skutecznością kontekstu przy frameworku Next.js. Różnica tkwi w rodzaju informacji.

Vercel dostarczał agentom wiedzę, której nie było w ich danych treningowych (np. zmiany w najnowszych wersjach bibliotek). Badacze z ETH Zurich skupili się na typowych zadaniach naprawy błędów w istniejących repozytoriach. Wniosek jest jasny: AGENTS.md sprawdza się, gdy działa jak precyzyjny skalpel – dostarczając brakującej wiedzy o specyficznych systemach budowania czy unikalnych narzędziach. Stosowanie go jako uniwersalnego „wspomagacza” generowanego automatycznie jest błędem.

Dla deweloperów to sygnał, by przestać traktować pliki kontekstowe jako magiczne rozwiązanie. Zamiast generować obszerne, redundantne instrukcje, lepiej postawić na minimalizm i ręczne wskazywanie wyłącznie tych elementów, których model nie jest w stanie wywnioskować samodzielnie.