AGENTS.md czy CLAUDE.md? Co tak naprawdę zawierają te 592 najpopularniejsze repozytoria?

Przewodnik SDLC opracowany przez Anthropic, oparty na sztucznej inteligencji, przearanżowuje wszystkie sześć etapów dostarczania oprogramowania wokół agentów kodujących. W trzecim etapie wymagany jest jeden konkretny plik: CLAUDE.md – plik z wiedzą na poziomie repozytorium, który jest aktualizowany za każdym razem, gdy agent powtarza ten sam błąd. Badanie najpopularniejszych publicznych repozytoriów pokazało, w jakim stopniu te zalecenia znajdują zastosowanie w praktyce, a odpowiedź jest zaskakująca. CLAUDE.md przewyższa je pod względem liczby plików, ale ustępuje im pod względem treści.

Główne liczby

8 września 2026 roku badanie objęło 592 najpopularniejsze repozytoria wybrane z sześciu rankingów języków (TypeScript, Python, Go, Rust, Java i JavaScript, po usunięciu duplikatów). Szukano w nich pliku CLAUDE.md oraz kilku powiązanych z nim plików.

• 165 repozytoriów (27,9%) zawiera plik CLAUDE.md.
• 94 z tych 165 (57,0%) w ogóle nie zawiera żadnej wiedzy o repozytorium – są to jedynie przekierowania.

Ze 165 takich repozytoriów 94 (57,0%) nie posiada żadnej wiedzy na temat repozytoriów. Są to przekierowania.

209 repozytoriów, czyli 35,3%, zawiera plik AGENTS.md, a 93,8% z nich ma w nim rzeczywisty treść.

W tych, gdzie oba pliki istnieją (132 repozytoria), 89 wskazuje CLAUDE.md na AGENTS.md. Tylko 10 wskazuje w przeciwnym kierunku.

Liczba repozytoriów z plikiem .claude/settings.json, w którym konfigurowane są haki z etapu 3 playbooka, wynosi zaledwie 5,9%.

Pliki CLAUDE.md o rzeczywistej treści mają średnią wielkość 3 934 bajtów, a największy z nich osiąga 66 176 bajtów.

Jeśli pominąć przekierowania, tylko 12,0% najważniejszych repozytoriów ma plik CLAUDE.md z jakąkolwiek treścią. Plik AGENTS.md o rzeczywistej treści występuje w 33,1% z nich.

Dla tych, którzy teraz przyjmują ten playbook, wnioski są mieszane. Agenci rzeczywiście potrzebują spójnego pliku wiedzy kontrolowanego wersją, jednak playbook wskazuje niewłaściwy plik. W tych repozytoriach CLAUDE.md stał się narzędziem kompatybilności umieszczonym przed AGENTS.md – plikiem neutralnym pod względem dostawcy, który jest czytany przez wszystkie główne agenty programistyczne. Projekty, które już rozwiązały ten problem, zapisały swoją wiedzę raz w AGENTS.md i zostawiły jednoliniowy wskaźnik.

Sposób liczenia

Frame próbkowania stanowił snapshot rankingu publicznego na GitHubie – pierwsze 100 repozytoriów według liczby gwiazdek w każdym z sześciu języków, które po usunięciu duplikatów dały 592 unikalne repozytoria. Z serwera raw.githubusercontent.com pobrano ustalony zestaw ścieżek w punkcie HEAD, bez klucza API, bez autoryzacji i bez żadnego scrapingu. Pytanie dotyczyło jedynie tego, czy plik istnieje i co w nim jest napisane. Następnie ręcznie pobraano całą treść plików CLAUDE.md i AGENTS.md – 374 pliki z 242 repozytoriów.

To właśnie podczas czytania okazało się, że informacje są niepełne. Mediana długości plików CLAUDE.md wynosiła dwa linie, więc sam ten wskaźnik sam w sobie prawie nic nie mówi.

Co zawierają te pliki

Żaden z tych typowych formatów nie stanowi prawdziwej wiedzy:

• Symlink w Git. Plik ma dziewięć bajtów – to tylko tekst AGENTS.md bez znaku nowej linii na końcu, ponieważ Git przechowuje symlink jako blok zawierający jego cel. Przykładami są openclaw, dify, ant-design, moby, home-assistant, superset, Stirling-PDF i nushell.
• Jedna linia importu, @AGENTS.md, o długości jedenastu bajtów; Claude Code rozwiązuje ją podczas ładowania. Tak działa również n8n, supabase, grafana, nuxt, storybook, prometheus, traefik, ruff i pdf.js.
• Jedno zdanie prozy. W lazygit stanowi ono instrukcję, by najpierw przeczytać AGENTS.md i postępować zgodnie z jego treścią. CLI Google Workspace mówi to samo, ale w dłuższej formie.

Kilka szczególnych przypadków ma znaczenie dla każdego, kto buduje klasyfikator. Docusaurus zawiera nagłówek, a po nim import – nic więcej. Jest natomiast odwołuje się do pliku .github/copilot-instructions.md. Ansible składa się z trzech linii importu bez żadnego tekstu opisowego. Zed odwołuje się za pomocą symlinków do pliku o nazwie .rules.

