# AGENTS.md czy CLAUDE.md? Co czyta Claude Code od wersji 2.1.277

> Od wersji 2.1.277 z 18 września 2026 roku Claude Code czyta AGENTS.md, ale tylko wtedy, gdy w katalogu roboczym ani wyżej nie ma CLAUDE.md; przy obu plikach wygrywa CLAUDE.md, chyba że w /config wybierze się odczyt obu. Sprawdziłem to 22 września 2026 roku w 33 przebiegach z wyłączonymi narzędziami: wersja 2.1.278 wczytała instrukcje z AGENTS.md w 9 z 10 przebiegów w katalogu z samym tym plikiem, wersja 2.1.272 w 0 z 10, a przy obu plikach obie wersje podały wyłącznie treść CLAUDE.md w 8 z 8 przebiegów. Funkcja działa jako wbudowana wtyczka. Według dokumentacji z 24 września 2026 roku do wersji 2.1.280 nie działała na platformie Bedrock ani przy wyłączonej telemetrii, a od wersji 2.1.281 z 23 września to ograniczenie zniknęło, choć wpis 2.1.277 w dzienniku zmian nadal wymienia Bedrock, Vertex i Foundry. Czasem nie działa też w pierwszej sesji po aktualizacji z wersji 2.1.276 lub starszej; na starszych wersjach i w takiej sesji zostaje import @AGENTS.md w CLAUDE.md. AGENTS.md jest formatem otwartym pod Linux Foundation, czytanym bez konfiguracji przez Codex, Cursor, Copilota, Jules, Amp, Factory, Devina, Windsurf, Zed, Warp i Junie, a przez Gemini CLI i Aidera tylko po ustawieniu.

Autor: Robert Marczyński · Opublikowano: 2026-09-24 · Aktualizacja: 2026-09-24
Kanoniczny URL: https://ekspertodsztucznejinteligencji.pl/odpowiedzi/agents-md-czy-claude-md

Krótka odpowiedź: od wersji 2.1.277 z 18 września 2026 roku Claude Code czyta AGENTS.md, ale tylko wtedy, gdy w projekcie nie ma CLAUDE.md. Sprawdziłem to 22 września w 33 przebiegach: wersja 2.1.278 wczytała instrukcje z AGENTS.md w 9 z 10 prób, wersja 2.1.272 w żadnej z 10, a gdy w katalogu leżały oba pliki, obie wersje w 8 z 8 przebiegów podały wyłącznie treść CLAUDE.md. Jeżeli firma używa kilku agentów kodujących, jeden AGENTS.md wystarczy, z zastrzeżeniem dla kanału stable (24 września 2026 roku jest na nim wersja 2.1.273, jeszcze bez tej funkcji), dla wersji starszych niż 2.1.281 na platformie Bedrock i przy wyłączonej telemetrii oraz dla pierwszej sesji po aktualizacji z wersji 2.1.276 lub starszej.

## Co zmieniło się 18 września 2026

Wpis w dzienniku zmian jest jednozdaniowy: dodano obsługę AGENTS.md, w projekcie bez CLAUDE.md Claude Code czyta zamiast niego AGENTS.md, a zmienić to można w /config pod „Project instructions”; na razie nie działa to na platformach Bedrock, Vertex ani Foundry. Wersja 2.1.277 trafiła do rejestru npm 18 września 2026 roku, a 2.1.278, na której robiłem test, dzień później.

