AGENTS.md i CLAUDE.md: co wpisać w plik z instrukcjami dla AI, a czego unikać

Większość poradników o agentach AI mówi: „dodaj AGENTS.md, to poprawi wyniki”. Brzmi rozsądnie, ale jest to hipoteza, nie fakt. Kiedy sprawdzono ją w badaniu, wynik był bardziej złożony. W tym artykule pokazuję, co ten plik naprawdę robi, które narzędzie czyta który plik, co warto w nim zapisać i jak sprawdzić, czy twój plik cokolwiek daje. Jeśli dopiero wybierasz narzędzie, zacznij od porównania Cursora, Claude Code, Copilota i Codexa. Jeśli chcesz zrozumieć, jak agenci działają od środka, w ścieżce AI Engineer budujesz takiego agenta samodzielnie w Pythonie.

Czym jest plik kontekstowy i po co agentowi AI?

Agent AI zaczyna każdą sesję od pustego okna kontekstu (context window). Nie pamięta, że testy uruchamiasz komendą pytest -q, że nie wolno edytować plików w migrations/ ręcznie ani że w tym projekcie komentarze piszesz po polsku. Plik kontekstowy to zwykły plik Markdown w repozytorium, który narzędzie wczytuje na starcie sesji i dołącza do kontekstu, zanim agent zacznie pracę.

Dobór tego, co trafia do kontekstu agenta, nazywa się czasem inżynierią kontekstu (context engineering). Plik kontekstowy to jej najprostsze, stałe narzędzie. Jednorazowe polecenia i opis konkretnego zadania to osobna sprawa; o planowaniu zadania przed kodowaniem piszę w artykule o spec-driven development. Plik kontekstowy zawiera to, co jest prawdziwe w każdym zadaniu w tym projekcie.

Które narzędzie czyta który plik?

Największe zamieszanie bierze się stąd, że każde narzędzie ma własną nazwę pliku. Według dokumentacji producentów wygląda to tak:

Kilka szczegółów, które oszczędzają godzin szukania błędu:

• Cursor wczytuje z .cursor/rules tylko pliki z rozszerzeniem .mdc. Zwykły .md w tym katalogu jest ignorowany.
• Copilot pozwala na reguły dla ścieżek (applyTo), ale według dokumentacji GitHub obsługują je tylko agent w chmurze i code review na GitHub.com. Jeśli reguła „nie działa” w czacie, sprawdź najpierw, w której części Copilota jej używasz.
• Codex łączy pliki od korzenia projektu w dół do bieżącego katalogu, a plik bliższy bieżącemu katalogowi ma pierwszeństwo. Po przekroczeniu limitu (domyślnie 32 KiB) przestaje dodawać kolejne pliki.
• Claude Code może użyć AGENTS.md zamiast CLAUDE.md, a w CLAUDE.md możesz zaimportować go linijką @AGENTS.md. To właśnie ten wzorzec pokazuję niżej na prawdziwym repozytorium.

Czy plik AGENTS.md naprawdę poprawia wyniki agenta?

Nie zawsze, a zwykle nie tak bardzo, jak się wydaje. Zespół z ETH Zurich opublikował w lutym 2026 roku badanie Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (arXiv 2602.11988, wersja zaktualizowana we wrześniu). Sprawdzili, czy agenci z plikiem kontekstowym rozwiązują zadania z repozytoriów częściej niż agenci bez niego. Wyniki:

Co z tego wynika w praktyce:

1. Plik wygenerowany automatycznie (komenda w stylu /init) nie jest darmową poprawą. W badaniu kosztował więcej, a skuteczności nie podniósł.
2. Plik napisany ręcznie wypadł lepiej niż generowany, ale różnica względem braku pliku nie była istotna statystycznie.
3. Agenci wykonują instrukcje z pliku. To dobra wiadomość, ale oznacza też więcej testów, więcej eksploracji i więcej kroków, czyli wyższy koszt.
4. Przegląd repozytorium nie pomaga. Osiem z dwunastu plików napisanych przez ludzi zawierało opis struktury katalogów, a agenci nie docierali dzięki temu szybciej do właściwych plików.

Autorzy podsumowują to ostrożnie: pliki kontekstowe przydają się do określenia niestandardowych praktyk, a każdą zmianę warto sprawdzić eksperymentem, zanim ją wdrożysz. Pamiętaj o ograniczeniu: badanie dotyczyło rozwiązywania zgłoszeń w repozytoriach, nie wszystkich typów pracy. Nie wynika z niego, że plik jest zbędny. Wynika, że nie jest magią.

