SSD Nodes Learn Hosting plans →
Panduan Matt ConnorOleh Matt Connor · Diperbarui 2026-10-28

AGENTS.md Bertingkat untuk Monorepo

Pelajari tata letak AGENTS.md bertingkat untuk monorepo: aturan root tetap ringkas, sedangkan setiap service menyimpan perintah dan konvensinya sendiri.

Makna AGENTS.md bertingkat dalam monorepo

AGENTS.md bertingkat dalam monorepo berarti ada satu file kecil di root repositori dan satu file tambahan di dalam setiap direktori service. File di root berisi beberapa aturan yang berlaku di semua tempat, serta peta lokasi file lainnya. Setiap file service berisi perintah dan konvensi yang hanya berlaku untuk direktori tersebut. Agent yang mengedit services/worker/queue.py kemudian membaca file di root dan file worker, tanpa menghabiskan konteks untuk front end yang tidak akan disentuhnya.

Tidak ada yang perlu diinstal. AGENTS.md adalah sebuah konvensi, dan proyek upstream menjelaskannya secara langsung:

AGENTS.md hanyalah Markdown standar. Gunakan heading apa pun yang Anda inginkan; agent cukup mengurai teks yang Anda berikan.

Itulah alasan teknik ini layak dipelajari dengan benar. Formatnya tidak akan berubah tanpa Anda sadari. Yang dapat menimbulkan masalah adalah penempatan dan pemeliharaannya, dan keduanya menjadi tanggung jawab Anda.

Mengapa satu AGENTS.md besar di root tidak lagi efektif?

Satu AGENTS.md berisi 600 baris di root repositori yang memuat web app, background worker, dan direktori Terraform gagal dalam empat hal terpisah.

Isinya menjadi usang karena tidak ada yang bertanggung jawab. Engineer yang mengganti nama skrip pengujian di apps/web sedang mengedit file di bawah apps/web. Root AGENTS.md tidak termasuk dalam diff tersebut, sehingga tidak ada reviewer yang melihat ketidaksesuaian itu. Enam minggu kemudian, file tersebut masih menjelaskan langkah build yang sudah tidak ada, sementara orang yang menyebabkan kerusakan itu sudah lupa pada perubahannya.

File tersebut menghabiskan context pada setiap tugas. File ini dimuat pada awal sesi, sebelum agent mengetahui permintaan Anda. Dokumentasi Claude Code mencantumkan batas yang jelas: "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." Codex berhenti menggabungkan file instruksi setelah ukuran gabungannya mencapai 32 KiB, yaitu nilai default project_doc_max_bytes. Root file yang mendokumentasikan empat service menghabiskan anggaran tersebut untuk tiga service yang tidak terkait pada setiap tugas.

Instruksi mulai saling bertentangan. Direktori web memerlukan pnpm test. Worker memerlukan pytest -q. Jika ditulis dalam satu file, setiap aturan hanya benar pada kondisi tertentu, sehingga agent harus menebak aturan mana yang berlaku. Dokumentasi Claude Code menjelaskan hasilnya: "if two instructions contradict each other, Claude may pick one arbitrarily." Memisahkan file tidak mencegah aturan lain masuk ke context. Claude Code menggabungkan setiap file instruksi yang telah dimuat, bukan membiarkan satu file menggantikan file lainnya. Karena itu, root file selalu ada. Setelah agent membuka file di apps/web dan services/worker, kedua file direktori tersebut berada dalam context secara bersamaan. Fungsi file per direktori adalah mengaitkan setiap aturan dengan direktori yang diaturnya. Cantumkan nama direktori di bagian atas file, seperti contoh di bawah ini yang menggunakan # apps/web. Dengan demikian, setiap perintah tetap menunjukkan lokasi berlakunya saat beberapa file dimuat sekaligus. Jika aturan yang Anda yakin sudah ditulis dengan jelas tetap diabaikan, menelusuri alasan instruksi tidak pernah diterapkan lebih baik daripada menulis ulang kalimatnya untuk keempat kalinya.

