gik|iewicz

Plik agent.md to najtańszy sposób na podniesienie jakości kodu generowanego przez modele takie jak Claude czy GPT. Zamiast powtarzać tych samych instrukcji w każdym promptcie, umieszczasz je raz w repozytorium – a agent czyta je przy każdym zadaniu. Badacze z ETH Zürich (SRI Lab) przeanalizowali tę praktykę i opisali ją jako powszechny standard w projektach korzystających z agentów kodujących (Evaluating AGENTS.md).

TL;DR: Plik agent.md (lub AGENTS.md) to repozytorium-poziomy plik kontekstowy, który dostarcza LLM reguły projektu: konwencje nazewnictwa, komendy builda, styl kodu. Dokumentacja OpenCode potwierdza, że jego zawartość trafia do kontekstu modelu przy każdym zapytaniu. W tym artykule pokazuję, jak zbudowałem swój plik i które sekcje dają największy przyrost jakości.

Kilka słów o mojej perspektywie, żebyś wiedział, skąd biorą się te wnioski. Od lat prowadzę blog gikiewicz.eu o technologii, AI i programowaniu, a pliki reguł dla agentów kodujących stosuję w własnych projektach od momentu pojawienia się CLAUDE.md w Claude Code. Przez ten czas przetestowałem różne warianty struktury – od rozbudowanych dokumentów po kilkanaście linii – i to właśnie te wnioski opisuję poniżej.

Czym właściwie jest plik agent.md i skąd się wziął?

To zwykły plik Markdown umieszczony w katalogu głównym projektu. Jego zawartość jest wstrzykiwana do kontekstu LLM automatycznie, jeszcze przed tym, jak agent zacznie czytać właściwy kod. Dokumentacja OpenCode opisuje ten mechanizm wprost: tworząc AGENTS.md, dostarczasz instrukcje, które model uwzględnia w każdym zadaniu – działa to analogicznie do reguł znanych z Cursora.

Otóż idea nie jest nowa. Zaczęło się od CLAUDE.md w Claude Code, potem OpenAI wprowadziło AGENTS.md dla Codex, a kolejne narzędzia przyjęły ten sam format. Dziś to de facto standard – dlatego warto trzymać jeden plik jako źródło prawdy, zamiast utrzymywać osobne wersje dla każdego agenta (poradnik o synchronizacji).

Sprawdziłem to na własnych projektach. Jeden plik wystarcza.

Dlaczego instrukcje w pliku działają lepiej niż promptowanie w rozmowie?

Ponieważ kontekst rozmowy jest ulotny, a plik – trwały. Gdy piszesz regułę w chacie, znika ona po zamknięciu sesji. Umieszczona w agent.md wraca przy każdym uruchomieniu agenta, przy każdym nowym tasku, na każdej gałęzi. Co więcej, taki plik jest wersjonowany w gicie razem z kodem, więc historia jego zmian jest jawna dla całego zespołu.

Kun Chen proponuje ciekawą ramę myślenia o tym pliku: traktuj go jak sieć neuronową, którą trenujesz metodą gradientu prostego (Your AGENTS.md is a Neural Net). Mianowicie – za każdym razem, gdy agent wygeneruje zły kod, nie poprawiasz ręcznie wyniku, lecz dodajesz lub modyfikujesz regułę w pliku. Po kilkunastu iteracjach plik „konwerguje” do stanu, w którym typowe błędy przestają się pojawiać.

Moim zdaniem to najlepszy mentalny model tej praktyki. Nie piszesz dokumentacji – trenujesz agenta.

Jakie sekcje powinien zawierać dobry agent.md?

Przede wszystkim konkret, zero ogólników. Model nie potrzebuje frazesów o „czystym kodzie”, tylko sprawdzalnych poleceń. W moim pliku, wypracowanym przez kilkanaście iteracji na własnych repozytoriach, znalazły się między innymi:

• Komendy builda i testów – dokładne polecenia, np. npm run test:unit, żeby agent sam weryfikował swoją pracę przed oddaniem
• Konwencje nazewnictwa – jak nazywać pliki, funkcje, zmienne w tym konkretnym projekcie
• Zakazane praktyki – np. „nie dodawaj nowych zależności bez wyraźnej instrukcji”, „nie modyfikuj plików w katalogu migrations”
• Struktura repozytorium – gdzie lądują komponenty, gdzie testy, gdzie konfiguracja
• Styl komunikatów błędów i logowania – żeby nowe logi pasowały do istniejących
• Proces review – co agent ma zrobić przed oznaczeniem zadania jako skończone

