Automatyczna aktualizacja pliku AGENTS.md za pomocą dox

Dlaczego plik AGENTS.md staje się nieaktualny po trzech tygodniach

Plik AGENTS.md traci aktualność, 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 zmienia nazwę, a usługa zostaje 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 aspekt 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ż uważa, że zna już odpowiedź. Uruchamia polecenie wskazane w pliku, powłoka zwraca Missing script: "test", a agent zaczyna zgadywać. Często edytuje package.json, aby dodać skrypt, który został obiecany w dokumentacji. Nieaktualny plik nie spowodował cichej awarii. Spowodował edycję, której nie chciał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, w którym znajduje się kod powodujący jego nieaktualność.

Czym jest dox, a czym nie jest

dox to pojedynczy plik Markdown. Repozytorium jest agent0ai/dox, udostępnione 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ż nazwa generatora sugeruje program analizujący kod. Nic nie analizuje kodu. dox to kontrakt, który odczytuje agent programistyczny: agent jest generatorem, a dox to zestaw instrukcji określający, kiedy należy przeczytać dokumentację, kiedy ją przeredagować oraz jaki kształt powinien przyjąć każdy dokument.

Plik składa się z dziesięciu 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 znajdującego się na tej 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 krok aktualizacji dokumentacji wykonany przed uznaniem zadania za zakoń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ść, Kontrakty lokalne, Wytyczne pracy, Weryfikacja oraz Indeks podrzędnych plików DOX. Plik główny zawiera zasady dotyczące całego projektu oraz nadrzędny Indeks podrzędnych plików DOX, dzięki któremu agent odkrywa dokumenty podrzędne. "Closeout" to lista kontrolna, którą agent wykonuje na końcu 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 pozostawiono bez zmian.

Przypięcie dokumentacji 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 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 wypisać 3906. 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 skrótu commita, -f spowoduje zatrzymanie curl z błędem curl: (22) The requested URL returned error: 404 i nie zapisze żadnej zawartości, a wc -c wypisze 0. Obcięty plik 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 repozytorium, które nie posiada jeszcze pliku AGENTS.md. Jeśli plik już istnieje, nie należy go nadpisywać. Należy umieścić sekcje dokumentacji nad istniejącą treścią, zachować własne reguły poniżej i przeczytać wynik od początku do końca. Dwa sprzeczne dokumenty powodują, że agent stosuje się do wytycznych z linii, którą przeczytał jako ostatnią.

Następnie należy poprosić agenta, będąc wewnątrz repozytorium, o wykonanie pierwszego przejścia. Plik README zawiera dokładne sformułowanie:

Initialize DOX tree for this project now.

Tworzy to podrzędne pliki AGENTS.md oraz indeksy, które na nie wskazują. Przed zatwierdzeniem zmian należy sprawdzić wykonane operacje:

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

Każdy plik wymieniony w danych wyjściowych find powinien pojawić się w indeksie dokumentacji podrzędnej (Child DOX Index) powyżej. Dokument podrzędny, o którym nie wspomina żaden indeks, może zostać pominięty przez agenta, ponieważ to właśnie indeks służy do odnajdywania dokumentów, które nie znajdują się bezpośrednio na ścieżce przetwarzania.

Co widzi dox, 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, Dockerfile, 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 aktualizuje opisującą go linię.

Wszystko poniżej należy do Ciebie, ponieważ nie znajduje się w repozytorium i nie może zostać odczytane:

• 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, 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 tę wiedzę na swój temat. Jego własne 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 odnosić się do istniejącego testu, 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.

Zachowanie ręcznie wprowadzonych założeń poza wygenerowanym inwentarzem

To właśnie ten błąd sprawia, że użytkownicy rezygnują z wygenerowanej dokumentacji. Piszesz akapit wyjaśniający, że kolejka zadań musi pozostać jednokonsumencka. Trzy tygodnie później automatyczny proces nadpisuje plik i Twój 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.

Potrzebujesz dwóch mechanizmów, aby temu zapobiec.

Po pierwsze, przenieś trwałe założenia 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 trafić tam, gdzie rozdzielisz HUMAN.md od AGENTS.md. Plik AGENTS.md zawiera wtedy inwentarz oraz lokalne kontrakty, czyli dokładnie te elementy, które powinny zmieniać się wraz z kodem.