File tersebut dipenuhi fakta yang dapat dibaca agent dari kode. Contohnya, struktur direktori, daftar dependensi, dan ringkasan fungsi setiap package. Pemeriksaan /doctor di Claude Code dibuat untuk menghapus hal-hal tersebut. Pemeriksaan itu "cuts content Claude can derive from the codebase, such as directory layouts, dependency lists, and architecture overviews" dan mempertahankan "pitfalls, rationale, and conventions that differ from tool defaults." Kalimat tersebut adalah pengujian terbaik yang saya ketahui untuk menentukan apakah sebuah baris memang perlu dimasukkan ke dalam file.

Apakah agent membaca file root, atau hanya file terdekat?

Di sinilah kebanyakan orang keliru memahami model ini, sehingga konvensi upstream layak dikutip, bukan diparafrasekan:

Letakkan AGENTS.md lain di dalam setiap package. Agent secara otomatis membaca file terdekat dalam hierarki direktori, sehingga file terdekat memiliki prioritas dan setiap subproject dapat menyertakan instruksi yang disesuaikan.

Dan terkait konflik:

AGENTS.md yang paling dekat dengan file yang diedit memiliki prioritas; prompt pengguna yang eksplisit dalam chat mengesampingkan semuanya.

Bagi banyak orang, "memiliki prioritas" berarti "file root diabaikan". Itu tidak benar. Pada tools yang menerapkan konvensi ini, setiap file pada path dari root repository hingga direktori kerja dibaca dan digabungkan. File terdekat hanya memiliki prioritas ketika dua file memberikan instruksi berbeda tentang subjek yang sama.

Codex menjelaskan mekanismenya secara eksplisit: "Codex menggabungkan file dari root ke bawah, dengan memisahkannya menggunakan baris kosong. File yang lebih dekat dengan direktori saat ini mengesampingkan panduan sebelumnya." Claude Code mengikuti path yang sama. Saat sesi dimulai, Claude Code membaca "setiap AGENTS.md dan .claude/AGENTS.md di direktori kerja Anda dan direktori di atasnya", dan dokumentasinya menjelaskan model pemuatan ini secara langsung: "Semua file yang ditemukan digabungkan ke dalam context, bukan saling menggantikan." Direktori di bawah direktori kerja berperilaku berbeda: Claude Code memuat AGENTS.md milik subdirektori sesuai kebutuhan, "ketika Claude membuka file di sana menggunakan Read tool."

Ada dua konsekuensi praktis. File root menjadi prefix pada setiap sesi di repository, sehingga perlakukan setiap baris di dalamnya sebagai baris yang biayanya Anda tanggung seratus kali seminggu. File per direktori tidak menimbulkan biaya sampai agent membuka file di direktori tersebut. Artinya, detail lebih murah ditempatkan di sana dan memang seharusnya berada di sana.

Perilaku ini diperiksa berdasarkan dokumentasi Codex dan Claude Code pada 27 October 2026. Tools menerapkan konvensi ini dengan sedikit perbedaan dan memang dapat berubah, jadi pastikan aturan pemuatan untuk agent yang digunakan oleh tim Anda.

Contoh struktur untuk repositori dengan tiga service

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

File di root sengaja dibuat singkat. File ini menunjukkan lokasi yang harus diperiksa dan hanya berisi aturan yang berlaku di 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.

File per direktori memuat detail dan dapat dibuat sepanjang kebutuhan 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.

File worker memiliki struktur yang sama dengan isi yang berbeda: perintah instalasi, pytest -q, alasan consumer harus tetap idempoten, serta migrasi yang harus dijalankan sebelum pengujian berhasil. File infra memuat aturan untuk mencegah agent menimbulkan kerusakan. Jangan pernah menjalankan terraform apply. Jalankan terraform plan lalu berhenti, dan sebutkan backend state yang sudah dikonfigurasi agar agent tidak mencoba menginisialisasi backend baru.

Perhatikan hal yang tidak terdapat dalam file-file ini: penjelasan tentang fungsi setiap service. Informasi tersebut ditujukan untuk manusia. Upstream menetapkan batas yang sama dengan menyatakan bahwa "file README.md ditujukan untuk manusia: quick start, deskripsi proyek, dan panduan kontribusi", sedangkan AGENTS.md memuat "konteks tambahan, yang terkadang mendetail, yang diperlukan coding agent: langkah build, pengujian, dan konvensi." Pemisahan antara AGENTS.md dan README yang ditujukan untuk manusia menjelaskan batas tersebut kalimat demi kalimat, sedangkan DESIGN.md yang mencatat alasan di balik struktur kode membahas file ketiga, yaitu file yang menjelaskan keputusan, bukan perintah.