Co warto wpisać do AGENTS.md lub CLAUDE.md?

Pasuje to, czego agent nie wyczyta z kodu i co jest prawdziwe w każdym zadaniu:

• Komendy uruchamiania: jak odpalić testy, linter, build (pytest -q, npm run lint).
• Konwencje, które odbiegają od domyślnych: np. „zmienne po angielsku, komentarze po polsku” albo „nie używamy klas, tylko funkcji”.
• Pułapki środowiska: „testy wymagają działającej bazy w Dockerze”, „tego katalogu nie edytuj ręcznie, jest generowany”.
• Fakty o wersjach, które model może znać inaczej: gdy używasz nowej wersji biblioteki ze zmianami łamiącymi zgodność.
• Zasady procesu: „przed zakończeniem zadania uruchom testy”.

Sprawdza się konkret zamiast ogólnika. „Uruchom pytest -q przed zakończeniem zadania” działa, a „dbaj o jakość kodu” nic agentowi nie mówi. Dokumentacja Claude Code zaleca zresztą celowanie w poniżej 200 linii na plik, bo dłuższe pliki zjadają kontekst i obniżają wykonywanie instrukcji.

Czego nie wpisywać do pliku kontekstowego?

Na podstawie wyników badania:

• Przeglądu struktury katalogów („src/ zawiera kod, tests/ zawiera testy”). Agent sam przeczyta drzewo plików, a opis się dezaktualizuje.
• Opisu architektury, który wynika z samego kodu. Jeśli agent dojdzie do tego jednym grep, nie płać za to w każdej sesji.
• Listy zależności. Są w requirements.txt lub package.json.
• Sprzecznych instrukcji. Dokumentacja Claude Code ostrzega, że przy sprzecznych zasadach agent może wybrać jedną dowolnie.
• Rzeczy, które mają być wymuszone, nie zasugerowane. Plik kontekstowy to prośba, nie zabezpieczenie. Do blokowania akcji służą uprawnienia i hooki; więcej o kontroli akcji agenta w artykule o uprawnieniach i zatwierdzaniu akcji agenta AI w Pythonie.
• Sekretów. Plik leży w repozytorium, więc nie wpisuj tam kluczy ani haseł. O typowych lukach w kodzie z AI piszę w artykule o bezpieczeństwie kodu generowanego przez AI.

Dlaczego narzędzie nie widzi mojego pliku z instrukcjami?

To jeden z najczęstszych problemów, a pytania o niego wracają na Stack Overflow: plik leży w repozytorium, a agent zachowuje się tak, jakby go nie było. Sprawdź po kolei:

1. Czy ta wersja narzędzia obsługuje ten plik? Nie każde narzędzie czyta AGENTS.md, a niektóre obsługują go tylko w części funkcji. Zerknij do tabeli wyżej i do dokumentacji.
2. Czy nazwa i rozszerzenie są dokładnie takie, jakich oczekuje narzędzie? Cursor ignoruje .md w .cursor/rules, a Copilot oczekuje .github/copilot-instructions.md.
3. Czy plik leży we właściwym katalogu? Narzędzia szukają od korzenia repozytorium lub od bieżącego katalogu w dół. Uruchomienie agenta w podkatalogu może zmienić, które pliki zostaną wczytane.
4. Czy plik nie jest za długi? Codex przestaje dodawać pliki po przekroczeniu limitu rozmiaru, a Claude Code zaleca krótkie pliki.
5. Czy to nowa sesja? Zmiana pliku działa w kolejnej sesji lub po ponownym uruchomieniu narzędzia. Nie zawsze w trwającej rozmowie.

Prosty test diagnostyczny: dopisz do pliku zdanie „Na początku każdej odpowiedzi napisz słowo TEST” i otwórz nową sesję. Jeśli agent go nie wykona, problem leży w ładowaniu pliku, nie w jego treści. Potem usuń to zdanie.

Jak zorganizować plik w większym projekcie?

Gdy projekt rośnie, jeden plik z setkami linii przestaje działać. Zamiast tego:

