AGENTS.md: jeden plik kontekstu dla każdego agenta kodującego (Codex, Antigravity, Claude)

Poświęciłeś całe popołudnie na napisanie porządnego CLAUDE.md. Twój agent w końcu przestał zgadywać twój stack i zaczął uruchamiać właściwą komendę testów. A potem kolega z zespołu otwiera to samo repo w Codex, ty próbujesz Antigravity CLI na bocznym branchu i cały ten z trudem wypracowany kontekst nigdzie nie przechodzi. Każde narzędzie chce własnego pliku, w swoim własnym miejscu.

AGENTS.md to odpowiedź na ten bałagan: jeden zwykły plik Markdown, w katalogu głównym repo, który każdy agent kodujący czyta, zanim dotknie twojego kodu.

Czym właściwie jest AGENTS.md

Żadnej magii. To plik Markdown o nazwie AGENTS.md, zwykle w katalogu głównym repozytorium, który agent ładuje jako stałe instrukcje, zanim zacznie pracować. Potraktuj go jak README, które piszesz dla swoich kolegów z zespołu AI zamiast dla tych z krwi i kości: czym jest projekt, jak go zbudować i przetestować, jakie konwencje należy uszanować i jakich pułapek unikać.

To otwarta konwencja, czytana już przez Codex i rosnącą listę narzędzi agentowych, pomyślana tak, by była przenośna między nimi. Jeden plik, mnóstwo agentów, zamiast jednego pliku szytego na miarę dla każdego narzędzia.

AGENTS.md vs CLAUDE.md vs GEMINI.md

Gdy ten przewodnik powstawał, każde narzędzie szukało własnego pliku. Większość z nich przeszła od tego czasu na AGENTS.md:

• Codex czyta AGENTS.md, podobnie jak GitHub Copilot CLI, Cursor, Amp i większość nowszych CLI agentów.
• Claude Code czyta CLAUDE.md, a od wersji 2.1.277 sam czyta też AGENTS.md, gdy w twoim katalogu roboczym i katalogach nad nim nie ma CLAUDE.md ani CLAUDE.local.md. Gdy istnieje CLAUDE.md, Claude czyta tylko ten plik, chyba że zmienisz ustawienie Project instructions w /config.
• Antigravity CLI czyta AGENTS.md lub GEMINI.md, w katalogu głównym repozytorium albo w dowolnym podkatalogu, a do tego folder .agents/rules/ i reguły globalne w ~/.gemini/.

Treść jest niemal identyczna we wszystkich trzech: kontekst projektu, komendy, konwencje. Różni się nadal to, który plik narzędzie wybiera, gdy znajdzie ich kilka. Właśnie dlatego ręczne duplikowanie tych samych reguł w trzech plikach to walka z góry przegrana (więcej o utrzymywaniu ich w synchronizacji poniżej). Sprawdziliśmy to zachowanie 10 października 2026 r. w dokumentacji pamięci Claude Code i w dokumentacji reguł Antigravity.

Jeśli pracujesz głównie w Claude Code, nasz przewodnik po CLAUDE.md wchodzi głęboko w strukturę specyficzną dla Claude. AGENTS.md to neutralny, niezależny od dostawcy kuzyn tego pliku.

Co w nim umieścić

Trzymaj go krótkim i mocno sygnałowym. Agent czyta go przy każdym zadaniu, więc każda linijka walczy o uwagę. To, co najważniejsze:

• Stack, jednym tchem. "Next.js 16, TypeScript, Prisma, MariaDB." Bez historii, bez marketingu.
• Komendy, które mają znaczenie. Jak zainstalować, uruchomić, zbudować, przetestować i odpalić linter. Dokładne komendy: npm test, nie "uruchom testy."
• Konwencje. Nazewnictwo, układ plików, obsługa błędów, wzorce, których faktycznie pilnujesz podczas review.
• Mapa katalogów. Dwie linijki o tym, gdzie co leży, żeby agent przestał grepować na ślepo.
• Reguły "przeczytaj, zanim dotkniesz". "Przeczytaj docs/payments.md, zanim zmienisz cokolwiek w billing/." Ten jeden nawyk zapobiega masie szkód.
• Twarde zakazy. "Nigdy nie twórz brancha bez polecenia." "Żadnych bezwzględnych ścieżek powiązanych z maszyną w commitowanych plikach."

