Nested AGENTS.md: Tamang Layout para sa Monorepo

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 naaangkop sa lahat ng bahagi, pati ang mapa kung saan matatagpuan ang iba pang file. Nilalaman naman ng bawat service file ang mga command at convention na 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 hindi nito ginagamit ang context para sa front end na hindi naman nito gagalawin.

Walang kailangang i-install. Convention ang AGENTS.md, at malinaw itong sinasabi ng upstream project:

Ang AGENTS.md ay karaniwang Markdown lamang. Gumamit ng anumang heading na gusto mo; simple lamang na bina-parse ng agent ang text na ibinibigay mo.

Iyan ang dahilan kung bakit mahalagang matutuhan nang maayos ang technique na ito. Hindi magbabago ang format nang hindi mo nalalaman. Ang karaniwang nasisira ay ang placement at maintenance, at responsibilidad mong ayusin ang dalawang iyon.

Bakit hindi na gumagana ang isang malaking root AGENTS.md?

Ang iisang 600-line na AGENTS.md sa root ng repository na naglalaman ng isang web app, background worker, at Terraform directory ay pumapalya sa apat na magkakahiwalay na paraan.

Nagiging luma ito dahil walang may-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 nakakakita sa mismatch. Pagkalipas ng anim na linggo, naglalarawan pa rin ang file ng build step na wala na, at nakalimutan na ng taong nagdulot ng problema ang pagbabagong iyon.

Kumakain ito ng context sa bawat task. Nilo-load ang mga file na ito sa simula ng session, bago pa malaman ng agent kung ano ang ipapagawa mo. May espesipikong 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 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 sa iisang file, tama lamang ang bawat rule sa ilang sitwasyon, 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.

Napupuno ito ng mga fact na mababasa naman ng agent mula sa code. Kasama rito ang directory tree, dependency list, at buod ng ginagawa ng bawat package. Ginagamit ang /doctor check ng Claude Code upang alisin mismo 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 test na alam ko para malaman kung dapat bang manatili sa file ang isang line.

Binabasa ba ng agent ang root file, o ang pinakamalapit na file lamang?

Dito kadalasang nagkakamali ang mga tao tungkol sa model, kaya makabubuting sipiin ang upstream convention sa halip na i-paraphrase 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 na file at maaaring maglaman ang bawat subproject ng mga tagubiling angkop dito.

Tungkol naman sa mga conflict:

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

Para sa maraming tao, ang "nangingibabaw" ay nangangahulugang "binabalewala ang root file". Hindi ito tama. Sa mga tool na nagpapatupad ng convention na ito, binabasa at pinagsasama ang bawat file mula sa repository root hanggang sa working directory. Ang pinakamalapit na file lamang ang nangingibabaw 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 mga blangkong linya. Ang mga file na mas malapit sa kasalukuyang directory mo ang uma-override sa naunang guidance." Parehong path ang sinusundan ng Claude Code para sa sarili nitong file name. Ang mga file sa directory hierarchy sa itaas ng working directory ay "ganap na nilo-load sa pagsisimula", at "Pinagsasama ang lahat ng natuklasang file sa context sa halip na mag-override sa 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 na para bang babayaran mo ito nang 100 beses bawat linggo. Walang cost ang per-directory file kapag sa ibang lugar nagtatrabaho ang agent, kaya mas mura roon ang detalye at doon ito dapat ilagay.

Sinuri ang behavior na ito batay sa dokumentasyon ng Codex at Claude Code noong August 2026. Bahagyang magkakaiba ang implementasyon ng mga tool sa convention na ito, at nagbabago rin ang mga ito, kaya kumpirmahin ang loading rules para sa agent na ginagamit ng inyong team.

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. Tinutukoy nito kung saan titingin, at naglalaman lamang ito ng mga panuntunang nalalapat 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 file para sa bawat directory, 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 kailangang patakbuhin bago pumasa ang mga test. Dito naman sa infra file inilalagay 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 tukuyin 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 paghahati ng upstream: sinasabi nitong ang "README.md files are for humans: quick starts, project descriptions, and contribution guidelines", habang ang AGENTS.md ay naglalaman ng "the extra, sometimes detailed context coding agents need: build steps, tests, and conventions." Tinutukoy ng paghahati sa pagitan ng AGENTS.md at README na para sa tao ang hangganang ito, pangungusap bawat pangungusap, at tinatalakay naman ng isang DESIGN.md na nagtatala kung bakit ganoon ang pagkakabuo ng code ang ikatlong file—ang nagpapaliwanag ng mga desisyon sa halip na mga command.

