Tutoriale how-to
AGENTS.md: jak napisać plik instrukcji dla agentów AI w 2026 roku
Zaktualizowano: Autor: Andrzej Niemiec10 min czytania
Czym jest AGENTS.md, jakich sekcji wymaga i kiedy podnosi koszt pracy agenta. Praktyczny przewodnik po formacie instrukcji dla Codex, Cursor i Copilot.
Spis treści
Czym jest AGENTS.md?
AGENTS.md to plik Markdown umieszczony w repozytorium, który przekazuje agentowi kodującemu kontekst projektu. Oficjalna strona formatu opisuje go jako „README for agents”, czyli README dla agentów [1]. Plik zawiera komendy instalacji, budowania i testów, konwencje kodu oraz ograniczenia, których agent ma przestrzegać [1]. Nie jest modelem ani aplikacją. To zapis wiedzy o projekcie w formacie, który czyta narzędzie AI. Mechanizmy automatyzacji procesów biznesowych po stronie firmy opisujemy w dziale agenci AI i automatyzacja.
Plik nie zastępuje testów ani przeglądu kodu. Jest instrukcją wejściową: agent czyta go na starcie zadania i na tej podstawie wybiera narzędzia oraz sposób pracy. Dlatego jego treść działa jak konfiguracja, a nie jak dokumentacja dla ludzi.
Kto odpowiada za format i od kiedy?
OpenAI opisało przekazywanie Codexowi instrukcji dotyczących struktury projektu, komend i testów w maju 2025 r. [2]. Wydanie formatu komunikacja firmy wiąże z sierpniem 2025 r. [2]. 9 grudnia 2025 r. OpenAI przekazało AGENTS.md fundacji Agentic AI Foundation działającej przy Linux Foundation [2]. Format ma więc neutralne, wielowendorowe zarządzanie, a nie jednego właściciela produktu.
Oficjalna strona formatu wskazuje datę 19 marca 2025 r. [1]. Skala użycia jest mierzalna: repozytorium OpenAI zawiera 88 plików AGENTS.md [1]. Ta liczba pokazuje, że plik nie jest dodatkiem do jednego projektu, ale elementem codziennej pracy nad kodem. Standard funkcjonuje obok innych mechanizmów przekazywania kontekstu agentom, opisanych w tekście o współdzielonej pamięci dla agentów AI.
Jakie sekcje powinien zawierać plik?
Format nie ma obowiązkowego schematu i pozwala używać dowolnych nagłówków [1]. Oficjalna dokumentacja wymienia typowe sekcje: opis projektu, komendy instalacji, budowania i testów, konwencje kodu, testowanie, bezpieczeństwo oraz ograniczenia [1]. Polscy autorzy opisują plik jako praktyczny interfejs między zespołem a agentem i zwracają uwagę, że README już nie wystarcza [3]. Przewodniki praktyczne wymieniają konwencje nazewnictwa, zasady testowania, workflow zespołu i listę wzorców zakazanych [4].
Trzy elementy powtarzają się w każdym z tych opisów. Pierwszy to komendy: dokładne polecenia instalacji, budowania i uruchamiania testów, żeby agent nie zgadywał narzędzi. Drugi to konwencje: styl nazewnictwa, układ katalogów, sposób obsługi błędów. Trzeci to granice: czego agent nie może zmienić bez zgody człowieka i które katalogi są wyłączone z automatycznych zmian.
Polecamy trzymać w pliku nazwy zmiennych środowiskowych, a nie wartości kluczy. Sekret zapisany w repozytorium zostaje w historii gita także wtedy, gdy usunie się go z pliku.
Jeden plik w katalogu głównym czy pliki zagnieżdżone?
Format dopuszcza pliki zagnieżdżone w monorepo: plik w katalogu bliższym modyfikowanemu kodowi może dostarczać reguły dla konkretnego podprojektu [1]. GitHub ogłosił obsługę plików głównych i zagnieżdżonych 28 sierpnia 2025 r. [1]. Wybór między jednym plikiem a kilkoma zmienia sposób utrzymania dokumentacji.
| Kryterium | Jeden plik w katalogu głównym | Pliki zagnieżdżone w katalogach |
|---|---|---|
| Kontekst dla agenta | wszystkie reguły w jednym miejscu | reguły bliżej modyfikowanego kodu [1] |
| Wsparcie narzędzi | format wymieniany na oficjalnej liście wspieranych narzędzi [1] | obsługa plików zagnieżdżonych jest węższa [1] |
| Utrzymanie | jedna wersja do przeglądu | więcej plików i ryzyko sprzecznych reguł |
| Skala | wystarcza w małych repozytoriach | sprawdza się w monorepo; repozytorium OpenAI ma 88 plików [1] |
Które narzędzia czytają ten plik?
Oficjalna lista wymienia Codex, Cursor, Gemini CLI, Jules, Factory, Aider, Zed, Windsurf, VS Code i GitHub Copilot [1]. Wsparcie nie oznacza identycznego działania — macierz zgodności dla ośmiu narzędzi pokazuje różnice w tym, jak plik wpływa na zachowanie agenta [5]. Google opisuje własny wariant użycia pliku agents.md w potokach deweloperskich Antigravity [6].
W praktyce warto sprawdzić dokumentację konkretnego narzędzia, zanim przeniesie się reguły z jednego agenta do drugiego. Ten sam zapis może być mocno respektowany w jednym kliencie i traktowany wyłącznie jako sugestia w innym.
Czy plik naprawdę poprawia wyniki agentów?
Badanie arXiv 2602.11988, którego najnowsza wersja została złożona 29 września 2026 r., nie wykazało ogólnej poprawy skuteczności wykonywania zadań przez pliki kontekstowe repozytorium [7]. Koszt inferencji rósł w nim średnio o ponad 20% [7]. Najlepiej działały konkretne instrukcje, a nie ogólne opisy repozytorium [7].
Wniosek jest praktyczny. Plik nie jest gwarancją jakości ani skrócenia pracy. Jest nośnikiem reguł, których wartość zależy od precyzji: im więcej konkretnych komend i zakazów, tym mniejsze pole na interpretację. Ogólne hasła o dobrych praktykach kosztują tokeny, a nie zmieniają zachowania modelu. Dlatego sekcje z liczbami i poleceniami warto trzymać krótko, a opisy projektu ograniczyć do niezbędnego minimum.
Jak wdrożyć plik w istniejącym projekcie?
- Zacznij od komend. Wypisz polecenia instalacji, budowania i testów, których zespół używa codziennie.
- Dodaj konwencje, które najczęściej łamie nowa osoba w zespole: nazewnictwo, układ katalogów, obsługę błędów.
- Opisz granice: czego agent nie może zmienić bez przeglądu człowieka i które katalogi są wyłączone z automatycznych zmian.
- Wersjonuj plik razem z kodem i przeglądaj zmiany w pull requeście jak każdy inny plik projektu.
- Usuń ogólniki. Zdania, których nie da się sprawdzić w kodzie, nie zmieniają zachowania agenta [7].
Zasady ograniczania uprawnień agenta omawiamy też w tekście o fakturach, do których agent nie powinien mieć dostępu oraz w artykule o kontroli nad agentem.
Najczęstsze pytania
Czym AGENTS.md różni się od README.md?
README opisuje projekt człowiekowi: instalację, przykłady użycia, licencję. AGENTS.md opisuje projekt agentowi: komendy, konwencje, testy i ograniczenia [1]. Format uzupełnia README, a nie go zastępuje [1]. W małym repozytorium wystarcza jeden plik, w monorepo dochodzą pliki zagnieżdżone przy podprojektach [1].
Czy AGENTS.md jest obowiązkowy?
Nie ma obowiązkowego schematu ani wymaganej listy sekcji [1]. Nie jest też warunkiem działania żadnego z wymienionych narzędzi [1]. To konwencja, którą zespół przyjmuje samodzielnie. Badanie z 2026 r. pokazuje, że sam plik nie gwarantuje poprawy wyników, więc warto traktować go jako element procesu, a nie zamiennik testów [7].
Czy w pliku można trzymać klucze API?
Nie polecamy. Plik trafia do repozytorium i zostaje w historii gita. Zamiast wartości wpisz nazwę zmiennej środowiskowej oraz informację, gdzie jej szukać. To zasada higieny pracy z repozytorium, a nie wymóg formatu.
Ile plików AGENTS.md powinno być w monorepo?
Tyle, ile podprojektów wymaga własnych reguł. Plik w katalogu bliżej kodu dostarcza reguły dla tego obszaru [1]. Repozytorium OpenAI ma 88 takich plików [1]. Koszt utrzymania rośnie z każdym plikiem, więc w małym repozytorium jeden plik w katalogu głównym jest zwykle wystarczający.
Źródła
- AGENTS.md (agents.md, 2025)
- OpenAI co-founds Agentic AI Foundation, donates AGENTS.md (OpenAI, 2025)
- Po co projektowi AGENTS.md i co tam wpisać, żeby agent nie… (hermes-agent.pl, 2026)
- AGENTS.md w Codex: jak nauczyć AI standardów twojego kodu (mojafirma.ai, 2026)
- Wzorce AGENTS.md: co naprawdę zmienia zachowanie agenta (blakecrosley.com, 2026)
- Tworzenie autonomicznych potoków deweloperskich za pomocą plików agents.md (Google Codelabs, 2026)
- Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (arXiv, 2026)
Fanatyk nowych technologii i specjalista w zakresie sztucznej inteligencji.
Jak powstają teksty: Polityka AI · O redakcji