Sprawdzając rady - jak sprawić, żeby agent pisał lepszy kod

Na r/Anthropic trafiłem na wątek „How do you make your coding agents write better code?”. Cindy Sridharan napisała, że Claude pisze dziś lepszy kod niż ona, jeśli dostanie dobre instrukcje, ograniczenia i kontekst. Swój CLAUDE.md zbudowała, każąc mu najpierw przeczytać ulubione książki i blogi, najlepsze projekty open source i kod inżynierów, których ceni. W komentarzach ktoś inny opisał zupełnie inne podejście: zamiast dłuższego CLAUDE.md hooki, które blokują pliki dłuższe niż 350 linii, nazwy w rodzaju utils.js i kolory wpisane na sztywno zamiast tokenów motywu. Kilka osób odpisało, że to „Claude, make no mistakes” z dodatkowymi krokami.

Pracuję z kilkoma agentami kodującymi na jednym repozytorium, więc chciałem wiedzieć, co z tego warto u siebie wdrożyć. Sprawdziłem, co mówią dokumentacja Claude Code i badania z ostatniego roku, a potem porównałem to z tym, jak moi agenci pracują dziś.

Dłuższy plik instrukcji nie daje lepszego kodu

Dokumentacja Claude Code mówi wprost: celuj w mniej niż 200 linii na jeden plik CLAUDE.md, bo dłuższe pliki zajmują więcej kontekstu i agent gorzej się ich trzyma (memory). Ten sam dokument przypomina, że CLAUDE.md to kontekst, a nie egzekwowana konfiguracja. Jeśli coś ma być zablokowane niezależnie od tego, co model postanowi, trzeba użyć hooka.

Ciekawsze są pomiary. Zespół z ETH Zurich sprawdził, co pliki w rodzaju AGENTS.md robią z wynikami agentów na prawdziwych zadaniach z repozytoriów (Gloaguen i in., wersja 3 z 29 września 2026). Wynik: takie pliki w ogólności nie poprawiają odsetka rozwiązanych zadań, a koszt rośnie średnio o ponad 20%. Pliki pisane przez ludzi wypadły średnio o 7% lepiej niż wygenerowane przez model. Agenci dobrze wykonywali zawarte w plikach polecenia, za to opisy struktury repozytorium nie pomagały, choć poleca je wielu dostawców.

To mi wystarczyło, żeby nie powtarzać pomysłu z czytaniem książek. Plik, który model napisze po lekturze cudzych blogów, jest dalej plikiem wygenerowanym przez model, a w tym badaniu takie pliki wypadały gorzej od ludzkich. Do tego te książki i projekty open source model najpewniej i tak widział podczas treningu. Moim zdaniem ten sposób daje głównie poczucie, że agent został lepiej przygotowany.

U siebie mam w repozytorium testy, które pilnują rozmiaru instrukcji ładowanych przy każdym starcie sesji, osobno dla każdego narzędzia. Mimo to główny plik z zasadami ma 373 linie, więc jest prawie dwa razy dłuższy, niż zaleca Anthropic. Na razie go nie tnę, bo nie mam jak sprawdzić, czy po cięciu agenci będą pisać lepiej, czy gorzej. Wracam do tego w ostatniej części.

Hooki po edycji pliku

Tu komentarz z Reddita ma rację co do zasady. Hook w Claude Code to polecenie, które narzędzie uruchamia w określonym momencie, na przykład przed wykonaniem komendy albo po edycji pliku. Dokumentacja opisuje to jako deterministyczną kontrolę: coś dzieje się zawsze, a nie wtedy, gdy model sobie o tym przypomni (hooks guide).

Jest jedno ograniczenie, o którym w wątku nikt nie wspomniał. Hook podpięty pod edycję pliku uruchamia się po narzędziach do edycji. Jeśli agent zapisze ten sam plik komendą w terminalu, hook się nie odpali, a dokumentacja odsyła wtedy do osobnego zdarzenia, które reaguje na każdą zmianę pliku.

Moje hooki pilnują dziś rzeczy, których agent nie może zrobić pod żadnym pozorem: zapisu do gita w katalogach, z których działają usługi, i zabijania procesów po nazwie, bo na tej samej maszynie pracują sesje innych agentów. Po edycji pliku nie dzieje się nic, linter odpala się dopiero w CI.

Dlatego przygotowałem hook, który po każdej edycji pliku w Pythonie uruchamia linter na tym jednym pliku i oddaje agentowi listę uwag. Celowo niczego nie blokuje. Jeśli agent zapisze plik z pominięciem hooka, nic się nie stanie, bo i tak zatrzyma go CI. Tu nie chodzi o bezpieczeństwo, tylko o to, żeby agent dowiedział się o błędzie od razu, a nie po publikacji. W chwili pisania to pilotaż tylko dla Claude Code i czeka na review.

350 linii i zakaz utils.js

