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

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ą.

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.

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, opisałem osobno; plik instrukcji jest w niej narzędziem, nie gwarancją.