Automatyczna aktualizacja pliku AGENTS.md za pomocą dox

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 według stanu na 11 sierpnia 2026 cały projekt to jeden plik AGENTS.md o rozmiarze 3906 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 określa, kiedy ma on czytać dokumentację, kiedy ją aktualizować i jaki kształt ma przyjąć każdy dokument.

Plik zawiera dziesięć sekcji, z których dwie wykonują główną 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, ż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, Wytyczne Pracy, Weryfikacja oraz Indeks Podrzędnych DOX. Plik główny zawiera zasady dotyczące całego projektu 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 raport dotyczący dokumentów, które celowo pominięto.

Przypięcie dokumentacji do konkretnego commita, a nie do main

Repozytorium nie posiada tagów ani wydań (releases), więc nie ma numeru wersji, do którego można by się odwołać. Należy przypiąć konkretny commit. Bieżący plik AGENTS.md odpowiada commitowi f34ec7ad1055d3393887e5a2670e8cb7320c9165 z dnia 1 sierpnia 2026.

mkdir -p .agent
curl -fsSL -o .agent/dox-f34ec7a.md \
  https://raw.githubusercontent.com/agent0ai/dox/f34ec7ad1055d3393887e5a2670e8cb7320c9165/AGENTS.md
wc -c .agent/dox-f34ec7a.md

Polecenie wc -c powinno zwrócić 3906. Inna wartość oznacza, że pobrano plik inny niż opisany w tym przewodniku; należy go zweryfikować przed użyciem. W przypadku błędnego wpisania skrótu commita, -f spowoduje przerwanie działania curl z kodem curl: (22) The requested URL returned error: 404 i brak zapisu zawartości, a wc -c wyświetli 0. Plik niekompletny jest gorszy niż brak pliku, ponieważ agent realizuje połowę kontraktu, nie będąc tego świadomym.

cp .agent/dox-f34ec7a.md AGENTS.md
git add AGENTS.md .agent/dox-f34ec7a.md
git commit -m "Add DOX rules (agent0ai/dox @ f34ec7a)"

Polecenie cp jest przeznaczone dla repozytoriów, które nie posiadają jeszcze pliku AGENTS.md. Jeśli plik już istnieje, nie należy go nadpisywać. Sekcje dokumentacji należy umieścić nad istniejącą treścią, zachować własne reguły poniżej i przeczytać całość od początku do końca. Dwa sprzeczne dokumenty powodują, że agent stosuje się do wytycznych, które przeczytał jako ostatnie.

Następnie należy poprosić agenta wewnątrz repozytorium o wykonanie pierwszego przebiegu. Plik README zawiera dokładne sformułowanie:

Initialize DOX tree for this project now.

Proces ten tworzy podrzędne pliki AGENTS.md oraz indeksy, które do nich prowadzą. Przed zatwierdzeniem zmian należy sprawdzić wynik działania:

git status --short
find . -name AGENTS.md -not -path './.git/*' | sort

Każdy plik wymieniony w danych wyjściowych find powinien znajdować się w odpowiednim indeksie dokumentacji podrzędnej powyżej. Dokument podrzędny, o którym nie wspomina żaden indeks, może zostać pominięty przez agenta, ponieważ indeks jest mechanizmem odnajdywania dokumentów, które nie znajdują się bezpośrednio na ścieżce przetwarzania.

Co dox widzi, a 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 taki istnieje. Inwentarz zbudowany na tej podstawie jest w pełni samoobsługowy. Gdy pakiet zmienia lokalizację, kolejne przejście agenta aktualizuje opisującą go linię.

Wszystkie poniższe informacje muszą zostać podane przez użytkownika, ponieważ nie znajdują się one w repozytorium:

• powód istnienia reguły, co zapobiega usuwaniu 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, co znajduje się 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 wiedzę o własnym działaniu. Jego reguły stanowią, że Work Guidance musi odzwierciedlać aktualne standardy projektu lub instrukcje użytkownika, a w przypadku ich braku sekcja ta pozostaje pusta. Weryfikacja musi opierać się na istniejącym sprawdzeniu, więc jeśli w repozytorium nie ma frameworka testowego, sekcja ta pozostaje pusta do czasu jego dodania. Wygenerowany plik, który wymyśla standard, jest gorszy niż pusta sekcja, ponieważ agent zacznie egzekwować wymyślone zasady.

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

diff 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
fi

Dostosuj ś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 --fill

Ten 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 ls rozstrzyga 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 jeden plik Markdown na licencji MIT. Według stanu na 11 sierpnia 2026 r. repozytorium nie udostępnia żadnych pakietów ani wydań. Należy skopiować zawartość pliku do 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 f34ec7ad1055d3393887e5a2670e8cb7320c9165, i umieścić jego identyfikator w komunikacie commitu. Pozwoli to w przyszłości sprawdzić, na podstawie której wersji reguł zbudowano drzewo projektu.

Jak zapobiec usuwaniu ręcznie napisanych reguł podczas regeneracji?

Należy oddzielić intencje 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 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 różnic. Zmiana wymaga wtedy zatwierdzenia lub odrzucenia 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ż tylko wtedy autor posiada kontekst niezbędny do sprawdzenia obu elementów. Cotygodniowe, zaplanowane zadanie stanowi zabezpieczenie przed rozbieżnościami, które mogły umknąć w gałęziach; powinno ono otwierać pull request, zamiast dokonywać commitu bezpośrednio do main.

Czy polecenia budowania powinny znajdować się w głównym AGENTS.md czy w pliku podrzędnym?

W najbliższym dokumencie, który nimi zarządza. Reguły dotyczące całego repozytorium oraz indeks podrzędny znajdują się w katalogu głównym. Polecenie dotyczące jednego pakietu powinno znajdować się w pliku AGENTS.md tego pakietu. dox rozwiązuje konflikty na podstawie odległości: dokument znajdujący się bliżej kontroluje szczegóły lokalne, a żaden dokument podrzędny nie może osłabiać reguły nadrzędnej. Kopiowanie tego samego polecenia do każdego pliku podrzędnego powoduje, że rutynowa operacja 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 degraduje się powoli i można go naprawić w minutę po zauważeniu problemu. dox zwraca się, gdy repozytorium posiada wiele granic z różnymi regułami lub gdy współtwórcy nie posiadają odpowiedniego przygotowania. W takich sytuacjach łańcuch dokumentów wykonuje pracę, której nie jest w stanie wykonać jedna osoba.