Jinsi ya kusasisha AGENTS.md kiotomatiki kwa kutumia dox

Kwa nini faili lako la AGENTS.md linakuwa si sahihi baada ya wiki tatu

Faili la AGENTS.md hupitwa na wakati kwa sababu hakuna kinacholiunganisha na msimbo (code). Unaliandika mara moja, kwa mkono, siku ambayo hazina (repository) ina muundo fulani. Kisha kimbiza-majaribio (test runner) kinabadilika, kifurushi (package) kinapewa jina jipya, huduma inafutwa, na faili linaendelea kuelezea hali ya mwezi Juni. Hakuna kinachofeli, kwa sababu hakuna hatua ya ujenzi (build step) inayolisoma.

Wakala (agent) huliona na kuliini. Hilo ndilo sehemu inayokugharimu. Hazina isiyo na AGENTS.md humfanya wakala wa uandishi wa msimbo aangalie kwanza kabla ya kuchukua hatua. Hazina yenye AGENTS.md isiyo sahihi humfanya aache kuangalia, kwa sababu tayari anayo majibu. Anatekeleza amri iliyotajwa kwenye faili lako, shell inajibu Missing script: "test", na sasa wakala anaanza kubahatisha. Mara nyingi huhariri package.json ili kuongeza hati (script) ambayo nyaraka zako ziliahidi. Faili lililopitwa na wakati halikufeli kimya kimya. Lilisababisha uhariri ambao hukutaka.

dox ni jibu moja kwa hilo. Ni seti ya kanuni, zilizoandikwa kwa ajili ya wakala, zinazofanya usasishaji wa nyaraka kuwa sehemu ya kukamilisha kazi, ili faili libadilike katika commit moja na msimbo uliolifanya liwe si sahihi.

dox ni nini, na si nini

dox ni faili moja la Markdown. Hifadhi hii ni agent0ai/dox, ina leseni ya MIT, na kufikia tarehe 11 Agosti 2026 mradi mzima ni AGENTS.md moja ya baiti 3906, README, LICENSE na picha mbili. Hakuna kifurushi cha kusakinisha na hakuna runtime.

Hili ni muhimu, kwa sababu neno generator linapendekeza programu inayochambua (parse) msimbo wako. Hakuna kinachochambua msimbo wako. dox ni mkataba ambao wakala wako wa uandishi wa msimbo (coding agent) huusoma: wakala wako ndiye generator, na dox ni seti ya maelekezo inayomwambia wakati wa kusoma nyaraka, wakati wa kuziandika upya, na umbo ambalo kila waraka unapaswa kuwa nao.

Faili hili lina sehemu kumi na mbili kati ya hizo ndizo hufanya kazi. "Read Before Editing" humwambia wakala atembee kutoka mzizi wa hifadhi (repository root) hadi kila njia (path) anayopanga kuigusa, na asome kila AGENTS.md kwenye kila njia, katika kipindi cha sasa, bila kutegemea kumbukumbu. "Update After Editing" humwambia kuwa kila mabadiliko ya maana yanahitaji hatua ya DOX, ikimaanisha hatua ya kusasisha nyaraka inayotekelezwa kabla ya kazi kuhesabiwa kuwa imekamilika. Hatua hiyo husasisha waraka husika wa karibu zaidi wakati madhumuni, muundo, mtiririko wa kazi, ruhusa au mapendeleo ya mtumiaji yamebadilika.

Sehemu nyingine ni za umbo. AGENTS.md ya mtoto (child) ina mpangilio wa kawaida wa sehemu: Madhumuni, Umiliki, Mikataba ya Ndani, Mwongozo wa Kazi, Uthibitishaji, na Faharisi ya DOX ya Mtoto. Faili la mzizi (root file) lina sheria za mradi mzima pamoja na Faharisi ya DOX ya Mtoto ya ngazi ya juu, ambayo ndiyo njia ambayo wakala hugundua nyaraka za watoto. "Closeout" ni orodha ya ukaguzi ambayo wakala huiendesha mwishoni mwa kazi: kagua upya njia zilizobadilishwa dhidi ya mnyororo, sasisha nyaraka husika za karibu zaidi, onyesha upya kila faharisi iliyoathiriwa, futa migongano, endesha uthibitishaji uliopo, na ripoti ni nyaraka zipi alizoziacha bila kuzigusa kwa makusudi.

Funga dox kwenye commit moja, si kwenye main

