Masalah: Kenapa AI Coding Selalu Gagal di Tempat yang Sama

Pakai Cursor, Windsurf, atau Claude Code buat ngerjain proyek, hampir semua orang pernah ngalamin momen yang sama: AI ngeluarin satu blok kode panjang, lo copy-paste, jalanin—build error, test merah, dependency ke-install di tempat salah. Masalahnya bukan di otak AI, tapi karena dia nggak tau “aturan main” proyek lo.

AGENTS.md itu file Markdown yang ditaro di root direktori proyek, ditulis khusus buat AI. Isinya kasih tau cara build, cara test, style guide apa yang dipake. README.md buat manusia, isinya penuh perkenalan proyek, panduan kontribusi, cerita brand. AI baca itu semua kayak karyawan baru hari pertama dikasih brosur perusahaan, terus disuruh langsung nulis kode—dia tau perusahaannya ngapain, tapi nggak tau perintah build, nggak tau test dijalankan gimana, nggak tau aturan ESLint apa. Hasilnya, lo harus terus-terusan koreksi di chat: “pake pnpm bukan npm”, “test-nya di packages/web”, “jangan lupa jalanin lint”. Koreksi yang sama diulang seratus kali, proyek tetep berantakan.

Kerugian di proyek freelance jauh lebih nyilem: lo dapet proyek Next.js + Prisma, pake Cursor buat ngebut, eh AI-nya pake npm install, konfigurasi workspace pnpm langsung ancur; dia nggak tau schema database di direktori mana, file migration yang di-generate langsung error. Klien nagih deadline, lo habis tiga jam debug kode bikinan AI—duit yang dikerjain tapi bikin emosi.

3 skenario gagal klasik gara-gara AI nggak tau aturan proyek: ① Package manager ketuker (proyek pake pnpm, AI default npm install), dependency ke-install di tempat salah, konfigurasi workspace失效; ② Test入口 ketuker (test proyek ada di packages/web, AI jalanin pnpm test di root, muncul “test file not found”); ③ Gaya kode nggak konsisten (proyek pake ESLint + Prettier, kode bikinan AI indentasi sama tanda kutip-nya salah semua, CI langsung gagal).

Peluang: AGENTS.md Bikin “Dokumen Manusia” dan “Dokumen Mesin” Kepekang Masing-Masing

Proyek open source AGENTS.md di GitHub (repo github.com/agentsmd/agents.md, per 2026-08-25 sekitar 24 ribu stars)解决 masalah ini. Intinya sederhana banget: taro satu file Markdown di root proyek, kasih tau AI cara build, cara test, style kode apa yang dipake.

Ini bukan pengganti README, tapi pelengkap. README buat kontributor manusia, AGENTS.md buat agen AI. Tugas jelas, nggak saling tabrakan.

Katanya AGENTS.md udah diadopsi puluhan ribu proyek open source (angka persisnya待核),覆盖 VS Code, Cursor, Windsurf, Aider, GitHub Copilot dan工具 AI coding主流 lainnya (核证结论确认); selain itu menurut反馈 komunitas, OpenAI Codex, Google Jules juga提供 dukungan (⚠️未核实). Kalau lo nggak belajar sekarang, sama aja biarin AI ngomong pake bahasa daerah sama lo.

Jalur 1: Tulis Sendiri AGENTS.md Versi Minimal

Biaya超 rendah. Bikin file baru, tulis tiga bagian udah cukup.

Catatan dulu: contoh di bawah pake pnpm (lebih hemat disk dari npm, dukung monorepo workspace), turbo itu编排工具任务 monorepo, parameter --filter指定生效 di子包 tertentu, biar nggak ganggu整个仓库.

Bagian pertama “Dev environment tips”: kasih tau AI proyek pake package manager apa, cara lompat ke子包, cara bikin modul baru. Contoh dari官方:

• pnpm dlx turbo run where <project_name> — lompat langsung ke direktori子包 yang指定, nggak perlu ls satu-satu
• pnpm install --filter <project_name> — install dependency cuma buat子包 tertentu, nggak gerak整个 monorepo
• pnpm create vite@latest <project_name> -- --template react-ts — bikin子包 baru React + Vite dengan检查 TypeScript

Perintah-perintah ini AI nggak bakal nebak sendiri, tapi begitu lo tulis, dia ikut.

Bagian kedua “Testing instructions”: kasih tau AI test dijalankan gimana, pipeline CI di mana,检查 apa yang wajib dijalanin sebelum commit. Contoh resmi:

• pnpm turbo run test --filter <project_name> — jalanin全套检查子包 yang指定
• pnpm vitest run -t "<test name>" — jalanin cuma satu test yang namanya cocok
• “Fix any test or type errors until the whole suite is green” — belum hijau semua belum boleh berhenti
• “Add or update tests for the code you change, even if nobody asked” — ini kuncinya, kalau nggak ditulis AI sering males bikin test

