Cara Menulis Fail AGENTS.md dan HUMAN.md yang Betul

Apakah itu AGENTS.md

AGENTS.md ialah fail markdown biasa di punca repositori yang memberitahu ejen pengekodan cara untuk bekerja pada projek tersebut. Laman rasmi menyifatkannya sebagai "README untuk ejen: tempat khusus dan boleh diramal untuk menyediakan konteks serta arahan bagi membantu ejen pengekodan AI bekerja pada projek anda." Format ini dikendalikan oleh Agentic AI Foundation di bawah Linux Foundation, dan lebih daripada dua puluh ejen membacanya, termasuk Codex, Cursor, Jules, Devin dan GitHub Copilot (sehingga Julai 2026).

Sebab konvensyen ini wujud adalah praktikal. Seseorang yang baharu dalam pasukan anda akan membaca README, meneka arahan binaan, dan bertanya kepada seseorang apabila tekaan itu salah. Ejen tidak boleh bertanya. Ia meneka, menjalankan npm test pada projek yang menggunakan pnpm test, membaca kegagalan tersebut, dan mencuba sesuatu yang lain. Anda membayar untuk setiap token tersebut. Menulis arahan sebenar sekali sahaja akan menghapuskan keseluruhan kelas kegagalan itu.

Tiada medan wajib. Laman tersebut menyatakan dengan jelas: "AGENTS.md hanyalah Markdown standard. Gunakan sebarang tajuk yang anda suka; ejen hanya menghuraikan teks yang anda sediakan." Itulah keseluruhan spesifikasi. Nilainya bukan pada format. Nilainya terletak pada fail yang berada di laluan yang sudah pun diperiksa oleh setiap alat.

Lokasi fail dan fail yang diutamakan

Letakkan fail pertama di root repositori. Dalam monorepo, anda boleh menambah lebih banyak fail di dalam setiap subprojek, dan peraturannya mudah: "ejen membaca fail terdekat dalam pepohon direktori secara automatik, jadi fail yang paling hampir akan diutamakan." Konflik antara dua fail diselesaikan dengan memilih fail yang sedang disunting, dan sebarang input yang anda taip ke dalam sembang akan 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

Penyarangan (nesting) wajar digunakan kerana ia merupakan satu-satunya cara untuk menyatakan sesuatu yang benar dalam satu folder tetapi salah dalam folder seterusnya. Peraturan seperti "setiap endpoint mengesahkan inputnya" perlu diletakkan bersebelahan dengan endpoint tersebut. Jika diletakkan dalam fail root, ia akan dimuatkan pada setiap tugasan yang tidak berkaitan dan tidak memberikan sebarang manfaat. Jika fail root anda sudah mempunyai bahagian khusus untuk setiap servis, memecahkannya kepada susun atur bersarang adalah penyelesaiannya, dan ia merangkumi peraturan yang perlu dipindahkan ke bawah serta peraturan yang kekal di peringkat atas.

Perkara yang perlu dimuatkan dalam AGENTS.md

Tuliskan perkara yang tidak dapat ditentukan oleh ejen dengan hanya membaca kod. Perintah binaan, ujian dan lint yang tepat hendaklah diletakkan di bahagian awal, dalam bentuk yang boleh anda tampal terus ke dalam terminal. Sertakan perintah untuk menjalankan satu ujian sahaja, kerana ejen yang hanya tahu menjalankan keseluruhan suite akan menjalankan keseluruhan suite tersebut sebanyak empat puluh kali. Namakan konvensyen yang berbeza daripada tetapan lalai alat, kerana ejen sudah mengetahui tetapan lalai dan hanya perlu diberitahu tentang penyimpangan anda. Sertakan format mesej komit dan peraturan pull request jika anda mempunyainya.

