Paano Panatilihing Napapanahon ang AGENTS.md Gamit ang dox

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

Luma na ang isang AGENTS.md file dahil walang nag-uugnay rito sa code. Isinusulat mo ito nang isang beses, mano-mano, sa araw na nasa isang partikular na kalagayan ang repository. Pagkatapos, nagbabago ang test runner, napapalitan ang pangalan ng package, nabubura ang isang service, at inilalarawan pa rin ng file ang kalagayan noong June. Walang nagfa-fail dahil walang build step na bumabasa rito.

Binabasa ito ng agent at pinaniniwalaan. Iyan ang bahaging nagdudulot ng problema. Kapag walang AGENTS.md ang repository, tumitingin-tingin muna ang coding agent bago kumilos. Kapag mali ang AGENTS.md, tumitigil itong maghanap dahil mayroon na itong sagot. Pinapatakbo nito ang command na nakasaad sa iyong 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 iyong dokumentasyon. Hindi tahimik na nag-fail ang lumang file. Nagdulot ito ng edit na hindi mo naman gusto.

Isang sagot dito ang dox. Isa itong hanay ng mga panuntunang isinulat para sa agent. Ginagawa nitong bahagi ng pagtatapos ng trabaho ang pag-update ng dokumentasyon, kaya nagbabago ang file sa parehong commit ng code na naging sanhi ng pagiging mali nito.

Ano ang dox at kung ano ito hindi

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 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 maaaring magpahiwatig 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 documentation, kailan ito ire-rewrite, at ano ang magiging anyo ng bawat document.

May sampung seksyon ang file, at dalawa rito ang pangunahing gumaganap ng trabaho. Sinasabi ng "Read Before Editing" sa agent na maglakad mula sa root ng repository patungo sa bawat path na plano nitong baguhin, at basahin ang bawat AGENTS.md sa bawat ruta, sa kasalukuyang session, nang hindi umaasa sa memorya. Sinasabi naman ng "Update After Editing" na ang bawat makabuluhang pagbabago ay nangangailangan ng DOX pass, ibig sabihin, isang documentation update step na kailangang patakbuhin bago maituring 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.

Ang natitira ay tungkol sa anyo. Ang child AGENTS.md ay may default na pagkakasunod-sunod ng mga seksyon: Purpose, Ownership, Local Contracts, Work Guidance, Verification, at Child DOX Index. Naglalaman ang root file ng mga panuntunan para sa buong project pati 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 i-report kung aling mga doc ang sinadyang hindi baguhin.

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 i-print ng wc -c ang 3906. Ibig sabihin ng ibang numero, hindi mo na-fetch ang file na inilalarawan ng guide na ito, kaya basahin muna ito bago mo ito pagkatiwalaan. Kung mali ang pag-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 pagkatapos ay ipi-print ng wc -c ang 0. Mas masama ang truncated file kaysa sa walang file, dahil susundin ng agent ang kalahati ng contract 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 nang isa, huwag itong i-overwrite. Ilagay ang mga dox section sa itaas ng dati mong content, panatilihin ang sarili mong mga rule sa ibaba, at basahin nang isang beses ang buong resulta mula simula hanggang dulo. Kapag nagkakasalungatan ang dalawang document, susundin ng agent ang linyang huli nitong nabasa.

Pagkatapos, hingin 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 ka maniwala rito:

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

Dapat lumitaw ang bawat file sa output ng find sa isang Child DOX Index na nasa itaas nito. Maaaring hindi makita ng agent ang isang child document na hindi binabanggit ng anumang index, dahil ginagamit nito ang index upang hanapin ang mga document na 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 maisama 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.

Ikaw ang dapat maglahad ng 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 kung alin ang nakatakdang 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
• ang plano mong gawin sa susunod na linggo; ito ang pagkakaiba ng file na kasalukuyan pa at file na kapaki-pakinabang

Alam ito ng dox tungkol sa sarili nito. Nakasaad sa sarili nitong rules na dapat ipakita ng Work Guidance ang kasalukuyang standards ng project o ang mga instruction ng user, at kung wala pa ang mga ito, dapat manatiling walang laman ang section. Dapat ipakita ng 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 inimbentong standard.

