Jinsi ya kupanga faili za AGENTS.md kwenye monorepo

Maana ya AGENTS.md iliyopangwa ndani ya monorepo

AGENTS.md iliyopangwa ndani ya monorepo inamaanisha faili moja dogo kwenye mzizi wa repository na faili lingine moja ndani ya kila saraka ya huduma. Faili la mzizi lina sheria chache ambazo ni kweli kila mahali, pamoja na ramani ya mahali ambapo faili nyingine zinapatikana. Kila faili la huduma lina amri na makubaliano ya saraka hiyo pekee. Wakala 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 makubaliano, na mradi wa upstream unasema hivyo waziwazi:

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

Hiyo ndiyo sababu mbinu hii inafaa kujifunza vizuri. Umbizo halitabadilika chini yako. Kinachovunjika ni uwekaji na matengenezo, na yote hayo ni kazi yako.

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 inayohifadhi 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 katika 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 kutolingana huko. Wiki sita baadaye, faili hilo linaelezea hatua ya build ambayo haipo tena, na mtu aliyesababisha hitilafu hiyo 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 ya kawaida. Faili la 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 kanuni ni sahihi kwa wakati fulani tu, kwa hivyo agent hulazimika kukisia ni ipi inayotumika. Nyaraka za Claude Code zinaelezea matokeo yake: "kama kanuni mbili zinapingana, Claude anaweza kuchagua moja kiholela." Faili la kila directory huondoa kukisia huko, kwa sababu ni kanuni moja tu kati ya mbili inayokuwa kwenye context.

Linajaa ukweli ambao agent angeweza 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 mipangilio ya kawaida ya 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 mfumo huu, kwa hivyo ni vyema 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 ndilo linalopewa kipaumbele na kila mradi mdogo unaweza kuwa na maelekezo yake maalum.

Na kuhusu migongano:

Faili la AGENTS.md lililo karibu zaidi na faili linalohaririwa ndilo linaloshinda; maelekezo ya moja kwa moja kutoka kwa mtumiaji kwenye chat huondoa maelekezo yote mengine.

Watu wengi hufasiri "kupewa kipaumbele" kama "faili la root linapuuzwa". Hiyo si kweli. Katika zana zinazotekeleza mwongozo huu, kila faili lililo kwenye njia kuanzia root ya repository hadi saraka ya kazi husomwa na kuunganishwa pamoja. Faili la karibu zaidi hushinda pale tu ambapo faili mbili zinasema mambo tofauti kuhusu mada moja.

Codex inaelezea utaratibu huu waziwazi: "Codex huunganisha faili kuanzia root kwenda chini, ikiyachanganya kwa kutumia mistari mitupu. Faili zilizo karibu na saraka yako ya sasa hufuta mwongozo uliotangulia." Claude Code hufuata njia hiyo hiyo kwa jina lake la faili. Faili zilizo kwenye uongozi wa saraka juu ya saraka ya kazi "hupakiwa kikamilifu wakati wa kuanzishwa", na "Faili zote zilizopatikana huunganishwa kwenye muktadha badala ya kufutana." 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 utangulizi wa kila kikao ndani ya repository, 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 uliothibitishwa 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 ya mzizi (root) imefupishwa kwa makusudi. Inaelekeza mahali pa kutazama, na inabeba 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 ya kila saraka ndipo maelezo yanapowekwa, na inaweza 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 ya mfanyakazi (worker) ina umbo sawa lakini maudhui tofauti: amri ya usakinishaji, pytest -q, sababu inayomfanya mtumiaji lazima abaki na tabia ya idempotent, na uhamiaji (migration) ambao lazima uendeshwe kabla ya majaribio (tests) kufaulu. Faili ya miundombinu (infra) 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 kwenye faili hizi: maelezo ya kazi ya kila huduma. Hilo ni jukumu la binadamu. Upstream inachora mstari uleule, ikisema "faili za README.md ni kwa ajili ya binadamu: kuanza haraka, maelezo ya mradi, na miongozo ya kuchangia", 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 ya tatu, ile inayoelezea 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 faili ya AGENTS.md ya saraka hiyo katika commit ileile.

Hii inafanya kazi kwa sababu ya kiufundi, si kwa sababu ya utamaduni. Faili ya kila saraka inapatikana katika diff ileile ya msimbo, 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. Mfumo hutafuta faili ya AGENTS.md iliyo karibu zaidi juu ya kila faili iliyobadilishwa, kisha hutoa taarifa ikiwa faili hiyo haikuguswa.

#!/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 huonekana 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, na hili ndilo sehemu inayofanya kazi kweli.

Ninawezaje kutambua 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. Inakuonyesha tu 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 katika session. Agent husoma faili, hujaribu kufungua src/api/client.ts kwa sababu faili limemwelekeza kufanya hivyo, na zana hiyo inarejesha:

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 kuunda upya code ambayo tayari unayo. Ujuzi kama Ponytail, ambayo humzuia agent kufanya mabadiliko madogo zaidi yanayofanya kazi, hufanya silika hiyo ya kuunda 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 kuwa na CLAUDE.md kando ya kila AGENTS.md.

Fomu ya import ni sahihi pale unapotaka mistari mahususi ya zana fulani (tool-specific) juu ya zile zinazoshirikiwa. Weka hili ndani ya services/worker/CLAUDE.md:

@AGENTS.md

## Claude Code

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

Fomu 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 anza kipindi (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 import ya @AGENTS.md huko.

Mtego mmoja unahusiana na hili. Baada ya /compact, faili ya mzizi (root file) inasomwa upya kutoka kwenye diski, lakini faili zilizopo kwenye saraka ndogo (subdirectories) hazirejeshwi. Zinarudi mara nyingine wakati wakala (agent) anaposoma faili katika saraka hiyo. Ikiwa sheria ya kila saraka inaonekana kuacha kufanya kazi katikati ya kipindi kirefu, hiyo ndiyo sababu, na kugusa (touch) 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 uleule: 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 mwenzako kwenye nakala mpya, hauwezi kuishi 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 kanuni inayoweza kutumika: "Ikiwa ingizo ni utaratibu wa hatua nyingi au ni muhimu kwa sehemu moja tu ya codebase, lisongeze kwenye ujuzi au sheria iliyowekewa wigo wa njia (path-scoped rule)." 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 kati ya 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, faili ya AGENTS.md iliyo ndani ya folda nyingine inachukua nafasi ya faili ya mzizi au inaongezea?

Inaongezea. Upstream inasema "faili iliyo karibu zaidi ndiyo yenye mamlaka," jambo linaloelezea kinachotokea wakati wa mgongano, si kinachopakiwa. Codex "huunganisha faili kutoka mzizini kwenda chini, ikizitenganisha kwa mistari mitupu," na Claude Code huunganisha kila faili inayoipata inapopanda kutoka kwenye working directory badala ya kuzifuta. Faili iliyo karibu zaidi hushinda pale tu ambapo faili mbili zinatoa maelekezo tofauti kuhusu jambo lilelile. 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 repository 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 pamoja kwa chaguo-msingi. Ikiwa faili yako ya mzizi inaelezea huduma nne, sehemu kubwa yake ni mzigo usio na maana kwa kazi moja 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 chini yake. 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 wakati mwingine 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 kwa mara unapaswa kuwa kwenye skill, ambayo hupakiwa ikihitajika. 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 dependencies, haupaswi kuwa kwenye yoyote kati ya hizo.