SSD Nodes Learn Hosting plans →
Mwongozo Matt ConnorNa Matt Connor · Imeboreshwa 2026-10-30

Jinsi ya kupanga AGENTS.md kwenye monorepo

Faili moja la AGENTS.md kwenye mzizi wa monorepo hupoteza muktadha na kupitwa na wakati. Jifunze kutumia muundo wa faili zilizopangwa ndani ya kila saraka ili kuboresha usahihi.

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 AGENTS.md moja kubwa 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.

Inapitwa na wakati, kwa sababu hakuna anayeimiliki. Mhandisi anayebadili jina la script ya majaribio katika apps/web anahariri faili zilizo chini ya apps/web. AGENTS.md ya root haipo kwenye diff hiyo, kwa hivyo hakuna mkaguzi anayeona kutokubaliana huko. Wiki sita baadaye, faili hiyo inaelezea hatua ya build ambayo haipo tena, na mtu aliyeivunja amesahau mabadiliko hayo.

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

Maelekezo huanza kupingana. Directory ya web inataka pnpm test. Worker inataka pytest -q. Zikiwa zimeandikwa kwenye faili moja, kila kanuni ni sahihi wakati mwingine tu, kwa hivyo agent hulazimika kukisia ni ipi inayotumika. Nyaraka za Claude Code zinaelezea matokeo: "kama maelekezo mawili yanapingana, Claude anaweza kuchagua moja kiholela." Kugawanya faili hakuzuii kanuni nyingine isiingie kwenye context. Claude Code huunganisha kila faili ya maelekezo iliyopakiwa badala ya kuruhusu moja kuchukua nafasi ya nyingine, kwa hivyo faili ya root ipo kila wakati, na mara tu agent anapofungua faili katika apps/web na services/worker, faili zote mbili za directory hukaa kwenye context pamoja. Kile ambacho faili ya kila directory hufanya ni kufunga kila kanuni kwenye directory inayoiongoza. Taja directory juu ya faili, kama mifano hapa chini inavyofanya na # apps/web, na kila amri bado inasema mahali inapofanya kazi wakati faili kadhaa zimepakiwa kwa wakati mmoja. Wakati kanuni unayohakikisha uliandika kwa uwazi inarukwa hata hivyo, kupitia sababu kwa nini maelekezo hayafanyi kazi ni bora kuliko kuandika upya maneno hayo kwa mara ya nne.

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

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

Hapa ndipo watu wengi wanapokosea kuelewa modeli hii, kwa hivyo ni vyema kunukuu mkataba wa msanidi badala ya kuufafanua:

Weka AGENTS.md nyingine 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 kusafirisha maelekezo yaliyolengwa.

Na kuhusu migogoro:

AGENTS.md iliyo karibu zaidi na faili linalohaririwa ndiyo inayoshinda; maelekezo ya moja kwa moja ya mtumiaji kwenye chat hubatilisha kila kitu.

"Kupewa kipaumbele" husomwa na watu wengi kama "faili la root linapuuzwa". Si kweli. Katika zana zinazotekeleza mkataba huu, kila faili lililo kwenye njia kutoka kwenye root ya hazina (repository) hadi kwenye saraka ya kazi husomwa na kuunganishwa pamoja. Faili la karibu zaidi hushinda pale tu 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 hubatilisha mwongozo wa awali." Claude Code hufuata njia hiyo hiyo. Wakati wa kuanza kipindi, husoma "kila AGENTS.md na .claude/AGENTS.md katika saraka yako ya kazi na saraka zilizo juu yake", na nyaraka zake hueleza modeli ya upakiaji waziwazi: "Faili zote zilizogunduliwa huunganishwa kwenye muktadha badala ya kubatilishana." Saraka zilizo chini ya saraka ya kazi hufanya kazi tofauti: Claude Code hupakia AGENTS.md ya saraka ndogo inapohitajika, "wakati Claude anapofungua faili huko kwa kutumia zana ya Read."

Matokeo mawili ya kivitendo yanajitokeza. Faili la root ni kiambishi awali (prefix) kwenye kila kipindi katika hazina, kwa hivyo chukulia kila mstari uliopo hapo kama mstari unaolipa mara mia moja kwa wiki. Faili la kila saraka haligharimu chochote hadi wakala afungue faili katika saraka hiyo, jambo linalomaanisha kuwa maelezo ya kina ni ya bei nafuu huko na yanapaswa kuwekwa huko.

Tabia hii ilikaguliwa dhidi ya nyaraka za Codex na Claude Code mnamo 27 Oktoba 2026. Zana hutekeleza mkataba huu kwa njia tofauti kidogo na hubadilika, kwa hivyo thibitisha sheria za upakiaji kwa wakala yeyote anayotumiwa na timu yako.

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 doc iliyo nyuma kwa miezi sita kuliko tarehe ya code haithibitishi kuwa faili hilo ni baya. Inakuonyesha 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 mojawapo iliyo faili kwenye disk. Kwenye Claude Code v2.1.283 au matoleo mapya zaidi, /doctor prompt-audit hufanya ukaguzi kama huo kwa ajili yako: hutafuta "marejeleo ya faili au amri zisizokuwepo" na faili zinazopingana, hushughulikia faili zako za AGENTS.md kwa chaguo-msingi, na haibadilishi chochote hadi utakapoiomba itekeleze marekebisho inayopendekeza.