Dokumentacja opisuje szczegóły, których wpis nie ma. Domyślnie Claude czyta AGENTS.md tylko wtedy, gdy nie ma CLAUDE.md w katalogu roboczym ani powyżej. Odczyt blokują też .claude/CLAUDE.md i osobisty CLAUDE.local.md; plik ~/.claude/CLAUDE.md, plik zarządzany przez administratora i reguły z .claude/rules go nie blokują. Kto chce zachować CLAUDE.local.md, musi w /config wybrać odczyt obu plików. Ustawienie „Project instructions” przyjmuje cztery wartości: CLAUDE.md albo AGENTS.md (domyślna), oba pliki z CLAUDE.md czytanym w każdym katalogu jako pierwszy, sam CLAUDE.md oraz wyłącznie pliki zarządzane przez administratora. Claude nie czyta AGENTS.local.md, AGENTS.override.md ani niczego z katalogu .agents. Funkcja jest wbudowaną wtyczką. Do wersji 2.1.280 nie działała w części sesji, na przykład na platformie Bedrock i przy wyłączonej telemetrii; dokumentacja z 24 września 2026 roku podaje, że wersja 2.1.281 z 23 września to zmieniła, choć wpisu 2.1.277 w dzienniku zmian nie poprawiono. Czasem funkcja nie działa też w pierwszej sesji po aktualizacji z wersji 2.1.276 lub starszej. W wersjach starszych niż 2.1.280 AGENTS.md wczytany tą drogą nie pojawiał się w /memory ani w /context; od wersji 2.1.280 z 22 września 2026 roku jego ścieżka jest na liście w /memory.

## Jak to sprawdziłem: 33 przebiegi na dwóch wersjach

Zainstalowałem wersję 2.1.278 osobno przez npm w katalogu testowym, obok mojej instalacji 2.1.272, i przygotowałem trzy katalogi: z samym AGENTS.md (instrukcja: zaczynaj każdą odpowiedź od słowa MALINA), z AGENTS.md i CLAUDE.md o innej instrukcji (JAGODA) oraz pusty. Każdą wersję uruchamiałem w trybie jednorazowego polecenia na modelu Haiku 4.5, z wyłączonymi wszystkimi narzędziami, i wysyłałem dwa polecenia: prośbę o zacytowanie instrukcji projektu oraz pytanie kontrolne o stolicę Polski, które sprawdza, czy instrukcja działa bez pytania o nią.

| Katalog | Wersja | Przebiegi | Instrukcja z AGENTS.md w odpowiedzi |
|---|---|---|---|
| sam AGENTS.md | 2.1.278 | 10 | 9 |
| sam AGENTS.md | 2.1.272 | 10 | 0 |
| AGENTS.md i CLAUDE.md | 2.1.278 | 5 | 0, w każdym tylko CLAUDE.md |
| AGENTS.md i CLAUDE.md | 2.1.272 | 3 | 0, w każdym tylko CLAUDE.md |
| pusty | obie | 5 | brak plików, 5 odpowiedzi „BRAK” |

Jedyny nieudany przebieg na nowej wersji był pierwszym w serii. Nie była to pierwsza sesja tej wersji: wcześniej uruchomiłem ją 15 razy w odrzuconej serii z narzędziami, opisanej niżej, w której pierwszy przebieg też zwrócił BRAK. Przyczyny nie ustaliłem, więc zostawiam to jako obserwację. Dziennik wszystkich przebiegów, skrypt i opis metody są w [zbiorze danych](/badania/agents-md-2026-09/README.md).

Jedną rzecz zrobiłem najpierw źle. W pierwszej serii zostawiłem narzędzia włączone i zapytałem o instrukcje z plików w katalogu roboczym; stara wersja też wtedy „cytowała” AGENTS.md, bo model po prostu otworzył plik narzędziem Read. Ten dziennik zostawiłem w zbiorze jako odrzucony. Test, który ma sprawdzić, co harness wstrzykuje do kontekstu, musi odebrać modelowi możliwość dojścia do pliku samemu.

## Dlaczego trwało to trzynaście miesięcy

Powodu Anthropic nie podał ani w wątku zgłoszenia, ani w dzienniku zmian. Prośba o AGENTS.md ma numer 6235 i datę 21 sierpnia 2025 roku; autor pisał, że Codex, Amp i Cursor zaczynają przyjmować ten plik jako wspólny standard, a CLAUDE.md jest zbyt specyficzny dla jednego narzędzia. Do 22 września 2026 roku wątek zebrał 6673 reakcje i 407 komentarzy. Jedyny komentarz opiekuna repozytorium padł 17 sierpnia 2026 roku przy zamknięciu wątku jako „completed”: Claude Code czyta CLAUDE.md, a plik można współdzielić przez CLAUDE.md z samą linią @AGENTS.md albo przez dowiązanie symboliczne. Dokumentacja jeszcze 21 sierpnia 2026 roku mówiła wprost, że Claude Code czyta CLAUDE.md, nie AGENTS.md. Natywna obsługa przyszła miesiąc później, jako wtyczka.

