AGENTS.md dan HUMAN.md: Penjelasan Lengkap

Apa itu AGENTS.md

AGENTS.md adalah file Markdown biasa di root repositori yang menjelaskan cara coding agent bekerja pada proyek tersebut. Situs resmi menyebutnya sebagai "README untuk agent: tempat khusus yang konsisten untuk menyediakan konteks dan instruksi agar AI coding agent dapat bekerja pada 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 ketika tebakannya salah. Agent tidak dapat bertanya. Agent akan menebak, menjalankan npm test pada proyek yang menggunakan pnpm test, membaca kegagalan tersebut, lalu mencoba cara lain. Anda membayar setiap token dalam proses itu. Menuliskan perintah yang benar satu kali akan menghilangkan seluruh jenis kegagalan tersebut.

Tidak ada kolom yang diwajibkan. Situs tersebut menjelaskannya secara tegas: "AGENTS.md hanyalah Markdown standar. Gunakan heading apa pun yang Anda inginkan; agent cukup mem-parsing teks yang Anda berikan." Itulah seluruh spesifikasinya. Nilainya bukan pada formatnya. Nilainya terletak pada file yang berada di path yang sudah 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 terdapat konflik antara dua file, file yang sedang diedit menjadi acuan. Apa pun yang Anda ketikkan di 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

Struktur bertingkat layak digunakan karena hanya dengan cara ini Anda dapat menyatakan sesuatu yang benar di satu folder dan salah di folder berikutnya. Aturan seperti "setiap endpoint memvalidasi input" sebaiknya ditempatkan di dekat endpoint. Jika ditempatkan dalam file root, aturan itu akan dimuat pada setiap tugas yang tidak terkait dan tidak memberikan manfaat. Jika file root Anda sudah memiliki satu bagian untuk setiap service, memisahkannya ke dalam tata letak bertingkat adalah solusinya. Pendekatan ini juga menjelaskan aturan mana yang dipindahkan ke bawah dan mana yang tetap di bagian atas.

Apa yang harus dimuat dalam AGENTS.md

Tuliskan hal-hal yang tidak dapat diketahui agen hanya dengan membaca kode. Perintah build, test, dan lint yang tepat harus dicantumkan terlebih dahulu, dalam format yang dapat langsung ditempel ke terminal. Tambahkan perintah untuk menjalankan satu test, karena agen yang hanya tahu cara menjalankan seluruh test suite akan menjalankan seluruh suite itu empat puluh kali. Sebutkan konvensi yang berbeda dari default tool, karena agen sudah mengetahui default dan hanya perlu mengetahui penyimpangan Anda. Tambahkan format pesan commit dan aturan pull request jika Anda memilikinya.

Berikan instruksi yang cukup konkret agar suatu klaim dapat diperiksa. "Gunakan indentasi 2 spasi" adalah instruksi yang dapat digunakan karena penerapannya dapat diverifikasi. "Format kode dengan benar" tidak dapat digunakan karena tidak ada hal spesifik yang dapat diperiksa. Hal yang sama berlaku untuk lokasi: "Handler API berada di src/api/handlers/" lebih baik daripada "atur 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 menentukan kasus serupa yang tidak Anda tuliskan. Aturan tentang cakupan juga termasuk di sini, karena agen yang dibiarkan menggunakan penilaiannya sendiri akan menulis ulang lebih banyak daripada yang Anda minta: satu skill yang banyak disalin hanya menekankan penggunaan perubahan terkecil yang berhasil.

Hal yang tidak boleh dicantumkan di dalamnya

Jangan pernah menyimpan rahasia di 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 di dalam AGENTS.md menjadi API key dalam riwayat repositori Anda dan log pihak ketiga. Alih-alih menempelkan rahasia, arahkan ke lokasinya: "kata sandi database ada di .env, yang diabaikan oleh git; minta izin sebelum membacanya." Disiplin yang lebih luas dibahas dalam menjauhkan kredensial dari jangkauan agent.

Jangan mencantumkan hal yang dapat diketahui agent dengan melihat langsung. Daftar direktori yang ditempelkan, salinan daftar dependensi, atau ikhtisar arsitektur yang hanya mengulang nama folder akan menjadi usang pada minggu setelah Anda menulisnya, tetapi tetap menghabiskan konteks pada setiap sesi. Pertahankan jebakan dan alasannya. Hapus inventarisnya. Alasan perlu dipisahkan karena agent yang tidak dapat melihat mengapa struktur yang tidak biasa itu ada akan diam-diam merapikannya, seperti pada praktik menyimpan DESIGN.md di sebelah file ini.