Hazina hii haina tags wala releases, kwa hivyo hakuna namba ya version ya kufunga. Funga commit badala yake. AGENTS.md ya sasa ni commit f34ec7ad1055d3393887e5a2670e8cb7320c9165, ya tarehe 1 Agosti 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

wc -c inapaswa kuchapisha 3906. Namba tofauti inamaanisha hukupata faili ambalo mwongozo huu unaelezea, kwa hivyo lisome kabla ya kuliwekea imani. Ukikosea kuandika commit hash, -f inafanya curl kusimama na curl: (22) The requested URL returned error: 404 na kutoandika maudhui yoyote, na wc -c kisha inachapisha 0. Faili lililokatwa ni mbaya zaidi kuliko kutokuwa na faili, kwa sababu wakala hufuata nusu ya mkataba bila kujua.

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

cp hiyo ni kwa ajili ya hazina ambayo haina AGENTS.md bado. Ikiwa tayari unayo, usiifute. Weka sehemu za dox juu ya maudhui yako yaliyopo, weka sheria zako chini, na usome matokeo mara moja kutoka juu hadi chini. Hati mbili zinazopingana huzalisha wakala anayefuata mstari wowote aliouona mwisho.

Kisha mwulize wakala wako, ndani ya hazina, kwa ajili ya hatua ya kwanza. README inatoa maneno kamili:

Initialize DOX tree for this project now.

Inatengeneza faili za AGENTS.md za watoto na faharasa zinazoyaelekeza. Hakiki kile ilichokifanya kabla ya kukiamini:

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

Kila faili katika pato hilo la find linapaswa kuonekana katika Faharasa ya DOX ya Mtoto mahali fulani juu yake. Hati ya mtoto ambayo hakuna faharasa inayoitaja ni ile ambayo wakala anaweza kuikosa, kwa sababu faharasa ndiyo njia anayotumia kupata hati ambazo hazipo moja kwa moja kwenye njia anayopitia.

Yale ambayo dox inaweza kuona, na yale ambayo haiwezi kujua

Wakala anayejenga mti wako husoma hazina (repository), kwa hivyo chochote kilicho kwenye hazina kinaweza kuingia kwenye orodha (inventory): mpangilio wa saraka, faili za manifest za vifurushi na lockfiles, hati (scripts) katika package.json au Makefile au pyproject.toml, faili za workflow za CI, Dockerfiles, entry points, na CODEOWNERS ikiwa unayo. Orodha iliyojengwa kutoka kwa vitu hivyo hujitunza yenyewe kikamilifu. Kifurushi kinapohamishwa, hatua inayofuata husogeza mstari unaokielezea.

Kila kitu kilicho hapa chini ni wajibu wako kukieleza, kwa sababu hakipo kwenye hazina ili kisomwe:

• kwa nini sheria fulani ipo, jambo ambalo humzuia wakala kuiondoa kama utata usio wa lazima
• ni ipi kati ya njia mbili zinazofanya kazi inayoungwa mkono, na ipi inasubiri kufutwa
• chochote kilicho nje ya hazina, kama vile mazingira ya staging au sababu ya dependency kufungiwa kwenye matoleo mawili yaliyopita
• kile unachopanga kufanya wiki ijayo, ambacho ndicho tofauti kati ya faili iliyo ya sasa na faili inayofaa

dox inajua hili kuhusu yenyewe. Sheria zake zenyewe zinasema Mwongozo wa Kazi (Work Guidance) lazima uakisi viwango vya sasa vya mradi au maelekezo ya mtumiaji, na kwamba ikiwa hakuna bado, unaacha sehemu hiyo ikiwa wazi. Uthibitishaji (Verification) lazima uakisi ukaguzi uliopo, kwa hivyo bila mfumo wa majaribio (test framework) kwenye hazina, sehemu hiyo hubaki wazi hadi pale utakapokuwepo. Faili iliyozalishwa inayobuni kiwango ni mbaya zaidi kuliko sehemu tupu, kwa sababu wakala ataanza kutekeleza uvumbuzi huo.

Zuia nia ya mwandishi kuondolewa kwenye orodha inayozalishwa kiotomatiki

Hii ndiyo hitilafu inayowafanya watu kukata tamaa na nyaraka zinazozalishwa kiotomatiki. Unaandika aya inayoeleza kuwa foleni ya kazi (jobs queue) lazima ibaki na mtumiaji mmoja (single consumer). Baada ya wiki tatu, mchakato wa kusasisha faili unafuta aya hiyo, ndani ya diff ya mistari arobaini inayobadilisha majina ya faili, na hakuna anayeigundua.

