Nested AGENTS.md para sa Monorepo: Tamang Setup

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 AGENTS.md na may 600 linya sa root ng repository na naglalaman ng web app, background worker, at Terraform directory ay pumapalya sa apat na magkahiwalay na paraan.

Nagiging luma ito dahil walang nagmamay-ari rito. Ang engineer na nagpapalit ng pangalan ng isang 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 nakakakita sa mismatch. Pagkalipas ng 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.

Kumakain ito ng context sa bawat task. Nilo-load ang mga file na ito sa simula ng session, bago malaman ng agent kung ano ang ipapagawa mo. May tiyak na rekomendasyon 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 pinagsamang laki ng mga ito, ang default na project_doc_max_bytes. Ang root file na nagdodokumento ng apat na serbisyo ay ginagamit 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 ang mga ito sa isang 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 rules contradict each other, Claude may pick one arbitrarily." Inaalis ng per-directory file ang paghuhula dahil isa lamang sa dalawang rule ang nasa context sa bawat pagkakataon. Kapag paulit-ulit na nilalaktawan ang isang rule na sigurado kang malinaw mong isinulat, mas mabuting alamin muna ang mga dahilan kung bakit hindi nailalapat ang isang instruction kaysa baguhin ang wording nito sa ikaapat na pagkakataon.

Napupuno ito ng mga impormasyong mababasa naman ng agent mula sa code. Isang directory tree, listahan ng dependency, at buod ng ginagawa ng bawat package. Umiiral ang /doctor check ng Claude Code upang alisin mismo ang ganitong content. Inaalis 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." Ang pangungusap na iyon ang pinakamainam na test na alam ko upang matukoy kung dapat bang nasa file ang isang linya.

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 sulit sipiin ang upstream convention sa halip na ibuod 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 nangingibabaw ang pinakamalapit at maaaring magkaroon ng mga tagubiling angkop sa bawat subproject.

At tungkol sa mga conflict:

Ang pinakamalapit na AGENTS.md sa file na ine-edit ang mananaig; nangingibabaw sa lahat ang mga tahasang user prompt sa chat.

Para sa maraming tao, ang "nangingibabaw" ay nangangahulugang "hindi pinapansin ang root file". Hindi ito tama. Sa mga tool na nagpapatupad ng convention na ito, binabasa at pinagsasama ang bawat file sa path mula sa repository root pababa hanggang sa working directory. Mananaig lamang ang pinakamalapit na file kapag magkaiba ang sinasabi ng dalawang file tungkol sa parehong paksa.

Malinaw ang Codex sa mekanismo: "Pinagdudugtong ng Codex ang mga file mula root pababa at pinaghihiwalay ang mga ito gamit ang mga blangkong linya. Ino-override ng mga file na mas malapit sa kasalukuyang directory ang naunang guidance." Sinusundan din ng Claude Code ang parehong path para sa sarili nitong file name. Ang mga file sa directory hierarchy sa itaas ng working directory ay "nilo-load nang buo sa pagsisimula", at "Pinagdudugtong ang lahat ng natuklasang file sa context sa halip na i-override ang isa't isa." Iba ang pag-uugali ng mga directory sa ibaba ng working directory: nilo-load ng Claude Code ang mga file na iyon kapag kinakailangan, "kapag nagbabasa si Claude ng mga file sa mga directory na iyon."

May dalawang praktikal na bunga ito. Ang root file ay prefix sa bawat session sa repository, kaya ituring ang bawat linya roon bilang linyang babayaran mo nang isandaang beses bawat linggo. Walang gastos ang per-directory file kapag nagtatrabaho ang agent sa ibang lugar, kaya mura ang detalye roon at doon ito dapat ilagay.

Sinuri ang pag-uugaling ito batay sa dokumentasyon ng Codex at Claude Code noong August 2026. Bahagyang magkakaiba ang pagpapatupad ng convention sa bawat tool, at nagbabago rin ang mga ito, kaya kumpirmahin ang mga tuntunin sa pag-load 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 scripts

Sadyang 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"
done

Sa 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 updated

Gawin 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 ko matutukoy kung lipas na ang isang AGENTS.md?

May dalawang check na maaari mong patakbuhin ngayon, at may isang sintomas na makikita mo sa loob ng session.

Ihambing 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")"
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

Hindi awtomatikong nangangahulugan na mali ang file kung anim na buwan na mas luma ang petsa ng dokumentasyon kaysa sa petsa ng code. Ipinapakita lamang nito kung aling file ang dapat mong basahin muna. Sapat na iyon para sa isang check na tumatagal ng isang segundo.

Hanapin ang mga path na wala na. May isang partikular na paraan ng pagkaluma ng dokumentasyon: patuloy nitong inilalarawan ang code na tinanggal na. Nakasulat sa backticks ang bawat path sa mga file na ito, kaya madali silang kunin at i-test.

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

Basahin ang output sa halip na isama ito sa CI. Nagfa-flag din ito ng mga glob gaya ng src/**/*.ts at anumang URL na nasa quotation marks, dahil parehong may slash at wala sa mga ito ang file sa disk.

