AGENTS.md jest teraz Pana/Pani przewagą: co zawierają produkcyjne pliki

Gdy create-next-app trzy dni temu wprowadził AGENTS.md jako domyślny element szablonu, wybór frameworka przestał różnicować projekty. Zawartość tego pliku jest teraz jedynym, co oddziela działający stack agentowy od niesprawnego.

Przez sześć miesięcy posiadanie AGENTS.md oznaczało, że zespół jest o krok do przodu. Od 2026-04-28 każdy nowy projekt Next.js dostarcza go z pudełka. Sygnał się zatarł. To, co znajduje się wewnątrz pliku, stało się nowym sygnałem.

Większość liderów inżynieryjnych traktuje AGENTS.md jak dokumentację. To plik konfiguracyjny uruchamiany w runtime, który model ładuje przy każdym wywołaniu. Ten artykuł omawia empiryczne badanie Augment Code, regułę 100-150 linii decydującą o tym, czy plik pomaga czy szkodzi, oraz szablon, który wdrażamy w 11 produkcyjnych repozytoriach klientów.

Kluczowe wnioski

• Next.js 16.2 dostarcza AGENTS.md jako domyślny szablon (wydanie 2026-04-28). Każdy nowy starter na Vercel dziedziczy ten plik.

• Badanie AuggieBench Augment Code (2026-04-23): pliki między 100 a 150 linii osiągają najlepsze wyniki. Po przekroczeniu 150 linii zyski się odwracają.

• Ten sam plik może podnieść dokładność naprawy błędów o 25% i obniżyć kompletność funkcji o 30% przy różnych zadaniach. Projekt sekcji ma większe znaczenie niż łączna długość.

• AGENTS.md jest jedyną powierzchnią dokumentacji ze 100% wskaźnikiem odkrywalności. Osierocone foldery _docs/ plasują się poniżej 10%.

• Nową przewagą są proceduralne workflow, tabele decyzyjne i jednoliniowe reguły reaktywne. Nie przeglądy architektury ani stosy ostrzeżeń.

Trzy dni temu AGENTS.md przestał być wyróżnikiem

Next.js 16.2 ukazał się 2026-04-28 z AGENTS.md jako domyślnym plikiem w szablonie create-next-app. Vercel dystrybuuje ten szablon do każdego nowego projektu startowego. Plik, który kiedyś oznaczał przewagę zespołu, teraz jest dostarczany w pustym pudełku.

Zmiana w debacie jest tu kluczowa. Sześć miesięcy temu pytano, czy dany zespół ma AGENTS.md. W tym tygodniu pytanie brzmi: co się w nim znajduje. Kupujący oceniający partnerów developerskich potrzebują nowego sposobu punktowania, bo binarny sygnał zniknął.

Dwa równoległe sygnały wzmacniają tę zmianę. Repozytorium mattpocock/skills Matta Pocock'a osiągnęło 41 000 gwiazdek w 85 dni, a repo to dosłownie opublikowany folder .claude. Ludzie oznaczają gwiazdkami cudze konfiguracje agentów tak, jak kiedyś oznaczali frameworki. Tak wygląda komodytyzacja.

Repozytorium gstack Garry'ego Tan'a, wydane w tym samym tygodniu, przekroczyło 23 000 gwiazdek w siedem dni. Tan użył go do dostarczenia 600 000 linii kodu produkcyjnego w 60 dni. Repo zawiera 31 plików markdown ze skill'ami. Nie ma pod spodem żadnego frameworka.

Jeśli dział zakupów potrzebuje sposobu na ocenę gotowości AI podczas ewaluacji dostawców, webvise wdrożył ten szablon w 11 buildach klientów i może przedstawić stosowaną przez nas metodologię.

Reguła 100-150 linii z pomiarami

Augment Code opublikował pierwsze empiryczne badanie jakości zawartości AGENTS.md 2026-04-23. Autor, Slava Zhenylenko, pobrał dziesiątki plików AGENTS.md z monorepository Augment. Każdy plik przeszedł dwukrotnie przez zestaw ewaluacyjny AuggieBench: raz z plikiem i raz bez. Wyniki były oceniane względem wzorcowych PR zatwierdzonych przez ludzi.

Główny wynik: najlepsze pliki dały skok jakości równoważny ulepszeniu z Haiku do Opus. Najgorsze pliki dawały wyniki gorsze niż brak AGENTS.md w ogóle. Ten sam zespół inżynieryjny, ten sam model, to samo zadanie. Plik decydował o różnicy.