Dalili ndani ya session. Agent husoma faili, hujaribu kufungua src/api/client.ts kwa sababu faili limemwelekeza kufanya hivyo, na tool hurudisha:

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 huizuia 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?

Ndiyo, kuanzia Claude Code v2.1.277, na kanuni kamili ni muhimu kwa sababu mpangilio wa ndani (nested layout) unategemea hilo. Imehakikiwa dhidi ya nyaraka za tarehe 27 Oktoba 2026: "Claude Code inaweza kusoma AGENTS.md kama maelekezo ya mradi wako, kwa hivyo hazina (repository) iliyosanidiwa tayari kwa ajili ya mawakala wengine wa usimbaji inafanya kazi bila kuongeza CLAUDE.md, import, au mpangilio wowote." Thamani chaguo-msingi ya Project instructions, claude-md-or-agents-md, inasoma "faili zako za AGENTS.md wakati huna CLAUDE.md au CLAUDE.local.md katika saraka yako ya kazi au juu yake." Faili za ndani pia zinajumuishwa: Claude inasoma AGENTS.md ya saraka ndogo "wakati Claude anapofungua faili hapo kwa kutumia zana ya Read", mradi "saraka hiyo ndogo haina hata moja ya faili tatu za CLAUDE.md zake yenyewe". Faili hizo tatu ni CLAUDE.md, .claude/CLAUDE.md na CLAUDE.local.md, kwa hivyo CLAUDE.local.md ya kibinafsi katika apps/web inatosha kuzuia apps/web/AGENTS.md isipakie.

Hiyo inafanya ushauri wa zamani wa kuweka CLAUDE.md kando ya kila AGENTS.md kuwa mtego. Pamoja na AGENTS.md na CLAUDE.md au CLAUDE.local.md katika saraka yako ya kazi au juu yake, nyaraka zinasema Claude inasoma "Faili zako za CLAUDE.md pekee". .claude/CLAUDE.md inahesabika kwa njia hiyo hiyo. Faili moja ya ziada kwenye mzizi (root) iliyo na mstari mmoja mahususi wa Claude huficha kila AGENTS.md kwenye njia hiyo, na CLAUDE.local.md ya kibinafsi hufanya vivyo hivyo. Ikiwa unataka kuweka moja, chapa /config na uweke Project instructions kuwa claude-md-and-agents-md, ambayo inasoma zote mbili, CLAUDE.md ya kila saraka kwanza na AGENTS.md yake baadaye.

Nambari ya toleo pekee haithibitishi kuwa ilifanya kazi. Unahitaji v2.1.277 au zaidi, lakini kabla ya v2.1.281 baadhi ya vipindi (sessions), kama vile vile kwenye Amazon Bedrock au vilivyo na telemetry imezimwa, husoma faili za CLAUDE.md pekee, na katika hali nyingine kipindi cha kwanza baada ya kuboresha kutoka v2.1.276 au mapema huruka AGENTS.md pia: nyaraka zinasema "Claude inasoma AGENTS.md kuanzia kipindi chako kijacho". Kwa hivyo angalia kipindi chenyewe. Katika kipindi cha mwingiliano (interactive session), Claude Code huchapisha mstari kama no CLAUDE.md found; AGENTS.md loaded: ikifuatiwa na njia, na kwenye matoleo ya sasa /memory huorodhesha faili hiyo. Kabla ya v2.1.280, /memory na /context hazikuorodhesha AGENTS.md ambayo Claude ilisoma moja kwa moja, kwa hivyo kwenye matoleo hayo muulize Claude maelekezo yake ya mradi yanasema nini.

Fomu ya import bado ni sahihi pale ambapo Claude haiwezi kusoma AGENTS.md moja kwa moja: toleo la zamani, kipindi kabla ya v2.1.281 kwenye Amazon Bedrock au kikiwa na telemetry imezimwa, kipindi ambapo programu-jalizi (plugin) iliyojengewa ndani inayoisoma imezimwa, au mradi unaoweka CLAUDE.md na Project instructions ikiwa imewekwa kuwa claude-md. Weka hii katika services/worker/CLAUDE.md:

@AGENTS.md

## Claude Code

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

