AGENTS.md dan HUMAN.md: Panduan untuk Coding Agent

Apa itu AGENTS.md

AGENTS.md adalah file markdown biasa di root repositori yang menjelaskan kepada coding agent cara mengerjakan proyek tersebut. Situs resminya menjelaskan bahwa file ini adalah "README untuk agent: tempat khusus dan terprediksi untuk menyediakan konteks dan instruksi agar coding agent AI dapat mengerjakan proyek Anda." Format ini dikelola oleh Agentic AI Foundation di bawah Linux Foundation. Lebih dari dua puluh agent membacanya, termasuk Codex, Cursor, Jules, Devin, dan GitHub Copilot (per Juli 2026).

Konvensi ini ada karena alasan praktis. Anggota baru dalam tim membaca README, menebak perintah build, lalu bertanya kepada seseorang jika tebakannya salah. Agent tidak dapat bertanya. Agent menebak, menjalankan npm test pada proyek yang menggunakan pnpm test, membaca kegagalannya, lalu mencoba cara lain. Anda membayar setiap token tersebut. Menuliskan perintah yang benar satu kali akan menghilangkan seluruh kelas kegagalan itu.

Tidak ada field yang diwajibkan. Situs tersebut menjelaskannya secara eksplisit: "AGENTS.md hanyalah Markdown standar. Gunakan heading apa pun yang Anda inginkan; agent cukup mengurai teks yang Anda berikan." Itulah seluruh spesifikasinya. Nilainya bukan pada formatnya. Nilainya terletak pada file yang berada di path yang selalu diperiksa oleh setiap tool.

Lokasi file dan file yang berlaku

Tempatkan file pertama di root repositori. Dalam monorepo, Anda dapat menambahkan file lain di setiap subproyek. Aturannya sederhana: "agents secara otomatis membaca file terdekat dalam hierarki direktori, sehingga file yang paling dekat memiliki prioritas." Jika dua file bertentangan, file yang sedang diedit yang berlaku. Apa pun yang Anda ketikkan dalam chat akan mengesampingkan keduanya.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

Penggunaan hierarki bertingkat ini bermanfaat karena hanya dengan cara itu Anda dapat menyatakan sesuatu yang benar di satu folder, tetapi salah di folder berikutnya. Aturan seperti "setiap endpoint memvalidasi inputnya" sebaiknya ditempatkan di dekat endpoint. Jika ditempatkan dalam file root, aturan tersebut akan dimuat pada setiap tugas yang tidak terkait dan tidak memberikan manfaat.

Hal yang Perlu Dicantumkan dalam AGENTS.md

Tuliskan hal-hal yang tidak dapat diketahui agen hanya dengan membaca kode. Cantumkan perintah build, test, dan lint yang tepat terlebih dahulu, dalam format yang dapat langsung ditempelkan ke terminal. Tambahkan perintah untuk menjalankan satu test, karena agen yang hanya tahu cara menjalankan seluruh rangkaian test akan menjalankan seluruh rangkaian tersebut sebanyak empat puluh kali. Sebutkan konvensi yang berbeda dari default alat, karena agen sudah mengetahui default dan hanya perlu mengetahui penyimpangan Anda. Tambahkan format pesan commit dan aturan pull request jika tersedia.

Berikan informasi yang cukup konkret agar setiap pernyataan dapat diperiksa. “Gunakan indentasi 2 spasi” merupakan instruksi yang dapat digunakan karena dapat ditentukan apakah aturan tersebut dipatuhi atau tidak. “Format kode dengan benar” tidak dapat digunakan karena tidak ada bagian yang dapat diverifikasi. Hal yang sama berlaku untuk lokasi: “Handler API berada di src/api/handlers/” lebih baik daripada “susun file dengan rapi”.

Aturan negatif juga layak dicantumkan. “Jangan pernah mengedit file di bawah dist/ karena file tersebut dibuat oleh npm run build” mencegah satu kesalahan tertentu. Karena penyebabnya disebutkan, agen dapat mengetahui kasus serupa yang tidak Anda tuliskan.

Hal yang tidak boleh dimasukkan

Jangan pernah menyimpan rahasia dalam salah satu file ini. File tersebut di-commit ke git, dimuat ke dalam konteks pada awal setiap sesi, dan dikirim ke penyedia model pada setiap permintaan. API key dalam AGENTS.md akan tersimpan dalam riwayat repositori dan log pihak ketiga. Arahkan ke lokasi rahasia tersebut, bukan menyalinnya: "kata sandi database ada di .env, yang diabaikan oleh git; minta izin sebelum membacanya." Praktik yang lebih luas dibahas dalam menjauhkan kredensial dari jangkauan agen.