Błędy, które sprawiają, że agenty go ignorują

Plik kontekstu zawodzi po cichu. Agent nie rzuca błędem, on po prostu dryfuje. Typowe przyczyny:

1. Za długi. Plik na 600 linii grzebie pięć reguł, które naprawdę się liczą. Wytnij wszystko, co agent może wywnioskować z samego kodu.
2. Sprzeczności. "Zawsze pisz testy" w jednej sekcji, "pomijaj testy dla prototypów" w innej. Agent wybiera jedną na chybił trafił.
3. Ścieżki powiązane z maszyną. /Users/you/project/... w commitowanym pliku psuje się u każdego kolegi z zespołu i u każdego agenta na każdej innej maszynie. Trzymaj ścieżki względne.
4. Nieaktualne komendy. Komenda testów zmieniła się pół roku temu, plik nie. Teraz agent z pełnym przekonaniem uruchamia nie to, co trzeba.
5. Brak priorytetów. Wszystko jest "ważne," więc nic nie jest. Postaw rzeczy bezdyskusyjne na początku i je oznacz.
6. Wrzucanie dokumentacji. To są instrukcje, a nie wiki. Linkuj do swojej dokumentacji, nie wklejaj jej tutaj.

Utrzymanie jednego kontekstu między dostawcami

Oto praktyczna część, którą większość poradników pomija. Jeśli ty albo twój zespół używacie więcej niż jednego CLI agenta, nie chcesz trzech rozjeżdżających się kopii tych samych reguł.

Dwa czyste podejścia:

• Jeden AGENTS.md, nic więcej. Jeśli nikt nie potrzebuje reguł dotyczących tylko Claude, trzymaj jeden AGENTS.md: Codex, Antigravity CLI i Claude Code 2.1.277 lub nowszy czytają go wszystkie. Haczyk jest cichy: dodany później CLAUDE.md albo osobisty CLAUDE.local.md sprawia, że Claude Code przestaje czytać AGENTS.md.
• Jeden plik kanoniczny, jeden import. Trzymaj wszystko w AGENTS.md, zacznij CLAUDE.md od linii @AGENTS.md, a pod nią wpisz reguły tylko dla Claude. Claude najpierw czyta zaimportowany plik. Nasze własne repozytorium działa właśnie tak: jego CLAUDE.md to ta jedna linia. Dowiązanie symboliczne (ln -s AGENTS.md CLAUDE.md) też działa, ale słabo na Windowsie, gdzie jego utworzenie wymaga uprawnień administratora lub trybu dewelopera, a klon bez core.symlinks dostaje jednoliniowy plik tekstowy zamiast twoich instrukcji.

Tak czy inaczej reguła jest ta sama: napisz kontekst raz, a nie raz na dostawcę. To zresztą jedyny sposób, żeby pozostał poprawny, bo pojedynczy plik to jedyny plik, który ludzie naprawdę utrzymują.

Kiedy uruchamiasz kilka agentów naraz

AGENTS.md na poziomie repo odpowiada na pytanie "czym jest ten projekt." Nie odpowiada na pytanie "kim jest ten agent." Kiedy uruchamiasz agenta Backend, agenta Frontend i agenta QA równolegle na tym samym kodzie, każdy z nich potrzebuje współdzielonego kontekstu projektu plus własnej roli.

