AGENTS.md: co to jest, kto go czyta i co wpisać do pliku (2026)

Czym jest AGENTS.md i do czego służy?

AGENTS.md to wersjonowany plik Markdown w repozytorium, który przekazuje agentowi kodującemu kontekst projektu: komendy instalacji, build, test i lint, strukturę katalogów, konwencje kodu oraz granice bezpieczeństwa. Format nie ma obowiązkowego schematu ani wymaganych sekcji — to zwykły Markdown, który uzupełnia README, a nie zastępuje dokumentacji dla ludzi [2][8]. Sam plik nie koduje, nie testuje i nie egzekwuje reguł; opisuje warunki pracy agenta.

Jeśli dopiero porównujesz narzędzia, zacznij od huba AI do programowania — zbieramy tam przewodniki po agentach i ich konfiguracji. Warto znać chronologię formatu. AGENTS.md wydano w sierpniu 2025 roku [1]. 9 grudnia 2025 roku Linux Foundation ogłosiła utworzenie Agentic AI Foundation (AAIF), a AGENTS.md został jednym z jej projektów założycielskich obok Model Context Protocol i goose [1]. Governance ma być neutralne: OpenAI pozostaje fundatorem, ale nie jest już jedynym właścicielem formatu [1].

Kto czyta AGENTS.md, a kto CLAUDE.md lub GEMINI.md?

AGENTS.md czyta część narzędzi natywnie, ale nie wszystkie — i nie zastępuje plików, które poszczególni producenci zostawili dla siebie. Codex, GitHub Copilot, Cursor, Jules, Devin, Factory i VS Code wspierają AGENTS.md, jednak nazwy i mechanizmy plików natywnych nadal się różnią [1][9]. Claude Code korzysta z CLAUDE.md, a Gemini CLI domyślnie z GEMINI.md [1][9].

Wniosek praktyczny: jeśli zespół używa kilku asystentów, AGENTS.md jest jedynym plikiem, który wszystkie przeczytają w tej samej postaci. Jeśli pracujecie wyłącznie w jednym narzędziu, plik natywny producenta wystarczy. O automatyzacji pracy zespołu z asystentami piszemy też w tekście o Codeksie w sprzedaży i forecastach bez kodu.

Ile projektów naprawdę używa AGENTS.md?

Linux Foundation podała 9 grudnia 2025 roku, że format przyjęło ponad 60 000 projektów open source i frameworków [1]. To deklaracja projektu i fundacji, nie audytowane zestawienie repozytoriów, dlatego liczbę warto podawać z tym zastrzeżeniem.

W niezależnych opracowaniach liczba bywa skracana do „60 000 repozytoriów GitHub”, choć oficjalny komunikat nie używa takiego sformułowania i nie wskazuje publicznego zestawienia do weryfikacji [1]. Skala adopcji jest realna, ale dokładny mianownik pozostaje deklaracją. Podobny problem mają inne liczby krążące w sieci — na przykład listy narzędzi wspierających format, które mieszają wsparcie natywne z odczytem przez import lub konfigurację [1][9].

Co wpisać do AGENTS.md?

Plik powinien zawierać konkretne komendy instalacji, build, test i lint, opis struktury repozytorium, konwencje kodu, workflow Git oraz granice bezpieczeństwa — na przykład zakaz modyfikacji sekretów i konfiguracji produkcyjnej [4]. GitHub opublikował wskazówki oparte na ponad 2 500 repozytoriach [4].

Sensowny minimalny zestaw wygląda tak:

• komendy startowe: instalacja zależności, build, test, lint — dokładnie w formie, w jakiej działają w repozytorium;
• mapa struktury: które katalogi są krytyczne i co zależy od czego;
• konwencje: nazewnictwo, frameworki, formatowanie, obsługa błędów;
• granice: czego nie wolno zmieniać, gdzie leżą sekrety i konfiguracja produkcyjna;
• workflow Git: nazwy gałęzi, wymagania pull requestu, obowiązkowe testy.

Nie ma obowiązkowych pól ani schematu [2][8]. Krótszy plik z prawdziwymi komendami jest lepszy niż obszerny dokument opisujący intencje. Bezpieczeństwo łańcucha dostaw w repozytoriach to osobny temat — pisaliśmy o nim w artykule o rozszerzeniu VS Code, które naraziło 3800 repozytoriów.

Czy AGENTS.md poprawia wyniki agentów?

Badania dają mieszany obraz. Pliki pisane przez deweloperów mogą nieznacznie poprawiać skuteczność, ale zwiększają liczbę kroków i koszt; pliki generowane przez modele językowe często pogarszały wyniki [5]. AGENTS.md dostarcza kontekst, nie gwarantuje jakości.

