AGENTS.md dan HUMAN.md: Panduan Lengkap

Apakah AGENTS.md

AGENTS.md ialah fail markdown biasa di akar repositori yang menerangkan kepada ejen pengekodan cara mengendalikan projek tersebut. Laman rasmi menerangkannya sebagai "README untuk ejen: tempat khusus dan mudah dijangka untuk menyediakan konteks serta arahan bagi membantu ejen pengekodan AI mengendalikan projek anda." Format ini diselia oleh Agentic AI Foundation di bawah Linux Foundation, dan lebih daripada dua puluh ejen membacanya, termasuk Codex, Cursor, Jules, Devin dan GitHub Copilot (setakat Julai 2026).

Konvensyen ini wujud atas sebab yang praktikal. Orang baharu dalam pasukan anda membaca README, meneka perintah binaan, kemudian bertanya kepada seseorang apabila tekaan itu salah. Ejen tidak boleh bertanya. Ejen akan meneka, menjalankan npm test pada projek yang menggunakan pnpm test, membaca kegagalan tersebut dan mencuba cara lain. Anda membayar setiap token itu. Dengan menulis perintah sebenar sekali, seluruh kelas kegagalan tersebut dapat dielakkan.

Tiada medan yang diwajibkan. Laman tersebut menyatakannya dengan jelas: "AGENTS.md hanyalah Markdown standard. Gunakan mana-mana tajuk yang anda mahu; ejen hanya menghuraikan teks yang anda berikan." Itulah keseluruhan spesifikasinya. Nilainya bukan pada format tersebut. Nilainya terletak pada fail yang berada di laluan yang sudah dicari oleh setiap alat.

Lokasi fail dan fail yang diutamakan

Letakkan fail pertama di akar repositori. Dalam monorepo, anda boleh menambah fail lain dalam setiap subprojek. Peraturannya mudah: "agents membaca fail terdekat secara automatik dalam pepohon direktori, jadi fail yang paling hampir diutamakan." Konflik antara dua fail diselesaikan dengan mengutamakan fail yang sedang diedit. Apa-apa yang anda taip dalam chat mengatasi kedua-duanya.

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 bersarang wajar digunakan kerana ini satu-satunya cara untuk menyatakan sesuatu yang benar dalam satu folder tetapi tidak benar dalam folder seterusnya. Peraturan seperti "setiap endpoint mengesahkan inputnya" hendaklah diletakkan bersebelahan dengan endpoint tersebut. Dalam fail akar, peraturan itu dimuatkan untuk setiap tugas yang tidak berkaitan dan tidak memberikan manfaat.

Perkara yang perlu dimasukkan dalam AGENTS.md

Catat perkara yang tidak dapat ditentukan oleh ejen hanya dengan membaca kod. Perintah build, test dan lint yang tepat perlu diletakkan dahulu, dalam format yang boleh ditampal ke terminal. Tambahkan perintah untuk menjalankan satu ujian, kerana ejen yang hanya tahu cara menjalankan keseluruhan suite akan menjalankannya sebanyak empat puluh kali. Nyatakan konvensyen yang berbeza daripada lalai alat, kerana ejen sudah mengetahui lalai dan hanya perlu mengetahui penyimpangan anda. Sertakan format mesej commit dan peraturan pull request jika ada.

Berikan butiran yang mencukupi supaya sesuatu dakwaan boleh disemak. "Gunakan lekukan 2 ruang" ialah arahan yang boleh digunakan kerana arahan itu sama ada dipatuhi atau tidak. "Formatkan kod dengan betul" tidak boleh digunakan kerana tiada perkara yang boleh disahkan daripadanya. Perkara yang sama terpakai pada lokasi: "Pengendali API berada dalam src/api/handlers/" lebih jelas daripada "pastikan fail tersusun".

Peraturan larangan juga wajar disertakan. "Jangan sekali-kali edit fail dalam dist/ kerana fail tersebut dijana oleh npm run build" menghalang satu kesilapan tertentu. Oleh sebab peraturan itu menyatakan puncanya, ejen boleh menentukan kes yang setara walaupun kes tersebut tidak ditulis.

Perkara yang tidak boleh dimasukkan

Jangan letakkan rahsia dalam mana-mana fail ini. Fail tersebut diserahkan kepada git, dimuatkan ke dalam konteks pada permulaan setiap sesi, dan dihantar kepada penyedia model bagi setiap permintaan. Kunci API dalam AGENTS.md menjadi sebahagian daripada sejarah repositori anda dan log pihak ketiga. Tunjukkan rujukan kepada rahsia itu dan bukannya menampalnya: "kata laluan pangkalan data berada dalam .env, yang diabaikan oleh git; minta kebenaran sebelum membacanya." Amalan yang lebih menyeluruh diterangkan dalam memastikan kelayakan berada di luar capaian ejen.

