# Satu Fail Arahan untuk Claude Code, Codex dan Cursor pada 2026
> Satu sumber kebenaran untuk Claude Code, Codex dan Cursor pada 2026: bila Claude Code membaca AGENTS.md sendiri, mengimport @AGENTS.md ke dalam CLAUDE.md, pautan simbolik dan /init.
Source: https://ailoot.ai/blog/ms/agents-md-claude-md-one-instruction-file/
Canonical: https://ailoot.ai/blog/ms/agents-md-claude-md-one-instruction-file/
Language: ms
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-004
Revision: sha256-0b4433866374f59509820804bd99bc5fdf214b700e4019036348f64b4caf53d4
Untuk mendapatkan maklumat tentang perkhidmatan ini, lihat [dokumentasi Ailoot](https://ailoot.ai/docs/).
## Apakah perubahan apabila anda menggunakan Claude Code, Codex dan Cursor bersama-sama?
Inti pati utama
Pada 2026, persediaan lazim seorang vibe coder bukan satu alat, tetapi 3–5. Claude Code sebagai alat utama, Codex untuk tugasan autonomi yang panjang, Cursor untuk suntingan pantas dalam IDE. Setiap alat mempunyai fail arahannya sendiri: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`. Jika anda menyegerakkannya secara manual, anda mengedit satu baris di lima tempat, terlupa mengemas kini Cursor, kemudian seminggu selepas itu Claude dan Codex memberikan hasil berbeza untuk arahan yang sama.
Dalam contoh yang dihuraikan, Claude Code ialah alat utama, manakala Codex dan Cursor digunakan untuk tugasan tertentu. `CLAUDE.md` saya mempunyai kira-kira 250 baris arahan: perkara yang perlu dibaca dan susunannya, perkara yang tidak boleh disentuh, arahan yang perlu digunakan untuk deployment, dan peraturan pemformatan commit. Apabila saya mula-mula mencuba Codex CLI pada projek itu, ia tidak tahu apa-apa tentang peraturannya: ia menjalankan `git push --force`, mengusik `.env`, dan menamakan semula fail dengan cuai.
Mula-mula saya menyalin `CLAUDE.md` secara manual menjadi `AGENTS.md`. Dua minggu kemudian, saya mendapati projek itu sudah mempunyai empat versi arahan yang sama: dalam `CLAUDE.md`, `AGENTS.md`, `.cursorrules` dan `.windsurf/rules/`. Semuanya berbeza sedikit. Ini bukan masalah Claude atau Cursor; inilah perangkap asas bagi mana-mana sistem yang mempunyai berbilang sumber kebenaran. Saya membincangkan masalah ini dengan lebih terperinci dalam [panduan kerja berbilang ejen](https://ailoot.ai/blog/ms/claude-code-codex-together/).
Pada Jun 2026, dokumentasi memori Claude Code daripada Anthropic menawarkan satu jawapan: fail dikongsi bersama satu import. Sejak September 2026, Claude Code membaca `AGENTS.md` sendiri jika projek tidak mempunyai `CLAUDE.md`, dan import diperlukan apabila anda mempunyai peraturan khusus untuk Claude. Di bawah, saya menerangkan bila satu `AGENTS.md` sudah memadai, cara menyediakan import, dan cara memisahkan peraturan bersama daripada peraturan khusus Claude.
## Adakah Claude Code membaca AGENTS.md sendiri?
Inti pati utama
Ya, bermula dengan versi 2.1.277 yang dikeluarkan pada 18 September 2026, tetapi hanya jika tiada `CLAUDE.md`, `.claude/CLAUDE.md` atau `CLAUDE.local.md` dalam direktori kerja atau mana-mana direktori induk. Jika `CLAUDE.md` wujud, secara lalai Claude Code hanya membaca fail itu, manakala `AGENTS.md` disertakan dengan baris `@AGENTS.md` di dalam `CLAUDE.md` atau melalui pautan simbolik. Tingkah laku ini berubah dalam `/config`, di bawah Project instructions. Sebelum September, Claude Code langsung tidak membaca `AGENTS.md`, dan mengimportnya ialah satu-satunya cara.
Sebelum September 2026, jawapannya ialah “tidak.” Issue \#6235, yang meminta sokongan untuk AGENTS.md, telah dibuka sejak Ogos 2025 dan ditutup pada 17 Ogos 2026. Sepanjang tempoh itu, dokumentasi memori mencadangkan satu penyelesaian: cipta CLAUDE.md dan sertakan AGENTS.md di dalamnya sebagai import. Bermula dengan versi 2.1.277, dokumentasi menyatakan sesuatu yang berbeza:
Claude Code boleh membaca AGENTS.md sebagai arahan projek, jadi repositori yang sudah disediakan untuk ejen lain boleh berfungsi tanpa CLAUDE.md, import atau konfigurasi.
— Anthropic, https://code.claude.com/docs/en/memory#agents-md
Perkara yang dibaca oleh Claude Code bergantung tepat pada fail yang terdapat dalam projek:
| Fail dalam projek | Perkara yang dibaca oleh Claude Code |
|----|----|
| `AGENTS.md`, tanpa `CLAUDE.md` atau `CLAUDE.local.md` dalam direktori kerja atau direktori induk | `AGENTS.md` |
| `AGENTS.md` dan `CLAUDE.md` (atau `CLAUDE.local.md`) dalam direktori kerja atau direktori induk | Hanya `CLAUDE.md` |
| `CLAUDE.md` dengan baris `@AGENTS.md` | `CLAUDE.md`, serta `AGENTS.md` di dalamnya melalui import |
Untuk semakan ini, `CLAUDE.md`, `.claude/CLAUDE.md` dan `CLAUDE.local.md` dalam direktori kerja dan mana-mana direktori induk turut diambil kira. Fail peribadi `~/.claude/CLAUDE.md`, fail korporat terurus dan peraturan daripada `.claude/rules/` tidak diambil kira: semuanya dimuatkan bersama `AGENTS.md`.
Jika tiada `CLAUDE.md`, Claude Code membaca semua fail `AGENTS.md` dan `.claude/AGENTS.md` dalam direktori kerja dan direktori induk semasa permulaan, dan mengambil `AGENTS.md` dalam subdirektori apabila ia membuka fail dalam subdirektori tersebut. Import `@path` di dalam `AGENTS.md` juga berfungsi. Claude Code tidak membaca `AGENTS.local.md`, `AGENTS.override.md` atau kandungan direktori `.agents/`.
Perangkapnya: `CLAUDE.local.md` peribadi juga dikira. Jika anda menciptanya untuk menyimpan peraturan yang belum di-commit, Claude Code akan berhenti membaca `AGENTS.md` secara senyap. Tetapan di bawah ialah penyelesaiannya.
Tingkah laku ini berubah dalam `/config`, di bawah Project instructions:
| Tetapan | Perkara yang dibaca oleh Claude Code |
|----|----|
| `claude-md-or-agents-md` (lalai) | `CLAUDE.md`, atau, jika fail itu dan `CLAUDE.local.md` tiada, `AGENTS.md` |
| `claude-md-and-agents-md` | Kedua-dua fail: dalam setiap direktori, `CLAUDE.md` dahulu, kemudian `AGENTS.md` |
| `claude-md` | Hanya `CLAUDE.md` |
| `managed-only` | Hanya `CLAUDE.md` korporat terurus dan memori automatik |
Jika anda mahu mengekalkan `CLAUDE.local.md` tanpa kehilangan `AGENTS.md`, tetapkan `claude-md-and-agents-md`. Bacaan pendua tidak akan berlaku: jika `AGENTS.md` sudah disertakan melalui baris `@AGENTS.md` atau pautan simbolik, Claude Code tidak akan memuatkannya sekali lagi, tanpa mengira tetapan.
Anda boleh menyemak sama ada fail itu telah diambil menggunakan arahan `/memory`: bermula dengan versi 2.1.280, laluan ke `AGENTS.md` akan muncul dalam senarai. Dalam versi sebelum 2.1.277 dan sesi yang mematikan plugin terbina dalam `agents-md`, Claude Code hanya membaca `CLAUDE.md`, dan tiada item Project instructions dalam `/config`. Sebelum versi 2.1.281, sesi melalui Amazon Bedrock dan sesi dengan telemetri dinyahdayakan juga berkelakuan dengan cara yang sama. Dalam sesi pertama selepas mengemas kini daripada versi lebih lama, `AGENTS.md` juga mungkin tidak diambil; ia akan berfungsi mulai sesi seterusnya.
Apakah maksudnya untuk persediaan dengan satu fail? Jika anda tiada peraturan yang khusus untuk Claude, anda boleh mengetepikan `CLAUDE.md`: `AGENTS.md` sudah memadai, dan Claude Code, Codex serta Cursor akan membacanya. Jika anda mempunyai peraturan sedemikian (plan mode untuk direktori berisiko, skills, hooks), anda memerlukan `CLAUDE.md`, dan Claude Code tidak akan membaca `AGENTS.md` sendiri. Kemudian sertakan `AGENTS.md` dalam `CLAUDE.md` dengan baris `@AGENTS.md`; persediaan ini berfungsi seperti sebelum September. Ia juga membantu dengan versi Claude Code yang lebih lama. Saya menerangkannya dengan terperinci di bawah.
## Bagaimanakah cara mengimport @AGENTS.md di dalam CLAUDE.md?
Inti pati utama
Import diperlukan apabila projek mempunyai `CLAUDE.md`: apabila fail itu wujud, secara lalai Claude Code tidak membaca `AGENTS.md` sendiri. Untuk menyediakannya, tulis baris `@AGENTS.md` pada bahagian atas fail `CLAUDE.md`. Apabila Claude Code memulakan sesi, ia memasukkan kandungan `AGENTS.md` menggantikan baris itu dan membaca hasilnya sebagai satu teks. Di bawah import itu, anda boleh menambah bahagian “Claude Code” dengan peraturan yang hanya terpakai kepada Claude. Import berfungsi dengan laluan relatif dan mutlak, serta boleh bersarang sehingga empat tahap.
Contoh minimum yang berfungsi daripada dokumentasi rasmi:
```markdown
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.
```
Beginilah cara ia berfungsi. Baris pertama, `@AGENTS.md`, ialah arahan import. Apabila Claude Code menghuraikan `CLAUDE.md` pada permulaan sesi, ia menemui import ini lalu memasukkan keseluruhan kandungan `AGENTS.md` di tempatnya. Seterusnya ialah tajuk `## Claude Code`: ia hanya markdown, tetapi berfungsi sebagai bahagian “tambahan khusus Claude”. Di bawahnya terdapat peraturan yang hanya terpakai kepada Claude Code: gunakan plan mode untuk perubahan dalam direktori billing. Codex CLI dan Cursor langsung tidak membuka fail ini; kedua-duanya menggunakan `AGENTS.md` biasa.
Petikan daripada dokumentasi tentang cara import berfungsi:
Fail CLAUDE.md boleh mengimport fail tambahan menggunakan sintaks @path/to/import. Fail yang diimport dikembangkan dan dimuatkan ke dalam konteks semasa permulaan sesi bersama-sama CLAUDE.md yang merujuk kepadanya.
— Anthropic, https://code.claude.com/docs/en/memory
Beberapa butiran praktikal:
- **Laluan relatif dan mutlak.** `@AGENTS.md` adalah relatif kepada fail yang mengandungi import itu. `@/Users/me/shared/rules.md` atau `@~/.claude/personal.md` ialah laluan mutlak. Saya menggunakan `@~/.claude/personal.md` untuk pilihan peribadi yang tidak mahu saya letakkan dalam repositori.
- **Kedalaman empat tahap.** `AGENTS.md` boleh mengimport `@docs/coding-style.md`, dan `coding-style.md` boleh mengimport fail lain sehingga empat tahap. Itu mencukupi untuk apa-apa struktur sebenar.
- **Backtick menghalang import.** Jika teks menyebut `` `@README` ``, itu cuma sebutan nama, bukannya import. Ini berguna apabila menerangkan kepada pembaca cara import berfungsi tanpa mencetuskan import.
- **Kelulusan untuk fail di luar projek.** Jika import menunjuk ke luar direktori kerja, seperti `@~/.claude/personal.md`, Claude Code akan memaparkan dialog yang menyenaraikan fail tersebut buat kali pertama. Jika anda menolaknya, import luaran kekal dinyahdayakan dan dialog itu tidak akan dipaparkan lagi. `@AGENTS.md` di akar projek tidak mencetuskan dialog. Ini melindungi anda daripada memuatkan fail yang tidak berkaitan ke dalam konteks secara tidak sengaja.
Selepas beralih kepada persediaan ini dalam projek yang diterangkan, `CLAUDE.md` saya berkurang daripada 250 baris kepada 60: `@AGENTS.md` serta lima hingga tujuh peraturan yang hanya terpakai kepada Claude Code (plan mode untuk direktori berisiko, perkara yang tidak boleh dibuat dalam bahagian pentadbir, dan cara menulis commit). Semua perkara yang dikongsi berada dalam `AGENTS.md`, yang dibaca oleh Codex dan Cursor.
## Bilakah anda patut memilih pautan simbolik, dan bilakah import?
Inti pati utama
Anthropic menawarkan dua mekanisme: import melalui `@AGENTS.md` atau pautan simbolik, `ln -s AGENTS.md CLAUDE.md`. Pautan simbolik lebih mudah—ia cuma alias dan tidak memerlukan perubahan fail. Namun, ia mempunyai tiga kekurangan: Windows memerlukan keistimewaan pentadbir, anda tidak boleh menambah peraturan khusus Claude pada `CLAUDE.md`, dan Git kadangkala memaparkan pautan simbolik sebagai sampah dalam diff. Import ialah pendekatan universal. Jika anda tiada peraturan khusus Claude, bermula dengan versi 2.1.277 anda tidak memerlukan kedua-duanya: Claude Code akan membaca `AGENTS.md` sendiri.
Dokumentasi menunjukkan pilihan pautan simbolik seperti ini:
```bash
ln -s AGENTS.md CLAUDE.md
```
Dokumentasi itu kemudian memberikan amaran terus terang tentang Windows:
Jika anda atau sesiapa yang mengklon repositori bekerja pada Windows, gunakan import @AGENTS.md. Membuat pautan simbolik di sana memerlukan keistimewaan pentadbir atau Developer Mode, dan Git tanpa core.symlinks yang didayakan akan membuat checkout pautan yang di-commit sebagai fail teks biasa, lalu meninggalkan `CLAUDE.md` satu baris dan bukannya arahan dalam salinan itu.
— Anthropic, https://code.claude.com/docs/en/memory
Jadual perbandingan:
| Kriteria | Import `@AGENTS.md` | Pautan simbolik `ln -s` |
|----|----|----|
| **Berfungsi pada Windows tanpa keistimewaan pentadbir** | ya | tidak (Developer Mode diperlukan) |
| **Boleh menambah peraturan khusus Claude sahaja** | ya, di bawah import | tidak, failnya serupa |
| **Muncul dalam Git sebagai markdown biasa** | ya | sebagai pautan (bergantung pada `core.symlinks`) |
| **Boleh mengimport berbilang fail** | ya, sehingga empat tahap | tidak, satu kepada satu |
| **Caching/pembatalan kesahan dalam Claude Code** | standard untuk CLAUDE.md | berfungsi, tetapi pautan simbolik mempunyai perangkap metadata |
| **Pilihan lalai** | sesuai untuk semua | hanya jika penggunaan merentas platform tidak penting |
Saya menggunakan import dalam projek yang diterangkan. Sebabnya:
1. **Pasukan menggunakan sistem yang berbeza.** Saya menggunakan Mac; dalam contoh ini, pasukan dibahagikan kira-kira sama rata antara pengguna Windows dan Mac. Jika pautan simbolik muncul dalam repositori, bagi pengguna Windows tanpa Developer Mode, fail itu akan dibuat checkout sebagai fail teks biasa yang mengandungi satu baris, `AGENTS.md`. Ini menyebabkan pepijat pelik: kadangkala peraturan berfungsi, kadangkala tidak, dan sebabnya tidak jelas.
2. **Saya mahukan peraturan khusus Claude.** Di bawah `@AGENTS.md`, `CLAUDE.md` saya mempunyai bahagian “Claude Code” dengan peraturan: gunakan `--effort high` untuk tugasan seni bina, jalankan `npm run build` sebelum `git push`, dan jangan panggil `/api/v1/deploy` secara manual. Codex tidak memahami arahan ini.
3. **Lebih mudah untuk nyahpepijat.** Apabila berlaku masalah, saya membuka `CLAUDE.md` dan melihat import serta penggantian saya. Pautan simbolik tidak menyatakan “ini telah ditambah di sini”. Untuk maklumat lanjut tentang nyahpepijat tetapan Claude Code, lihat [panduan mod selamat](https://ailoot.ai/blog/ms/claude-code-safe-mode-recovery/).
Jika anda tiada peraturan khusus Claude, pautan simbolik tidak lagi diperlukan bermula dengan versi 2.1.277: padamkan `CLAUDE.md`, dan Claude Code akan membaca `AGENTS.md` sendiri. Kekalkan pautan simbolik hanya jika seseorang dalam pasukan menggunakan versi lebih lama daripada 2.1.277 dan tidak boleh mengemas kini. Jika anda mempunyai peraturan khusus Claude, import lebih mudah dalam sembilan daripada sepuluh keadaan.
## Apakah yang dibaca oleh Codex, Cursor, Copilot, Windsurf dan Gemini CLI?
Inti pati utama
Setiap alat membaca failnya sendiri, kadangkala lebih daripada satu. Claude Code membaca `CLAUDE.md` dan, sejak September 2026, turut membaca `AGENTS.md` jika projek tidak mempunyai `CLAUDE.md`. Codex CLI membaca `AGENTS.md` serta `AGENTS.override.md`. Cursor membaca format lama `.cursorrules` atau `.cursor/rules/*.mdc` yang lebih baharu, dan sejak musim panas 2026 turut membaca `AGENTS.md`. Copilot membaca `.github/copilot-instructions.md` atau `.github/instructions/*.instructions.md`. Windsurf membaca `.windsurfrules` yang lama atau `.windsurf/rules/` yang baharu. Gemini CLI membaca `GEMINI.md`. Aider dan Cline sudah menerima pakai `AGENTS.md`.
Peta tujuh alat utama (berdasarkan dokumentasi rasmi setiap alat):
| Alat | Fail arahan utama | Alternatif | Membaca AGENTS.md? |
|----|----|----|----|
| **Claude Code** | `CLAUDE.md` | `~/.claude/CLAUDE.md`, `./.claude/CLAUDE.md`, dasar terurus | ya, jika projek tidak mempunyai `CLAUDE.md` (sejak 2.1.277), selain itu melalui import |
| **Codex CLI** (OpenAI) | `AGENTS.md` | `AGENTS.override.md` | ya (secara natif) |
| **Cursor** | `.cursor/rules/*.mdc` | `.cursorrules` (ditamatkan) | ya |
| **GitHub Copilot** | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | melalui sambungan |
| **Windsurf** | `.windsurf/rules/` | `.windsurfrules` (ditamatkan) | ya |
| **Gemini CLI** | `GEMINI.md` | \- | tidak |
| **Aider, Cline, opencode** | `AGENTS.md` | \- | ya (secara natif) |
Apakah kesimpulannya? Jika repositori mempunyai `AGENTS.md` (serta `CLAUDE.md` dengan import apabila peraturan khusus Claude diperlukan), lima daripada tujuh alat mendapat arahan terkini secara automatik. Cursor dan Windsurf, yang mempunyai fail natif sendiri, boleh dibiarkan seperti sedia ada (`AGENTS.md` juga dibaca oleh kedua-duanya) atau boleh ditambah import `@AGENTS.md`—tetapi sintaksnya berbeza dan tidak sentiasa disokong.
Strategi paling ringkas untuk projek baharu:
1. **Letakkan semua peraturan bersama dalam `AGENTS.md`**—95% peraturan sepatutnya berada di situ.
2. **Cipta `CLAUDE.md` jika anda memerlukan peraturan khusus Claude:** letakkan `@AGENTS.md` pada baris pertama, kemudian tambah bahagian yang mengandungi peraturan khusus Claude sahaja. Jika tiada peraturan sedemikian, `CLAUDE.md` tidak diperlukan; Claude Code telah membaca `AGENTS.md` sendiri sejak versi 2.1.277.
3. **Kekalkan `.cursor/rules/` untuk Cursor** bagi kes jarang apabila sesuatu yang khusus untuk Cursor diperlukan (arahannya `@Codebase` dan `@Docs`).
4. **Lakukan perkara yang sama untuk Windsurf:** lupakan `.windsurfrules` lama; gunakan `.windsurf/rules/` yang baharu hanya apabila anda memerlukan corak untuk sintaksnya.
Pendekatan ini memberikan 80% manfaat dengan 20% usaha. Berdasarkan pengalaman saya, apabila menyusun pasukan bercampur dalam “Antigravity”, mengekalkan lebih daripada dua sumber kebenaran (bersama dan khusus Claude) menjadi sukar. Jika seseorang dalam pasukan menambah peraturan pada `.cursorrules` dan terlupa tentang `AGENTS.md`, seminggu kemudian Cursor dan Codex akan bercanggah.
## Bagaimanakah /init dalam Claude Code mengambil AGENTS.md yang sedia ada?
Inti pati utama
`/init` membina `CLAUDE.md` daripada kandungan yang sudah ada dalam repositori dan menjimatkan 20–30 minit kerja manual. Secara lalai, ia mengambil peraturan Cursor (`.cursor/rules/`, `.cursorrules`) dan Copilot (`.github/copilot-instructions.md`), manakala `AGENTS.md`, `.windsurfrules` dan `.clinerules` dibaca dalam mod `CLAUDE_CODE_NEW_INIT=1`. Mod yang sama memulakan aliran interaktif berbilang fasa: ia bertanya soalan, meneroka kod melalui subagent dan mencadangkan pelan sebelum menulis. Sejak September 2026, `/init` mempunyai satu kelemahan dalam projek yang mengandungi `AGENTS.md`: `CLAUDE.md` baharu akan menyahdayakan bacaan terus `AGENTS.md`, lalu peraturan berakhir dalam dua fail.
Anthropic menerangkan `/init` begini dalam dokumentasinya:
Menjalankan /init membaca fail arahan alat lain dan memindahkan bahagian yang berkaitan ke dalam CLAUDE.md yang dijana: peraturan Cursor daripada `.cursor/rules/` atau `.cursorrules`, peraturan Copilot daripada `.github/copilot-instructions.md`, dan, dengan CLAUDE_CODE_NEW_INIT=1, turut membaca AGENTS.md, `.devin/rules/`, `.windsurf/rules/` atau `.windsurfrules`, serta `.clinerules`.
— Anthropic, https://code.claude.com/docs/en/memory
Apakah maksudnya dalam amalan? Repositori yang saya terangkan mempunyai `.cursorrules` daripada masa saya mencuba Cursor (kira-kira 80 baris), dan `AGENTS.md` (120 baris, disusun secara manual). Apabila saya menjalankan `claude /init`, arahan itu mengambil kedua-dua fail, membuang peraturan yang serupa dan menyusun `CLAUDE.md` yang kemas dalam masa seminit. Saya menyemaknya selepas itu dan membuat sedikit suntingan—membuang item lapuk dan menambah struktur dengan tajuk. Ini lebih pantas daripada menulis semula dari awal.
Mod interaktif, yang membolehkan `/init` turut membaca `AGENTS.md`, didayakan melalui pemboleh ubah persekitaran:
```bash
CLAUDE_CODE_NEW_INIT=1 claude
```
Selepas `/init` bermula, Claude akan mengemukakan beberapa soalan penjelasan: artifak yang hendak dikonfigurasi (`CLAUDE.md`, skills, hooks), stack yang digunakan projek dan arahan yang digunakan untuk ujian. Kemudian subagent meneroka pangkalan kod—membaca `package.json`, `README.md` dan fail konfigurasi—lalu mengisi bahagian yang belum lengkap. Pada akhirnya, ia memaparkan cadangan yang boleh anda sunting sebelum menyimpannya. Untuk maklumat lanjut tentang mengkonfigurasi Claude Code ketika memulakan projek, lihat [panduan berasingan](https://ailoot.ai/blog/ms/spec-kit-claude-code-spec-driven-development/).
Kini tentang kelemahannya. Jika projek sudah mempunyai `AGENTS.md` yang aktif, `/init` akan mencipta `CLAUDE.md` di sebelahnya yang mengandungi salinan peraturannya. Mulai saat itu, secara lalai Claude Code hanya membaca `CLAUDE.md`, jadi terdapat dua sumber kebenaran sekali lagi: anda mengemas kini `AGENTS.md`, sementara Claude terus menggunakan salinan lama. Arahan `/import` melakukan sesuatu yang serupa: ia menambah salinan sekali sahaja daripada `AGENTS.md` kepada `CLAUDE.md`. Untuk mengekalkan satu sumber, letakkan import `@AGENTS.md` pada baris pertama `CLAUDE.md` selepas `/init`, dan buang apa-apa daripada `CLAUDE.md` yang mengulangi kandungan `AGENTS.md`.
`/init` ialah titik permulaan yang sesuai untuk projek baharu atau projek yang anda pindahkan daripada Cursor atau Copilot. Tidak perlu mencari dalam talian untuk “templat CLAUDE.md terbaik”—Anthropic sudah mengambil kira kandungan repositori. Jika projek sudah mempunyai `AGENTS.md` yang aktif dan tiada peraturan khusus Claude, `/init` tidak diperlukan: Claude Code akan membaca `AGENTS.md` sendiri.
## Bagaimanakah cara memisahkan arahan bersama daripada arahan khusus Claude?
Inti pati utama
Letakkan peraturan yang boleh difahami oleh mana-mana ejen AI dalam `AGENTS.md`: perkara yang tidak boleh disentuh, cara menamakan branch, bahawa `.env` mengandungi rahsia, dan arahan yang digunakan untuk ujian. Letakkan peraturan khusus Claude Code dalam `CLAUDE.md` (di bawah import): plan mode, skills, hooks, rujukan skill dan nama model mengikut versi. Perbezaannya mudah: jika peraturan bermula dengan “Claude patut,” letakkannya dalam `CLAUDE.md`. Jika bermula dengan “alat patut,” letakkannya dalam `AGENTS.md`.
Saya memisahkannya berdasarkan prinsip ini. Peraturan bersama yang diletakkan dalam `AGENTS.md`:
- **Perkara yang tidak boleh disentuh dalam kod.** Folder `.env`, `node_modules`, `prisma/migrations` (hanya melalui `prisma migrate`), `.next/`, `.git/`.
- **Cara menamakan perkara.** Branch: `feat/`, `fix/`, `chore/`. Commit: awalan `feat:`, `fix:`, `docs:` diikuti penerangan ringkas. Fail komponen dalam `kebab-case`.
- **Arahan ujian/lint.** `npm run build`, `npm run lint`, `npm test`. Arahan yang perlu dijalankan sebelum `git push`.
- **Prinsip seni bina.** Perkara yang diletakkan dalam `src/lib/`, perkara yang diletakkan dalam `src/components/`, tempat logik perniagaan berada dan tempat UI berada.
- **Keselamatan.** Jangan sekali-kali commit rahsia. Akses pangkalan data production hanya melalui `prod-psql`. Akses production melalui SSH hanya menggunakan alias `prod`, bukan `root@IP`.
Peraturan khusus Claude yang diletakkan dalam `CLAUDE.md` (di bawah `@AGENTS.md`):
- **Plan mode.** Gunakan `plan mode` untuk perubahan dalam direktori berisiko (contohnya, `src/billing/`).
- **Tahap usaha.** Gunakan `--effort high` untuk tugasan seni bina dan `medium` untuk kerja rutin.
- **Skills.** Ejen AI dan skills yang perlu dijalankan dalam situasi tertentu. Contohnya: “apabila bekerja pada panduan, jalankan skill `build-masterskaya-guide`.”
- **Memori Claude.** Perkara yang perlu dimasukkan ke dalam memori automatik dan perkara yang perlu diletakkan dalam `CLAUDE.local.md`. Untuk maklumat lanjut tentang memori Claude, lihat [panduan Memory dan CLAUDE.md](https://ailoot.ai/blog/ms/claude-memory-claude-md-auto-memory/).
- **Hooks.** Jika `.claude/settings.json` mempunyai hooks yang dikonfigurasi, terangkan fungsinya dalam `CLAUDE.md` (Codex dan Cursor tidak mengetahuinya dan tidak perlu mengetahuinya).
- **Skills dan arahan.** Senarai arahan garis miring yang kerap saya gunakan (`/init`, `/cd`, `/memory`, `/plan`).
Sempadannya tidak semestinya jelas. Contohnya, “jangan sekali-kali jalankan `git push --force` ke `main`” jelas merupakan peraturan bersama, jadi ia diletakkan dalam `AGENTS.md`. Tetapi “apabila menjalankan `git push` ke branch hot, gunakan plan mode dahulu” khusus kepada Claude Code, jadi ia diletakkan dalam `CLAUDE.md`. Uji dengan bertanya: “Jika saya membuang Claude Code esok dan hanya mengekalkan Codex, adakah peraturan ini masih terpakai?” Jika ya, letakkannya dalam `AGENTS.md`. Jika tidak, letakkannya dalam `CLAUDE.md`.
## Apakah yang patut diletakkan dalam AGENTS.md, dan apakah yang patut diletakkan dalam CLAUDE.md atau .claude/rules?
Inti pati utama
Untuk projek besar, satu `AGENTS.md` tidak mencukupi—fail itu menjadi terlalu besar, dan setiap ejen membawa bahan yang tidak diperlukan ke dalam konteksnya. Penyelesaiannya ialah direktori `.claude/rules/` dengan fail berasingan mengikut topik dan YAML frontmatter `paths:` untuk pencetus berdasarkan laluan. Contohnya, peraturan API hanya terpakai apabila Claude bekerja dalam `src/api/`. Ini menjimatkan banyak ruang tetingkap konteks. Padanan untuk Cursor ialah `.cursor/rules/`, manakala untuk Windsurf ialah `.windsurf/rules/`.
Jika peraturan melebihi 200 baris, sudah tiba masanya untuk memecahkannya. Dokumentasi Anthropic mengesyorkan sasaran 200 baris bagi setiap fail, kerana fail `CLAUDE.md` yang panjang menyebabkan Claude kurang mematuhi arahan secara senyap: nampaknya ia membacanya, tetapi ia semakin jarang mengikutinya.
Struktur untuk projek besar yang berkesan bagi saya:
```
my-project/
├── AGENTS.md # 100-150 lines, shared
├── CLAUDE.md # 30-50 lines: @AGENTS.md + Claude-only
└── .claude/
├── CLAUDE.md # alternative to root file, same file
└── rules/
├── api.md # with paths: ['src/api/**']
├── components.md # with paths: ['src/components/**']
├── testing.md # without paths, always active
└── security.md # without paths, always active
```
Setiap fail dalam `.claude/rules/` boleh mempunyai frontmatter:
```markdown
---
paths:
- "src/api/**/*.ts"
---
# API rules
- Every endpoint validates input with zod
- Errors use the standard `{error, code}` format
- OpenAPI comments are required
```
Claude memuatkan peraturan ini hanya apabila bekerja dengan fail yang sepadan dengan corak tersebut. Jika ia menyentuh `src/components/Button.tsx`, peraturan API tidak ditambah ke dalam konteks. Dengan cara ini, tetingkap konteks hanya digunakan untuk perkara yang relevan. Direktori `.claude/rules/` juga berfungsi tanpa `CLAUDE.md`: jika projek hanya mengandungi `AGENTS.md`, peraturannya dimuatkan bersama fail itu dan tidak menyahdayakan bacaan terus `AGENTS.md`.
Cursor dan Windsurf menyokong pendekatan yang sama melalui direktori `.cursor/rules/` dan `.windsurf/rules/`. Piawaian AGENTS.md boleh merujuk kepada direktori ini, tetapi sintaks merentas alat masih belum stabil sepenuhnya. Lebih selamat untuk mengekalkan peraturan bersama dalam `AGENTS.md` dan menggandakan peraturan berskop laluan dalam `.claude/rules/` dan `.cursor/rules/`—ini kes khusus yang jarang berlaku, bukannya sebahagian besar peraturan.
Lokasi berguna untuk CLAUDE.md (mengikut susunan daripada paling luas kepada paling khusus):
| Tahap | Lokasi | Tujuan |
|----|----|----|
| **Dasar terurus** | `/Library/Application Support/ClaudeCode/CLAUDE.md` (Mac), `/etc/claude-code/CLAUDE.md` (Linux) | Peraturan korporat, IT/DevOps |
| **Pengguna** | `~/.claude/CLAUDE.md` | Pilihan peribadi merentas semua projek |
| **Projek** | `./CLAUDE.md` atau `./.claude/CLAUDE.md` | Peraturan pasukan projek |
| **Tempatan** | `./CLAUDE.local.md` (dalam `.gitignore`) | Pilihan peribadi untuk projek tertentu |
Contoh `~/.claude/CLAUDE.md` mungkin mengandungi dua peraturan: “balas dalam bahasa pilihan pengguna” dan “eja Ailoot tepat seperti ini.” Peraturan ini terpakai kepada setiap projek, jadi tidak perlu menggandakannya dalam setiap repositori.
Daripada empat tahap ini, hanya `CLAUDE.md` peringkat projek dan `CLAUDE.local.md` menyahdayakan bacaan terus `AGENTS.md`. `~/.claude/CLAUDE.md` peribadi dan dasar terurus tidak menghalangnya; Claude Code membaca kedua-duanya bersama `AGENTS.md`.
## Apakah yang patut anda lakukan jika AGENTS.md sudah lapuk dalam projek anda?
Inti pati utama
Jika `AGENTS.md` disusun pada 2025 untuk Codex atau Aider dan tidak diedit sejak itu, buka projek dalam Claude Code dan minta Claude mengedit fail tersebut. AGENTS.md ialah dokumen yang sentiasa berkembang; spesifikasi Linux Foundation dikemas kini. Peraturan utama untuk memastikan kandungannya terkini: setiap peraturan mesti menjawab soalan “Apakah yang saya sudah bosan mengulang kepada Claude/Codex?” Jika tidak, arkibkannya.
Dalam projek yang saya huraikan, saya mempunyai `AGENTS.md` dari Mei 2025—180 baris, banyak daripadanya sudah lapuk (ia menyebut endpoint Anthropic API yang telah berubah sejak itu; contoh sintaks `claude --tools` yang tidak lagi wujud; dan peraturan mengenai `~/.claude/projects/` dengan struktur yang sudah lapuk).
Pelan yang saya gunakan untuk mengemas kininya:
1. **Semak dengan `claude` dalam plan mode.** Saya membuka repositori, menjalankan `claude --safe-mode`, dan meminta: “Baca semula `AGENTS.md` dan cadangkan senarai item yang sudah lapuk atau berulang. Jangan editnya; senaraikan sahaja.” Dalam masa dua minit, saya mendapat senarai 23 item untuk disemak.
2. **Buang item yang jelas sudah lapuk.** Daripada 23 item, 9 memang sudah lapuk—sintaks arahan, endpoint dan nama flag. Saya memadamkan baris tersebut.
3. **Gabungkan pendua.** Enam item lain mengulangi perkara yang sama dengan kata-kata berbeza (“jangan buat force-push,” “jangan sekali-kali gunakan `--force`,” “elakkan `git push -f`”). Saya menggabungkannya menjadi satu baris.
4. **Tambah item baharu.** Saya menambah perkara yang saya perhatikan sering dilakukan dengan salah oleh Claude/Codex sepanjang bulan lalu, berdasarkan peraturan “satu baris bagi setiap corak kesilapan”. Hasilnya ialah 8 item baharu.
5. **Minta subagent membuat semakan akhir.** Saya meminta Claude menyemak dengan arahan “cari percanggahan, kekaburan dan pendua.” Ia menemui tiga frasa yang boleh diperjelas. Saya membetulkannya.
Selepas sejam, `AGENTS.md` mempunyai 110 baris, terkini, dan saya mengenali setiap baris secara peribadi. Mudah untuk membina `CLAUDE.md` sepanjang 30 baris daripadanya. Codex juga menjadi jauh lebih berhati-hati dengan ujian selepas itu—saya mengesyaki beberapa keputusannya yang “pelik” berpunca daripada arahan lapuk yang dipatuhinya dengan niat baik.
Prinsip utama untuk `AGENTS.md` yang sentiasa berkembang:
- **Setiap peraturan menjawab kesilapan berulang.** Jika saya tidak teringat tentang sesuatu peraturan walaupun sekali sepanjang bulan itu, tidak ada gunanya mengekalkannya.
- **Tulis peraturan sebagai arahan, bukan teori.** “Gunakan dua ruang” ialah peraturan. “Gaya kod patut kemas” bukan.
- **Perincian mengatasi keumuman.** “Jalankan `npm run build` sebelum `git push`” ialah peraturan. “Uji perubahan anda” bukan.
## Apakah yang sememangnya TIDAK berfungsi dengan persediaan ini?
Inti pati utama
Mengimport `@AGENTS.md` tidak menjadikan alat yang berbeza berkelakuan seperti satu alat. Setiap alat mempunyai keistimewaan tersendiri: Codex CLI tidak mengetahui `.claude/rules/` atau hooks. Cursor mempunyai enjin autolengkap tersendiri, yang tidak membaca CLAUDE.md semasa melengkapkan teks. Copilot mengikuti `.github/copilot-instructions.md`, dan peraturan dalam AGENTS.md sahaja tidak mencukupi baginya. Ini bukan “satu fail = satu tingkah laku”; sebaliknya, “satu sumber bagi peraturan asas, kemudian setiap alat mempunyai tambahannya sendiri.”
Beberapa perkara yang saya pelajari dengan cara yang sukar sepanjang enam bulan bekerja menggunakan persediaan ini:
**1. Autolengkap Cursor tidak menggunakan AGENTS.md.** Apabila Cursor mencadangkan pelengkapan baris dalam editor, ia tidak membaca `AGENTS.md` dalam masa nyata—ada enjin pantas yang berasingan. Peraturan dalam AGENTS.md hanya penting apabila anda membuat permintaan dalam sembang Cursor. Ini bermakna menulis “jangan gunakan `var`, gunakan `const`” dalam AGENTS.md tidak akan mempengaruhi autolengkap; anda perlu mengkonfigurasikannya melalui ESLint atau konfigurasi TypeScript.
**2. Hooks Claude Code dalam AGENTS.md tidak berfungsi untuk Codex.** Jika `.claude/settings.json` mempunyai hook PreToolUse yang dikonfigurasi untuk menyekat tindakan tertentu, maklumat itu hanya berguna untuk Claude. Codex tidak tahu tentang hooks; baginya, “alat itu membuat keputusan sendiri.” Wajar untuk menulis “jangan buat X” dalam `AGENTS.md`, dan “terdapat hook yang menyekat X secara fizikal” dalam `CLAUDE.md` di bawah import.
**3. Copilot dan `.github/copilot-instructions.md`.** GitHub Copilot membaca failnya sendiri dan masih tidak membaca AGENTS.md dengan begitu baik. Jika pasukan anda aktif menggunakan Copilot, sama ada tambahkan `.github/copilot-instructions.md` berasingan dengan versi ringkas peraturan itu, atau gunakan [Copilot Extensions](https://github.com/marketplace?type=apps&category=copilot-extensions) yang mengetahui tentang AGENTS.md. Perkara ini berubah dengan pantas, jadi keadaannya mungkin berbeza dalam masa tiga hingga enam bulan.
**4. Git tidak menjejak pautan simbolik sebagai perubahan CLAUDE.md.** Jika anda menjalankan `ln -s AGENTS.md CLAUDE.md` dan mengemas kini `AGENTS.md` seminggu kemudian, Git hanya akan menunjukkan diff untuk `AGENTS.md`. Itu perkara biasa, tetapi rakan sekerja yang menyemak PR mungkin tidak sedar bahawa `CLAUDE.md` juga telah dikemas kini (melalui pautan simbolik). Penyelesaian: nyatakan secara jelas dalam huraian PR, “`AGENTS.md` dikemas kini; Claude Code melihat fail yang sama melalui pautan simbolik.”
**5. Import bersarang dalam-dalam sukar dinyahpepijat.** Jika `AGENTS.md` mengimport `@docs/coding-style.md`, yang mengimport `@docs/typescript.md`, dan terdapat peraturan yang bercanggah, penyahpepijatan sukar dilakukan. Saya mengehadkan import kepada satu tahap (`CLAUDE.md` → `AGENTS.md`) dan tidak menyarangnya lebih jauh. Anthropic menyediakan hook `InstructionsLoaded` yang merekod fail yang dimuatkan—berguna untuk menyahpepijat persediaan berlapis. Nota: hook ini dicetuskan untuk `AGENTS.md` yang disertakan melalui import atau pautan simbolik, tetapi bukan untuk `AGENTS.md` yang dibaca sendiri oleh Claude Code.
### Sumber
- [Dokumentasi Claude Code Memory — bahagian AGENTS.md](https://code.claude.com/docs/en/memory#agents-md) — bila Claude Code membaca AGENTS.md sendiri, tetapan Project instructions, import dan pautan simbolik, serta tingkah laku `/init`.
- [Dokumentasi Claude Code Memory — mengimport fail tambahan](https://code.claude.com/docs/en/memory#import-additional-files) — sintaks `@path/to/file`, kedalaman empat tahap, laluan relatif dan mutlak.
- [agents.md — piawaian Linux Foundation](https://agents.md/) — piawaian rasmi AGENTS.md dan senarai alat yang menyokongnya.
- [Dokumentasi Peraturan Cursor](https://docs.cursor.com/context/rules-for-ai) — perkara yang dibaca oleh Cursor (`.cursor/rules/*.mdc`, AGENTS.md).
- [Arahan Tersuai GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) — format `.github/copilot-instructions.md`.
- [Spesifikasi AGENTS.md di Linux Foundation](https://aaif.io/projects/agents-md/) — spesifikasi yang sentiasa dikemas kini.
Persediaan vibe coding lengkap untuk satu malam: **klon AI + Second Brain + kejuruteraan konteks**.
Kenali [Ailoot](https://ailoot.ai/).
## Soalan lazim: Satu Fail Arahan untuk Claude Code, Codex dan Cursor pada 2026
### Bilakah import patut digunakan berbanding symlink?
Gunakan `@AGENTS.md` dalam `CLAUDE.md` apabila memerlukan tambahan khusus Claude atau rakan pasukan menggunakan Windows. Symlink menjadikan kedua-dua nama merujuk kandungan sama, maka tidak boleh menyimpan bahagian Claude sahaja yang berasingan.
### Bagaimanakah saya memeriksa arahan bersama telah dimuatkan?
Jalankan `/memory` dan periksa fail arahan tersenarai. Jika `CLAUDE.md` atau `CLAUDE.local.md` menyekat pemuatan langsung AGENTS.md dalam konfigurasi anda, tambah import atau pilih tetapan yang memuatkan kedua-duanya, kemudian mulakan sesi baharu.
## 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.