Import i dowiązanie nadal działają i w kilku sytuacjach są jedyną drogą. CLAUDE.md może importować pliki składnią @ścieżka do czterech poziomów zagnieżdżenia, więc jedna linia @AGENTS.md wystarczy. Dowiązanie ma dwie wady opisane w dokumentacji: narzędzia Edit i Write odmawiają zapisu przez dowiązanie, a w systemie Windows jego utworzenie wymaga uprawnień administratora albo trybu deweloperskiego.

## Kto czyta AGENTS.md bez konfiguracji

AGENTS.md wyszedł z OpenAI w sierpniu 2025 roku, a 9 grudnia 2025 trafił razem z MCP od Anthropic i goose od firmy Block do nowo powołanej Agentic AI Foundation pod Linux Foundation. Format nie ma wymaganych pól; to zwykły Markdown, a przy konflikcie wygrywa plik najbliższy edytowanemu plikowi. Codex czyta pliki od katalogu głównego w dół i skleja je, przy czym honoruje AGENTS.override.md i domyślnie ogranicza łączny rozmiar do 32 KiB. Cursor czyta AGENTS.md w katalogu głównym i podkatalogach. Copilot w chmurze i w wierszu poleceń czyta AGENTS.md, CLAUDE.md i GEMINI.md; według macierzy GitHub Docs przegląd kodu Copilota i czat Copilota w VS Code czytają tylko AGENTS.md, choć dokumentacja samego VS Code opisuje automatyczne wykrywanie CLAUDE.md z osobnym przełącznikiem, więc oba źródła z 22 września 2026 roku się tu rozjeżdżają. Jules szuka AGENTS.md w katalogu głównym, Amp bierze pliki z katalogu roboczego i nadrzędnych, a gdy ich nie ma, sięga po AGENT.md albo CLAUDE.md. Factory czyta AGENTS.md i zgodne nazwy, w tym CLAUDE.md. Devin, Windsurf i Junie czytają AGENTS.md z katalogu głównego.

Dwa narzędzia z logo na stronie formatu czytają go tylko po ustawieniu: Gemini CLI domyślnie szuka GEMINI.md, a inne nazwy przyjmuje przez context.fileName; Aider w dokumentacji zaleca CONVENTIONS.md dodawany poleceniem read i o AGENTS.md nie wspomina. Dwa inne mają własną kolejność: Zed sprawdza najpierw .rules i .cursorrules, a AGENTS.md dopiero po nich, Warp daje pierwszeństwo WARP.md.

## Który plik wybrać w firmie

Jeden AGENTS.md jako źródło i CLAUDE.md tylko tam, gdzie jest potrzebny. Jeżeli zespół używa Codeksa, Cursora albo Copilota obok Claude Code, instrukcje w AGENTS.md dotrą do Codeksa, Cursora i Copilota, a do Claude Code w wersji 2.1.277 lub nowszej bez dodatkowego pliku. Polecenia instalacji z dokumentacji dla Homebrew i repozytoriów pakietów Linuksa ustawiają kanał stable, na którym 24 września 2026 roku jest jeszcze wersja 2.1.273; kto z niego korzysta, potrzebuje CLAUDE.md z linią @AGENTS.md, dopóki kanał nie dojdzie do 2.1.277. Jeżeli ktoś w zespole pracuje przez Bedrock, Vertex, Foundry albo z wyłączoną telemetrią na wersji starszej niż 2.1.281, w jego repozytorium powinien leżeć CLAUDE.md z linią @AGENTS.md; nie zaszkodzi też pozostałym, bo przy obu plikach Claude i tak czyta CLAUDE.md, a przez import dostanie tę samą treść. Taki jednolinijkowy CLAUDE.md zabezpiecza też pierwszą sesję po aktualizacji z wersji 2.1.276 lub starszej, bo według dokumentacji w tej sesji odczyt AGENTS.md czasem zawodzi.

