Jinsi ya kusasisha AGENTS.md kiotomatiki kwa kutumia dox

Kwa nini faili lako la AGENTS.md linakuwa na makosa 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) hubadilika, kifurushi (package) hubadilishwa jina, huduma (service) hufutwa, na faili hilo huendelea 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 (coding agent) atazame mazingira kabla ya kuchukua hatua. Hazina yenye AGENTS.md isiyo sahihi humfanya aache kutazama, kwa sababu tayari ana jibu. Huendesha amri iliyotajwa kwenye faili lako, shell hujibu Missing script: "test", na sasa wakala huanza 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, zilizoundwa kwa ajili ya wakala, zinazofanya usasishaji wa nyaraka kuwa sehemu ya kukamilisha kazi, ili faili libadilike katika commit moja na msimbo uliolifanya liwe na makosa.

Dox ni nini, na si nini

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

Hili ni muhimu, kwa sababu neno generator linapendekeza programu inayochanganua (parse) msimbo wako. Hakuna kinachochanganua 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 kuzibadilisha, na umbo ambalo kila hati inapaswa kuwa nalo.

Faili hili lina sehemu kumi na mbili kati ya hizo ndizo hufanya kazi. "Read Before Editing" humwambia wakala atembee kutoka mzizi wa hazina (repository root) hadi kila njia anayopanga kuigusa, na kusoma 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 hati inayomiliki husika 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 Kielezo cha DOX cha Mtoto. Faili la mzizi (root) lina sheria za mradi mzima pamoja na Kielezo cha DOX cha Mtoto cha ngazi ya juu, ambacho ndicho njia ambayo wakala hutumia kugundua hati za watoto. "Closeout" ni orodha ya ukaguzi ambayo wakala huiendesha mwishoni mwa kazi: kagua upya njia zilizobadilishwa dhidi ya mnyororo, sasisha hati za karibu zinazomiliki, onyesha upya kila kielezo kilichoathiriwa, futa utata, endesha uthibitishaji uliopo, na ripoti hati ambazo ameacha 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 hash ya commit, -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 mwenyewe chini, na usome matokeo mara moja kutoka juu hadi chini. Nyaraka mbili zinazopingana huzalisha wakala anayefuata mstari wowote aliouona mwisho.

Kisha muulize 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 anayopita.

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 ya mali (inventory): mpangilio wa saraka, manifest za vifurushi na lockfiles, hati (scripts) katika package.json au Makefile au pyproject.toml, faili za mtiririko wa kazi wa CI, Dockerfiles, entry points, na CODEOWNERS ikiwa unayo. Orodha iliyojengwa kutoka kwa hayo 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 utegemezi (dependency) kufungwa 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 maagizo 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) katika hazina, sehemu hiyo inabaki wazi hadi pale utakapokuwepo. Faili iliyozalishwa inayobuni kiwango ni mbaya zaidi kuliko sehemu iliyo wazi, kwa sababu wakala atatekeleza uvumbuzi huo.

Zuia nia iliyoandikwa kwa mkono isitoke 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). Wiki tatu baadaye, mchakato wa kiotomatiki unaandika upya faili na aya yako inapotea, ndani ya diff ya mistari arobaini ambayo mingi inabadilisha tu majina ya faili, na hakuna anayeigundua.

Kuna mifumo miwili, na unahitaji yote miwili.

Kwanza, hamisha nia ya kudumu kwenye faili tofauti. Maamuzi ya usanifu na sababu zake ni mali ya DESIGN.md iliyoandikwa kwa ajili ya wakala, na madokezo yaliyopo kwa ajili ya watu ni mali ya mahali ambapo unatenganisha HUMAN.md kutoka AGENTS.md. AGENTS.md basi inashikilia 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 ndani ya alama na uichukulie kizuizi hicho kama kinachomilikiwa 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 unaokiharibu ushindwe kwa kelele. Tekeleza hili katika CI (continuous integration) kwenye 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 haichapishi chochote na inatoka (exit) kwa 0 wakati kizuizi hicho hakijaguswa. Pato lolote linamaanisha kuwa mchakato umeandika upya maandishi yanayomilikiwa na binadamu, kwa 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 kipima muda

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. Thamani yake ni kwamba inashindwa kwenye branch, ambapo marekebisho ni rahisi, na inashindwa kwa sababu ambayo mkaguzi anaweza kuifanyia kazi.

Ratiba ni chelezo, 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 itashindwa 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 hutoka (exit) na thamani isiyo sifuri (non-zero) pamoja na nothing to commit, working tree clean wakati mti (tree) tayari umesasishwa, na chini ya set -e hiyo ingeripoti uendeshaji mzuri kama kosa.

Kila hatua inagharimu token, kwa sababu "Soma Kabla ya Kuhariri" humfanya wakala asome mnyororo mzima katika 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 (repository) yenye vifurushi arobaini huzalisha diff ya urejeshaji ambayo hakuna anayeisoma, na hati ambayo mara nyingi haihusiani na kile ambacho wakala (agent) 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 (boundary) imara humiliki faili lake lenyewe. Jinsi ya kupanga mti huo, na ni zana zipi zinazoweza kusoma faili zilizowekwa ndani ya nyingine, imeelezewa katika faili za AGENTS.md zilizowekwa ndani ya nyingine kwa ajili ya monorepos.

