Instruksi agent yang nggak pernah dites itu cuma harapan dalam bentuk Markdown. Kelihatannya rapi, panjang, dan meyakinkan. Tapi begitu AI agent mulai pakai tool, buka file, baca chat, lalu ambil keputusan berantai, pertanyaan utamanya bukan lagi “instruksinya sudah ditulis belum?” Pertanyaannya: “agent beneran patuh nggak saat situasinya mulai ribet?”
Artikel ini ngebahas kenapa dokumen seperti AGENTS.md, skill file, policy, dan SOP panjang belum cukup buat mengatur AI agent. Dokumen tetap penting, tapi harus diperlakukan sebagai bagian dari sistem yang bisa diuji: ada eval, contoh task, permission boundary, observability, dan review manusia. Kalau lu pakai AI coding agent buat repo, automation, atau workflow kerja harian, ini cara lebih waras membaca “manual agent” tanpa jatuh ke overprompting.
Apa itu HANDBOOK.md?
HANDBOOK.md adalah benchmark baru berjudul HANDBOOK.md: A Benchmark for Long-Context Agentic Instruction Following. Intinya, paper ini menguji kemampuan AI agent mengikuti instruksi panjang dalam skenario kerja yang lebih mirip dunia nyata.
Benchmark ini menarik karena problemnya dekat banget dengan workflow developer sekarang. Banyak tim mulai menaruh aturan repo, policy perusahaan, SOP security, sampai instruksi tool-use ke dalam context agent. Bentuknya bisa AGENTS.md, README internal, skill document, system prompt panjang, atau kumpulan rule di editor AI.
Di atas kertas, pendekatan ini masuk akal. Agent butuh konteks. Agent butuh aturan. Agent butuh tahu “cara kerja tim ini”. Tapi paper HANDBOOK.md mengangkat pertanyaan yang sering kelewat: apakah agent benar-benar mengikuti aturan panjang itu saat harus bekerja lintas banyak langkah?
Long context bukan governance
Kesalahan umum yang gua lihat: orang menganggap context window besar sebagai solusi governance. Seolah-olah selama semua aturan sudah dimasukkan ke prompt atau file, agent bakal otomatis patuh.
Padahal long context itu resource, bukan kontrak. Agent masih harus mengambil aturan yang relevan, mengingatnya pada momen tepat, menafsirkan konflik antaraturan, lalu menerapkannya saat menjalankan tool. Di workflow nyata, ini bisa berarti agent harus membaca issue, mengedit kode, menjalankan test, memilih command yang aman, dan berhenti saat butuh approval.
Kalau dokumennya 20 sampai 100 halaman, problemnya makin jelas. Semakin panjang instruksi, semakin banyak peluang aturan penting terkubur di tengah noise. Bukan berarti dokumen panjang tidak berguna. Tapi dokumen panjang tanpa verifikasi itu gampang berubah jadi ritual: terlihat serius, tapi belum tentu mengubah behavior.
AGENTS.md tetap penting, tapi jangan diperlakukan sebagai jimat
Gua tetap suka konsep AGENTS.md atau manual repo buat AI agent. Di workflow rafli.dev, file instruksi, Obsidian note, dan skill Hermes sangat membantu supaya agent tidak mulai dari nol setiap run. Instruksi yang rapi bisa mengurangi salah paham dan bikin hasil lebih konsisten.
Masalahnya muncul kalau lu berhenti di sana. Manual agent bukan jimat. Dia harus punya pasangan: test kecil yang membuktikan agent bisa mengikuti instruksi itu.
Contoh sederhana:
- Kalau aturan repo bilang “jangan publish langsung”, harus ada gate yang ngecek status tetap
draft. - Kalau aturan bilang “jangan akses file sensitif”, agent harus punya boundary file atau preflight check, bukan cuma kalimat larangan.
- Kalau aturan bilang “jalankan test sebelum export”, command test harus jelas dan mudah dieksekusi.
- Kalau aturan bilang “pakai gaya bahasa gua/lu”, perlu scanner bahasa atau review step sebelum draft dibuat.
Dengan kata lain: instruksi bagus menjelaskan ekspektasi. Eval membuktikan ekspektasi itu kejaga.
Kenapa ini relevan buat developer yang pakai coding agent?
AI coding agent makin sering diberi akses ke repo, terminal, issue tracker, browser, bahkan deployment flow. Saat agent hanya menjawab chat, risiko salah tafsir masih relatif terbatas. Tapi saat agent bisa mengubah file dan menjalankan command, instruksi yang tidak diverifikasi bisa berubah jadi risiko operasional.
Lu mungkin pernah lihat pola ini: agent sudah diberi instruksi jelas, tapi tetap mengulang style lama, menjalankan command yang salah, atau memperbaiki bug dengan cara yang terlalu besar. Biasanya reaksi pertama adalah menambah prompt. Prompt makin panjang, rule makin banyak, tapi error yang sama tetap muncul dalam variasi baru.
Di titik itu, problemnya mungkin bukan “prompt kurang panjang”. Problemnya adalah workflow belum punya mekanisme feedback yang cukup kuat.
Cara bikin manual agent yang lebih testable
Kalau lu punya AGENTS.md, skill file, atau policy agent internal, gua sarankan mulai dari checklist kecil ini.
1. Pisahkan aturan wajib dan preferensi
Jangan campur “wajib” dan “nice to have” dalam paragraf panjang. Agent dan manusia sama-sama lebih gampang mengikuti aturan kalau prioritasnya jelas.
- Wajib: jangan publish langsung, jangan print secret, jalankan test sebelum deploy.
- Preferensi: gaya commit, format response, pilihan library, urutan folder.
2. Tambahkan contoh task yang benar dan salah
Instruksi abstrak sering terlalu gampang disalahartikan. Contoh konkret bikin agent punya pattern yang lebih jelas.
Misalnya bukan cuma: “jaga kualitas artikel.” Lebih bagus: “artikel harus punya hook problem-driven, ringkasan intent 2–4 kalimat, minimal 3 sumber, bagian referensi, dan tidak memakai kata ganti yang dilarang style guide.”
3. Buat gate otomatis untuk aturan kritikal
Aturan yang penting jangan cuma ditulis. Bikin bisa dicek.
- Script scan kata terlarang untuk gaya bahasa.
- Check status payload Ghost harus
draft. - Check minimal jumlah referensi.
- Check command build/test berhasil sebelum export.
- Check tidak ada secret di output log.
Gate sederhana sering lebih bernilai daripada prompt tambahan 20 baris.
4. Simpan audit trail, bukan cuma summary
Kalau agent melakukan 30 aksi, summary akhir tidak cukup. Lu butuh tahu file apa yang berubah, command apa yang jalan, test apa yang gagal, dan keputusan apa yang diambil.
Ini penting buat debugging. Saat output agent salah, lu tidak mau cuma baca “sudah diperbaiki”. Lu butuh jejak kerja yang bisa direview.
5. Uji instruksi dengan failure mode yang realistis
Test agent jangan cuma skenario bahagia. Coba kasus yang sering bikin kacau:
- Issue ambigu.
- File instruksi bertentangan dengan permintaan user.
- Test gagal di tengah jalan.
- Tool tidak tersedia.
- Data dari luar mengandung instruksi palsu.
Kalau agent tetap berhenti, minta klarifikasi, atau memilih jalur aman, baru instruksi lu mulai terbukti berguna.
Takeaway praktis
Gua bukan anti prompt panjang. Gua juga bukan anti AGENTS.md. Justru menurut gua, developer yang serius pakai AI agent harus punya dokumentasi kerja yang rapi.
Tapi dokumentasi agent harus naik kelas dari “catatan instruksi” menjadi “interface kerja yang bisa diuji”. Kalau instruksi penting, bikin test. Kalau aksesnya sensitif, bikin boundary. Kalau agent bisa jalan lama, simpan audit trail. Kalau outputnya masuk production, tetap butuh review manusia.
AI agent yang bagus bukan cuma agent yang pintar. Agent yang bagus adalah agent yang bisa diarahkan, dibatasi, diamati, dan diperbaiki saat salah.
FAQ singkat
Apakah AGENTS.md jadi tidak berguna?
Tetap berguna. Yang perlu dihindari adalah menganggap AGENTS.md sebagai satu-satunya guardrail. Anggap dia sebagai manual kerja, lalu dukung dengan test, permission, dan audit trail.
Apakah context window besar menyelesaikan masalah instruksi?
Tidak otomatis. Context besar membantu agent membawa lebih banyak informasi, tapi belum menjamin agent mengambil aturan yang tepat pada momen yang tepat.
Mulai dari mana kalau workflow agent lu masih berantakan?
Mulai dari tiga hal: tulis aturan wajib paling kritikal, bikin satu gate otomatis untuk aturan itu, lalu review log aksi agent setiap kali hasilnya meleset.
