Nested AGENTS.md para sa Monorepo: Tamang Setup
Alamin kung bakit naluluma ang isang malaking root AGENTS.md at kung paano hinahati ang rules sa nested files para bawasan ang context na binabasa ng agent.
Ano ang ibig sabihin ng nested AGENTS.md sa isang monorepo
Ang nested na AGENTS.md sa isang monorepo ay nangangahulugang may isang maliit na file sa root ng repository at may isa pang file sa loob ng bawat service directory. Nilalaman ng root file ang iilang rule na nalalapat sa lahat, pati ang mapa kung saan makikita ang iba pang file. Nilalaman naman ng bawat service file ang mga command at convention para lamang sa directory na iyon. Kapag nag-e-edit ang isang agent ng services/worker/queue.py, binabasa nito ang root file at ang worker file, kaya wala itong ginagawang context para sa front end na hindi naman nito gagalawin.
Walang kailangang i-install. Convention lamang ang AGENTS.md, at malinaw itong sinasabi ng upstream project:
Ang AGENTS.md ay karaniwang Markdown lamang. Gumamit ng anumang heading na gusto mo; bina-parse lamang ng agent ang tekstong ibinigay mo.
Kaya sulit na matutunan nang maayos ang teknik na ito. Hindi magbabago ang format nang hindi mo namamalayan. Ang karaniwang nagdudulot ng problema ay ang placement at maintenance, at responsibilidad mo ang dalawang ito.
Bakit hindi na gumagana ang isang malaking root AGENTS.md?
Ang iisang 600-line na AGENTS.md sa root ng repository na naglalaman ng web app, background worker, at Terraform directory ay pumapalya sa apat na magkakahiwalay na paraan.
Nagiging luma ito dahil walang nagmamay-ari nito. Ang engineer na nagre-rename ng test script sa apps/web ay nag-e-edit ng mga file sa ilalim ng apps/web. Wala ang root AGENTS.md sa diff na iyon, kaya walang reviewer na makakakita sa hindi pagtutugma. Makalipas ang anim na linggo, inilalarawan pa rin ng file ang build step na wala na, at nakalimutan na ng taong nagdulot ng problema ang pagbabagong ginawa niya.
Kumokonsumo ito ng context sa bawat task. Nilo-load ang mga file na ito sa simula ng session, bago malaman ng agent ang itatanong mo. May partikular na gabay ang documentation ng Claude Code: “target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.” Humihinto ang Codex sa pag-merge ng mga instruction file kapag umabot sa 32 KiB ang pinagsama-samang laki ng mga ito, ang default na project_doc_max_bytes. Ang root file na nagdodokumento ng apat na serbisyo ay inuubos ang budget na iyon para sa tatlo sa mga ito sa bawat task.
Nagsisimulang magkasalungat ang mga instruction. Kailangan ng web directory ang pnpm test. Kailangan naman ng worker ang pytest -q. Kapag isinulat sa iisang file, tama lamang ang bawat rule sa ilang pagkakataon, kaya kailangang hulaan ng agent kung alin ang naaangkop. Inilalarawan ng docs ng Claude Code ang resulta: “if two instructions contradict each other, Claude may pick one arbitrarily.” Hindi awtomatikong inaalis sa context ang ibang rule kapag hinati ang file. Pinagdudugtong ng Claude Code ang bawat instruction file na na-load nito sa halip na hayaang palitan ng isa ang isa pa. Dahil dito, palaging kasama ang root file, at kapag nagbukas ang agent ng mga file sa parehong apps/web at services/worker, magkasama sa context ang dalawang directory file. Ang ginagawa ng per-directory file ay itinatali ang bawat rule sa directory na sakop nito. Ilagay ang pangalan ng directory sa itaas ng file, gaya ng mga halimbawang gumagamit ng # apps/web sa ibaba, upang malinaw pa rin kung saan naaangkop ang bawat command kapag maraming file ang sabay-sabay na na-load. Kapag patuloy na nilalaktawan ang isang rule na tiyak mong malinaw na isinulat, mas mabuting alamin muna ang mga dahilan kung bakit hindi naipapatupad ang isang instruction kaysa muling isulat ang wording nito sa ikaapat na pagkakataon.
Napupuno ito ng mga impormasyong mababasa naman ng agent mula sa code. Kabilang dito ang directory tree, listahan ng dependency, at buod ng ginagawa ng bawat package. Ang /doctor check ng Claude Code ay ginawa upang eksaktong alisin ang ganitong content. Tinatanggal nito ang “content Claude can derive from the codebase, such as directory layouts, dependency lists, and architecture overviews” at pinananatili ang “pitfalls, rationale, and conventions that differ from tool defaults.” Iyan ang pinakamainam na pagsusuri na alam ko para malaman kung dapat bang ilagay ang isang linya sa file.
Binabasa ba ng agent ang root file, o ang pinakamalapit na file lamang?
Dito kadalasang nagkakamali ang mga tao sa pag-unawa sa model, kaya mas mabuting sipiin ang upstream convention kaysa iparaphrase ito:
Maglagay ng isa pang AGENTS.md sa loob ng bawat package. Awtomatikong binabasa ng mga agent ang pinakamalapit na file sa directory tree, kaya ang pinakamalapit na file ang may precedence at maaaring maglaman ang bawat subproject ng mga tagubiling iniangkop dito.
At tungkol sa mga conflict:
Ang pinakamalapit na AGENTS.md sa ine-edit na file ang mananaig; nangingibabaw sa lahat ang mga tahasang user prompt sa chat.
Para sa maraming tao, ang "may precedence" ay nangangahulugang "binabalewala ang root file". Hindi ito tama. Sa mga tool na nagpapatupad ng convention na ito, binabasa at pinagsasama ang bawat file sa path mula repository root pababa hanggang sa working directory. Ang pinakamalapit na file lamang ang mananaig kapag magkaiba ang sinasabi ng dalawang file tungkol sa parehong paksa.
Malinaw ang Codex tungkol sa mekanismo: "Pinagdudugtong ng Codex ang mga file mula root pababa, at pinaghihiwalay ang mga ito gamit ang blank lines. Ino-override ng mga file na mas malapit sa kasalukuyan mong directory ang naunang guidance." Pareho ring tinatahak ng Claude Code ang path na ito. Sa simula ng session, binabasa nito ang "bawat AGENTS.md at .claude/AGENTS.md sa iyong working directory at sa mga directory na nasa itaas nito", at malinaw na inilalarawan ng dokumentasyon nito ang loading model: "Pinagsasama ang lahat ng natuklasang file sa context sa halip na i-override ang mga ito." Iba ang pag-uugali ng mga directory na nasa ibaba ng working directory: nilo-load ng Claude Code ang AGENTS.md ng isang subdirectory kapag kinakailangan, "kapag nagbukas si Claude ng file roon gamit ang Read tool."
Dalawang praktikal na resulta ang sumusunod. Ang root file ay prefix sa bawat session sa repository, kaya ituring ang bawat linya roon bilang linyang babayaran mo nang sandaang beses bawat linggo. Walang gastos ang isang per-directory file hanggang sa magbukas ang agent ng file sa directory na iyon, kaya mura ang detalye roon at doon ito dapat ilagay.
Sinuri ang behavior na ito batay sa dokumentasyon ng Codex at Claude Code noong 27 October 2026. Bahagyang magkakaiba ang pagpapatupad ng convention ng mga tool, at nagbabago rin ang mga ito, kaya kumpirmahin ang loading rules para sa agent na ginagamit ng team ninyo.
Isang aktuwal na layout para sa repository na may tatlong serbisyo
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 scriptsSadyang maikli ang root file. Sinasabi nito kung saan titingin, at naglalaman lamang ito ng mga panuntunang naaangkop sa bawat directory.
# 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.Dito inilalagay ang mga detalye sa per-directory file, at maaari itong maging kasinghaba ng kinakailangan ng directory.
# 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.Pareho ang anyo ng worker file, pero iba ang nilalaman: ang install command, pytest -q, ang dahilan kung bakit kailangang manatiling idempotent ang consumer, at ang migration na dapat tumakbo bago pumasa ang mga test. Dito inilalagay sa infra file ang mga panuntunang pumipigil sa agent na makapagdulot ng pinsala. Huwag kailanman patakbuhin ang terraform apply. Patakbuhin ang terraform plan at doon na huminto, at pangalanan ang state backend na naka-configure na upang hindi subukang mag-initialize ang agent ng bago.
Pansinin kung ano ang wala sa alinman sa mga file na ito: paglalarawan kung para saan ang bawat serbisyo. Para iyon sa mga tao. Ganito rin ang hangganang itinatakda ng upstream: ang "README.md files are for humans: quick starts, project descriptions, and contribution guidelines", samantalang ang AGENTS.md ay naglalaman ng "the extra, sometimes detailed context coding agents need: build steps, tests, and conventions." Isa-isang sinusuri sa pagkakahati sa pagitan ng AGENTS.md at README na para sa tao ang hangganang ito, at tinatalakay naman sa DESIGN.md na nagtatala kung bakit ganito ang pagkakahubog ng code ang ikatlong file—ang nagpapaliwanag ng mga desisyon, hindi ng mga command.
Sino ang nag-a-update ng file kapag nagbabago ang code?
Isang panuntunan lang, at nasa root file ito: ang sinumang nagbabago ng code sa isang directory ang dapat ding mag-update sa AGENTS.md ng directory na iyon sa parehong commit.
Gumagana ito dahil sa mekanikal na dahilan, hindi dahil sa kultura. Nasa parehong diff ng code ang file para sa directory, kaya sabay na nakikita ng reviewer ng pull request ang dalawa. Para sa lahat ang root file, kaya wala talagang partikular na may pananagutan dito, at hindi ito kailanman kasama sa diff na binabasa na ng sinuman.
Suportahan ang panuntunan sa pamamagitan ng check sa pull request. Hinahanap nito ang pinakamalapit na AGENTS.md sa itaas ng bawat nabagong file, pagkatapos ay nag-uulat kapag hindi nabago ang file na iyon.
#!/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"
doneSa isang branch na nag-rework sa API client nang hindi binabago ang docs, ganito ang magiging output:
note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updatedGawin itong warning sa halip na failure. Kapag hard gate ito, matututo ang mga tao na magdagdag ng blangkong linya sa file para maging green ang CI. Mas mababa pa ang halaga ng file na binago para lang mapasunod ang isang robot kaysa sa kawalan ng file. Nagbibigay ang warning ng tanong na maaaring itanong ng reviewer, at iyon ang bahaging talagang gumagana.
Paano matutukoy kung luma na ang isang AGENTS.md?
May dalawang pagsusuring maaari mong patakbuhin ngayon, at may isang sintomas na makikita mo sa loob ng isang session.
Ikumpara ang edad ng bawat file sa edad ng code na inilalarawan nito. Ipinapakita ng %cs ang petsa ng commit bilang 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")"
doneapps/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-01Hindi nito pinatutunayang mali ang file kung anim na buwan na mas luma ang petsa ng dokumento kaysa sa petsa ng code. Sinasabi lang nito kung aling file ang dapat mong basahin muna. Iyan lang ang kailangan mo mula sa pagsusuring tumatagal nang isang segundo.
Hanapin ang mga path na wala na. May isang tiyak na paraan kung paano naluluma ang documentation: patuloy nitong inilalarawan ang code na dinelete na. Nasa backticks ang bawat path sa mga file na ito, kaya madali itong kunin at suriin.
grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
[ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
doneBasahin ang output sa halip na isama ito sa CI. Naa-flag din nito ang mga glob gaya ng src/**/*.ts at anumang URL na inilagay mo sa quotes, dahil parehong may slash at wala sa disk ang alinman sa mga ito bilang file. Sa Claude Code v2.1.283 o mas bago, awtomatikong nagsasagawa ng katulad na pagsusuri ang /doctor prompt-audit: hinahanap nito ang “mga reference sa mga file o command na wala” at ang mga file na nagkakasalungatan, sinasaklaw nito bilang default ang mga AGENTS.md file mo, at wala itong binabago hangga't hindi mo ito inuutusang ilapat ang mga iminungkahing edit.
Ang sintomas sa loob ng isang session. Binabasa ng agent ang file, sinusubukang buksan ang src/api/client.ts dahil iyon ang sinabi ng file, at ibinabalik ng tool ang:
No such file or directoryKaya ginagawa nito ang makatuwirang hakbang at sumusulat ng sarili nitong fetch wrapper. Iyan ang tunay na gastos ng lumang file. Hindi binabalewala ng agent ang documentation mo. Sinusunod nito ang documentation, napupunta sa path na dinelete tatlong buwan na ang nakalipas, at muling binubuo ang code na mayroon ka na. Nakababawas sa ganitong instinct na muling bumuo ang isang skill gaya ng Ponytail, na pinananatili ang agent sa pinakamaliit na pagbabagong gumagana, pero hindi nito mahahanap ang helper na itinuro ng file mo sa maling lugar.
Binabasa ba ng Claude Code ang mga AGENTS.md file?
Oo, mula sa Claude Code v2.1.277. Mahalaga ang eksaktong rule dahil nakadepende rito ang nested layout. Sinuri ito batay sa documentation noong 27 October 2026: "Mababasa ng Claude Code ang AGENTS.md bilang mga instruction ng project mo, kaya gagana ang repository na naka-set up na para sa ibang coding agent nang hindi nagdadagdag ng CLAUDE.md, import, o setting." Ang default na value ng Project instructions, claude-md-or-agents-md, ay bumabasa ng "mga AGENTS.md file mo kapag wala kang CLAUDE.md o CLAUDE.local.md sa working directory mo o sa mga directory sa itaas nito." Sakop din ang nested file: binabasa ng Claude ang AGENTS.md ng subdirectory "kapag nagbukas ang Claude ng file roon gamit ang Read tool", basta "walang alinman sa tatlong CLAUDE.md file ang subdirectory na iyon." Ang tatlong ito ay CLAUDE.md, .claude/CLAUDE.md, at CLAUDE.local.md. Kaya sapat na ang personal na CLAUDE.local.md sa apps/web upang pigilan ang pag-load ng apps/web/AGENTS.md.
Dahil dito, nagiging patibong ang dating payo na maglagay ng CLAUDE.md sa tabi ng bawat AGENTS.md. Kapag may AGENTS.md at may CLAUDE.md o CLAUDE.local.md sa working directory mo o sa mga directory sa itaas nito, sinasabi ng documentation na "Mga CLAUDE.md file mo lamang" ang binabasa ng Claude. Ganito rin ang epekto ng .claude/CLAUDE.md. Itinatago ng isang companion file sa root na may isang Claude-specific na linya ang bawat AGENTS.md sa path, at ganoon din ang personal na CLAUDE.local.md. Kung gusto mong panatilihin ang isa, i-type ang /config at itakda ang Project instructions sa claude-md-and-agents-md. Babasahin nito ang dalawa: una ang CLAUDE.md ng bawat directory, at pagkatapos ang AGENTS.md nito.
Hindi sapat ang version number lang para matiyak na gumana ito. Kailangan mo ng v2.1.277 o mas bago, ngunit bago ang v2.1.281, ilang session—gaya ng mga nasa Amazon Bedrock o may disabled telemetry—ay CLAUDE.md file lamang ang binabasa. Sa ilang kaso, nilalaktawan din ng unang session pagkatapos mag-upgrade mula sa v2.1.276 o mas luma ang AGENTS.md: sinasabi ng documentation na "Babasahin ng Claude ang AGENTS.md sa susunod mong session." Kaya suriin mismo ang session. Sa interactive session, nagpi-print ang Claude Code ng linyang gaya ng no CLAUDE.md found; AGENTS.md loaded: na sinusundan ng path. Sa kasalukuyang versions, inililista ng /memory ang file. Bago ang v2.1.280, hindi inililista ng /memory at /context ang AGENTS.md na direktang binasa ng Claude. Sa mga version na iyon, itanong sa Claude kung ano ang nakasaad sa project instructions nito.
Ang import form pa rin ang tamang gamitin kapag hindi direktang mabasa ng Claude ang AGENTS.md: kapag mas luma ang version, nasa Amazon Bedrock ang session o disabled ang telemetry bago ang v2.1.281, disabled ang built-in plugin na bumabasa nito, o may CLAUDE.md ang project na nakatakda ang Project instructions sa claude-md. Ilagay ito sa services/worker/CLAUDE.md:
@AGENTS.md
## Claude Code
Use plan mode for changes under `services/worker/migrations/`.Tama ang symlink form kapag wala nang kailangang idagdag na tool-specific configuration.
git ls-files '*AGENTS.md' | while read -r f; do
ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.mdWalang output ang ln kapag matagumpay ito, kaya suriin ang listing: apps/web/CLAUDE.md -> AGENTS.md. Pagkatapos, magsimula ng session at patakbuhin ang /context. Lalabas ang mga na-load na file sa ilalim ng Memory files. Sa Windows, kailangan ng Administrator rights o Developer Mode para sa symlink. Tinitingnan naman ng Git bilang plain text file ang committed symlink kapag checkout sa Windows, maliban kung naka-enable ang core.symlinks. Dahil dito, magkakaroon ang clone na iyon ng isang linyang CLAUDE.md kapalit ng instructions mo. Kung may mga taong magki-clone ng repository at gagamit ng Windows, gamitin ang @AGENTS.md import. Kung na-set up mo ang alinman sa dalawang workaround bago pa mabasa ng Claude Code ang AGENTS.md nang kusa, maaari mo itong iwan. Sinasabi ng documentation na ang pagpapanatili ng import ay "hindi kailanman nagpapabasa nang dalawang beses sa Claude ng AGENTS.md", at isang beses lamang binabasa ang naka-symlink na CLAUDE.md.
May isa pang patibong na dapat tandaan. Pagkatapos ng /compact, muling binabasa mula sa disk ang CLAUDE.md sa project root, ngunit hindi muling ini-inject ang nested file sa mga subdirectory. Nire-reload ng Claude Code ang mga ito kapag kailangan, sa susunod na gumamit ang agent ng file sa directory na iyon. Tiyak itong inilalarawan ng documentation para sa CLAUDE.md file, ngunit hindi nito hiwalay na inilalarawan ang compaction para sa AGENTS.md na direktang binasa. Kaya asahan na ganito rin ang asal ng nested file sa alinmang pangalan. Kung mukhang tumigil sa pag-apply ang isang per-directory rule sa kalagitnaan ng mahabang session, karaniwan itong dahilan. Kapag nagbasa ka ng anumang file sa directory, maibabalik ito.
Mga setting na nagtuturo sa ibang agent kung saan makikita ang AGENTS.md
Native na binabasa ng Codex ang AGENTS.md. Sa bawat level, sinusuri muna nito ang AGENTS.override.md. Nagbibigay ito ng local override sa isang directory nang hindi ine-edit ang shared file. Tumitigil ito sa pag-merge kapag umabot sa 32 KiB ang pinagsamang size, na siyang default na project_doc_max_bytes. Isa pa itong dahilan upang panatilihing maliit ang root file.
Binabasa ito ng Aider sa pamamagitan ng .aider.conf.yml gamit ang linyang read: AGENTS.md.
Binabasa ito ng Gemini CLI sa pamamagitan ng .gemini/settings.json gamit ang { "context": { "fileName": "AGENTS.md" } }.
May backward-compatible rename na dokumentado sa upstream para sa mga repository na gumagamit pa rin ng mas lumang singular na pangalan: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.
Sa napakalaking monorepo, nilalaktawan ng setting na claudeMdExcludes ng Claude Code ang mga ancestor file batay sa path o glob. Kapaki-pakinabang ito kapag may directory ng ibang team sa itaas ng directory mo. Nalalapat din ang mga pattern nito sa AGENTS.md file na binabasa ng Claude Code.
Paano ito naiiba sa agent memory o sa isang skill?
Magkamukha ang mga mekanismong ito, pero lubhang magkakaiba ang paraan ng pag-fail ng mga ito. Kaya mahalagang tukuyin kung alin ang kailangan mo.
Ang AGENTS.md ay sinusulat mo, kino-commit sa git, nire-review sa pull request, at pare-pareho para sa lahat ng nagki-clone ng repository. Ang agent memory ay sinusulat ng agent, iniimbak sa labas ng repository, at lokal sa isang machine. Pareho ang pagkakaibang ito sa dokumentasyon ng Claude Code: naglalaman ang CLAUDE.md ng “Instructions and rules” na ikaw ang nagsusulat, ang auto memory ay naglalaman ng “Learnings and patterns” na sinusulat ni Claude, at hindi ibinabahagi sa ibang machine ang memory directory. Simple ang pagsusuri. Kung kailangang maging totoo ang isang fact para sa kasamahan mong gumagamit ng fresh clone, hindi ito dapat nasa memory. Tinutukoy ng Paano nananatili ang agent memory sa pagitan ng mga session ang bahaging ito.
Ang skill ang ikatlong mekanismo. Ang AGENTS.md ay context na nilo-load sa bawat session; ang skill ay procedure na nilo-load kapag kailangan. Nagbibigay ang dokumentasyon ng Claude Code ng praktikal na panuntunan: “Kung ang isang entry ay multi-step procedure o mahalaga lamang sa isang bahagi ng codebase, ilipat ito sa isang skill o sa isang path-scoped rule.” Ang ikalawang bahagi ng pangungusap na ito ang eksaktong nilulutas ng nested AGENTS.md. Ang unang bahagi naman ang gamit ng agent skills, at kapag kailangan ang parehong procedure sa higit sa isang repository, ibahagi ang skill sa maraming repo sa halip na kopyahin ang parehong mga talata sa sampung magkakaibang AGENTS.md file.
Binanggit ng upstream na “sa oras ng pagsulat nito, may 88 AGENTS.md file ang pangunahing OpenAI repo.” Iyon ang buong paliwanag. Hindi kailangan ng malaking repository ang mas malaking file. Kailangan nito ng mas maraming maliliit na file, na bawat isa ay nasa tabi ng code na inilalarawan nito at pinamamahalaan ng huling nagbago sa code na iyon.
FAQ
Pinapalitan ba ng nested na AGENTS.md ang root file o idinadagdag ito rito?
Idinadagdag ito rito. Sinasabi ng upstream na “nangunguna ang pinakamalapit na file,” na tumutukoy sa nangyayari kapag may conflict, hindi sa mga nilo-load. “Pinagsasama-sama ng Codex ang mga file mula sa root pababa, at pinagdurugtong ang mga ito gamit ang mga blangkong linya,” habang pinagsasama naman ng Claude Code ang bawat file na nakikita nito habang umaakyat mula sa working directory, sa halip na i-override ang mga ito. Ang pinakamalapit na file lamang ang nananaig kapag magkaiba ang tagubilin ng dalawang file tungkol sa parehong paksa. Isulat nang isang beses ang mga shared rule sa root, at huwag ulitin ang mga ito sa bawat directory.
Gaano kalaki dapat ang root AGENTS.md?
Dapat sapat itong maliit para hindi ka mag-atubiling ilagay ito sa ibabaw ng bawat request na ginagawa mo sa repository na iyon, dahil iyon mismo ang nangyayari. Iminumungkahi ng dokumentasyon ng Claude Code na panatilihing wala pang 200 lines ang bawat file at nagbababala na ang mas mahahabang file ay “nakababawas sa pagsunod sa mga tagubilin.” Bilang default, humihinto ang Codex sa pagsasama ng mga instruction file kapag umabot sa 32 KiB ang pinagsamang laki. Kung nagdodokumento ang root file mo ng apat na serbisyo, karamihan dito ay hindi kailangan para sa isang partikular na task. Ilipat ang mga detalye sa mga per-directory file at mag-iwan ng mapa.
Paano ko mapipigilang maging luma ang mga file na ito?
Maglagay ng isang rule sa root file: sinumang nagbabago ng code sa isang directory ay dapat mag-update ng AGENTS.md ng directory na iyon sa parehong commit. Kapag inilagay ang file sa tabi ng code, mas nasusunod ang rule dahil napapabilang ang pagbabago sa parehong pull request diff na binabasa na ng isang tao. Magdagdag ng CI warning na nagmamapa sa bawat binagong path papunta sa pinakamalapit na AGENTS.md sa itaas nito, at paminsan-minsan ay ihambing ang git log -1 --format=%cs sa parehong command na pinatakbo sa directory na idinodokumento nito.
Binabasa ba ng Claude Code ang mga AGENTS.md file?
Oo, mula sa v2.1.277. Batay sa pagsusuri sa dokumentasyon noong 27 October 2026, binabasa ng Claude Code ang AGENTS.md bilang default kapag wala kang CLAUDE.md o CLAUDE.local.md sa working directory o sa itaas nito, at binabasa nito ang AGENTS.md ng isang subdirectory kapag nagbukas ito ng file doon gamit ang Read tool at walang sariling CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md ang subdirectory na iyon. Huwag magdagdag ng CLAUDE.md sa tabi ng bawat AGENTS.md: kapag may isa nito sa working directory o sa itaas nito, binabasa ni Claude ang “mga CLAUDE.md file mo lamang.” Kung kailangan mo rin ng CLAUDE.md, itakda ang Project instructions sa claude-md-and-agents-md sa /config, o ilagay ang @AGENTS.md sa unang linya nito. Patakbuhin ang /memory sa isang session at tiyaking lumilitaw sa listahan ang AGENTS.md path.
Saan ko ilalagay ang rule na paminsan-minsan lamang naaangkop?
Huwag sa AGENTS.md. Nilo-load ang file na iyon sa bawat session, kaya ang bawat linya rito ay nakikipag-agawan sa atensyon sa request na aktuwal mong isinulat. Ang procedure na may ilang hakbang at paminsan-minsang kailangan ay dapat ilagay sa isang skill, na nilo-load kapag kinakailangan. Ang rule na naaangkop sa isang directory lamang ay dapat ilagay sa AGENTS.md ng directory na iyon. Ang impormasyong direktang mababasa ng agent mula sa code, gaya ng directory tree o dependency list, ay hindi dapat ilagay sa alinman sa mga ito.