Cara Guna AGENTS.md Bersarang dalam Monorepo

Apakah maksud AGENTS.md bersarang dalam monorepo

AGENTS.md bersarang dalam monorepo bermaksud satu fail kecil diletakkan di punca repositori dan satu lagi fail di dalam setiap direktori servis. Fail punca mengandungi beberapa peraturan yang terpakai di mana-mana, serta peta lokasi fail-fail lain. Setiap fail servis mengandungi arahan dan konvensyen khusus untuk direktori tersebut sahaja. Ejen yang menyunting services/worker/queue.py kemudiannya membaca fail punca dan fail pekerja, dan tidak menggunakan sebarang konteks pada bahagian hadapan (front end) yang tidak akan disentuhnya.

Tiada apa-apa yang perlu dipasang. AGENTS.md hanyalah satu konvensyen, dan projek huluan menyatakan perkara ini dengan jelas:

AGENTS.md hanyalah Markdown standard. Gunakan sebarang tajuk yang anda suka; ejen hanya menghuraikan teks yang anda sediakan.

Itulah sebabnya teknik ini berbaloi untuk dipelajari dengan betul. Formatnya tidak akan berubah. Perkara yang boleh terjejas ialah penempatan dan penyelenggaraan, dan kedua-duanya adalah tanggungjawab anda.

Mengapa satu fail AGENTS.md yang besar di direktori root berhenti berfungsi?

Satu fail AGENTS.md sepanjang 600 baris di root repositori yang mengandungi aplikasi web, pekerja latar belakang (background worker) dan direktori Terraform gagal dalam empat cara berbeza.

Ia menjadi lapuk kerana tiada siapa yang memilikinya. Jurutera yang menamakan semula skrip ujian dalam apps/web sedang menyunting fail di bawah apps/web. Fail AGENTS.md di root tidak termasuk dalam diff tersebut, jadi tiada penyemak yang melihat ketidakpadanan itu. Enam minggu kemudian, fail tersebut menerangkan langkah binaan yang tidak lagi wujud, dan orang yang merosakkannya telah melupakan perubahan tersebut.

Ia memakan konteks pada setiap tugasan. Fail-fail ini dimuatkan pada permulaan sesi, sebelum ejen mengetahui apa yang akan anda tanya. Dokumentasi Claude Code meletakkan had padanya: "sasarkan bawah 200 baris bagi setiap fail CLAUDE.md. Fail yang lebih panjang menggunakan lebih banyak konteks dan mengurangkan pematuhan." Codex berhenti menggabungkan fail arahan sebaik sahaja saiz gabungannya mencapai 32 KiB, iaitu project_doc_max_bytes lalai. Fail root yang mendokumentasikan empat servis membelanjakan bajet tersebut untuk tiga daripadanya bagi setiap tugasan.

Arahan mula bercanggah antara satu sama lain. Direktori web mahukan pnpm test. Pekerja mahukan pytest -q. Apabila ditulis dalam satu fail, setiap peraturan hanya betul pada waktu tertentu, jadi ejen terpaksa meneka yang mana satu terpakai. Dokumentasi Claude Code menerangkan hasilnya: "jika dua peraturan bercanggah antara satu sama lain, Claude mungkin memilih salah satu secara sewenang-wenangnya." Fail bagi setiap direktori menghapuskan tekaan tersebut, kerana hanya satu daripada dua peraturan itu yang akan berada dalam konteks pada satu-satu masa.

Ia dipenuhi dengan fakta yang ejen boleh baca daripada kod. Struktur pokok direktori, senarai dependensi, ringkasan fungsi setiap pakej. Semakan /doctor Claude Code wujud untuk membuang perkara ini. Ia "memotong kandungan yang boleh diperoleh Claude daripada pangkalan kod, seperti susun atur direktori, senarai dependensi dan gambaran keseluruhan seni bina" serta mengekalkan "perangkap, rasional dan konvensyen yang berbeza daripada tetapan lalai alat." Ayat itu adalah ujian terbaik yang saya tahu untuk menentukan sama ada sesuatu baris itu patut berada dalam fail tersebut atau tidak.