Ang sintomas sa isang session. Binabasa ng agent ang file, sinusubukang buksan ang src/api/client.ts dahil iyon ang nakasaad sa file, at ibinabalik ng tool ang:

No such file or directory

Kaya ginagawa nito ang makatuwirang hakbang at isinusulat ang sarili nitong fetch wrapper. Iyan ang tunay na gastos ng lipas na file. Hindi binabalewala ng agent ang dokumentasyon mo. Sinusunod nito ang dokumentasyon, napupunta sa path na tinanggal tatlong buwan na ang nakalipas, at muling binubuo ang code na mayroon ka na. Ang skill gaya ng Ponytail, na pumipigil sa agent na gumawa ng higit sa pinakamaliit na gumaganang pagbabago, ay nagpapababa sa posibilidad na muli nitong buuin ang code, pero hindi nito mahahanap ang helper na itinuro ng file mo sa maling lugar.

Binabasa ba ng Claude Code ang mga AGENTS.md file?

Hindi. Mahalagang sabihin ito nang malinaw dahil nakadepende rito ang nested layout. Noong August 2026, nakasaad sa documentation: “Binabasa ng Claude Code ang CLAUDE.md, hindi ang AGENTS.md.” Gumagana pa rin ang pattern; kailangan mo lamang ng CLAUDE.md sa tabi ng bawat AGENTS.md.

Tama ang import form kapag gusto mong magdagdag ng mga tool-specific line sa ibabaw ng mga shared line. 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 kang 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.md

Walang inilalabas na output ang ln kapag matagumpay itong tumakbo, 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, kaya gamitin na lamang ang @AGENTS.md import doon.

May isang mahalagang limitasyon dito. Pagkatapos ng /compact, muling binabasa mula sa disk ang root file, pero hindi awtomatikong muling ini-inject ang mga nested file sa mga subdirectory. Babalik ang mga ito sa susunod na magbasa ang agent ng file sa directory na iyon. Kung tila hindi na naa-apply ang isang per-directory rule sa kalagitnaan ng mahabang session, karaniwan itong ang dahilan. Ang pag-touch sa anumang file sa directory ay magbabalik dito.

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 “the closest one takes precedence,” na naglalarawan kung ano ang nangyayari kapag may conflict, hindi kung ano ang nilo-load. “Concatenates files from the root down, joining them with blank lines” ang ginagawa ng Codex, at kino-concatenate 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 ay nananalo lamang kapag magkaiba ang instructions ng dalawang file tungkol sa iisang paksa. Isulat nang isang beses sa root ang mga shared rule, at huwag ulitin ang mga ito sa bawat directory.

Gaano dapat kalaki ang root AGENTS.md?

Dapat sapat itong maliit para hindi ka mabahala kung ilalagay ito sa ibabaw ng bawat request na ginagawa mo sa repository na iyon, dahil iyon mismo ang nangyayari. Iminumungkahi ng documentation ng Claude Code na panatilihing wala sa 200 lines ang bawat file at nagbababala na ang mas mahahabang file ay “reduce adherence.” Bilang default, humihinto ang Codex sa pag-merge ng mga instruction file kapag umabot sa pinagsamang 32 KiB. 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 mapipigilan na maging luma ang mga file na ito?

Maglagay ng isang rule sa root file: dapat i-update ng sinumang nagbabago ng code sa isang directory ang AGENTS.md ng directory na iyon sa parehong commit. Ang paglalagay ng file katabi ng code ang nagpapatibay sa rule, dahil mapupunta ang pagbabago sa parehong pull request diff na sinusuri na ng isang tao. Magdagdag ng CI warning na nagmamapa sa bawat binagong path patungo sa pinakamalapit na AGENTS.md sa itaas nito, at paminsan-minsan ay ikumpara ang git log -1 --format=%cs sa bawat file sa parehong command na pinatakbo sa directory na dinodokumento nito.

Binabasa ba ng Claude Code ang mga AGENTS.md file?

Hindi. Noong Agosto 2026, sinasabi ng documentation na “Claude Code reads CLAUDE.md, not AGENTS.md.” Gumawa ng CLAUDE.md sa parehong directory, na may @AGENTS.md sa unang line. Ilo-load nito ang shared file at hahayaan kang magdagdag ng Claude-specific instructions sa ibaba nito. Gumagana ang symlink na ginawa gamit ang ln -s AGENTS.md CLAUDE.md kapag wala nang kailangang idagdag, ngunit sa Windows ay kailangan nito ng Administrator rights o Developer Mode. Patakbuhin ang /context sa isang session at kumpirmahing lumilitaw ang file sa ilalim ng Memory files.

Saan ko ilalagay ang rule na mahalaga lamang paminsan-minsan?

Huwag sa AGENTS.md. Nilo-load ang file na iyon sa bawat session, kaya nakikipag-agawan ang bawat line nito sa atensyon kasama ng request na aktuwal mong tina-type. Ang procedure na may ilang step at kailangan lamang paminsan-minsan 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.