Sakit Kepala: Kenapa AI Selalu Gagal Di Tempat Yang Sama

Pembangun yang guna Cursor, Windsurf atau Claude Code mesti pernah rasa macam nak hempas laptop: AI hantar blok kod panjang, anda copy-paste, run — build error, test merah,依赖 salah letak. Masalahnya bukan bodoh, tapi AI langsung tak tahu “peraturan tak tertulis” projek anda.

AGENTS.md ialah fail Markdown dalam root direktori projek, ditulis khusus untuk AI — beritahu dia cara build, cara test, patuh gaya kod mana. README.md untuk manusia, penuh dengan intro projek, garis panduan kontribusi, cerita brand. AI baca semua tu macam pekerja baru hari pertama masuk ofis, dikepil buku promosi syarikat, lepas tu disuruh tulis kod terus — dia tahu syarikat buat apa, tapi tak tahu command build, tak tahu test jalan macam mana, tak tahu rule ESLint apa. Setiap kali kena betulkan dalam chat: “Guna pnpm, bukan npm”, “Test dalam packages/web“, “Jangan lupa run lint”. Betulkan seratus kali, projek tetap bersepah.

Dalam konteks ambil kerja freelance, kerugian lagi terus: anda dapat projek Next.js + Prisma, guna Cursor untuk pecut, tapi AI install依赖 guna npm, konfigurasi workspace pnpm rosak; dia tak tahu schema database kat mana, fail migration yang dijana terus error. Klien催促 serahan, anda habiskan tiga jam debug kod yang AI tulis — duit yang赚 memang menyakitkan hati.

3 senario tipikal AI langgar peraturan projek: ① Pengurus pakej salah (projek guna pnpm, AI default npm install),依赖安装 kat tempat salah, konfigurasi workspace失效; ② Pintu masuk test tak jumpa (test projek kat packages/web, AI run pnpm test kat root, dapat “fail test tak dijumpai”); ③ Gaya kod tak seragam (projek guna ESLint + Prettier, kod yang AI jana缩进、petik semua salah, CI terus merah).

Peluang: AGENTS.md Asingkan “Dokumen Manusia” Dengan “Dokumen Mesin”

Projek sumber terbuka AGENTS.md di GitHub (repo github.com/agentsmd/agents.md, sehingga 2026-08-25 lebih kurang 24 ribu stars) selesaikan masalah ni. Idea dia senang gila: letak satu fail Markdown dalam root projek, beritahu AI cara build, cara test, patuh gaya kod mana.

Ni bukan ganti README, tapi pelengkap. README untuk penyumbang manusia, AGENTS.md untuk ejen AI. Dua-dua ada tugas jelas, tak ganggu satu sama lain.

Menurut帖子 asal, AGENTS.md dah diguna pakai oleh puluhan ribu projek sumber terbuka (angka tepat待核), meliputi VS Code, Cursor, Windsurf, Aider, GitHub Copilot dan alat pengekodan AI arus perdana lain (kesimpulan disahkan); maklum balas komuniti kata OpenAI Codex, Google Jules juga sokong (⚠️belum disahkan). Kalau anda tak belajar sekarang, bermakna anda biar AI bercakap loghat Kelantan dengan anda.

Laluan Satu: Tulis AGENTS.md Minimum Sendiri

Kos sangat rendah. Cipta fail baru, tulis tiga perenggan dah cukup.

Asas yang perlu tahu: contoh bawah guna pnpm (jimat cakera berbanding npm, sokong monorepo workspace), turbo ialah alat orkestrasi tugasan monorepo, parameter --filter tentukan hanya satu sub-pakej terkesan, elak kesan keseluruhan repo.

Perenggan pertama “Dev environment tips”: beritahu AI projek guna pengurus pakej apa, cara lompat ke sub-pakej, cara cipta modul baru. Contoh dari官方:

• pnpm dlx turbo run where <project_name> — terus lompat ke direktori sub-pakej tertentu, tak payah ls satu-satu
• pnpm install --filter <project_name> — install依赖 satu sub-pakej je, tak sentuh keseluruhan monorepo
• pnpm create vite@latest <project_name> -- --template react-ts — cipta sub-pakej React + Vite dengan semakan TypeScript

Perintah ni AI tak boleh teka sendiri, tapi bila anda tulis, dia ikut.

Perenggan kedua “Testing instructions”: beritahu AI cara run test, pelan CI kat mana, check apa yang wajib run sebelum commit. Contoh官方:

• pnpm turbo run test --filter <project_name> — run semua check untuk sub-pakej tertentu
• pnpm vitest run -t "<test name>" — run satu test je yang匹配 nama tu
• “Fix any test or type errors until the whole suite is green” — tak hijau semua tak boleh berhenti
• “Add or update tests for the code you change, even if nobody asked” — ayat ni关键, kalau tak tulis AI selalu malas tulis test

Perenggan ketiga “PR instructions”: piawai format tajuk commit,强制 run lint dan test. Contoh官方 Title format: [<project_name>] <Title>, dan “Always run pnpm lint and pnpm test before committing”.

