AGENTS.md to teraz Panstwa przewaga: co zawieraja produkcyjne pliki

Gdy create-next-app trzy dni temu wprowadzil AGENTS.md jako domyslny element szablonu, wybor frameworka przestal rozroznic projekty. Zawartosc tego pliku jest teraz jedynym, co oddziela dzialajacy stack agentowy od niesprawnego.

Przez szesc miesiecy posiadanie AGENTS.md oznaczalo wyprzedzenie. Od 2026-04-28 kazdy nowy projekt Next.js dostarcza go z pudelka. Sygnal sie zatrl. To, co znajduje sie wewnatrz pliku, stalo sie nowym wyroznikiem.

Wiekszosc liderow inzynieryjnych traktuje AGENTS.md jak dokumentacje. To plik konfiguracyjny uruchamiany w czasie wykonania, ktory model laduje przy kazdym wywolaniu. Ten artykul omawia empiryczne badanie Augment Code, regule 100 do 150 linii decydujaca o tym, czy plik pomaga czy szkodzi, oraz wzorzec szablonu stosowany w produkcyjnych repozytoriach klientow.

Zmiany w kontrakcie plikowym

• Next.js 16.2 dostarcza AGENTS.md jako domyslny szablon (wydanie 2026-04-28). Kazdy nowy starter na Vercel dziedziczy ten plik.
• Badanie AuggieBench przeprowadzone przez Augment Code (2026-04-23): pliki o dlugosci od 100 do 150 linii osiagaja najlepsze wyniki. Po przekroczeniu 150 linii zyski sie odwracaja.
• Ten sam plik moze podniesc dokladnosc naprawy bledow o 25% i obnizyc kompletnosc funkcji o 30% przy roznych zadaniach. Projekt sekcji ma wieksze znaczenie niz laczna dlugosc.
• AGENTS.md jest jedyna powierzchnia dokumentacji ze 100-procentowym wskaznikiem wykrywalnosci. Osierocone foldery _docs/ plasuja sie ponizej 10%.
• Nowa przewaga to proceduralne workflow, tabele decyzyjne i jednolinijkowe reguly reaktywne. Nie przeglady architektury ani stosy ostrzezen.

Trzy dni temu AGENTS.md przestalo byc wyroznikiem

Next.js 16.2 ukazal sie 2026-04-28 z AGENTS.md jako domyslnym plikiem w szablonie create-next-app. Vercel dystrybuuje ten szkielet do kazdego nowego projektu startowego. Plik, ktory kiedy oznaczal przewage zespolu, teraz jest dostarczany w pustym pudelku.

Istotna jest zmiana tresci debaty. Szesc miesiecy temu pytano, czy dany zespol ma AGENTS.md. W tym tygodniu pytanie brzmi: co sie w nim znajduje. Oceniajacy partnerow developerskich potrzebuja nowego sposobu punktowania, bo binarny sygnal zniknal.

Dwa rownolegne sygnaly wzmacniaja te zmiane. Repozytorium mattpocock/skills Matta Pocock'a osiagnelo 41 000 gwiazdek w 85 dni, a to dosłownie jego folder .claude opublikowany wprost. Ludzie oznaczaja gwiazdkami cudze konfiguracje agentow tak, jak kiedy oznaczali frameworki. Tak wyglada komodytyzacja.

Repozytorium gstack Garry'ego Tan'a, wydane w tym samym tygodniu, przekroczylo 23 000 gwiazdek w siedem dni. Tan uzyl go do dostarczenia 600 000 linii kodu produkcyjnego w 60 dni. Repozytorium zawiera 31 plikow markdown ze skryptami. Nie ma pod nim zadnego frameworka.

Jesli dzial zakupow potrzebuje sposobu oceny gotowosci AI podczas ewaluacji dostawcow, webvise moze przeprowadzic Panstwa przez rubryki stosowane w projektach klientow.

Regula 100 do 150 linii z pomiarami

Augment Code opublikowal pierwsze empiryczne badanie jakosci zawartosci AGENTS.md 2026-04-23. Autor, Slava Zhenylenko, pobral dziesiatki plikow AGENTS.md z monorepository Augment. Kazdy plik przeszedl dwukrotnie przez zestaw ewaluacyjny AuggieBench: raz z plikiem i raz bez. Wyniki porownywano ze wzorcowymi PR zatwierdzonymi przez ludzi.

Glowny wynik: najlepsze pliki dawaly skok jakosci rownowazny ulepseniu z Haiku do Opus. Najgorsze pliki dawaly wyniki gorsze niz brak AGENTS.md w ogole. Ten sam zespol inzynieryjny, ten sam model, to samo zadanie. Plik decydowal o roznicy.

