Jinsi ya kupanga AGENTS.md katika monorepo

Maana ya AGENTS.md iliyopangwa ndani ya monorepo

AGENTS.md iliyopangwa ndani ya monorepo inamaanisha kuwa na faili moja dogo kwenye mzizi wa repository na faili lingine moja ndani ya kila saraka ya huduma. Faili la mzizi lina sheria chache zinazotumika kila mahali, pamoja na ramani ya mahali ambapo faili nyingine zilipo. Kila faili ya huduma ina amri na kanuni za saraka hiyo pekee. Wakala (agent) anayehariri services/worker/queue.py basi husoma faili la mzizi na faili la mfanyakazi, na hatumii muktadha wowote kwenye front end ambayo hataigusa kamwe.

Hakuna cha kusakinisha. AGENTS.md ni kanuni, na mradi wa upstream unasema hivyo waziwazi:

AGENTS.md ni Markdown ya kawaida tu. Tumia vichwa vyovyote unavyopenda; wakala huchanganua tu maandishi unayotoa.

Ndiyo maana mbinu hii inafaa kujifunza vizuri. Umbizo halitabadilika chini yako. Kinachovunjika ni uwekaji na matengenezo, na yote hayo ni jukumu lako.

Kwa nini faili moja kubwa la AGENTS.md kwenye root huacha kufanya kazi?

Faili moja la AGENTS.md lenye mistari 600 kwenye root ya repository inayoshikilia web app, background worker, na directory ya Terraform hushindwa kufanya kazi kwa njia nne tofauti.

Linapitwa na wakati, kwa sababu hakuna anayelimiliki. Mhandisi anayebadilisha jina la script ya majaribio kwenye apps/web anahariri faili zilizo chini ya apps/web. Faili la AGENTS.md la kwenye root halimo kwenye diff hiyo, kwa hivyo hakuna mkaguzi anayeona kutokubaliana huko. Baada ya wiki sita, faili hilo linaelezea hatua ya build ambayo haipo tena, na mtu aliyelivunja amesahau mabadiliko hayo.

Linapoteza context kwenye kila kazi. Faili hizi hupakiwa mwanzoni mwa session, kabla ya agent kujua utauliza nini. Nyaraka za Claude Code zinaweka kikomo: "lenga chini ya mistari 200 kwa kila faili la CLAUDE.md. Faili ndefu hutumia context nyingi na kupunguza ufanisi." Codex huacha kuunganisha faili za maelekezo pindi ukubwa wake unapofikia 32 KiB, ambayo ni project_doc_max_bytes chaguo-msingi. Faili la kwenye root linaloelezea huduma nne hutumia bajeti hiyo kwa huduma tatu kati ya hizo kwa kila kazi unayofanya.

Maelekezo huanza kupingana. Directory ya web inataka pnpm test. Worker inataka pytest -q. Yakiwa yameandikwa kwenye faili moja, kila sheria ni sahihi kwa wakati fulani tu, kwa hivyo agent analazimika kukisia ni ipi inayotumika. Nyaraka za Claude Code zinaelezea matokeo yake: "ikiwa sheria mbili zinapingana, Claude anaweza kuchagua moja kiholela." Faili la kila directory huondoa kukisia huko, kwa sababu ni sheria moja tu kati ya mbili inayokuwa kwenye context. Wakati sheria uliyohakikisha umeandika kwa uwazi inapupuuzwa, kupitia sababu zinazofanya maelekezo kutotekelezwa ni bora kuliko kuandika upya maneno hayo kwa mara ya nne.

Linajaa ukweli ambao agent anaweza kuusoma kutoka kwenye code. Mti wa directory, orodha ya dependencies, muhtasari wa kile kila package inachofanya. Ukaguzi wa /doctor wa Claude Code upo ili kuondoa mambo haya hasa. "Hukata maudhui ambayo Claude anaweza kuyapata kutoka kwenye codebase, kama vile mpangilio wa directory, orodha za dependencies, na muhtasari wa usanifu" na huweka "changamoto, mantiki, na miongozo inayotofautiana na chaguo-msingi za zana." Sentensi hiyo ndiyo kipimo bora zaidi ninachokijua cha kuamua kama mstari unastahili kuwemo kwenye faili hilo au la.

