60 000 repozytoriów GitHub już ma AGENTS.md — Twój projekt czeka

Agenci kodujący bez instrukcji to jak kierowca bez map. Wskakują w kod, dotykają wszystko, mówią "gotowe" bez weryfikacji. AGENTS.md zmienia to. Plik kontekstowy, który czytają Copilot, Claude Code, Cursor i 10 innych narzędzi, stał się de facto standardem — 60 000 publicznych repozytoriów GitHub go już używa [1]. Pokazujemy, dlaczego każdy builder powinien go mieć w projekcie już teraz.

Dlaczego agenci kodujący bez kontekstu robią chaos

Wyobraź sobie scenariusz: prosisz Claude Code o zmianę w jednym module. Agent wchodzi do repozytorium, nie wie, jaka jest architektura, nie zna konwencji kodu, nie wie, które pliki są krytyczne. Rezultat: zmienia kod poza scope'em, dotyka sąsiednich funkcji, halucynuje testy zamiast je uruchamiać [4].

To nie jest wina agenta. To brak instrukcji. Agent kodujący to maszyna, która czyta kontekst — jeśli go nie ma, wymyśla. AGENTS.md to plik, który mówi agentowi: "Oto architektura, oto konwencje, oto co możesz zmieniać, oto co jest zakazane" [2].

Praktyka pokazuje trzy główne problemy. Po pierwsze, agent wskakuje w kod bez zrozumienia repozytorium — zmienia rzeczy bez wiedzy o zależnościach. Po drugie, scope creep — zaczyna od jednej funkcji, kończy na pięciu plikach. Po trzecie, fake verification — mówi "testowałem", ale nigdy nie uruchomił żadnego testu [4].

AGENTS.md rozwiązuje to wymuszając regułę "evidence before code". Agent musi najpierw przeczytać plik, zrozumieć strukturę, potem dopiero pisać kod. To dodaje 20–30 sekund do sesji, ale oszczędza godziny debugowania.

AGENTS.md to już standard — stewardowany przez Linux Foundation

Od grudnia 2025 roku AGENTS.md jest stewardowany przez Agentic AI Foundation, część Linux Foundation [1]. To nie moda, to infrastruktura. Na maj 2026 ponad 60 000 publicznych repozytoriów GitHub używa tego pliku [1].

Natywne wsparcie ma 13+ narzędzi kodujących: OpenAI Codex CLI, GitHub Copilot, Google Gemini CLI, Cursor, Claude Code, Windsurf, Amp, Aider, Zed, Jules, Devin, Junie [1]. To znaczy, że każde z tych narzędzi automatycznie czyta AGENTS.md na starcie sesji — bez dodatkowej konfiguracji.

Dla polskich firm to oznacza jedno: jeśli używasz Copilota w zespole, jeśli masz Claude Code w IDE, jeśli ktoś z zespołu pracuje w Cursor — agenci czytają AGENTS.md. Pytanie nie brzmi "czy warto?", ale "co tam napiszemy?".

AGENTS.md vs CLAUDE.md vs SKILL.md — kto czyta co i kiedy

Zanim zaczniesz pisać, musisz wiedzieć, gdzie co wpisać. Trzy pliki, trzy role.

AGENTS.md to plik cross-tool. Zawiera instrukcje dla wszystkich agentów — niezależnie od tego, czy to Copilot, Gemini czy Claude Code [2]. Tu wpisz architekturę projektu, konwencje kodu, komendy build i test, ograniczenia bezpieczeństwa, zasady PR. Każdy agent go czyta [2].

CLAUDE.md to instrukcje specyficzne dla Claude Code. Claude Code czyta ten plik na starcie każdej sesji [3]. Tu wpisz wskazówki dla Claude — na przykład jak kompaktować kod, jakie uprawnienia ma, które skills może używać [3]. Ważne: Claude Code domyślnie czyta tylko CLAUDE.md, nie AGENTS.md. Aby Claude przeczytał AGENTS.md, musisz w CLAUDE.md dodać import @AGENTS.md [5].

SKILL.md to dokumentacja specjalnych narzędzi i funkcji dla agentów. Jeśli masz custom API, plugin, bibliotekę — opisz ją w SKILL.md [3].