Po wykluczeniu wszystkich plików, których jedyną zawartością jest przekierowanie, w 71 z 592 repozytoriów znajduje się plik CLAUDE.md zawierający informacje o tym repozytorium, co stanowi 12,0%. Te 71 plików jest rzeczywistych, a niektóre z nich są dość duże: mediana wynosi 3 934 bajty, 90. percentyl 19 506 bajtów, a maksimum 66 176 bajtów. Projekty takie jak bun, pytorch, swc, gstack i 3x-ui utrzymują rzeczywiste przewodniki operacyjne obejmujące polecenia budowania, mapy repozytoriów, filozofię testowania oraz zasady dotyczące struktury katalogów.

Gdzie faktycznie znajdują się te informacje

W pliku AGENTS.md, i to z dużą przewagą. Jego rzeczywisty wskaźnik wynosi 93,8%, czyli 196 z 209 plików, w porównaniu z 43,0% dla CLAUDE.md. To właśnie ta asymetria jest kluczowa. Repozytorium, które tworzy plik AGENTS.md, niemal zawsze wypełnia go treścią. Repozytorium, które tworzy plik CLAUDE.md, najczęściej stanowi jedynie most do innego miejsca.

132 repozytoria, które zawierają oba pliki, jasno wskazują tę zależność:

• W 89 z nich CLAUDE.md pełni rolę wskaźnika, a AGENTS.md zawiera treść.
• W 10 przypadkach role są odwrotne: AGENTS.md kieruje do innego pliku, a CLAUDE.md jest prawdziwym plikiem. Do nich należą Pytorch, bun, milvus, anki i litellm.
• 31 repozytoriów przechowuje treść w obu plikach, co oznacza, że ta sama wiedza instytucjonalna jest utrzymywana dwa razy.
• 2 repozytoria zawierają wskaźniki w obu plikach, co sugeruje istnienie trzeciego pliku gdzieś indziej.

Przekierowania kierują się więc w przybliżeniu w stosunku dziewięć do jednego w stronę pliku neutralnego pod względem dostawcy. Taki jednokierunkowy wynik jest często efektem błędu pomiarowego, dlatego celowo poszukiwano przeciwnego przypadku. Istnieje on, ale tylko w niewielkim stopniu.

Adopcja według języka

Różnica pomiędzy poszczególnymi językami jest na tyle duża, że można na niej oprzeć planowanie. Najpierw CLAUDE.md, potem AGENTS.md:

• TypeScript: 46,5% i 53,5%
• Rust: 33,3% i 43,4%
• Go: 32,3% i 37,4%
• Python: 25,5% i 31,6%
• JavaScript: 19,0% i 23,0%
• Java: 10,3% i 22,7%

AGENTS.md dominuje we wszystkich językach. Największa luka występuje w przypadku Javy – repozytorium z AGENTS.md ma ponad dwukrotnie większe szanse istnienia niż takie z CLAUDE.md, natomiast projekty typu TypeScript mają ponad czterokrotnie większe szanse na posiadanie CLAUDE.md w porównaniu z projektami Javy. We wszystkich sześciu językach 43,2% czołowych repozytoriów zawiera jakiś plik z instrukcjami dla agenta, czy to AGENTS.md, CLAUDE.md, .cursorrules, czy plik z instrukcjami Copilota. Plik Copilota występuje w 9,3% przypadków. Konwencja .cursorrules niemal zniknęła w tej grupie, występując jedynie w 0,5%, co jest dobrym przypomnieniem o tym, jak szybko może zaniknąć nawyk specyficzny dla danego dostawcy.

Pozostałe elementy stacku Stage-3

Zespoły pracujące nad platformami powinny uważnie przeczytać tę część. Plan działania wymaga czegoś więcej niż tylko pliku z wiedzą – łączy on pliki z wiedzą, umiejętności oraz hooki, a hooki stanowią warstwę kontrolną, która zapobiega niebezpiecznym działaniom podczas budowania.

Tylko 35 z 592 repozytoriów (5,9%) posiada plik .claude/settings.json, a tylko 32 z nich (5,4%) ma go razem z plikiem CLAUDE.md. To właśnie dokumentacja, będąca zwykłym plikiem, który może napisać każdy, została przyjęta przez użytkowników. Warstwa kontrolna, która faktycznie określa, co agent może robić, występuje jedynie w mniej niż jednym repozytorium na osiemnaście. Scenariusz działania, którego bezpieczeństwo zależy od mechanizmów typu hooks, opisuje coś, czego prawie nikt jeszcze nie stworzył.

Ograniczenia danych

• Przykład obejmuje publiczne repozytoria posortowane według liczby gwiazdek. Takie scenariusze działania są używane w prywatnych repozytoriach firm, które nie są dostępne publicznie; ich przyjęcie może być tam wyższe i bardziej uporządkowane.
• Jest to pojedynczy zrzut stanu, wykonany w punkcie HEAD 8 września 2026 roku. Przyjęcie nowych rozwiązań następuje szybko, więc już po miesiącu procenty będą błędne, a kierunek rozwoju jest ważniejszy niż jego poziom.

