Struktur AGENTS.md Bertingkat untuk Monorepo

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 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 root dan file worker, sehingga tidak menggunakan konteks untuk front end yang tidak akan disentuhnya.

Tidak ada yang perlu diinstal. AGENTS.md adalah sebuah konvensi, dan proyek upstream menyatakannya dengan jelas:

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

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

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

Satu AGENTS.md sepanjang 600 baris di root repositori yang berisi aplikasi web, 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. AGENTS.md di root 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, dan orang yang menyebabkan masalah itu sudah melupakan perubahan tersebut.

File ini menghabiskan konteks pada setiap tugas. File-file ini dimuat pada awal sesi, sebelum agent mengetahui permintaan Anda. Dokumentasi Claude Code memberikan 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. File root yang mendokumentasikan empat service menggunakan 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 rules contradict each other, Claude may pick one arbitrarily." File per direktori menghilangkan tebakan tersebut karena hanya satu dari dua aturan itu yang berada dalam konteks.

Isinya dipenuhi fakta yang dapat dibaca agent dari kode. Misalnya, struktur direktori, daftar dependensi, dan ringkasan fungsi setiap package. Pemeriksaan /doctor milik Claude Code dibuat khusus untuk menghapus hal-hal tersebut. Pemeriksaan ini "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 ada dalam file.

Apakah agent membaca file root, atau hanya file terdekat?

Di sinilah kebanyakan orang keliru memahami modelnya. Karena itu, lebih baik mengutip konvensi upstream daripada memparafrasakannya:

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

Tentang konflik:

AGENTS.md yang paling dekat dengan file yang diedit memiliki prioritas; prompt chat pengguna yang eksplisit 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 working directory dibaca dan digabungkan. File terdekat hanya memiliki prioritas ketika dua file memberikan instruksi berbeda tentang hal yang sama.

Codex menjelaskan mekanismenya secara eksplisit: "Codex menggabungkan file dari root ke bawah dan memisahkannya dengan baris kosong. File yang lebih dekat ke direktori saat ini mengesampingkan panduan sebelumnya." Claude Code menelusuri path yang sama untuk nama filenya sendiri. File dalam hierarki direktori di atas working directory "dimuat sepenuhnya saat peluncuran", dan "Semua file yang ditemukan digabungkan ke dalam konteks, bukan saling mengesampingkan." Direktori di bawah working directory berperilaku berbeda: Claude Code memuat file tersebut sesuai kebutuhan, "saat Claude membaca file di direktori tersebut."

Ada dua konsekuensi praktis. File root menjadi awalan pada setiap sesi dalam repository. Karena itu, perlakukan setiap baris di sana sebagai baris yang biayanya harus Anda tanggung seratus kali seminggu. File per-direktori tidak menambah biaya ketika agent bekerja di lokasi lain. Jadi, detail lebih tepat ditempatkan di sana.

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

Tata letak yang dapat digunakan 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 memuat 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 detailnya. Panjangnya dapat disesuaikan dengan 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 idempotent, dan migrasi yang harus dijalankan sebelum pengujian berhasil. File infra adalah tempat untuk menulis aturan yang mencegah agent melakukan tindakan yang merusak. Jangan pernah menjalankan terraform apply. Jalankan terraform plan saja, lalu berhenti. Cantumkan nama state backend yang sudah dikonfigurasi agar agent tidak mencoba menginisialisasi backend baru.

Perhatikan hal yang tidak ada dalam file-file tersebut: deskripsi tentang fungsi setiap service. Deskripsi itu ditujukan untuk manusia. Upstream menetapkan batas yang sama dengan menyatakan bahwa "README.md files are for humans: quick starts, project descriptions, and contribution guidelines", sedangkan AGENTS.md memuat "the extra, sometimes detailed context coding agents need: build steps, tests, and conventions." Pemisahan antara AGENTS.md dan README yang ditujukan untuk manusia membahas batas tersebut kalimat demi kalimat. Sementara itu, DESIGN.md yang mencatat alasan struktur kode dibuat seperti itu membahas file ketiga, yaitu file yang menjelaskan keputusan, bukan perintah.

