Blog

Apa Itu AGENTS.md dan Cara Menulis Sendiri dalam 30 Menit

Markdown

Format AGENTS.md, dukungan di berbagai alat AI, templat siap pakai, aturan, dan kesalahan. Cara menyelaraskan AGENTS.md dengan CLAUDE.md dan file instruksi lainnya.

Baca artikel lengkap

Materi praktis tentang vibe coding dan bekerja dengan agen: dokumentasi Ailoot.

AGENTS.md dalam Satu Paragraf

Poin utama

AGENTS.md adalah file Markdown biasa di root proyek Anda yang berisi instruksi untuk agen AI: cara memasang dependensi, cara menjalankan tes, gaya kode yang harus diikuti, dan hal-hal yang tidak boleh disentuh. Format ini terbuka, dibuat oleh OpenAI pada Agustus 2025, dan bergabung dengan Linux Foundation pada Desember tahun yang sama. Banyak alat pemrograman dapat memakainya, tetapi cara menemukan file berbeda menurut klien dan versinya: sebagian memuat AGENTS.md otomatis, sementara yang lain memerlukan pengaturan nama file atau konfigurasi pembacaan file secara eksplisit. Sejak versi 2.1.277 (September 2026), Claude Code juga membaca AGENTS.md jika proyek tidak memiliki CLAUDE.md. Jika CLAUDE.md tersedia, Claude Code hanya membaca file itu secara default, dan AGENTS.md disertakan dengan baris @AGENTS.md atau melalui symlink.

Di bawah ini, format tersebut dibahas berdasarkan agents.md, dokumentasi OpenAI Codex, JetBrains Junie, Cursor Rules Docs, changelog GitHub Copilot Coding Agent, dan siaran pers Linux Foundation tentang Agentic AI Foundation. Semua angka dan fitur berlaku per 30 Mei 2026, dan dukungan AGENTS.md di Claude Code dijelaskan berdasarkan dokumentasi Anthropic, dengan pembaruan dari 24 September 2026.

Jika Anda tidak tahu apa itu kebun binatang alat yang beredar di pasar ini atau mengapa semuanya membutuhkan file bersama, baca dulu panduan “Apa yang Digunakan untuk Coding pada 2026: 8 Alat AI dari Claude Code hingga Antigravity”. Artikel ini secara khusus membahas format AGENTS.md dan cara menulisnya sendiri dalam 30 menit.

Apa Itu AGENTS.md dan Dari Mana Asalnya?

Poin utama

AGENTS.md adalah format file Markdown terbuka yang memungkinkan Anda menulis sendiri instruksi untuk agen AI. OpenAI merilisnya pada Agustus 2025 bersama Codex CLI dan langsung mengundang rekan penulis: Cursor, Sourcegraph Amp, Google Jules, dan Factory. Gagasannya sederhana: “jangan membuat file berpemilik untuk setiap alat; mari sepakati satu format.” Pada 9 Desember 2025, AGENTS.md, bersama MCP dari Anthropic dan goose dari Block, bergabung dengan Linux Foundation sebagai salah satu dari tiga proyek pendiri Agentic AI Foundation yang baru. Pada Desember tahun yang sama, lebih dari 60.000 repositori GitHub sudah memiliki AGENTS.md di root-nya.

Sebelumnya, setiap alat AI memiliki file aturannya sendiri: Anthropic memiliki CLAUDE.md, Cursor memiliki .cursorrules, GitHub memiliki .github/copilot-instructions.md, Aider memiliki .aider.conf.yml, dan JetBrains memiliki .junie/guidelines.md. Jika tim Anda memiliki tiga agen berbeda, artinya ada tiga file paralel dengan isi yang sama, yang akan mulai berbeda dalam waktu seminggu.

OpenAI adalah yang pertama merasa lelah dengan keadaan ini. Pada Agustus 2025, OpenAI merilis Codex CLI sekaligus meluncurkan agents.md sebagai format terbuka. Dari situs tersebut:

“Anggap AGENTS.md sebagai README untuk agen.”

(agents.md, diterjemahkan dari bahasa Inggris)

Intinya, AGENTS.md melengkapi README. README ditulis untuk manusia: “apa proyek ini, cara menjalankannya secara lokal, cara berkontribusi.” AGENTS.md ditulis untuk agen: perintah shell yang tepat, kriteria “selesai” yang dapat diverifikasi, dan batasan seperti “jangan pernah menyentuh ini.”

Dari situs tersebut:

“AGENTS.md melengkapi README: file ini memuat konteks tambahan, yang terkadang terperinci, yang dibutuhkan agen—langkah build, pengujian, dan konvensi yang akan membuat README terlalu penuh atau memang tidak diperlukan oleh kontributor manusia.”