Plik nie jest dowodem na praktykę. Istnienie pliku CLAUDE.md samo w sobie pokazuje jedynie, że ktoś go napisał. Nie dostarcza on żadnych dowodów na to, że ktoś go aktualizuje lub że jakość wyjść agenta się poprawiła. Publikowane prace kwestionują, czy takie pliki w ogóle pomagają agentom do programowania, a ta miara nic na ten temat nie mówi.

Plik settings.json jest jedynie zamiennikiem dla hooków, a nie pełnym spisem. Wszystkie hooki zdefiniowane w innych miejscach pozostają niewidoczne, dlatego 5,9% to wartość minimalna.

Rozstrzygnięcie co do granicy pomiędzy wskaźnikami a treścią merytoryczną jest subiektywne. Ostateczna długość tekstu wyniosła 120 znaków pozostałej prozy po usunięciu nagłówków, elementów importowych oraz zdań kierujących do innych plików. Czternaście plików najbliższych tej granicy zostało sprawdzonych ręcznie, a najbliższy plik merytoryczny, lazydocker, zawiera 172 znaki rzeczywistych flag budowania. Zmiana progu powoduje zmianę tej liczby. Druga weryfikacja 25 repozytoriów na podstawie plików aktualnych wykazała, że błędy występują tylko w jednym kierunku: klasyfikator czasami traktuje zdanie kierujące jako treść merytoryczną, gdy jest ono sformułowane jako instrukcja dla agenta, a nie stwierdzenie dotyczące lokalizacji dokumentacji, jak w przypadku pliku zeroclaw. Dlatego 57,0% to minimalna wartość, a rzeczywisty udział wskaźników jest nieco wyższy.

Był też jeden incydent, który warto przyznać. Pierwsza analiza wskazywała, że 27,9% czołowych repozytoriów przyjęło CLAUDE.md, i że ta informacja miała zostać opublikowana. To właśnie mediana dwóch wartości ją powstrzymała.

Rozwiązania praktyczne

Który plik powinien zawierać treść? Dowody przemawiają za AGENTS.md, przy czym CLAUDE.md miałby pełnić rolę jedynie odnośnika. Większość repozytoriów z dwoma plikami (89 z 132) robi dokładnie to. Pozostaje jedna kopia wiedzy, a agenci, które nigdy nie szukają pliku specyficznego dla Claude’a, nadal mogą go odczytać.

Czy Claude Code czyta bezpośrednio plik AGENTS.md? Nie, ze względu na zasady nazywania plików – w odróżnieniu od CLAUDE.md – i to właśnie ta różnica jest powodem istnienia wzorca wskaźników. W praktyce sprawdzają się dwa rozwiązania: symlink gitowy o nazwie CLAUDE.md, który wskazuje na AGENTS.md, albo import typu @AGENTS.md. Projekt new-api nawet w swoim pliku CLAUDE.md ostrzega, że import nie zawsze działa poprawnie, i zaleca agentowi otwarcie pliku osobiście.

Czy 27,9% stopnia adopcji to dobra czy zła wartość? Lepsza niż oczekiwano dla tak młodej konwencji, gorsza jednak niż sugeruje playbook. Dwie inne liczby mówią więcej: 12,0% repozytoriów zawiera pliki CLAUDE.md z rzeczywistą treścią, a tylko 5,4% łączy je z mechanizmami egzekucji.

Dlaczego 31 repozytoriów nadal przechowuje oba te istotne pliki? Różnice pomiędzy kopiami nigdy nie były mierzone, co stanowi oczywisty temat dla kolejnych badań. Podwójna wiedza instytucjonalna staje się obciążeniem, gdy kopie się różnią, a narzędzia nie dają żadnych ostrzeżeń.

Czy ktoś inny może to powtórzyć? Tak. Próbka pochodzi z publicznego rankingu gwiazd, sondą są proste, nieautoryzowane żądania HTTP do raw.githubusercontent.com, a klasyfikator mieści się w około 40 liniach kodu.

Ostatnia sprawdzenie przed uruchomieniem repozytorium z przypisanym agentem kodującym: kiedy ostatnio zmienił się polecenie budowania, czy plik z wiedzą agenta również uległ zmianie w tym samym komitcie, czy też stare polecenie pojawiło się trzy sesje później?

Literatura pokrewna

• Format Otwartej Wiedzy: Porywna pamięć dla agentów do programowania AI — Jak Format Otwartej Wiedzy przechowuje wiedzę agentów w postaci powiązanych plików markdown, w czym różni się od CLAUDE.md i MCP oraz jak zacząć go używać.
• Strukturyzowanie projektów Claude Code, aby agenci mogli skupić się w dużych repozytoriach — Sześć wzorców dla dużych baz kodu: warstwowe pliki CLAUDE.md, umiejętności, podagenci, reguły odrzucenia, rzadkie drzewa zadań oraz wtyczki language-server, które utrzymują czysty kontekst agenta.