# Apakah AGENTS.md dan Cara Menulisnya Sendiri dalam 30 Minit > Format AGENTS.md, sokongan dalam alat AI, templat sedia guna, peraturan dan kesilapan. Cara menyelaraskan AGENTS.md dengan CLAUDE.md dan fail arahan lain. Source: https://ailoot.ai/blog/ms/agents-md-guide-template/ Canonical: https://ailoot.ai/blog/ms/agents-md-guide-template/ Language: ms Publisher: Ailoot (https://ailoot.ai/) Translation: guide-034 Revision: sha256-95d53f456456712d4bde2ef75af47c0f1c33001e4eba7a031f012b6e6678b5b9 Bahan praktikal tentang vibe coding dan bekerja dengan ejen: [dokumentasi Ailoot](https://ailoot.ai/docs/). ## AGENTS.md dalam Satu Perenggan
Inti utama bahagian AGENTS.md ialah fail Markdown biasa di akar projek anda yang mengandungi arahan untuk ejen AI: cara memasang kebergantungan, menjalankan ujian, gaya kod yang perlu diikuti dan perkara yang tidak boleh diusik. Format ini terbuka, dicipta oleh OpenAI pada Ogos 2025, dan menyertai Linux Foundation pada Disember tahun yang sama. Banyak alat pengekodan boleh menggunakannya, tetapi cara fail dikesan berbeza mengikut klien dan versi: sesetengahnya memuatkan AGENTS.md secara automatik, manakala yang lain memerlukan tetapan nama fail atau konfigurasi pembacaan fail yang jelas. Sejak versi 2.1.277 (September 2026), Claude Code juga membaca AGENTS.md jika projek tiada CLAUDE.md. Jika CLAUDE.md wujud, Claude Code secara lalai hanya membaca fail itu, manakala AGENTS.md disertakan dengan baris `@AGENTS.md` atau melalui pautan simbolik.
Di bawah, format ini dibincangkan berdasarkan [agents.md](https://agents.md), dokumentasi [OpenAI Codex](https://github.com/openai/codex), [JetBrains Junie](https://junie.jetbrains.com/docs/guidelines-and-memory.html), [Cursor Rules Docs](https://cursor.com/docs/rules), [log perubahan GitHub Copilot Coding Agent](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/) dan [siaran akhbar Linux Foundation tentang Agentic AI Foundation](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation). Semua angka dan ciri adalah setakat 30 Mei 2026, dan sokongan AGENTS.md dalam Claude Code dihuraikan berdasarkan [dokumentasi Anthropic](https://code.claude.com/docs/en/memory#agents-md), dengan kemas kini pada 24 September 2026. Jika anda tidak tahu langsung apa itu zoo alat yang ada di pasaran ini atau mengapa alat-alat itu memerlukan fail bersama, baca dahulu panduan [“Apa yang Patut Digunakan untuk Menulis Kod pada 2026: 8 Alat AI daripada Claude Code hingga Antigravity”](https://ailoot.ai/blog/ms/ai-coding-tools/). Artikel ini memfokuskan khusus pada format AGENTS.md dan cara menulisnya sendiri dalam 30 minit. ## Apakah AGENTS.md dan Dari Mana Asalnya?
Inti utama bahagian AGENTS.md ialah format fail Markdown terbuka yang membolehkan anda menulis arahan sendiri untuk ejen AI. OpenAI melancarkannya pada Ogos 2025 bersama Codex CLI dan serta-merta menjemput pengarang bersama: Cursor, Sourcegraph Amp, Google Jules dan Factory. Ideanya mudah: “jangan cipta fail proprietari untuk setiap alat; mari sepakat menggunakan satu fail.” Pada 9 Disember 2025, AGENTS.md, bersama MCP daripada Anthropic dan goose daripada Block, menyertai Linux Foundation sebagai salah satu daripada tiga projek pengasas Agentic AI Foundation yang baharu. Menjelang Disember tahun yang sama, lebih daripada 60,000 repositori GitHub sudah mengandungi AGENTS.md pada akar repositori.
Sebelum ini, setiap alat AI mempunyai fail peraturannya sendiri: Anthropic mempunyai `CLAUDE.md`, Cursor mempunyai `.cursorrules`, GitHub mempunyai `.github/copilot-instructions.md`, Aider mempunyai `.aider.conf.yml`, dan JetBrains mempunyai `.junie/guidelines.md`. Jika pasukan anda mempunyai tiga ejen berbeza, itu bermakna tiga fail selari dengan kandungan yang sama, yang akan mula bercanggah dalam masa seminggu. OpenAI orang pertama yang bosan dengan keadaan ini. Pada Ogos 2025, syarikat itu melancarkan Codex CLI dan pada masa yang sama memperkenalkan [agents.md](https://agents.md) sebagai format terbuka. Daripada laman tersebut: > “Anggap AGENTS.md sebagai README untuk ejen.” > > ([agents.md](https://agents.md), diterjemahkan daripada bahasa Inggeris) Intinya ialah AGENTS.md melengkapi README. README ditulis untuk manusia: “apakah projek ini, cara menjalankannya secara setempat, cara menyumbang.” AGENTS.md ditulis untuk ejen: arahan shell yang tepat, kriteria “selesai” yang boleh disahkan dan sempadan seperti “jangan sesekali sentuh ini.” Daripada laman tersebut: > “AGENTS.md melengkapi README: fail ini mengandungi konteks tambahan, kadangkala terperinci, yang diperlukan ejen—langkah binaan, ujian dan konvensyen yang akan memenuhi README atau tidak diperlukan oleh penyumbang manusia.” > > ([agents.md](https://agents.md), diterjemahkan daripada bahasa Inggeris) Menjelang September 2025, GitHub Copilot Coding Agent menyokong format ini ([log perubahan, 28.08.2025](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/)). Menjelang Disember, Cursor, Junie, Gemini CLI, Aider dan sedozen alat lain menyertainya. Pada 9 Disember 2025, Linux Foundation menubuhkan [Agentic AI Foundation (AAIF)](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation): tiga projek pengasasnya ialah AGENTS.md daripada OpenAI, MCP daripada Anthropic dan goose daripada Block. Ahli pengasasnya ialah AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft dan OpenAI. Menjelang 24 Februari 2026, yayasan itu sudah merangkumi [146 organisasi](https://www.linuxfoundation.org/press/agentic-ai-foundation-welcomes-97-new-members), termasuk Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, UiPath dan Hitachi. Sejak itu, AGENTS.md tidak lagi menjadi “satu lagi benda daripada OpenAI” dan menjadi standard de facto. ## Ejen AI Mana yang Membaca AGENTS.md, dan Mana yang Tidak?
Inti utama bahagian AGENTS.md digunakan dalam pelbagai alat pengekodan, termasuk klien dalam jadual di bawah. Baca jadual itu sebagai peta cara pemuatan, bukan janji sokongan natif yang seragam: pengesanan automatik, konfigurasi jelas, keutamaan nama fail dan pengendalian fail bersarang boleh berbeza. Claude Code daripada Anthropic sekian lama menjadi pengecualian: issue \#6235 yang meminta sokongan kekal terbuka dari Ogos 2025 hingga Ogos 2026. Sejak versi 2.1.277 (18 September 2026), Claude Code membaca AGENTS.md sendiri jika projek tiada CLAUDE.md. Jika CLAUDE.md wujud, hanya fail itu dibaca secara lalai, manakala AGENTS.md disertakan melalui baris `@AGENTS.md` dalam CLAUDE.md atau melalui pautan simbolik.
Jadual sokongan setakat 30 Mei 2026; baris Claude Code dikemas kini pada 24 September 2026: | Alat | Membaca AGENTS.md | Tarikh / sumber | |----|----|----| | OpenAI Codex CLI | Ya (format natif) | Ogos 2025, [agents.md](https://agents.md) | | GitHub Copilot Coding Agent | Ya | 28.08.2025, [GitHub Changelog](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/) | | Cursor | Ya, akar + bersarang | [Cursor Rules Docs](https://cursor.com/docs/rules) | | JetBrains Junie | Ya, projek + global `~/.junie/AGENTS.md` | [Junie Docs](https://junie.jetbrains.com/docs/guidelines-and-memory.html) | | Gemini CLI (Google) | Ya, melalui `.gemini/settings.json` dengan `fileName: AGENTS.md` | [agents.md](https://agents.md) | | Jules (Google) | Ya, pengarang bersama standard | Ogos 2025 | | Sourcegraph Amp | Ya, pengarang bersama standard | Ogos 2025 | | Aider | Ya, melalui `read: AGENTS.md` dalam `.aider.conf.yml` | [agents.md](https://agents.md) | | Factory | Ya, pengarang bersama standard | Ogos 2025 | | OpenCode | Ya | — | | Zed | Ya | [agents.md](https://agents.md) | | Warp | Ya | [agents.md](https://agents.md) | | VS Code | Ya | [agents.md](https://agents.md) | | Windsurf | Ya | — | | Devin (Cognition) | Ya, melalui Spec Kit Skills | April 2026 | | RooCode, Kilo Code, Augment Code | Ya | [agents.md](https://agents.md) | | **Claude Code (Anthropic)** | **Ya, jika projek tiada CLAUDE.md** | Sejak versi 2.1.277 (18.09.2026), [dokumentasi Claude Code](https://code.claude.com/docs/en/memory#agents-md) | Anthropic menjadi pemain utama terakhir yang menyertai. Pada Ogos 2025, issue \#6235 yang meminta sokongan AGENTS.md dibuka dalam repositori rasmi `anthropics/claude-code`. Issue itu kekal terbuka selama hampir setahun dan ditutup pada 17 Ogos 2026; versi 2.1.277 dengan sokongan AGENTS.md dikeluarkan pada 18 September. Logik Anthropic adalah seperti berikut: CLAUDE.md diberi keutamaan, dan AGENTS.md dibaca apabila tiada CLAUDE.md dalam folder kerja atau mana-mana folder induk. Menurut [dokumentasi](https://code.claude.com/docs/en/memory#agents-md), cara kerjanya begini: | Kandungan projek | Perkara yang dibaca oleh Claude Code | |----|----| | AGENTS.md sahaja | AGENTS.md | | AGENTS.md dan CLAUDE.md (atau CLAUDE.local.md) | CLAUDE.md sahaja | | CLAUDE.md dengan baris `@AGENTS.md` | CLAUDE.md, yang menyertakan AGENTS.md | Perangkapnya: `CLAUDE.local.md` peribadi juga dikira, dan dengan fail itu Claude Code berhenti membaca AGENTS.md. Anda boleh menukar tingkah laku ini dalam `/config`, di bawah Project instructions—contohnya, menetapkan Claude Code supaya membaca kedua-dua fail serentak. Dalam versi sebelum 2.1.277, AGENTS.md tidak dimuatkan secara automatik; baris `@AGENTS.md` dalam CLAUDE.md masih menjadi penyelesaian alternatif. ## Apakah Perbezaan AGENTS.md dengan CLAUDE.md dan `.cursorrules`?
Inti utama bahagian Dari segi teknikal, tiada apa-apa yang istimewa tentangnya: keempat-empat format (AGENTS.md, CLAUDE.md, `.cursorrules`, `.github/copilot-instructions.md`) ialah fail Markdown biasa yang mengandungi arahan untuk ejen. Perbezaannya ialah siapa yang membacanya dan di mana fail itu berada. AGENTS.md boleh menyimpan arahan bersama untuk beberapa klien, dengan cara pengesanan atau konfigurasi khusus setiap klien dikekalkan secara berasingan. CLAUDE.md hanya untuk Claude Code, tetapi memberikan akses kepada ciri lanjutan: peraturan khusus mengikut laluan, `CLAUDE.local.md` untuk penggantian peribadi, `@import` untuk memasukkan fail lain, serta hierarki projek + pengguna + setempat. `.cursorrules` sudah lapuk dalam Cursor—sistem baharu menggunakan `.cursor/rules/*.mdc` dengan lampiran automatik mengikut jenis fail. `.github/copilot-instructions.md` hanya diperlukan untuk Copilot web.
Perbandingan empat format setakat 30 Mei 2026: | Format | Siapa yang membacanya | Lokasi | Kekuatan | Kelemahan | |----|----|----|----|----| | **AGENTS.md** | Pelbagai klien; pemuatan bergantung pada klien/versi | Akar repositori dan fail bersarang mengikut peraturan klien | Kandungan arahan bersama, dengan konfigurasi pemuatan khusus klien | Semak pengesanan, hierarki dan keutamaan setiap klien secara berasingan | | **CLAUDE.md** | Claude Code sahaja | Akar + `~/.claude/CLAUDE.md` + `CLAUDE.local.md` | Hierarki, peraturan khusus laluan, `@import`, skills, hooks | Claude sahaja. Tidak berfungsi dalam Cursor / Codex / Copilot | | **`.cursor/rules/*.mdc`** | Cursor sahaja | `.cursor/rules/.mdc` | Lampiran automatik mengikut jenis fail (TS, Python, laluan tertentu) | Cursor sahaja, sintaks `.mdc` bukan standard | | **`.github/copilot-instructions.md`** | GitHub Copilot (web + klasik) | `.github/` | Berfungsi terus dalam pelayar di GitHub.com | Copilot sahaja, menggandakan AGENTS.md | Idea utamanya: AGENTS.md boleh menyimpan arahan projek bersama, manakala laluan pemuatan dan tetapan peribadi setiap klien masih memerlukan konfigurasi tersendiri. Claude Code mempunyai `CLAUDE.local.md` untuk tujuan itu, manakala Cursor mempunyai fail `.mdc` setempat di bawah pengguna. AGENTS.md sahaja tidak menyediakan ciri itu—anda perlu menggabungkannya dengan fail lain atau bersetuju dalam pasukan untuk menulis peraturan peribadi dalam bahagian yang diabaikan oleh Git. Satu lagi butiran penting ialah monorepo. Codex dan Cursor menggunakan peraturan “AGENTS.md yang paling hampir akan digunakan”: > “Dalam monorepo, letakkan AGENTS.md yang berasingan dalam setiap pakej. Ejen membaca fail yang paling hampir secara automatik dalam pepohon direktori, dan fail yang paling hampir akan digunakan.” > > ([agents.md](https://agents.md), diterjemahkan daripada bahasa Inggeris) [agents.md](https://agents.md) menyatakan bahawa monorepo utama OpenAI mengandungi 88 fail AGENTS.md untuk subpakej yang berbeza. Jika anda bekerja dalam monorepo, agihkan peraturan mengikut aras: peraturan umum di akar, peraturan khusus dalam subfolder. ## Apakah Kandungan AGENTS.md yang Baik?
Inti utama bahagian Rangka AGENTS.md yang baik mempunyai 8 bahagian yang terdapat dalam kebanyakan fail popular: Gambaran keseluruhan projek, Arahan persediaan, Gaya kod, Petua persekitaran pembangunan, Arahan ujian, Garis panduan PR, Pertimbangan keselamatan dan Sempadan (perkara yang tidak boleh dilakukan). Yang lain semuanya pilihan. Peraturan utama: setiap item mestilah arahan yang tepat atau contoh konkrit, bukannya idea umum seperti “tulis kod yang kemas”.
Laman [agents.md](https://agents.md) menawarkan format yang fleksibel—“sebarang Markdown”. Namun, 80% fail yang baik di luar sana mengandungi lapan bahagian yang sama. Peraturan utama: setiap item patut berupa arahan yang tepat atau contoh konkrit. Idea abstrak seperti “tulis kod yang kemas” akan diabaikan oleh ejen. 1. **Gambaran keseluruhan projek** — 2–3 baris. Apakah projek itu, untuk siapa dan apakah matlamat utamanya. Tiada pemasaran. Contoh: “Bot Telegram untuk onboarding ke bengkel berbayar. Stack: Next.js 14, Prisma, PostgreSQL. Dicetuskan oleh rekod baharu dalam `purchases`.” 2. **Arahan persediaan** — arahan shell yang tepat untuk menjalankannya secara setempat. `npm install`, `npm run dev`, `npm run build`. Jangan tulis “biasanya begini cara kami melakukannya.” 3. **Gaya kod / konvensyen** — peraturan khusus berserta contoh, bukan “tulis dengan kemas”. Contohnya: “TypeScript strict, tanda petik tunggal, tiada default export, nama komponen dalam PascalCase, hooks bermula dengan `use`.” 4. **Petua persekitaran pembangunan** — lokasi perkara penting. Pemboleh ubah yang diperlukan dalam `.env`, lokasi rahsia disimpan, port yang sedang digunakan dan cara bekerja dengan DB setempat. 5. **Arahan ujian** — cara menjalankan ujian tertentu dan perkara yang dianggap “lulus”. Contohnya: `npm test -- --testPathPattern=user-auth`; 100% lulus dijangka. 6. **Garis panduan PR / commit** — format mesej commit, senarai semak sebelum PR (ujian, linter, dokumentasi) dan pihak yang meluluskan. 7. **Pertimbangan keselamatan** — perkara yang tidak boleh berlaku. “Jangan sekali-kali komitkan `.env`. Rahsia hanya boleh disimpan dalam Vault. Jangan paparkan data peribadi pengguna dalam log.” 8. **Sempadan / Jangan lakukan ini** — larangan berserta alternatif. “Jangan gunakan `git push --force` pada main. Jika perlu membuat rollback, gunakan `git revert` atau `git reset` pada feature branch.” Untuk setiap bahagian, ikut prinsip “arahan menggantikan idea”. Ejen akan mengabaikan “berhati-hati dengan migrasi”. Ia akan mematuhi “Sebelum `alembic upgrade head`, jalankan `alembic check`. Jika terdapat ralat, jangan gunakan migrasi itu; tanya saya.” ## Templat AGENTS.md Sedia Digunakan (Salin dan Sesuaikan)
Inti utama bahagian Di bawah ialah templat permulaan AGENTS.md untuk projek web biasa. Salinnya ke akar repositori, gantikan ``, ``, dan arahan yang tepat, kemudian buang bahagian yang tidak diperlukan. Penyesuaiannya mengambil masa 20–30 minit—atau lebih lama jika ini kali pertama anda.
````markdown # AGENTS.md ## Project overview - . Stack: . Main entities: . Details for people are in README.md. ## Setup commands ```bash # first install npm install cp .env.example .env # then fill in manually; see list below # run npm run dev # dev server on :3000 npm run build # production build npm run start # run production build ``` ## Dev environment - Node 20+ (via nvm: `nvm use 20`) - PostgreSQL 16 locally on :5432 (`docker-compose up postgres`) - Redis is optional, needed only for queues (`docker-compose up redis`) - `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET` - Never read the entire `.env` file. If you need one variable: `grep "^VAR=" .env` ## Code style - TypeScript strict mode - Single quotes, no semicolons (unless ESLint requires them) - Imports: external first, then internal via `@/`, then relative - Components in PascalCase; hooks start with `use` - No `any` without an explicit comment explaining “why it can’t be typed” Example of a good module: ```ts import { z } from 'zod' const UserSchema = z.object({ email: z.string().email(), name: z.string().min(2), }) export function parseUser(raw: unknown) { return UserSchema.parse(raw) } ``` ## Testing ```bash npm test # all tests npm test -- --testPathPattern=auth # auth only npm test -- --watch # watch mode ``` All tests must pass (be green) before committing. If a test is red, don’t commit; ask me what to do. ## Pull request guidelines - Commit format: `(): ` (`feat(auth): add magic-link`) - Before PR: `npm run build && npm test && npm run lint` - PR description = what changes, why, and how to test - Don’t approve your own PR—always wait for human review ## Security - Secrets only in `.env` and Vault, never in code - Don’t log personal data (email, phone, name) - When working with the production DB, use read-only queries only unless explicitly authorized - Don’t hardcode external service API keys (Stripe, OpenAI) in tests ## Never do this - Don’t `git push --force` to main. If you need to roll back, use `git revert` or open a new PR - Don’t run DB migrations without `alembic check` (or the equivalent in your ORM) - Don’t use `npm install -g` or `sudo` for project dependencies - Don’t add dependencies without approval (especially heavy ones: webpack plugins, ORM) ```` Secara purata, templat ini mempunyai 80–120 baris. Jika fail melebihi 150 baris, itu petanda anda perlu memfaktorkannya semula: pindahkan sesuatu ke `docs/`, pautkan kepada maklumat lain atau ringkaskannya menjadi satu baris. Dalam amalan, fail sepanjang 100–150 baris berfungsi paling baik; selepas had itu, peningkatan kualiti mula berbalik. ## Apakah 5 Peraturan yang Menjadikan AGENTS.md Benar-benar Berguna?
Inti utama bahagian AGENTS.md yang baik mengikuti lima peraturan: arahan menggantikan idea, larangan disertai alternatif, tepat satu sumber kebenaran, kriteria penyelesaian yang boleh disahkan dan fail yang kurang daripada 150 baris.
1. **Arahan menggantikan idea.** Ejen tidak memahami “berhati-hati dengan migrasi”. Ia akan mematuhi `alembic check` sebelum `alembic upgrade head`. Ejen bekerja dengan arahan dan syarat, bukan perasaan. Bentukkan semua peraturan utama sebagai “buat X, jika tidak, buat Y”. 2. **Larangan disertai alternatif.** Larangan kosong “jangan buat force push” akan diabaikan secara senyap oleh ejen selepas dua atau tiga arahan. Padanan “jangan buat X; buat Y sebagai ganti” berkesan. Contoh: “Jangan gunakan `git push --force` pada main; jika perlu membuat rollback, gunakan `git revert` atau buka PR baharu.” 3. **Tepat satu sumber kebenaran.** AGENTS.md di akar ialah sumber kebenaran untuk seluruh projek. Jika anda mempunyai monorepo, gunakan fail AGENTS.md bersarang dalam subfolder dan ikut peraturan “yang paling hampir akan digunakan”. Jangan ada fail selari dengan arahan yang bercanggah. 4. **Kriteria “selesai” yang boleh disahkan.** “Ujian mesti lulus” tidak berguna. Kriteria yang tepat ialah: `npm test` mengembalikan kod keluar 0 dan tidak mencetak `FAIL` ke stdout. “Kod perlu kemas” juga tidak berguna. Kriteria yang tepat ialah: `npm run lint` lulus tanpa amaran. Ejen hanya memahami maksud “selesai” jika syaratnya dihuraikan secara jelas. 5. **Fail kurang daripada 150 baris.** Selepas 150 baris, metrik mula merosot: ejen menggunakan lebih banyak konteks untuk membaca dan terlepas peraturan penting. Jika kandungan tidak muat, pindahkan butiran ke `docs/architecture.md` dan pautkannya daripada AGENTS.md, dengan hanya arahan dan sempadan dikekalkan dalam fail itu. ## Apakah 10 Kesilapan yang Menjadikan AGENTS.md Tidak Berguna?
Inti utama bahagian Sebab utama AGENTS.md tidak berfungsi ialah ungkapan yang kabur. Dalam kajian terhadap lebih daripada 2,500 repositori, GitHub Blog menunjukkan bahawa kebanyakan fail gagal kerana ditulis terlalu umum. Contohnya, “Anda ialah pembantu pengekodan yang membantu” langsung tidak memberikan maklumat berguna kepada ejen. Berikut ialah 10 kesilapan lazim dan rupanya dalam fail yang buruk: penduaan README, prosa tidak berstruktur, 30+ larangan tanpa alternatif, keutamaan yang bercanggah, rahsia yang ditulis secara terus, dokumentasi lapuk dan seni bina yang terlalu rumit untuk tugasan mudah.
1. **Peraturan kabur tanpa arahan.** Ejen akan mengabaikan “berhati-hati dengan migrasi”—ayat itu kosong baginya. Hanya arahan khusus dengan syarat yang berkesan: “Jalankan `alembic check` sebelum `alembic upgrade head`. Jika ada ralat, jangan gunakan migrasi itu; tanya saya.” 2. **“Kod bersih.”** Frasa yang tidak berguna. Gantikannya dengan corak khusus: “Gunakan komponen fungsi dengan hooks. Contoh: `function LoginForm() { const [email, setEmail] = useState(''); ... }`” 3. **Prosa tidak berstruktur.** Jika AGENTS.md mengandungi 300 baris prosa tanpa tajuk, ejen akan menghabiskan 80K token konteks untuk petikan yang tidak relevan dan terlepas perkara penting. Gunakan tajuk H2/H3, bahagian pendek dan senarai berbulet. 4. **Fail melebihi 150 baris.** Metrik kualiti merosot selepas ambang ini. Bahagikan kandungan antara fail utama dengan pautan ke butiran dalam `docs/`. 5. **30+ larangan tanpa alternatif.** Jika fail mempunyai senarai panjang “jangan buat X, jangan buat Y” tanpa menerangkan “buat Z sebagai ganti”, ejen akan terkial-kial tanpa arah. 6. **Menduplikasi README.md.** Jika anda sudah menulis “cara memasang dan menjalankan” dalam README, jangan salin kandungannya ke AGENTS.md. Sebaliknya, rujuk README dalam satu baris dan huraikan dalam AGENTS.md perkara yang diperlukan oleh ejen tetapi tidak oleh penyumbang manusia. 7. **Rahsia dikodkan terus.** AGENTS.md mungkin terbuka kepada umum (kerana terdapat dalam Git). Jangan letakkan kunci API, token atau kata laluan sebenar di dalamnya. Hanya sertakan rujukan kepada stor rahsia: “Lihat Vault: `secret/staging/db`.” 8. **Keutamaan bercanggah tanpa susunan.** “Bergerak pantas” + “kekalkan liputan ujian 90%” menyebabkan ejen tidak pasti perkara yang perlu dipilih. Susun keutamaan dengan jelas: “Liputan ujian ≥80% dahulu, kemudian kelajuan. Jika bercanggah, utamakan ujian.” 9. **Dokumentasi lapuk.** Huraian seni bina menyatakan REST+polling sedangkan sistem sebenar sudah menggunakan WebSockets. Ejen mengikuti huraian lapuk itu lalu merosakkan seni bina. Peraturan: kemas kini AGENTS.md dalam PR yang sama dengan kod setiap kali seni bina berubah. 10. **Seni bina terlalu rumit untuk tugasan mudah.** Jika seseorang meminta perubahan dua baris dalam konfigurasi, ejen tidak sepatutnya perlu membaca keseluruhan topologi 14 mikropelayanan. Pindahkan seni bina “mendalam” ke `docs/architecture.md`; dalam AGENTS.md, tinggalkan sahaja “jika tugasan berkaitan seni bina, baca `docs/architecture.md`”. [Kajian GitHub Blog terhadap lebih daripada 2,500 repositori AGENTS.md](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/) menyatakan kesimpulan utamanya: > “Kebanyakan fail ejen gagal kerana terlalu umum. ‘Anda ialah pembantu pengekodan yang membantu’ tidak berkesan.” > > ([GitHub Blog](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/), diterjemahkan daripada bahasa Inggeris) ## Bagaimana Mengekalkan AGENTS.md dan CLAUDE.md dalam Satu Repositori?
Inti utama bahagian Tiga senario: (1) Claude Code sahaja—kekalkan CLAUDE.md; AGENTS.md tidak diperlukan. (2) Alat bukan Claude sahaja (Codex, Cursor, Copilot, Junie)—gunakan AGENTS.md sebagai satu-satunya sumber kebenaran. (3) Pasukan campuran dengan Claude Code dan alat lain—jadikan AGENTS.md fail utama. Jika anda tiada peraturan khusus untuk Claude, CLAUDE.md boleh ditinggalkan: sejak versi 2.1.277, Claude Code membaca AGENTS.md sendiri. Jika anda mempunyai peraturan berasingan, pautkan AGENTS.md kepada CLAUDE.md melalui pautan simbolik atau import `@AGENTS.md`. Pada macOS dan Linux, namakan semula hanya apabila AGENTS.md belum wujud. Jika kedua-dua fail wujud, simpan serta gabungkan peraturan dahulu, kemudian gunakan pembalut CLAUDE.md ringkas dengan `@AGENTS.md`; jangan tindih AGENTS.md sedia ada. Pada Windows, pautan simbolik memerlukan Developer Mode, jadi lebih mudah menggunakan import.
Persoalan praktikal utamanya ialah cara menggunakan kedua-dua fail tanpa menduplikasi kandungan. Terdapat tiga senario: **Senario 1: Claude Code sahaja.** Kekalkan CLAUDE.md dan gunakan semua ciri Claude Code: `~/.claude/CLAUDE.md` untuk arahan peringkat pengguna, `CLAUDE.md` untuk projek, `CLAUDE.local.md` untuk penggantian peribadi, `@import` untuk memasukkan fail lain dan `.claude/skills/` untuk kemahiran khusus. AGENTS.md tidak diperlukan. **Senario 2: Beberapa klien pengekodan.** Simpan peraturan bersama dalam AGENTS.md, kemudian sambungkan dan sahkan setiap klien secara berasingan. Gemini CLI menyokong nama fail konteks yang dikonfigurasikan; Aider boleh memuatkan fail melalui konfigurasi pembacaannya. Ini ialah laluan pemuatan yang jelas, bukan pengesanan automatik yang sama. | Cara pemuatan | Perkara yang perlu disahkan | |----|----| | Pengesanan AGENTS.md secara automatik | Peraturan akar, fail bersarang dan keutamaan yang didokumenkan bagi klien terpasang | | Konfigurasi jelas, seperti Gemini CLI atau Aider | Nama fail/laluan bacaan yang ditetapkan serta paparan konteks yang dimuatkan dalam klien | | Pemuatan bersyarat atau import Claude Code | Versi terpasang dan keutamaan fail; lihat [panduan AGENTS.md untuk Claude Code](https://ailoot.ai/blog/ms/claude-code-agents-md-support/) | Mulakan sesi baharu dalam repositori ujian yang tidak berbahaya. Tambahkan arahan unik yang tidak berbahaya seperti “sertakan penanda instructions-loaded dalam jawapan ujian”, kemudian periksa paparan fail dimuatkan atau log yang didokumenkan oleh klien, selain jawapannya. Ulangi bagi setiap klien dan versi yang benar-benar digunakan. Dakwaan model bahawa fail telah dibaca bukan bukti bebas tentang pemuatannya; satu semakan berjaya tidak membuktikan sokongan semua alat lain. **Senario 3: Pasukan campuran (Claude Code + alat lain).** Ini persediaan yang paling lazim pada 2026. Penyelesaiannya ialah menjadikan AGENTS.md fail utama. Jika anda tiada peraturan khusus untuk Claude Code sahaja, langsung jangan cipta CLAUDE.md: sejak versi 2.1.277, Claude Code membaca AGENTS.md apabila tiada CLAUDE.md dalam projek. Jika anda mempunyai peraturan sedemikian, jadikan CLAUDE.md sama ada pautan simbolik atau pembalut pendek dengan import `@AGENTS.md`. Sebelum mengubah mana-mana fail, periksa dan sandarkan kedua-duanya. Jika kedua-duanya wujud, gabungkan arahan bersama tidak bercanggah ke AGENTS.md dan kekalkan arahan khusus Claude dalam CLAUDE.md dengan import `@AGENTS.md`. Kekalkan symlink sedia ada daripada menggantikannya. Untuk CLAUDE.md biasa **hanya apabila AGENTS.md tiada**, pengadang shell macOS/Linux ini menolak penindihan sasaran atau symlink sedia ada: ```bash if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then printf '%s\n' 'STOP: AGENTS.md exists; merge both files first.' >&2 elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md else printf '%s\n' 'STOP: inspect the existing CLAUDE.md path first.' >&2 fi ``` Selepas penamaan semula berjaya, CLAUDE.md ialah symlink kepada AGENTS.md. Semua ejen yang membaca AGENTS.md melihat kandungan yang sama. Claude Code, yang membaca CLAUDE.md, melihat kandungan yang sama melalui pautan simbolik. Pada Windows, mewujudkan pautan simbolik memerlukan Developer Mode (atau Admin), yang mungkin tidak mudah untuk seluruh pasukan. Alternatifnya ialah CLAUDE.md ringkas yang mengimport AGENTS.md: ```markdown # CLAUDE.md @AGENTS.md ## Claude Code specific - Use .claude/skills/ for specialized prompts - When working with Skills, consult .claude/skills/INDEX.md - Use Plan Mode before major changes (Shift+Tab) ``` Dalam Claude Code, sintaks ini memuatkan AGENTS.md dengan satu baris dan menambah arahan khusus Claude Code di bawahnya. Jika anda mahu membuang AGENTS.md kemudian, padam sahaja import itu. Baris ini tidak menyebabkan fail dibaca dua kali: menurut dokumentasi Claude Code, AGENTS.md yang sama tidak dimuatkan dua kali walaupun Claude Code boleh membacanya sendiri. Susun atur kanonik untuk pasukan berbilang alat pada 2026: ``` repo-root/ ├── AGENTS.md # sumber kebenaran, ≤150 baris ├── CLAUDE.md # hanya jika terdapat peraturan khusus Claude: pautan simbolik → AGENTS.md ATAU @AGENTS.md + tambahan ├── .cursor/rules/ # penggantian khusus untuk Cursor sahaja ├── .github/copilot-instructions.md # “Lihat AGENTS.md,” jika digunakan └── docs/architecture.md # seni bina terperinci yang dirujuk oleh AGENTS.md ``` Maklumat lanjut tentang CLAUDE.md terdapat dalam panduan [“Cara Mengkonfigurasi CLAUDE.md dengan Betul”](https://ailoot.ai/blog/ms/claude-md-template/). Untuk konteks lanjut tentang sebab ejen memerlukan fail arahan yang besar, baca [“Apakah Kejuruteraan Konteks”](https://ailoot.ai/blog/ms/context-engineering/). ## Apa yang Berubah pada 2026: Mengapa AAIF Membawa AGENTS.md ke Linux Foundation?
Inti utama bahagian Pada 9 Disember 2025, Linux Foundation menubuhkan Agentic AI Foundation (AAIF) dengan tiga projek pengasas: AGENTS.md daripada OpenAI, MCP daripada Anthropic dan goose daripada Block. Ahli pengasasnya ialah AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft dan OpenAI. Menjelang 24 Februari 2026, yayasan itu merangkumi 146 organisasi. Ini bermakna AGENTS.md tidak lagi menjadi “sesuatu daripada OpenAI” dan menjadi standard industri bersama MCP. Dari segi praktikal, jika anda membina produk yang sepatutnya berfungsi dengan ejen daripada vendor berbeza, meletakkan AGENTS.md pada akar projek ialah amalan asas. Tanpanya, anda akan mengekalkan tiga atau empat fail selari yang akan bercanggah dalam masa sebulan.
Kisah politik utama Mei 2026 dalam pengekodan AI bukanlah pelancaran model baharu, tetapi penyatuan format. Sebelum ini, setiap vendor mempunyai fail peraturannya sendiri, yang memudahkan vendor tetapi menyusahkan pasukan yang bekerja dengan beberapa alat. Dalam [siaran akhbar bertarikh 9 Disember 2025](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation), Linux Foundation mengumumkan Agentic AI Foundation sebagai payung untuk tiga format: - **AGENTS.md** daripada OpenAI — format fail arahan untuk ejen - **Model Context Protocol (MCP)** daripada Anthropic — protokol untuk menghubungkan alat luaran kepada ejen - **goose** daripada Block — rangka kerja ejen sumber terbuka Daripada siaran akhbar Linux Foundation: > “Menghimpunkan projek-projek ini di bawah payung AAIF memastikan projek tersebut dapat berkembang dengan ketelusan dan kestabilan yang hanya boleh disediakan oleh tadbir urus terbuka.” > > ([siaran akhbar Linux Foundation, 9 Disember 2025](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation), diterjemahkan daripada bahasa Inggeris) Menjelang 24 Februari 2026, [146 organisasi menjadi ahli AAIF](https://www.linuxfoundation.org/press/agentic-ai-foundation-welcomes-97-new-members) (97 ahli baharu dalam dua bulan). Ahli Gold baharu termasuk Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express dan Autodesk. Anthropic berada pada peringkat Platinum, mempromosikan MCP. OpenAI berada pada peringkat Platinum, mempromosikan AGENTS.md. Block berada pada peringkat Platinum bersama goose. Ini mengubah kedudukan AGENTS.md: daripada “format OpenAI” kepada standard industri. Pada musim bunga 2026, Claude Code masih berada di pinggir, tetapi pada September, dengan versi 2.1.277, ia belajar membaca AGENTS.md sendiri. CLAUDE.md masih wujud dan secara lalai tetap diberi keutamaan jika terdapat dalam projek. Titik mula yang praktikal ialah peraturan projek bersama dalam AGENTS.md, ditambah import, pembalut atau konfigurasi bacaan jelas yang diperlukan setiap klien anda. Untuk Claude Code, semak versi terpasang dan keutamaan fail arahan sebelum memutuskan sama ada import CLAUDE.md atau symlink diperlukan. Sahkan pemuatan dalam setiap klien; tiada peratusan liputan dibuktikan di sini. ## Apa Seterusnya AGENTS.md ialah blok binaan pertama dalam “cara mencapai persetujuan dengan ejen supaya ia berfungsi secara boleh dijangka”. Seterusnya ialah blok binaan kedua—folder pengetahuan projek, yang mengandungi konteks perniagaan, khalayak, produk dan harga. Blok binaan ketiga ialah [kejuruteraan konteks](https://ailoot.ai/blog/ms/context-engineering/), yang menghubungkan semuanya: fail yang dilihat ejen pada setiap langkah, cara mengekalkan keadaan antara sesi dan cara bertukar antara model berbeza. Bahan praktikal: [dokumentasi Ailoot](https://ailoot.ai/docs/).
### Sumber - [agents.md — laman rasmi standard](https://agents.md) - [Linux Foundation: penubuhan Agentic AI Foundation (9 Disember 2025)](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) - [AAIF mengalu-alukan 97 ahli baharu (24 Februari 2026)](https://www.linuxfoundation.org/press/agentic-ai-foundation-welcomes-97-new-members) - [OpenAI menjadi pengasas bersama Agentic AI Foundation](https://openai.com/index/agentic-ai-foundation/) - [GitHub Changelog: ejen pengekodan Copilot menyokong AGENTS.md (28 Ogos 2025)](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/) - [GitHub Blog: pengajaran daripada lebih 2500 repositori AGENTS.md](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/) - [Dokumentasi Claude Code: cara Claude membaca AGENTS.md](https://code.claude.com/docs/en/memory#agents-md) - [Dokumentasi garis panduan JetBrains Junie](https://junie.jetbrains.com/docs/guidelines-and-memory.html) - [Cursor Rules Docs](https://cursor.com/docs/rules)
Lebih banyak bahan dan alat: [Ailoot](https://ailoot.ai/). ## Soalan lazim: Apakah AGENTS.md dan Cara Menulisnya Sendiri dalam 30 Minit | Ailoot ### Bagaimana jika AGENTS.md dan CLAUDE.md sudah wujud? Sandarkan dan bandingkan kedua-dua fail sebelum mengubahnya. Gabungkan peraturan bersama ke AGENTS.md, kekalkan peraturan khusus Claude dalam CLAUDE.md serta tambah import @AGENTS.md; jangan namakan semula satu di atas yang lain. ### Bagaimanakah saya menjadikan arahan boleh disahkan? Tulis arahan persediaan dan ujian tepat, tentukan hasil dijangka serta nyatakan perkara yang tidak boleh diubah ejen. Pindahkan seni bina terperinci ke dokumen berpaut supaya arahan utama mudah diimbas. ## Ailoot · Syarikat dan portfolio projeknya Ailoot berteraskan pengalaman operasi yang mantap, pangkalan pelanggan yang besar, perkhidmatan yang stabil dan pemantauan KPI berterusan. Syarikat dan portfolio projeknya: jutaan pelanggan; jualan bernilai berbilion setiap bulan. Ailoot menggunakan pengalaman operasi ini untuk akses API kepada ciri AI dalam produk pelanggan, ejen, aplikasi dan automasi.