Siapa yang memperbarui file saat kode berubah?

Satu aturan, dan aturan ini ditulis dalam file root: siapa pun yang mengubah kode dalam suatu direktori harus memperbarui AGENTS.md milik direktori tersebut dalam commit yang sama.

Aturan ini berfungsi karena alasan mekanis, bukan alasan budaya. File per direktori berada dalam diff yang sama dengan kode, sehingga reviewer pull request dapat melihat keduanya sekaligus. File root berlaku untuk semua orang, yang berarti tidak benar-benar menjadi tanggung jawab siapa pun. File tersebut juga tidak pernah muncul dalam diff yang sedang dibaca seseorang.

Dukung aturan ini dengan pemeriksaan pada pull request. Pemeriksaan tersebut mencari AGENTS.md terdekat di atas setiap file yang diubah, lalu melaporkan jika file tersebut tidak ikut diubah.

#!/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 branch yang mengubah API client tanpa mengubah dokumentasi, output-nya terlihat seperti berikut:

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

Jadikan ini peringatan, bukan kegagalan. Gate yang tegas mendorong orang menambahkan baris kosong ke file agar CI berstatus hijau. File yang diedit hanya untuk memenuhi pemeriksaan otomatis lebih buruk daripada tidak memiliki file sama sekali. Peringatan memberi reviewer pertanyaan untuk diajukan. Bagian itulah yang benar-benar berfungsi.

Bagaimana cara mengetahui bahwa AGENTS.md sudah tidak relevan?

Ada dua pemeriksaan yang dapat Anda jalankan hari ini, serta satu gejala yang akan terlihat dalam sesi.

Bandingkan usia setiap file dengan usia kode yang dijelaskannya. %cs menampilkan tanggal commit 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

Tanggal dokumentasi yang tertinggal enam bulan dari tanggal kode tidak membuktikan bahwa file tersebut salah. Namun, hal itu menunjukkan file mana yang harus dibaca terlebih dahulu. Itulah semua informasi yang Anda perlukan dari pemeriksaan yang hanya memerlukan waktu satu detik.

Cari path yang sudah tidak ada. Dokumentasi menjadi usang dengan cara yang sangat spesifik: dokumentasi terus menjelaskan kode yang sudah dihapus. Setiap path dalam file ini ditulis di dalam backtick, sehingga mudah diekstrak 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 outputnya, dan jangan langsung memasukkan pemeriksaan ini ke CI. Pemeriksaan ini juga menandai glob seperti src/**/*.ts dan URL apa pun yang Anda masukkan dalam tanda kutip, karena keduanya mengandung garis miring dan tidak satu pun merupakan file di disk. Pada Claude Code v2.1.283 atau yang lebih baru, /doctor prompt-audit menjalankan pemeriksaan serupa untuk Anda: perintah tersebut mencari "referensi ke file atau perintah yang tidak ada" dan file yang saling bertentangan, mencakup file AGENTS.md Anda secara default, serta tidak mengubah apa pun sampai Anda memintanya menerapkan edit yang diusulkan.

Gejalanya dalam sesi. Agent membaca file tersebut, mencoba membuka src/api/client.ts karena file mengarahkannya ke sana, lalu tool mengembalikan:

No such file or directory

Jadi, agent melakukan hal yang wajar dan menulis wrapper fetch miliknya sendiri. Itulah biaya sebenarnya dari file yang sudah usang. Agent tidak mengabaikan dokumentasi Anda. Agent mengikuti dokumentasi tersebut, menemukan path yang sudah dihapus tiga bulan lalu, lalu membangun ulang kode yang sebenarnya sudah Anda miliki. Skill seperti Ponytail, yang mengarahkan agent untuk melakukan perubahan sekecil mungkin yang berhasil, dapat mengurangi kecenderungan membangun ulang ini, tetapi tidak dapat menemukan helper yang diarahkan file Anda ke lokasi yang salah.

Apakah Claude Code membaca file AGENTS.md?