Trzy różnice trzeba mieć w głowie przy pisaniu. Codex honoruje AGENTS.override.md, Claude Code go ignoruje, więc lokalne nadpisania dla jednego narzędzia nie przeniosą się na drugie. Codex przestaje dołączać kolejne pliki, gdy łączna treść osiągnie domyślne 32 KiB, więc przy długich instrukcjach część z podkatalogów nie trafi do modelu; dokumentacja radzi podnieść limit albo podzielić instrukcje. AGENTS.md wczytany przez Claude Code bez importu nie uruchamia hooków InstructionsLoaded, więc skrypty podpięte pod wczytanie instrukcji go nie zobaczą; w wersjach starszych niż 2.1.280 nie było go też w /memory.

Skala jest wyrównana. Wyszukiwanie kodu na GitHubie z 22 września 2026 roku zwróciło około 505 tysięcy repozytoriów z AGENTS.md w katalogu głównym i około 523 tysięcy z CLAUDE.md, z forkami i tylko dla repozytoriów aktywnych w ostatnim roku, więc to rząd wielkości. Liczba „ponad 60 tysięcy projektów” ze strony formatu pochodzi z grudnia 2025 roku. Czy plik instrukcji w ogóle pomaga, badania mierzą różnie: zespół z ETH Zurich napisał w lutym 2026 roku, że pliki kontekstu na ogół nie zwiększają odsetka rozwiązanych zadań, a podnoszą koszt wnioskowania średnio o ponad 20%. Badanie Lulli i współautorów ze stycznia 2026 roku (wersja poprawiona 30 marca 2026) na 10 repozytoriach i 124 pull requestach wiąże z kolei obecność AGENTS.md z niższą o 28,64% medianą czasu i mniejszym o 16,58% zużyciem tokenów wyjściowych. [Jak sam prowadzę pracę z agentem w pętli](/blog/loop-development-programowanie-w-petli-z-ai), opisałem osobno; plik instrukcji jest w niej narzędziem, nie gwarancją.

## Najczęstsze pytania

**Czy Claude Code czyta AGENTS.md?**

Tak, od wersji 2.1.277 wydanej 18 września 2026 roku, ale domyślnie tylko wtedy, gdy w katalogu roboczym ani w katalogach nadrzędnych nie ma CLAUDE.md ani CLAUDE.local.md. W moim teście z 22 września 2026 wersja 2.1.278 wczytała instrukcje z AGENTS.md w 9 z 10 przebiegów, a wersja 2.1.272 w żadnym z 10. Dokumentacja zastrzega, że w wersjach starszych niż 2.1.281 funkcja nie działała na platformie Amazon Bedrock ani przy wyłączonej telemetrii, a czasem nie działa w pierwszej sesji po aktualizacji z wersji 2.1.276 lub starszej.

**Co się dzieje, gdy w projekcie są oba pliki, AGENTS.md i CLAUDE.md?**

Domyślnie Claude Code czyta tylko CLAUDE.md. W moim teście z 22 września 2026 obie wersje, 2.1.272 i 2.1.278, w katalogu z oboma plikami podały wyłącznie instrukcję z CLAUDE.md w 8 z 8 przebiegów. Ustawienie Project instructions w /config ma cztery wartości: domyślną CLAUDE.md albo AGENTS.md, oba pliki z CLAUDE.md czytanym jako pierwszy, sam CLAUDE.md oraz tylko pliki zarządzane przez administratora.

**Czym różni się AGENTS.md od CLAUDE.md?**

Zawartością niczym: oba to zwykły Markdown bez wymaganych pól. AGENTS.md jest formatem otwartym, od grudnia 2025 roku pod Agentic AI Foundation w Linux Foundation, czytanym przez Codex, Cursor, Copilota, Jules, Amp, Factory, Devina, Windsurf, Zed, Warp i Junie. CLAUDE.md jest plikiem Claude Code z hierarchią od pliku zarządzanego przez administratora, przez katalog użytkownika, po projekt i plik lokalny, z importami @ścieżka do czterech poziomów. W wersjach starszych niż 2.1.280 AGENTS.md czytany przez Claude Code nie pokazywał się w /memory ani w /context; od wersji 2.1.280 jego ścieżka jest na liście w /memory.