Adakah ejen membaca fail root, atau hanya fail yang paling hampir?

Di sinilah kebanyakan orang tersalah faham tentang model ini, jadi adalah wajar untuk memetik konvensyen hulu (upstream) daripada mengolahnya semula:

Letakkan satu lagi AGENTS.md di dalam setiap pakej. Ejen secara automatik membaca fail yang paling hampir dalam pepohon direktori, jadi fail yang paling dekat akan diutamakan dan setiap subprojek boleh menghantar arahan yang disesuaikan.

Dan mengenai konflik:

AGENTS.md yang paling hampir dengan fail yang disunting akan menang; gesaan sembang pengguna yang eksplisit mengatasi segala-galanya.

"Diutamakan" dibaca oleh ramai orang sebagai "fail root diabaikan". Ia tidak diabaikan. Dalam alatan yang melaksanakan konvensyen ini, setiap fail pada laluan dari root repositori sehingga ke direktori kerja dibaca dan digabungkan bersama. Fail yang paling hampir hanya menang apabila dua fail menyatakan perkara yang berbeza mengenai subjek yang sama.

Codex menyatakan mekanisme ini secara eksplisit: "Codex mencantumkan fail dari root ke bawah, menyambungkannya dengan baris kosong. Fail yang lebih dekat dengan direktori semasa anda mengatasi panduan terdahulu." Claude Code menggunakan laluan yang sama untuk nama failnya sendiri. Fail dalam hierarki direktori di atas direktori kerja "dimuatkan sepenuhnya semasa pelancaran", dan "Semua fail yang ditemui dicantumkan ke dalam konteks dan bukannya mengatasi satu sama lain." Direktori di bawah direktori kerja berkelakuan berbeza: Claude Code memuatkan fail tersebut atas permintaan, "apabila Claude membaca fail dalam direktori tersebut."

Dua akibat praktikal akan berlaku. Fail root merupakan awalan pada setiap sesi dalam repositori, jadi anggap setiap baris di sana sebagai baris yang anda bayar seratus kali seminggu. Fail per-direktori tidak menelan kos apabila ejen bekerja di tempat lain, yang bermaksud perincian adalah murah di sana dan sepatutnya diletakkan di sana.

Kelakuan ini telah disemak terhadap dokumentasi Codex dan Claude Code pada Ogos 2026. Alatan melaksanakan konvensyen ini dengan sedikit perbezaan dan ia memang berubah, jadi sahkan peraturan pemuatan untuk mana-mana ejen yang dijalankan oleh pasukan anda.

Susun atur yang berfungsi untuk repositori dengan tiga servis

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

Fail akar sengaja dibuat ringkas. Ia menyatakan lokasi untuk mencari fail lain, dan hanya mengandungi peraturan yang terpakai dalam setiap direktori.

# 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.

Fail bagi setiap direktori ialah tempat perincian diletakkan, dan ia boleh menjadi sepanjang yang diperlukan oleh direktori tersebut.

# 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.

Fail pekerja mempunyai bentuk yang sama dengan kandungan yang berbeza: arahan pemasangan, pytest -q, sebab mengapa pengguna mesti kekal idempoten, dan migrasi yang perlu dijalankan sebelum ujian berjaya. Fail infrastruktur ialah tempat anda menulis peraturan yang menghalang ejen daripada melakukan kerosakan. Jangan sekali-kali menjalankan terraform apply. Jalankan terraform plan dan berhenti di situ, serta namakan backend keadaan yang telah dikonfigurasikan supaya ejen tidak cuba memulakan yang baharu.