Kile ambacho dox hubadilisha ni eneo la ukaguzi. Ombi la pull request linalogusa packages/api linapaswa kuzalisha diff ya nyaraka 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 ilinakiliwa kwenye kila mtoto. dox inataja suluhisho moja kwa moja: sheria pana huwekwa kwenye nyaraka za mzazi, maelezo mahususi huwekwa kwenye nyaraka za mtoto. Sheria zilizorudiwa ndizo zinazofanya marekebisho ya kawaida yawe ya kila kitu. Ikiwa sheria zilezile zinatumika kikweli katika hazina tofauti, hilo ni tatizo tofauti, na kushiriki ujuzi wa wakala katika hazina mbalimbali 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 wewe mwenyewe kabla ya kuunganisha (merge). Maelekezo ya ujenzi (build instructions) yaliyobuniwa ndiyo chanzo cha kawaida cha hitilafu.
• mstari uliofutwa uliokuwa na nia fulani. Kuongeza vitu ni rahisi. Kufuta ndiko kunakopelekea upotevu wa taarifa.
• njia kamili (absolute path), hostname, URL ya ndani, au kitu chochote kinachofanana na kitambulisho (credential).
• ingizo la orodha (inventory entry) kwa kitu ambacho hakipo tena, jambo ambalo ls hutatua kwa sekunde moja.

Kisha kagua 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 (agent) husoma sehemu ndogo inayohusika badala ya kusoma kila kitu.

Inapoharibika

Pass imefuta block yako ya nia. 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 mahususi zaidi yanayotaja sehemu zinazoweza kuguswa.

Branches mbili zote zimezalishwa upya. Unapata CONFLICT (content): Merge conflict in AGENTS.md na alama za mgongano <<<<<<< 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.

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 moja kwa moja bila kumtambua.

Wakati generator inapokuwa haihitajiki

Kifurushi kimoja, amri moja ya majaribio, na watu wawili wanaofahamu hazina (repository) hiyo: andika mistari ishirini kwa mkono. Faili ya AGENTS.md yenye mistari ishirini haichakai haraka kiasi cha kuhalalisha mti (tree), index, ukaguzi wa CI, na kazi ya kila wiki. Isome upya unapobadilisha build. Hiyo ndiyo gharama nzima ya matengenezo, nayo ni ndogo kuliko gharama ya mfumo mzima unaoizunguka.

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

FAQ

Je, ninahitaji kusakinisha kitu chochote ili kutumia dox?

Hapana. dox ni faili moja ya Markdown, yenye leseni ya MIT, na kufikia tarehe 11 Agosti 2026 hazina (repository) hiyo haitoi package yoyote wala releases. Unanakili yaliyomo kwenye faili ya AGENTS.md ya mradi wako na wakala wako wa uandishi wa msimbo (coding agent) atafuata kanuni zilizomo humo. Funga (pin) commit uliyoinakili, f34ec7ad1055d3393887e5a2670e8cb7320c9165 wakati wa kuandika mwongozo huu, na uitaje kwenye ujumbe wako wa commit ili uweze kujua baadaye ni toleo gani la kanuni ambalo mti wako wa msimbo 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 kwenye CI: kitoe kutoka kwenye branch na kutoka origin/main kwa kutumia sed, linganisha viwili hivyo kwa kutumia diff, na usitishe build iwapo kuna tofauti yoyote. Mtu ataidhinisha au kubatilisha mabadiliko hayo, badala ya kupita bila kutambuliwa ndani ya diff kubwa.

Ni mara ngapi ninapaswa kuunda upya AGENTS.md?

Kwenye pull request inayofanya faili hiyo kuwa na makosa. Mabadiliko ya kimuundo na nyaraka zake yanapaswa kuwa kwenye diff moja, kwa sababu huo ndio wakati pekee mtu anapokuwa na muktadha wa kupitia yote mawili. Uendeshaji uliopangwa kila wiki ni njia ya kuhifadhi nakala kwa ajili ya mabadiliko yaliyopita bila kutambuliwa kwenye branch, na inapaswa kufungua pull request badala ya kufanya commit moja kwa moja kwenye main.

Je, amri za build zinapaswa kuwepo kwenye AGENTS.md ya mzizi (root) au kwenye faili ndogo (child)?

Kwenye hati iliyo karibu zaidi inayozimiliki. Kanuni za hazina nzima na faharasa ya watoto (child index) huwekwa kwenye mzizi. Amri inayotumika kwa package moja huwekwa kwenye AGENTS.md ya package hiyo. 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. Package moja yenye amri moja ya majaribio na AGENTS.md ya mistari ishirini huchakaa polepole, na unaweza kuirekebisha 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 anayeweza kuifanya.