Jangan masukkan perkara yang boleh diperoleh oleh ejen melalui pemerhatian. Senarai direktori yang ditampal, salinan senarai kebergantungan, atau gambaran keseluruhan seni bina yang hanya mengulangi nama folder akan menjadi lapuk seminggu selepas ditulis. Sementara itu, semua kandungan tersebut menggunakan ruang konteks pada setiap sesi. Kekalkan perangkap dan sebabnya. Gugurkan inventori.

CLAUDE.md ialah contoh Claude Code bagi idea yang sama

Claude Code membaca CLAUDE.md dan tidak membaca AGENTS.md secara sendiri. Fail projek terletak di ./CLAUDE.md atau ./.claude/CLAUDE.md, manakala keutamaan peribadi untuk setiap projek diletakkan dalam ~/.claude/CLAUDE.md. Organisasi boleh menolak fail seluruh mesin ke /etc/claude-code/CLAUDE.md pada Linux. Fail yang ditemui digabungkan dari root sistem fail hingga direktori kerja anda. Oleh itu, fail yang paling hampir dengan lokasi anda melancarkan sesi dibaca paling akhir.

Jika repositori anda sudah mempunyai AGENTS.md, jangan kekalkan salinan kedua. Import fail itu, kemudian tambahkan perkara yang khusus kepada Claude sahaja:

@AGENTS.md

## Claude Code

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

Symlink berfungsi apabila anda tidak perlu menambahkan apa-apa:

ln -s AGENTS.md CLAUDE.md

Perintah itu tidak memaparkan apa-apa jika berjaya. Dalam sesi seterusnya, jalankan /context dan sahkan bahawa CLAUDE.md dipaparkan di bawah Fail memori. Jika fail itu tiada dalam senarai tersebut, fail itu tidak pernah dimuatkan. Oleh itu, kandungannya tidak digunakan. Untuk menjana draf pertama dan bukannya menulisnya sendiri, jalankan /init. Perintah ini membaca pangkalan kod dan menghasilkan fail permulaan. Jika CLAUDE.md sudah wujud, perintah ini mencadangkan penambahbaikan dan bukannya menulis ganti fail tersebut.

Pastikan setiap fail mempunyai kurang daripada kira-kira 200 baris. Fail yang lebih panjang menggunakan lebih banyak ruang tetingkap dan mengurangkan pematuhan. Jika anda mahu melihat perkara lain yang bersaing untuk ruang tersebut, perkara yang sebenarnya memenuhi tetingkap konteks ejen menghuraikannya.

Satu perkara perlu ditekankan. AGENTS.md ialah panduan, bukan sistem kebenaran. Kandungannya diterima sebagai konteks biasa. Model akan membacanya dan biasanya mematuhinya, tetapi tiada apa-apa yang menghalang tindakan yang bercanggah dengannya. Untuk peraturan yang mesti dipatuhi setiap kali, seperti "jangan sekali-kali push ke main", gunakan hook atau tetapan kebenaran. Kedua-duanya berjalan sebagai kod dan tidak bergantung pada keputusan model untuk mematuhinya.

Alat yang menulis fail ini untuk anda

Dua projek dalam senarai sohor kini GitHub pada 30 July 2026 menunjukkan hala tuju konvensyen ini.

agent0ai/dox (1,368 bintang setakat July 2026) ialah rangka kerja untuk memastikan pepohon fail AGENTS.md sentiasa terkini. Projek ini tidak menyediakan pakej atau runtime. Anda menyalin kandungan AGENTS.md projek ini ke dalam AGENTS.md akar anda sendiri, dan itulah proses pemasangannya. Untuk projek yang telah sedia ada, beritahu ejen anda:

Initialize DOX tree for this project now.

Ejen itu kemudian mencipta fail AGENTS.md anak dan indeksnya, menyemak pepohon tersebut sebelum mengedit apa-apa, serta mengemas kini dokumentasi yang terjejas selepas perubahan diterapkan. Andaian di sebaliknya ialah dokumentasi yang diselenggara oleh ejen sebagai kesan sampingan tugasnya kekal tepat, manakala dokumentasi yang dikemas kini secara manual oleh manusia tidak semestinya.

HUMAN.md, pendekatan yang sama ditujukan kepada anda