Jangan masukkan hal yang dapat diketahui agen melalui pemeriksaan. Daftar direktori yang ditempelkan, salinan daftar dependensi, atau ikhtisar arsitektur yang hanya mengulang nama folder akan menjadi usang seminggu setelah ditulis. Semua itu juga menghabiskan konteks pada setiap sesi selama masih ada. Pertahankan jebakan dan alasannya. Hapus inventaris.

CLAUDE.md adalah penerapan Claude Code untuk konsep yang sama

Claude Code membaca CLAUDE.md dan tidak membaca AGENTS.md secara otomatis. File proyek berada di ./CLAUDE.md atau ./.claude/CLAUDE.md, preferensi pribadi untuk setiap proyek disimpan di ~/.claude/CLAUDE.md, dan organisasi dapat menempatkan file yang berlaku di seluruh mesin pada /etc/claude-code/CLAUDE.md di Linux. File yang ditemukan digabungkan mulai dari root sistem berkas hingga direktori kerja Anda. Karena itu, file yang paling dekat dengan lokasi peluncuran sesi dibaca terakhir.

Jika repositori Anda sudah memiliki AGENTS.md, jangan memelihara salinan kedua. Impor file tersebut, lalu tambahkan hanya hal-hal khusus untuk Claude:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Symlink dapat digunakan jika tidak ada tambahan yang perlu ditambahkan:

ln -s AGENTS.md CLAUDE.md

Perintah tersebut tidak mencetak apa pun jika berhasil. Pada sesi berikutnya, jalankan /context dan pastikan CLAUDE.md muncul di bawah File memori. Jika tidak ada dalam daftar tersebut, berarti file tidak pernah dimuat dan isinya tidak diterapkan. Untuk membuat draf awal tanpa menulisnya secara manual, jalankan /init: perintah ini membaca codebase dan menghasilkan file awal. Jika CLAUDE.md sudah ada, perintah ini menyarankan perbaikan, bukan menimpanya.

Pertahankan setiap file di bawah sekitar 200 baris. File yang lebih panjang menggunakan lebih banyak ruang konteks, sehingga kepatuhan menurun. Jika Anda ingin melihat hal lain yang bersaing untuk ruang tersebut, apa yang sebenarnya mengisi jendela konteks agen menguraikannya.

Satu hal perlu ditekankan. AGENTS.md berisi panduan, bukan sistem izin. Isinya diterima sebagai konteks biasa, sehingga model membacanya dan biasanya mematuhinya. Namun, tidak ada mekanisme yang memblokir tindakan yang bertentangan dengan panduan tersebut. Untuk aturan yang harus selalu berlaku, seperti "jangan pernah melakukan push ke main", gunakan hook atau pengaturan izin. Keduanya dijalankan sebagai kode dan tidak bergantung pada keputusan model untuk mematuhinya.

Alat yang menulis file ini untuk Anda

Dua proyek dalam daftar GitHub trending pada 30 July 2026 menunjukkan arah perkembangan konvensi ini.

agent0ai/dox (1,368 stars per July 2026) adalah framework untuk menjaga agar hierarki file AGENTS.md tetap mutakhir. Framework ini tidak menyediakan package atau runtime. Anda menyalin isi AGENTS.md miliknya ke AGENTS.md root Anda sendiri, dan itulah proses instalasinya. Untuk proyek yang sudah ada, beri tahu agent Anda:

Initialize DOX tree for this project now.

Agent tersebut kemudian membuat file AGENTS.md turunan beserta indeksnya, menelusuri hierarki itu sebelum mengedit apa pun, dan memperbarui dokumentasi yang terdampak setelah perubahan diterapkan. Gagasan dasarnya adalah dokumentasi yang dipelihara agent sebagai bagian dari pekerjaannya tetap akurat, sedangkan dokumentasi yang diperbarui seseorang secara manual tidak.

HUMAN.md, trik yang sama yang diarahkan kepada Anda