Bagian ketiga “PR instructions”: atur format judul commit, wajib jalanin lint dan test. Contoh resmi: Title format: [<project_name>] <Title>, plus “Always run pnpm lint and pnpm test before committing”.

Tiga bagian ini总 panjang不到 50 baris, tapi tingkat lulus pertama kode bikinan AI naik明显 (menurut反馈 komunitas, angka persisnya待核).

Jalur 2: Pakai Bersarang di Monorepo Besar

Kalau lo handle proyek enterprise, basis kode-nya monorepo (banyak proyek相关放在同一个仓库 Git, misal frontend, backend, kode共享 masing-masing satu子目录), satu AGENTS.md nggak cukup. AGENTS.md支持嵌套: taro satu AGENTS.md专属 di setiap子目录, AI otomatis baca “yang paling dekat”.

Cara praktek: AGENTS.md di root tulis aturan全局 (package manager, alur CI, catatan keamanan), terus di packages/web/, packages/api/, packages/shared/ masing-masing taro satu, tulis perintah build khusus子包 itu,入口 test, dependency khusus. Misal paket前端 perlu tulis “komponen pake shadcn, styling pake Tailwind, ikon pake lucide-react”; paket backend perlu tulis “database migration pake Prisma, route API ada di src/routes, autentikasi pake JWT”.

AI yang kerja di子目录 otomatis muat AGENTS.md terdekat, prioritas lebih tinggi dari yang di root. Artinya di proyek yang sama, asisten AI frontend sama backend dapet指令 yang beda total, nggak saling nimbrung.

Jalur 3: Jadikan Nilai Jual Bedanya di Pasar Freelance

Sekarang pasar freelance AI udah merah—semua orang bisa pake Cursor, tapi kualitas交付 timpang jauh. Kalau lo bisa tulis satu kalimat di proposal: “Proyek ini sudah配备 standar dokumen AGENTS.md, pengembangan berbantuan AI mengikuti规范 proyek”, tingkat menang tender lo bakal jauh lebih tinggi dari kompetitor yang cuma bilang “saya pake AI buat nulis kode”.

Strateginya: begitu dapet proyek, habisi 30 menit dulu buat paham struktur proyek klien, terus tulis AGENTS.md yang dikustomisasi. Dokumen ini sendiri jadi bagian dari交付—klien dapet, ke depan mereka maintenance kode pake AI juga jadi lebih mulus.

Jual jasa konfigurasi AGENTS.md terpisah (referensi harga, disesuaikan sama pasar lokal): versi dasar Rp 700 ribu (konfigurasi satu file + satu README penjelasan), versi enterprise Rp 4,2 juta (nested monorepo +规范 keamanan + pelatihan tim). Daftar交付: ① File AGENTS.md custom ② Konsultasi WhatsApp 30 hari ③ Video培训 10 menit. Cocok buat: klien udah langganan Cursor/Windsurf tapi hasilnya nggak maksimal. Nggak cocok buat: klien masih开发 full manual, belum工具 AI.

Studi Kasus: Parit Pertahanan Kompatibilitas AGENTS.md

AGENTS.md pakai lisensi MIT (素材包确认), dikelola komunitas (struktur tata kelola persisnya待核), situs resminya agents.md.

Kompatibilitas itu parit pertahanannya:核证结论确认 VS Code, Cursor, Windsurf, Aider, GitHub Copilot semuanya支持 baca AGENTS.md; menurut反馈 komunitas, OpenAI Codex, Claude Code, Gemini CLI, Google Jules juga提供 dukungan (⚠️未核实). Artinya lo tulis satu file,工具 AI主流 semuanya bisa pake—nggak perlu nulis konfigurasi terpisah buat tiap工具.

Bandingin sama solusi lain: .cursorrules Cursor cuma生效 di Cursor, ganti Windsurf langsung失效; CLAUDE.md Claude Code cuma buat Claude; sistem instruksi GitHub Copilot lagi一套 lain. Sifat “tulis sekali, jalan di mana-mana” AGENTS.md itulah alasan dia diadopsi luas dalam waktu singkat.

Biaya migrasi工具 jadi nol. Hari ini lo pake Cursor, besok ganti Windsurf, AGENTS.md langsung复用, nggak perlu tulis ulang aturan.

Call to Action: Malam Ini Juga Pasang Buku Panduan Mesin di Proyek Lo

Checklist 5 menit: ① Buka root direktori proyek ② Bikin file AGENTS.md ③ Copy template resmi (github.com/agentsmd/agents.md) ④ Isi tiga perintah (build, test, lint) ⑤ Besok minta AI nulis kode, amati hasilnya.

Kalau lo pake monorepo, malam ini tambahin 20 menit buat pasang konfigurasi嵌套 di setiap子包. Besok开工 lo bakal notice, kode bikinan AI nggak perlu lagi反复 dikoreksi.

AGENTS.md adalah konfigurasi AI coding dengan ROI paling tinggi saat ini—modal 30 menit, tukar好几 jam waktu debug tiap bulan.