91 na 100 repozytoriów ma plik konfiguracyjny z usterką

Plik CLAUDE.md albo AGENTS.md w korzeniu repozytorium traktujemy zwykle jak notatnik: dopisuje się do niego regułę, gdy agent coś spaprze, i nigdy się go nie kasuje. Naukowcy z wydziału informatyki brazylijskiego Federalnego Uniwersytetu Minas Gerais przejrzeli 100 popularnych projektów open-source z takim plikiem i w 91 z nich znaleźli przynajmniej jedną usterkę. W preprincie nazwali to "katalogiem zapachów" konfiguracji, na wzór code smells, czyli fragmentów kodu, które działają, ale zdradzają, że coś jest nie tak. Wynik czyta się jak lista kontrolna, którą warto raz przejść przez własne repo, bo każda z tych usterek kosztuje konkretnie: tokeny, pieniądze i mniej przewidywalne zachowanie agenta. Agent to tu po prostu asystent kodowania w stylu Claude Code czy Copilota, ten sam, który czyta ten plik na starcie każdej sesji.

W 62% plików badacze znaleźli to, co nazwali wyciekiem reguł lintera. Wpisujesz do konfiguracji rzeczy, których i tak pilnuje formater albo linter: długość linii, kolejność importów, konwencje nazewnictwa, ogólne wskazówki co do stylu. Te narzędzia egzekwują wszystko za darmo i deterministycznie, więc w pliku dla agenta są czystym balastem. Model czyta je na starcie każdej sesji, płaci za nie tokenami i, co gorsza, te drobiazgi konkurują o jego uwagę z tym, co naprawdę ważne, czyli ograniczeniami architektury, regułami domeny czy zasadami bezpieczeństwa. Lekarstwo jest proste: styl zostaw narzędziom, a z promptu go wytnij.

Druga pod względem częstości, w 42% plików, jest przerost kontekstu. Plik puchnie od reguł, przykładów i szczegółów, z których połowa jest mało istotna, a rachunek za każde wywołanie rośnie. Anthropic zaleca tu twardy próg: poniżej 200 linii na plik CLAUDE.md. Blisko spokrewniony jest wyciek umiejętności, obecny w 35% repozytoriów, czyli wpychanie do głównego pliku instrukcji potrzebnych raz na jakiś czas. Specjalistyczna wiedza, której model w danym zadaniu nie używa, jedzie z nim w każdej sesji. Rozwiązaniem jest rozbicie tego na osobne pliki z opisowymi nazwami i wciąganie ich tylko wtedy, gdy są potrzebne. Te trzy usterki nie są zresztą osobnymi pudełkami: dotyczą tego samego, czyli plik niesie materiał, którego model w danej chwili nie potrzebuje, a procenty się nakładają, bo jeden plik łapie się na kilka kategorii naraz.