Drugie z badań odnotowało medianę czasu krótszą o 28,64% i zużycie tokenów mniejsze o 16,58%, ale autorzy opisali wyniki jako wstępne [6]. Rozbieżność między badaniami nie jest sprzecznością — różnią się skalą, doborem zadań i sposobem mierzenia kosztu. Praktyczny wniosek dla zespołu: traktuj plik jako element procesu, a nie jako zabezpieczenie przed błędami. Ani dokumentacja Codeksa, ani GitHub nie opisują AGENTS.md jako mechanizmu egzekwowania — instrukcja nie uruchomi testów za agenta [3][4].

Jak działa AGENTS.md w monorepo?

Codex dokumentuje warstwowe wyszukiwanie plików AGENTS.md oraz AGENTS.override.md — narzędzie stosuje instrukcje właściwe dla danego drzewa katalogów [3]. W monorepo oznacza to, że plik w katalogu pakietu może doprecyzować reguły z katalogu głównego.

Praktyka jest prosta: w korzeniu trzymaj reguły wspólne dla całego repozytorium, a w podkatalogach tylko to, co różni się między pakietami — komendy testów, wersje frameworków, zakazy charakterystyczne dla modułu. Nie duplikuj treści, bo rozjazd między kopiami jest trudny do wykrycia. Jeśli używasz wielu narzędzi jednocześnie, sprawdź ich dokumentację osobno: hierarchia plików natywnych nie musi działać identycznie [3][9].

Najczęstsze pytania

Czy AGENTS.md jest formalnym standardem?

Nie w sensie ISO czy IETF. Linux Foundation nazywa go prostym, uniwersalnym standardem, a projekt jest pod opieką AAIF [1]. Trafniejsze określenie to otwarty, de facto standard lub wspólny format. Nie ma organu certyfikującego ani obowiązkowej walidacji treści, więc „standard” oznacza tu raczej powszechną konwencję niż specyfikację techniczną [2][8].

Czy AGENTS.md zastępuje CLAUDE.md?

Nie. Claude Code korzysta z CLAUDE.md, a Gemini CLI domyślnie z GEMINI.md, więc plik uniwersalny nie wyłącza plików natywnych [1][9]. W praktyce utrzymuje się AGENTS.md jako warstwę wspólną i krótkie pliki natywne z odwołaniem do niego. Dzięki temu zmiana konwencji w zespole trafia w jedno miejsce, a nie w trzy kopie.

Czy AGENTS.md musi mieć określony schemat?

Nie ma obowiązkowych sekcji ani pól. Format to zwykły Markdown, a dokumentacja projektu opisuje go jako uzupełnienie README, nie zamiennik dokumentacji dla ludzi [2][8]. Zespół sam decyduje o układzie. Warto jednak trzymać stałą kolejność sekcji, żeby agent i nowi członkowie zespołu znajdowali informacje w przewidywalnym miejscu.

Czy wystarczy wygenerować AGENTS.md modelem?

Nie ma na to dowodów, a badanie AGENTbench wskazuje, że pliki generowane przez LLM często pogarszały wyniki agentów [5]. Plik pisany przez dewelopera ma szansę nieznacznie pomóc, ale zwiększa koszt i liczbę kroków [5]. Najbezpieczniej zacząć od ręcznie spisanych komend, które naprawdę działają w repozytorium, a model wykorzystać tylko do redakcji tekstu.

Od czego zacząć w małym projekcie?

Od jednego pliku w katalogu głównym: komendy instalacji, build i test, krótki opis struktury oraz lista rzeczy zakazanych [4]. To wystarczy, żeby agent nie zgadywał poleceń. Reszta — konwencje, workflow Git, reguły pull requestów — może dojść później, gdy pojawi się realny problem do rozwiązania, a nie z góry przyjęty szablon.

Źródła

1. Linux Foundation Announces the Formation of the Agentic AI Foundation (AAIF), Anchored by New Project Contributions Including Model Context Protocol (MCP), goose and AGENTS.md (Linux Foundation, 2025)
2. AGENTS.md (agents.md, 2026)
3. Custom instructions with AGENTS.md (OpenAI, 2026)
4. How to write a great agents.md: Lessons from over 2,500 repositories (The GitHub Blog, 2026)
5. Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (arXiv, 2026)
6. On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents (arXiv, 2026)
7. AGENTS.md — a simple, open format for guiding coding agents (GitHub, agentsmd/agents.md)
8. AGENTS.md Complete Guide for Engineering Teams (BuildBetter, 2026)
9. AGENTS.md Guide (2026): Copilot, Cursor & More (vibecoding.app, 2026)
10. AGENTS.md (Atlan Docs, 2026)
11. Codex AGENTS.md Explained: How Team Instructions Work (Verdent, 2026)