Ya, mulai Claude Code v2.1.277, dan aturan tepatnya penting karena susunan bertingkat bergantung padanya. Dokumentasi diperiksa pada 27 October 2026: "Claude Code dapat membaca AGENTS.md sebagai instruksi proyek Anda, sehingga repositori yang sudah disiapkan untuk coding agent lain dapat digunakan tanpa menambahkan CLAUDE.md, import, atau pengaturan." Nilai default Project instructions, claude-md-or-agents-md, membaca "file AGENTS.md Anda jika tidak ada CLAUDE.md atau CLAUDE.local.md di working directory Anda atau di atasnya." File bertingkat juga tercakup: Claude membaca AGENTS.md milik subdirektori "ketika Claude membuka file di sana dengan tool Read", selama "subdirektori tersebut tidak memiliki salah satu dari tiga file CLAUDE.md sendiri". Ketiganya adalah CLAUDE.md, .claude/CLAUDE.md, dan CLAUDE.local.md, sehingga satu CLAUDE.local.md pribadi di apps/web sudah cukup untuk menghentikan pemuatan apps/web/AGENTS.md.

Hal itu membuat saran lama untuk menempatkan CLAUDE.md di samping setiap AGENTS.md menjadi jebakan. Jika terdapat AGENTS.md dan CLAUDE.md atau CLAUDE.local.md di working directory Anda atau di atasnya, dokumentasi menyatakan bahwa Claude hanya membaca "file CLAUDE.md Anda". .claude/CLAUDE.md diperlakukan dengan cara yang sama. Satu file pendamping di root yang berisi satu baris khusus Claude menyembunyikan setiap AGENTS.md pada path tersebut, dan CLAUDE.local.md pribadi juga memiliki efek yang sama. Jika Anda ingin mempertahankan salah satunya, ketik /config dan atur Project instructions ke claude-md-and-agents-md, yang membaca keduanya, dengan CLAUDE.md milik setiap direktori dibaca lebih dahulu, lalu AGENTS.md miliknya.

Nomor versi saja tidak membuktikan bahwa konfigurasi berhasil. Anda memerlukan v2.1.277 atau yang lebih baru, tetapi sebelum v2.1.281 beberapa session, seperti session pada Amazon Bedrock atau session dengan telemetry dinonaktifkan, hanya membaca file CLAUDE.md, dan dalam beberapa kasus session pertama setelah upgrade dari v2.1.276 atau yang lebih lama juga melewati AGENTS.md: dokumentasi menyatakan bahwa "Claude membaca AGENTS.md mulai dari session Anda berikutnya". Jadi, periksa session itu sendiri. Dalam session interaktif, Claude Code mencetak baris seperti no CLAUDE.md found; AGENTS.md loaded: yang diikuti path, dan pada versi saat ini /memory mencantumkan file tersebut. Sebelum v2.1.280, /memory dan /context tidak mencantumkan AGENTS.md yang dibaca langsung oleh Claude, sehingga pada versi tersebut tanyakan kepada Claude isi project instructions yang dibacanya.

Format import tetap tepat ketika Claude tidak dapat membaca AGENTS.md secara langsung: pada versi lama, session sebelum v2.1.281 di Amazon Bedrock atau dengan telemetry dinonaktifkan, session ketika plugin bawaan yang membacanya dinonaktifkan, atau project yang memiliki CLAUDE.md dengan Project instructions diatur ke claude-md. Tambahkan ini ke services/worker/CLAUDE.md:

@AGENTS.md

## Claude Code

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

Format symlink tepat ketika tidak ada konfigurasi khusus tool yang perlu ditambahkan.

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 pun jika berhasil, jadi periksa hasil listing: apps/web/CLAUDE.md -> AGENTS.md. Kemudian mulai session dan jalankan /context; file yang dimuat akan muncul di bawah Memory files. Di Windows, symlink memerlukan hak Administrator atau Developer Mode, dan Git akan checkout symlink yang di-commit sebagai file teks biasa kecuali core.symlinks diaktifkan. Akibatnya, clone tersebut memiliki CLAUDE.md satu baris sebagai pengganti instruksi Anda. Jika orang yang melakukan clone repositori bekerja di Windows, gunakan import @AGENTS.md. Jika Anda menyiapkan salah satu workaround sebelum Claude Code membaca AGENTS.md secara mandiri, Anda dapat membiarkannya: dokumentasi menyatakan bahwa mempertahankan import "tidak pernah membuat Claude membaca AGENTS.md dua kali", dan CLAUDE.md yang berupa symlink dibaca satu kali.

