Apa itu harness engineering: cara membuat agen AI menjadi alat kerja yang nyata

Harness engineering dengan bahasa sederhana

Harness engineering adalah disiplin rekayasa tentang cara membangun lingkungan di sekitar model bahasa agar ia dapat menyelesaikan pekerjaan nyata secara andal. Kata harness berarti «tali kekang» atau «perlengkapan»: model itu kuat, tetapi dengan sendirinya ia tidak tahu harus ke mana, memakai apa, dan kapan harus berhenti. Harness mengarahkan kekuatan itu.

Rumusan paling singkatnya berbunyi:

Agen = Model + Harness

Model adalah bobot jaringan serta kemampuan bernalar dan menulis teks atau kode. Harness adalah semua yang lain: instruksi sistem dan file seperti CLAUDE.md atau AGENTS.md, kumpulan alat (shell, pengeditan file, server MCP), sandbox tempat agen menjalankan perintah, file status antarsesi, serta tes, linter, dan hook yang memberi tahu agen tentang kesalahan. Jika harness dihilangkan, yang tersisa hanyalah sebuah obrolan yang hanya bisa menjawab dengan teks.

Mengapa agen terkadang «senior», terkadang «junior»

Gambaran yang sudah akrab: di satu repositori agen bekerja seperti pengembang berpengalaman, di repositori lain ia kebingungan, lupa keputusan kemarin, dan melaporkan «selesai» untuk fitur yang tidak berjalan. Reaksi pertama biasanya mengganti model dengan versi yang lebih baru. Biasanya ini tidak membantu, karena modelnya sama di kedua kasus. Yang berbeda adalah lingkungannya.

Dari sini dimulailah pergeseran cara berpikir yang menjadi inti harness engineering: agen tidak rusak — yang rusak adalah apa yang mengelilinginya. Agen tidak bisa menjalankan tes jika tidak punya akses ke sana. Ia tidak akan ingat apa yang sudah dicobanya jika hal itu tidak pernah dicatat. Ia tidak akan tahu fitur itu rusak jika tidak ada pemeriksaan yang memberitahunya. Ini bukan «karakter» model, melainkan cacat rancangan, dan cacat seperti itu bisa diperbaiki secara sistematis.

Gejala harness yang buruk

• Setiap sesi baru dimulai dengan memperbaiki lingkungan: dependensi tidak cocok, basis data tidak naik, variabel tidak ada.
• Agen mengulang solusi yang sudah ditolak, karena tidak mengingat sesi sebelumnya.
• Aturan sudah tertulis jelas di instruksi, tetapi agen mengabaikannya.
• «Tes hijau», tetapi fiturnya rusak, karena tes itu memeriksa hal yang keliru.
• Agen mengambil tiga tugas sekaligus dan tidak menuntaskan satu pun.

Isi harness: lima subsistem

Kesalahan yang sering terjadi adalah menganggap harness hanyalah satu file prompt. Kenyataannya, harness terdiri dari lima mekanisme, dan masing-masing rusak dengan caranya sendiri.

Instruksi

Instruksi menjawab pertanyaan «apakah agen akan menemukan aturan yang tepat». File masukan yang baik adalah peta, bukan buku pelajaran: daftar isi yang singkat berisi perintah verifikasi dan batasan keras, sementara detailnya ada di dokumen terpisah yang dibuka agen bila diperlukan. Instruksi yang baik menetapkan invarian («semua kueri SQL diparameterisasi»), bukan mendikte implementasi baris demi baris.

Alat

Agen hanya bisa memverifikasi hal yang dapat diaksesnya. Jika agen tidak bisa menjalankan linter, aturan «jalankan linter sebelum commit» tidak akan berguna. Alat dihubungkan melalui kemampuan bawaan agen (membaca dan mengedit file, menjalankan perintah) dan melalui MCP, protokol yang memberi agen akses ke basis data, browser, dan pelacak tugas.

Lingkungan

Lingkungan adalah tempat agen menjalankan perintah. Ia harus bisa dinyalakan dengan satu perintah, sama dari sesi ke sesi, dan membatasi kerugian akibat kesalahan: sandbox tanpa akses ke produksi, cabang atau salinan kerja terpisah, dan kemampuan untuk mengembalikan semuanya ke keadaan awal dalam satu menit.

Status

Model tidak punya memori antarsesi: semua yang tidak tertulis di repositori hilang bersama jendela konteks. Karena itu tujuan, hal yang sudah selesai, keputusan yang diambil, jalan buntu, dan langkah berikutnya harus disimpan di file. Caranya mudah diuji: buka sesi baru, katakan kepada agen «lanjutkan» — lalu lihat apakah ia langsung bekerja atau malah bertanya apa yang harus dilakukan.

Umpan balik

Lingkaran umpan balik adalah subsistem yang paling penting. Tanpanya, agen menjadi hakim tunggal bagi dirinya sendiri dan dengan jujur menganggap tugasnya selesai. Tes, pemeriksaan tipe, linter, hook yang berjalan setelah setiap perubahan, dan skenario E2E di browser — semuanya mengembalikan sinyal merah kepada agen selagi kesalahan masih murah untuk diperbaiki.

Harness adalah lingkaran, bukan daftar

Kelima subsistem bekerja sebagai lingkaran tertutup. Model menerima instruksi, bertindak melalui alat di dalam lingkungan, membuat perubahan pada repositori, dan verifikasi memeriksa hasilnya. Sinyal merah dikembalikan ke model untuk diperbaiki, sinyal hijau dicatat dalam status. Status pada gilirannya memperbarui instruksi untuk sesi berikutnya.

instruksi → model → alat → lingkungan → perubahan
                ↑                              ↓
                └──── merah ── verifikasi ─────┘
                                     ↓ hijau
                                 status → (sesi berikutnya)