Siapa yang memperbarui file saat kode berubah?

Terapkan satu aturan di file root: siapa pun yang mengubah kode dalam suatu direktori harus memperbarui AGENTS.md direktori tersebut dalam commit yang sama.

Aturan ini efektif karena alasan mekanis, bukan alasan budaya. File pada setiap direktori berada dalam diff yang sama dengan kode, sehingga reviewer pull request dapat melihat keduanya sekaligus. File root menjadi tanggung jawab semua orang, yang berarti tidak menjadi tanggung jawab siapa pun, dan file tersebut tidak pernah muncul dalam diff yang sedang dibaca seseorang.

Dukung aturan ini dengan pemeriksaan pada pull request. Pemeriksaan tersebut menemukan 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 akan terlihat seperti ini:

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

Jadikan pemeriksaan ini peringatan, bukan kegagalan. Gate yang wajib lulus akan mengajarkan orang untuk menambahkan baris kosong ke file agar CI berstatus hijau. File yang diedit hanya untuk memuaskan robot nilainya lebih rendah daripada tidak memiliki file sama sekali. Peringatan ini memberi reviewer pertanyaan untuk diajukan. Bagian itulah yang benar-benar efektif.

Bagaimana cara mengetahui bahwa AGENTS.md sudah usang?

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. Hal itu hanya memberi tahu file mana yang perlu dibaca terlebih dahulu. Itu sudah cukup untuk pemeriksaan yang hanya memerlukan satu detik.

Cari path yang sudah tidak ada. Dokumentasi mengalami kerusakan dengan cara yang sangat spesifik: dokumentasi tetap menjelaskan kode yang telah 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 output tersebut, bukan memasukkannya langsung ke CI. Perintah ini juga menandai glob seperti src/**/*.ts dan URL apa pun yang Anda kutip, karena keduanya mengandung slash dan bukan file di disk.

Gejala dalam sesi. Agent membaca file tersebut, mencoba membuka src/api/client.ts karena file menginstruksikannya, lalu tool mengembalikan:

No such file or directory

Karena itu, agent melakukan hal yang masuk akal dan menulis wrapper fetch miliknya sendiri. Itulah biaya sebenarnya dari file yang usang. Agent tidak mengabaikan dokumentasi Anda. Agent mengikuti dokumentasi tersebut, tiba di path yang telah dihapus tiga bulan sebelumnya, lalu membangun ulang kode yang sebenarnya sudah Anda miliki. Skill seperti Ponytail, yang memastikan agent hanya melakukan perubahan terkecil yang berfungsi, dapat mengurangi kecenderungan membangun ulang tersebut, tetapi tidak dapat menemukan helper yang ditunjukkan file Anda ke lokasi yang salah.

Apakah Claude Code membaca file AGENTS.md?

Tidak, dan hal ini perlu ditegaskan karena struktur bertingkat bergantung padanya. Per Agustus 2026, dokumentasi menyatakan: "Claude Code membaca CLAUDE.md, bukan AGENTS.md." Pola ini tetap berfungsi. Anda hanya perlu menempatkan CLAUDE.md di samping setiap AGENTS.md.

Gunakan bentuk impor jika Anda ingin menambahkan baris khusus alat di atas baris bersama. Masukkan ini ke services/worker/CLAUDE.md:

@AGENTS.md

## Claude Code

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

Gunakan bentuk symlink jika tidak ada pengaturan khusus alat 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 daftar file dengan apps/web/CLAUDE.md -> AGENTS.md. Kemudian mulai sesi dan jalankan /context. File yang dimuat akan muncul di bagian Memory files. Di Windows, symlink memerlukan hak Administrator atau Developer Mode. Karena itu, gunakan impor @AGENTS.md.

Ada satu hal yang perlu diperhatikan. Setelah /compact, file root dibaca ulang dari disk, tetapi file bertingkat dalam subdirektori tidak dimuat ulang. File tersebut akan dimuat kembali saat agen membaca file di direktori itu pada kesempatan berikutnya. Jika aturan per direktori tampaknya berhenti diterapkan di tengah sesi yang panjang, biasanya itulah penyebabnya. Menyentuh file apa pun di direktori tersebut akan memuatnya kembali.

