dox: Awtomatikong Panatilihing Updated ang AGENTS.md

Bakit mali na ang iyong AGENTS.md pagkalipas ng tatlong linggo

Naluluma ang AGENTS.md dahil walang nag-uugnay dito sa code. Isinusulat mo ito nang isang beses, mano-mano, sa araw na ganoon ang itsura ng repository. Pagkatapos, nagbabago ang test runner, napapalitan ang pangalan ng package, nade-delete ang isang service, at inilalarawan pa rin ng file ang kalagayan noong June. Walang nagfa-fail dahil walang build step na nagbabasa rito.

Binabasa ito ng agent at pinaniniwalaan. Iyan ang bahaging nagdudulot sa iyo ng problema. Kapag walang AGENTS.md ang repository, tumitingin muna ang coding agent sa paligid bago kumilos. Kapag mali ang AGENTS.md, tumitigil itong maghanap dahil mayroon na itong sagot. Pinapatakbo nito ang command na nakalagay sa file, sumasagot ang shell ng Missing script: "test", at nagsisimula nang manghula ang agent. Madalas nitong ine-edit ang package.json upang idagdag ang script na ipinangako ng documentation. Hindi tahimik na nag-fail ang lumang file. Nagdulot ito ng edit na hindi mo gusto.

Isang sagot dito ang dox. Isa itong set ng rules na isinulat para sa agent. Ginagawa nitong bahagi ng pagtatapos ng trabaho ang pag-update ng documentation, kaya nagbabago ang file sa parehong commit ng code na naging dahilan kung bakit ito mali.

Ano ang dox, at ano ang hindi nito

Ang dox ay isang Markdown file lamang. Ang repository ay agent0ai/dox, lisensyado ito sa ilalim ng MIT, at noong 11 August 2026, ang buong project ay binubuo ng isang 3906-byte na AGENTS.md, isang README, isang LICENSE, at dalawang image. Walang package na kailangang i-install at walang runtime.

Mahalaga ito dahil ang salitang generator ay nagmumungkahi ng program na nagpa-parse ng iyong code. Walang nagpa-parse ng iyong code. Ang dox ay isang contract na binabasa ng iyong coding agent: ang agent mo ang generator, at ang dox ang instruction set na nagsasabi rito kung kailan babasahin ang mga dokumento, kailan ire-rewrite ang mga ito, at kung ano ang magiging format ng bawat dokumento.

May sampung section ang file, at dalawa sa mga ito ang gumagawa ng pangunahing trabaho. Sinasabi ng "Read Before Editing" sa agent na sundan mula sa repository root ang bawat path na plano nitong baguhin, at basahin ang bawat AGENTS.md sa bawat dinaanang path, sa kasalukuyang session, nang hindi umaasa sa memorya. Sinasabi naman ng "Update After Editing" na nangangailangan ng DOX pass ang bawat makabuluhang pagbabago. Ibig sabihin, dapat magpatakbo ng documentation update step bago ituring na tapos ang task. Ina-update ng pass ang pinakamalapit na document na may-ari ng path kapag nagbago ang purpose, structure, workflow, permissions, o user preferences.

Tungkol naman sa format ang iba pang bahagi. May default section order ang child AGENTS.md: Purpose, Ownership, Local Contracts, Work Guidance, Verification, at Child DOX Index. Naglalaman ang root file ng project-wide rules at ng top-level Child DOX Index, na ginagamit ng agent upang matuklasan ang mga child document. Ang "Closeout" ang checklist na pinapatakbo ng agent sa pagtatapos ng task: muling suriin ang mga binagong path laban sa chain, i-update ang pinakamalapit na owning docs, i-refresh ang bawat apektadong index, burahin ang mga contradiction, patakbuhin ang kasalukuyang verification, at iulat kung aling mga doc ang sadyang hindi nito binago.

I-pin ang dox sa isang commit, hindi sa main