Perhatikan perkara yang tiada dalam fail-fail ini: penerangan tentang tujuan setiap servis. Itu adalah untuk manusia. Upstream melukis garisan yang sama, menyatakan "fail README.md adalah untuk manusia: panduan permulaan pantas, penerangan projek, dan garis panduan sumbangan", manakala AGENTS.md membawa "konteks tambahan yang kadangkala terperinci yang diperlukan oleh ejen pengekodan: langkah binaan, ujian, dan konvensyen." pemisahan antara AGENTS.md dan README yang ditujukan untuk manusia meneliti sempadan tersebut ayat demi ayat, dan fail DESIGN.md yang merekodkan sebab kod dibentuk sedemikian merangkumi fail ketiga, iaitu fail yang menjelaskan keputusan dan bukannya arahan.

Siapa yang mengemas kini fail apabila kod berubah?

Satu peraturan, dan ia diletakkan dalam fail root: sesiapa yang menukar kod dalam sesuatu direktori perlu mengemas kini AGENTS.md direktori tersebut dalam commit yang sama.

Ini berfungsi atas sebab mekanikal, bukan budaya. Fail per-direktori terletak dalam diff yang sama dengan kod, jadi penyemak pull request melihat kedua-duanya sekali gus. Fail root adalah milik semua orang, yang bermaksud ia milik sesiapa pun, dan ia tidak pernah berada dalam diff yang sedang dibaca oleh sesiapa.

Sokong peraturan ini dengan semakan pada pull request. Ia mencari AGENTS.md terdekat di atas setiap fail yang diubah, kemudian melaporkan apabila fail tersebut tidak disentuh.

#!/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

Pada cawangan yang mengubah suai API client tanpa menyentuh dokumentasi, outputnya kelihatan seperti ini:

note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updated

Jadikannya sebagai amaran dan bukannya kegagalan. Sekatan keras akan mengajar orang untuk menambah baris kosong pada fail supaya CI menjadi hijau, dan fail yang disunting untuk memuaskan robot adalah lebih tidak bernilai daripada tiada fail langsung. Amaran memberikan penyemak soalan untuk ditanya, yang merupakan bahagian yang sebenarnya berkesan.

Bagaimanakah cara mengesan AGENTS.md yang sudah lapuk?

Terdapat dua pemeriksaan yang boleh anda jalankan hari ini, dan satu simptom yang akan anda lihat di dalam sesi.

Bandingkan usia setiap fail dengan usia kod yang diterangkannya. %cs mencetak tarikh komit sebagai 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

Tarikh dokumen yang enam bulan ketinggalan berbanding tarikh kod tidak membuktikan fail tersebut salah. Ia hanya memberitahu anda fail mana yang perlu dibaca dahulu, dan itu sahaja yang anda perlukan daripada pemeriksaan yang mengambil masa satu saat.

Cari laluan yang tidak lagi wujud. Dokumentasi menjadi lapuk dengan cara yang sangat khusus: ia terus menerangkan kod yang telah dipadamkan. Setiap laluan dalam fail ini ditulis dalam backtick, jadi ia mudah untuk dikeluarkan dan diuji.

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

Baca output tersebut dan jangan sambungkan proses ini ke dalam CI. Ia juga akan menandakan glob seperti src/**/*.ts dan sebarang URL yang anda petik, kerana kedua-duanya mengandungi garis miring (slash) dan bukan fail pada cakera.

Simptom dalam sesi. Ejen membaca fail tersebut, cuba membuka src/api/client.ts kerana fail itu mengarahkannya berbuat demikian, dan alat tersebut mengembalikan:

No such file or directory

Jadi, ia melakukan tindakan yang munasabah dengan menulis pembungkus fetch miliknya sendiri. Itulah kos sebenar bagi fail yang lapuk. Ejen tidak mengabaikan dokumentasi anda. Ia mengikut dokumentasi tersebut, sampai ke laluan yang telah dipadamkan tiga bulan lalu, dan membina semula kod yang sudah anda miliki. Kemahiran seperti Ponytail, yang mengehadkan ejen kepada perubahan terkecil yang berfungsi, menjadikan naluri membina semula itu lebih jarang berlaku, tetapi ia tidak dapat mencari pembantu yang ditunjukkan oleh fail anda di tempat yang salah.