Sino ang nag-a-update ng file kapag nagbabago ang code?

Isang rule lang ito, at dapat itong ilagay sa root file: ang sinumang nagbabago ng code sa isang directory ang dapat ding mag-update ng AGENTS.md ng directory na iyon sa parehong commit.

Gumagana ito para sa mekanikal na dahilan, hindi dahil sa kultura. Nasa parehong diff ng code ang file para sa bawat directory, kaya sabay na nakikita ng reviewer ng pull request ang mga ito. Para sa lahat ang root file, na nangangahulugang walang partikular na may-ari nito, at hindi ito kailanman kasama sa diff na binabasa na ng isang tao.

Suportahan ang rule sa pamamagitan ng check sa pull request. Hinahanap nito ang pinakamalapit na AGENTS.md sa itaas ng bawat binagong file, pagkatapos ay nag-uulat kapag hindi binago 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 ng 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 blank line sa file para maging green ang CI. Mas mababa ang halaga ng file na binago para lamang masiyahan ang isang robot kaysa sa file na walang pagbabago. 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 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")"
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 nangangahulugang mali ang file kapag anim na buwan na mas luma ang petsa ng dokumentasyon kaysa sa petsa ng code. Sinasabi lamang nito kung aling file ang dapat mong basahin muna, at iyon lang ang kailangan mo mula sa pagsusuring tumatagal ng isang segundo.

Hanapin ang mga path na wala na. May isang partikular na paraan kung paano naluluma ang documentation: patuloy nitong inilalarawan ang code na dinelete 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. Tina-flag din nito ang mga glob gaya ng src/**/*.ts at anumang URL na nilagyan mo ng quote, dahil parehong may slash ang mga ito at wala sa disk bilang file.

Ang sintomas sa 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 directory

Kaya ginagawa nito ang makatwirang hakbang at nagsusulat ng sarili nitong fetch wrapper. Iyan ang tunay na gastos ng lumang file. Hindi binabalewala ng agent ang iyong documentation. Sinusunod nito ang documentation, napupunta sa path na dinelete tatlong buwan na ang nakalipas, at muling binubuo ang code na mayroon ka na. Ang isang skill gaya ng Ponytail, na naglilimita sa agent sa pinakamaliit na gumaganang pagbabago, ay nagpapabawas sa ganitong instinct na muling bumuo, pero hindi nito mahahanap ang helper na itinuro ng file sa maling lugar.

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

Hindi, at mahalagang sabihin ito dahil dito nakabatay ang nested layout. Noong August 2026, sinasabi ng documentation: “Binabasa ng Claude Code ang CLAUDE.md, hindi ang AGENTS.md.” Gumagana pa rin ang pattern; kailangan mo lang ng CLAUDE.md sa tabi ng bawat AGENTS.md.

Tama ang import form kapag gusto mong magdagdag ng mga tool-specific na linya sa 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 nang tool-specific na kailangang idagdag.

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 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 makagawa ng symlink, kaya gamitin na lang ang @AGENTS.md import doon.

May isang karaniwang problema rito. Pagkatapos ng /compact, muling binabasa mula sa disk ang root file, pero hindi muling ipinapasok ang mga nested file sa mga subdirectory. Babalik ang mga ito sa susunod na pagbasa ng agent ng isang file sa directory na iyon. Kung tila hindi na gumagana ang isang per-directory rule sa kalagitnaan ng mahabang session, karaniwan itong dahilan. Maaibalik ito sa pamamagitan ng pag-touch sa anumang file sa directory.

