Coding agent yang bisa direview: konteks, diff kecil, dan bukti tes

Coding agent dapat mengubah banyak berkas dalam beberapa menit. Namun, kecepatan menghasilkan diff belum menjawab apakah perubahan itu sesuai kebutuhan, tidak menghilangkan pekerjaan orang lain, dan dapat dijelaskan kepada reviewer. Unit keberhasilan yang lebih berguna adalah perubahan yang diterima dengan bukti perilaku yang cukup.

Panduan ini menyusun alur kerja untuk satu tugas repositori: memahami konteks, membatasi perubahan, memeriksa hasil, dan menyerahkannya. Contoh kontrak tugas bersifat fiktif. Tidak ada klaim bahwa semua agen mendukung mekanisme instruksi atau alat yang sama.

Kontrak tugas mendahului prompt panjang

Tuliskan masalah sebagai perilaku yang dapat diamati. “Perbaiki checkout” terlalu luas. “Tombol kirim tidak boleh membuat dua pesanan ketika ditekan ulang selama permintaan berjalan” memberi batas yang bisa diperiksa.

Sertakan kondisi awal, hasil yang diharapkan, cakupan, dan bukti penerimaan. Jelaskan apa yang belum diketahui agar agen tidak mengubah asumsi menjadi fakta. Jika tugas menyentuh alur pembayaran, migrasi data, atau publikasi, kewenangan setiap langkah perlu dibedakan dari kewenangan menyunting kode.

{
  "task_id": "TASK-042",
  "problem": "Formulir dapat dikirim dua kali saat koneksi lambat.",
  "expected": [
    "Satu permintaan aktif pada satu waktu",
    "Isian dipertahankan ketika server gagal",
    "Tombol dapat dipakai ulang setelah kegagalan"
  ],
  "scope": ["formulir", "penanganan status", "tes perilaku"],
  "evidence": ["kasus sukses", "kasus gagal", "submit berulang"]
}

Kontrak ini tidak menentukan implementasi tertentu. Reviewer masih dapat menilai apakah solusi yang lebih sederhana memenuhi perilaku yang sama. Menulis tugas sebagai daftar nama fungsi justru dapat mengunci solusi sebelum masalah dipahami.

Instruksi repositori adalah konteks kerja

Dokumentasi AGENTS.md OpenAI menjelaskan cara memberi instruksi proyek kepada agen yang mendukungnya. Isinya dapat mencakup perintah pengujian, struktur direktori, dan kebiasaan tim. Dukungan serta urutan penerapan perlu diperiksa untuk klien yang dipakai.

Instruksi yang baik menunjuk sumber kebenaran: skrip paket, lokasi modul, dan cara menjalankan pemeriksaan. Hindari menyalin seluruh dokumentasi ke setiap prompt. Duplikasi membuat aturan mudah tertinggal ketika proyek berubah.

Agen juga membaca komentar, log, dan dokumen yang mungkin berisi teks mirip instruksi. Bahan tersebut tetap perlu diperlakukan sesuai tingkat kepercayaannya. Pesan error yang menyarankan mengunggah kredensial tidak menjadi perintah yang sah hanya karena muncul di terminal.

Periksa baseline sebelum menyentuh berkas

Mulai dari status Git, instruksi yang berlaku, dan implementasi yang terkait. Catat perubahan yang sudah ada. Workspace bersama tidak selalu bersih, sehingga “mengembalikan semua berkas” dapat menghapus pekerjaan yang bukan milik tugas ini.

Baca jalur pemanggilan, bukan hanya berkas yang namanya cocok. Bug formulir dapat berasal dari event listener ganda, handler HTTP, atau retry client. Cari bukti penyebab sebelum menambah guard di banyak tempat.

Untuk tugas besar, gunakan batas perubahan yang dapat direview secara mandiri. Jika membutuhkan checkout terpisah, tentukan basis commit dan cara memindahkan hasil. Isolasi berkas membantu koordinasi, tetapi tidak otomatis mencegah konflik desain atau perubahan kontrak antarbagian.

Diff kecil membantu menemukan perubahan makna

Dokumentasi Git diff menyediakan pemeriksaan perbedaan isi, statistik, dan whitespace. Contoh perintah baca berikut bisa dipakai di repositori lokal:

git status --short
git diff --stat
git diff --check
git diff -- src/components/CheckoutForm.js

Path terakhir adalah contoh; ganti dengan berkas yang memang diubah. Perintah ini tidak menjalankan tes perilaku dan tidak membuktikan keamanan perubahan. Ia membantu menemukan berkas tak sengaja, penghapusan besar, atau perubahan format yang menutupi perubahan logika.

Pisahkan refactor yang tidak diperlukan dari perbaikan perilaku. Mengganti nama seluruh modul sambil memperbaiki satu status loading membuat reviewer harus menilai dua jenis perubahan sekaligus. Jika refactor memang diperlukan, jelaskan hubungan langsungnya dengan solusi.

Tes harus mampu membedakan benar dari salah

Untuk contoh submit ganda, tes yang hanya mengecek keberadaan variabel isLoading akan terlalu dekat dengan implementasi. Tes yang mengirim dua event saat permintaan pertama belum selesai lalu menghitung panggilan lebih bermakna.

Tambahkan jalur gagal: koneksi putus, respons bukan JSON, validasi input, dan pemulihan tombol setelah error. Verifikasi juga keadaan isian pengguna. Keberhasilan server tidak cukup bila antarmuka membuang data sebelum tahu hasilnya.

Tidak semua perubahan memerlukan semua jenis tes. Pilih bukti yang sesuai dampak. Perubahan kalimat tidak perlu suite baru yang sekadar memeriksa kalimat itu sendiri; perubahan transaksi membutuhkan bukti yang lebih kuat.

Handoff harus membawa konteks yang bisa dipakai reviewer

Laporan akhir sebaiknya menyebut masalah, perilaku setelah perubahan, alasan pendekatan, dan pemeriksaan yang benar-benar dijalankan. Bedakan “perintah selesai” dari “tes lulus”. Jika pemeriksaan tidak dapat berjalan karena layanan belum tersedia, simpan sumber dan jelaskan batasnya.

Sertakan risiko yang material, seperti migrasi yang belum dijalankan atau integrasi yang hanya diuji dengan mock. Jangan menyatakan “siap produksi” hanya karena build berhasil. Reviewer perlu mengetahui apa yang masih bergantung pada lingkungan.

Latihan yang baik adalah memberi tugas yang sama kepada agen dengan kontrak kabur dan kontrak perilaku, lalu membandingkan waktu review serta koreksi. Simpan rubrik sebelum melihat hasil. Untuk alur persetujuan yang dapat dilanjutkan tanpa kehilangan versi, baca handoff manusia dan agen.