AGENTS.md menunjukkan performa lebih baik daripada skills dalam evaluasi agen

 (vercel.com)
15 poin oleh GN⁺ 2026-01-31 | 4 komentar | Bagikan ke WhatsApp
  • Dalam evaluasi yang menargetkan Next.js 16 API, indeks dokumen AGENTS.md yang disertakan di root proyek mencatat akurasi lebih tinggi dibanding pendekatan berbasis skills
  • Skills berbentuk paket pengetahuan domain yang dipanggil agen saat diperlukan, tetapi karena pemanggilannya tidak stabil, tingkat kelulusan default hanya 53%
  • Sebaliknya, indeks AGENTS.md yang dikompresi menjadi 8KB mencapai tingkat kelulusan 100% di semua pengujian (Build, Lint, Test)
  • Pendekatan ini menunjukkan hasil yang lebih stabil daripada pemanggilan proaktif karena menghilangkan titik keputusan, selalu tersedia, dan menyelesaikan masalah urutan
  • Maintainer framework dapat menyertakan indeks dokumentasi yang sesuai versi di AGENTS.md untuk meningkatkan akurasi pembuatan kode

Latar belakang masalah

  • Agen coding AI memiliki keterbatasan karena data pelatihan didasarkan pada API versi lama, sehingga tidak selalu mampu menangani framework terbaru dengan tepat
    • 'use cache', connection(), dan forbidden() di Next.js 16 tidak ada dalam data pelatihan model yang ada
  • Sebaliknya, pada proyek versi lama, model juga dapat menyarankan API terbaru yang sebenarnya tidak ada
  • Untuk mengatasi hal ini, dilakukan eksperimen dengan pendekatan akses dokumentasi yang sesuai versi

Dua pendekatan

  • Skills: paket standar terbuka yang menggabungkan prompt, tool, dan dokumentasi, lalu dipanggil agen saat diperlukan
  • AGENTS.md : file konteks persisten yang berada di root proyek dan selalu dapat dirujuk pada setiap giliran percakapan
  • Kedua pendekatan dibandingkan menggunakan dokumentasi Next.js yang sama

Keterbatasan pendekatan skills

  • Hasil evaluasi menunjukkan bahwa pada 56% pengujian skill tidak dipanggil, dan tingkat kelulusan dasar tetap 53% tanpa peningkatan
  • Pada beberapa item, hasilnya bahkan lebih rendah daripada baseline (misalnya test 58% vs 63%)
  • Ini ditunjukkan sebagai keterbatasan model saat ini yang belum mampu melakukan penggunaan tool secara stabil

Eksperimen tambahan dengan instruksi eksplisit

  • Ketika ditambahkan instruksi eksplisit di AGENTS.md yang menyatakan “panggil skill sebelum menulis kode”, tingkat kelulusan naik menjadi 79%
  • Namun, perbedaan kecil dalam perumusan instruksi sangat memengaruhi hasil
    • “Panggil skill terlebih dahulu” → terpaku pada pola dokumentasi, konteks proyek terlewat
    • “Jelajahi proyek lalu panggil skill” → hasil lebih baik
  • Karena kerapuhan linguistik ini, keandalannya dalam penggunaan nyata tetap rendah

Membangun evaluasi yang dapat dipercaya

  • Pengujian awal kurang andal karena prompt yang ambigu dan masalah verifikasi yang tumpang tindih
  • Hal ini kemudian diperbaiki dengan verifikasi berbasis perilaku dan pengujian yang berpusat pada API Next.js 16 yang belum ada di data pelatihan
  • API utama yang diuji: connection(), 'use cache', cacheLife(), forbidden(), proxy.ts, cookies(), headers(), after(), refresh() dan lainnya

Eksperimen pendekatan AGENTS.md

  • Proses pemilihan oleh agen dihilangkan, lalu indeks dokumentasi disisipkan langsung ke AGENTS.md
  • Indeks tersebut bukan seluruh dokumentasi, melainkan daftar jalur dokumentasi per versi
  • Instruksi tambahan:
    IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Next.js tasks.
    • Ini mendorong model untuk memprioritaskan penalaran berbasis dokumentasi dibanding data pelatihan yang sudah ada