To jest warstwa, którą AgentsRoom dokłada na wierzch twojego AGENTS.md. Każdy agent dostaje dedykowaną rolę z własnym system promptem (DevOps, Frontend, Security i inne), żeby współdzielony plik pozostał szczupły, a każdy agent i tak wiedział, na czym polega jego zadanie. Z założenia jest niezależny od dostawcy, więc ten sam zestaw uruchamia Claude, Codex albo Antigravity obok siebie, a twoje powtarzalne instrukcje żyją w bibliotece promptów zamiast być przepisywane do każdej sesji.

Kiedy do tego dojdziesz, metoda na uruchamianie kilku agentów równolegle bez gubienia wątku jest naturalną kolejną lekturą.

Wnioski

Napisz jeden AGENTS.md. Trzymaj go krótkim, aktualnym i przenośnym. Skieruj na niego każde narzędzie zamiast utrzymywać osobny plik na agenta. Twój kontekst przestaje być przywiązany do tego CLI, od którego akurat zacząłeś, a twoje agenty, jakiekolwiek byś nie uruchomił, startują z tej samej strony.

Chcesz mieć wszystkie agenty na jednym ekranie, każdego z własną rolą i twoim współdzielonym kontekstem? Pobierz AgentsRoom, podłącz swojego dostawcę i puść swoją flotę do pracy.

Często zadawane pytania

Czym jest AGENTS.md?

To plik Markdown, zwykle w katalogu głównym repozytorium, który agenty kodujące ładują jako stałe instrukcje, zanim zaczną pracować: czym jest projekt, jak go zbudować i przetestować, jakie konwencje uszanować i jakich pułapek unikać. To otwarta konwencja wspólna dla wielu narzędzi, a nie plik jednego narzędzia, czytana przez Codex, Antigravity CLI, GitHub Copilot CLI, Cursor, Amp oraz, od wersji 2.1.277, Claude Code.

Czy Claude Code czyta AGENTS.md?

Tak, od Claude Code 2.1.277, ale tylko wtedy, gdy w twoim katalogu roboczym ani wyżej nie ma CLAUDE.md, .claude/CLAUDE.md ani CLAUDE.local.md. Wtedy ładuje każdy AGENTS.md od katalogu roboczego w górę, a AGENTS.md z podkatalogu, gdy otwiera w nim plik. Jeśli istnieje CLAUDE.md, Claude czyta tylko ten plik, chyba że w /config ustawisz Project instructions na claude-md-and-agents-md. W starszych wersjach wstaw linię @AGENTS.md na początku pliku CLAUDE.md.

Czy Antigravity używa AGENTS.md czy GEMINI.md?

Obu. Antigravity czyta AGENTS.md, GEMINI.md albo folder .agents/rules/ w katalogu głównym repozytorium lub w dowolnym podkatalogu, a także reguły globalne z ~/.gemini/. Reguły sumują się, zamiast się nawzajem zastępować, a gdy dwie z nich są ze sobą sprzeczne, wygrywa reguła z bardziej szczegółowego katalogu.

Zostawić AGENTS.md czy CLAUDE.md?

Zostaw AGENTS.md jako jedyny plik, który utrzymujesz. Jeśli potrzebujesz też reguł tylko dla Claude, dodaj CLAUDE.md, którego pierwsza linia to @AGENTS.md, i wpisz te reguły pod nią: Claude najpierw czyta zaimportowany plik. Jeśli ich nie potrzebujesz, sam AGENTS.md wystarczy dla Claude Code 2.1.277 lub nowszego. Unikaj dwóch pełnych kopii tych samych reguł: ta, której nikt nie edytuje, się zdezaktualizuje.

Gdzie umieścić AGENTS.md?

W katalogu głównym repozytorium, dla reguł obowiązujących wszędzie. Claude Code i Antigravity czytają też pliki AGENTS.md w podkatalogach, więc pakiet albo usługa z własnymi komendami może mieć własny plik, czytany, gdy agent pracuje w tym katalogu.