Apakah AGENTS.md mengubah apa yang dibangun coding agent?

Apakah AGENTS.md benar-benar mengarahkan agent, atau cuma pajangan?

Saya mengujinya di waktu luang. Setiap run memakai prompt yang sama: aplikasi todo dengan CRUD, editor markdown dengan preview, pencarian dengan highlight, dan tag berwarna dengan filter. Template awalnya juga sama: React 19, Vite 7, Tailwind 4, shadcn/ui, TypeScript, dan localStorage, tanpa backend. Satu-satunya yang berubah adalah file instruksinya.

Ada 3 ronde dari 26 September sampai 7 Oktober 2025, total 14 run.

Yang saya ubah-ubah:

• ada atau tidaknya AGENTS.md (3 run tanpa file ini)
• aturan yang sama dalam dua bentuk: markdown, dan teks biasa tanpa heading maupun bullet
• editor dan agent yang menjalankannya: Zed, VS Code, dan Claude

Saya mencatat struktur folder dari setiap run. Waktu tiga tugas saya ukur manual di RUN.md.

Tanpa instruksi, semua run menaruh komponen di satu folder src/components/.

Dengan AGENTS.md, agent beralih ke susunan per fitur, seperti src/features/todos, src/features/tags, dan src/features/search, lengkap dengan dokumentasi di sampingnya. Jadi file itu memang mengarahkan agent. Hanya saja, yang berubah terutama letak kodenya, bukan kualitasnya.

Hasil paling mengejutkan: isi yang sama tanpa format justru paling dipatuhi.

Versi teks biasa membuat KNOWLEDGE.md untuk setiap fitur. Logika pencariannya juga dipindah ke hook useSearchFilter. Versi markdown, dengan aturan yang persis sama, hanya menulis satu KNOWLEDGE.md untuk todos. Dugaan saya, heading dan bullet terbaca seperti dokumen untuk dibaca sekilas. Kalimat biasa terbaca seperti perintah.

Hanya satu varian yang menulis test tanpa diminta di prompt.

Varian itu memakai AGENTS.md versi lengkap yang mewajibkan test, dan hasilnya suite Vitest. README-nya mengklaim 14 dari 14 test lulus, tapi angka itu belum saya jalankan ulang. Satu run di Claude malah melenceng: ia hanya membuat fitur prioritas yang tidak diminta siapa pun. Agent tetap bisa keluar jalur, sebagus apa pun instruksinya.

Hasil ini menunjukkan arah, bukan benchmark.

Setiap varian hanya dijalankan sekali dengan satu prompt. Waktunya diukur manual, hasilnya saya nilai dengan membaca output, dan versi modelnya tidak tercatat. Uji yang lebih layak akan mengulang tiap varian beberapa kali dan menilai hasilnya terhadap spesifikasi.

KNOWLEDGE.md per fitur ternyata berguna.

Pola itu sekarang jadi konvensi .docs/knowledge di proyek sungguhan saya. Saya juga menulis instruksi agent sebagai kalimat biasa, dan aturan wajib saya tulis sebagai aturan.