Je, wakala husoma faili la root, au lile la karibu zaidi pekee?

Hapa ndipo watu wengi wanapokosea kuelewa modeli hii, kwa hivyo inafaa kunukuu mwongozo wa msanidi badala ya kuufafanua:

Weka faili lingine la AGENTS.md ndani ya kila kifurushi. Mawakala husoma kiotomatiki faili la karibu zaidi katika mti wa saraka, kwa hivyo lile la karibu zaidi huchukua kipaumbele na kila mradi mdogo unaweza kusafirisha maelekezo maalum.

Na kuhusu migogoro:

Faili la AGENTS.md lililo karibu zaidi na faili linalohaririwa ndilo linaloshinda; maelekezo ya moja kwa moja ya mtumiaji kwenye chat huzidi kila kitu kingine.

"Huchukua kipaumbele" husomwa na watu wengi kama "faili la root hupuuzwa". Si kweli. Katika zana zinazotekeleza mwongozo huu, kila faili kwenye njia kuanzia root ya hazina (repository) hadi saraka ya kazi husomwa na kuunganishwa pamoja. Faili la karibu zaidi hushinda tu pale ambapo faili mbili zinasema mambo tofauti kuhusu mada moja.

Codex iko wazi kuhusu utaratibu huu: "Codex huunganisha faili kutoka root kwenda chini, ikiziunganisha kwa mistari mitupu. Faili zilizo karibu na saraka yako ya sasa huzidi mwongozo wa awali." Claude Code hufuata njia hiyo hiyo kwa jina lake la faili. Faili zilizo kwenye daraja la saraka juu ya saraka ya kazi "hupakiwa kikamilifu wakati wa kuanzishwa", na "Faili zote zilizogunduliwa huunganishwa kwenye muktadha badala ya kuzidiana." Saraka zilizo chini ya saraka ya kazi hufanya kazi tofauti: Claude Code hupakia faili hizo inapohitajika, "wakati Claude anaposoma faili katika saraka hizo."

Matokeo mawili ya kivitendo yanajitokeza. Faili la root ni kiambishi awali (prefix) kwenye kila kikao ndani ya hazina, kwa hivyo chukulia kila mstari uliopo hapo kama mstari unaolipia mara mia moja kwa wiki. Faili la kila saraka haligharimu chochote wakati wakala anapofanya kazi mahali pengine, jambo linalomaanisha kuwa maelezo ya kina ni ya bei nafuu huko na yanapaswa kuwekwa huko.

Tabia hii ilithibitishwa dhidi ya nyaraka za Codex na Claude Code mnamo Agosti 2026. Zana hutekeleza mwongozo huu kwa njia tofauti kidogo na hubadilika, kwa hivyo thibitisha sheria za upakiaji kwa wakala wowote ambao timu yako inautumia.

Mpangilio uliothibitiwa wa hazina yenye huduma tatu

repo/
  AGENTS.md                   rules true everywhere, plus the map
  apps/web/AGENTS.md          TypeScript client, Vite, Vitest
  services/worker/AGENTS.md   Python queue consumer, pytest
  infra/AGENTS.md             Terraform and the deploy scripts

Faili la mzizi (root file) ni fupi kwa makusudi. Linaelekeza mahali pa kutazama, na linabeba tu sheria zinazotumika katika kila saraka.

# AGENTS.md

This is a monorepo. Each top-level directory ships its own AGENTS.md.
Read this file and the AGENTS.md nearest the code you are editing
before you change anything.

- `apps/web` browser client
- `services/worker` queue consumer
- `infra` Terraform and deploy scripts

## Rules for the whole repository

- The package manager is `pnpm`. `npm install` writes a second lockfile
  that CI ignores, so the install you tested is not the install that ships.