Kuna mbinu mbili, na unahitaji zote mbili.

Kwanza, hamisha nia ya kudumu kwenye faili tofauti. Maamuzi ya usanifu na sababu zake yanapaswa kuwa ndani ya DESIGN.md iliyoandikwa kwa ajili ya wakala, na maelezo yaliyokusudiwa watu yanapaswa kuwa mahali ambapo unatenganisha HUMAN.md kutoka AGENTS.md. AGENTS.md inabeba orodha na mikataba ya ndani, ambayo ndiyo sehemu inayopaswa kubadilika wakati msimbo (code) unapobadilika.

Pili, weka uzio kwenye nia inayopaswa kubaki ndani ya AGENTS.md. Ifunge kwa alama na uichukulie kama sehemu inayomilikiwa na binadamu:

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

Maoni ya Markdown hayajionyeshi kwenye ukurasa, na wakala bado anayasoma. Sasa fanya uhai wa kizuizi hicho uweze kukaguliwa, ili mchakato unaokifuta ushindwe kwa kelele. Tekeleza hili kwenye CI (continuous integration) katika kila 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 haitoi matokeo yoyote na inatoka (exit) kwa 0 wakati kizuizi hicho hakijaguswa. Matokeo yoyote yanamaanisha kuwa mchakato umeandika upya maandishi yanayomilikiwa na binadamu, hivyo mtu anapaswa kuidhinisha au kuirejesha hali ya awali. Ukaguzi huu unadumu bila mtu yeyote kulazimika kuukumbuka.

Fanya upya kwenye pull request, siyo kwa kutumia timer

Wakati mwafaka wa kusasisha hati ni wakati wa commit inayofanya hati hiyo kuwa na makosa. Weka hatua ya DOX kwenye pull request ileile ya mabadiliko ya kimuundo ili diff ibaki ndogo na inayosomeka.

Hundi ya kuzuia inayotekeleza hili:

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

Rekebisha njia (paths) kulingana na hazina (repository) yako. Faida yake ni kwamba inafeli kwenye branch, ambapo marekebisho ni rahisi, na inafeli kwa sababu ambayo mkaguzi anaweza kuifanyia kazi.

Ratiba ni njia mbadala, siyo utaratibu mkuu. Kazi ya kila wiki inakamata kile ambacho hakuna aliyeona kwenye branch: faili zilizohamishwa na rebase, kifurushi kilichofutwa kwenye merge, au hati inayotaja saraka (directory) ambayo haipo tena. Iendeshe kwenye seva ndogo, ileile unayoweza kutumia kuendesha wakala wa usimbaji kwenye VPS, na uifanye ifungue pull request badala ya kusukuma (push) kwenye 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

Maoni hayo ni kishika nafasi kwa makusudi. Kila wakala ana CLI (command line interface) yake na flag yake ya kutohitaji mwingiliano, na amri iliyonakiliwa kutoka kwenye ukurasa wa wavuti ambayo hailingani na toleo lako itafeli ndani ya cron ambapo hakuna anayeona kosa hilo. Ijazie na uendeshe hati hiyo kwa mkono mara moja kabla ya kuipangia ratiba. || exit 0 pia ni muhimu: git commit inatoka (exit) kwa kutoa thamani isiyo sifuri (non-zero) na nothing to commit, working tree clean wakati mti (tree) umeshakuwa wa sasa, na chini ya set -e hiyo ingetoa ripoti ya uendeshaji mzuri kama kufeli.

Kila hatua inagharimu token, kwa sababu "Soma Kabla ya Kuhariri" humfanya wakala asome mnyororo mzima kwenye kila kazi. Huo ndio mabadilishano, na inafaa kufuatilia ikiwa tayari unahesabu gharama za uendeshaji wa wakala wako.

Monorepos: mikataba mingi, index moja

Faili moja kuu la AGENTS.md katika hazina yenye vifurushi arobaini husababisha mabadiliko ya upya (regeneration diff) ambayo hakuna anayeyasoma, na hati ambayo mara nyingi haihusiani na kile ambacho wakala anafanya kwa sasa. Jibu la dox ni Child DOX Index: mzizi (root) huhifadhi sheria za hazina nzima na kuelekeza kwenye watoto wake, na kila mpaka thabiti (durable boundary) unamiliki faili lake. Jinsi ya kupanga mti huo, na ni zana zipi zinazoweza kusoma faili zilizowekwa ndani ya nyingine, imeelezewa katika faili za AGENTS.md zilizowekwa ndani kwa ajili ya monorepos.