(agents.md, diterjemahkan dari bahasa Inggris)

Pada September 2025, GitHub Copilot Coding Agent mendukung format ini (changelog, 28.08.2025). Pada Desember, Cursor, Junie, Gemini CLI, Aider, dan belasan alat lainnya ikut bergabung. Pada 9 Desember 2025, Linux Foundation membentuk Agentic AI Foundation (AAIF): tiga proyek pendirinya adalah AGENTS.md dari OpenAI, MCP dari Anthropic, dan goose dari Block. Anggota pendirinya adalah AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft, dan OpenAI. Pada 24 Februari 2026, yayasan tersebut sudah mencakup 146 organisasi, termasuk Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, UiPath, dan Hitachi.

Sejak saat itu, AGENTS.md berhenti menjadi “hal lain dari OpenAI” dan menjadi standar de facto.

Agen AI Mana yang Membaca AGENTS.md, dan Mana yang Tidak?

Poin utama

AGENTS.md dipakai oleh banyak alat pemrograman, termasuk klien dalam tabel di bawah. Baca tabel sebagai peta cara memuat file, bukan jaminan dukungan native yang seragam: penemuan otomatis, konfigurasi eksplisit, prioritas nama file, dan penanganan file bertingkat dapat berbeda. Claude Code dari Anthropic adalah pengecualian sejak lama: issue #6235, yang meminta dukungan, tetap terbuka dari Agustus 2025 hingga Agustus 2026. Sejak versi 2.1.277 (18 September 2026), Claude Code membaca AGENTS.md sendiri jika proyek tidak memiliki CLAUDE.md. Jika CLAUDE.md tersedia, secara default hanya file itu yang dibaca, dan AGENTS.md disertakan dengan baris @AGENTS.md di dalam CLAUDE.md atau melalui symlink.

Tabel dukungan per 30 Mei 2026; baris Claude Code diperbarui pada 24 September 2026:

AlatMembaca AGENTS.mdTanggal / sumber
OpenAI Codex CLIYa (format native)Agustus 2025, agents.md
GitHub Copilot Coding AgentYa28.08.2025, GitHub Changelog
CursorYa, root + bertingkatCursor Rules Docs
JetBrains JunieYa, proyek + global ~/.junie/AGENTS.mdJunie Docs
Gemini CLI (Google)Ya, melalui .gemini/settings.json dengan fileName: AGENTS.mdagents.md
Jules (Google)Ya, rekan penulis standarAgustus 2025
Sourcegraph AmpYa, rekan penulis standarAgustus 2025
AiderYa, melalui read: AGENTS.md di .aider.conf.ymlagents.md
FactoryYa, rekan penulis standarAgustus 2025
OpenCodeYa—
ZedYaagents.md
WarpYaagents.md
VS CodeYaagents.md
WindsurfYa—
Devin (Cognition)Ya, melalui Spec Kit SkillsApril 2026
RooCode, Kilo Code, Augment CodeYaagents.md
Claude Code (Anthropic)Ya, jika proyek tidak memiliki CLAUDE.mdSejak versi 2.1.277 (18.09.2026), dokumentasi Claude Code

Anthropic menjadi pemain besar terakhir yang bergabung. Pada Agustus 2025, issue #6235 yang meminta dukungan AGENTS.md dibuka di repositori resmi anthropics/claude-code.

Issue tersebut tetap terbuka selama hampir setahun dan ditutup pada 17 Agustus 2026; versi 2.1.277 yang mendukung AGENTS.md dirilis pada 18 September. Logika Anthropic sebagai berikut: CLAUDE.md diutamakan, dan AGENTS.md dibaca jika tidak ada CLAUDE.md di folder kerja atau folder induk mana pun. Menurut dokumentasi, cara kerjanya seperti ini:

Isi proyekYang dibaca Claude Code
Hanya AGENTS.mdAGENTS.md
AGENTS.md dan CLAUDE.md (atau CLAUDE.local.md)Hanya CLAUDE.md
CLAUDE.md dengan baris @AGENTS.mdCLAUDE.md, yang menyertakan AGENTS.md

Catatannya: CLAUDE.local.md pribadi juga dihitung, dan dengan file itu Claude Code berhenti membaca AGENTS.md. Anda dapat mengubah perilaku ini di /config, pada bagian Project instructions—misalnya, agar Claude Code membaca kedua file sekaligus. Pada versi sebelum 2.1.277, AGENTS.md tidak akan terdeteksi secara otomatis; baris @AGENTS.md di CLAUDE.md masih menjadi solusinya.