**Jak używać jednego pliku instrukcji dla wszystkich agentów?**

Trzymać instrukcje w AGENTS.md i nie tworzyć ani CLAUDE.md, ani CLAUDE.local.md, wtedy Claude Code od wersji 2.1.277 przeczyta AGENTS.md sam. Tam, gdzie funkcja nie działa, na przykład na kanale stable (24 września 2026 roku wersja 2.1.273), w wersjach starszych niż 2.1.281 na platformie Bedrock albo przy wyłączonej telemetrii, a czasem w pierwszej sesji po aktualizacji z wersji 2.1.276 lub starszej, wystarczy CLAUDE.md z jedną linią @AGENTS.md. Dowiązanie symboliczne też działa, ale narzędzia Edit i Write w Claude Code odmawiają zapisu przez dowiązanie, a w systemie Windows wymaga ono uprawnień administratora albo trybu deweloperskiego.

**Ile projektów używa AGENTS.md, a ile CLAUDE.md?**

Wyszukiwanie kodu na GitHubie z 22 września 2026 roku pokazało około 505 tysięcy repozytoriów z AGENTS.md w katalogu głównym i około 523 tysięcy z CLAUDE.md, z forkami i tylko wśród repozytoriów aktywnych w ostatnim roku, więc to rząd wielkości, nie pomiar. Liczba „ponad 60 tysięcy projektów” ze strony agents.md pochodzi z grudnia 2025 roku i nie była od tego czasu aktualizowana.


## Źródła