Panatilihing hiwalay sa generated inventory ang isinulat ng tao

Ito ang failure na nagiging dahilan kung bakit sumusuko ang mga tao sa generated docs. Nagsulat ka ng paragraph na nagpapaliwanag na dapat iisang consumer lang ang manatili sa jobs queue. Pagkalipas ng tatlong linggo, muling nirewrite ng isang pass ang file at nawala ang paragraph sa loob ng diff na may apatnapung linya, na karamihan ay pagbabago lang ng ayos ng mga pangalan ng file. Walang nakapansin.

Dalawang mekanismo ang kailangan mo, at dapat gamitin ang pareho.

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 ihiwalay ang HUMAN.md mula sa AGENTS.md. Ang AGENTS.md ay dapat maglaman ng inventory at mga lokal na contract. Ito mismo ang 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 mga marker at ituring ang block bilang pagmamay-ari ng tao:

## 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 nire-render sa page ang Markdown comments, pero nababasa pa rin ito ng agent. Gawing nasusuri ang pananatili ng block upang mabigo agad ang isang pass na nag-aalis nito. 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 output ang diff at nag-e-exit ito nang may code 0 kapag hindi nabago ang block. Anumang output ay nangangahulugang nirewrite ng pass ang text na pagmamay-ari ng tao, kaya kailangang aprubahan o i-revert ito ng isang tao. 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 sa commit na nagiging mali rito. Ilagay ang DOX pass sa parehong pull request ng structural change para manatiling sapat na maliit ang diff upang aktuwal na masuri.

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 ang pag-aayos, at nagfa-fail ito dahil sa isang dahilan na maaaring aksyunan ng reviewer.

Backup lamang ang schedule, hindi ang pangunahing mekanismo. Nahuhuli ng weekly job ang mga bagay na walang nakapansin sa branch: mga file na nailipat ng rebase, package na natanggal sa merge, o dokumentong tumutukoy sa directory na hindi na umiiral. Patakbuhin ito sa isang maliit na box, gaya ng ginagamit mo para magpatakbo ng coding agent sa VPS, at ipabukas ito ng pull request sa halip na 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 hindi tugma sa iyong version ang command na kinopya mula sa isang web page, magfa-fail ito sa loob ng cron at walang makakakita sa error. Punan ito at patakbuhin muna nang manu-mano ang script 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 ipinababasa ng "Read Before Editing" sa agent ang buong chain sa bawat task. Iyon ang trade-off, at sulit itong subaybayan kung binibilang mo na ang gastos sa pagpapatakbo ng iyong agent.

Monorepo: maraming contract, iisang index

Ang isang root AGENTS.md sa repository na may apatnapung package ay nagbubunga ng regeneration diff na walang nagbabasa, at ng dokumentong halos walang kaugnayan sa ginagawa ng agent sa kasalukuyan. Ang sagot ng dox ay ang Child DOX Index: naglalaman ang root ng mga panuntunang saklaw ang buong repo at tumuturo ito sa mga child nito, habang ang bawat permanenteng boundary ay may sariling file. Ipinaliliwanag sa mga nested AGENTS.md file para sa mga monorepo kung paano ayusin ang tree na ito at kung aling mga tool ang nagbabasa ng nested file.

Binabago ng dox ang saklaw ng review. Ang pull request na may binabagong packages/api ay dapat magbunga 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 pagbabago sa isang package, mali ang pagkakaayos ng tree. Maaaring masyadong malawak ang mga boundary, o nakopya sa bawat child ang panuntunang dapat nasa root. Direktang tinutukoy ng dox ang solusyon: ilagay ang malalawak na panuntunan sa parent docs, at ang mga partikular na detalye sa child docs. Ang mga duplicated rule ang dahilan kung bakit nire-rewrite ng isang karaniwang pass ang lahat. Kung talagang pareho ang mga panuntunang nalalapat sa magkakahiwalay na repository, ibang problema iyon, at mas angkop na tool ang pagbabahagi ng agent skills sa magkakahiwalay na repository.

Suriin ang diff gaya ng code