Jika salah satu panah dihilangkan, lingkaran terputus tepat di titik itu. Tanpa verifikasi, agen tidak tahu tentang kesalahannya. Tanpa status, sesi berikutnya dimulai dengan menggali-gali ulang alih-alih bekerja. Karena itu, investasi pada satu subsistem tidak menutup celah di subsistem lain: AGENTS.md lima halaman tidak bisa menggantikan tes yang tidak ada.

Apa bedanya harness engineering dengan prompt dan context engineering

Ketiga konsep ini bersarang, tidak saling bersaing.

Prompt engineering adalah bagian dari subsistem instruksi. Context engineering mencakup instruksi dan status: apa yang dilihat agen pada setiap momen. Harness engineering menambahkan hal-hal yang sama sekali tidak muat di jendela konteks: akses, sandbox, tes, hook, dan proses kerja. Prompt yang ditulis dengan baik tidak akan membantu jika agen secara fisik tidak bisa menjalankan tes.

Mengapa harness diperlukan: matematika tugas panjang

Secara intuitif, model yang benar dalam 95% langkahnya terlihat hampir sempurna. Namun tugas agen terdiri dari banyak langkah, dan kesalahan menumpuk. Jika langkah-langkahnya saling bebas, peluang melewati semuanya tanpa salah adalah hasil kali peluang masing-masing:

0.95 ^ 10 ≈ 0.60
0.95 ^ 20 ≈ 0.36
0.95 ^ 50 ≈ 0.08

Pada langkah kesepuluh tanpa satu kesalahan pun hanya sekitar 60% percobaan yang sampai, dan pada langkah kelima puluh kurang dari satu dari sepuluh. Meningkatkan model hingga 97% itu mahal dan tidak sepenuhnya berada di tangan Anda. Tetapi menangkap kesalahan pada langkah tempat ia terjadi dan mengembalikannya kepada agen adalah tugas harness. Lingkaran umpan balik mengubah rantai «satu kesalahan menyeret kesalahan berikutnya» menjadi rantai langkah-langkah pendek yang bisa diperbaiki.

Contoh: agen yang sama di dua repositori

Tugas: menambahkan diskon dengan kode promo ke backend pembayaran berbasis FastAPI.

Tanpa harness

Agen membaca beberapa file, menulis fungsi penghitung diskon dan satu tes unit yang menguji fungsi itu secara terisolasi. Tes hijau, agen menulis «selesai». Ia tidak tahu bahwa perhitungan total pesanan dilakukan di modul lain, dan ia tidak bisa menjalankan basis data atau skenario checkout secara utuh. Sehari kemudian ketahuan bahwa diskon di keranjang belanja tidak diterapkan.

Dengan harness

Di akar proyek ada AGENTS.md beberapa puluh baris: cara menyalakan lingkungan, perintah verifikasi apa saja yang wajib, dan di mana arsitektur pembayaran dijelaskan. Lingkungan dinyalakan dengan docker compose up -d. Di repositori ada file rencana dengan kriteria selesai: «skenario E2E checkout dengan kode promo lulus». Setelah setiap perubahan, hook menjalankan linter dan pemeriksaan tipe; sebelum menyelesaikan tugas, agen wajib menjalankan tes E2E.

# AGENTS.md (cuplikan)
## Verifikasi — wajib sebelum kata «selesai»
make lint        # ruff + mypy
make test        # pytest, unit dan integrasi
make e2e         # skenario checkout

## MUST
- Uang dihitung dalam sen (int), tidak pernah float
- Semua kueri SQL diparameterisasi
- Jangan ubah migrasi yang sudah diterapkan di produksi

Modelnya sama. Namun sekarang agen menemukan modul total pesanan lewat peta proyek, tes E2E gagal pada percobaan pertama, agen melihat bahwa diskon tidak sampai ke keranjang, memperbaikinya, dan baru melaporkan setelah hasil uji hijau. Perbedaan hasilnya sepenuhnya berkat harness.

Dari mana memulai

1. Tuliskan bagaimana agen memeriksa pekerjaannya: satu sampai tiga perintah yang wajib dijalankannya. Umpan balik memberikan dampak terbesar, jadi mulailah dari sini.
2. Buat lingkungan dapat direproduksi: lingkungan dinyalakan dengan satu perintah, dan ada cara cepat untuk kembali ke keadaan awal.
3. Buat file status: tujuan, hal yang sudah selesai, keputusan dan jalan buntu, serta langkah berikutnya.
4. Pangkas instruksi menjadi peta: perintah verifikasi, batasan keras, dan tautan ke dokumen rinci.
5. Simpan catatan kegagalan agen: untuk setiap kegagalan, catat subsistem mana yang membiarkannya terjadi. Catatan ini menunjukkan apa yang harus diperbaiki berikutnya.

Latihan yang berguna adalah menilai setiap dari lima subsistem dengan skala 1 sampai 5, menghabiskan setengah jam untuk subsistem yang paling lemah, lalu menjalankan kumpulan beberapa tugas tipikal yang sama sebelum dan sesudah. Dengan begitu, perbaikan harness menjadi dapat diukur, bukan sekadar «terasa lebih baik».

Kesimpulan

Harness engineering adalah pekerjaan bukan pada model, melainkan pada semua yang mengelilinginya: instruksi, alat, lingkungan, status, dan lingkaran umpan balik. Keandalan agen ditentukan oleh mata rantai yang paling lemah dalam lingkaran ini, sehingga mengganti model jarang menyelesaikan ketidakstabilan, sedangkan satu tes atau file rencana yang ditambahkan sering kali berhasil. Kelima subsistem dan cara menyusun harness secara utuh dibahas langsung dalam praktik di kursus harness engineering.