Jadilah cukup konkrit supaya sesuatu tuntutan boleh disemak. "Gunakan indentasi 2-ruang" ialah arahan yang boleh digunakan kerana ia sama ada berlaku atau tidak. "Format kod dengan betul" bukanlah arahan yang boleh digunakan, kerana tiada apa-apa di dalamnya yang boleh disahkan. Perkara yang sama berlaku untuk lokasi: "Pengendali API berada dalam src/api/handlers/" adalah lebih baik daripada "pastikan fail disusun dengan teratur".

Peraturan negatif juga penting. "Jangan sesekali mengedit fail di bawah dist/, ia dijana oleh npm run build" menghalang satu kesilapan khusus, dan kerana ia menamakan puncanya, ejen boleh menentukan kes setara yang tidak anda tuliskan. Peraturan mengenai skop juga perlu diletakkan di sini, kerana ejen yang dibiarkan dengan pertimbangannya sendiri akan menulis semula lebih daripada apa yang anda minta: satu kemahiran yang banyak ditiru tidak melakukan apa-apa selain menegaskan perubahan terkecil yang berkesan.

Perkara yang tidak sepatutnya dimasukkan

Jangan sekali-kali meletakkan rahsia dalam fail ini. Fail ini akan dimasukkan ke dalam git, dimuatkan ke dalam konteks pada permulaan setiap sesi, dan dihantar kepada penyedia model bagi setiap permintaan. Kunci API dalam AGENTS.md bermakna kunci API tersebut berada dalam sejarah repositori anda dan dalam log pihak ketiga. Rujuk kepada rahsia tersebut dan bukannya menampalnya: "kata laluan pangkalan data ada dalam .env, yang telah di-gitignore; minta izin sebelum membacanya." Disiplin yang lebih meluas dibincangkan dalam menjauhkan kelayakan daripada capaian ejen.

Tinggalkan apa-apa sahaja yang boleh disimpulkan oleh ejen dengan melihatnya sendiri. Senarai direktori yang ditampal, salinan senarai dependensi anda, gambaran keseluruhan seni bina yang menyatakan semula nama folder: kesemuanya akan menjadi lapuk seminggu selepas anda menulisnya, dan ia memakan ruang konteks pada setiap sesi sementara itu. Kekalkan perangkap dan sebab-sebabnya. Gugurkan inventori. Sebab-sebabnya perlu diasingkan, kerana ejen yang tidak dapat melihat mengapa bentuk yang luar biasa wujud akan mengubah suainya secara senyap, itulah sebabnya perlu mengekalkan fail DESIGN.md di sebelah fail ini.

CLAUDE.md ialah contoh Claude Code bagi idea yang sama

Claude Code membaca CLAUDE.md dan tidak membaca AGENTS.md secara automatik. Fail projek terletak di ./CLAUDE.md atau ./.claude/CLAUDE.md, keutamaan peribadi untuk setiap projek diletakkan dalam ~/.claude/CLAUDE.md, dan organisasi boleh menolak fail peringkat mesin ke /etc/claude-code/CLAUDE.md pada Linux. Fail yang ditemui dicantumkan dari akar sistem fail sehingga ke direktori kerja anda, jadi fail yang paling hampir dengan tempat anda melancarkan sesi akan dibaca terakhir. Setiap sesi yang anda mulakan dalam direktori tersebut memuatkan tindanan yang sama, yang menjadikannya boleh dilaksanakan untuk menjalankan dua sesi secara bersebelahan pada satu mesin, dan sesi-sesi tersebut boleh menyerahkan kerja antara satu sama lain semasa ia berjalan.

Jika repositori anda sudah mempunyai AGENTS.md, jangan selenggara salinan kedua. Import fail tersebut, kemudian tambah hanya perkara yang khusus untuk Claude:

@AGENTS.md

## Claude Code

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

Pautan simbolik (symlink) berfungsi apabila anda tidak mempunyai apa-apa tambahan untuk dimasukkan:

ln -s AGENTS.md CLAUDE.md