Praktyka: w małym projekcie wystarczy AGENTS.md. W średnim projekcie — AGENTS.md + CLAUDE.md (jeśli używasz Claude Code). W dużym — wszystkie trzy, plus .cursorrules dla Cursor [2].

Jakie narzędzia natywnie wspierają AGENTS.md w 2026

Jeśli używasz któregokolwiek z tych narzędzi, AGENTS.md już działa:

OpenAI Codex CLI, GitHub Copilot, Google Gemini CLI — to narzędzia z dużych graczy. Cursor, Claude Code, Windsurf — to IDE z wbudowanymi agentami. Amp, Aider, Zed, Jules, Devin, Junie — to bardziej specjalistyczne narzędzia [1].

Każde z nich czyta AGENTS.md automatycznie. Nie musisz nic konfigurować. Wrzucisz plik do repozytorium, agent go przeczyta.

Praktyka: testuj AGENTS.md w narzędziu, które używasz. Otwórz Claude Code, uruchom sesję, poproś agenta o zmianę w kodzie — powinien przeczytać AGENTS.md na starcie. To potrwa 2–3 sekundy więcej, ale agent będzie miał kontekst.

Trzy błędy, które agenci robią bez AGENTS.md (i jak je naprawić)

Błąd 1: Agent wskakuje w kod bez zrozumienia repozytorium

Agent widzi plik, widzi funkcję, zaczyna pisać. Nie wie, że ta funkcja jest używana w 12 innych miejscach. Nie wie, że zmiana break'uje API. Nie wie, że jest test, który to sprawdza.

Rozwiązanie: AGENTS.md zawiera mapę repozytorium. Agent czyta, że "moduł X jest krytyczny, zmiana wymaga aktualizacji Y i Z". Agent czyta, że "każda zmiana API wymaga aktualizacji testów w pliku test/api.spec.js". To wymusza "evidence before code" [4].

Błąd 2: Agent zmienia kod poza scope'em

Prosisz o zmianę w module A. Agent zmienia moduł A, ale przy okazji "poprawia" moduł B, bo "wyglądał dziwnie". Scope creep. Godzina debugowania.

Rozwiązanie: AGENTS.md zawiera regułę "small scoped changes" [4]. Agent musi przeczytać: "Zmień TYLKO to, co zostało poproszone. Nie dotykaj sąsiedniego kodu. Jeśli widzisz problem — zgłoś, nie naprawiaj".

Błąd 3: Agent halucynuje zamiast weryfikować

Agent mówi "testowałem, wszystko działa". Ale nigdy nie uruchomił testu. Po prostu wygenerował tekst, który brzmi wiarygodnie.

Rozwiązanie: AGENTS.md zawiera regułę "real verification" [4]. Agent musi przeczytać: "Zanim powiesz 'gotowe', uruchom npm test. Jeśli test się nie uruchomi, nie mów 'gotowe'". To wymusza rzeczywistą weryfikację, nie halucynacje.

WRITING.md: reguły dla tekstu generowanego przez LLM

Jeśli piszesz z LLM, znasz problem: tekst jest zbyt polerowany, zbyt generyczny, pełen filler'a. "Warto zauważyć, że", "nie tylko... ale również", fake specificity — liczby wymyślone dla narracji.

WRITING.md to plik z regułami dla tekstu. Autor opisuje problem: agenci kodujący generują tekst, który wygląda profesjonalnie, ale jest pusty [7]. WRITING.md mówi: "Pisz konkretnie. Pisz liczby. Unikaj filler'a".

Plik dostępny jest w trzech rozmiarach [7]:

• 3900 słów — pełna specyfikacja z przykładami
• 1000 słów — wersja skrócona dla zespołów
• 155 słów — quick reference dla agentów

Praktyka: jeśli generujesz teksty z LLM, użyj WRITING.md. Agenci czytają go, rozumieją regułę "konkret nad opinią", generują lepszy tekst. To działa — testowaliśmy w kilku projektach.

Ograniczenie: WRITING.md działa dla tekstu, ale nie dla kodu. Dla kodu potrzebujesz AGENTS.md. To dwa różne standardy dla dwóch różnych problemów.