Optymalny zakres byl waski. Pliki o dlugosci od 100 do 150 linii, sparowane z malym zestawem skoncentrowanych dokumentow referencyjnych ladowanych na zadanie, dawaly zyski od 10 do 15% we wszystkich metrykach w modulach sredniej wielkosci liczacych okolo 100 plikow zrodlowych. Po przekroczeniu 150 linii zyski sie odwracaly.

Doswiadczenie samego Tan'a potwierdzalo to od strony zasad. Jego plik CLAUDE.md liczyl 20 000 linii i zawieral kazda osobliwosc, kazdy wzorzec i kazda lekcje w jednym pliku. Claude Code sam wskazal ten przerost. Rozwiazaniem bylo okolo 200 linii wskaznikow, a tresc przeniesiono do skryptow ladowanych na zadanie.

Szablony webvise w repozytoriach klientow mieszcza sie w zakresie rekomendowanym przez Augment. Nazwy repozytoriow klientow nie sa publikowane, bo liczy sie wzorzec pracy: jeden kompaktowy plik wejsciowy, elementy zastepowalne specyficzne dla projektu i skrypty wyciagane dopiero po tym, jak zespol rozwiaze powtarzalny problem.

Wskazniki wykrywalnosci z logow Augment zebranych przez setki sesji wyjasniaja, dlaczego umiejscowienie ma rownie duze znaczenie co zawartosc:

AGENTS.md jest jedyna powierzchnia z gwarantowana wykrywalnoscio. Jesli cos musi byc widoczne, musi tam sie znajdowac lub byc stamtad wskazane. Przeniesienie tresci do miejsca z referencja przynosi wiecej efektow niz pisanie kolejnych dokumentow.

Co wzmacnia plik, a co go niszczy

Logi Augment zostaly przeanalizowane wedlug typow zawartosci. Wzorce podnoszace wyniki i te je psujace nie sa symetryczne.

Co dziala

• Proceduralne workflow. Ponumerowane wieloetapowe workflow byly najsilniejszym pojedynczym wzorcem. Szescioetapowy workflow wdrozenia nowej integracji obnizy1 odsetek PR z brakujacymi plikami konfiguracyjnymi z 40% do 10%, podnisl poprawnosc o 25% i kompletnosc o 20%.
• Tabele decyzyjne przy 2 lub 3 rozsdnych opcjach. Tabela decyzyjna React Query kontra Zustand dala 25% poprawe w best_practices przy PR z danego obszaru. Tabela rozstrzyga niejednoznacznosc, zanim agent zacznie pisac kod.
• Rzeczywiste przyklady z kodu, po 3 do 10 linii. Poprawia ponowne uzycie i przestrzeganie wzorcow. Dluzsze fragmenty powoduja, ze agent dopasowuje wzorzec do niewlasciwego elementu.
• Do kazdego zakazu dolaczyc wskazanie pozytywne. Dokumentacja zawierajaca same zakazy wypada gorzej. Samo zakazanie czyni agenta ostroznym i sklonnym do eksploracji. Parowanie go z pozytywna dyrektywa wskazujaca wlasciwe miejsce w kodzie sprawia, ze agent idzie dalej.
• Pliki na poziomie modulow zamiast jednego ogromnego pliku root. Zakres 100 do 150 linii pasuje do modulu sredniej wielkosci liczacego okolo 100 plikow. Pliki przekrojowe dla calego projektu powyzej tego rozmiaru tracily w kazdej metryce.

Co niszczy wyniki

• Przeglady architektury. Agent czyta przeglad, nastepnie otwiera dziesiatki otaczajacych dokumentow, by zweryfikowac podejscie, laduje od 10 000 do 100 000 tokenow nieistotnego kontekstu i wyniki sie pogarzaja. Augment nazwal to pulapka nadmiernej eksploracji.
• Stosy ostrzezen bez sparowanej instrukcji. Przy 30 do 50 zakazach i braku wskazowek agent weryfikuje swoje rozwiazanie wzgledem kazdego ostrzezenia indywidualnie, nawet gdy zadne nie ma zastosowania.
• Wzorce, ktore jeszcze nie istnieja w codebase. Jesli AGENTS.md opisuje architekture, ktorej kod nie implementuje, plik aktywnie prowadzi agenta w zlym kierunku.
• Rozrost dokumentacji wokol pliku. Najgorsze przypadki w badaniu Augment to pliki AGENTS.md spoczywajace na dokumentacji architektonicznej o rozmiarze od 500 KB do 2 MB. Usuniecie samego AGENTS.md z uruchomienia prawie nie zmienilo zachowania. Agent i tak czytal otaczajace pliki.