Ada satu jebakan terkait hal ini. Setelah /compact, CLAUDE.md di root project dibaca ulang dari disk, tetapi file bertingkat di subdirektori tidak dimuat ulang. Claude Code memuatnya sesuai kebutuhan, pada saat agent berikutnya bekerja dengan file di direktori tersebut. Dokumentasi menjelaskan hal ini untuk file CLAUDE.md dan tidak menjelaskan compaction secara terpisah untuk AGENTS.md yang dibaca langsung, jadi anggap file bertingkat dengan nama mana pun berperilaku seperti ini. Jika aturan per direktori tampaknya berhenti berlaku di tengah session yang panjang, biasanya itulah penyebabnya. Membaca file apa pun di direktori tersebut akan memuatnya kembali.

Pengaturan yang mengarahkan agent lain ke AGENTS.md

Codex membaca AGENTS.md secara native. Pada setiap tingkat, Codex memeriksa AGENTS.override.md terlebih dahulu. Dengan begitu, satu direktori dapat memiliki override lokal tanpa mengubah file bersama. Codex berhenti menggabungkan file setelah ukuran gabungan mencapai 32 KiB, yaitu project_doc_max_bytes default. Ini menjadi alasan tambahan untuk menjaga file root tetap kecil.

Aider membacanya melalui .aider.conf.yml dengan baris read: AGENTS.md.

Gemini CLI membacanya melalui .gemini/settings.json dengan { "context": { "fileName": "AGENTS.md" } }.

Upstream mendokumentasikan penggantian nama yang kompatibel dengan versi sebelumnya untuk repositori yang masih menggunakan nama singular lama: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.

Dalam monorepo yang sangat besar, pengaturan claudeMdExcludes milik Claude Code melewati file ancestor berdasarkan path atau glob. Ini berguna ketika direktori tim lain berada di atas direktori Anda. Polanya juga berlaku untuk file AGENTS.md yang dibaca Claude Code.

Bagaimana perbedaannya dengan memori agen atau skill?

Mekanisme ini terlihat serupa, tetapi dapat gagal dengan cara yang sama sekali berbeda. Karena itu, penting untuk menentukan mekanisme yang tepat.

AGENTS.md ditulis oleh Anda, di-commit ke git, ditinjau melalui pull request, dan sama untuk semua orang yang melakukan clone repository. Memori agen ditulis oleh agen, disimpan di luar repository, dan hanya tersedia secara lokal pada satu mesin. Dokumentasi Claude Code menjelaskan perbedaan yang sama: CLAUDE.md berisi "Instruksi dan aturan" yang Anda tulis, sedangkan auto memory berisi "Pembelajaran dan pola" yang ditulis Claude. Direktori memori tidak dibagikan antar-mesin. Pengujiannya sederhana. Jika sebuah fakta harus berlaku bagi rekan kerja yang melakukan clone baru, fakta tersebut tidak boleh disimpan dalam memori. Bagaimana memori agen dipertahankan antar-sesi membahas bagian tersebut.

Skill adalah mekanisme ketiga. AGENTS.md merupakan konteks yang dimuat pada setiap sesi; skill merupakan prosedur yang dimuat saat diperlukan. Dokumentasi Claude Code memberikan aturan yang jelas: "Jika suatu entri merupakan prosedur multilangkah atau hanya berlaku untuk satu bagian codebase, pindahkan entri tersebut ke skill atau aturan yang dibatasi oleh path." Bagian kedua kalimat tersebut menjelaskan fungsi AGENTS.md bertingkat. Bagian pertama menjelaskan fungsi skill agen, dan jika prosedur yang sama diperlukan di lebih dari satu repository, bagikan skill di berbagai repo alih-alih menyalin paragraf yang sama ke sepuluh file AGENTS.md yang berbeda.

Upstream mencatat bahwa "saat tulisan ini dibuat, repo OpenAI utama memiliki 88 file AGENTS.md". Angka tersebut merangkum seluruh alasannya. Repository besar tidak memerlukan satu file yang lebih besar. Repository tersebut memerlukan lebih banyak file kecil, masing-masing berada di dekat kode yang dijelaskannya dan dikelola oleh pihak yang terakhir kali mengubah kode tersebut.