Apa perbedaannya dengan memori agent atau skill?

Mekanisme ini terlihat serupa, tetapi dapat mengalami kegagalan dengan cara yang sangat berbeda. Karena itu, penting untuk menentukan mekanisme mana yang Anda perlukan.

AGENTS.md ditulis oleh Anda, di-commit ke git, ditinjau melalui pull request, dan identik bagi semua orang yang melakukan clone repository. Memori agent ditulis oleh agent, disimpan di luar repository, dan hanya tersedia pada satu mesin. Dokumentasi Claude Code menjelaskan perbedaan yang sama: CLAUDE.md berisi "Instructions and rules" yang Anda tulis, sedangkan auto memory berisi "Learnings and patterns" yang ditulis oleh Claude. Direktori memori tidak dibagikan antar-mesin. Pengujiannya sederhana. Jika suatu fakta harus berlaku bagi rekan kerja yang menggunakan clone baru, fakta tersebut tidak boleh disimpan dalam memori. Cara memori agent bertahan antar-sesi membahas bagian tersebut.

Skill adalah mekanisme ketiga. AGENTS.md adalah konteks yang dimuat pada setiap sesi, sedangkan skill adalah prosedur yang dimuat saat diperlukan. Dokumentasi Claude Code memberikan aturan yang dapat digunakan: "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." Kalimat kedua secara tepat menjelaskan fungsi AGENTS.md bertingkat. Kalimat pertama menjelaskan fungsi skill agent, dan jika prosedur yang sama diperlukan di lebih dari satu repository, bagikan skill antar-repository alih-alih menyalin paragraf yang sama ke sepuluh file AGENTS.md yang berbeda.

Upstream mencatat bahwa "at time of writing the main OpenAI repo has 88 AGENTS.md files". Angka tersebut merangkum seluruh alasannya. Repository besar tidak memerlukan satu file yang lebih besar. Repository tersebut memerlukan lebih banyak file kecil, masing-masing ditempatkan di dekat kode yang dijelaskannya dan dikelola oleh pihak yang terakhir 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 terdapat konflik, bukan file mana yang dimuat. Codex "menggabungkan file dari root ke bawah dengan menyisipkan baris kosong di antaranya", sedangkan Claude Code menggabungkan setiap file yang ditemukan dengan menelusuri direktori kerja ke atas, bukan menggantikannya. File terdekat hanya memiliki prioritas ketika dua file memberikan instruksi berbeda tentang subjek yang sama. Tulis aturan bersama satu kali di root, dan jangan mengulanginya di setiap direktori.

Seberapa besar seharusnya AGENTS.md root?

Buat cukup kecil sehingga Anda tidak keberatan jika isinya ditempelkan di awal setiap permintaan yang Anda buat dalam repositori tersebut, karena itulah 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 ketika ukuran gabungannya mencapai 32 KiB. Jika file root Anda mendokumentasikan empat service, sebagian besar isinya tidak diperlukan untuk satu tugas tertentu. Pindahkan detail ke file per direktori dan sisakan petanya.

Bagaimana cara mencegah file-file ini menjadi usang?

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 masuk dalam diff pull request yang sama dan 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 yang dijalankan pada direktori yang didokumentasikan file tersebut.

Apakah Claude Code membaca file AGENTS.md?

Tidak. Per Agustus 2026, dokumentasi menyatakan bahwa "Claude Code membaca CLAUDE.md, bukan AGENTS.md." Buat CLAUDE.md di direktori yang sama dengan @AGENTS.md pada baris pertama. File tersebut akan memuat file bersama dan memungkinkan Anda menambahkan instruksi khusus Claude di bawahnya. Symlink yang dibuat dengan ln -s AGENTS.md CLAUDE.md berfungsi jika tidak ada tambahan yang perlu dimasukkan, tetapi di Windows tindakan ini memerlukan hak Administrator atau Developer Mode. Jalankan /context dalam sesi dan pastikan file tersebut muncul di bawah Memory files.

Di mana saya menempatkan aturan yang hanya berlaku sesekali?

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