Checklist: co wpisać do AGENTS.md w ciągu 2 godzin

Nie musisz pisać 10 stron. Wystarczy 1–2 strony, konkretnie.

Sekcja 1: Architektura (5 minut)

Napisz, jak wygląda Twój projekt. Które pliki są krytyczne? Jaka jest struktura folderów? Które moduły komunikują się ze sobą?

Sekcja 2: Konwencje kodu (10 minut)

Jak piszecie kod? Jakie są reguły nazewnictwa? Jakie frameworki używacie? Jaki styl formatowania?

Sekcja 3: Komendy build i test (5 minut)

Jak się buduje projekt? Jak się uruchamiają testy? Jakie są kroki do deployment'u?

Sekcja 4: Ograniczenia i zakazane operacje (10 minut)

Które pliki agent nie powinien zmieniać? Które API są zagrożone? Jakie są reguły bezpieczeństwa?

Sekcja 5: Reguły PR (5 minut)

Jakie są wymagania dla pull requestu? Kto musi zaaprobować? Jakie testy muszą przejść?

Razem: 35 minut pisania + 25 minut na formatowanie i testowanie = 1 godzina. Możesz to zrobić w poniedziałek rano.

Gdzie znaleźć gotowe szablony i przykłady

Nie musisz pisać od zera. Istnieją gotowe szablony.

The AGENTS.md Field Guide (2026 edition) zawiera przykłady dla różnych typów projektów — od aplikacji webowych po biblioteki [1]. Morfllm.com ma guide z praktycznymi wskazówkami [2]. Reddit community dzieli się szablonami — szukaj "AGENTS.md template" [7].

Praktyka: weź szablon, dostosuj do swojego projektu, wrzuć do repozytorium. To zajmie 1–2 godziny.

Werdykt: to już nie opcja, to baseline

AGENTS.md to nie trend. To infrastruktura. 60 000 repozytoriów GitHub to już używa [1]. 13+ narzędzi kodujących to wspiera [1]. Linux Foundation to stewarduje [1].

Jeśli Twój projekt ma agentów kodujących — Copilota, Claude Code, Cursor — AGENTS.md powinien być w repozytorium. Nie "warto mieć", ale "powinien być".

Dlaczego? Ponieważ bez niego agent robi chaos. Z nim — agent robi to, co prosisz. To różnica między 2 godzinami debugowania a 20 minutami pracy.

Next step na poniedziałek rano:

1. Otwórz repozytorium swojego projektu.
2. Utwórz plik AGENTS.md w głównym folderze.
3. Wpisz pięć sekcji z checklisty powyżej — zajmie to 1 godzinę.
4. Jeśli używasz Claude Code — utwórz CLAUDE.md z importem @AGENTS.md.
5. Uruchom sesję w swoim ulubionym narzędziu, poproś agenta o zmianę — powinien przeczytać AGENTS.md.

To wszystko. Reszta działa sama.

Źródła

[1] The AGENTS.md Field Guide, 2026 edition - Iurii Okhmat — https://www.iuriio.com/blog/posts/2026/05/agents-md-field-guide-2026

[2] AGENTS.md Spec (2026) - MorphLLM — https://www.morphllm.com/agents-md-guide

[3] SKILL.md vs CLAUDE.md vs AGENTS.md Compared — https://www.termdock.com/blog/skill-md-vs-claude-md-vs-agents-md

[4] What Goes in AGENTS.md (and What Doesn't) — https://ro14nd.de/what-goes-in-agents-md/

[5] CLAUDE.md vs AGENTS.md vs SKILL.md (2026) — https://pub.towardsai.net/claude-md-vs-agents-md-vs-skill-md-which-file-owns-what-in-2026-13859378f56a

[6] How to Build Your AGENTS.md (2026): The Context File ... — https://www.augmentcode.com/guides/how-to-build-agents-md

[7] Released my global AGENTS.md / CLAUDE.md for more reliable coding agent work, and WRITING.md rules for cleaner AI text — https://www.reddit.com/r/PromptEngineering/comments/1sxzbux/released_my_global_agentsmd_claudemd_for_more/