Przejdź do treści

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.

AGENTS.md: jak napisać plik instrukcji dla agentów AI w 2026 roku
Spis treści
  1. Czym jest AGENTS.md?
  2. Kto odpowiada za format i od kiedy?
  3. Jakie sekcje powinien zawierać plik?
  4. Jeden plik w katalogu głównym czy pliki zagnieżdżone?
  5. Które narzędzia czytają ten plik?
  6. Czy plik naprawdę poprawia wyniki agentów?
  7. Jak wdrożyć plik w istniejącym projekcie?
  8. Najczęstsze pytania
  9. Źródła

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.

KryteriumJeden plik w katalogu głównymPliki zagnieżdżone w katalogach
Kontekst dla agentawszystkie reguły w jednym miejscureguły bliżej modyfikowanego kodu [1]
Wsparcie narzędziformat wymieniany na oficjalnej liście wspieranych narzędzi [1]obsługa plików zagnieżdżonych jest węższa [1]
Utrzymaniejedna wersja do przegląduwięcej plików i ryzyko sprzecznych reguł
Skalawystarcza w małych repozytoriachsprawdza 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?

  1. Zacznij od komend. Wypisz polecenia instalacji, budowania i testów, których zespół używa codziennie.
  2. Dodaj konwencje, które najczęściej łamie nowa osoba w zespole: nazewnictwo, układ katalogów, obsługę błędów.
  3. Opisz granice: czego agent nie może zmienić bez przeglądu człowieka i które katalogi są wyłączone z automatycznych zmian.
  4. Wersjonuj plik razem z kodem i przeglądaj zmiany w pull requeście jak każdy inny plik projektu.
  5. 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

  1. AGENTS.md (agents.md, 2025)
  2. OpenAI co-founds Agentic AI Foundation, donates AGENTS.md (OpenAI, 2025)
  3. Po co projektowi AGENTS.md i co tam wpisać, żeby agent nie… (hermes-agent.pl, 2026)
  4. AGENTS.md w Codex: jak nauczyć AI standardów twojego kodu (mojafirma.ai, 2026)
  5. Wzorce AGENTS.md: co naprawdę zmienia zachowanie agenta (blakecrosley.com, 2026)
  6. Tworzenie autonomicznych potoków deweloperskich za pomocą plików agents.md (Google Codelabs, 2026)
  7. Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (arXiv, 2026)
AN
O autorze
Andrzej Niemiec

Fanatyk nowych technologii i specjalista w zakresie sztucznej inteligencji.

Jak powstają teksty: Polityka AI · O redakcji