Optymalny zakres był wąski. Pliki między 100 a 150 linii, sparowane z małym zestawem skoncentrowanych dokumentów referencyjnych ładowanych na żądanie, dawały zyski między 10 a 15% we wszystkich metrykach w modułach średniej wielkości liczących około 100 plików źródłowych. Po przekroczeniu 150 linii zyski się odwracały.

Wyznanie samego Tan'a pokrywało się z tym odkryciem od strony zasad. Jego CLAUDE.md miał 20 000 linii, z każdą osobliwością, każdym wzorcem, każdą lekcją zakodowaną w jednym pliku. Claude Code sam wskazał ten przerost. Rozwiązaniem było około 200 linii wskaźników, a treść przeniesiono do skill'ów ładowanych na żądanie.

Nasz własny szablon stosowany w 11 repozytoriach klientów webvise, w tym aesthetic-medicine-app, biomed-landing, hyyve-landing, kersten-betreuung-landing i urban-sports-sniper-app, ma 126 linii. Tej liczby nie dobieraliśmy, by pasować do badania. Badanie zostało opublikowane dwa tygodnie po tym, jak ustandaryzowaliśmy szablon.

Wskaźniki odkrywalności z logów Augment zebranych przez setki sesji wyjaśniają, dlaczego umiejscowienie ma równie duże znaczenie co zawartość:

AGENTS.md jest jedyną powierzchnią z gwarantowaną odkrywalnością. Jeśli coś musi być widoczne, musi tam się znajdować lub być stamtąd wskazane. Przeniesienie treści do miejsca z referencją przynosi więcej efektów niż pisanie kolejnych dokumentów.

Co umieszcza się w pliku, a co go niszczy

Logi Augment zostały przeanalizowane według typów zawartości. Wzorce podnoszące wyniki i te je psujące nie są symetryczne.

Co działa

• Proceduralne workflow. Ponumerowane wieloetapowe workflow były najsilniejszym pojedynczym wzorcem. Sześcioetapowy workflow wdrożenia nowej integracji obniżył PR z brakującymi plikami konfiguracyjnymi z 40% do 10%, podniósł poprawność o 25% i kompletność o 20%.

• Tabele decyzyjne przy 2 lub 3 rozsądnych opcjach. Tabela decyzyjna React Query kontra Zustand dała 25% poprawę w best_practices przy PR w tym obszarze. Tabela rozstrzyga niejednoznaczność, zanim agent zacznie pisać kod.

• Rzeczywiste przykłady z kodu, po 3 do 10 linii. Poprawia ponowne użycie i przestrzeganie wzorców. Dłuższe fragmenty powodują, że agent dopasowuje wzorzec do niewłaściwego elementu.

• Do każdego "nie" dołącz "tak". Dokumentacja zawierająca tylko zakazy wypada gorzej. Samo zakaz czyni agenta ostrożnym i skłonnym do eksploracji. Sparowanie go z pozytywną dyrektywą wskazującą właściwe miejsce w kodzie sprawia, że agent idzie dalej.

• Pliki na poziomie modułów zamiast jednego ogromnego pliku root. Zakres 100-150 linii pasuje do modułu średniej wielkości liczącego około 100 plików. Pliki przekrojowe dla całego projektu powyżej tego rozmiaru traciły w każdej metryce.

Co niszczy wyniki

• Przeglądy architektury. Agent czyta przegląd, następnie otwiera dziesiątki otaczających dokumentów, by zweryfikować podejście, ładuje od 10 000 do 100 000 tokenów nieistotnego kontekstu i wyniki się pogarszają. Augment nazwał to pułapką nadmiernej eksploracji.

• Stosy ostrzeżeń bez sparowanej instrukcji. Przy 30 do 50 zakazach i braku wskazówek agent weryfikuje swoje rozwiązanie wobec każdego ostrzeżenia indywidualnie, nawet gdy żadne nie ma zastosowania.

• Wzorce, które jeszcze nie istnieją w codebase. Jeśli AGENTS.md opisuje architekturę, której kod nie implementuje, plik aktywnie prowadzi agenta w złym kierunku.

• Rozrost dokumentacji wokół pliku. Najgorsze przypadki w badaniu Augment to pliki AGENTS.md spoczywające na 500K do 2 MB dokumentów architektonicznych. Usunięcie samego AGENTS.md niemal nie zmieniało zachowania. Agent i tak czytał otaczające pliki.

Reaktywnie, nie z wyprzedzeniem