Po drugie, zabezpiecz założenia, które muszą pozostać wewnątrz AGENTS.md. Otocz je znacznikami i traktuj 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 spraw, aby przetrwanie tego bloku było weryfikowalne, tak aby proces, który go usunie, zakończył się wyraźnym błędem. Uruchamiaj 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 niczego 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 w ramach pull request, 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 przeczytać.

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 błąd występuje na branchu, gdzie poprawka jest tania, a przyczyna jest zrozumiała dla recenzenta.

Harmonogram to zabezpieczenie, a nie główny mechanizm. Cotygodniowe zadanie wyłapuje to, czego nikt nie zauważył na branchu: pliki przeniesione przez rebase, pakiet usunięty podczas merge, dokument wskazujący na katalog, który już nie istnieje. Uruchamiaj to na małej maszynie, tej samej, której możesz użyć, aby uruchomić agenta programistycznego na VPS, i skonfiguruj tak, aby otwierał 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. Parametr || exit 0 również ma znaczenie: git commit kończy działanie z kodem wyjścia innym niż zero przy użyciu nothing to commit, working tree clean, gdy drzewo jest już aktualne, a w ramach set -e spowodowałoby to zgłoszenie poprawnego przebiegu jako awarii.

Każde przejście kosztuje tokeny, ponieważ zasada "Read Before Editing" sprawia, że agent odczytuje cały łańcuch przy każdym zadaniu. Jest to kompromis, który warto monitorować, jeśli już liczysz koszty uruchomień 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. Żądanie pull request modyfikujące packages/api powinno 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 ogólne, 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 szczegóły techniczne w dokumentacji podrzędnej. Zduplikowane zasady powodują, że rutynowa zmiana wymusza nadpisanie wszystkiego. Jeśli te same zasady faktycznie mają zastosowanie w różnych repozytoriach, jest to inny problem, a udostępnianie umiejętności agenta między repozytoriami jest w takim przypadku lepszym narzędziem.

Weryfikacja różnic w dokumentacji jak w kodzie źródłowym

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 zawierała istotne założenia. Dodawanie treści jest łatwe. Utrata informacji następuje w miejscach, gdzie usunięto fragmenty tekstu.
• ścieżka bezwzględna, nazwa hosta, wewnętrzny URL lub cokolwiek przypominającego dane uwierzytelniające.
• wpis w inwentarzu dotyczący elementu, który 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ą zaletą łańcucha jest to, że agent odczytuje mały, istotny fragment zamiast całości.

W przypadku awarii

Przekazanie 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 ponownie przekazanie z węższą instrukcją wskazującą sekcje, które mogą zostać zmodyfikowane.

Obie gałęzie zostały wygenerowane ponownie. 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 uruchomienie procesu dla scalonego drzewa.

Agent całkowicie ignoruje plik. Sprawdź, którą nazwę pliku faktycznie odczytuje narzędzie. Jeśli odczytuje inny plik, wskaż go za pomocą ln -s AGENTS.md CLAUDE.md i zatwierdź dowiązanie symboliczne, aby zachować jedno źródło zamiast dwóch dokumentów, które z czasem zaczną się różnić.

Drzewo rozrosło się o elementy nieindeksowane. Porównaj wynik find . -name AGENTS.md z wpisami w indeksie 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.

Narzędzia typu dox są przydatne, gdy repozytorium posiada granice, których jedna osoba nie jest w stanie objąć: kilka pakietów z różnymi regułami lub współtwórcy, którzy dołączają do projektu bez odpowiedniego przygotowania. Wartość nie tkwi w wygenerowanym tekście. Polega ona na tym, ż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 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 f34ec7ad1055d3393887e5a2670e8cb7320c9165, i umieścić jego identyfikator w wiadomości commitu. Pozwoli to w przyszłości ustalić, 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 procesie 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 wprowadza nieprawidłowości. Zmiana strukturalna i jej dokumentacja powinny znajdować się w jednym diffie, ponieważ tylko wtedy osoba przeglądająca posiada kontekst niezbędny do oceny obu elementów. Cotygodniowe, zaplanowane przebiegi służą jako zabezpieczenie przed rozbieżnościami, które ominęły gałąź, i powinny otwierać pull request zamiast commitować bezpośrednio do main.

Czy polecenia budowania powinny znajdować się w głównym pliku 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 znajduje się w pliku AGENTS.md tego pakietu. dox rozwiązuje konflikty na podstawie odległości: bliższy dokument 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 podkatalogu sprawia, że rutynowy przebieg 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 poprawę można wprowadzić w 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. Wtedy łańcuch dokumentów wykonuje pracę, której nie wykonuje żadna pojedyncza osoba.