• Trzymaj stałe zasady w jednym głównym pliku i dziel resztę według obszaru.
• Używaj plików zagnieżdżonych. AGENTS.md w podkatalogu (np. backend/) opisuje tylko to, co dotyczy tej części; narzędzia traktują bliższy plik jako ważniejszy.
• Używaj reguł dla ścieżek, jeśli narzędzie je ma: .claude/rules/ z polem paths: w Claude Code, globs w regułach Cursora, applyTo w Copilocie. Reguła dla src/api/** ładuje się tylko wtedy, gdy agent pracuje z takimi plikami.
• Importy nie oszczędzają kontekstu. Według dokumentacji Claude Code plik zaimportowany linijką @ ładuje się razem z importującym, więc służy porządkowi, a nie oszczędności.

Wzorzec „jeden plik dla wielu narzędzi” wygląda tak:

# CLAUDE.md
@AGENTS.md

## Claude Code
Use plan mode before changing more than three files.

Reguły wspólne trzymasz w AGENTS.md, a w CLAUDE.md dopisujesz tylko to, co dotyczy samego Claude Code.

Jak sprawdzić, czy mój plik cokolwiek daje?

Skoro badanie pokazuje, że efekt bywa zerowy, nie zgaduj. Przetestuj własny plik prostą metodą:

1. Wybierz jedno zadanie, które pojawia się u ciebie często (np. „dodaj endpoint z walidacją i testem”).
2. Uruchom je kilka razy bez pliku (usuń go lub zmień nazwę). Zapisz, czy testy przeszły, ile było kroków i ile to kosztowało.
3. Uruchom to samo zadanie tyle samo razy z plikiem.
4. Porównaj wyniki. Jeśli plik nie skraca drogi ani nie poprawia rezultatu, odchudź go albo usuń.

Pojedynczy przebieg to za mało, bo agent daje różne wyniki przy tym samym zadaniu. To metoda do powtórzenia, nie wynik, który ja ci podaję: nie mam własnych pomiarów, więc ich nie wymyślam. Koszty i limity tokenów wyjaśniam w artykule o tokenach, kontekście i kosztach API OpenAI.

Jak wygląda to w prawdziwym repozytorium?

Tak wygląda plik kontekstowy tej strony. CLAUDE.md ma jedną linię:

@AGENTS.md

A AGENTS.md to krótki blok o Next.js, który nie został napisany ręcznie: dopisuje go i odtwarza narzędzie deweloperskie (next dev), oznaczając go znacznikami początku i końca. Zaczyna się tak:

# This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file
structure may all differ from your training data. Read the relevant
guide in node_modules/next/dist/docs/ before writing any code.

Dwa wnioski:

• Wzorzec @AGENTS.md pozwala trzymać jedno źródło prawdy: CLAUDE.md tylko je importuje, a inne narzędzia czytają AGENTS.md bezpośrednio.
• To dobry przykład niestandardowej reguły. Nie opisuje struktury projektu i nie pyta o oczywistości. Mówi agentowi coś, czego jego dane treningowe mogą nie zawierać: że ta wersja frameworka różni się od tej, którą zna, i gdzie szukać aktualnej dokumentacji. To dokładnie ta kategoria, którą badanie uznaje za użyteczną.

Czy agent i tak by to zrobił? Test jednej linijki

Najprostszy sposób na odchudzenie pliku to pytanie do każdej linijki: czy agent znalazłby to sam w kodzie lub w konfiguracji? Jeśli tak, wykreśl. Jeśli nie, zostaw. Poniższa tabela to przykład ilustracyjny dla wymyślonego projektu w FastAPI, nie dane z prawdziwego repozytorium:

Po takim czyszczeniu zostają trzy-cztery rzeczy, które kosztują niewiele i naprawdę coś zmieniają. Wnioski z badania i z praktyki są zgodne: krótki plik z niestandardowymi regułami wygrywa z długim opisem projektu.

Podsumowanie: jak pisać AGENTS.md i CLAUDE.md

• Plik kontekstowy to prośba, nie gwarancja i koszt, nie darmowa poprawa. Badanie nie wykazało ogólnej poprawy skuteczności, a koszt rośnie o około 20%.
• Wpisuj komendy, niestandardowe konwencje, pułapki i fakty o wersjach, których model może nie znać.
• Nie wpisuj przeglądu katalogów, zależności ani niczego, co agent znajdzie jednym wyszukiwaniem.
• Trzymaj stałe zasady w jednym AGENTS.md, a w CLAUDE.md dodaj tylko @AGENTS.md i to, co dotyczy Claude Code.
• Jeśli narzędzie „nie widzi” pliku, sprawdź nazwę, rozszerzenie, katalog, rozmiar i to, czy zaczynasz nową sesję.
• Zanim rozbudujesz plik, przetestuj go na własnym zadaniu: kilka przebiegów bez pliku i z plikiem.

Jak zaplanować zadanie dla agenta, zanim napiszesz pierwszy plik, pokazuję w artykule o spec-driven development. A jeśli chcesz uczyć się programować z AI tak, żeby rozumieć kod, który powstaje, zajrzyj do artykułu o halucynacjach AI w kodzie.