Walang tags at releases ang repository, kaya walang version number na maaaring i-pin. Sa halip, i-pin ang commit. Ang kasalukuyang AGENTS.md ay commit f34ec7ad1055d3393887e5a2670e8cb7320c9165, na may petsang 1 August 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

Dapat mag-print ang wc -c ng 3906. Nangangahulugan ang ibang numero na hindi mo na-fetch ang file na tinutukoy ng guide na ito, kaya basahin muna ito bago mo pagkatiwalaan. Kung mali ang pagkaka-type mo sa commit hash, ihihinto ng -f ang curl na may curl: (22) The requested URL returned error: 404 at walang isusulat na content, at magpi-print naman ang wc -c ng 0. Mas masama ang truncated file kaysa sa walang file, dahil sinusunod ng agent ang kalahati ng isang kontrata nang hindi nito nalalaman.

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

Ang cp ay para sa repository na wala pang AGENTS.md. Kung mayroon ka na nito, huwag itong i-overwrite. Ilagay ang mga dox section bago ang dati mong content, panatilihin ang sarili mong rules sa ibaba, at basahin nang isang beses ang resulta mula itaas hanggang ibaba. Ang dalawang dokumentong nagkakasalungatan ay nagreresulta sa agent na sumusunod sa linyang huli nitong nabasa.

Pagkatapos, hilingin sa agent, habang nasa loob ng repository, ang unang pass. Nasa README ang eksaktong wording:

Initialize DOX tree for this project now.

Gagawa ito ng mga child AGENTS.md file at ng mga index na tumutukoy sa mga ito. Suriin muna ang ginawa nito bago mo ito pagkatiwalaan:

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

Dapat lumitaw ang bawat file sa find output na iyon sa isang Child DOX Index sa isang lugar sa itaas nito. Maaaring hindi makita ng agent ang child document na walang index na tumutukoy rito, dahil ginagamit nito ang index upang mahanap ang mga dokumentong wala mismo sa path na nilalakaran nito.

Ano ang nakikita ng dox, at ano ang hindi nito malalaman

Binabasa ng agent na gumagawa ng iyong tree ang repository, kaya maaaring mapunta sa inventory ang anumang nasa repository: ang directory layout, package manifests at lockfiles, ang mga script sa package.json o Makefile o pyproject.toml, CI workflow files, Dockerfiles, entry points, at CODEOWNERS kung mayroon ka nito. Tunay na self-maintaining ang inventory na binuo mula sa mga iyon. Kapag inilipat ang isang package, ililipat din ng susunod na pass ang linyang naglalarawan dito.

Maaari mong ilahad ang lahat ng nasa ibaba, dahil wala ang mga ito sa repository para mabasa:

• kung bakit umiiral ang isang rule; ito ang pumipigil sa agent na alisin ito bilang hindi kailangang complexity
• kung alin sa dalawang gumaganang path ang supported, at alin ang nakabinbing tanggalin
• anumang nasa labas ng repository, gaya ng staging environment o dahilan kung bakit naka-pin ang isang dependency nang dalawang version na mas luma
• kung ano ang plano mong gawin sa susunod na linggo; ito ang pagkakaiba ng file na current at file na kapaki-pakinabang

Alam ito ng dox tungkol sa sarili nito. Sinasabi ng sarili nitong rules na dapat ipakita sa Work Guidance ang kasalukuyang standards ng project o ang instructions ng user, at kung wala pa ang mga iyon, dapat manatiling walang laman ang section. Dapat ipakita sa Verification ang isang umiiral na check, kaya kung walang test framework sa repo, mananatiling walang laman ang section na iyon hanggang sa magkaroon nito. Mas masama ang generated file na nag-iimbento ng standard kaysa sa walang laman na section, dahil ipatutupad ng agent ang imbensiyon.

Panatilihing wala sa generated inventory ang intent na isinulat ng tao