- Anthropic — dziennik zmian Claude Code (wpis 2.1.277: odczyt AGENTS.md w projekcie bez CLAUDE.md, ustawienie Project instructions w /config, brak na platformach Bedrock, Vertex i Foundry): https://raw.githubusercontent.com/anthropics/claude-code/refs/heads/main/CHANGELOG.md
- GitHub — wydanie Claude Code v2.1.277 (18.09.2026): https://github.com/anthropics/claude-code/releases/tag/v2.1.277
- Claude Code — dokumentacja pamięci i plików instrukcji: sekcja AGENTS.md, wartości ustawienia Project instructions, sytuacje, w których odczyt nie działa, różnice wobec CLAUDE.md, zmiany w wersjach 2.1.280 i 2.1.281, hierarchia CLAUDE.md i importy (odczyt 22.09.2026 i 24.09.2026): https://code.claude.com/docs/en/memory
- Claude Code — instalacja i kanały aktualizacji latest i stable (odczyt 24.09.2026): https://code.claude.com/docs/en/setup
- npm — rejestr pakietu @anthropic-ai/claude-code: dist-tag stable 2.1.273, latest 2.1.281 (odczyt 24.09.2026): https://registry.npmjs.org/@anthropic-ai/claude-code
- GitHub — wydanie Claude Code v2.1.280 (22.09.2026): https://github.com/anthropics/claude-code/releases/tag/v2.1.280
- GitHub — wydanie Claude Code v2.1.281 (23.09.2026): https://github.com/anthropics/claude-code/releases/tag/v2.1.281
- Wayback Machine — ta sama strona dokumentacji z 21.08.2026: „Claude Code reads CLAUDE.md, not AGENTS.md”, zalecany import @AGENTS.md albo dowiązanie: https://web.archive.org/web/20260821052423/https://code.claude.com/docs/en/memory
- GitHub — anthropics/claude-code, issue #6235 „Feature Request: Support AGENTS.md” (otwarte 21.08.2025, 6673 reakcje do 22.09.2026, zamknięte 17.08.2026 z obejściem przez import): https://github.com/anthropics/claude-code/issues/6235
- GitHub — anthropics/claude-code, wtyczka wbudowana agents-md (README: AGENTS.md czytany jak CLAUDE.md, opcja instructionFiles): https://github.com/anthropics/claude-code/blob/main/mods/agents-md/README.md
- Test własny — dziennik 33 przebiegów z 22.09.2026 na wersjach 2.1.278 i 2.1.272 z wyłączonymi narzędziami, skrypt i opis metody: https://ekspertodsztucznejinteligencji.pl/badania/agents-md-2026-09/README.md
- agents.md — strona formatu: brak wymaganych pól, pierwszeństwo najbliższego pliku, lista narzędzi, zarządzanie przez Agentic AI Foundation (odczyt 22.09.2026): https://agents.md
- Linux Foundation (9.12.2025) — powołanie Agentic AI Foundation z MCP, goose i AGENTS.md; „ponad 60 tysięcy projektów” jako stan z grudnia 2025: https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation
- OpenAI Codex — dokumentacja AGENTS.md: odczyt od katalogu głównego w dół, AGENTS.override.md, limit 32 KiB: https://learn.chatgpt.com/docs/agent-configuration/agents-md
- Cursor — Rules: AGENTS.md w katalogu głównym i podkatalogach: https://cursor.com/docs/context/rules
- GitHub Docs — Adding repository custom instructions: AGENTS.md w dowolnym miejscu repozytorium, alternatywnie CLAUDE.md albo GEMINI.md w katalogu głównym: https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions
- GitHub Docs — macierz obsługi plików instrukcji w produktach Copilot: https://docs.github.com/en/copilot/reference/custom-instructions-support
- VS Code — Custom instructions: automatyczne wykrywanie AGENTS.md i CLAUDE.md, ustawienia chat.useAgentsMdFile i chat.useClaudeMdFile: https://code.visualstudio.com/docs/copilot/customization/custom-instructions
- Google Gemini CLI — dokumentacja plików kontekstu: GEMINI.md domyślnie, inne nazwy przez context.fileName: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md
- Google Jules — dokumentacja: automatyczny odczyt AGENTS.md z katalogu głównego: https://jules.google/docs
- Amp — AGENTS.md: pliki z katalogu roboczego i nadrzędnych; zastępczo AGENT.md albo CLAUDE.md: https://ampcode.com/docs/customize/agents-md
- Factory — AGENTS.md i zgodne nazwy plików, w tym CLAUDE.md: https://docs.factory.ai/cli/configuration/agents-md
- Devin — obsługa AGENTS.md: https://docs.devin.ai/onboard-devin/agents-md
- Windsurf (Cognition) — Memories and rules: AGENTS.md w katalogu głównym jako reguły zawsze włączone: https://docs.devin.ai/desktop/cascade/memories
- Zed — Instructions: AGENTS.md jako plik główny; kolejność wyszukiwania z .rules i .cursorrules przed AGENTS.md: https://github.com/zed-industries/zed/blob/main/docs/src/ai/instructions.md
- Warp — Rules: AGENTS.md albo WARP.md, z pierwszeństwem WARP.md: https://docs.warp.dev/knowledge-and-collaboration/rules
- Aider — Specifying coding conventions: plik CONVENTIONS.md dodawany przez read: https://aider.chat/docs/usage/conventions.html
- JetBrains Junie — Guidelines and memory: kolejność odczytu .junie/AGENTS.md, AGENTS.md, .junie/guidelines.md: https://junie.jetbrains.com/docs/guidelines-and-memory.html
- arXiv 2602.11988 (Gloaguen, Mündler, Müller, Raychev, Vechev, 12.02.2026) — pliki kontekstu na ogół nie zwiększają odsetka rozwiązanych zadań, a podnoszą koszt wnioskowania średnio o ponad 20%: https://arxiv.org/abs/2602.11988
- arXiv 2601.20404 (Lulla i in., 28.01.2026, v2 30.03.2026) — 10 repozytoriów, 124 pull requesty: obecność AGENTS.md wiąże się z niższą medianą czasu o 28,64% i mniejszym zużyciem tokenów wyjściowych o 16,58%: https://arxiv.org/abs/2601.20404