Automatyczna aktualizacja pliku AGENTS.md za pomocą dox
Nieaktualny plik AGENTS.md prowadzi do błędów agentów AI. Wykorzystaj narzędzie dox do automatycznego generowania dokumentacji z kodu i weryfikuj zmiany poprzez diff.
Dlaczego plik AGENTS.md staje się nieaktualny po trzech tygodniach
Plik AGENTS.md dezaktualizuje się, ponieważ nie jest powiązany z kodem źródłowym. Tworzysz go ręcznie w dniu, w którym repozytorium ma określony stan. Następnie zmienia się mechanizm uruchamiania testów, pakiet zostaje przemianowany, a usługa usunięta, podczas gdy plik nadal opisuje stan z czerwca. Nic nie zgłasza błędu, ponieważ żaden etap budowania nie odczytuje tego pliku.
Agent odczytuje plik i uznaje zawarte w nim informacje za prawdziwe. To właśnie ten element generuje koszty. Repozytorium bez pliku AGENTS.md zmusza agenta programistycznego do rozejrzenia się przed podjęciem działania. Repozytorium z błędnym plikiem AGENTS.md sprawia, że agent przestaje szukać, ponieważ posiada już odpowiedź. Wykonuje polecenie wskazane w pliku, powłoka zwraca Missing script: "test", a agent zaczyna zgadywać. Często edytuje package.json, aby dodać skrypt, który obiecała dokumentacja. Nieaktualny plik nie zawiódł w sposób cichy. Spowodował edycję, której nie oczekiwałeś.
dox stanowi rozwiązanie tego problemu. Jest to zestaw reguł przygotowanych dla agenta, dzięki którym aktualizacja dokumentacji staje się częścią kończenia pracy. W rezultacie plik zmienia się w tym samym commicie, co kod, który spowodował jego nieaktualność.
Czym jest dox, a czym nie jest
dox to pojedynczy plik Markdown. Repozytorium to agent0ai/dox, jest ono na licencji MIT, a na dzień 13 października 2026 cały projekt to jeden plik AGENTS.md o rozmiarze 3965 bajtów, plik README, plik LICENSE oraz dwa obrazy. Nie ma żadnego pakietu do instalacji ani środowiska uruchomieniowego.
Ma to znaczenie, ponieważ słowo „generator” sugeruje program, który analizuje kod. Nic nie analizuje kodu. dox to kontrakt, który odczytuje agent programistyczny: agent jest generatorem, a dox to zestaw instrukcji, który mówi mu, kiedy czytać dokumentację, kiedy ją nadpisywać i jaki kształt ma przyjąć każdy dokument.
Plik zawiera dziewięć sekcji, z których dwie wykonują właściwą pracę. „Read Before Editing” nakazuje agentowi przejście od katalogu głównego repozytorium do każdej ścieżki, którą zamierza zmodyfikować, oraz odczytanie każdego pliku AGENTS.md na danej trasie w bieżącej sesji, bez polegania na pamięci. „Update After Editing” informuje agenta, że każda istotna zmiana wymaga przejścia DOX, co oznacza, że krok aktualizacji dokumentacji musi zostać wykonany przed uznaniem zadania za ukończone. Przejście to aktualizuje najbliższy dokument nadrzędny, gdy zmieni się cel, struktura, przepływ pracy, uprawnienia lub preferencje użytkownika.
Reszta to struktura. Podrzędny plik AGENTS.md posiada domyślną kolejność sekcji: Cel, Własność, Lokalne Kontrakty, Wskazówki Dotyczące Pracy, Weryfikacja oraz Indeks Podrzędnych DOX. Plik główny zawiera zasady obowiązujące w całym projekcie oraz nadrzędny Indeks Podrzędnych DOX, dzięki któremu agent odkrywa dokumenty podrzędne. „Closeout” to lista kontrolna, którą agent wykonuje po zakończeniu zadania: ponowne sprawdzenie zmienionych ścieżek względem łańcucha, aktualizacja najbliższych dokumentów nadrzędnych, odświeżenie każdego powiązanego indeksu, usunięcie sprzeczności, uruchomienie istniejącej weryfikacji oraz raportowanie, które dokumenty zostały celowo pominięte.
Przypnij dox do konkretnego commita, a nie do main
Repozytorium nie posiada tagów ani wydań, więc nie ma numeru wersji, do którego można by się odwołać. Zamiast tego należy przypiąć commit. Aktualny plik AGENTS.md to commit 765ae4ac02cc884eefcd41a3d0f71941721adb89 z dnia 1 września 2026.
mkdir -p .agent
curl -fsSL -o .agent/dox-765ae4a.md \
https://raw.githubusercontent.com/agent0ai/dox/765ae4ac02cc884eefcd41a3d0f71941721adb89/AGENTS.md
wc -c .agent/dox-765ae4a.mdPolecenie wc -c powinno wyświetlić 3965. Inna wartość oznacza, że nie pobrano pliku opisanego w tym przewodniku, więc należy go przeczytać przed zaufaniem jego zawartości. W przypadku błędnego wpisania hasha commita, -f spowoduje przerwanie działania curl z błędem curl: (22) The requested URL returned error: 404 i nie zapisze żadnej zawartości, a wc -c wyświetli 0. Obcięty plik jest gorszy niż brak pliku, ponieważ agent realizuje połowę kontraktu, nie będąc tego świadomym.
Jeśli przypięto wcześniejszy commit, f34ec7a z 1 sierpnia 2026, należy sprawdzić jego Child DOX Index. W tej wersji sekcja opisuje własne repozytorium dox: informuje, że pliki AGENTS.md potomne nie są wymagane i wymienia README.md, LICENSE oraz dwa obrazy jako pliki należące do roota. Skopiowany do własnego projektu indeks opisuje niewłaściwe repozytorium. Wersja z 1 września zastąpiła go symbolem zastępczym, który informuje, że projekt nie został jeszcze zaindeksowany i nakazuje agentowi przeskanowanie repozytorium oraz zbudowanie drzewa przed kontynuacją. Należy zastąpić starą sekcję właściwym indeksem lub nowym symbolem zastępczym.
cp .agent/dox-765ae4a.md AGENTS.md
git add AGENTS.md .agent/dox-765ae4a.md
git commit -m "Add DOX rules (agent0ai/dox @ 765ae4a)"Polecenie cp jest przeznaczone dla repozytorium, które nie posiada jeszcze pliku AGENTS.md. Jeśli taki plik już istnieje, nie należy go nadpisywać. Sekcje dox należy umieścić nad istniejącą zawartością, zachować własne reguły poniżej i przeczytać wynik od początku do końca. Dwa sprzeczne dokumenty powodują, że agent postępuje zgodnie z instrukcją, którą przeczytał jako ostatnią.
Następnie należy poprosić agenta, znajdując się wewnątrz repozytorium, o wykonanie pierwszego przejścia. Plik README zawiera dokładne sformułowanie:
Initialize DOX tree for this project now.Tworzy to potomne pliki AGENTS.md oraz indeksy, które na nie wskazują. Warto o to poprosić jawnie, mimo że indeks zastępczy nakazuje agentowi wykonanie tego przed jakąkolwiek inną pracą: pozwala to uzyskać całe drzewo w jednym możliwym do zweryfikowania commicie, zamiast jako efekt uboczny niezwiązanego zadania. Przed zaakceptowaniem zmian należy sprawdzić, co zostało wykonane:
git status --short
find . -name AGENTS.md -not -path './.git/*' | sortKażdy plik w danych wyjściowych find powinien pojawić się w Child DOX Index w miejscu powyżej. Dokument potomny, o którym nie wspomina żaden indeks, może zostać pominięty przez agenta, ponieważ to właśnie indeks pozwala mu odnaleźć dokumenty, które nie znajdują się bezpośrednio na ścieżce, którą podąża.
Co widzi dox i czego nie może wiedzieć
Agent budujący drzewo odczytuje repozytorium, więc wszystko, co się w nim znajduje, może trafić do inwentarza: struktura katalogów, manifesty pakietów i pliki blokad, skrypty w package.json, Makefile lub pyproject.toml, pliki workflow CI, Dockerfiles, punkty wejścia oraz CODEOWNERS, jeśli istnieje. Inwentarz zbudowany na tej podstawie jest w pełni samoutrzymujący się. Gdy pakiet zmienia lokalizację, kolejne przejście agenta przenosi linię, która go opisuje.
Wszystko poniżej należy do użytkownika, ponieważ nie znajduje się w repozytorium:
- powód istnienia reguły, co zapobiega usunięciu jej przez agenta jako zbędnej złożoności
- informacja, która z dwóch działających ścieżek jest wspierana, a która oczekuje na usunięcie
- wszystko poza repozytorium, na przykład środowisko stagingowe lub powód, dla którego zależność jest przypięta do wersji sprzed dwóch wydań
- plany na przyszły tydzień, co stanowi różnicę między plikiem aktualnym a plikiem użytecznym
dox posiada tę wiedzę na swój temat. Jego własne reguły stanowią, że wytyczne dotyczące pracy (Work Guidance) muszą odzwierciedlać aktualne standardy projektu lub instrukcje użytkownika, a w przypadku ich braku sekcja ta pozostaje pusta. Weryfikacja musi odnosić się do istniejącego mechanizmu sprawdzającego, więc jeśli w repozytorium nie ma frameworka weryfikacyjnego, sekcja ta pozostaje pusta do momentu jego wdrożenia. Wygenerowany plik, który wymyśla standard, jest gorszy niż pusta sekcja, ponieważ agent zacznie wymuszać stosowanie tego wymysłu.
Utrzymanie ręcznie dopisanych intencji poza wygenerowanym inwentarzem
To właśnie ten błąd sprawia, że użytkownicy rezygnują z generowanej dokumentacji. Autor pisze akapit wyjaśniający, że kolejka zadań musi obsługiwać tylko jednego konsumenta. Trzy tygodnie później proces automatyczny nadpisuje plik, akapit znika wewnątrz diffa o długości czterdziestu linii, który głównie zmienia nazwy plików, a nikt tego nie zauważa.
Potrzebne są dwa mechanizmy i należy wdrożyć oba.
Po pierwsze, należy przenieść trwałe intencje do osobnego pliku. Decyzje projektowe i stojąca za nimi argumentacja powinny znajdować się w pliku DESIGN.md przeznaczonym dla agenta, natomiast notatki przeznaczone dla ludzi powinny być tam, gdzie oddzielono HUMAN.md od AGENTS.md. Plik AGENTS.md zawiera wtedy inwentarz oraz lokalne kontrakty, czyli dokładnie tę część, która powinna zmieniać się wraz z kodem.
Po drugie, należy zabezpieczyć intencje, które muszą pozostać wewnątrz AGENTS.md. Należy otoczyć je znacznikami i traktować ten blok jako własność człowieka:
## User Preferences
<!-- dox:keep start -->
The jobs queue stays single consumer. Ordering is the reason this service exists.
Deploys ship on Tuesday. A Friday deploy is a human decision, not an agent decision.
<!-- dox:keep end -->Komentarze Markdown nie są renderowane na stronie, a agent nadal je odczytuje. Teraz należy sprawdzić, czy blok przetrwał, tak aby proces, który go usunie, zakończył się wyraźnym błędem. Należy uruchamiać to w CI (continuous integration) przy każdym pull request:
git fetch -q origin main
sed -n '/dox:keep start/,/dox:keep end/p' AGENTS.md > /tmp/keep.head
git show origin/main:AGENTS.md | sed -n '/dox:keep start/,/dox:keep end/p' > /tmp/keep.base
diff -u /tmp/keep.base /tmp/keep.headdiff nie wypisuje nic i kończy się kodem 0, gdy blok pozostaje nienaruszony. Jakiekolwiek wyjście oznacza, że proces nadpisał tekst należący do człowieka, więc musi on zostać zatwierdzony lub cofnięty przez osobę. Kontrola działa bez konieczności pamiętania o niej przez kogokolwiek.
Regeneracja przy pull request, a nie według harmonogramu
Najlepszym momentem na odświeżenie dokumentu jest commit, który czyni go nieaktualnym. Umieszczenie procesu DOX w tym samym pull request co zmiany strukturalne sprawia, że diff pozostaje na tyle mały, by można go było faktycznie przejrzeć.
Blokująca kontrola wymuszająca to działanie:
#!/usr/bin/env bash
set -euo pipefail
git fetch -q origin main
base=$(git merge-base origin/main HEAD)
changed=$(git diff --name-only "$base" HEAD)
if grep -qE '^(src|apps|packages)/' <<<"$changed" && ! grep -q 'AGENTS\.md$' <<<"$changed"; then
echo "Code changed but no AGENTS.md was touched. Run a DOX pass, or say why not."
exit 1
fiDostosuj ścieżki do swojego repozytorium. Wartość tego rozwiązania polega na tym, że proces kończy się niepowodzeniem na gałęzi, gdzie poprawka jest tania, a przyczyna błędu jest zrozumiała dla recenzenta.
Harmonogram to rozwiązanie zapasowe, a nie główny mechanizm. Cotygodniowe zadanie wyłapuje to, czego nikt nie zauważył na gałęzi: pliki przeniesione przez rebase, pakiet usunięty podczas merge, czy dokument wskazujący na katalog, który już nie istnieje. Uruchamiaj je na małej maszynie, tej samej, której możesz użyć, aby uruchomić agenta programistycznego na VPS, i skonfiguruj je tak, aby otwierało pull request zamiast wypychać zmiany bezpośrednio do main.
#!/usr/bin/env bash
set -euo pipefail
cd /srv/src/myapp
git fetch -q origin
git switch -c "dox/refresh-$(date +%Y%m%d)" origin/main
# Your agent CLI goes on the next line, in whatever non-interactive mode it offers.
# Prompt: "Run a DOX pass over this repository. Change AGENTS.md files only."
git add '*AGENTS.md'
git commit -m "dox: refresh AGENTS.md tree" || { echo "nothing to refresh"; exit 0; }
git push -q -u origin HEAD
gh pr create --fillTen komentarz jest celowo umieszczonym symbolem zastępczym. Każdy agent posiada własne CLI (command line interface) oraz własną flagę trybu nieinteraktywnego, a polecenie skopiowane ze strony internetowej, które nie pasuje do Twojej wersji, zakończy się błędem wewnątrz cron, gdzie nikt go nie zauważy. Uzupełnij je i uruchom skrypt ręcznie przed dodaniem do harmonogramu. Wartość || exit 0 również ma znaczenie: git commit kończy działanie z kodem innym niż zero przy użyciu nothing to commit, working tree clean, gdy drzewo jest już aktualne, a w ramach set -e mogłoby to zgłosić poprawne wykonanie zadania jako awarię.
Każde przejście kosztuje tokeny, ponieważ zasada "Read Before Editing" zmusza agenta do odczytania całego łańcucha przy każdym zadaniu. Jest to kompromis, który warto monitorować, jeśli już liczysz koszty operacji swojego agenta.
Monorepo: wiele kontraktów, jeden indeks
Jeden główny plik AGENTS.md w repozytorium zawierającym czterdzieści pakietów generuje różnice w dokumentacji, których nikt nie czyta, oraz dokument, który w większości jest nieistotny dla bieżących zadań agenta. Rozwiązaniem dox jest Child DOX Index: katalog główny zawiera zasady dotyczące całego repozytorium i wskazuje na swoje elementy podrzędne, a każda trwała granica posiada własny plik. Sposób rozmieszczenia tego drzewa oraz narzędzia obsługujące zagnieżdżone pliki zostały opisane w zagnieżdżone pliki AGENTS.md dla monorepo.
To, co zmienia dox, to zakres przeglądu. Pull request modyfikujący packages/api powinien wygenerować różnicę w dokumentacji wewnątrz packages/api i nigdzie indziej:
git diff --stat -- '*AGENTS.md'Jeśli to polecenie wyświetla sześć plików dla zmiany w jednym pakiecie, struktura drzewa jest błędna. Albo granice są zbyt szerokie, albo zasada, która powinna znajdować się w katalogu głównym, została skopiowana do każdego elementu podrzędnego. dox wskazuje bezpośrednie rozwiązanie: ogólne zasady umieszcza się w dokumentacji nadrzędnej, a konkretne szczegóły w dokumentacji podrzędnej. Zduplikowane zasady sprawiają, że rutynowa zmiana powoduje nadpisanie wszystkiego. Jeśli te same zasady rzeczywiście mają zastosowanie w różnych repozytoriach, jest to inny problem, a udostępnianie umiejętności agenta między repozytoriami stanowi w takim przypadku lepsze narzędzie.
Weryfikacja różnic w kodzie
Wygenerowane różnice w dokumentacji łatwo zatwierdzić bez czytania, co prowadzi do publikacji błędnych plików. Należy czytać je z taką samą podejrzliwością, jak wygenerowany kod, zwracając uwagę na cztery elementy.
- Polecenie wymienione w pliku, które należy samodzielnie uruchomić przed scaleniem zmian. Wymyślone instrukcje budowania są najczęstszą przyczyną awarii.
- Usunięta linia, która niosła istotną treść. Dodawanie treści jest tanie. Utrata informacji następuje podczas usuwania.
- Ścieżka bezwzględna, nazwa hosta, wewnętrzny URL lub cokolwiek przypominającego dane uwierzytelniające.
- Wpis w inwentarzu dotyczący czegoś, co już nie istnieje, co
lsrozstrzyga w sekundę.
Następnie należy sprawdzić rozmiar za pomocą wc -l AGENTS.md. Plik root przekraczający dwieście linii jest sygnałem do jego podziału, ponieważ główną wartością łańcucha jest to, że agent odczytuje małą, istotną część zamiast całości.
W razie awarii
Przejście usunęło blok intencji. Kontrola diff powyżej wyświetla usunięte linie. Przywróć plik z punktu rozgałęzienia za pomocą git restore --source=origin/main AGENTS.md, a następnie uruchom przejście ponownie, stosując węższą instrukcję wskazującą sekcje, które mogą zostać zmodyfikowane.
Obie gałęzie wygenerowały zmiany. Otrzymasz CONFLICT (content): Merge conflict in AGENTS.md oraz znaczniki konfliktu <<<<<<< HEAD wewnątrz pliku. Nie edytuj znaczników ręcznie. Plik jest generowany automatycznie, więc poprawnym rozwiązaniem jest ponowne wykonanie przejścia na scalonym drzewie.
Agent całkowicie ignoruje plik. Sprawdź, jaką nazwę pliku faktycznie odczytuje narzędzie. Jeśli odczytuje inny plik, wskaż go na tę samą zawartość za pomocą ln -s AGENTS.md CLAUDE.md i zatwierdź dowiązanie symboliczne (symlink), aby zachować jedno źródło zamiast dwóch rozbieżnych dokumentów. Jeśli nazwa pliku jest poprawna, a reguły nadal są pomijane, przeprowadź diagnostykę dlaczego agenci programujący ignorują instrukcje przed ponownym przepisaniem dokumentu.
Drzewo rozrosło się o elementy nieindeksowane. Porównaj wynik find . -name AGENTS.md z wpisami indeksu w dokumentach nadrzędnych. Element podrzędny, o którym nie wspomina żaden indeks, jest elementem, który agent może całkowicie pominąć.
Kiedy generator jest zbędny
Jeden pakiet, jedno polecenie testowe, dwie osoby znające repozytorium: dwadzieścia linii kodu można napisać ręcznie. Plik AGENTS.md o długości dwudziestu linii nie dezaktualizuje się na tyle szybko, aby uzasadniać tworzenie drzewa, indeksu, sprawdzania w CI oraz cotygodniowych zadań. Należy przeczytać go ponownie przy zmianie procesu budowania. To cały koszt utrzymania, który jest niższy niż koszt infrastruktury potrzebnej do jego automatyzacji.
Warto płacić cenę za dox, gdy repozytorium posiada granice, których jedna osoba nie jest w stanie objąć pamięcią: kilka pakietów z różnymi regułami lub współtwórcy, którzy dołączają do projektu bez odpowiedniego przygotowania. Wartością nie jest wygenerowany tekst. Wartością jest to, że dokumentacja staje się elementem, przez który pull request może zostać odrzucony, co jest jedynym powodem, dla którego jakikolwiek plik w repozytorium pozostaje aktualny.
FAQ
Czy muszę coś instalować, aby używać dox?
Nie. dox to pojedynczy plik Markdown na licencji MIT. Według stanu na 13 października 2026 repozytorium nie dostarcza żadnych pakietów ani wydań. Należy skopiować jego zawartość do pliku AGENTS.md w swoim projekcie, a agent programistyczny będzie przestrzegał zawartych tam reguł. Należy przypiąć skopiowany commit, w momencie pisania tego tekstu jest to 765ae4ac02cc884eefcd41a3d0f71941721adb89, i umieścić tę informację w wiadomości commitu, aby później móc określić, na podstawie której wersji reguł zbudowano drzewo projektu.
Jak zapobiec usunięciu ręcznie napisanych reguł podczas regeneracji?
Należy oddzielić intencję od inwentarza. Trwałe uzasadnienia powinny znajdować się w osobnym dokumencie, a wszystko, co musi pozostać wewnątrz AGENTS.md, należy umieścić w oznaczonym bloku. Następnie należy sprawdzić ten blok w systemie CI: wyodrębnić go z gałęzi oraz z origin/main za pomocą sed, porównać oba za pomocą diff i przerwać budowanie w przypadku wykrycia jakiejkolwiek różnicy. Zmiana powinna zostać zatwierdzona lub odrzucona przez człowieka, zamiast przechodzić niezauważenie wewnątrz dużego diffa.
Jak często należy regenerować AGENTS.md?
W ramach pull requesta, który powoduje, że plik staje się nieaktualny. Zmiana strukturalna i jej dokumentacja powinny znajdować się w jednym diffie, ponieważ jest to jedyny moment, w którym ktoś posiada kontekst niezbędny do zweryfikowania obu elementów. Cotygodniowe, zaplanowane uruchomienie służy jako zabezpieczenie przed rozbieżnościami, które mogły umknąć w gałęzi, i powinno otwierać pull request zamiast commitować bezpośrednio do gałęzi main.
Czy polecenia budowania powinny znajdować się w głównym pliku AGENTS.md czy w pliku podrzędnym?
W najbliższym dokumencie, do którego się odnoszą. Reguły dotyczące całego repozytorium oraz indeks podrzędny znajdują się w katalogu głównym. Polecenie mające zastosowanie do jednego pakietu znajduje się w pliku AGENTS.md tego pakietu. W przypadku konfliktu dokumentów, dox pozwala dokumentowi znajdującemu się bliżej kontrolować szczegóły pracy lokalnej, przy czym jedyną rzeczą, której żaden dokument podrzędny nie może osłabić, jest sama umowa DOX. Ogólne zasady znajdują się w dokumentach nadrzędnych, a konkretne szczegóły w dokumentach podrzędnych. Kopiowanie tego samego polecenia do każdego dokumentu podrzędnego sprawia, że rutynowa aktualizacja nadpisuje całe drzewo.
Czy warto używać dox w małym repozytorium?
Zazwyczaj nie. Jeden pakiet z jednym poleceniem testowym i dwudziestoliniowym plikiem AGENTS.md ulega degradacji powoli, a naprawa zajmuje minutę po zauważeniu problemu. dox zwraca się, gdy repozytorium posiada kilka granic z różnymi regułami lub gdy współpracownicy nie posiadają odpowiedniego tła technicznego, ponieważ wtedy łańcuch dokumentów wykonuje pracę, której nie wykonuje żadna pojedyncza osoba.