AGENTS.md, co to jest. Plik Markdown bez wymaganych pól, który czytają Codex, Cursor i Copilot
AGENTS.md to README dla agentów AI do kodu. Co do niego wpisać, gdzie go położyć, co z plikami w podfolderach i które narzędzia go czytają.
Część przewodnikaClaude Code. Kompletny przewodnik od instalacji po własne skille i pluginy
W tym tekście
W skrócie
AGENTS.md to zwykły plik Markdown w głównym folderze repozytorium, w którym zapisuje się instrukcje dla agentów AI piszących kod. Nie ma wymaganych pól, a w dużym projekcie może być kilka takich plików i pierwszeństwo ma ten najbliżej edytowanego kodu. Czytają go między innymi Codex, Cursor, Gemini CLI i agent GitHub Copilot.
Nowy programista dostaje dostęp do repozytorium i od razu odpala agenta AI. Agent nie wie, jak tu uruchamia się testy, więc zgaduje, puszcza złe polecenie i traci kwadrans na naprawianie czegoś, co wcale nie było zepsute. Jedna linijka w pliku AGENTS.md by to załatwiła. To najkrótsza odpowiedź na pytanie, co to jest AGENTS.md.
Ten tekst należy do naszego przewodnika po Claude Code. Fakty sprawdziliśmy na stronach twórców formatu i narzędzi, stan na 10 listopada 2026.
AGENTS.md, co to jest i po co go pisać
Strona formatu agents.md nazywa go README dla agentów. README jest dla ludzi. Opisuje projekt, mówi, jak zacząć, i nie powinno tonąć w szczegółach. AGENTS.md jest dla agentów AI, które piszą kod. Trafia tu to, co w README by przeszkadzało. Polecenia do budowania i testów, styl kodu, zasady przy pull requestach.
To otwarty format, a nie funkcja jednego producenta. Według strony agents.md używa go ponad 60 tysięcy projektów open source, a opiekuje się nim Agentic AI Foundation działająca przy Linux Foundation.
Dla firmy, która zleca kod albo ma u siebie programistę, sens jest prosty. Zasady projektu zapisuje się raz i każde narzędzie AI, które je czyta, zaczyna pracę z tą samą wiedzą. Nie trzeba ich przepisywać do osobnego pliku dla każdego programu.
Jaki format ma AGENTS.md
Żadnego szczególnego. To zwykły Markdown bez wymaganych pól i bez nagłówków, których trzeba użyć. Agent czyta ten tekst tak jak człowiek. Liczy się to, żeby instrukcje były konkretne i dało się sprawdzić, czy zostały wykonane.
Strona formatu radzi wpisać przede wszystkim polecenia do testów. Jeśli są w pliku, agent spróbuje je uruchomić i naprawić błędy, zanim uzna zadanie za skończone. Plik ma żyć razem z projektem, więc poprawia się go za każdym razem, gdy coś w projekcie się zmienia.
Tak może wyglądać AGENTS.md dla wymyślonego projektu, sklepu z kawą na Laravelu i Vue.
# Sklep Ziarno
Laravel 12 i Vue 3. Panel administracyjny leży w `resources/js/admin`.
## Uruchomienie
- `composer install` i `npm install` po pobraniu repozytorium
- `php artisan serve` i `npm run dev` startują stronę lokalnie
## Testy
- `php artisan test` przed każdym commitem
- `npm run lint` po każdej zmianie w plikach Vue
- Każda poprawka błędu dostaje test, który ten błąd odtwarza
## Styl kodu
- Wcięcia na 4 spacje w PHP i na 2 spacje w Vue
- Teksty dla klientów tylko w `lang/pl.json`
- Nowe tabele w bazie tylko przez migracje
## Pull requesty
- Tytuł w formacie `[sklep] krótki opis`
- Nie zmieniaj plików w `config/payments` bez pytaniaNie ma tu opisu firmy ani próśb o „dobry kod”. Agent sam widzi kod. Plik mówi mu tylko to, czego z kodu nie wyczyta.
Gdzie leży AGENTS.md i co z plikami w podfolderach
Główny plik leży w głównym folderze repozytorium. W dużym repozytorium z kilkoma aplikacjami można dodać osobny AGENTS.md w folderze każdej z nich. Zasada ze strony formatu jest prosta. Agent czyta plik najbliżej edytowanego kodu, więc ten z podfolderu ma pierwszeństwo przed głównym. Polecenie wpisane wprost w rozmowie wygrywa z każdym plikiem.
Szczegóły różnią się między narzędziami. Najdokładniej opisuje je OpenAI w dokumentacji Codex.
| Co | Jak to robi Codex |
|---|---|
| Plik globalny | ~/.codex/AGENTS.md dla wszystkich projektów |
| Nadpisanie | AGENTS.override.md czytany zamiast AGENTS.md |
| Kolejność | od głównego folderu repozytorium w dół do bieżącego |
| Łączenie | pliki sklejane, bliższy bieżącemu folderowi dochodzi później |
| Limit | 32 KiB łącznie, ustawienie project_doc_max_bytes |
Z tabeli wynika jedna praktyczna rzecz. Codex bierze z każdego folderu najwyżej jeden plik, a gdy suma dojdzie do limitu, kolejne pliki przestają się doklejać. Rozwlekły AGENTS.md szybko go zjada, więc lepiej pisać krótko.
Codex pozwala też uznać inne nazwy plików za instrukcje. Dopisuje się je w pliku ~/.codex/config.toml, a pliki spoza tej listy Codex pomija.
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536Kto czyta AGENTS.md
Strona agents.md wymienia narzędzia, które obsługują format. Są wśród nich Codex od OpenAI, Jules i Gemini CLI od Google, Cursor, Windsurf, Devin, Aider, Zed, Warp, VS Code, Junie od JetBrains i agent GitHub Copilot. Pełna lista na stronie jest dłuższa.
Dwa narzędzia z tej listy potrzebują jednej linijki konfiguracji. W Aider dopisuje się read: AGENTS.md do pliku .aider.conf.yml. W Gemini CLI wskazuje się AGENTS.md jako plik kontekstu w .gemini/settings.json.
Claude Code na liście nie ma. Mimo to dokumentacja Anthropic opisuje, że od wersji 2.1.277 Claude Code czyta AGENTS.md sam, jeśli w projekcie nie ma pliku CLAUDE.md. Kiedy dokładnie tak się dzieje i jak trzymać oba pliki w zgodzie, opisujemy w tekście AGENTS.md i CLAUDE.md. Sam CLAUDE.md omawia tekst CLAUDE.md, jak go napisać, a gotowe szablony są w przykładach CLAUDE.md.
AGENTS.md to instrukcja, a nie blokada
Agent czyta AGENTS.md i stara się go trzymać, ale to tekst dla modelu, a nie zamek. Anthropic pisze wprost, że takie pliki Claude traktuje jako kontekst, a nie wymuszoną konfigurację. Linijka „nie zmieniaj plików płatności” nikogo nie zatrzyma, jeśli agent uzna inaczej. To, co ma być naprawdę zablokowane, ustawia się w uprawnieniach konkretnego narzędzia. W Claude Code opisujemy to w tekście o uprawnieniach.
AGENTS.md trafia do repozytorium, więc widzi go każdy, kto ma do niego dostęp. Haseł, kluczy API i adresów wewnętrznych serwerów się tam nie wpisuje.
Na początek wystarczy plik z czterema sekcjami jak w przykładzie wyżej. Potem dopisujcie jedno zdanie za każdym razem, gdy agent drugi raz popełni ten sam błąd.
Jeśli chcecie wiedzieć, gdzie AI może zdjąć pracę z Waszej firmy, zamówcie bezpłatny audyt AI. Przejrzymy Wasze zadania i powiemy, od czego zacząć.
Dokumentacja do tematu
Co chcecie zmienić w swojej firmie?
Zostawcie numer. Porozmawiamy o Waszym procesie i sprawdzimy, czy możemy pomóc. Pierwsza rozmowa jest bezpłatna.
Usługa, o której jest ten tekst
Automatyzacja i AI / OCRAutomatyzacja przepisywania dokumentów, OCR i reguły sprawdzania, a dane zostają u Was.