Tiga perenggan ni bawah 50 baris, tapi kadar kejayaan kod AI yang dijana melonjak naik (ikut maklum balas komuniti, angka tepat待核).

Laluan Dua: Guna Bersarang Dalam Monorepo Besar

Kalau anda ambil projek企业级, codebase struktur monorepo (banyak projek berkaitan dalam satu repo Git, cth depan, belakang, kod kongsi masing-masing satu subdirektori), satu AGENTS.md tak cukup. AGENTS.md sokong bersarang: letak satu AGENTS.md khusus dalam setiap subdirektori, AI自动 baca “yang paling dekat”.

Cara praktikal: AGENTS.md root tulis piawai全局 (pengurus pakej, aliran CI, nota keselamatan), lepas tu dalam packages/web/, packages/api/, packages/shared/ masing-masing letak satu, tulis command build khusus, pintu masuk test, kebergantungan khas untuk sub-pakej tu. Cth pakej depan kena tulis “pustaka komponen guna shadcn, gaya guna Tailwind, ikon guna lucide-react”; pakej belakang kena tulis “migration database guna Prisma, laluan API kat src/routes, pengesahan guna JWT”.

AI yang kerja dalam subdirektori akan自动 muat naik AGENTS.md yang paling dekat, keutamaan lebih tinggi dari root. Maksudnya dalam projek yang sama, pembantu AI depan dan belakang boleh dapat arahan yang完全不同, tak campur aduk.

Laluan Tiga: Jadikan Senjata Pembezaan Dalam Kerja Freelance

Pasaran kerja AI sekarang dah jadi padang pasir merah — semua orang tahu guna Cursor, tapi kualiti serahan tak sama. Kalau dalam kertas cadangan anda boleh tulis satu ayat “Projek ini dah konfigurasikan dokumen piawai AGENTS.md, pembangunan berbantukan AI patuh piawai projek”, kadar menang tawaran akan lebih tinggi dari mereka yang cuma cakap “saya guna AI tulis kod”.

Taktik khusus: lepas dapat kerja, habiskan 30 minit baca struktur projek klien, lepas tu tulis AGENTS.md yang di sesuaikan. Dokumen ni sendiri jadi sebahagian dari serahan — klien dapat, masa depan mereka sendiri guna AI untuk selenggara kod pun lagi lancar.

Letak harga perkhidmatan konfigurasi AGENTS.md secara berasingan (rujuk tawaran, perlu ikut pasaran tempatan): versi asas RM350 (konfigurasi satu fail + satu README penjelasan), versi企业 RM1800 (monorepo bersarang + piawai keselamatan + latihan pasukan). Senarai serahan: ① Fail AGENTS.md tersuai ② Jawab soalan 30 hari melalui WhatsApp ③ Satu rakaman latihan 10 minit. Sesuai untuk: klien dah ada langganan Cursor/Windsurf tapi tak dapat hasil. Tak sesuai: klien masih guna pembangunan manual sepenuhnya, belum perkenalkan alat AI.

Kajian Kes: Benteng Keserasian AGENTS.md

AGENTS.md guna lesen MIT (pakej素材 disahkan), diselenggara komuniti (struktur tadbir urus tepat待核), laman rasmi agents.md.

Keserasian ialah benteng terbesar: kesimpulan disahkan VS Code, Cursor, Windsurf, Aider, GitHub Copilot semua sokong baca AGENTS.md; maklum balas komuniti kata OpenAI Codex, Claude Code, Gemini CLI, Google Jules juga sokong (⚠️belum disahkan). Maksudnya satu fail yang anda tulis, pembantu AI arus perdana semua boleh guna — tak payah tulis konfigurasi berasingan untuk setiap alat.

Banding dengan penyelesaian lain: .cursorrules Cursor hanya生效 untuk Cursor, tukar Windsurf terus失效; CLAUDE.md Claude Code hanya untuk Claude; sistem arahan GitHub Copilot lain pula. Ciri “tulis sekali, jalan di mana-mana” AGENTS.md ialah sebab utama ia cepat diterima pakai.

Kos migrasi alat jadi sifar. Hari ini guna Cursor, esok tukar Windsurf, AGENTS.md terus boleh pakai, tak payah tulis semula.

Seruan Tindakan: Malam Ni Pun Letak Manual Mesin Dalam Projek

Senarai tindakan 5 minit: ① Buka root direktori projek ② Cipta AGENTS.md ③ Salin templat官方 (github.com/agentsmd/agents.md) ④ Isi tiga perintah (build, test, lint) ⑤ Perhatikan kesan bila suruh AI tulis kod kali depan.

Kalau guna monorepo, malam ni habiskan 20 minit tambahan untuk tambah konfigurasi bersarang dalam setiap sub-pakej. Esok mula kerja, anda akan perasan kod yang AI jana tak payah kena betulkan berkali-kali.

AGENTS.md ialah konfigurasi pengekodan AI dengan ROI paling tinggi sekarang — pelaburan 30 minit, tukar dengan beberapa jam debug setiap bulan.