AGENTS.md: jeden plik kontekstu dla każdego agenta kodującego (Codex, Gemini, 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 Gemini 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

Na razie krajobraz jest podzielony według narzędzi:

• CLAUDE.md to plik, którego szuka Claude Code.
• GEMINI.md to konwencja Gemini CLI.
• AGENTS.md to standard międzynarzędziowy, czytany przez Codex i inne, zaprojektowany tak, by być tym neutralnym.

Treść jest niemal identyczna we wszystkich trzech: kontekst projektu, komendy, konwencje. Jedyna prawdziwa różnica to nazwa pliku, który każde narzędzie czyta domyślnie. 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).

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 plik kanoniczny, cienkie wskaźniki. Trzymaj wszystko w AGENTS.md, a z CLAUDE.md i GEMINI.md zrób jednoliniowe pliki mówiące "patrz AGENTS.md," albo zrób z nich dowiązania symboliczne. Jedno źródło prawdy, każde narzędzie nakarmione.
• Jeden plik, współdzielony przez konwencję. Jeśli twoje narzędzia da się skierować na własną ścieżkę, wyceluj je wszystkie w AGENTS.md i skasuj resztę.

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 Gemini 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.