Perintah tersebut tidak mencetak apa-apa jika berjaya. Dalam sesi seterusnya, jalankan /context dan sahkan CLAUDE.md muncul di bawah Memory files. Jika ia tiada dalam senarai tersebut, fail itu tidak pernah dimuatkan, jadi tiada apa-apa di dalamnya yang diaplikasikan. Untuk menjana draf pertama dan bukannya menulisnya sendiri, jalankan /init: ia membaca pangkalan kod dan menghasilkan fail permulaan, dan apabila CLAUDE.md sudah wujud, ia mencadangkan penambahbaikan dan bukannya menulis ganti fail tersebut.

Pastikan setiap fail di bawah kira-kira 200 baris. Fail yang lebih panjang menggunakan lebih banyak tetingkap konteks dan tahap pematuhan akan menurun. Jika anda ingin melihat perkara lain yang bersaing untuk ruang tersebut, perkara yang sebenarnya mengisi tetingkap konteks ejen memperincikannya.

Satu perkara perlu diberi penekanan. AGENTS.md adalah panduan, bukan sistem kebenaran. Kandungannya sampai sebagai konteks biasa, jadi model membacanya dan biasanya mematuhi, tetapi tiada apa-apa yang menghalang tindakan yang bercanggah dengannya. Apabila peraturan yang anda tulis diabaikan secara senyap dan anda tidak tahu sebabnya, semak sebab arahan tidak diendahkan sebelum anda menulis semula ayat tersebut buat kali ketiga. Bagi peraturan yang mesti dipatuhi setiap masa, seperti "never push to main", gunakan hook atau tetapan kebenaran, kerana perkara tersebut berjalan sebagai kod dan tidak bergantung pada keputusan model untuk mematuhi.

Alatan yang menulis fail ini untuk anda

Dua projek dalam senarai trending GitHub pada 30 Julai 2026 menunjukkan hala tuju konvensyen ini.

agent0ai/dox (1,368 bintang setakat Julai 2026) ialah rangka kerja untuk memastikan pepohon fail AGENTS.md sentiasa terkini. Ia tidak mengeluarkan sebarang pakej atau runtime. Anda menyalin kandungan AGENTS.md miliknya ke dalam AGENTS.md akar anda sendiri, dan itulah proses pemasangannya. Bagi projek yang sedia ada, anda memberitahu ejen anda:

Initialize DOX tree for this project now.

Ejen tersebut kemudiannya mencipta fail AGENTS.md anak serta indeksnya, menelusuri pepohon tersebut sebelum ia menyunting apa-apa, dan mengemas kini dokumentasi yang terjejas selepas sesuatu perubahan dilakukan. Pertaruhan di sebalik ini ialah dokumentasi yang diselenggara oleh ejen sebagai kesan sampingan kerjanya akan kekal tepat, manakala dokumentasi yang dikemas kini secara manual oleh manusia tidak akan kekal tepat.

HUMAN.md, helah yang sama ditujukan kepada anda

Intuition-Lab/personal-model (1,260 bintang setakat Julai 2026) menggunakan corak ini kepada seseorang dan bukannya repositori. Projek ini membingkai HUMAN.md anda sebagai output sistem dan bukannya fail yang anda taip: "model hidup tentang perkara yang penting sekarang, cara anda cenderung membuat keputusan, dan ke mana tumpuan anda beralih." Ia berjalan secara setempat pada macOS 13 atau lebih baharu, menangkap aktiviti selepas anda memberikan kebenaran macOS, dan mendedahkan hasilnya kepada ejen melalui MCP (model context protocol). Laluan pemasangan ringkas:

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

Anda tidak memerlukan semua itu untuk mendapatkan kebanyakan manfaatnya. HUMAN.md yang ditulis tangan hanya sekitar dua puluh baris: peranan anda, zon waktu anda, stack yang anda benar-benar gunakan, keputusan yang telah anda buat dan tidak mahu dibuka semula, serta berapa banyak penjelasan yang anda mahukan sebagai balasan. Ia menjimatkan penjelasan berulang yang sama seperti yang dilakukan oleh fail projek, satu lapisan lebih tinggi.