- Any `generated/` directory is build output. Edit the schema in
  `schemas/` and run `pnpm codegen` instead.
- `.env.local` holds real credentials. Do not read it and do not print it.
- If you change code in a directory, update that directory's AGENTS.md
  in the same commit.

Faili la kila saraka (per-directory file) ndipo maelezo yanapowekwa, na linaweza kuwa na urefu wowote kulingana na mahitaji ya saraka hiyo.

# apps/web

Browser client. Vite and React, TypeScript with `strict` on.

## Commands

- `pnpm dev` serves on port 5173.
- `pnpm test` runs Vitest once and exits.
- `pnpm typecheck` runs `tsc --noEmit`.

## Conventions

- One component per file under `src/components/`.
- All HTTP goes through `src/api/client.ts`. Do not call `fetch` directly,
  because the client attaches the auth header and retries on 429.

## Traps

- `pnpm build` does not type check. Vite strips the types instead of
  checking them, so a broken type still produces a green build.
  Run `pnpm typecheck` as a separate step.

Faili la mfanyakazi (worker file) lina umbo sawa lakini lina maudhui tofauti: amri ya usakinishaji, pytest -q, sababu inayomfanya mtumiaji lazima abaki kuwa idempotent, na uhamiaji (migration) ambao lazima uendeshwe kabla ya majaribio kupita. Faili la miundombinu (infra file) ndipo unapoandika sheria zinazozuia wakala (agent) kusababisha uharibifu. Usiwahi kuendesha terraform apply. Endesha terraform plan na uishie hapo, kisha taja backend ya hali (state backend) ambayo tayari imesanidiwa ili wakala asijaribu kuanzisha mpya.

Angalia kile ambacho hakipo katika faili hizi zote: maelezo ya kazi ya kila huduma. Hilo ni jukumu la binadamu. Upstream inachora mstari huo huo, ikisema "faili za README.md ni kwa ajili ya binadamu: kuanza haraka, maelezo ya mradi, na miongozo ya uchangiaji", wakati AGENTS.md inabeba "muktadha wa ziada, wakati mwingine wa kina, ambao mawakala wa usimbaji wanahitaji: hatua za ujenzi, majaribio, na mikataba." mgawanyo kati ya AGENTS.md na README inayolenga binadamu unapitia sentensi kwa sentensi kupitia mpaka huo, na DESIGN.md inayorekodi kwa nini msimbo umeumbwa jinsi ulivyo inashughulikia faili la tatu, lile linaloelezea maamuzi badala ya amri.

Nani anayesasisha faili wakati msimbo unapobadilika?

Kuna kanuni moja, na inawekwa kwenye faili ya root: yeyote anayebadilisha msimbo katika saraka fulani anapaswa kusasisha AGENTS.md ya saraka hiyo katika commit ileile.

Hii inafanya kazi kwa sababu ya kiufundi, si ya kiutamaduni. Faili ya kila saraka inapatikana katika diff ileile ya msimbo, kwa hivyo mkaguzi wa pull request huona vyote viwili kwa wakati mmoja. Faili ya root ni ya kila mtu, jambo linalomaanisha kuwa si ya mtu yeyote, na kamwe haipo kwenye diff ambayo mtu yeyote anaisoma.

Imarisha kanuni hii kwa kuweka ukaguzi kwenye pull request. Inatafuta AGENTS.md iliyo karibu zaidi juu ya kila faili iliyobadilishwa, kisha inatoa taarifa wakati faili hiyo haijaguswa.

#!/usr/bin/env bash
# Warn when code changed but the nearest AGENTS.md above it did not.
changed=$(git diff --name-only origin/main...HEAD)

nearest_doc() {
  d=$(dirname "$1")
  while [ "$d" != "." ]; do
    if [ -f "$d/AGENTS.md" ]; then echo "$d/AGENTS.md"; return; fi
    d=$(dirname "$d")
  done
  echo "AGENTS.md"
}

