Agen pengodean membaca repositori Anda sebelum mereka menulis kode, dan berkas yang pertama kali mereka baca adalah AGENTS.md. Ini adalah konvensi terbuka yang disepakati oleh Codex CLI, Cursor, Aider, OpenHands, dan daftar alat lain yang terus bertambah sehingga satu berkas konteks dapat berfungsi di setiap agen. Untuk tim pengembangan API, berkas tersebut adalah perbedaan antara agen yang menjalankan pengujian yang benar terhadap server lokal sungguhan dan agen yang mengada-ada titik akhir serta mengirimkan klien yang rusak.
Panduan ini mencakup apa itu AGENTS.md, mengapa tim API harus memperlakukannya sebagai kode produksi, bagian-bagian yang penting untuk repositori yang mengutamakan OpenAPI, contoh konkret, dan cara menjaganya tetap mutakhir seiring perkembangan API. Kami menyandingkannya dengan Apidog pada akhirnya agar alur pengujian kontrak agen tetap berlandaskan pada spesifikasi yang nyata.
TL;DR
AGENTS.mdadalah berkas Markdown biasa di root repositori yang memberi tahu agen pengodean cara menavigasi, membangun, menguji, dan mengirimkan kode dalam proyek Anda.- Konvensi ini bersifat terbuka dan didukung di seluruh Codex CLI, Cursor, OpenHands, Aider, Claude Code, dan peralatan agen lainnya.
- Untuk tim API, bagian-bagian yang paling memberikan manfaat adalah perintah build, jalur spesifikasi OpenAPI, titik akhir server mock, perintah uji kontrak, pengaturan otentikasi, dan zona "jangan sentuh".
- Jaga agar tetap singkat. 200 hingga 400 baris sudah cukup. Jika lebih panjang, agen akan melewatkan bagian-bagian penting.
- Sandingkan dengan koleksi Apidog sehingga agen memiliki konteks (
AGENTS.md) dan kontrak yang dapat dijalankan (spesifikasi OpenAPI).
Apa Sebenarnya AGENTS.md Itu
AGENTS.md adalah berkas Markdown yang Anda commit di root repositori. Agen pengodean mencarinya pada kontak pertama dengan basis kode dan memperlakukan isinya sebagai briefing otoritatif tentang cara kerja proyek. Konvensi ini dimulai di dalam Codex CLI milik OpenAI dan diterbitkan sebagai standar terbuka agar alat lain dapat membaca berkas yang sama. Hingga tahun ini, Codex CLI, Cursor, Aider, Claude Code, OpenHands, Sourcegraph Cody, dan beberapa agen yang lebih kecil semuanya membacanya.
Tiga hal yang membuatnya berguna:
- Satu berkas, setiap agen. Anda menulis konteksnya sekali dan setiap agen dalam perangkat tim mengambilnya. Tidak ada penyimpangan konfigurasi per alat.
- Markdown biasa. Tanpa DSL, tanpa skema, tanpa langkah build. Engineer mengeditnya seperti dokumen lainnya.
- Berada di samping kode yang dijelaskannya. Ketika skrip build berubah, berkas tersebut berubah dalam PR yang sama. Perbedaan tersebut membuat perubahan terlihat oleh peninjau dan agen.
Sepupu terdekatnya adalah CLAUDE.md, yang dibaca oleh Claude Code dari Anthropic. Kedua format ini sangat tumpang tindih; banyak proyek menyimpan AGENTS.md yang di-symlink ke CLAUDE.md sehingga kedua alat berfungsi tanpa konfigurasi tambahan. Tim Codex dan Anthropic telah secara publik menyelaraskan untuk menjaga format tetap kompatibel di masa mendatang.
Mengapa Tim Pengembangan API Sangat Membutuhkannya
Tim API berada di persimpangan yang canggung: kode kecil, kontrak besar, dan konsekuensi dari kesalahan salah satunya terlihat oleh setiap klien hilir. Agen yang tidak mengetahui bahwa spesifikasi berada di openapi.yaml akan menulis ulang jenis dari bentuk respons yang diingatnya dari data pelatihan. Agen yang tidak mengetahui perintah uji kontrak akan melakukan commit kode yang mengompilasi tetapi merusak pipeline SDK klien.
Berkas AGENTS.md yang ditulis dengan baik untuk repositori API melakukan empat hal:
- Menetapkan spesifikasi sebagai sumber kebenaran. Setiap perubahan dimulai dan diakhiri dengan skema OpenAPI atau GraphQL. Agen belajar untuk memperbarui spesifikasi terlebih dahulu, kemudian meregenerasi jenis.
- Menamai server lokal. Agen yang mem-boot server mock lokal atau server langsung memilih URL yang tepat untuk pengujian, bukan cuplikan Stack Overflow.
- Mencantumkan perintah uji berdasarkan tujuan. "Jalankan pengujian unit" tidak sama dengan "jalankan pengujian kontrak" atau "jalankan pengujian integrasi terhadap lingkungan staging."
- Menunjukkan jalur terlarang. Kode SDK yang dihasilkan, wrapper klien pihak ketiga, dan berkas migrasi seringkali terlihat dapat diedit tetapi sebenarnya tidak.
Ketika berkas melakukan keempat hal ini, output agen berhenti terlihat seperti pengembang junior yang melewatkan README dan mulai terlihat seperti rekan setim.
Struktur yang Berfungsi untuk Repositori API
AGENTS.md tidak memiliki skema yang diwajibkan. Komunitas telah menyepakati beberapa bagian yang muncul di hampir setiap berkas yang disetel dengan baik. Untuk tim API, urutan di bawah ini adalah standar awal yang kuat.
1. Ringkasan Proyek (3-5 baris)
Nyatakan apa yang dilakukan API, siapa konsumennya, serta bahasa dan kerangka kerja apa yang digunakan server. Jaga agar tetap faktual.
# Project: Payments API
Layanan pembayaran internal untuk lini produk Acme. Pelanggan adalah
backend mobile, web, dan mitra. Server adalah Go 1.23 di Echo, Postgres
17 untuk penyimpanan, dan lapisan idempoten berbasis Redis.
Blok ini memberi tahu agen bahasa mana yang harus menjadi default, idiom mana yang harus diikuti, dan klien mana yang akan rusak jika Anda mengirimkan bentuk respons yang salah.
2. Perintah Mulai Cepat
Lima hingga sepuluh perintah yang akan terus-menerus dijalankan oleh agen. Selalu sertakan perintahnya, jangan pernah menautkan ke wiki.
## Perintah
| Tujuan | Perintah |
|--------|---------|
| Instal dependensi | \`make deps\` |
| Jalankan server lokal | \`make dev\` (mengikat 127.0.0.1:8080) |
| Jalankan uji unit | \`make test\` |
| Jalankan uji kontrak terhadap mock lokal | \`make contract\` |
| Lint | \`make lint\` |
| Regenerasi klien dari spesifikasi | \`make codegen\` |
| Terapkan migrasi | \`make migrate\` |
Jika suatu perintah memerlukan variabel lingkungan (env var) agar berfungsi, letakkan nama variabel lingkungan tersebut di sampingnya. Agen pandai mengekspor variabel; mereka buruk dalam menebak.
3. Bagian Spesifikasi OpenAPI / GraphQL
Ini adalah bagian paling berharga dalam repositori API. Beri tahu agen di mana spesifikasi berada, bagaimana spesifikasi berhubungan dengan kode yang dihasilkan, dan arah aliran pengeditan.
## Sumber kebenaran
- Spesifikasi ada di \`apis/payments/openapi.yaml\`.
- Klien yang dihasilkan berada di \`gen/clients/{go,ts,python}\` dan TIDAK BOLEH diedit secara manual.
- Pipeline generasi adalah \`make codegen\`. Jalankan setelah setiap perubahan spesifikasi
dan commit klien yang diregenerasi dalam PR yang sama.
- Alur perubahan spesifikasi: spesifikasi -> \`make codegen\` -> pembaruan handler server ->
pengujian kontrak -> rilis.
Blok ini sendiri menghilangkan kelas bug di mana agen mengedit klien yang dihasilkan untuk "memperbaiki" ketidakcocokan tipe, eksekusi codegen berikutnya menghapus perubahan tersebut, dan build secara misterius rusak dua hari kemudian.
4. Pengkabelan Server Mock dan Apidog
Jika Anda menjalankan server mock (dan seharusnya demikian), beri nama mereka. Cantumkan URL, spesifikasi yang mereka baca, dan cara memulainya.
## Server lokal
- Server nyata: \`make dev\` -> \`http://127.0.0.1:8080\`
- Server mock Apidog: \`make mock\` -> \`http://127.0.0.1:4010\`
- Mock membaca dari \`openapi.yaml\` yang sama dan memutar ulang contoh yang disimpan
dari koleksi Apidog di \`apis/payments/apidog/\`.
Di sinilah Apidog mendapatkan tempatnya di berkas ini. Server mock, spesifikasi, dan contoh permintaan yang disimpan membentuk kontrak yang dapat dijalankan agen tanpa membebani panggilan pada backend nyata. Pasangkan dengan panduan pengujian API tanpa Postman untuk alur kerja yang mendasarinya.
5. Autentikasi dan Rahasia
Beri tahu agen bagaimana API melakukan autentikasi dan variabel lingkungan (env var) mana yang menyimpan apa. Jangan pernah memasukkan rahasia nyata ke dalam berkas.
## Autentikasi
- Produksi menggunakan kredensial klien OAuth 2 yang dikeluarkan oleh Auth0.
- Pengembangan lokal menggunakan token dev statis; ekspor \`DEV_TOKEN\` dari \`.env.local\`.
- Koleksi Apidog menggunakan nama env var yang sama sehingga mock dan
klien nyata berperilaku identik.
- Token TIDAK BOLEH di-commit; \`.env.local\` ada di \`.gitignore\`.
6. Strategi Pengujian
Urutkan lapisan pengujian. Agen akan menjalankannya sesuai urutan yang Anda cantumkan.
## Pengujian
1. \`make test\` untuk uji unit. Cepat, dijalankan setiap ada perubahan.
2. \`make contract\` untuk uji kontrak OpenAPI terhadap mock. Jalankan sebelum
perubahan spesifikasi apa pun digabungkan.
3. \`make integration\` untuk uji end-to-end terhadap server lokal dengan
Postgres nyata. Jalankan sebelum menggabungkan ke main.
4. Staging soak berjalan setiap malam melalui GitHub Actions; bukan perintah lokal.
7. Daftar Jangan Sentuh
Kode yang dihasilkan, dependensi pihak ketiga (vendored dependencies), dan migrasi hampir selalu masuk di sini.
## Jangan edit secara manual
- \`gen/**\` (diregenerasi oleh \`make codegen\`)
- \`vendor/**\` (dikelola oleh \`go mod vendor\`)
- \`migrations/*.up.sql\` melewati migrasi pertama yang belum diterapkan
- Nama field skema \`apis/payments/openapi.yaml\` tanpa persetujuan pemilik
8. Gaya Rumah (House Style)
Tiga hingga lima aturan. Lebih dari itu dan agen akan memilih yang salah.
## Konvensi
- Error mengembalikan JSON masalah RFC 7807; jangan pernah string kosong.
- Gunakan snake_case di JSON, camelCase di Go, PascalCase di klien TS.
Codegen menangani pemetaan.
- Kunci idempoten diperlukan di semua titik akhir POST yang membuat sumber daya.
- Titik akhir baru memerlukan pengujian kontrak yang melatih jalur 200 dan 4xx.
Contoh Konkret: Berkas 90 Baris yang Melakukan Tugasnya
Godaan untuk menulis 800 baris. Lawanlah. Berkas di bawah ini mencakup layanan API nyata dalam 90 baris Markdown dan cukup bagi agen utama mana pun untuk bekerja secara produktif.
# Proyek: Payments API
Layanan pembayaran internal untuk lini produk Acme. Go 1.23, Echo,
Postgres 17, Redis untuk idempoten. Konsumen adalah mobile, web,
dan backend mitra.
## Perintah
| Tujuan | Perintah |
|--------|---------|
| Instal | \`make deps\` |
| Jalankan server | \`make dev\` |
| Uji unit | \`make test\` |
| Uji kontrak | \`make contract\` |
| Lint | \`make lint\` |
| Regen klien | \`make codegen\` |
| Migrasi DB | \`make migrate\` |
## Sumber kebenaran
- Spesifikasi: \`apis/payments/openapi.yaml\`
- Klien yang dihasilkan: \`gen/clients/{go,ts,python}\` (jangan edit)
- Alur edit: spesifikasi -> \`make codegen\` -> handler -> uji kontrak -> rilis
## Server lokal
- Server nyata: \`make dev\` (\`http://127.0.0.1:8080\`)
- Mock Apidog: \`make mock\` (\`http://127.0.0.1:4010\`)
- Koleksi Apidog: \`apis/payments/apidog/\`
## Autentikasi
- Produksi: Kredensial klien Auth0 OAuth 2.
- Dev lokal: \`DEV_TOKEN\` statis dari \`.env.local\`.
## Urutan pengujian
1. \`make test\`
2. \`make contract\`
3. \`make integration\`
## Jangan edit secara manual
- \`gen/**\`, \`vendor/**\`
- Migrasi yang diterapkan di \`migrations/\`
- Nama field spesifikasi tanpa persetujuan pemilik
## Konvensi
- JSON masalah RFC 7807 untuk error
- JSON snake_case, codegen menangani pemetaan bahasa
- Kunci idempoten diperlukan pada POST creates
- Setiap endpoint baru dirilis dengan pengujian kontrak
Itu sudah cukup. Tambahkan bagian hanya ketika agen membuat pilihan yang salah dua kali.
Menjaga Berkas Tetap Mutakhir
AGENTS.md yang basi lebih buruk daripada tidak ada berkas sama sekali. Agen akan mempercayainya dan mengirimkan kode berdasarkan perintah build yang tidak lagi berfungsi.
Tiga kebiasaan yang menjaganya tetap mutakhir:
- Perlakukan sebagai kode produksi. Perubahan melalui tinjauan yang sama dengan PR lainnya. Peninjau memeriksa bahwa daftar perintah cocok dengan
Makefileyang sebenarnya. - Integrasikan ke CI. Skrip singkat yang menguraikan tabel perintah dan menjalankan setiap perintah pada checkout baru akan dengan cepat mendeteksi penyimpangan. Sebagian besar tim menulis ini dalam 30 baris Bash.
- Perbarui dalam PR yang sama. Ketika Anda menambahkan perintah pengujian baru, jangan berjanji untuk memperbarui
AGENTS.mdnanti. Perbarui sekarang. Biayanya dua menit; biaya melewatkannya adalah dua minggu kebingungan agen.
Apidog sebagai Kontrak Runtime untuk AGENTS.md Anda
AGENTS.md memberikan konteks kepada agen. Spesifikasi OpenAPI memberikannya kontrak. Apidog menjembatani keduanya: ia membaca spesifikasi, menjalankan mock lokal di URL yang tercantum dalam AGENTS.md, memutar ulang contoh permintaan yang disimpan untuk pengujian, dan memungkinkan agen melihat respons nyata tanpa menghabiskan kredit pada backend langsung.
Pola yang berfungsi:
- Commit
apis/<service>/openapi.yamldanapis/<service>/apidog/(koleksi yang diekspor). - Cantumkan URL mock dan perintah
make mockdiAGENTS.md. - Agen menjalankan
make contractuntuk pengujian cepat terhadap contoh yang disimpan. - Ketika spesifikasi berubah, agen meregenerasi klien, menjalankan rangkaian kontrak, dan baru kemudian menyentuh server langsung.
Untuk panduan yang lebih mendalam tentang alur kerja mock Apidog dengan API nyata, panduan DeepSeek V4 API mencakup pola yang sama yang diterapkan pada API model alih-alih API layanan.
Kesalahan Umum yang Dilakukan Tim API
Setelah meninjau lusinan berkas ini, lima masalah yang sama muncul:
- Menautkan alih-alih mencantumkan. "Lihat wiki untuk perintah build." Agen tidak menjelajahi wiki. Masukkan perintahnya langsung.
- Prosa berbau pemasaran. "Platform API kelas dunia kami memberdayakan..." Agen tidak memerlukan promosi. Nyatakan fakta.
- Perintah yang sudah usang. Perintah yang rusak di bulan Maret masih ada di berkas di bulan April. Integrasikan CI untuk menangkap ini.
- Melewatkan bagian spesifikasi. Blok paling berguna. Selalu sertakan.
- Tidak ada daftar jangan sentuh. Agen mengedit kode yang dihasilkan. Eksekusi codegen berikutnya menghapus pengeditan. Build rusak. Berulang.
Jika Anda ingin dasar untuk memulai, salin contoh di atas ke repositori Anda, edit ringkasan proyek, dan sesuaikan tabel perintah. Anda dapat mengirimkan berkas yang dapat digunakan dalam 20 menit.
FAQ
Apakah AGENTS.md sama dengan CLAUDE.md?Formatnya kompatibel. Sebagian besar tim menyimpan salah satunya sebagai sumber kebenaran dan membuat symlink yang lain. Anthropic dan OpenAI secara publik menyelaraskan untuk menjaga konvensi tetap dapat dioperasikan.
Di mana saya harus meletakkan berkas?Selalu di root repositori. Beberapa agen juga membaca berkas AGENTS.md bersarang di dalam subdirektori, berguna untuk monorepo. Mulai dengan satu berkas tingkat root dan tambahkan berkas subdirektori hanya jika satu berkas root menjadi terlalu panjang.
Berapa panjang seharusnya?200 hingga 400 baris adalah titik terbaik. Lebih dari itu, agen mulai melewatkan bagian. Jika Anda membutuhkan kedalaman lebih, tautkan ke dokumen terpisah dengan ringkasan satu baris secara inline.
Haruskah saya menyertakan contoh kode?Yang singkat, ya. Yang panjang, tidak. Simpan contoh lengkap untuk pengujian; agen juga membaca pengujian. Panduan Codex gratis GPT-5.5 mencakup bagaimana Codex secara khusus menggunakan contoh pengujian sebagai sinyal tambahan.
Apakah agen membaca ulang berkas di setiap giliran?Sebagian besar agen membacanya saat sesi dimulai dan menyimpannya di cache. Beberapa membaca ulang setelah perubahan berkas besar. Jika Anda melakukan pengeditan besar, memulai ulang sesi agen adalah langkah teraman.
Bagaimana cara menguji bahwa berkas saya berfungsi?Jalankan sesi agen baru tanpa konteks lain, berikan tugas kecil ("tambahkan respons 422 ke POST /payments"), dan amati apa yang dilakukannya. Jika ia membaca spesifikasi, menjalankan make codegen, dan menulis pengujian kontrak, berarti berkas tersebut berfungsi dengan baik.