Satu peringatan. HUMAN.md ialah profil seseorang, jadi ia sensitif mengikut definisinya. Jauhkan ia daripada repositori awam. Letakkannya dalam ~/.claude/CLAUDE.md, atau dalam CLAUDE.local.md yang diabaikan oleh git di root projek, yang dimuatkan bersama fail yang dikomit dan dilayan dengan cara yang sama.

Templat permulaan yang boleh anda salin

Bahagian ini sengaja dibuat ringkas. Padamkan bahagian yang tidak berkaitan, dan elakkan menambah bahagian yang anda tidak mampu 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, kemudian betulkan di tempatnya. Isyarat untuk menambah baris ialah apabila anda menaip pembetulan yang sama ke dalam sembang sebanyak dua kali. Satu peraturan itu memastikan fail kekal berguna, dan menghalangnya daripada berkembang menjadi dokumen yang tidak dibaca oleh sesiapa, termasuk mesin. Apabila ia sudah stabil, ia akan bergerak bersama repositori, yang paling penting apabila ejen berjalan di tempat selain komputer riba anda: menjalankan ejen pengekodan pada pelayan anda sendiri merangkumi persediaan tersebut.

FAQ

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

Kedua-duanya adalah konsep yang sama di bawah dua nama fail yang berbeza. Claude Code membaca CLAUDE.md dan mengabaikan AGENTS.md melainkan anda menyambungkannya. Kekalkan satu fail sebagai sumber rujukan utama dan pautkan fail yang satu lagi kepadanya, sama ada dengan baris yang mengandungi @AGENTS.md di bahagian atas CLAUDE.md anda atau dengan ln -s AGENTS.md CLAUDE.md. Dua salinan lengkap yang diselenggara secara berasingan akan mempunyai maklumat yang bercanggah dalam masa sebulan.

Adakah menulis AGENTS.md menjamin ejen akan mematuhinya?

Tidak. Kandungan tersebut disampaikan sebagai konteks, jadi model akan membacanya dan secara amnya mematuhi arahan tersebut, namun tiada apa yang menghalang tindakan yang bercanggah dengannya. Arahan yang samar-samar adalah yang paling kurang boleh dipercayai, dan dua fail yang memberikan panduan bertentangan akan menyebabkan ejen memilih salah satu secara arbitrari. Bagi peraturan yang mesti dipatuhi setiap masa, gunakan hook atau peraturan kebenaran, yang dikuatkuasakan oleh klien walau apa pun keputusan model tersebut.

Patutkah AGENTS.md dimasukkan ke dalam git?

Ya, untuk sebarang perkara yang benar tentang projek tersebut: arahan binaan (build commands), susun atur, dan konvensyen. Itulah tujuan fail tersebut, kerana ejen rakan sepasukan anda akan bermula dengan konteks yang sama seperti anda. Sebarang perkara yang bersifat peribadi atau khusus untuk satu mesin perlu diletakkan dalam fail berasingan yang diabaikan oleh git (gitignored), dan kelayakan (credentials) tidak boleh diletakkan dalam mana-mana fail tersebut.

Apakah itu HUMAN.md dan adakah saya memerlukannya?

HUMAN.md ialah profil seseorang yang boleh dibaca oleh mesin, bukannya profil projek. Ia menyimpan peranan anda, kekangan anda, dan keputusan yang telah anda tetapkan supaya ia tidak perlu dibincangkan semula setiap sesi. Anda tidak memerlukan sebarang alatan untuk bermula: dua puluh baris yang ditulis tangan dalam fail arahan peringkat pengguna anda sudah memberikan kebanyakan nilai tersebut. Anggap ia sebagai data peribadi dan jangan masukkan ke dalam mana-mana repositori yang anda tolak (push).