Adakah Claude Code membaca fail AGENTS.md?

Tidak, dan perkara ini perlu ditegaskan kerana susun atur bersarang bergantung kepadanya. Setakat Ogos 2026, dokumentasi menyatakan: "Claude Code membaca CLAUDE.md, bukan AGENTS.md." Corak ini masih berfungsi, anda hanya perlu meletakkan CLAUDE.md di sebelah setiap AGENTS.md.

Bentuk import adalah tepat apabila anda mahukan baris khusus alat di atas baris yang dikongsi. Letakkan ini dalam services/worker/CLAUDE.md:

@AGENTS.md

## Claude Code

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

Bentuk symlink adalah tepat apabila tiada perkara khusus alat untuk ditambah.

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 tidak mencetak apa-apa apabila berjaya, jadi semak senarai tersebut: apps/web/CLAUDE.md -> AGENTS.md. Kemudian mulakan sesi dan jalankan /context, di mana fail yang dimuatkan akan muncul di bawah Memory files. Pada Windows, symlink memerlukan hak Administrator atau Developer Mode, jadi gunakan import @AGENTS.md di sana.

Satu perangkap berkaitan dengan perkara ini. Selepas /compact, fail akar dibaca semula daripada cakera, tetapi fail bersarang dalam subdirektori tidak disuntik semula. Fail tersebut akan kembali pada kali seterusnya ejen membaca fail dalam direktori itu. Jika peraturan per-direktori kelihatan berhenti berfungsi di tengah-tengah sesi yang panjang, itulah puncanya, dan menyentuh mana-mana fail dalam direktori tersebut akan mengaktifkannya semula.

Bagaimanakah ini berbeza daripada memori ejen, atau daripada kemahiran?

Mekanisme ini kelihatan serupa tetapi gagal dengan cara yang berbeza, jadi adalah penting untuk menentukan dengan tepat mekanisme mana yang anda perlukan.

AGENTS.md ditulis oleh anda, di-commit ke git, disemak dalam pull request, dan adalah sama bagi sesiapa sahaja yang melakukan clone repositori tersebut. Memori ejen ditulis oleh ejen, disimpan di luar repositori, dan bersifat setempat pada satu mesin. Dokumentasi Claude Code menetapkan garis yang sama: CLAUDE.md menyimpan "Arahan dan peraturan" yang anda tulis, memori automatik menyimpan "Pembelajaran dan corak" yang ditulis oleh Claude, dan direktori memori tidak dikongsi merentasi mesin. Ujiannya mudah. Jika sesuatu fakta perlu benar bagi rakan sekerja yang melakukan clone baharu, fakta itu tidak boleh berada dalam memori. Bagaimana memori ejen dikekalkan antara sesi merangkumi separuh daripada gambaran tersebut.

Kemahiran (skill) adalah perkara ketiga. AGENTS.md ialah konteks yang dimuatkan setiap sesi; kemahiran ialah prosedur yang dimuatkan apabila ia diperlukan. Dokumentasi Claude Code memberikan peraturan yang boleh digunakan: "Jika entri tersebut merupakan prosedur berbilang langkah atau hanya penting untuk satu bahagian pangkalan kod, pindahkannya ke kemahiran atau peraturan yang dikhususkan mengikut laluan (path-scoped)." Separuh kedua ayat tersebut adalah tepat apa yang diselesaikan oleh AGENTS.md bersarang. Separuh pertama adalah tujuan kemahiran ejen, dan apabila prosedur yang sama diperlukan dalam lebih daripada satu repositori, kongsi kemahiran tersebut merentasi repositori daripada menampal perenggan yang sama ke dalam sepuluh fail AGENTS.md yang berbeza.

Upstream menyatakan bahawa "pada masa penulisan, repositori utama OpenAI mempunyai 88 fail AGENTS.md". Nombor itu adalah hujah keseluruhannya. Repositori yang besar tidak memerlukan fail yang lebih besar. Ia memerlukan lebih banyak fail kecil, setiap satunya terletak bersebelahan dengan kod yang diterangkannya, dan setiap satunya dimiliki oleh sesiapa sahaja yang terakhir mengubah kod tersebut.