Fomu ya symlink ni sahihi wakati hakuna kitu mahususi cha zana cha 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 haichapishi chochote inapofanikiwa, kwa hivyo angalia orodha: apps/web/CLAUDE.md -> AGENTS.md. Kisha anza kipindi na uendeshe /context, ambapo faili zilizopakiwa zinaonekana chini ya Memory files. Kwenye Windows, symlink inahitaji haki za Administrator au Developer Mode, na Git hutoa symlink iliyofanyiwa commit kama faili ya maandishi ya kawaida isipokuwa core.symlinks ikiwa imewezeshwa, jambo ambalo huacha clone hiyo na CLAUDE.md ya mstari mmoja badala ya maelekezo yako. Ikiwa mtu yeyote anayefanya clone ya hazina hiyo anafanya kazi kwenye Windows, tumia import ya @AGENTS.md badala yake. Ikiwa uliweka mojawapo ya njia mbadala kabla ya Claude Code kusoma AGENTS.md yenyewe, unaweza kuiacha: nyaraka zinasema kuweka import "kamwe hakufanyi Claude asome AGENTS.md mara mbili", na CLAUDE.md iliyounganishwa kwa symlink inasomwa mara moja.

Mtego mmoja unahusiana na hili. Baada ya /compact, CLAUDE.md ya mzizi wa mradi inasomwa tena kutoka kwenye diski, lakini faili za ndani katika saraka ndogo hazidungwi tena. Claude Code huzipakia tena inapohitajika, wakati mwingine wakala anapofanya kazi na faili katika saraka hiyo. Nyaraka zinafafanua hili kwa faili za CLAUDE.md na haielezei compaction kando kwa AGENTS.md iliyosomwa moja kwa moja, kwa hivyo tarajia faili za ndani za jina lolote kufanya kazi kwa njia hii. Ikiwa kanuni ya kila saraka inaonekana kuacha kutumika katikati ya kipindi kirefu, hiyo ndiyo sababu kawaida, na kusoma faili yoyote katika saraka hiyo huirejesha.

Mipangilio inayoelekeza mawakala wengine kwenye AGENTS.md

Codex inasoma AGENTS.md kiasili. Katika kila ngazi inakagua AGENTS.override.md kwanza, ambayo inatoa saraka moja uwezo wa kubatilisha (override) wa ndani bila kuhariri faili iliyoshirikiwa. Inaacha kuunganisha (merging) mara tu ukubwa wa jumla unapofikia 32 KiB, project_doc_max_bytes chaguo-msingi, ambayo ni sababu nyingine ya kuweka faili ya mzizi ndogo.

Aider inachukua kupitia .aider.conf.yml na mstari read: AGENTS.md.

Gemini CLI inachukua kupitia .gemini/settings.json na { "context": { "fileName": "AGENTS.md" } }.

Upstream inaandika jina jipya linalooana na matoleo ya awali kwa hazina zinazotumia jina la zamani la umoja: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.

Katika monorepo kubwa sana, mpangilio wa claudeMdExcludes wa Claude Code huruka faili za mababu kwa njia au glob, jambo ambalo ni muhimu wakati saraka ya timu nyingine iko juu ya yako. Mifumo yake inatumika kwa faili za AGENTS.md ambazo Claude Code inasoma pia.

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 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 inapopita kwenye saraka kuanzia ile ya kazi badala ya kuzifuta. 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 saraka.

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

Iwe ndogo kiasi kwamba hutaona shida ikibandikwa 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 pamoja kwa chaguo-msingi. Ikiwa faili yako ya mzizi inaelezea huduma nne, sehemu kubwa yake ni mzigo usio na faida kwa kazi yoyote moja. Hamisha maelezo hayo kwenye faili za kila saraka na uache ramani nyuma.

Ninawezaje kuzuia faili hizi kupitwa na wakati?

Weka sheria moja kwenye faili ya mzizi: yeyote anayebadilisha msimbo katika saraka anapaswa kusasisha AGENTS.md ya saraka hiyo katika commit ileile. Kuweka faili karibu na msimbo ndiko kunakofanya sheria hiyo kuzingatiwa, kwa sababu mabadiliko hayo huingia kwenye diff ya pull request ileile ambayo binadamu anaisoma. Ongeza onyo la CI linalohusisha 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 saraka inayoelezewa.

Je, Claude Code inasoma faili za AGENTS.md?

Ndiyo, kuanzia v2.1.277. Ikiangaliwa dhidi ya nyaraka mnamo 27 Oktoba 2026, Claude Code inasoma AGENTS.md kwa chaguo-msingi wakati huna CLAUDE.md au CLAUDE.local.md katika saraka yako ya kazi au juu yake, na inasoma AGENTS.md ya saraka ndogo wakati inafungua faili hapo kwa kutumia zana ya Read na saraka hiyo ndogo haina CLAUDE.md, .claude/CLAUDE.md au CLAUDE.local.md yake yenyewe. Usiongeze CLAUDE.md kando ya kila AGENTS.md: ukiwa na moja kwenye au juu ya saraka ya kazi, Claude inasoma "Faili zako za CLAUDE.md pekee". Ikiwa unahitaji CLAUDE.md pia, weka Project instructions kuwa claude-md-and-agents-md katika /config, au weka @AGENTS.md kwenye mstari wake wa kwanza. Tekeleza /memory katika kipindi cha kazi na uthibitishe kuwa njia ya AGENTS.md inaonekana kwenye orodha.

Ninaweka wapi sheria inayohitajika mara chache tu?

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

Je, makala hii ilikusaidia?