FAQ

Apakah AGENTS.md bertingkat menggantikan file root atau menambahkannya?

File tersebut menambahkannya. Dokumentasi upstream menyatakan bahwa "file yang paling dekat memiliki prioritas", yang menjelaskan apa yang terjadi saat terjadi konflik, bukan file mana yang dimuat. Codex "menggabungkan file dari root ke bawah dengan memisahkannya menggunakan baris kosong", sedangkan Claude Code menggabungkan setiap file yang ditemukan saat menelusuri ke atas dari direktori kerja, bukan menggantikannya. File terdekat hanya memiliki prioritas jika dua file memberikan instruksi berbeda tentang subjek yang sama. Tulis aturan bersama satu kali di root, dan jangan mengulanginya di setiap direktori.

Seberapa besar ukuran AGENTS.md root?

Ukurannya harus cukup kecil sehingga Anda tidak keberatan jika file tersebut ditempelkan di awal setiap permintaan yang Anda buat di repositori itu, karena memang demikian yang terjadi. Dokumentasi Claude Code menyarankan agar setiap file berisi kurang dari 200 baris dan memperingatkan bahwa file yang lebih panjang "mengurangi kepatuhan". Secara default, Codex berhenti menggabungkan file instruksi jika ukuran gabungannya mencapai 32 KiB. Jika file root Anda mendokumentasikan empat service, sebagian besar isinya tidak diperlukan untuk satu tugas tertentu. Pindahkan detail tersebut ke file per direktori, lalu sisakan peta strukturnya.

Bagaimana cara mencegah file-file ini menjadi kedaluwarsa?

Tambahkan satu aturan di file root: siapa pun yang mengubah kode dalam suatu direktori harus memperbarui AGENTS.md direktori tersebut dalam commit yang sama. Menempatkan file di dekat kode membuat aturan ini lebih mudah dipatuhi, karena perubahan tersebut kemudian muncul dalam diff pull request yang sama dan memang sedang dibaca oleh manusia. Tambahkan peringatan CI yang memetakan setiap path yang berubah ke AGENTS.md terdekat di atasnya, lalu secara berkala bandingkan git log -1 --format=%cs pada setiap file dengan perintah yang sama saat dijalankan pada direktori yang didokumentasikan file tersebut.

Apakah Claude Code membaca file AGENTS.md?

Ya, sejak v2.1.277. Berdasarkan pemeriksaan terhadap dokumentasi pada 27 October 2026, Claude Code membaca AGENTS.md secara default jika tidak ada CLAUDE.md atau CLAUDE.local.md di direktori kerja Anda atau di atasnya, dan membaca AGENTS.md milik subdirektori saat membuka file di sana dengan Read tool jika subdirektori tersebut tidak memiliki CLAUDE.md, .claude/CLAUDE.md, atau CLAUDE.local.md sendiri. Jangan menambahkan CLAUDE.md di samping setiap AGENTS.md: jika terdapat satu file di atau di atas direktori kerja, Claude hanya membaca "hanya file CLAUDE.md Anda". Jika Anda juga memerlukan CLAUDE.md, atur Project instructions ke claude-md-and-agents-md di /config, atau letakkan @AGENTS.md pada baris pertamanya. Jalankan /memory dalam suatu sesi dan pastikan path AGENTS.md muncul dalam daftar.

Di mana saya harus menempatkan aturan yang hanya berlaku sesekali?

Jangan di AGENTS.md. File tersebut dimuat pada setiap sesi, sehingga setiap baris di dalamnya harus bersaing untuk mendapatkan perhatian dengan permintaan yang sebenarnya Anda ketik. Prosedur yang terdiri atas beberapa langkah dan hanya diperlukan sesekali sebaiknya ditempatkan dalam skill yang dimuat sesuai kebutuhan. Aturan yang hanya berlaku untuk satu direktori sebaiknya ditempatkan dalam AGENTS.md milik direktori tersebut. Fakta yang dapat dibaca agen langsung dari kode, seperti pohon direktori atau daftar dependensi, tidak perlu ditempatkan di keduanya.

Apakah artikel ini bermanfaat?