Intuition-Lab/personal-model (1,260 bintang setakat Julai 2026) menggunakan corak ini pada seseorang dan bukannya repositori. Projek ini menganggap HUMAN.md anda sebagai output sistem, bukannya fail yang anda taip: "model hidup tentang perkara yang penting sekarang, cara anda biasanya membuat keputusan, dan arah pergerakan perhatian anda." Ia dijalankan secara setempat pada macOS 13 atau lebih baharu, merekod aktiviti selepas anda memberikan kebenaran macOS, dan mendedahkan hasilnya kepada ejen melalui MCP (protokol konteks model). Langkah pemasangan ringkas:

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

Anda tidak memerlukan semua itu untuk memperoleh sebahagian besar manfaatnya. HUMAN.md yang ditulis sendiri mengandungi kira-kira dua puluh baris: peranan anda, zon waktu anda, susunan teknologi yang benar-benar anda gunakan, keputusan yang telah anda buat dan tidak mahu dibuka semula, serta jumlah penjelasan yang anda mahu terima. Fail ini mengurangkan penerangan berulang yang sama seperti yang dilakukan oleh fail projek, tetapi pada lapisan yang lebih tinggi.

Satu peringatan. HUMAN.md ialah profil seseorang, jadi fail ini sememangnya sensitif. Jangan simpan fail ini dalam repositori awam. Letakkannya dalam ~/.claude/CLAUDE.md, atau dalam CLAUDE.local.md yang diabaikan oleh git di akar projek. Fail ini dimuatkan bersama fail yang dikomitkan dan diperlakukan dengan cara yang sama.

Templat permulaan yang boleh anda salin

Templat ini sengaja ringkas. Padam bahagian yang tidak berkaitan, dan elakkan menambah bahagian yang tidak dapat anda kekalkan kemas kini.

# 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 kandungan itu, kemudian betulkannya terus di tempat asal. Petunjuk untuk menambah satu baris ialah apabila anda menaip pembetulan yang sama dalam chat sebanyak 2 kali. Peraturan ini memastikan fail itu kekal berguna dan menghalang fail tersebut daripada berkembang menjadi dokumen yang tiada sesiapa baca, termasuk mesin. Setelah stabil, fail itu bergerak bersama repository, yang paling penting apabila agent berjalan di tempat selain komputer riba anda: menjalankan coding agent pada server anda sendiri menerangkan persediaan itu.

FAQ

Adakah AGENTS.md fail yang sama dengan CLAUDE.md?

Kedua-duanya ialah idea yang sama di bawah dua nama fail. Claude Code membaca CLAUDE.md dan mengabaikan AGENTS.md melainkan anda memautkan kedua-duanya. Jadikan satu fail sebagai sumber rujukan utama dan pautkan fail yang satu lagi kepadanya, sama ada dengan baris @AGENTS.md di bahagian atas CLAUDE.md anda atau dengan ln -s AGENTS.md CLAUDE.md. Dua salinan penuh yang diselenggarakan secara berasingan akan bercanggah dalam tempoh sebulan.

Adakah penulisan AGENTS.md menjamin ejen mematuhinya?

Tidak. Kandungan tersebut dihantar sebagai konteks. Model membacanya dan biasanya mematuhinya, tetapi tiada mekanisme yang menghalang tindakan yang bercanggah dengannya. Arahan yang kabur paling kurang boleh dipercayai, manakala dua fail yang memberikan panduan berlawanan menyebabkan ejen memilih salah satu secara sewenang-wenangnya. Untuk peraturan yang mesti dipatuhi setiap kali, gunakan hook atau peraturan kebenaran. Peraturan ini dikuatkuasakan oleh klien tanpa mengira keputusan model.

Patutkah AGENTS.md dihantar ke git?

Ya, untuk apa-apa yang benar tentang projek: arahan build, susun atur dan konvensyen. Itulah tujuan fail ini, kerana ejen rakan sepasukan anda akan bermula dengan konteks yang sama seperti ejen anda. Apa-apa yang bersifat peribadi atau khusus untuk satu mesin hendaklah diletakkan dalam fail berasingan yang diabaikan oleh git, manakala kelayakan hendaklah diletakkan dalam kedua-duanya.

Apakah HUMAN.md dan adakah saya memerlukannya?

HUMAN.md ialah profil seseorang yang boleh dibaca mesin, bukannya profil projek. Profil ini menyimpan peranan, kekangan dan keputusan yang telah anda tetapkan supaya perkara tersebut tidak dibuka semula pada setiap sesi. Anda tidak memerlukan sebarang alat untuk bermula: dua puluh baris yang ditulis sendiri dalam fail arahan peringkat pengguna memberikan sebahagian besar manfaatnya. Anggap fail ini sebagai data peribadi dan jangan masukkannya ke dalam mana-mana repositori yang anda hantar.