FAQ

Adakah AGENTS.md bersarang menggantikan fail akar atau menambah kepadanya?

Ia menambah kepadanya. Pihak hulu menyatakan "fail yang paling hampir diutamakan", yang menerangkan perkara yang berlaku apabila terdapat konflik, bukannya apa yang dimuatkan. Codex "mencantumkan fail dari akar ke bawah, menyambungkannya dengan baris kosong", dan Claude Code mencantumkan setiap fail yang ditemuinya semasa menyusuri dari direktori kerja dan bukannya mengatasi fail tersebut. Fail yang paling hampir hanya menang apabila dua fail memberikan arahan berbeza mengenai subjek yang sama. Tulis peraturan kongsi di akar sekali sahaja, dan jangan ulangi dalam setiap direktori.

Berapa besarkah AGENTS.md akar sepatutnya?

Cukup kecil sehingga anda tidak keberatan jika ia ditampal pada setiap permintaan yang anda buat dalam repositori tersebut, kerana itulah yang berlaku. Dokumentasi Claude Code mencadangkan sasaran bawah 200 baris setiap fail dan memberi amaran bahawa fail yang lebih panjang "mengurangkan pematuhan". Codex berhenti menggabungkan fail arahan pada 32 KiB secara gabungan secara lalai. Jika fail akar anda mendokumenkan empat servis, kebanyakan daripadanya adalah beban sia-sia untuk mana-mana tugas tunggal. Pindahkan perincian ke bawah ke dalam fail setiap direktori dan tinggalkan peta di belakang.

Bagaimanakah cara saya menghalang fail ini daripada menjadi lapuk?

Letakkan satu peraturan dalam fail akar: sesiapa yang menukar kod dalam sesuatu direktori perlu mengemas kini AGENTS.md direktori tersebut dalam commit yang sama. Meletakkan fail di sebelah kod adalah perkara yang menjadikan peraturan itu kekal, kerana perubahan itu kemudiannya akan masuk ke dalam diff pull request yang sama yang sedang dibaca oleh manusia. Tambahkan amaran CI yang memetakan setiap laluan yang ditukar kepada AGENTS.md terdekat di atasnya, dan sekali-sekala bandingkan git log -1 --format=%cs pada setiap fail dengan arahan yang sama yang dijalankan pada direktori yang didokumenkannya.

Adakah Claude Code membaca fail AGENTS.md?

Tidak. Setakat Ogos 2026, dokumentasi menyatakan "Claude Code membaca CLAUDE.md, bukan AGENTS.md." Cipta CLAUDE.md dalam direktori yang sama dengan @AGENTS.md pada baris pertama, yang memuatkan fail kongsi dan membolehkan anda menambah arahan khusus Claude di bawahnya. Symlink yang dicipta dengan ln -s AGENTS.md CLAUDE.md berfungsi apabila tiada perkara tambahan untuk ditambah, walaupun pada Windows ia memerlukan hak Administrator atau Mod Pembangun. Jalankan /context dalam sesi dan sahkan fail tersebut muncul di bawah fail Memory.

Di manakah saya perlu meletakkan peraturan yang hanya penting pada masa tertentu?

Bukan dalam AGENTS.md. Fail itu dimuatkan dalam setiap sesi, jadi setiap baris di dalamnya bersaing untuk mendapatkan perhatian dengan permintaan yang anda taip sebenarnya. Prosedur dengan beberapa langkah yang diperlukan sekali-sekala tergolong dalam kemahiran (skill), yang dimuatkan atas permintaan. Peraturan yang terpakai pada satu direktori tergolong dalam AGENTS.md direktori tersebut. Fakta yang boleh dibaca oleh ejen terus daripada kod, seperti pepohon direktori atau senarai dependensi, tidak tergolong dalam mana-mana fail tersebut.