Ito ang failure na nagiging dahilan kung bakit sumusuko ang mga tao sa generated docs. Sumulat ka ng paragraph na nagpapaliwanag na dapat manatiling single consumer ang jobs queue. Makalipas ang tatlong linggo, may pass na muling nagsulat sa file at nawala ang paragraph mo sa loob ng diff na may 40 lines, kung saan karamihan ay pag-aayos lang ng mga filename, at walang nakapansin.

Dalawang mechanism ang kailangan, at dapat gamitin ang dalawa.

Una, ilipat ang permanenteng intent sa ibang file. Ang mga design decision at paliwanag sa mga ito ay dapat nasa DESIGN.md na isinulat para sa agent, at ang mga note para sa mga tao ay dapat nasa lugar kung saan mo hinihiwalay ang HUMAN.md mula sa AGENTS.md. Ang AGENTS.md ay dapat maglaman ng inventory at mga lokal na contract, na siyang bahaging dapat magbago kapag nagbago ang code.

Ikalawa, lagyan ng fence ang intent na kailangang manatili sa loob ng AGENTS.md. I-wrap ito sa markers at ituring na pagmamay-ari ng tao ang block:

## 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 -->

Hindi nagre-render sa page ang Markdown comments, pero nababasa pa rin ito ng agent. Gawing mache-check ang pananatili ng block upang ang pass na magtanggal nito ay mag-fail nang malinaw. Patakbuhin ito sa CI (continuous integration) sa bawat 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

Walang pini-print ang diff at nag-e-exit ito sa 0 kapag hindi nabago ang block. Anumang output ay nangangahulugang muling isinulat ng pass ang text na pagmamay-ari ng tao, kaya kailangan itong i-approve ng isang tao o i-revert. Gumagana ang check kahit walang kailangang makaalala nito.

Mag-regenerate sa pull request, hindi ayon sa timer

Ang pinakamainam na oras para i-refresh ang isang dokumento ay kapag ginawa ng commit na mali ito. Ilagay ang DOX pass sa parehong pull request ng structural change para manatiling sapat na maliit ang diff upang aktuwal na mabasa.

Isang blocking check na nagpapatupad nito:

#!/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

I-adjust ang mga path ayon sa iyong repository. Ang pakinabang nito ay nagfa-fail ito sa branch, kung saan mura pang ayusin ang problema, at nagfa-fail ito dahil sa isang dahilan na maaaring aksyunan ng reviewer.

Backup lamang ang schedule, hindi ito ang mekanismo. Nahuhuli ng weekly job ang mga bagay na walang nakapansin sa branch: mga file na nailipat dahil sa rebase, package na natanggal sa merge, o dokumentong tumutukoy sa directory na wala na. Patakbuhin ito sa isang maliit na box, gaya ng maaari mong gamitin upang magpatakbo ng coding agent sa isang VPS, at ipagawa rito ang pagbubukas ng pull request sa halip na direktang mag-push sa 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

Sadyang placeholder ang comment na iyon. May sariling CLI (command line interface) at sariling non-interactive flag ang bawat agent. Kapag ang command na kinopya mula sa isang web page ay hindi tugma sa iyong version, magfa-fail ito sa loob ng cron at walang makakakita ng error. Punan ito at manu-manong patakbuhin ang script nang isang beses bago mo i-schedule. Mahalaga rin ang || exit 0: nag-e-exit ang git commit gamit ang nothing to commit, working tree clean kapag current na ang tree, at sa ilalim ng set -e, iuulat nito ang matagumpay na run bilang failure.

May token cost ang bawat pass dahil pinapabasa ng “Read Before Editing” sa agent ang buong chain sa bawat task. Iyan ang trade-off, at sulit itong subaybayan kung binibilang mo na kung magkano ang gastos ng mga pinapatakbo ng iyong agent.

Monorepo: maraming contract, iisang index