printf '%s\n' "$changed" | while read -r f; do
  [ -n "$f" ] || continue
  case "$f" in AGENTS.md|*/AGENTS.md) continue ;; esac
  doc=$(nearest_doc "$f")
  printf '%s\n' "$changed" | grep -Fqx "$doc" && continue
  echo "note: $f changed but $doc was not updated"
done

Kwenye branch iliyofanyia kazi upya API client bila kugusa nyaraka, matokeo yanaonekana hivi:

note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updated

Iweke kama onyo badala ya kuzuia kabisa. Kizuizi kikali huwafundisha watu kuongeza mstari mtupu kwenye faili ili CI ipitishe, na faili iliyohaririwa ili kuridhisha roboti haina thamani yoyote. Onyo humpa mkaguzi swali la kuuliza, ambalo ndilo sehemu inayofanya kazi kweli.

Ninawezaje kubaini AGENTS.md iliyopitwa na wakati?

Kuna ukaguzi mbili unazoweza kufanya leo, na dalili moja utakayoiona ndani ya session.

Linganisha umri wa kila faili na umri wa code inayoelezea. %cs huchapisha tarehe ya commit kama YYYY-MM-DD.

for f in $(git ls-files '*AGENTS.md'); do
  d=$(dirname "$f")
  printf '%s  doc:%s  code:%s\n' "$f" \
    "$(git log -1 --format=%cs -- "$f")" \
    "$(git log -1 --format=%cs -- "$d")"
done

apps/web/AGENTS.md          doc:2026-02-11  code:2026-08-07
services/worker/AGENTS.md   doc:2026-07-29  code:2026-08-09
infra/AGENTS.md             doc:2026-08-01  code:2026-08-01

Tarehe ya hati iliyo nyuma kwa miezi sita kuliko tarehe ya code haithibitishi kuwa faili hilo si sahihi. Inakuambia ni faili lipi la kusoma kwanza, na hilo ndilo unalohitaji kutoka kwa ukaguzi unaochukua sekunde moja.

Tafuta njia (paths) ambazo hazipo tena. Nyaraka huharibika kwa njia moja mahususi: zinaendelea kuelezea code iliyofutwa. Kila njia katika faili hizi imeandikwa ndani ya backticks, kwa hivyo ni rahisi kuzitoa na kuzijaribu.

grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
  [ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
done

Soma matokeo badala ya kuunganisha hii kwenye CI. Pia huashiria globs kama src/**/*.ts na URL yoyote uliyonukuu, kwa sababu zote zina slash na hakuna hata moja iliyo faili kwenye diski.

Dalili ndani ya session. Agent husoma faili, hujaribu kufungua src/api/client.ts kwa sababu faili limemwambia afanye hivyo, na zana hiyo inarudisha:

No such file or directory

Kwa hivyo hufanya jambo la busara na kuandika wrapper yake ya fetch. Hiyo ndiyo gharama halisi ya faili lililopitwa na wakati. Agent haipuuzi nyaraka zako. Inafuata nyaraka, inafika kwenye njia iliyofutwa miezi mitatu iliyopita, na kujenga upya code ambayo tayari unayo. Ujuzi kama Ponytail, ambayo humzuia agent kwenye mabadiliko madogo zaidi yanayofanya kazi, hufanya silika hiyo ya kujenga upya kuwa nadra, lakini haiwezi kupata kisaidizi ambacho faili lako kilikielekeza mahali pasipo sahihi.

Je, Claude Code inasoma faili za AGENTS.md?

Hapana, na ni muhimu kusema hili kwa uwazi kwa sababu mpangilio wa ndani (nested layout) unategemea hilo. Kufikia Agosti 2026, nyaraka zinasema: "Claude Code inasoma CLAUDE.md, si AGENTS.md." Muundo huu bado unafanya kazi, unahitaji tu CLAUDE.md kando ya kila AGENTS.md.

Njia ya import ni sahihi pale unapotaka mistari mahususi ya zana fulani juu ya ile inayoshirikiwa. Iweke hii kwenye services/worker/CLAUDE.md:

@AGENTS.md

## Claude Code

Use plan mode for changes under `services/worker/migrations/`.

Njia ya symlink ni sahihi pale ambapo hakuna kitu mahususi cha zana ya kuongeza.

git ls-files '*AGENTS.md' | while read -r f; do
  ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.md

ln haitoi matokeo yoyote ikifanikiwa, kwa hivyo kagua orodha: apps/web/CLAUDE.md -> AGENTS.md. Kisha anzisha session na uendeshe /context, ambapo faili zilizopakiwa zitaonekana chini ya Memory files. Kwenye Windows, symlink inahitaji haki za Administrator au Developer Mode, kwa hivyo tumia @AGENTS.md import huko.

Mtego mmoja unahusiana na hili. Baada ya /compact, faili ya mzizi (root file) inasomwa upya kutoka kwenye diski, lakini faili zilizomo ndani ya saraka ndogo (subdirectories) hazirejeshwi. Zinarudi wakati mwingine ambapo wakala (agent) anasoma faili katika saraka hiyo. Ikiwa sheria ya kila saraka inaonekana kuacha kufanya kazi katikati ya session ndefu, hiyo ndiyo sababu, na kugusa faili yoyote katika saraka hiyo huirejesha.

Hii inatofautianaje na kumbukumbu ya wakala (agent memory), au ujuzi (skill)?

Mbinu hizi zinaonekana kufanana lakini zinashindwa kufanya kazi kwa njia tofauti kabisa, hivyo ni muhimu kuwa sahihi kuhusu ni ipi unayohitaji.

AGENTS.md huandikwa na wewe, huwekwa kwenye git, hupitiwa katika pull request, na inafanana kwa kila mtu anayekopi (clone) hazina (repository) hiyo. Kumbukumbu ya wakala huandikwa na wakala, huhifadhiwa nje ya hazina, na ni ya ndani kwa mashine moja tu. Nyaraka za Claude Code huchora mstari huo huo: CLAUDE.md hushikilia "Maelekezo na sheria" unazoandika wewe, kumbukumbu ya kiotomatiki hushikilia "Mafunzo na mifumo" ambayo Claude huandika, na saraka ya kumbukumbu haishirikiwi kati ya mashine mbalimbali. Jaribio ni rahisi. Ikiwa ukweli lazima uwe wa kweli kwa mfanyakazi mwenzako kwenye nakala mpya, hauwezi kuwepo kwenye kumbukumbu. Jinsi kumbukumbu ya wakala inavyodumu kati ya vipindi inashughulikia nusu hiyo ya picha.

Ujuzi (skill) ni kitu cha tatu. AGENTS.md ni muktadha unaopakiwa kila kipindi; ujuzi ni utaratibu unaopakiwa unapohitajika. Nyaraka za Claude Code hutoa sheria inayoweza kutumika: "Ikiwa ingizo ni utaratibu wa hatua nyingi au ni muhimu kwa sehemu moja tu ya codebase, lisongeze kwenye ujuzi au sheria inayohusu njia (path-scoped rule) badala yake." Nusu ya pili ya sentensi hiyo ndiyo hasa inayotatuliwa na AGENTS.md iliyowekwa ndani ya nyingine (nested). Nusu ya kwanza ndiyo inayokusudiwa kwa ujuzi wa wakala, na wakati utaratibu uleule unapohitajika katika zaidi ya hazina moja, shiriki ujuzi huo kwenye hazina mbalimbali badala ya kubandika aya zilezile kwenye faili kumi tofauti za AGENTS.md.

Upstream inabainisha kuwa "wakati wa kuandika, hazina kuu ya OpenAI ina faili 88 za AGENTS.md". Nambari hiyo ndiyo hoja nzima. Hazina kubwa haihitaji faili kubwa zaidi. Inahitaji faili nyingi ndogo, kila moja ikiwa karibu na msimbo (code) inaouelezea, kila moja ikimilikiwa na yeyote aliyebadilisha msimbo huo mara ya mwisho.

FAQ

Je, AGENTS.md iliyopo ndani ya folda nyingine inachukua nafasi ya faili ya mzizi au inaongezea?

Inaongezea. Upstream inasema "ile iliyo karibu zaidi ndiyo inayopewa kipaumbele", jambo linaloelezea kinachotokea wakati wa mgongano, si kile kinachopakiwa. Codex "huunganisha faili kutoka kwenye mzizi kwenda chini, ikizitenganisha kwa mistari mitupu", na Claude Code huunganisha kila faili inayoipata inapopitia folda kuanzia kwenye working directory badala ya kuzifuta zile za awali. Faili iliyo karibu zaidi hushinda pale tu ambapo faili mbili zinatoa maelekezo tofauti kuhusu mada moja. Andika sheria za pamoja kwenye mzizi mara moja, na usizirudie katika kila folda.

Faili ya mzizi ya AGENTS.md inapaswa kuwa na ukubwa gani?

Iwe ndogo kiasi kwamba hutaona shida ikiwekwa juu ya kila ombi unalofanya kwenye hifadhi hiyo, kwa sababu ndivyo inavyotokea. Nyaraka za Claude Code zinapendekeza kulenga chini ya mistari 200 kwa kila faili na kuonya kuwa faili ndefu "hupunguza utiifu". Codex huacha kuunganisha faili za maelekezo zikifikia 32 KiB kwa jumla kwa chaguo-msingi. Ikiwa faili yako ya mzizi inaelezea huduma nne, sehemu kubwa yake ni mzigo usio na kazi kwa kazi yoyote mahususi. Hamisha maelezo hayo kwenye faili za kila folda na uache ramani nyuma.

Ninawezaje kuzuia faili hizi kupitwa na wakati?

Weka sheria moja kwenye faili ya mzizi: yeyote anayebadilisha msimbo kwenye folda anapaswa kusasisha AGENTS.md ya folda hiyo katika commit ileile. Kuweka faili karibu na msimbo ndiko kunakofanya sheria hiyo kuzingatiwa, kwa sababu mabadiliko hayo huonekana kwenye pull request diff ileile ambayo binadamu anaisoma. Ongeza onyo la CI linalounganisha kila njia iliyobadilishwa na AGENTS.md iliyo karibu zaidi juu yake, na mara kwa mara linganisha git log -1 --format=%cs kwenye kila faili dhidi ya amri ileile inayotekelezwa kwenye folda inayoelezewa.

Je, Claude Code inasoma faili za AGENTS.md?

Hapana. Kufikia Agosti 2026, nyaraka zinasema "Claude Code inasoma CLAUDE.md, si AGENTS.md." Unda CLAUDE.md katika folda ileile ukiwa na @AGENTS.md kwenye mstari wa kwanza, ambayo hupakia faili ya pamoja na kukuwezesha kuongeza maelekezo mahususi ya Claude hapo chini. Symlink iliyoundwa kwa ln -s AGENTS.md CLAUDE.md hufanya kazi wakati hakuna kitu cha ziada cha kuongeza, ingawa kwenye Windows inahitaji haki za Administrator au Developer Mode. Tekeleza /context katika kikao na uthibitishe kuwa faili inaonekana chini ya Memory files.

Ninaweka wapi sheria inayohitajika mara chache tu?

Si kwenye AGENTS.md. Faili hiyo hupakiwa katika kila kikao, kwa hivyo kila mstari ndani yake hushindania umakini na ombi uliloliandika. Utaratibu wenye hatua kadhaa unaohitajika mara chache unapaswa kuwa kwenye skill, ambayo hupakiwa inapohitajika. Sheria inayotumika kwenye folda moja inapaswa kuwa kwenye AGENTS.md ya folda hiyo. Ukweli ambao wakala anaweza kuusoma moja kwa moja kutoka kwenye msimbo, kama vile mti wa folda au orodha ya dependency, haupaswi kuwa kwenye yoyote kati ya hizo.