Madaling aprubahan ang diff ng nabuong documentation nang hindi ito binabasa. Dahil dito, maaaring ma-release ang maling file. Basahin ito nang may parehong pag-iingat na ginagamit mo sa nabuong code, at hanapin ang apat na bagay na ito.

• isang command na unang binanggit ng file, na dapat mong patakbuhin mismo bago ang merge. Ang mga inimbentong build instruction ang pinakakaraniwang problema.
• isang binurang line na naglalaman ng layunin. Madaling magdagdag. Sa deletion nagaganap ang pagkawala ng mahalagang impormasyon.
• isang absolute path, hostname, internal URL, o anumang mukhang credential
• isang inventory entry para sa bagay na wala na, na mabilis na malulutas ng ls

Pagkatapos, tingnan ang laki gamit ang wc -l AGENTS.md. Kapag lumampas sa two hundred lines ang root file, senyales ito na dapat itong hatiin. Ang buong halaga ng chain ay nakasalalay sa pagbasa ng agent sa maliit na bahaging kailangan nito, sa halip na sa buong file.

Kapag may masira

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

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

Lubusang binabalewala ng agent ang file. Suriin kung aling filename ang aktuwal na binabasa ng 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 lamang ang source, sa halip na dalawang dokumentong unti-unting magkakaiba. Kung tama na ang filename ngunit nilalaktawan pa rin ang mga rule, patakbuhin ang diagnosis para sa kung bakit binabalewala ng coding agent ang iyong mga instruction bago muling isulat ang dokumento.

Lumaki ang tree ng mga child na walang nag-index. Ikumpara ang output ng find . -name AGENTS.md sa mga entry ng index sa parent documents. Ang child na hindi binabanggit ng anumang index ay child na madaling malampasan ng agent.

Kapag sobra ang generator

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

Sulit gamitin ang dox kapag may mga boundary ang repository na walang sinumang taong lubos na kabisado: maraming package na may magkakaibang rule, o mga contributor na dumarating nang walang sapat na background. Hindi ang generated text ang halaga nito. Ang mahalaga, nagiging bagay ang documentation na maaaring maging dahilan para ma-fail ang isang pull request. Iyon lang ang dahilan kung bakit nananatiling updated ang anumang file sa 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 walang package at release ang repository. I-copy 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 ayon sa petsa ng pagsulat, at banggitin ito sa commit message para matukoy mo sa hinaharap kung aling bersyon ng mga panuntunan ang ginamit sa pagbuo ng iyong tree.

Paano ko mapipigilan na mabura ng regeneration ang mga panuntunang mano-mano kong isinulat?

Paghiwalayin ang intent at inventory. Ilagay ang matibay na reasoning sa hiwalay na document, 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 sa origin/main gamit ang sed, paghambingin ang dalawa gamit ang diff, at i-fail ang build kapag may anumang pagkakaiba. Isang tao ang mag-a-approve o magre-revert ng pagbabago, sa halip na hindi ito mapansin sa loob ng malaking diff.

Gaano kadalas ko dapat i-regenerate ang AGENTS.md?

Sa pull request na nagiging sanhi ng pagkakamali nito. Dapat nasa iisang diff ang structural change at ang dokumentasyon nito, dahil iyon lang ang sandaling may sapat na context ang isang tao para masuri 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 mag-commit sa main.

Dapat bang nasa root AGENTS.md ang build commands, o sa child?

Ilagay ang mga ito sa pinakamalapit na document na nagmamay-ari sa mga ito. Nasa root ang mga panuntunang saklaw ang buong repository at ang child index. Ang command na para sa isang package lang ay dapat nasa AGENTS.md ng package na iyon. Niresolba ng dox ang mga conflict batay sa layo: ang mas malapit na document ang kumokontrol sa mga lokal na detalye, at hindi maaaring pahinain ng child ang panuntunan 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 pagkatapos mo itong mapansin. Sulit ang dox kapag maraming boundary ang repository na may magkakaibang panuntunan, o kapag may mga contributor na kulang sa background, dahil ang chain ng mga document ang gumagawa ng trabahong walang iisang tao ang gumagawa.