Kile ambacho dox hubadilisha ni eneo la ukaguzi. Ombi la pull request linalogusa packages/api linapaswa kutoa mabadiliko ya hati ndani ya packages/api na si mahali pengine popote:

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

Ikiwa amri hiyo itaorodhesha faili sita kwa mabadiliko ya kifurushi kimoja, basi mti huo umekosewa. Aidha mipaka ni mipana mno, au sheria inayopaswa kuwa kwenye mzizi imenakiliwa kwenye kila mtoto. dox inataja suluhisho moja kwa moja: sheria pana huwekwa kwenye hati za mzazi, maelezo mahususi huwekwa kwenye hati za mtoto. Sheria zilizorudiwa ndizo zinazofanya marekebisho ya kawaida yaweze kubadilisha kila kitu. Ikiwa sheria zilezile zinatumika kikweli katika hazina tofauti, hilo ni tatizo tofauti, na kushiriki ujuzi wa wakala kati ya hazina ndiyo zana bora zaidi kwa ajili hiyo.

Kagua diff kama msimbo

Ni rahisi kuidhinisha diff ya nyaraka zilizozalishwa bila kuzisoma, na hivi ndivyo faili isiyo sahihi inavyoweza kusafirishwa. Isome kwa mashaka yale yale unayotumia kwenye msimbo uliotengenezwa, na utafute mambo manne.

• amri ambayo faili sasa inataja, ambayo unapaswa kuiendesha mwenyewe kabla ya kuunganisha (merge). Maelekezo ya ujenzi yaliyobuniwa ndiyo chanzo cha kawaida cha hitilafu.
• mstari uliofutwa uliokuwa na kusudi. Kuongeza vitu ni rahisi. Kufuta ndiko kunakopelekea upotevu.
• njia kamili (absolute path), hostname, URL ya ndani, au kitu chochote kinachofanana na kitambulisho (credential).
• ingizo la hesabu (inventory entry) kwa kitu ambacho hakipo tena, jambo ambalo ls hulitatua kwa sekunde moja.

Kisha angalia ukubwa kwa kutumia wc -l AGENTS.md. Faili ya root inayozidi mistari mia mbili ni ishara ya kuigawanya, kwa sababu thamani nzima ya mnyororo huu ni kwamba wakala husoma sehemu ndogo inayohusika badala ya kila kitu.

Inapoharibika

Pass imefuta block yako ya maelekezo. Ukaguzi wa diff hapo juu huchapisha mistari iliyoondolewa. Rejesha faili kutoka sehemu ya branch kwa kutumia git restore --source=origin/main AGENTS.md, kisha endesha pass hiyo tena kwa maelekezo finyu zaidi yanayotaja sehemu zinazoweza kuguswa.

Branch mbili zimezalishwa upya. Utapata CONFLICT (content): Merge conflict in AGENTS.md na alama za mgongano (conflict markers) <<<<<<< HEAD ndani ya faili. Usihariri alama hizo kwa mkono. Faili hili huzalishwa kiotomatiki, kwa hivyo suluhisho sahihi ni kufanya pass mpya juu ya mti uliounganishwa (merged tree).

Agent inapuuza faili kabisa. Angalia ni jina gani la faili ambalo zana yako inalisoma. Ikiwa inasoma faili tofauti, ielekeze kwenye maudhui yaleyale kwa kutumia ln -s AGENTS.md CLAUDE.md na ufanye commit ya symlink hiyo, ili uwe na chanzo kimoja badala ya hati mbili zinazotofautiana. Ikiwa jina la faili ni sahihi na sheria bado zinapukuzwa, fanya utambuzi wa kwa nini coding agents hupuuza maelekezo yako kabla ya kuandika upya hati hiyo.

Mti umekua na watoto ambao hakuna aliyewaorodhesha. Linganisha matokeo ya find . -name AGENTS.md na entries za index katika hati mama. Mtoto ambaye hajatajwa kwenye index yoyote ni mtoto ambaye agent anaweza kumpita bila kumgundua.

Wakati generator inapokuwa haihitajiki