Hasil evaluasi

  • Penyisipan indeks ke AGENTS.md menghasilkan tingkat kelulusan 100%
    • Build, Lint, dan Test semuanya sempurna
  • Statistik perbandingan:
    • Baseline 53%, Skill default 53%, Skill+instruksi 79%, AGENTS.md 100%
  • Alasan pendekatan konteks pasif lebih unggul daripada pemanggilan aktif
    1. Tidak ada titik keputusan — informasi selalu tersedia
    2. Ketersediaan konsisten — disertakan dalam system prompt pada setiap giliran
    3. Masalah urutan hilang — tidak bergantung pada urutan penjelajahan dokumentasi

Mengatasi masalah kapasitas konteks

  • Indeks awal berukuran 40KB, tetapi dikompresi menjadi 8KB (berkurang 80%)
  • Struktur yang dipisahkan dengan pipe (|) menyimpan jalur dokumentasi dan nama file dalam ruang minimum
  • Agen hanya membaca file yang diperlukan dari direktori .next-docs/ untuk memanfaatkan informasi versi yang akurat

Cara menerapkan

  • Dapat disiapkan dengan satu baris perintah 
    npx @next/codemod@canary agents-md
  • Perintah ini akan
    1. Mendeteksi versi Next.js
    2. Mengunduh dokumentasi untuk versi tersebut ke .next-docs/
    3. Menyisipkan indeks terkompresi ke AGENTS.md
  • Ini juga bekerja sama pada agen yang mengenali AGENTS.md seperti Cursor

Implikasi bagi pengembang framework

  • Skills tetap berguna, tetapi untuk meningkatkan akurasi pembuatan kode secara umum, pendekatan AGENTS.md lebih efektif
  • Skills cocok untuk workflow yang berfokus pada tugas tertentu seperti “upgrade versi” atau “migrasi App Router”
  • Rekomendasi:
    • jangan menunggu perbaikan skills, langsung gunakan AGENTS.md
    • sertakan hanya indeks dokumentasi untuk meminimalkan konteks
    • validasi dengan evaluasi yang berpusat pada API yang tidak ada di data pelatihan
    • rancang dokumentasi dengan struktur pencarian yang terperinci
  • Tujuannya adalah beralih dari penalaran yang berpusat pada pre-training ke penalaran berbasis retrieval, dan AGENTS.md adalah cara paling stabil untuk mewujudkannya

Bacaan terkait

4 komentar

 
channprj 2026-01-31

Agen coding AI memiliki keterbatasan karena data pelatihannya berbasis API versi lama, sehingga tidak dapat menangani framework terbaru secara akurat.

Dengan menggunakan Context7, masalah di atas tampaknya bisa teratasi sampai tingkat tertentu.

https://context7.com
 
slowandsnow 2026-02-04

Itu karena context7 tidak efisien, jadi digunakan dua metode di atas...
 
channprj 2026-02-05

Saya paham apa yang ingin Anda sampaikan, tetapi tetap saja, alih-alih setiap kali merapikan dan memasukkan satu per satu tautan dokumentasi terbaru dari semua framework/library yang sedang digunakan saat ini ke AGENTS.md atau Skills, menurut saya menggunakan context7 sebagai pelengkap bukanlah pilihan yang terlalu buruk.

Selain itu, baik artikel GeekNews maupun artikel utama Vercel sama-sama tidak menyebut context7. Saya meninggalkan balasan ini karena rasanya Anda menafsirkan isinya setengah langkah lebih maju.

(Sebagai catatan, fakta bahwa Skills dan AGENTS.md yang ditulis dengan baik dapat menghemat token sudah lama diketahui, dan saya juga sangat memahami hal tersebut.)
 