Reaktywnie, nie z wyprzedzeniem

Elie Steinbock opublikowal 2026-04-20 odrebny tekst z dyscyplina, ktora naprawia wiekszosc plikow AGENTS.md w firmach poddawanych audytowi. Nie nalezy pisac dziesiatek regul, zanim cokolwiek pojdzie nie tak. Nadmierne strukturyzowanie z wyprzedzeniem tworzy przerost, ktory model parsuje przy kazdym uruchomieniu.

Reguly nalezy dodawac reaktywnie, gdy nastapila rzeczywista korekta, i ograniczac kazde dodanie do jednej linii. Przy czymskolwiek ciezszym tresc powinna trafic do progresywnie ladowanego skryptu. AGENTS.md pozostaje kompaktowy, a warstwa skryptow przejmuje ciezar.

Rownolegla regula Tan'a, dyscyplina dwukrotnej prosby, mowi to samo z drugiej strony. Jesli trzeba prosic agenta o cos dwukrotnie, drugiej prosby nie powinno byc. Wzorzec trafia do warstwy skryptow lub do AGENTS.md jako jednolinijkowa regula. System sie kumuluje.

W buildzie webvise wyglada to nastepujaco: AGENTS.md jest dostarczany jako kompaktowy plik wejsciowy z miejscami na uzupelnienie. Katalog .claude/skills zawiera maly zestaw plikow skryptow specyficznych dla dostawy, a kazdy z nich to procedura faktycznie wykonana przez zespol podczas buildu. Plik nie antycypuje problemow. Rejestruje rozwiazane.

Piec pytan, ktore dzial zakupow powinien zadac kazdemu dostawcy

Jakosc zawartosci AGENTS.md jest teraz mierzalnym wskaznikiem egzekucji natywnej dla AI. Ponizsze piec pytan daje nieinzynierskim dzialomzakupow szybki obraz tego, czy dostawca dostarcza na stack 2026 czy 2024.

Jesli dostawca nie jest w stanie odpowiedziec na trzy z pieciu pytan, nadal dostarcza szablon z 2024 roku. Wiekszosc korporacyjnych zespolow napotyka te bariere na poziomie dokumentacji. Ten audyt jest pierwsza faza kazdego zaangozowania migracyjnego webvise.

Glebszy wniosek: naprawa srodowiska, nie tylko punktu wejscia

Najbardziej niepokojacy wynik Augment dotyczyl najgorzej ocenianych plikow AGENTS.md. Spoczywaly one na otaczajacej dokumentacji architektonicznej o rozmiarze od 500 KB do 2 MB. Zespol usunal sam AGENTS.md z uruchomienia, a zachowanie prawie sie nie zmienilo. Agent i tak czytal te pliki niezaleznie od tego, co mowil plik wejsciowy.

To wniosek trudny do zaakceptowania przez korporacyjne zespoly z dluga historia. Wiekszosc srodowisk dokumentacyjnych zbudowanych przed 2024 rokiem zawiera lata zapisow decyzji architektonicznych, dokumentow projektowych i instrukcji operacyjnych. Agent laduje ich wystarczajaco duzo, by zgluszyl czysty AGENTS.md. Napisanie lepszego pliku wejsciowego jest konieczne, lecz niewystarczajace.

Ta praca jest mozolna. Nalezy przeprowadzic audyt dokumentow faktycznie ladowanych przez agenta, oznaczyc martwe do archiwizacji, zmodularyzowac aktywne w referencje na poziomie modulow i utrzymywac AGENTS.md wskazujacy tylko na to, co agent powinien przeczytac na sciezce do zmiany. Metafora Tan'a ma tu zastosowanie: mozg to repozytorium git, a orkiestrator to cienki dyrygent czytajacy pliki. Jesli repozytorium jest pelne martwych stron, zaden plik wejsciowy tego nie naprawi.

Lista kontrolna oddania buildu

Wojna o frameworki dobiegla konca. Next.js, Astro, SvelteKit i Nuxt dostarczaja szablony AGENTS.md domyslnie lub uczynio to w ciagu kwartalu. Wyroznik przesunol sie o warstwe wyzej. Zawartosc pliku, struktura katalogu skryptow i dyscyplina stojaca za oboma decyduja o tym, czy stack agentowy pomaga czy szkodzi.

Nowoczesne buildy webowe w 2026 roku sa gotowe do odczytu przez agenta od pierwszego dnia. To kontrakt, ktory webvise realizuje domyslnie w kazdym projekcie, od jednotematycznego landing site do wielodostepowego SaaS. Kompaktowy szablon, warstwa .claude/skills i dyscyplina reaktywnych regul nie sa opcjami dodatkowymi. To jest build.