CLAUDE.md adalah implementasi Claude Code dari gagasan 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 menerapkan file untuk seluruh mesin ke /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 Anda menjalankan sesi akan dibaca terakhir. Setiap sesi yang Anda mulai di direktori tersebut memuat susunan file yang sama. Inilah yang memungkinkan Anda menjalankan dua sesi secara berdampingan pada satu mesin, dan sesi tersebut dapat saling menyerahkan pekerjaan saat berjalan.

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

@AGENTS.md

## Claude Code

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

Symlink dapat digunakan jika tidak ada tambahan yang perlu Anda masukkan:

ln -s AGENTS.md CLAUDE.md

Perintah tersebut tidak menampilkan apa pun jika berhasil. Pada sesi berikutnya, jalankan /context dan pastikan CLAUDE.md muncul di bawah Memory files. Jika tidak ada dalam daftar tersebut, file tidak pernah dimuat sehingga tidak ada isinya yang diterapkan. Untuk membuat draf awal tanpa menulisnya secara manual, jalankan /init. Perintah ini membaca basis kode dan menghasilkan file awal. Jika CLAUDE.md sudah ada, perintah tersebut menyarankan perbaikan alih-alih menimpanya.

Usahakan setiap file tidak lebih dari sekitar 200 baris. File yang lebih panjang menggunakan lebih banyak ruang dalam konteks, sehingga kepatuhan menurun. Jika ingin melihat hal lain yang menggunakan ruang tersebut, uraian tentang isi sebenarnya dari context window agent menjelaskannya secara terperinci.

Ada satu hal yang perlu ditekankan. AGENTS.md berisi panduan, bukan sistem izin. Isinya diterima sebagai konteks biasa. Model akan membacanya dan biasanya mematuhinya, tetapi tidak ada mekanisme yang memblokir tindakan yang bertentangan dengannya. Jika aturan yang Anda tulis diam-diam dilewati dan Anda tidak tahu alasannya, telusuri alasan instruksi dapat diabaikan sebelum menulis ulang kalimatnya untuk ketiga kalinya. 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 membuat 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 struktur pohon file AGENTS.md tetap mutakhir. Proyek ini tidak merilis 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 pohon itu sebelum mengedit apa pun, lalu memperbarui dokumentasi yang terdampak setelah perubahan diterapkan. Gagasan dasarnya adalah dokumentasi yang dipelihara agent sebagai bagian dari pekerjaannya akan tetap akurat, sedangkan dokumentasi yang diperbarui secara manual oleh manusia tidak.

HUMAN.md, trik yang sama untuk Anda

Intuition-Lab/personal-model (1,260 bintang per Juli 2026) menerapkan pola tersebut pada seseorang, bukan repositori. Proyek ini memosisikan 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 pada macOS 13 atau versi lebih baru, merekam aktivitas setelah Anda memberikan izin macOS, dan menyediakan hasilnya kepada agent 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 panjangnya 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 menghemat penjelasan berulang yang sama seperti yang dihemat file proyek, tetapi pada lapisan yang lebih tinggi.

Satu hal yang perlu diperhatikan. HUMAN.md adalah profil seseorang, sehingga secara definisi 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.

Template awal yang dapat Anda salin

Bagian ini sengaja dibuat singkat. Hapus bagian yang tidak relevan, dan jangan menambahkan bagian yang tidak dapat Anda perbarui secara berkala.

# 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 terlebih dahulu, lalu perbaiki langsung di tempat. Tambahkan baris jika Anda mengetikkan koreksi yang sama di chat sebanyak 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 itu paling penting ketika agent berjalan di tempat selain laptop Anda: menjalankan coding agent di server Anda sendiri menjelaskan konfigurasi 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. Simpan 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 dipelihara secara terpisah akan berbeda dalam waktu satu bulan.

Apakah menulis AGENTS.md menjamin agent akan mematuhinya?

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

Apakah AGENTS.md harus di-commit ke git?

Ya, untuk segala hal yang benar tentang project: perintah build, struktur, dan konvensi. Itulah tujuan file tersebut, karena agent milik rekan tim Anda kemudian memulai dengan konteks yang sama seperti agent Anda. Hal yang bersifat pribadi atau spesifik 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 seseorang yang dapat dibaca mesin, bukan profil project. File ini memuat peran, batasan, dan keputusan yang telah Anda tetapkan agar hal-hal tersebut tidak dibuka kembali pada setiap sesi. Anda tidak memerlukan tooling untuk memulainya: dua puluh baris yang ditulis manual dalam file instruksi tingkat pengguna sudah memberikan sebagian besar manfaatnya. Perlakukan file tersebut sebagai data pribadi dan jangan menyertakannya dalam repositori mana pun yang Anda push.