GN⁺ 2026-01-31
Komentar Hacker News

  • Model bukan AGI. Itu hanya generator teks yang dilatih untuk menimbulkan efek seperti mengedit file atau memanggil tool
    Model bukan memakai skill karena “memahami” skill pengguna, melainkan menghasilkan teks seperti itu berkat reinforcement learning (RL) berdasarkan contoh buatan manusia dan log penggunaan
    Alasan skill tidak selalu dipakai adalah karena kasus seperti itu belum cukup banyak dipelajari. Jika dipaksa dengan RL, model justru bisa menjadi lebih bodoh
    Saat ini kita sedang menumpuk log penggunaan skill agar model masa depan bisa belajar lebih baik kapan harus memakai skill
    AGENTS.md hanyalah konteks. Model sejak awal memang dilatih untuk mengikuti konteks

    • Perbedaan AGENTS.md dan skill pada akhirnya adalah soal bagaimana disisipkan ke dalam konteks
      Frontmatter skill juga pada akhirnya masuk ke konteks, jadi jika AGENTS.md bekerja lebih baik, itu karena perbedaan cara mengekstrak dan menyuntikkan informasi skill
      Sebagian agen mungkin memakai model kecil (misalnya Haiku) untuk menentukan informasi skill mana yang akan diteruskan ke model besar (misalnya Sonnet, Opus)
      Pada akhirnya, inti masalahnya adalah informasi apa yang masuk ke dalam “prompt mentah”
    • Ini bukan AGI. Praktiknya lebih seperti autocorrect yang diperkuat
      Berguna, tapi tidak sempurna. Teknologi GPT sendiri tampaknya sudah masuk fase stagnasi performa
      Perbaikan ke depan kemungkinan ada pada sistem pendukung seperti skill. Namun implementasi skill saat ini kalah dibanding langsung memakai AGENTS.md
    • Saya juga pernah melakukan eksperimen serupa. Di system prompt, skill terkait dimuat lebih dulu, sedangkan di user prompt diuji agar dipanggil saat diperlukan
    • Ada yang bertanya apa itu RL
    • Ada komentar bercanda yang menganalogikan pernyataan “model bukan AGI” dengan kontroversi penamaan GNU/Linux

  • Dalam evaluasi, ada hasil bahwa pada 56% kasus skill sama sekali tidak pernah dipanggil. Artinya dokumentasinya ada, tetapi tidak dipakai. Ditambah candaan, “Berarti lolos Turing test…”

    • Ada tanggapan jenaka, “AI juga RTFM (tidak membaca manual)”
    • Saya juga tertawa, tetapi kalau serius, manusia juga sering tidak bisa diandalkan
      Bedanya, AI menerima instruksi koreksi tanpa ego
      Memang belum setara developer senior, tetapi cenderung lebih patuh daripada junior

  • Temuan utamanya adalah kompresi (compression) pointer dokumen itu efektif
    Sulit dibaca manusia, tetapi bagi LLM itu struktur referensi yang langsung dan efisien
    Ke depannya, alih-alih heuristik seperti agents.md/claude.md/skills.md, kemungkinan besar akan ada standardisasi format indeks terkompresi yang selalu dimuat
    Test suite API juga bisa didaur ulang untuk memverifikasi performa kode LLM
    Makin besar adopsi LLM, library dan API juga harus berevolusi menyesuaikannya

    • Pelajaran lainnya adalah bahwa “jelajahi proyek dulu lalu panggil skill” lebih baik daripada “selalu pakai skill”
      Di Antigravity (=berbasis GEMINI.md), aturan AGENTS.md sudah disetel untuk diikuti tetapi diabaikan
      Sebaliknya, prompt “periksa apakah proyek memiliki AGENTS.md” selalu berhasil
      Fenomena ini terasa ajaib, mirip masa ketika “let’s think step by step” memicu chain of thought
    • Ada juga tanggapan bahwa ini disebut “kompresi”, padahal pada dasarnya cuma tingkat minify
    • Ada pendapat bahwa kalau memakai baris baru alih-alih pipe, hasilnya akan lebih mudah dibaca

  • Jika AGENTS.md dimasukkan langsung ke system prompt, maka ia selalu masuk konteks
    Namun memasukkan semua skill setiap saat itu boros. Karena itu diperlukan pendekatan yang hanya memanggil saat perlu, seperti advanced tool use milik Anthropic
    Pada akhirnya ini soal keseimbangan antara konteks dan biaya. Jika ada ruang, memadatkannya ke AGENTS.md itu efisien

    • Skill pada akhirnya juga dideklarasikan di dalam konteks. Tampaknya sekadar memadatkannya ke AGENTS.md bekerja lebih baik
    • Vercel tampaknya mencampuradukkan skill dan pengaturan konteks. Keduanya punya tujuan yang sama sekali berbeda, jadi keduanya harus dipakai bersama
    • Inilah juga alasan pendekatan RLM bekerja baik. Hanya informasi yang diperlukan yang dimasukkan ke konteks, sisanya dibiarkan di lingkungan
      Agen yang mengelola konteksnya sendiri seperti ini tampaknya akan berkembang pesat tahun ini
    • Pada akhirnya keduanya sama-sama dibutuhkan. Sebagian harus dipaksa masuk ke konteks (index/sparknotes), sebagian lagi perlu ditambahkan secara dinamis berbasis eksplorasi/pencarian
    • Pengguna individu cukup mengubah system prompt, tetapi di tingkat tim skill tetap perlu dipakai untuk standar seperti gaya kode
      Tingkat kepatuhan Claude terhadap skill rendah

  • Saya juga sedang bekerja di area yang serupa. Saya ingin mengevaluasi bagaimana struktur scaffolding proyek memengaruhi hasil Claude Code/Opencode
    Namun metode pengujian Vercel tidak cukup jelas sehingga sulit dibandingkan

  • AGENTS.md bukan sesuatu yang sepenuhnya berbeda dari skill, melainkan bentuk skill yang disederhanakan
    Intinya adalah kualitas desain skill, yaitu meminimalkan jumlah langkah yang harus dilalui AI sampai menemukan informasi yang benar
    Semakin sedikit langkah, semakin kecil akumulasi error

    • Saya juga mengelolanya dalam dua kategori
      1. Hal-hal berbasis aturan yang dipaksa disisipkan ke system prompt
      2. Hal-hal yang dijelajahi agen saat diperlukan
        Dan untuk mengurangi pemborosan token, file besar hanya dimasukkan sekali ke system prompt

  • Setiap kali blog membandingkan prompt engineering, yang selalu saya penasaran adalah apakah dijalankan sekali saja atau diulang berkali-kali
    Hasil LLM tidak konsisten bahkan untuk input yang sama

    • Menyajikan hasil yang tidak deterministik seperti ini seolah-olah sains itu membuat frustrasi
      Kebanyakan terasa seperti data setingkat anekdot yang dibungkus seperti sains
    • Saya selalu menjalankannya berulang kali dan menghitung confidence interval
      Namun kalau benchmark dibuat dengan serius, view-nya sedikit; kalau asal-asalan, traffic blog naik 9 kali lipat
      Struktur insentif yang terdistorsi adalah masalahnya

  • Ada cara yang lebih baik daripada AGENTS.md
    Yaitu membuat folder .context, lalu memasukkan dokumen terkait proyek (README, dokumentasi dependensi, dll.) sebagai symbolic link agar selalu dimuat ke konteks
    Dengan begitu LLM sejak awal sudah memiliki semua informasi yang diperlukan sehingga performa meningkat dan biaya turun

    • Namun dokumentasi dependensi tidak memberi perbedaan besar. Sebaliknya, memasukkan source code itu sendiri ke folder _vendor jauh lebih berguna
      LLM bisa menganalisis kode langsung untuk memahami perilakunya
    • Memuat semua dokumentasi setiap saat itu tidak efisien. Ada juga pendapat bahwa lebih baik cukup mencantumkan lokasinya di Claude.md atau Agents.md lalu dibaca saat perlu
    • Konteks tidak boleh digembungkan tanpa perlu. Sebaliknya, hanya indeks dokumentasi yang dimampatkan adalah pendekatan yang lebih efisien
    • Memasukkan file besar setiap saat adalah pemborosan token. Ada peringatan yang sama di blog Claude Code

  • Ini pengalaman yang saya dapat saat membuat agen kustom saya

    1. Saya merujuk pada panduan ekstraksi Claude Code
    2. Saya memuat otomatis AGENTS.md untuk daftar isi dan ringkasan (sparknotes)
    3. Saya mengelola file Markdown per topik sebagai skill
    4. MCP dan skill secara konsep mirip, jadi kuncinya adalah membuat tool yang bagus
    5. Saya terus bereksperimen, menikmatinya, dan memperbaikinya
      Setelah saya mengubah agar read/write_file dimasukkan ke state dan ditampilkan di system prompt, hasilnya bekerja jauh lebih baik
      Sekarang saya sedang mencoba membuktikannya lewat evaluasi kuantitatif (evals). Secara subjektif, performanya terasa sangat bagus