Elie Steinbock opublikował 2026-04-20 odrębny tekst z dyscypliną, która naprawia większość plików AGENTS.md w firmach, które audytujemy. Nie należy pisać dziesiątek reguł, zanim cokolwiek pójdzie nie tak. Nadmierne strukturyzowanie z wyprzedzeniem tworzy przerost, który model parsuje przy każdym uruchomieniu.

Reguły należy dodawać reaktywnie, gdy nastąpiła rzeczywista korekta, i ograniczać każde dodanie do jednej linii. Przy czymkolwiek cięższym treść powinna trafić do progresywnie ładowanego skill'a. AGENTS.md pozostaje kompaktowy. Warstwa skill'ów przejmuje ciężar.

Równoległa reguła Tan'a, dyscyplina "dwa razy poprosiłeś", mówi to samo z drugiej strony. Jeśli trzeba prosić agenta o coś dwukrotnie, drugie prośby nie powinno być. Wzorzec trafia do warstwy skill'ów lub do AGENTS.md jako jednoliniowa reguła. System się kumuluje.

W buildzie webvise wygląda to tak: AGENTS.md jest dostarczany z 126 liniami i miejscami na uzupełnienie. Katalog .claude/skills zawiera 8 do 15 plików skill'ów przy dostarczeniu, a każdy z nich to procedura, którą zespół faktycznie wykonał podczas buildu. Plik nie antycypuje problemów. Rejestruje rozwiązane.

Pięć pytań, które dział zakupów powinien zadać każdemu dostawcy

Jakość zawartości AGENTS.md jest teraz mierzalnym wskaźnikiem egzekucji natywnej dla AI. Pięć poniższych pytań daje nieinżynierskiemu działowi zakupów szybki obraz tego, czy dostawca dostarcza na stack 2026, czy 2024.

Jeśli dostawca nie potrafi odpowiedzieć na trzy z pięciu pytań, nadal dostarcza szablon z 2024 roku. Większość korporacyjnych zespołów napotyka tę barierę na poziomie dokumentacji. Ten audyt jest pierwszą fazą każdego zaangażowania migracyjnego webvise.

Głębszy wniosek: napraw środowisko, nie tylko punkt wejścia

Najbardziej niewygodne odkrycie Augment dotyczyło najgorzej ocenianych plików AGENTS.md. Spoczywały one na 500K do 2 MB otaczających dokumentów architektonicznych. Zespół usunął sam AGENTS.md z uruchomienia, a zachowanie niemal się nie zmieniło. Agent i tak czytał te pliki niezależnie od tego, co mówił plik wejściowy.

To wniosek trudny do zaakceptowania przez korporacyjne zespoły z długą historią. Większość środowisk dokumentacyjnych zbudowanych przed 2024 rokiem zawiera lata zapisów decyzji architektonicznych, dokumentów projektowych i instrukcji operacyjnych. Agent ładuje ich wystarczająco dużo, by zagłuszyć czysty AGENTS.md. Napisanie lepszego pliku wejściowego jest konieczne, ale niewystarczające.

Ta praca jest niewygodna. Należy przeprowadzić audyt dokumentów faktycznie ładowanych przez agenta, oznaczyć martwe do archiwizacji, zmodularyzować aktywne w referencje na poziomie modułów i utrzymywać AGENTS.md wskazujący tylko na to, co agent powinien przeczytać na ścieżce do zmiany. Metafora Tan'a ma tu zastosowanie: mózg to repozytorium git, orkiestrator to cienki dyrygent czytający pliki. Jeśli repozytorium git jest pełne martwych stron, żaden plik wejściowy tego nie naprawi.

Co to oznacza dla zamawiających build w 2026 roku

Wojna o frameworki dobiegła końca. Next.js, Astro, SvelteKit i Nuxt dostarczają szablony AGENTS.md domyślnie lub uczynią to w tym kwartale. Wyróżnik przesunął się o warstwę wyżej. Zawartość pliku, struktura katalogu skill'ów i dyscyplina stojąca za oboma decydują o tym, czy stack agentowy pomaga czy przeszkadza.

Nowoczesne buildy webowe w 2026 roku są czytelne dla agenta od pierwszego dnia. To kontrakt, który webvise realizuje domyślnie w każdym projekcie, od jednostronicowego landing site do wielotenantowego SaaS. Szablon 126 linii, warstwa .claude/skills i dyscyplina reaktywnych reguł nie są opcjami dodatkowymi. To jest build.