Ang isang root AGENTS.md sa repository na may forty packages ay nagbubunga ng regeneration diff na walang nagbabasa, at ng dokumentong halos walang kaugnayan sa kasalukuyang ginagawa ng agent. Ang sagot ng dox ay ang Child DOX Index: nasa root ang mga panuntunang saklaw ang buong repository at mga reference patungo sa mga child nito, habang ang bawat permanenteng boundary ay may sarili nitong file. Ang tamang ayos ng tree na ito, pati kung aling tools ang bumabasa ng nested files, ay tinatalakay sa nested AGENTS.md files para sa mga monorepo.

Binabago ng dox ang saklaw ng review. Ang pull request na nagbabago sa packages/api ay dapat maglabas ng documentation diff sa loob lamang ng packages/api:

git diff --stat -- '*AGENTS.md'

Kung naglilista ang command na iyon ng anim na file para sa pagbabagong saklaw ang isang package, mali ang ayos ng tree. Maaaring masyadong malawak ang mga boundary, o nakopya sa bawat child ang panuntunang dapat nasa root. Direktang inilalahad ng dox ang dapat gawin: ilagay ang malalawak na panuntunan sa parent docs, at ang mga konkretong detalye sa child docs. Ang duplicate na panuntunan ang dahilan kung bakit nire-rewrite ng isang karaniwang pass ang lahat. Kung tunay na pareho ang mga panuntunan sa magkakahiwalay na repository, ibang problema iyon, at mas angkop na tool ang pagbabahagi ng agent skills sa iba’t ibang repository.

Suriin ang diff na parang code

Madaling i-approve ang generated documentation diff nang hindi ito binabasa. Dito nagmumula ang pag-release ng maling file. Basahin ito nang kasing-ingat ng generated code, at hanapin ang apat na bagay.

• isang command na binanggit na ngayon ng file, na dapat mong patakbuhin mismo bago ang merge. Ang gawa-gawang build instruction ang pinakakaraniwang problema.
• isang dinelete na linya na naglalaman ng layunin. Madaling magdagdag. Sa deletion nangyayari ang pagkawala ng mahalagang impormasyon.
• isang absolute path, hostname, internal URL, o anumang kahawig ng credential
• isang inventory entry para sa bagay na wala na, na mabilis maayos ng ls

Pagkatapos, tingnan ang laki gamit ang wc -l AGENTS.md. Ang root file na lumampas sa 200 lines ay senyales na dapat itong hatiin, dahil ang buong halaga ng chain ay mabasa ng agent ang maliit na bahaging kailangan nito sa halip na basahin ang lahat.

Kapag nagkaproblema

Binura ng pass ang iyong intent block. Ipinapakita ng diff check sa itaas ang mga tinanggal na linya. I-restore ang file mula sa branch point gamit ang git restore --source=origin/main AGENTS.md, pagkatapos ay patakbuhin muli ang pass gamit ang mas makitid na instruction na tahasang nagbabanggit sa mga section na maaari nitong baguhin.

Parehong nag-regenerate ang dalawang branch. Makakakita ka ng CONFLICT (content): Merge conflict in AGENTS.md at mga conflict marker na <<<<<<< HEAD sa loob ng file. Huwag manu-manong i-edit ang mga marker. Generated ang file, kaya ang tamang resolution ay magpatakbo muli ng panibagong pass sa merged tree.

Lubusang binabalewala ng agent ang file. Suriin kung aling filename ang aktuwal na binabasa ng iyong tool. Kung iba ang binabasa nito, ituro ito sa parehong content gamit ang ln -s AGENTS.md CLAUDE.md at i-commit ang symlink, para iisa lang ang source mo sa halip na dalawang dokumentong unti-unting nagkakaiba.

Lumaki ang tree at may mga child na hindi na-index. Ihambing ang output ng find . -name AGENTS.md sa mga index entry sa parent documents. Ang child na walang index na tumutukoy rito ay child na maaaring tuluyang malampasan ng agent.