Paano ito naiiba sa agent memory o sa isang skill?

Magkakamukha ang mga mekanismong ito, pero magkakaiba ang paraan ng pag-fail ng mga ito. Kaya mahalagang tukuyin nang tama kung alin ang kailangan mo.

Ang AGENTS.md ay isinusulat mo, kino-commit sa git, nire-review sa pull request, at pare-pareho para sa lahat ng nagco-clone ng repository. Ang agent memory ay isinusulat ng agent, ini-store sa labas ng repository, at lokal sa isang machine. Pareho ang ipinapakitang pagkakaiba sa documentation ng Claude Code: naglalaman ang CLAUDE.md ng "Instructions and rules" na ikaw ang sumusulat, habang ang auto memory ay naglalaman ng "Learnings and patterns" na Claude ang sumusulat. Hindi rin sine-share sa ibang machine ang memory directory. Simple ang pagsusuri. Kung kailangang maging totoo ang isang fact para sa kasamahan mong gumagamit ng bagong clone, hindi ito dapat nasa memory. Sinasaklaw ng Paano nananatili ang agent memory sa magkakaibang session ang bahaging iyon.

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 documentation ng Claude Code ng praktikal na panuntunan: "If an entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule instead." Ang ikalawang bahagi ng pangungusap na iyon ang eksaktong problemang nilulutas ng nested AGENTS.md. Ang unang bahagi naman ang layunin ng agent skills, at kapag kailangan ang parehong procedure sa higit sa isang repository, i-share ang skill sa iba’t ibang repo sa halip na i-paste ang parehong mga talata sa sampung magkakaibang AGENTS.md file.

Ayon sa upstream, "at time of writing the main OpenAI repo has 88 AGENTS.md files". Iyon mismo ang buong punto. Hindi kailangan ng malaking repository ng mas malaking file. Mas kailangan nito ng mas maraming maliliit na file. Bawat isa ay dapat 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 idinaragdag ba ito rito?

Idinaragdag ito rito. Sinasabi ng upstream na “the closest one takes precedence,” na naglalarawan kung ano ang mangyayari kapag may conflict, hindi kung ano ang ilo-load. Ang Codex ay “concatenates files from the root down, joining them with blank lines,” at pinagdurugtong 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 mananaig kapag magkaiba ang instructions 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 dapat kahaba ang root AGENTS.md?

Dapat sapat itong maikli para hindi ka mabahala kung ilalagay ito sa unahan 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 idodokumento ng root file mo ang apat na serbisyo, karamihan dito ay hindi kakailanganin para sa isang partikular na task. Ilipat ang mga detalye sa mga per-directory file at mag-iwan ng map.

Paano ko mapipigilan na maging luma ang mga file na ito?

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

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

Hindi. Noong August 2026, nakasaad sa 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 magbibigay-daan sa iyong magdagdag ng Claude-specific instructions sa ibaba nito. Gumagana ang symlink na ginawa gamit ang ln -s AGENTS.md CLAUDE.md kapag wala nang ibang idaragdag, ngunit sa Windows kailangan nito ng Administrator rights o Developer Mode. Patakbuhin ang /context sa isang session at tiyaking lumilitaw ang file sa ilalim ng Memory files.

Saan ko ilalagay ang rule na paminsan-minsan lang nalalapat?

Huwag sa AGENTS.md. Ilo-load ang file na iyon sa bawat session, kaya ang bawat line dito ay nakikipag-agawan ng atensyon sa request na aktuwal mong tina-type. Ang procedure na may ilang hakbang at paminsan-minsang kailangan ay dapat ilagay sa isang skill, na nilo-load kapag kinakailangan. Ang rule na nalalapat sa isang directory lamang ay dapat ilagay sa AGENTS.md ng directory na iyon. Ang impormasyong mababasa mismo ng agent mula sa code, gaya ng directory tree o dependency list, ay hindi dapat ilagay sa alinman sa mga ito.