Zwróć uwagę na pierwszą pozycję. Reguła „uruchom testy przed oddaniem” zmienia więcej niż jakakolwiek instrukcja stylistyczna, bo zamienia agenta z generatora kodu w generator zweryfikowanego kodu. Pisałem o tym szerzej w kontekście kosztów utrzymania kodu pisanego przez agenta AI – tam, gdzie nikt nie weryfikuje wyników, dług techniczny rośnie najszybciej.

Jak wygląda mój plik agent.md w praktyce?

Poniżej rdzeń mojego pliku, okrojony do tego, co faktycznie wpływa na jakość wyników. To wersja po wielu iteracjach – początkowo wyglądał zupełnie inaczej, ale reguły, których agent nigdy nie łamał, po prostu wyciąłem:

# Zasady agenta dla tego repozytorium

### Przed oddaniem pracy
- Uruchom `pnpm test` i upewnij się, że wszystkie testy przechodzą
- Uruchom `pnpm lint --fix` na zmienionych plikach

### Zakazy
- Nie instaluj nowych pakietów bez pytania
- Nie zmieniaj plików w `db/migrations/`
- Nie zostawiaj zakomentowanego kodu

### Konwencje
- Funkcje: camelCase, komponenty: PascalCase
- Każda nowa funkcja eksportowana dostaje test jednostkowy
- Błędy logujemy przez `logger.error`, nigdy `console.log`

To wszystko. Niecałe dwadzieścia linii. Jednakże różnica w jakości wyników jest odczuwalna od pierwszego zadania, bo agent przestaje zgadywać, a zaczyna wykonywać. Jeśli chcesz zobaczyć, jak daleko można popchnąć automatyczną weryfikację generowanego kodu, zajrzyj też do eksperymentu ze wyciąganiem śladów rozumowania z API modeli – tam problem „jak zmusić model do lepszej pracy” jest rozwiązany od zupełnie innej strony.

Jak iterować plik agent.md, żeby faktycznie działał?

Najpierw wersja minimalna, potem iteracje. Badacze z ETH Zürich opisują pliki kontekstowe jako powszechną praktykę w projektach korzystających z agentów kodujących, jednakże sam plik nie działa od razu – wymaga dostrajania (SRI Lab). Otóż Kun Chen proponuje konkretną metodę: po każdym błędzie agenta popraw regułę w pliku zamiast ręcznie naprawiać kod, a po kilkunastu iteracjach typowe błędy znikają (Your AGENTS.md is a Neural Net).

W praktyce wygląda to tak. Agent zostawił zakomentowany kod? Dodajesz zakaz do sekcji zakazów. Agent zainstalował pakiet bez pytania? Analogicznie. Mimo to nie przesadzaj z rozmiarem – każdy zbędny wiersz zjada kontekst modelu i rozmywa ważne reguły. Zatem trzymaj plik poniżej kilkudziesięciu linii i wycinaj reguły, które przestały być łamane.

Moim zdaniem proces iteracji to najważniejszy element całej metody. Sam szablon nic nie daje.

Jak zachować spójność między AGENTS.md, CLAUDE.md i innymi plikami reguł?

Jeden plik jako źródło prawdy. Różne narzędzia używają różnych nazw – Claude Code czyta CLAUDE.md, OpenAI Codex czyta AGENTS.md, a OpenCode obsługuje AGENTS.md analogicznie do reguł znanych z Cursora (OpenCode). Ponadto utrzymywanie osobnych wersji dla każdego agenta prowadzi do rozjazdów instrukcji, czyli tzw. instruction drift (poradnik o synchronizacji).

Rekomendowane podejście jest proste:

• trzymaj AGENTS.md jako jedyne źródło prawdy dla wszystkich agentów
• dla Claude Code użyj importu lub symlinku wskazującego na AGENTS.md
• nie edytuj kopii – zawsze modyfikuj plik źródłowy
• sprawdź raz w miesiącu, czy symlink nadal działa po zmianach w repo