Szukałem badania, które pokazałoby, że limit długości pliku albo bramka wykrywająca duplikaty poprawia kod pisany przez agentów. Nie znalazłem żadnego. Najbliżej jest praca firmy CodeScene, która sprzedaje narzędzie do oceny jakości kodu (arXiv 2601.02200). Pokazuje ona związek między „zdrowiem” kodu a tym, jak często model psuje go przy refaktoryzacji. To jednak korelacja, nikt tam nie testował limitu ani bramki, a dla Sonneta autorzy nie znaleźli istotnej różnicy między kodem zdrowym i niezdrowym.

Sprawdziłem też, co by się stało, gdybym u siebie włączył w linterze reguły złożoności, długości funkcji, upraszczania kodu i typowych pułapek. Wyszło 1725 uwag, z czego 638 dotyczyło samej złożoności. Każdy otwarty pull request od razu by się wysypał, a moje zasady dla agentów mówią, że około 500 linii w pliku to sygnał do podziału, a nie naruszenie. Odrzuciłem to. Zostawiłem pięć reguł, które łapią prawdziwe błędy, na przykład mutowalną wartość domyślną argumentu. W całym repozytorium dały 15 trafień. Włączę je, kiedy scalą się zmiany innych agentów w tych samych plikach.

Zakazu nazw w rodzaju utils.js też nie wprowadzam. Nie mam na to dowodu, a zasady tego typu łatwo obejść, nazywając plik my-utils.js. Blokada kolorów wpisanych na sztywno ma sens w projekcie z rozbudowanym interfejsem, a ja pisałem o repozytorium z kodem infrastruktury i agentów.

Przykłady z własnego repozytorium

Z tego, co znalazłem, najlepiej wypada pokazanie agentowi kodu z tego samego projektu. W pracy o przykładach w promptach (arXiv 2508.06414) przykłady wyciągnięte z repozytorium wyraźnie poprawiły wyniki na zadaniach z prawdziwych projektów. Qwen-32B rozwiązał 36,79% zadań, a bez przykładów 15,21%. Na zadaniach konkursowych dobieranie podobnych rozwiązań nie dawało stałej poprawy.

Druga praca porównała reguły stylu, przykłady i jedno z drugim na 160 parach programów (Show and Tell, jeszcze w recenzji). Najlepiej działało połączenie. Same przykłady dawały niewielki efekt i model przestawał się ich trzymać, kiedy w kolejnym kroku rozbudowywał kod.

Moi agenci mają już regułę, żeby przed zmianą znaleźć najbliższy istniejący wzorzec. Nie mieli natomiast listy plików, które uważam za dobre. Dopisałem więc do przewodnika dla kontrybutorów krótką tabelę: hook, serwer MCP tylko do odczytu, rola Ansible dla aplikacji i skill, przy każdym ścieżka do jednego pliku i to, co z niego skopiować.

Pięć uruchomień zamiast jednego

Najbardziej przydała mi się notatka Andrei Griffiths na blogu AAIF (Measuring AGENTS.md, lipiec 2026). Porównała dwa identyczne klony repozytorium, jeden z dwunastolinijkowym AGENTS.md, drugi bez. Po jednym uruchomieniu na wariant wyszło, że na trudniejszym zadaniu agent z plikiem pracuje o 44% wolniej i o 41% drożej. Po pięciu uruchomieniach na wariant wynik się odwrócił i plik wygrał na obu zadaniach. Na zadaniu z niejasnym poleceniem skrócił czas o 27%, koszt o 24%, a zmiany były o 26% mniejsze, bo jedyne polecenie w pliku kazało trzymać się zakresu zadania. Na zadaniu obejmującym wiele plików zysk wyniósł 9-10%. Autorka sama zaznacza, że to jeden punkt danych z jednego repozytorium i jednego agenta.

Tu jest moja największa luka. Mierzę, ile miejsca zajmują instrukcje, ale nigdy nie zmierzyłem, czy cokolwiek zmieniają. Claude Code ma do tego polecenie claude plugin eval, które uruchamia te same przypadki kilka razy w świeżych sesjach, z pluginem i bez niego, i pokazuje różnicę (plugin evals). Domyślnie robi trzy przebiegi na przypadek.

Zaplanowałem mały pilotaż: jeden skill do debugowania, jedno zadanie z crawlerem, w którym zbiór odwiedzonych stron nie jest bezpieczny przy wielu wątkach, i po trzy do pięciu przebiegów z tym skillem i bez niego. Pomysł z crawlerem pochodzi z tego samego wątku. Na razie to tylko plan, nie ustaliłem jeszcze limitu kosztów.

Dopóki go nie zrobię, nie odpowiem sobie na pytanie, które interesuje mnie najbardziej: czy hook z linterem zmieni sposób pracy agenta, czy tylko dorzuci mu tokenów do czytania.

Do tematu będę jeszcze na pewno wracał, a tymczasem zachęcam do własnych eksperymentów.