Intuition-Lab/personal-model (1,260 bintang per Juli 2026) menerapkan pola ini pada seseorang, bukan repositori. Proyek ini menganggap HUMAN.md sebagai keluaran sistem, bukan file yang Anda ketik: "model hidup tentang hal yang penting saat ini, cara Anda biasanya mengambil keputusan, dan arah perhatian Anda." Proyek ini berjalan secara lokal di macOS 13 atau versi lebih baru, merekam aktivitas setelah Anda memberikan izin macOS, dan menyediakan hasilnya untuk agen melalui MCP (model context protocol). Langkah instalasi singkatnya:

uv tool install personal-model
persome onboard
persome model open --after 30

Anda tidak memerlukan semua itu untuk memperoleh sebagian besar manfaatnya. HUMAN.md yang ditulis sendiri biasanya terdiri dari sekitar dua puluh baris: peran Anda, zona waktu Anda, stack yang benar-benar Anda gunakan, keputusan yang sudah Anda ambil dan tidak ingin dibahas ulang, serta seberapa banyak penjelasan yang ingin Anda terima. File ini mengurangi penjelasan berulang yang sama seperti yang dilakukan file proyek, tetapi pada tingkat yang lebih tinggi.

Satu hal yang perlu diperhatikan. HUMAN.md adalah profil seseorang, sehingga secara bawaan bersifat sensitif. Jangan menyimpannya di repositori publik. Simpan di ~/.claude/CLAUDE.md, atau di CLAUDE.local.md yang diabaikan git pada root proyek. File tersebut dimuat bersama file yang di-commit dan diperlakukan dengan cara yang sama.

Templat awal yang dapat Anda salin

Templat ini sengaja dibuat singkat. Hapus bagian yang tidak berlaku, dan jangan menambahkan bagian yang tidak dapat Anda perbarui secara rutin.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

Tulis file ini, lalu perbaiki langsung di tempat. Tambahkan baris jika Anda mengetikkan koreksi yang sama di chat dua kali. Satu aturan ini membuat file tetap berguna dan mencegahnya berkembang menjadi dokumen yang tidak dibaca siapa pun, termasuk mesin. Setelah stabil, file ini ikut tersimpan bersama repository. Hal ini terutama penting ketika agent berjalan di tempat selain laptop Anda: menjalankan coding agent di server Anda sendiri membahas penyiapan tersebut.

FAQ

Apakah AGENTS.md sama dengan file CLAUDE.md?

Keduanya merupakan gagasan yang sama dengan dua nama file. Claude Code membaca CLAUDE.md dan mengabaikan AGENTS.md kecuali Anda menghubungkan keduanya. Jadikan satu file sebagai sumber kebenaran dan tautkan file lainnya ke file tersebut, baik dengan baris @AGENTS.md di bagian atas CLAUDE.md maupun dengan ln -s AGENTS.md CLAUDE.md. Dua salinan lengkap yang dikelola secara terpisah akan berbeda dalam waktu satu bulan.

Apakah penulisan AGENTS.md menjamin agent mematuhinya?

Tidak. Isinya diberikan sebagai konteks, sehingga model membacanya dan umumnya mematuhinya, tetapi tidak ada mekanisme yang mencegah tindakan yang bertentangan dengannya. Instruksi yang tidak jelas paling tidak dapat diandalkan, dan dua file yang memberikan panduan berlawanan akan membuat agent memilih salah satunya secara sembarang. Untuk aturan yang harus selalu berlaku, gunakan hook atau aturan izin. Keduanya diberlakukan oleh client terlepas dari keputusan model.

Apakah AGENTS.md sebaiknya di-commit ke git?

Ya, untuk segala hal yang benar tentang project: perintah build, tata letak, dan konvensi. Itulah tujuan file tersebut, karena agent rekan satu tim Anda akan memulai dengan konteks yang sama seperti agent Anda. Hal yang bersifat pribadi atau khusus untuk satu mesin harus disimpan dalam file terpisah yang diabaikan oleh git, sedangkan kredensial tidak boleh disimpan di salah satu file tersebut.

Apa itu HUMAN.md dan apakah saya memerlukannya?

HUMAN.md adalah profil yang dapat dibaca mesin tentang seseorang, bukan tentang project. File ini memuat peran, batasan, dan keputusan yang telah Anda tetapkan agar hal-hal tersebut tidak dibahas ulang pada setiap sesi. Anda tidak memerlukan tooling untuk memulai: dua puluh baris yang ditulis secara manual dalam file instruksi tingkat pengguna sudah memberikan sebagian besar manfaatnya. Perlakukan file tersebut sebagai data pribadi dan jangan menyimpannya di repository mana pun yang Anda push.