Apa Perbedaan AGENTS.md dengan CLAUDE.md dan .cursorrules?

Poin utama

Secara teknis, tidak ada yang istimewa dari semua itu: keempat format (AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md) adalah file Markdown biasa dengan instruksi untuk agen. Perbedaannya adalah siapa yang membacanya dan di mana file tersebut berada. AGENTS.md dapat menyimpan instruksi bersama bagi beberapa klien, dengan penemuan file atau konfigurasi khusus tiap klien disimpan terpisah. CLAUDE.md hanya untuk Claude Code, tetapi menyediakan fitur tingkat lanjut: aturan yang dibatasi berdasarkan path, CLAUDE.local.md untuk penggantian pribadi, @import untuk menyertakan file lain, serta hierarki proyek + pengguna + lokal. .cursorrules sudah usang di Cursor—sistem baru menggunakan .cursor/rules/*.mdc dengan pemasangan otomatis berdasarkan jenis file. .github/copilot-instructions.md hanya diperlukan untuk Copilot web.

Perbandingan empat format per 30 Mei 2026:

FormatSiapa yang membacanyaLokasiKelebihanKekurangan
AGENTS.mdBeberapa klien dengan jalur pemuatan berbedaRoot/file bertingkat menurut aturan klienInstruksi bersama tanpa terikat satu penyediaPerlu memverifikasi penemuan, konfigurasi, dan prioritas tiap klien
CLAUDE.mdHanya Claude CodeRoot + ~/.claude/CLAUDE.md + CLAUDE.local.mdHierarki, aturan berbasis path, @import, skills, hooksHanya Claude. Tidak berfungsi di Cursor / Codex / Copilot
.cursor/rules/*.mdcHanya Cursor.cursor/rules/<rule>.mdcPemasangan otomatis berdasarkan jenis file (TS, Python, path tertentu)Hanya Cursor, sintaks .mdc tidak standar
.github/copilot-instructions.mdGitHub Copilot (web + klasik).github/Berfungsi langsung di browser pada GitHub.comHanya Copilot, menggandakan AGENTS.md

AGENTS.md dapat menyimpan instruksi proyek bersama, sedangkan jalur pemuatan dan pengaturan pribadi tiap klien tetap memerlukan konfigurasi terpisah. Claude Code memiliki CLAUDE.local.md untuk itu, sedangkan Cursor memiliki file .mdc lokal di bawah pengguna. AGENTS.md saja tidak menyediakan hal tersebut—Anda perlu menggabungkannya dengan file lain atau menyepakati di tim untuk menulis aturan pribadi di bagian yang diabaikan Git.

Detail penting lainnya adalah monorepo. Codex dan Cursor menerapkan aturan “AGENTS.md terdekat yang berlaku”:

“Di monorepo, letakkan AGENTS.md terpisah di setiap paket. Agen otomatis membaca file terdekat dalam pohon direktori, dan file terdekat yang berlaku akan menang.”

(agents.md, diterjemahkan dari bahasa Inggris)

agents.md menyebutkan bahwa monorepo utama OpenAI memuat 88 file AGENTS.md untuk berbagai subpaket. Jika Anda bekerja di monorepo, sebarkan aturan ke beberapa tingkat: aturan umum di root, aturan khusus di subfolder.

Apa Isi AGENTS.md yang Baik?

Poin utama

Kerangka AGENTS.md yang baik memiliki 8 bagian yang ditemukan di sebagian besar file populer: Gambaran umum proyek, Perintah penyiapan, Gaya kode, Tips lingkungan pengembangan, Instruksi pengujian, Panduan PR, Pertimbangan keamanan, dan Batasan (hal yang tidak boleh dilakukan). Yang lainnya opsional. Aturan utamanya: setiap butir harus berupa perintah yang tepat atau contoh konkret, bukan gagasan umum seperti “tulis kode yang rapi.”

Situs agents.md menawarkan format yang fleksibel—“Markdown apa pun.” Namun, 80% file bagus yang ditemukan di lapangan berisi delapan bagian yang sama. Aturan utamanya: setiap butir harus berupa perintah yang tepat atau contoh konkret. Gagasan abstrak seperti “tulis kode yang rapi” akan diabaikan agen.

  1. Gambaran umum proyek — 2–3 baris. Apa proyeknya, untuk siapa, dan apa tujuan utamanya. Tanpa pemasaran. Contoh: “Bot Telegram untuk orientasi peserta lokakarya berbayar. Stack: Next.js 14, Prisma, PostgreSQL. Dipicu oleh catatan baru di purchases.”
  2. Perintah penyiapan — perintah shell yang tepat untuk dijalankan secara lokal. npm install, npm run dev, npm run build. Tidak perlu kalimat “biasanya begini cara kita melakukannya.”
  3. Gaya / konvensi kode — aturan khusus dengan contoh, bukan “tulis dengan rapi.” Misalnya: “TypeScript strict, tanda petik tunggal, tanpa default export, nama komponen dalam PascalCase, nama hook dimulai dengan use.”
  4. Tips lingkungan pengembangan — lokasi hal-hal penting. Variabel apa yang dibutuhkan dalam .env, lokasi penyimpanan rahasia, port yang sedang digunakan, dan cara bekerja dengan DB lokal.
  5. Instruksi pengujian — cara menjalankan pengujian tertentu dan kriteria “lulus”. Misalnya: npm test -- --testPathPattern=user-auth; diharapkan 100% lulus.
  6. Panduan PR / commit — format pesan commit, daftar periksa sebelum PR (tes, linter, dokumentasi), dan siapa yang menyetujui.
  7. Pertimbangan keamanan — hal yang tidak boleh terjadi. “Jangan pernah commit .env. Rahasia hanya boleh disimpan di Vault. Jangan tampilkan data pribadi pengguna di log.”
  8. Batasan / Jangan pernah lakukan ini — larangan disertai alternatif. “Jangan gunakan git push --force pada main. Jika perlu membatalkan perubahan, gunakan git revert atau git reset pada feature branch.”

Untuk setiap bagian, gunakan prinsip “perintah alih-alih gagasan.” Agen akan mengabaikan “berhati-hatilah dengan migrasi.” Agen akan mengikuti “Sebelum alembic upgrade head, jalankan alembic check. Jika melaporkan kesalahan, jangan terapkan migrasi; tanyakan kepada saya.”

Templat AGENTS.md Siap Pakai (Salin dan Sesuaikan)

Poin utama

Di bawah ini adalah templat awal AGENTS.md untuk proyek web biasa. Salin ke root repositori, ganti <project-name>, <stack>, perintah yang tepat, dan hapus bagian yang tidak diperlukan. Menyesuaikannya memerlukan waktu 20–30 menit—atau lebih lama jika ini pertama kalinya.

# AGENTS.md

## Gambaran umum proyek

<project-name> - <one phrase describing its purpose>.
Stack: <Next.js / Python / Go / ...>.
Main entities: <users, orders, posts ...>.
Details for people are in README.md.

## Perintah penyiapan

```bash
# first install
npm install
cp .env.example .env  # then fill in manually; see list below

# run
npm run dev           # dev server on :3000
npm run build         # production build
npm run start         # run production build
```

## Lingkungan pengembangan

- Node 20+ (via nvm: `nvm use 20`)
- PostgreSQL 16 secara lokal di :5432 (`docker-compose up postgres`)
- Redis opsional, hanya dibutuhkan untuk antrean (`docker-compose up redis`)
- `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET`
- Jangan pernah membaca seluruh file `.env`. Jika membutuhkan satu variabel: `grep "^VAR=" .env`

## Gaya kode

- TypeScript strict mode
- Tanda petik tunggal, tanpa titik koma (kecuali ESLint mengharuskannya)
- Impor: eksternal lebih dahulu, lalu internal melalui `@/`, lalu relatif
- Komponen dalam PascalCase; nama hook dimulai dengan `use`
- Jangan gunakan `any` tanpa komentar eksplisit yang menjelaskan “mengapa tipenya tidak bisa ditentukan”

Contoh modul yang baik:

```ts
import { z } from 'zod'

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
})

export function parseUser(raw: unknown) {
  return UserSchema.parse(raw)
}
```

## Pengujian

```bash
npm test                                # semua tes
npm test -- --testPathPattern=auth      # khusus auth
npm test -- --watch                     # mode watch
```

Semua tes harus lulus (berwarna hijau) sebelum commit. Jika sebuah tes gagal, jangan commit; tanyakan kepada saya apa yang harus dilakukan.

## Panduan pull request

- Format commit: `<type>(<scope>): <description>` (`feat(auth): add magic-link`)
- Sebelum PR: `npm run build && npm test && npm run lint`
- Deskripsi PR = apa yang berubah, mengapa, dan cara mengujinya
- Jangan menyetujui PR sendiri—selalu tunggu tinjauan manusia

## Keamanan

- Rahasia hanya di `.env` dan Vault, jangan pernah di kode
- Jangan mencatat data pribadi (email, telepon, nama)
- Saat bekerja dengan DB produksi, gunakan hanya kueri baca-saja kecuali ada otorisasi eksplisit
- Jangan hardcode kunci API layanan eksternal (Stripe, OpenAI) di tes

## Jangan pernah lakukan ini

- Jangan `git push --force` ke main. Jika perlu membatalkan perubahan, gunakan `git revert` atau buka PR baru
- Jangan menjalankan migrasi DB tanpa `alembic check` (atau yang setara di ORM Anda)
- Jangan gunakan `npm install -g` atau `sudo` untuk dependensi proyek
- Jangan menambahkan dependensi tanpa persetujuan (terutama yang berat: plugin webpack, ORM)

Rata-rata, templat ini terdiri atas 80–120 baris. Jika file melebihi 150 baris, itu pertanda Anda perlu merapikannya: pindahkan sebagian ke docs/, tautkan ke sesuatu, atau ringkas menjadi satu baris. Dalam praktik, file berukuran 100–150 baris bekerja paling baik; setelah titik itu, peningkatan kualitas mulai berbalik.

5 Aturan Apa yang Membuat AGENTS.md Benar-Benar Berguna?

Poin utama

AGENTS.md yang baik mengikuti lima aturan: perintah alih-alih gagasan, larangan disertai alternatif, tepat satu sumber kebenaran, kriteria penyelesaian yang dapat diverifikasi, dan file yang lebih pendek dari 150 baris.

  1. Perintah alih-alih gagasan. Agen tidak memahami “berhati-hatilah dengan migrasi.” Agen akan mengikuti alembic check sebelum alembic upgrade head. Agen bekerja dengan perintah dan kondisi, bukan suasana hati. Rumuskan semua aturan utama sebagai “lakukan X, jika tidak, lakukan Y.”

  2. Larangan disertai alternatif. Larangan tanpa penjelasan seperti “jangan force push” akan diam-diam diabaikan agen setelah dua atau tiga prompt. Pasangan “jangan lakukan X; lakukan Y sebagai gantinya” berfungsi. Contoh: “jangan gunakan git push --force pada main; jika perlu membatalkan perubahan, gunakan git revert atau buka PR baru.”

  3. Tepat satu sumber kebenaran. AGENTS.md di root adalah sumber kebenaran untuk seluruh proyek. Jika Anda memiliki monorepo, gunakan file AGENTS.md bertingkat di subfolder, dengan mengikuti aturan “yang terdekat berlaku”. Jangan ada file paralel dengan instruksi yang bertentangan.

  4. Kriteria “selesai” yang dapat diverifikasi. “Tes harus lulus” tidak berguna. Kriteria yang tepat adalah: npm test menghasilkan exit code 0 dan tidak mencetak FAIL ke stdout. “Kode harus rapi” juga tidak berguna. Kriteria yang tepat adalah: npm run lint lulus tanpa peringatan. Agen hanya memahami arti “selesai” jika Anda menjelaskan kondisinya secara eksplisit.

  5. File yang lebih pendek dari 150 baris. Setelah 150 baris, metrik mulai memburuk: agen menghabiskan lebih banyak konteks untuk membaca dan melewatkan aturan penting. Jika tidak muat, pindahkan detail ke docs/architecture.md dan tautkan dari AGENTS.md, sisakan hanya perintah dan batasan di dalam file.

10 Kesalahan Apa yang Mengubah AGENTS.md Menjadi Sampah?

Poin utama

Alasan utama AGENTS.md tidak berfungsi adalah rumusannya yang samar. Dalam studi terhadap lebih dari 2.500 repositori, GitHub Blog menunjukkan bahwa sebagian besar file gagal karena ditulis terlalu umum. Misalnya, “Anda adalah asisten coding yang membantu” sama sekali tidak memberi informasi berguna kepada agen. Berikut 10 kesalahan umum dan kemunculannya dalam file yang buruk: menduplikasi README, prosa tanpa struktur, 30+ larangan tanpa alternatif, prioritas yang bertentangan, rahasia yang ditulis langsung, dokumentasi kedaluwarsa, dan kerumitan arsitektur yang berlebihan untuk tugas sederhana.

  1. Aturan samar tanpa perintah. Agen akan mengabaikan “berhati-hatilah dengan migrasi”—kalimat itu kosong baginya. Hanya perintah spesifik dengan kondisi yang berfungsi: “Jalankan alembic check sebelum alembic upgrade head. Jika ada kesalahan, jangan terapkan migrasi; tanyakan kepada saya.”

  2. “Kode bersih.” Frasa yang tidak berguna. Ganti dengan pola spesifik: “Gunakan komponen fungsional dengan hook. Contoh: function LoginForm() { const [email, setEmail] = useState(''); ... }”

  3. Prosa tanpa struktur. Jika AGENTS.md berisi 300 baris prosa tanpa judul, agen akan menghabiskan 80K token konteks untuk bagian yang tidak relevan dan melewatkan hal penting. Gunakan judul H2/H3, bagian pendek, dan daftar berpoin.

  4. File lebih dari 150 baris. Metrik kualitas menurun setelah ambang ini. Pisahkan menjadi file utama dan tautan ke detail di docs/.

  5. 30+ larangan tanpa alternatif. Jika file berisi daftar panjang “jangan lakukan X, jangan lakukan Y” tanpa menjelaskan “lakukan Z sebagai gantinya,” agen akan bingung dan bergerak tanpa arah.

  6. Menduplikasi README.md. Jika Anda sudah menulis “cara memasang dan menjalankan” di README, jangan salin ke AGENTS.md. Sebagai gantinya, rujuk README dalam satu baris dan jelaskan di AGENTS.md hal-hal yang dibutuhkan agen tetapi tidak dibutuhkan kontributor manusia.

  7. Menulis rahasia langsung. AGENTS.md bisa bersifat publik (file ini ada di Git). Jangan memasukkan kunci API, token, atau kata sandi asli. Hanya cantumkan rujukan ke penyimpanan rahasia: “Lihat Vault: secret/staging/db.”

  8. Prioritas yang bertentangan tanpa urutan. “Bekerjalah cepat” + “pertahankan cakupan tes 90%” membuat agen tidak yakin apa yang harus dipilih. Tentukan urutannya secara eksplisit: “Cakupan tes ≥80% lebih dahulu, baru kecepatan. Jika keduanya bertentangan, utamakan tes.”

  9. Dokumentasi kedaluwarsa. Deskripsi arsitektur menyebut REST+polling, padahal kenyataannya sudah WebSockets. Agen mengikuti deskripsi lama dan merusak arsitektur. Aturannya: perbarui AGENTS.md dalam PR yang sama dengan kode setiap kali arsitektur berubah.

  10. Kerumitan arsitektur berlebihan untuk tugas sederhana. Jika seseorang meminta perubahan dua baris dalam konfigurasi, agen tidak perlu membaca seluruh topologi 14 layanan mikro. Pindahkan pembahasan arsitektur “mendalam” ke docs/architecture.md; di AGENTS.md, sisakan “jika tugasnya terkait arsitektur, baca docs/architecture.md.”

Studi GitHub Blog terhadap lebih dari 2.500 repositori AGENTS.md menyatakan kesimpulan utamanya:

“Sebagian besar file agen gagal karena terlalu umum. ‘Anda adalah asisten coding yang membantu’ tidak berhasil.”

(GitHub Blog, diterjemahkan dari bahasa Inggris)

Bagaimana Menyimpan AGENTS.md dan CLAUDE.md dalam Satu Repositori?

Poin utama

Ada tiga skenario: (1) Hanya Claude Code—pertahankan CLAUDE.md; AGENTS.md tidak diperlukan. (2) Hanya alat non-Claude (Codex, Cursor, Copilot, Junie)—gunakan AGENTS.md sebagai satu-satunya sumber kebenaran. (3) Tim campuran dengan Claude Code dan alat lain—jadikan AGENTS.md file utama. Jika tidak ada aturan khusus untuk Claude, Anda bisa tidak membuat CLAUDE.md: sejak versi 2.1.277, Claude Code membaca AGENTS.md sendiri. Jika Anda memiliki aturan terpisah, hubungkan AGENTS.md ke CLAUDE.md melalui symlink atau impor @AGENTS.md. Pada macOS dan Linux, ubah nama hanya ketika AGENTS.md belum ada. Jika kedua file sudah ada, pertahankan dan gabungkan aturannya terlebih dahulu, lalu gunakan wrapper CLAUDE.md singkat dengan @AGENTS.md; jangan menimpa AGENTS.md yang ada. Di Windows, symlink memerlukan Developer Mode, jadi lebih mudah menggunakan impor.

Pertanyaan praktis utamanya adalah bagaimana menggunakan kedua file tanpa menduplikasi isi. Ada tiga skenario:

Skenario 1: Hanya Claude Code. Pertahankan CLAUDE.md dan gunakan semua fitur Claude Code: ~/.claude/CLAUDE.md untuk instruksi tingkat pengguna, CLAUDE.md untuk proyek, CLAUDE.local.md untuk penggantian pribadi, @import untuk menyertakan file lain, dan .claude/skills/ untuk skill khusus. AGENTS.md tidak diperlukan.

Skenario 2: Beberapa klien pemrograman. Simpan aturan bersama di AGENTS.md, lalu hubungkan dan verifikasi tiap klien secara terpisah. Gemini CLI mendukung nama file konteks yang dikonfigurasi; Aider dapat memuat file melalui konfigurasi read. Keduanya merupakan jalur pemuatan eksplisit, bukan penemuan otomatis yang identik.

Jalur pemuatanYang perlu diverifikasi
Penemuan AGENTS.md otomatisAturan root, file bertingkat, dan prioritas yang didokumentasikan untuk klien terpasang
Konfigurasi eksplisit, seperti Gemini CLI atau AiderNama file/jalur read yang dikonfigurasi serta tampilan konteks yang dimuat klien
Pemuatan bersyarat atau impor Claude CodeVersi terpasang dan file yang diutamakan; lihat panduan AGENTS.md khusus Claude Code

Mulai sesi baru dalam repositori uji yang aman, tambahkan instruksi unik yang tidak berbahaya seperti “sertakan penanda instructions-loaded dalam jawaban uji”, lalu periksa tampilan file yang dimuat atau log sesuai dokumentasi klien beserta jawabannya. Ulangi untuk setiap klien/versi yang benar-benar digunakan. Pernyataan model bahwa file telah dibaca bukan bukti independen pemuatan; satu pemeriksaan berhasil tidak membuktikan dukungan pada semua alat lain.

Skenario 3: Tim campuran (Claude Code + alat lain). Ini adalah penyiapan paling umum pada 2026. Solusinya adalah menjadikan AGENTS.md file utama. Jika tidak ada aturan khusus Claude Code, jangan buat CLAUDE.md sama sekali: sejak versi 2.1.277, Claude Code membaca AGENTS.md jika proyek tidak memiliki CLAUDE.md. Jika ada aturan semacam itu, jadikan CLAUDE.md symlink atau pembungkus singkat dengan impor @AGENTS.md.

Sebelum mengubah salah satu file, periksa dan cadangkan keduanya. Jika sama-sama ada, gabungkan instruksi bersama yang tidak bertentangan ke AGENTS.md dan pertahankan instruksi khusus Claude dalam CLAUDE.md dengan impor @AGENTS.md. Pertahankan symlink yang ada alih-alih menggantinya.

Untuk CLAUDE.md biasa hanya ketika AGENTS.md belum ada, guard shell macOS/Linux ini menolak menimpa target atau symlink yang sudah ada:

if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
  printf '%s\n' 'STOP: AGENTS.md exists; merge both files first.' >&2
elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
  mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
else
  printf '%s\n' 'STOP: inspect the existing CLAUDE.md path first.' >&2
fi

Setelah penggantian nama berhasil, CLAUDE.md merupakan symlink ke AGENTS.md. Semua agen yang membaca AGENTS.md melihat isi yang sama. Claude Code, yang membaca CLAUDE.md, melihat isi yang sama melalui symlink.

Di Windows, membuat symlink memerlukan Developer Mode (atau Admin), yang mungkin merepotkan seluruh tim. Alternatifnya adalah membuat CLAUDE.md singkat yang mengimpor AGENTS.md:

# CLAUDE.md

@AGENTS.md

## Khusus Claude Code

- Gunakan .claude/skills/ untuk prompt khusus
- Saat bekerja dengan Skills, lihat .claude/skills/INDEX.md
- Gunakan Plan Mode sebelum perubahan besar (Shift+Tab)

Di Claude Code, sintaks ini memuat AGENTS.md dengan satu baris dan menambahkan aturan khusus Claude Code di bawahnya. Jika nanti ingin menghapus AGENTS.md, cukup hapus impornya. Baris ini tidak menyebabkan pembacaan ganda: menurut dokumentasi Claude Code, file AGENTS.md yang sama tidak dimuat dua kali, sekalipun Claude Code dapat membacanya sendiri.

Tata letak kanonis untuk tim multi-alat pada 2026:

repo-root/
├── AGENTS.md                              # sumber kebenaran, ≤150 baris
├── CLAUDE.md                              # hanya jika ada aturan khusus Claude: symlink → AGENTS.md ATAU @AGENTS.md + aturan tambahan
├── .cursor/rules/                         # penggantian khusus untuk Cursor
├── .github/copilot-instructions.md        # “Lihat AGENTS.md,” jika digunakan
└── docs/architecture.md                   # arsitektur mendalam yang dirujuk AGENTS.md

Informasi selengkapnya tentang CLAUDE.md ada di panduan “Cara Mengonfigurasi CLAUDE.md dengan Benar”. Untuk konteks lebih lanjut tentang alasan agen membutuhkan file instruksi yang panjang, baca “Apa Itu Context Engineering”.

Apa yang Berubah pada 2026: Mengapa AAIF Membawa AGENTS.md ke Linux Foundation?

Poin utama

Pada 9 Desember 2025, Linux Foundation membentuk Agentic AI Foundation (AAIF) dengan tiga proyek pendiri: AGENTS.md dari OpenAI, MCP dari Anthropic, dan goose dari Block. Anggota pendirinya adalah AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft, dan OpenAI. Pada 24 Februari 2026, yayasan ini mencakup 146 organisasi. Ini berarti AGENTS.md berhenti menjadi “sesuatu dari OpenAI” dan menjadi standar industri bersama MCP. Secara praktis, jika Anda membangun produk yang harus bekerja dengan agen dari berbagai vendor, memiliki AGENTS.md di root adalah praktik dasar. Tanpanya, Anda akan mengelola tiga atau empat file paralel yang akan berbeda dalam waktu sebulan.

Kisah politik utama Mei 2026 dalam coding AI bukanlah perilisan model lain, melainkan konsolidasi format. Sebelumnya, setiap vendor memiliki file aturannya sendiri, yang memudahkan vendor tetapi menyulitkan tim yang bekerja dengan beberapa alat.

Dalam siaran pers tertanggal 9 Desember 2025, Linux Foundation mengumumkan Agentic AI Foundation sebagai payung bagi tiga format:

  • AGENTS.md dari OpenAI — format file instruksi untuk agen
  • Model Context Protocol (MCP) dari Anthropic — protokol untuk menghubungkan alat eksternal ke agen
  • goose dari Block — kerangka kerja agen open source

Dari siaran pers Linux Foundation:

“Menyatukan proyek-proyek ini di bawah payung AAIF memastikan proyek-proyek tersebut dapat berkembang dengan transparansi dan stabilitas yang hanya dapat disediakan oleh tata kelola terbuka.”

(siaran pers Linux Foundation, 9 Desember 2025, diterjemahkan dari bahasa Inggris)

Pada 24 Februari 2026, 146 organisasi tergabung dalam AAIF (97 anggota baru dalam dua bulan). Anggota Gold baru mencakup Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express, dan Autodesk. Anthropic berada di tingkat Platinum, mendorong MCP. OpenAI berada di tingkat Platinum, mendorong AGENTS.md. Block berada di tingkat Platinum dengan goose.

Ini mengubah posisi AGENTS.md: dari “format OpenAI” menjadi standar industri. Pada musim semi 2026, Claude Code masih berada di pinggir, tetapi pada September, dengan versi 2.1.277, Claude Code belajar membaca AGENTS.md sendiri. CLAUDE.md tidak hilang, dan secara default tetap diutamakan jika ada di proyek.

Titik awal praktis adalah aturan proyek bersama dalam AGENTS.md, ditambah impor, wrapper, atau konfigurasi pembacaan eksplisit yang diperlukan tiap klien. Untuk Claude Code, periksa versi terpasang serta prioritas file instruksi sebelum menentukan kebutuhan impor CLAUDE.md atau symlink. Verifikasi pemuatan pada setiap klien; tidak ada persentase cakupan yang ditetapkan di sini.

Selanjutnya

AGENTS.md adalah unsur pertama dalam “cara mencapai kesepakatan dengan agen agar ia bekerja secara konsisten.” Berikutnya adalah unsur kedua—folder pengetahuan proyek, yang berisi konteks bisnis, audiens, produk, dan harga. Unsur ketiga adalah context engineering, yang menyatukan semuanya: file apa yang dilihat agen pada setiap langkah, bagaimana status dipertahankan antar sesi, dan cara beralih di antara berbagai model.

Materi praktis: dokumentasi Ailoot.

Materi dan alat lainnya: Ailoot.

Rincian selengkapnya

Pertanyaan tentang Apa Itu AGENTS.md dan Cara Menulis Sendiri dalam 30 Menit | Ailoot

Bagaimana jika AGENTS.md dan CLAUDE.md sudah sama-sama ada?

Cadangkan dan bandingkan kedua file sebelum mengubahnya. Gabungkan aturan bersama ke AGENTS.md, pertahankan aturan khusus Claude dalam CLAUDE.md, dan tambahkan impor @AGENTS.md; jangan mengganti nama satu file dengan menimpa yang lain.

Bagaimana membuat instruksi dapat diverifikasi?

Tulis perintah pengaturan dan pengujian yang tepat, tetapkan hasil yang diharapkan, dan nyatakan hal yang tidak boleh diubah agen. Pindahkan arsitektur terperinci ke dokumen tertaut agar instruksi utama tetap mudah dipindai.

Semua artikel