Dzięki temu jedna poprawka reguły trafia do wszystkich narzędzi naraz. Co więcej, historia zmian w gicie pokazuje, kiedy i dlaczego dana reguła powstała – to przydatne podczas review.

Jakie błędy popełniają twórcy plików agent.md?

Najczęstszy to ogólniki zamiast poleceń. Frazy w stylu „pisz czysty kod” nie mają wartości operacyjnej, bo model nie wie, jak je przełożyć na konkretne decyzje. Zatem zamiast tego pisz: „uruchom pnpm test przed oddaniem” albo „nie dodawaj nowych zależności bez pytania”. Sprawdzalne polecenie wygrywa z deklaracją o charakterze.

Drugi błąd to pomijanie komend weryfikacji. Badacze z ETH Zürich wskazują, że pliki kontekstowe służą dostosowaniu agenta do repozytorium – a bez komend builda i testów agent nie ma jak zweryfikować swojej pracy (SRI Lab). Trzeci to nadmiarowość: powielanie reguł, które model i tak stosuje domyślnie. Każde zdanie w pliku powinno istnieć dlatego, że bez niego agent robi coś złego.

Czym różni się dobry agent.md od dokumentacji README?

Przeznaczeniem. README piszesz dla ludzi, agent.md dla modelu. Zatem inna jest też forma:

Choć oba pliki mogą się uzupełniać, kopiowanie README do agent.md to błąd. Model dostaje wtedy setki słów opisu produktu zamiast kilkunastu reguł roboczych. Dlatego traktuj je jako dwa osobne dokumenty o różnych zadaniach.

Często zadawane pytania

Czy agent.md obniża jakość wyników, gdy plik jest za długi?

Tak, nadmiar reguł rozmywa kontekst modelu. Kun Chen opisuje plik jako obiekt trenowany metodą gradientu prostego – każda iteracja to jedna poprawka, nie dziesięć naraz (Your AGENTS.md is a Neural Net). Wycinaj reguły, które przestały być łamane, i trzymaj plik poniżej kilkudziesięciu linii.

Czy jeden plik wystarczy dla Claude Code, Codex i Cursora?

Tak. Poradnik o synchronizacji zaleca uczynienie AGENTS.md jedynym źródłem prawdy, a dla Claude Code mostek w postaci importu lub symlinku (aq.dev). W ten sposób eliminujesz rozjazd instrukcji między narzędziami.

Od czego zacząć, jeśli nie mam żadnych reguł?

Od trzech sekcji: komend testów, zakazów i konwencji nazewnictwa. Dokumentacja OpenCode potwierdza, że zawartość AGENTS.md trafia do kontekstu LLM przy każdym zadaniu (OpenCode), więc nawet reguła „uruchom testy przed oddaniem” działa natychmiast.

Jak często aktualizować plik agent.md?

Po każdym błędzie agenta, zgodnie z metodą opisaną przez Kuna Chena – jedna poprawka reguły zamiast ręcznej naprawy kodu (Your AGENTS.md is a Neural Net). Badanie ETH Zürich pokazuje z kolei, że pliki kontekstowe to już standard w projektach z agentami (SRI Lab).

Podsumowanie

Plik agent.md to najtańsza inwestycja w jakość kodu generowanego przez LLM. Po pierwsze, zacznij od wersji minimalnej z komendami testów, zakazami i konwencjami nazewnictwa. Po drugie, iteruj po każdym błędzie agenta – jedna poprawka reguły zamiast ręcznej naprawy kodu. Po trzecie, trzymaj AGENTS.md jako jedyne źródło prawdy i spinaj pozostałe narzędzia symlinkami. Po czwarte, pisz imperatywy sprawdzalne komendami, nie ogólniki. Po piąte, utrzymuj plik krótki – kontekst modelu to zasób ograniczony.

Jeśli chcesz pójść dalej w stronę kontroli nad zachowaniem modeli, zajrzyj do eksperymentu ze wyciąganiem śladów rozumowania z API modeli albo sprawdź, jak wytrenować własny model LLM od zera. Skopiuj szablon z tego artykułu, dostosuj komendy do swojego stacka i wróć po tygodniu – zobacz, które reguły faktycznie zadziałały.