Kapag sobra na ang generator

Isang package, isang test command, at dalawang taong parehong pamilyar sa repository: isulat nang mano-mano ang dalawampung linya. Hindi sapat ang bilis ng pagbabago ng isang dalawampung-linyang AGENTS.md para bigyang-katwiran ang isang tree, index, CI check, at weekly job. Basahin itong muli kapag binago mo ang build. Iyon na ang buong maintenance cost, at mas maliit ito kaysa sa cost ng mga mekanismong nakapaligid dito.

Sulit gamitin ang dox kapag may mga boundary ang repository na walang isang tao ang ganap na kabisado: ilang package na may magkakaibang rule, o mga contributor na nagsisimula nang walang background sa proyekto. Hindi ang nabuong text ang mahalaga. Ang halaga nito ay nagiging dokumentasyong maaaring maging dahilan para mag-fail ang isang pull request. Iyon lang ang dahilan kung bakit nananatiling updated ang anumang file sa isang repository.

FAQ

Kailangan ko bang mag-install ng anuman para magamit ang dox?

Hindi. Ang dox ay isang Markdown file, may MIT license, at noong 11 August 2026 ay wala pang package o release ang repository. Kopyahin ang laman nito sa AGENTS.md ng iyong project, at susundin ng coding agent mo ang mga panuntunan mula roon. I-pin ang commit na kinopya mo, f34ec7ad1055d3393887e5a2670e8cb7320c9165 noong isinulat ito, at ilagay ang pangalan nito sa commit message para matukoy mo kung anong bersyon ng mga panuntunan ang ginamit sa pagbuo ng tree mo.

Paano ko pipigilan na mabura ng regeneration ang mga panuntunang isinulat ko nang mano-mano?

Paghiwalayin ang intent at inventory. Ilagay ang pangmatagalang reasoning sa hiwalay na dokumento, at ilagay sa marked block ang anumang kailangang manatili sa loob ng AGENTS.md. Pagkatapos, i-check ang block sa CI: i-extract ito mula sa branch at mula sa origin/main gamit ang sed, ikumpara ang dalawa gamit ang diff, at i-fail ang build kapag may anumang pagkakaiba. Tao ang mag-aapruba o magre-revert ng pagbabago, sa halip na hindi ito mapansin sa loob ng malaking diff.

Gaano kadalas dapat akong mag-regenerate ng AGENTS.md?

Sa pull request na nagiging sanhi ng pagiging mali nito. Dapat nasa iisang diff ang structural change at ang dokumentasyon nito, dahil iyon lang ang panahong may sapat na context ang isang tao para suriin ang dalawa. Ang weekly scheduled pass ang backup para sa drift na nakalusot sa isang branch, at dapat itong magbukas ng pull request sa halip na direktang mag-commit sa main.

Dapat bang nasa root AGENTS.md ang mga build command o nasa child?

Sa pinakamalapit na dokumentong nagmamay-ari ng mga ito. Nasa root ang repo-wide rules at ang child index. Ang command na para sa isang package lamang ay dapat nasa AGENTS.md ng package na iyon. Niresolba ng dox ang mga conflict batay sa layo: ang mas malapit na dokumento ang kumokontrol sa mga lokal na detalye, at hindi maaaring pahinain ng child ang rule ng parent. Ang pagkopya ng parehong command sa bawat child ang dahilan kung bakit nire-rewrite ng routine pass ang buong tree.

Sulit ba ang dox para sa maliit na repository?

Karaniwan, hindi. Mabagal ma-decay ang isang package na may isang test command at dalawampung-linyang AGENTS.md, at maaayos mo ito sa loob ng isang minuto kapag napansin mo. Sulit ang dox kapag maraming boundary ang repository na may magkakaibang panuntunan, o kapag may mga contributor na kulang sa background, dahil ginagawa ng chain of documents ang trabahong hindi ginagawa ng isang tao lamang.