Kifurushi kimoja, amri moja ya majaribio, na watu wawili wanaojua hazina (repository) hiyo: andika mistari ishirini kwa mkono. Faili ya AGENTS.md yenye mistari ishirini haichakai haraka kiasi cha kuhalalisha matumizi ya tree, index, CI check, na kazi ya kila wiki. Isome upya unapobadilisha build. Huo ndio gharama nzima ya matengenezo, na ni ndogo kuliko gharama ya mifumo inayozunguka faili hiyo.

dox inafaa kulipiwa wakati hazina ina mipaka ambayo hakuna mtu anayoweza kuikumbuka yote: vifurushi kadhaa vyenye sheria tofauti, au wachangiaji wanaokuja bila uzoefu wa awali. Thamani yake si maandishi yanayozalishwa. Thamani ni kwamba nyaraka hizo zinakuwa kitu ambacho pull request inaweza kufeli, ambayo ndiyo sababu pekee inayofanya faili yoyote ndani ya hazina kubaki ikiwa ya kisasa.

FAQ

Je, nahitaji kusakinisha kitu chochote ili kutumia dox?

Hapana. dox ni faili moja la Markdown, lenye leseni ya MIT, na kufikia tarehe 11 Agosti 2026 hazina (repository) hiyo haisambazi kifurushi chochote wala releases zozote. Unanakili yaliyomo kwenye faili lako la AGENTS.md la mradi wako na wakala wako wa uandishi wa msimbo (coding agent) atafuata kanuni kutoka hapo. Bandika (pin) commit uliyokili, f34ec7ad1055d3393887e5a2670e8cb7320c9165 wakati wa uandishi huu, na uitaje kwenye ujumbe wako wa commit ili uweze kujua baadaye ni toleo gani la kanuni ambalo mti (tree) wako ulijengwa chini yake.

Ninawezaje kuzuia uundaji upya (regeneration) usifute kanuni nilizoandika mwenyewe?

Tenganisha nia (intent) na orodha (inventory). Hoja za kudumu huwekwa kwenye hati tofauti, na chochote kinachopaswa kubaki ndani ya AGENTS.md huwekwa ndani ya kizuizi kilichotiwa alama. Kisha kagua kizuizi hicho katika CI: kitoe kutoka kwenye branch na kutoka origin/main kwa kutumia sed, linganisha viwili hivyo kwa kutumia diff, na usitishe ujenzi (build) iwapo kuna tofauti yoyote. Mtu ataidhinisha au kurejesha mabadiliko hayo, badala ya kupita bila kutambuliwa ndani ya diff kubwa.

Ni mara ngapi ninapaswa kuunda upya AGENTS.md?

Kwenye pull request inayofanya faili hilo kuwa si sahihi. Mabadiliko ya kimuundo na nyaraka zake ni lazima yawe kwenye diff moja, kwa sababu huo ndio wakati pekee mtu anapokuwa na muktadha wa kupitia yote mawili. Uendeshaji uliopangwa wa kila wiki ni chelezo kwa ajili ya mkengeuko (drift) uliopita bila kugundulika kwenye branch, na unapaswa kufungua pull request badala ya kufanya commit kwenye main.

Je, amri za ujenzi (build commands) zinapaswa kuwepo kwenye AGENTS.md ya mzizi (root) au kwenye mtoto (child)?

Kwenye hati iliyo karibu zaidi inayozimiliki. Kanuni za hazina nzima na faharasa ya watoto huishi kwenye mzizi. Amri inayotumika kwa kifurushi kimoja huishi kwenye AGENTS.md ya kifurushi hicho. dox hutatua migogoro kwa umbali: hati iliyo karibu zaidi hudhibiti maelezo ya ndani, na hakuna mtoto anayeweza kudhoofisha kanuni ya mzazi. Kunakili amri ileile kwenye kila mtoto ndiko kunakofanya uendeshaji wa kawaida uandike upya mti mzima.

Je, dox inafaa kwa hazina ndogo?

Kwa kawaida hapana. Kifurushi kimoja chenye amri moja ya majaribio na AGENTS.md ya mistari ishirini huchakaa polepole, na unaweza kurekebisha ndani ya dakika moja baada ya kugundua. dox inalipa gharama yake wakati hazina ina mipaka kadhaa yenye kanuni tofauti, au wachangiaji wasio na msingi wa kutosha, kwa sababu hapo mnyororo wa nyaraka hufanya kazi ambayo hakuna mtu mmoja anayefanya.