# Satu File Instruksi untuk Claude Code, Codex, dan Cursor pada 2026
> Satu sumber kebenaran untuk Claude Code, Codex, dan Cursor pada 2026: kapan Claude Code membaca AGENTS.md sendiri, mengimpor @AGENTS.md ke dalam CLAUDE.md, tautan simbolis, dan /init.
Source: https://ailoot.ai/blog/id/agents-md-claude-md-one-instruction-file/
Canonical: https://ailoot.ai/blog/id/agents-md-claude-md-one-instruction-file/
Language: id
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-004
Revision: sha256-96410a06d5bf4b87634dae299bbf054a08eced2b2f03d2e4e5028ae7e35a0008
Untuk informasi tentang layanan ini, lihat [dokumentasi Ailoot](https://ailoot.ai/docs/).
## Apa yang berubah saat Anda menggunakan Claude Code, Codex, dan Cursor bersama-sama?
Poin utama
Pada 2026, pengaturan yang umum bagi seorang vibe coder bukanlah satu alat, melainkan 3–5 alat. Claude Code sebagai alat utama, Codex untuk tugas otonom yang panjang, Cursor untuk penyuntingan cepat di IDE. Masing-masing memiliki file instruksi sendiri: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`. Jika Anda menyinkronkannya secara manual, Anda mengedit satu baris di lima tempat, lupa memperbarui Cursor, dan seminggu kemudian Claude dan Codex memberikan hasil berbeda untuk prompt yang sama.
Dalam contoh yang dijelaskan, Claude Code adalah alat utama, sementara Codex dan Cursor digunakan untuk tugas tertentu. `CLAUDE.md` saya berisi sekitar 250 baris instruksi: apa yang harus dibaca dan dalam urutan apa, apa yang tidak boleh disentuh, perintah mana yang digunakan untuk deployment, dan aturan format commit. Saat pertama kali mencoba Codex CLI pada proyek tersebut, alat itu tidak mengetahui aturan apa pun: alat itu menjalankan `git push --force`, mengutak-atik `.env`, dan mengganti nama file dengan ceroboh.
Awalnya saya menyalin `CLAUDE.md` ke `AGENTS.md` secara manual. Dua minggu kemudian, saya menemukan bahwa proyek tersebut sudah memiliki empat versi instruksi yang sama: di `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, dan `.windsurf/rules/`. Semuanya sedikit berbeda. Ini bukan masalah Claude atau Cursor; ini jebakan dasar dari sistem apa pun yang memiliki beberapa sumber kebenaran. Saya membahas masalah ini lebih terperinci dalam [panduan kerja multi-agen](https://ailoot.ai/blog/id/claude-code-codex-together/).
Pada Juni 2026, dokumentasi memori Claude Code dari Anthropic memberikan satu jawaban: file bersama plus impor. Sejak September 2026, Claude Code membaca `AGENTS.md` sendiri jika proyek tidak memiliki `CLAUDE.md`, dan impor diperlukan bila Anda memiliki aturan khusus untuk Claude. Di bawah ini, saya menjelaskan kapan satu `AGENTS.md` sudah cukup, cara menyiapkan impor, dan cara memisahkan aturan bersama dari aturan khusus Claude.
## Apakah Claude Code membaca AGENTS.md sendiri?
Poin utama
Ya, mulai versi 2.1.277 yang dirilis pada 18 September 2026, tetapi hanya jika tidak ada `CLAUDE.md`, `.claude/CLAUDE.md`, atau `CLAUDE.local.md` di direktori kerja atau di atasnya. Jika `CLAUDE.md` ada, Claude Code secara default hanya membaca file itu, dan `AGENTS.md` disertakan dengan baris `@AGENTS.md` di dalam `CLAUDE.md` atau dengan tautan simbolis. Perilakunya berubah di `/config`, di bagian Project instructions. Sebelum September, Claude Code sama sekali tidak membaca `AGENTS.md`, dan mengimpornya adalah satu-satunya cara.
Sebelum September 2026, jawabannya adalah “tidak.” Issue \#6235, yang meminta dukungan untuk AGENTS.md, telah dibuka sejak Agustus 2025 dan ditutup pada 17 Agustus 2026. Dokumentasi memori selama itu menunjuk ke satu solusi: buat CLAUDE.md dan sertakan `AGENTS.md` di dalamnya sebagai impor. Mulai versi 2.1.277, dokumentasinya menyatakan hal yang berbeda:
Claude Code dapat membaca AGENTS.md sebagai instruksi proyek, sehingga repositori yang sudah disiapkan untuk agen lain dapat digunakan tanpa CLAUDE.md, impor, atau konfigurasi.
— Anthropic, https://code.claude.com/docs/en/memory#agents-md
File yang dibaca Claude Code bergantung pada file yang ada di proyek:
| File di proyek | Yang dibaca Claude Code |
|----|----|
| `AGENTS.md`, tanpa `CLAUDE.md` atau `CLAUDE.local.md` di direktori kerja atau di atasnya | `AGENTS.md` |
| `AGENTS.md` dan `CLAUDE.md` (atau `CLAUDE.local.md`) di direktori kerja atau di atasnya | Hanya `CLAUDE.md` |
| `CLAUDE.md` dengan baris `@AGENTS.md` | `CLAUDE.md`, dan `AGENTS.md` di dalamnya melalui impor |
Untuk pemeriksaan ini, `CLAUDE.md`, `.claude/CLAUDE.md`, dan `CLAUDE.local.md` di direktori kerja serta direktori mana pun di atasnya ikut diperhitungkan. `~/.claude/CLAUDE.md` pribadi, file terkelola perusahaan, dan aturan dari `.claude/rules/` tidak ikut diperhitungkan: semuanya dimuat bersama `AGENTS.md`.
Saat tidak ada `CLAUDE.md`, Claude Code membaca semua file `AGENTS.md` dan `.claude/AGENTS.md` di direktori kerja dan di atasnya saat startup, serta mengambil `AGENTS.md` di subdirektori ketika membuka file di subdirektori tersebut. Impor `@path` di dalam `AGENTS.md` juga berfungsi. Claude Code tidak membaca `AGENTS.local.md`, `AGENTS.override.md`, atau isi direktori `.agents/`.
Catatannya: `CLAUDE.local.md` pribadi juga ikut diperhitungkan. Jika Anda membuatnya untuk menyimpan aturan yang belum di-commit, Claude Code akan diam-diam berhenti membaca `AGENTS.md`. Pengaturan di bawah ini adalah solusinya.
Perilakunya berubah di `/config`, di bagian Project instructions:
| Pengaturan | Yang dibaca Claude Code |
|----|----|
| `claude-md-or-agents-md` (default) | `CLAUDE.md`, atau, jika tidak ada `CLAUDE.md` maupun `CLAUDE.local.md`, `AGENTS.md` |
| `claude-md-and-agents-md` | Kedua file: di setiap direktori, `CLAUDE.md` terlebih dahulu, lalu `AGENTS.md` |
| `claude-md` | Hanya `CLAUDE.md` |
| `managed-only` | Hanya `CLAUDE.md` terkelola perusahaan dan memori otomatis |
Jika Anda ingin mempertahankan `CLAUDE.local.md` tanpa kehilangan `AGENTS.md`, tetapkan `claude-md-and-agents-md`. Tidak akan ada pembacaan ganda: jika `AGENTS.md` sudah disertakan melalui baris `@AGENTS.md` atau tautan simbolis, Claude Code tidak memuatnya untuk kedua kalinya, apa pun pengaturannya.
Anda dapat memeriksa apakah file tersebut terdeteksi dengan perintah `/memory`: mulai versi 2.1.280, jalur ke `AGENTS.md` muncul dalam daftar. Pada versi sebelum 2.1.277 dan dalam sesi dengan plugin bawaan `agents-md` yang dinonaktifkan, Claude Code hanya membaca `CLAUDE.md`, dan tidak ada item Project instructions di `/config`. Sebelum versi 2.1.281, sesi melalui Amazon Bedrock dan sesi dengan telemetri dinonaktifkan berperilaku sama. Pada sesi pertama setelah pembaruan dari versi lama, `AGENTS.md` mungkin juga tidak terdeteksi; file itu akan berfungsi mulai sesi berikutnya.
Apa artinya ini untuk pengaturan dengan satu file? Jika Anda tidak memiliki aturan khusus untuk Claude, Anda dapat melewatkan `CLAUDE.md`: `AGENTS.md` sudah cukup, dan Claude Code, Codex, serta Cursor akan membacanya. Jika Anda memiliki aturan semacam itu (plan mode untuk direktori berisiko, skills, hooks), Anda memerlukan `CLAUDE.md`, dan Claude Code akan berhenti membaca `AGENTS.md` sendiri. Lalu, sertakan `AGENTS.md` di dalam `CLAUDE.md` dengan baris `@AGENTS.md`; pengaturan ini bekerja seperti sebelum September. Cara ini juga membantu pada versi Claude Code yang lebih lama. Saya menjelaskannya secara terperinci di bawah.
## Bagaimana cara mengimpor @AGENTS.md ke dalam CLAUDE.md?
Poin utama
Impor diperlukan saat proyek memiliki `CLAUDE.md`: jika file itu ada, secara default Claude Code tidak membaca `AGENTS.md` sendiri. Untuk menyiapkannya, tulis baris `@AGENTS.md` di bagian atas file `CLAUDE.md`. Saat Claude Code memulai sesi, isinya disisipkan sebagai pengganti baris tersebut dan hasilnya dibaca sebagai satu teks. Di bawah impor, Anda dapat menambahkan bagian “Claude Code” dengan aturan yang hanya berlaku untuk Claude. Impor dapat menggunakan jalur relatif dan absolut, serta dapat bersarang hingga empat tingkat.
Contoh minimal yang berfungsi dari dokumentasi resmi:
```markdown
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.
```
Berikut yang terjadi. Baris pertama, `@AGENTS.md`, adalah direktif impor. Saat Claude Code mengurai `CLAUDE.md` pada awal sesi, ia menemukan impor ini lalu menyisipkan seluruh isi `AGENTS.md` di tempatnya. Berikutnya adalah judul `## Claude Code`: ini hanya markdown, tetapi berfungsi sebagai bagian “tambahan khusus Claude”. Di bawahnya ada aturan yang hanya berlaku untuk Claude Code: gunakan plan mode untuk perubahan di direktori billing. Codex CLI atau Cursor sama sekali tidak membuka file ini; keduanya menggunakan `AGENTS.md` biasa.
Kutipan dari dokumentasi tentang cara kerja impor:
File CLAUDE.md dapat mengimpor file tambahan menggunakan sintaks @path/to/import. File yang diimpor diperluas dan dimuat ke dalam konteks saat sesi dimulai, bersama dengan CLAUDE.md yang merujuknya.
— Anthropic, https://code.claude.com/docs/en/memory
Beberapa detail praktis:
- **Jalur relatif dan absolut.** `@AGENTS.md` relatif terhadap file yang berisi impor. `@/Users/me/shared/rules.md` atau `@~/.claude/personal.md` bersifat absolut. Saya menggunakan `@~/.claude/personal.md` untuk preferensi pribadi yang tidak ingin saya masukkan ke repositori.
- **Kedalaman empat lompatan.** `AGENTS.md` dapat mengimpor `@docs/coding-style.md`, lalu `coding-style.md` dapat mengimpor file lain, hingga empat tingkat. Itu cukup untuk struktur nyata apa pun.
- **Backtick memblokir impor.** Jika teks menyebut `` `@README` ``, itu hanya penyebutan nama, bukan impor. Ini berguna saat menjelaskan cara kerja impor kepada pembaca tanpa memicunya.
- **Persetujuan untuk file di luar proyek.** Jika impor mengarah ke luar direktori kerja, seperti `@~/.claude/personal.md`, Claude Code menampilkan dialog yang mencantumkan file tersebut untuk pertama kalinya. Jika Anda menolak, impor eksternal tetap dinonaktifkan dan dialog tidak akan ditampilkan lagi. `@AGENTS.md` di akar proyek tidak memicu dialog. Ini melindungi Anda agar file yang tidak terkait tidak sengaja dimuat ke dalam konteks.
Setelah saya beralih ke pengaturan ini di proyek yang diceritakan, `CLAUDE.md` saya menyusut dari 250 baris menjadi 60: `@AGENTS.md` ditambah lima hingga tujuh aturan yang hanya berlaku untuk Claude Code (plan mode untuk direktori berisiko, hal-hal yang tidak boleh disentuh di area admin, dan cara merumuskan commit). Semua aturan bersama berada di `AGENTS.md`, yang dibaca Codex dan Cursor.
## Kapan sebaiknya memilih tautan simbolis, dan kapan memilih impor?
Poin utama
Anthropic menawarkan dua mekanisme: impor melalui `@AGENTS.md` atau tautan simbolis, `ln -s AGENTS.md CLAUDE.md`. Tautan simbolis lebih sederhana—hanya sebuah alias dan tidak memerlukan perubahan file. Namun, ada tiga kekurangannya: Windows memerlukan hak administrator, Anda tidak dapat menambahkan aturan khusus Claude ke `CLAUDE.md`, dan Git terkadang menampilkan tautan simbolis sebagai sampah dalam diff. Mengimpor adalah pendekatan universal. Jika Anda tidak memiliki aturan khusus untuk Claude, mulai versi 2.1.277 Anda tidak memerlukan keduanya: Claude Code akan membaca `AGENTS.md` sendiri.
Dokumentasi menunjukkan opsi tautan simbolis seperti ini:
```bash
ln -s AGENTS.md CLAUDE.md
```
Dokumentasi langsung memberikan peringatan terus terang tentang Windows:
Jika Anda atau siapa pun yang mengkloning repositori bekerja di Windows, gunakan impor @AGENTS.md. Membuat tautan simbolis di sana memerlukan hak administrator atau Developer Mode, dan Git tanpa core.symlinks yang diaktifkan akan mengambil tautan yang di-commit sebagai file teks biasa, sehingga menghasilkan CLAUDE.md satu baris alih-alih instruksi dalam salinan tersebut.
— Anthropic, https://code.claude.com/docs/en/memory
Tabel perbandingan:
| Kriteria | Impor `@AGENTS.md` | Tautan simbolis `ln -s` |
|----|----|----|
| **Berfungsi di Windows tanpa hak admin** | ya | tidak (memerlukan Developer Mode) |
| **Dapat menambahkan aturan khusus Claude** | ya, di bawah impor | tidak, filenya identik |
| **Muncul di Git sebagai markdown biasa** | ya | sebagai tautan (bergantung pada `core.symlinks`) |
| **Dapat mengimpor beberapa file** | ya, hingga empat lompatan | tidak, satu banding satu |
| **Caching/invalidasi di Claude Code** | standar untuk CLAUDE.md | berfungsi, tetapi tautan simbolis memiliki jebakan meta |
| **Pilihan default** | cocok untuk semua orang | hanya jika penggunaan lintas platform tidak menjadi masalah |
Saya menggunakan impor di proyek yang diceritakan. Alasannya:
1. **Timnya beragam.** Saya menggunakan Mac; dalam contoh ini, anggota tim terbagi kurang lebih sama rata antara Windows dan Mac. Jika ada tautan simbolis di repositori, pengguna Windows tanpa Developer Mode akan mendapatkannya sebagai file teks biasa yang berisi satu baris, `AGENTS.md`. Ini menimbulkan bug aneh: terkadang aturan berfungsi, terkadang tidak, dan penyebabnya tidak jelas.
2. **Saya ingin aturan khusus Claude.** Di bawah `@AGENTS.md`, `CLAUDE.md` saya memiliki bagian “Claude Code” dengan aturan: gunakan `--effort high` untuk tugas arsitektur, jalankan `npm run build` sebelum `git push`, dan jangan panggil `/api/v1/deploy` secara manual. Codex tidak memahami perintah-perintah ini.
3. **Lebih mudah di-debug.** Saat terjadi masalah, saya membuka `CLAUDE.md` dan melihat impor serta penggantian yang saya buat. Tautan simbolis tidak menunjukkan “ini ditambahkan di sini.” Untuk informasi lebih lanjut tentang debugging pengaturan Claude Code, lihat [panduan safe mode](https://ailoot.ai/blog/id/claude-code-safe-mode-recovery/).
Jika Anda tidak memiliki aturan khusus Claude, tautan simbolis tidak lagi diperlukan mulai versi 2.1.277: hapus `CLAUDE.md`, dan Claude Code akan membaca `AGENTS.md` sendiri. Pertahankan tautan simbolis hanya jika ada anggota tim yang menggunakan versi lebih lama dari 2.1.277 dan tidak dapat memperbarui. Jika Anda memiliki aturan khusus Claude, impor lebih praktis dalam sembilan dari sepuluh kasus.
## Apa yang dibaca Codex, Cursor, Copilot, Windsurf, dan Gemini CLI?
Poin utama
Setiap alat membaca filenya sendiri, terkadang lebih dari satu. Claude Code membaca `CLAUDE.md`, dan sejak September 2026 juga membaca `AGENTS.md` jika proyek tidak memiliki `CLAUDE.md`. Codex CLI membaca `AGENTS.md` beserta `AGENTS.override.md`. Cursor membaca format lama `.cursorrules` atau format baru `.cursor/rules/*.mdc`, dan sejak musim panas 2026 juga membaca `AGENTS.md`. Copilot membaca `.github/copilot-instructions.md` atau `.github/instructions/*.instructions.md`. Windsurf membaca `.windsurfrules` versi lama atau `.windsurf/rules/` versi baru. Gemini CLI membaca `GEMINI.md`. Aider dan Cline sudah mengadopsi `AGENTS.md`.
Peta tujuh alat utama (berdasarkan dokumentasi resmi setiap alat):
| Alat | File instruksi utama | Alternatif | Membaca AGENTS.md? |
|----|----|----|----|
| **Claude Code** | `CLAUDE.md` | `~/.claude/CLAUDE.md`, `./.claude/CLAUDE.md`, kebijakan terkelola | ya, jika proyek tidak memiliki `CLAUDE.md` (sejak 2.1.277), selain itu melalui impor |
| **Codex CLI** (OpenAI) | `AGENTS.md` | `AGENTS.override.md` | ya (native) |
| **Cursor** | `.cursor/rules/*.mdc` | `.cursorrules` (deprecated) | ya |
| **GitHub Copilot** | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | melalui ekstensi |
| **Windsurf** | `.windsurf/rules/` | `.windsurfrules` (deprecated) | ya |
| **Gemini CLI** | `GEMINI.md` | \- | tidak |
| **Aider, Cline, opencode** | `AGENTS.md` | \- | ya (native) |
Apa maknanya? Jika repositori memiliki `AGENTS.md` (serta `CLAUDE.md` dengan impor bila aturan khusus Claude diperlukan), lima dari tujuh alat otomatis memperoleh instruksi terbaru. Cursor dan Windsurf, yang memiliki filenya sendiri, dapat dibiarkan apa adanya (`AGENTS.md` juga dibaca oleh keduanya) atau diberi impor `@AGENTS.md`—tetapi sintaksnya berbeda dan dukungannya tidak selalu tersedia.
Strategi paling sederhana untuk proyek baru:
1. **Letakkan semua aturan bersama di `AGENTS.md`**—95% aturan sebaiknya ada di sana.
2. **Buat `CLAUDE.md` jika Anda memerlukan aturan khusus Claude:** letakkan `@AGENTS.md` di baris pertama, lalu tambahkan bagian berisi aturan khusus Claude di bawahnya. Jika tidak ada aturan semacam itu, `CLAUDE.md` tidak diperlukan; Claude Code telah membaca `AGENTS.md` sendiri sejak versi 2.1.277.
3. **Pertahankan `.cursor/rules/` untuk Cursor** jika dalam kasus yang jarang Anda memerlukan sesuatu yang khusus untuk Cursor (perintah `@Codebase` dan `@Docs` miliknya).
4. **Lakukan hal yang sama untuk Windsurf:** lupakan `.windsurfrules` lama; gunakan `.windsurf/rules/` baru hanya jika pola untuk sintaksnya diperlukan.
Pendekatan ini memberikan 80% manfaat dengan 20% upaya. Dari pengalaman saya, saat merapikan kerja tim campuran di “Antigravity,” mempertahankan lebih dari dua sumber kebenaran (bersama dan khusus Claude) menjadi merepotkan. Jika seseorang di tim menambahkan aturan ke `.cursorrules` dan lupa memperbarui `AGENTS.md`, seminggu kemudian Cursor dan Codex akan berbeda pendapat.
## Bagaimana /init di Claude Code menggunakan AGENTS.md yang sudah ada?
Poin utama
`/init` membuat `CLAUDE.md` dari isi repo yang sudah ada dan menghemat 20–30 menit kerja manual. Secara default, perintah ini mengambil aturan Cursor (`.cursor/rules/`, `.cursorrules`) dan Copilot (`.github/copilot-instructions.md`), sedangkan `AGENTS.md`, `.windsurfrules`, dan `.clinerules` dibaca dalam mode `CLAUDE_CODE_NEW_INIT=1`. Mode yang sama memulai alur interaktif dalam beberapa tahap: mengajukan pertanyaan, menjelajahi kode melalui subagen, dan mengusulkan rencana sebelum menulis. Sejak September 2026, `/init` memiliki kekurangan di proyek dengan `AGENTS.md`: `CLAUDE.md` baru menonaktifkan pembacaan langsung `AGENTS.md`, sehingga aturan akhirnya berada di dua file.
Anthropic menjelaskan `/init` demikian dalam dokumentasinya:
Menjalankan /init membaca file instruksi alat lain dan memindahkan bagian yang relevan ke dalam CLAUDE.md yang dihasilkan: aturan Cursor dari .cursor/rules/ atau .cursorrules, aturan Copilot dari .github/copilot-instructions.md, serta, dengan CLAUDE_CODE_NEW_INIT=1, juga AGENTS.md, .devin/rules/, .windsurf/rules/ atau .windsurfrules, dan .clinerules.
— Anthropic, https://code.claude.com/docs/en/memory
Apa artinya dalam praktik? Repo yang saya ceritakan memiliki `.cursorrules` dari saat saya mencoba Cursor (sekitar 80 baris), serta `AGENTS.md` (120 baris, dirangkai secara manual). Saat saya menjalankan `claude /init`, perintah itu mengambil kedua file, menghapus aturan serupa yang berulang, lalu menyusun `CLAUDE.md` yang rapi dalam satu menit. Setelah itu saya memeriksanya dan membuat sedikit penyuntingan—menghapus butir yang sudah usang dan menambahkan struktur dengan judul. Ini lebih cepat daripada menulis ulang dari awal.
Mode interaktif, yang juga membuat `/init` membaca `AGENTS.md`, diaktifkan melalui variabel lingkungan:
```bash
CLAUDE_CODE_NEW_INIT=1 claude
```
Setelah `/init` dimulai, Claude mengajukan serangkaian pertanyaan klarifikasi: artefak mana yang perlu dikonfigurasi (`CLAUDE.md`, skills, hooks), stack apa yang digunakan proyek, dan perintah apa yang digunakan untuk pengujian. Lalu sebuah subagen menjelajahi basis kode—membaca `package.json`, `README.md`, dan file konfigurasi—serta melengkapi bagian yang belum ada. Pada akhirnya, Claude menampilkan usulan yang dapat Anda sunting sebelum menyimpannya. Untuk informasi lebih lanjut tentang mengonfigurasi Claude Code saat memulai proyek, lihat [panduan terpisah](https://ailoot.ai/blog/id/spec-kit-claude-code-spec-driven-development/).
Sekarang kekurangannya. Jika proyek sudah memiliki `AGENTS.md` yang aktif, `/init` akan membuat `CLAUDE.md` di sampingnya dengan salinan aturan tersebut. Sejak saat itu, secara default Claude Code hanya membaca `CLAUDE.md`, sehingga ada dua sumber kebenaran lagi: Anda memperbarui `AGENTS.md`, sedangkan Claude terus bekerja dari salinan lama. Perintah `/import` melakukan hal serupa: menambahkan salinan satu kali dari `AGENTS.md` ke `CLAUDE.md`. Agar tetap memiliki satu sumber, letakkan impor `@AGENTS.md` pada baris pertama `CLAUDE.md` setelah `/init`, lalu hapus apa pun dari `CLAUDE.md` yang mengulang isi `AGENTS.md`.
`/init` adalah titik awal yang tepat untuk proyek baru atau proyek yang Anda pindahkan dari Cursor atau Copilot. Anda tidak perlu mencari “template CLAUDE.md terbaik” di internet—Anthropic sudah mempertimbangkan isi repo. Jika proyek sudah memiliki `AGENTS.md` aktif dan tidak ada aturan khusus Claude, `/init` tidak diperlukan: Claude Code akan membaca `AGENTS.md` sendiri.
## Bagaimana cara memisahkan instruksi bersama dan instruksi khusus Claude?
Poin utama
Letakkan aturan yang dapat dipahami agen AI mana pun di `AGENTS.md`: apa yang tidak boleh disentuh, cara menamai cabang, bahwa `.env` berisi rahasia, dan perintah yang digunakan untuk pengujian. Letakkan aturan khusus Claude Code di `CLAUDE.md` (di bawah impor): plan mode, skills, hooks, referensi skill, dan nama model menurut versi. Pembedanya sederhana: jika sebuah aturan diawali dengan “Claude sebaiknya,” masukkan ke `CLAUDE.md`. Jika diawali dengan “alat sebaiknya,” masukkan ke `AGENTS.md`.
Saya memisahkannya berdasarkan prinsip ini. Aturan bersama yang dimasukkan ke `AGENTS.md`:
- **Apa yang tidak boleh disentuh dalam kode.** Folder `.env`, `node_modules`, `prisma/migrations` (hanya melalui `prisma migrate`), `.next/`, `.git/`.
- **Cara menamai berbagai hal.** Cabang: awalan `feat/`, `fix/`, `chore/`. Commit: awalan `feat:`, `fix:`, `docs:` ditambah deskripsi singkat. File komponen menggunakan `kebab-case`.
- **Perintah pengujian/lint.** `npm run build`, `npm run lint`, `npm test`. Perintah mana yang harus dijalankan sebelum `git push`.
- **Prinsip arsitektur.** Apa yang masuk ke `src/lib/`, apa yang masuk ke `src/components/`, di mana logika bisnis berada, dan di mana UI berada.
- **Keamanan.** Jangan pernah meng-commit rahasia. Akses basis data produksi hanya melalui `prod-psql`. Akses produksi melalui SSH hanya lewat alias `prod`, bukan `root@IP`.
Aturan khusus Claude yang dimasukkan ke `CLAUDE.md` (di bawah `@AGENTS.md`):
- **Plan mode.** Gunakan `plan mode` untuk perubahan di direktori berisiko (misalnya, `src/billing/`).
- **Tingkat upaya.** Gunakan `--effort high` untuk tugas arsitektur dan `medium` untuk pekerjaan rutin.
- **Skills.** Agen AI dan skill mana yang dijalankan dalam situasi tertentu. Misalnya: “saat mengerjakan panduan, jalankan skill `build-masterskaya-guide`.”
- **Memori Claude.** Apa yang dimasukkan ke memori otomatis dan apa yang dimasukkan ke `CLAUDE.local.md`. Untuk informasi lebih lanjut tentang memori Claude, lihat [panduan Memori dan CLAUDE.md](https://ailoot.ai/blog/id/claude-memory-claude-md-auto-memory/).
- **Hooks.** Jika `.claude/settings.json` memiliki hook yang dikonfigurasi, jelaskan fungsinya dalam `CLAUDE.md` (Codex dan Cursor tidak mengetahui hook ini dan tidak perlu mengetahuinya).
- **Skills dan perintah.** Daftar perintah garis miring yang sering saya gunakan (`/init`, `/cd`, `/memory`, `/plan`).
Batasnya tidak selalu jelas. Misalnya, “jangan pernah menjalankan `git push --force` ke `main`” jelas merupakan aturan bersama, jadi masukkan ke `AGENTS.md`. Namun, “saat menjalankan `git push` ke cabang hot, gunakan plan mode terlebih dahulu” khusus untuk Claude Code, jadi masukkan ke `CLAUDE.md`. Ujiannya: “Jika besok saya menghapus Claude Code dan hanya mempertahankan Codex, apakah aturan ini masih berlaku?” Jika ya, masukkan ke `AGENTS.md`. Jika tidak, masukkan ke `CLAUDE.md`.
## Apa yang sebaiknya dimasukkan ke AGENTS.md, dan apa yang sebaiknya dimasukkan ke CLAUDE.md atau .claude/rules?
Poin utama
Untuk proyek besar, satu `AGENTS.md` tidak cukup—file itu akan tumbuh terlalu besar, dan setiap agen membawa materi yang tidak diperlukan ke dalam konteksnya. Solusinya adalah direktori `.claude/rules/` dengan file terpisah berdasarkan topik serta YAML frontmatter `paths:` untuk pemicu berbasis jalur. Misalnya, aturan API hanya berlaku ketika Claude bekerja di `src/api/`. Ini menghemat banyak ruang context window. Padanan untuk Cursor adalah `.cursor/rules/`, dan untuk Windsurf adalah `.windsurf/rules/`.
Jika aturan melebihi 200 baris, sudah waktunya untuk memisahkannya. Dokumentasi Anthropic menyarankan untuk menargetkan 200 baris per file, karena file `CLAUDE.md` yang panjang mulai diam-diam mengurangi kepatuhan: Claude tampaknya membacanya, tetapi lebih jarang mengikutinya.
Struktur untuk proyek besar yang berfungsi bagi saya:
```
my-project/
├── AGENTS.md # 100-150 lines, shared
├── CLAUDE.md # 30-50 lines: @AGENTS.md + Claude-only
└── .claude/
├── CLAUDE.md # alternative to root file, same file
└── rules/
├── api.md # with paths: ['src/api/**']
├── components.md # with paths: ['src/components/**']
├── testing.md # without paths, always active
└── security.md # without paths, always active
```
Setiap file di `.claude/rules/` dapat memiliki frontmatter:
```markdown
---
paths:
- "src/api/**/*.ts"
---
# API rules
- Every endpoint validates input with zod
- Errors use the standard `{error, code}` format
- OpenAPI comments are required
```
Claude memuat aturan ini hanya ketika bekerja dengan file yang cocok dengan pola tersebut. Jika Claude menyentuh `src/components/Button.tsx`, aturan API tidak ditambahkan ke konteks. Dengan cara ini, context window hanya digunakan untuk hal yang relevan. Direktori `.claude/rules/` juga berfungsi tanpa `CLAUDE.md`: jika proyek hanya berisi `AGENTS.md`, aturannya dimuat bersamanya dan tidak menonaktifkan pembacaan langsung `AGENTS.md`.
Cursor dan Windsurf mendukung pendekatan yang sama melalui direktori `.cursor/rules/` dan `.windsurf/rules/`. Standar AGENTS.md dapat merujuk ke direktori ini, tetapi sintaks lintas alat belum sepenuhnya stabil. Lebih aman menyimpan aturan bersama di `AGENTS.md` dan menggandakan aturan yang cakupannya dibatasi jalur di `.claude/rules/` dan `.cursor/rules/`—kasus khusus ini jarang terjadi, bukan bagian terbesar dari aturan.
Lokasi yang berguna untuk CLAUDE.md (diurutkan dari cakupan terluas hingga tersempit):
| Tingkat | Lokasi | Tujuan |
|----|----|----|
| **Kebijakan terkelola** | `/Library/Application Support/ClaudeCode/CLAUDE.md` (Mac), `/etc/claude-code/CLAUDE.md` (Linux) | Aturan perusahaan, IT/DevOps |
| **Pengguna** | `~/.claude/CLAUDE.md` | Preferensi pribadi di semua proyek |
| **Proyek** | `./CLAUDE.md` atau `./.claude/CLAUDE.md` | Aturan tim proyek |
| **Lokal** | `./CLAUDE.local.md` (di `.gitignore`) | Preferensi pribadi untuk proyek tertentu |
Contoh `~/.claude/CLAUDE.md` mungkin berisi dua aturan: “jawab dalam bahasa pilihan pengguna” dan “eja Ailoot persis seperti ini.” Aturan ini berlaku untuk setiap proyek, sehingga tidak perlu menggandakannya di setiap repositori.
Dari keempat tingkat ini, hanya `CLAUDE.md` tingkat proyek dan `CLAUDE.local.md` yang menonaktifkan pembacaan langsung `AGENTS.md`. `~/.claude/CLAUDE.md` pribadi dan kebijakan terkelola tidak menghalangi; Claude Code membacanya bersama `AGENTS.md`.
## Apa yang harus dilakukan jika AGENTS.md di proyek Anda sudah usang?
Poin utama
Jika `AGENTS.md` dirangkai pada 2025 untuk Codex atau Aider dan belum disunting sejak itu, buka proyek di Claude Code dan minta Claude menyunting file tersebut. AGENTS.md adalah dokumen hidup; spesifikasi Linux Foundation diperbarui. Aturan utama untuk menjaganya tetap mutakhir: setiap aturan harus menjawab “Apa yang sudah bosan saya ulang kepada Claude/Codex?” Jika tidak, arsipkan.
Di proyek yang saya ceritakan, saya memiliki `AGENTS.md` dari Mei 2025—180 baris, banyak di antaranya sudah usang (file tersebut menyebut endpoint Anthropic API yang sudah berubah sejak itu; contoh sintaks `claude --tools` yang sudah tidak ada; serta aturan tentang `~/.claude/projects/` dengan struktur yang sudah usang).
Rencana yang saya gunakan untuk memperbaruinya:
1. **Tinjau dengan `claude` dalam plan mode.** Saya membuka repo, menjalankan `claude --safe-mode`, lalu meminta: “Baca ulang `AGENTS.md` dan sarankan daftar butir yang sudah usang atau berulang. Jangan sunting; daftarkan saja.” Dalam dua menit, saya mendapat daftar berisi 23 butir untuk ditinjau.
2. **Hapus butir yang jelas sudah usang.** Dari 23 butir, 9 jelas sudah kedaluwarsa—sintaks perintah, endpoint, dan nama flag. Saya menghapus baris-baris itu.
3. **Gabungkan duplikat.** Enam butir lainnya mengulang hal yang sama dengan kata-kata berbeda (“jangan force-push,” “jangan pernah gunakan `--force`,” “hindari `git push -f`”). Saya menggabungkannya menjadi satu baris.
4. **Tambahkan butir baru.** Saya menambahkan hal-hal yang berulang kali salah dilakukan Claude/Codex selama sebulan terakhir, mengikuti aturan “satu baris untuk setiap pola kesalahan.” Hasilnya delapan butir baru.
5. **Jalankan subagen untuk peninjauan akhir.** Saya meminta Claude meninjau dengan instruksi “temukan kontradiksi, ambiguitas, dan duplikat.” Claude menemukan tiga frasa yang dapat diperjelas. Saya memperbaikinya.
Setelah satu jam, `AGENTS.md` menjadi 110 baris, mutakhir, dan saya mengenal setiap barisnya. Membuat `CLAUDE.md` 30 baris darinya pun mudah. Codex juga tampak lebih berhati-hati saat menangani pengujian setelahnya—saya menduga beberapa keputusan “aneh” yang dibuatnya berasal dari aturan usang yang diikutinya dengan itikad baik.
Prinsip utama untuk `AGENTS.md` yang terus diperbarui:
- **Setiap aturan menjawab kesalahan berulang.** Jika selama sebulan saya tidak pernah memikirkan suatu aturan, tidak ada gunanya mempertahankannya.
- **Tuliskan aturan sebagai perintah, bukan teori.** “Gunakan dua spasi” adalah aturan. “Gaya kode harus rapi” bukan.
- **Hal spesifik lebih baik daripada hal umum.** “Jalankan `npm run build` sebelum `git push`” adalah aturan. “Uji perubahan Anda” bukan.
## Apa yang PASTI TIDAK berfungsi dengan pengaturan ini?
Poin utama
Mengimpor `@AGENTS.md` tidak membuat berbagai alat berperilaku sebagai satu kesatuan. Masing-masing memiliki keunikannya sendiri: Codex CLI tidak mengetahui `.claude/rules/` atau hooks. Cursor memiliki mesin pelengkapan otomatis sendiri, yang tidak membaca CLAUDE.md saat melengkapi teks. Copilot mengikuti `.github/copilot-instructions.md`, dan aturan yang hanya ada di AGENTS.md tidak cukup baginya. Ini bukan “satu file = satu perilaku”; artinya adalah “satu sumber untuk aturan dasar, lalu setiap alat memiliki tambahannya sendiri.”
Beberapa hal yang saya pelajari dengan susah payah selama enam bulan menggunakan pengaturan ini:
**1. Pelengkapan otomatis Cursor tidak menggunakan AGENTS.md.** Saat Cursor menyarankan pelengkapan baris di editor, ia tidak membaca `AGENTS.md` secara real-time—ada mesin cepat terpisah yang bekerja. Aturan di AGENTS.md hanya berpengaruh saat Anda mengirim permintaan chat di dalam Cursor. Artinya, menulis “jangan gunakan `var`, gunakan `const`” di AGENTS.md tidak akan memengaruhi pelengkapan otomatis; Anda perlu mengaturnya melalui ESLint atau konfigurasi TypeScript.
**2. Hook Claude Code di AGENTS.md tidak berfungsi untuk Codex.** Jika `.claude/settings.json` memiliki hook PreToolUse yang dikonfigurasi untuk memblokir tindakan tertentu, informasi ini hanya berguna bagi Claude. Codex tidak mengetahui hooks; baginya, ini berarti “alat memutuskan sendiri.” Masuk akal untuk menulis “jangan lakukan X” di `AGENTS.md`, dan “ada hook yang secara fisik memblokir X” di `CLAUDE.md` di bawah impor.
**3. Copilot dan `.github/copilot-instructions.md`.** GitHub Copilot membaca filenya sendiri dan masih tidak terlalu baik dalam membaca AGENTS.md. Jika tim Anda aktif menggunakan Copilot, tambahkan file `.github/copilot-instructions.md` terpisah yang berisi versi aturan yang lebih singkat, atau gunakan [Copilot Extensions](https://github.com/marketplace?type=apps&category=copilot-extensions) yang memahami AGENTS.md. Perkembangannya cepat, sehingga gambaran ini mungkin berbeda dalam tiga hingga enam bulan.
**4. Git tidak melacak tautan simbolis sebagai perubahan CLAUDE.md.** Jika Anda menjalankan `ln -s AGENTS.md CLAUDE.md` lalu memperbarui `AGENTS.md` seminggu kemudian, Git hanya akan menampilkan diff untuk `AGENTS.md`. Itu normal, tetapi kolega yang meninjau PR mungkin tidak menyadari bahwa `CLAUDE.md` juga telah diperbarui (melalui tautan simbolis). Solusinya: tulis secara eksplisit di deskripsi PR, “`AGENTS.md` diperbarui; Claude Code melihat file yang sama melalui tautan simbolis.”
**5. Impor berlapis sulit di-debug.** Jika `AGENTS.md` mengimpor `@docs/coding-style.md`, yang mengimpor `@docs/typescript.md`, dan ada aturan yang bertentangan, proses debugging menjadi sulit. Saya membatasi impor ke satu tingkat (`CLAUDE.md` → `AGENTS.md`) dan tidak membuatnya bersarang lebih jauh. Anthropic menyediakan hook `InstructionsLoaded` yang mencatat file mana yang dimuat—berguna untuk men-debug pengaturan berlapis. Catatan: hook ini aktif untuk `AGENTS.md` yang disertakan melalui impor atau tautan simbolis, tetapi tidak untuk `AGENTS.md` yang dibaca Claude Code sendiri.
### Sumber
- [Dokumentasi Memori Claude Code - bagian AGENTS.md](https://code.claude.com/docs/en/memory#agents-md) - kapan Claude Code membaca AGENTS.md sendiri, pengaturan Project instructions, impor dan tautan simbolis, serta perilaku `/init`.
- [Dokumentasi Memori Claude Code - mengimpor file tambahan](https://code.claude.com/docs/en/memory#import-additional-files) - sintaks `@path/to/file`, kedalaman empat lompatan, serta jalur relatif dan absolut.
- [agents.md - standar Linux Foundation](https://agents.md/) - standar AGENTS.md resmi dan daftar alat yang mendukungnya.
- [Dokumentasi Cursor Rules](https://docs.cursor.com/context/rules-for-ai) - apa yang dibaca Cursor (`.cursor/rules/*.mdc`, AGENTS.md).
- [Instruksi Khusus GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) - format `.github/copilot-instructions.md`.
- [Spesifikasi AGENTS.md di Linux Foundation](https://aaif.io/projects/agents-md/) - spesifikasi yang terus diperbarui.
Pengaturan vibe-coding lengkap untuk satu malam: **klon AI + Otak Kedua + rekayasa konteks**.
Kenali [Ailoot](https://ailoot.ai/).
## Pertanyaan tentang Satu File Instruksi untuk Claude Code, Codex, dan Cursor pada 2026
### Kapan memakai impor alih-alih symlink?
Gunakan `@AGENTS.md` dalam `CLAUDE.md` ketika perlu tambahan khusus Claude atau rekan memakai Windows. Symlink membuat kedua nama menunjuk isi yang sama, sehingga tidak dapat memuat bagian Claude tersendiri.
### Bagaimana memeriksa instruksi bersama dimuat?
Jalankan `/memory` dan periksa file instruksi yang tercantum. Jika `CLAUDE.md` atau `CLAUDE.local.md` menghalangi pemuatan AGENTS.md langsung pada konfigurasi Anda, tambahkan impor atau pilih pengaturan yang memuat keduanya, lalu mulai sesi baru.
## Ailoot · Perusahaan dan portofolio proyeknya
Ailoot bertumpu pada pengalaman operasional yang teruji, basis pelanggan yang besar, layanan yang stabil, dan pemantauan KPI berkelanjutan.
Perusahaan dan portofolio proyeknya: jutaan pelanggan; penjualan miliaran setiap bulan.
Ailoot memanfaatkan pengalaman operasional ini untuk akses API ke fitur AI dalam produk pelanggan, agen, aplikasi, dan otomatisasi.