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 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 aplikasi web, background worker, dan direktori Terraform gagal dalam empat hal terpisah.

File tersebut menjadi usang karena tidak ada yang memilikinya. Engineer yang mengganti nama skrip pengujian di apps/web sedang mengedit file di bawah apps/web. File 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 perubahan itu sudah melupakannya.

File tersebut menggunakan context pada setiap tugas. File ini dimuat pada awal sesi, sebelum agent mengetahui permintaan Anda. Dokumentasi Claude Code menetapkan angka 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 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 yang pernah dimuat ke dalam context. Jika aturan yang Anda yakin sudah ditulis dengan jelas tetap dilewati, 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. Misalnya, struktur direktori, daftar dependensi, dan ringkasan fungsi setiap package. Pemeriksaan /doctor milik Claude Code dibuat 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 suatu baris memang perlu dimasukkan ke file itu.

Apakah agent membaca file root, atau hanya file yang paling dekat?

Di sinilah sebagian besar orang keliru memahami model, jadi sebaiknya kutip konvensi upstream alih-alih memparafrasakannya:

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

Tentang konflik:

AGENTS.md yang paling dekat dengan file yang diedit memiliki prioritas; prompt chat eksplisit dari pengguna 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 menyatakan hal yang 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 menelusuri path yang sama untuk nama filenya sendiri. File dalam hierarki direktori di atas working directory "dimuat sepenuhnya saat startup", dan "Semua file yang ditemukan digabungkan ke dalam context, bukan saling mengesampingkan." Direktori di bawah working directory berperilaku berbeda: Claude Code memuat file tersebut sesuai kebutuhan, "saat Claude membaca file dalam direktori tersebut."

Ada dua konsekuensi praktis. File root menjadi prefix pada setiap session dalam repository, jadi perlakukan setiap baris di dalamnya sebagai baris yang biayanya Anda tanggung seratus kali seminggu. File per-directory tidak menimbulkan biaya saat agent bekerja di lokasi lain. Dengan demikian, 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 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 kedaluwarsa?

Ada dua pemeriksaan yang dapat Anda jalankan hari ini, serta satu gejala yang akan terlihat dalam sebuah 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 perlu dibaca terlebih dahulu. Informasi tersebut sudah cukup untuk pemeriksaan yang hanya memerlukan satu detik.

Cari path yang sudah tidak ada. Dokumentasi mengalami kedaluwarsa dengan cara yang sangat spesifik: dokumentasi tetap 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, jangan masukkan pemeriksaan ini ke CI. Pemeriksaan ini juga menandai glob seperti src/**/*.ts dan URL apa pun yang Anda tulis, karena keduanya berisi garis miring dan bukan file pada disk.

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

No such file or directory

Karena itu, agent melakukan hal yang wajar dan menulis wrapper fetch miliknya sendiri. Itulah biaya sebenarnya dari file yang kedaluwarsa. 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 memastikan agent hanya melakukan perubahan terkecil yang berfungsi, dapat mengurangi kecenderungan membangun ulang ini, tetapi skill tersebut tidak dapat menemukan helper yang ditunjuk file Anda ke lokasi yang salah.

Apakah Claude Code membaca file AGENTS.md?

Tidak, dan hal ini perlu ditegaskan karena tata letak bertingkat bergantung padanya. Per Agustus 2026, dokumentasi menyatakan: "Claude Code reads CLAUDE.md, not AGENTS.md." Pola ini tetap berfungsi, tetapi Anda perlu menambahkan CLAUDE.md di samping setiap AGENTS.md.

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

@AGENTS.md

## Claude Code

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

Gunakan bentuk symlink jika tidak ada konfigurasi 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 menampilkan apa pun jika berhasil, jadi periksa daftar 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, jadi gunakan impor @AGENTS.md sebagai gantinya.

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 agent membaca file berikutnya di direktori tersebut. 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.

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 menyatukannya menggunakan baris kosong", sedangkan Claude Code menggabungkan setiap file yang ditemukan saat menelusuri direktori dari working directory ke atas, bukan menimpanya. File yang paling dekat hanya menang 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 AGENTS.md root seharusnya?

Buat cukup kecil sehingga Anda tidak keberatan jika file tersebut ditempelkan di awal setiap permintaan yang Anda buat dalam repository itu, karena itulah yang terjadi. Dokumentasi Claude Code menyarankan target di bawah 200 baris per file dan memperingatkan bahwa file yang lebih panjang "mengurangi kepatuhan". Secara default, Codex berhenti menggabungkan file instruksi setelah total ukurannya mencapai 32 KiB. Jika file root Anda mendokumentasikan empat service, sebagian besar isinya tidak relevan untuk satu tugas tertentu. Pindahkan detail ke file per direktori dan tinggalkan peta sebagai petunjuk.

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 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 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 ditambahkan, tetapi pada Windows tindakan tersebut memerlukan hak Administrator atau Developer Mode. Jalankan /context dalam suatu session dan pastikan file tersebut muncul di bawah Memory files.

Di mana saya harus menempatkan aturan yang hanya berlaku pada waktu tertentu?

Jangan menempatkannya di AGENTS.md. File tersebut dimuat dalam setiap session, sehingga setiap baris di dalamnya 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 berlaku untuk satu direktori harus ditempatkan dalam AGENTS.md direktori tersebut. Fakta yang dapat dibaca agent langsung dari kode, seperti struktur direktori atau daftar dependency, tidak perlu ditempatkan di mana pun.