Subagen Claude Code: isolasi konteks, orkestrator dan reviewer, kapan tidak diperlukan

Apa itu subagen Claude Code

Subagen adalah instans agen lain yang dijalankan oleh agen utama untuk satu tugas tertentu. Ia punya jendela konteks sendiri, system prompt sendiri, dan daftar alat yang diizinkan sendiri. Agen utama menyerahkan deskripsi tugas, subagen bekerja secara mandiri — membaca berkas, menjalankan perintah — lalu mengembalikan hanya pesan akhirnya.

Kata kunci di sini adalah isolasi. Semua yang dibaca subagen di sepanjang jalan — puluhan berkas, keluaran tes yang panjang, hipotesis buntu — tetap berada di konteksnya dan tidak masuk ke konteks sesi utama. Agen utama hanya melihat hasil singkat: «kesalahan ada di fungsi X, penyebabnya begini, ada tiga tempat yang terdampak».

Subagen Claude Code adalah kasus khusus dari gagasan sistem multi-agen: alih-alih satu siklus «berpikir — bertindak — memeriksa», muncul graf dengan beberapa simpul, masing-masing dengan peran dan tanggung jawabnya sendiri.

Mengapa isolasi konteks penting

Jendela konteks adalah sumber daya utama agen. Di dalamnya sekaligus ada instruksi dari CLAUDE.md, riwayat dialog, kode yang dibaca, dan keluaran perintah. Ketika agen selama setengah jam mencari penyebab bug, konteksnya penuh dengan sampah: berkas yang ternyata tidak relevan dan log yang hanya satu baris pentingnya.

Akibatnya sudah dikenal oleh siapa pun yang lama bekerja dengan agen: model mulai kurang baik dalam menjaga aturan proyek, mencampuradukkan detail, dan ketika riwayat dipampatkan otomatis, hal penting ikut hilang. Subagen menyelesaikan ini secara struktural: pekerjaan kotor dilakukan di konteks terpisah yang dibuang setelah jawaban diberikan.

• Pencarian dan investigasi. «Cari semua tempat yang memanggil fungsi pembayaran dan jelaskan cara kerjanya» adalah tugas khas untuk subagen.
• Pemeriksaan yang berisik. Menjalankan tes dan membedah yang gagal — serahkan ke subagen, terima daftar penyebabnya.
• Membaca dokumen besar. Spesifikasi ratusan halaman dibutuhkan untuk beberapa fakta saja — biarkan subagen mengekstraknya.

Cara menyiapkan subagen: folder .claude/agents

Subagen sendiri dideskripsikan dengan berkas Markdown yang memiliki header YAML. Berkas proyek berada di .claude/agents/ dalam repositori dan tersedia untuk seluruh tim lewat git; berkas pribadi ada di ~/.claude/agents/ dan berlaku di semua proyek Anda. Subagen juga bisa dibuat dan diubah secara interaktif dengan perintah /agents di Claude Code.

---
name: code-reviewer
description: Memeriksa perubahan kode terhadap kesalahan dan pelanggaran aturan proyek. Gunakan setelah tugas selesai, sebelum commit.
tools: Read, Grep, Glob, Bash
---
Kamu adalah reviewer kode. Kamu tidak perlu memperbaiki apa pun.

1. Lihat perubahan: git diff.
2. Periksa setiap perubahan terhadap kesalahan logika, penanganan error,
   keamanan (SQL, escaping keluaran, rahasia).
3. Cocokkan dengan aturan di AGENTS.md.
4. Kembalikan daftar catatan: berkas, baris, masalah, mengapa ini penting.
   Jika tidak ada catatan, tulis itu secara eksplisit.

Arti setiap kolom:

Isi berkas adalah system prompt subagen. Ia tidak melihat riwayat dialog Anda, jadi semua yang perlu ia ketahui tentang peran dan format jawaban harus ada di prompt atau di tugas yang diserahkan agen utama.

Cara memanggil subagen

Agen utama bisa memilih subagen sendiri jika tugas sesuai dengan description-nya. Namun lebih andal jika diminta secara eksplisit: «Gunakan subagen code-reviewer untuk memeriksa perubahan ini». Frasa seperti «gunakan secara proaktif» dalam deskripsi menaikkan peluang subagen dipanggil tanpa diingatkan, tetapi tidak menjaminnya.

Subagen peneliti

Berkas kedua yang hampir selalu berguna dibuat di proyek mana pun adalah peneliti hanya-baca. Ia menjawab pertanyaan tentang kode dan tidak mengubah apa pun.

---
name: explorer
description: Mencari jawaban di basis kode tentang di mana dan bagaimana sesuatu bekerja. Gunakan ketika perlu membaca banyak berkas demi jawaban yang singkat.
tools: Read, Grep, Glob
---
Kamu menyelidiki kode dan tidak mengubah apa pun.
Kembalikan: jawaban singkat atas pertanyaan, daftar berkas dengan baris
yang menjadi dasar jawaban, dan hal-hal yang tidak berhasil diverifikasi.

Subagen seperti ini sangat berguna di awal tugas: agen utama mendapat peta tempat-tempat yang relevan tanpa menghabiskan konteks untuk membaca semuanya, lalu bekerja dengan berkas-berkas yang spesifik.

Pola «orkestrator dan eksekutor»

Pola multi-agen yang paling umum: satu agen orkestrator memegang rencana dan gambaran besar, sementara langkah-langkah konkret diberikan kepada eksekutor. Orkestrator tidak membaca seluruh kode sendiri — ia merumuskan tugas, menerima hasil, dan memutuskan langkah berikutnya.

1. Orkestrator memecah tugas menjadi bagian-bagian independen dan untuk setiap bagian menulis instruksi yang mandiri: tujuan, tempat mencari, apa yang dianggap selesai, dan bentuk jawaban yang diharapkan.
2. Eksekutor menjalankan instruksi tersebut di konteksnya masing-masing.
3. Orkestrator mengumpulkan jawaban, memeriksa bahwa bagian-bagian itu cocok satu sama lain, lalu menjalankan langkah berikutnya atau kembali ke langkah sebelumnya.

Titik lemah pola ini adalah penyerahan tugas. Subagen hanya tahu apa yang ditulis kepadanya. Instruksi «perbaiki bug yang kita bahas tadi» kosong baginya: ia tidak melihat pembahasannya. Instruksi yang baik dibaca seperti tugas untuk rekan baru yang baru pertama kali membuka repositori.

Apa yang harus dikembalikan eksekutor

Tetapkan format jawaban sejak awal: daftar berkas, keluaran, penyebab yang ditemukan, dan hal yang tidak berhasil diperiksa. Jawaban singkat yang terstruktur menghemat konteks orkestrator, dan butir «yang belum diperiksa» melindungi dari keyakinan palsu — eksekutor, seperti agen lain, cenderung melaporkan keberhasilan.

Reviewer terpisah: mengapa juri dipisahkan dari eksekutor

Ketika agen yang sama menulis kode dan sekaligus memeriksanya sendiri, juri dan terdakwa berbagi satu kepala. Agen ingat apa yang ingin ia buat dan melihat niatnya di dalam kode, bukan apa yang sebenarnya tertulis. Selain itu, ia berkepentingan untuk segera selesai, sehingga pemeriksaan berubah menjadi formalitas.

Reviewer di konteks terpisah bebas dari masalah ini. Ia tidak tahu riwayat keputusan, hanya melihat diff dan aturan proyek, dan menilai hasilnya dengan pandangan segar. Ini prinsip yang sama seperti dalam tim sungguhan: penulis tidak menyetujui pull request-nya sendiri.

• Berikan reviewer hanya alat baca dan menjalankan pemeriksaan — tanpa izin mengedit berkas. Dengan begitu ia tidak akan diam-diam «memperbaiki» alih-alih melaporkan masalah.
• Jelaskan kriteria pemeriksaan secara eksplisit: apa yang dianggap kesalahan, aturan proyek mana yang wajib.
• Keputusan tentang apa yang dilakukan dengan catatan diserahkan kepada orkestrator atau manusia. Reviewer menemukan, eksekutor memperbaiki.

Reviewer tidak menggantikan pemeriksaan mekanis. Tes, linter, dan pemeriksaan tipe adalah simpul deterministik; mereka lebih andal daripada model mana pun. Reviewer menangkap hal yang tidak dilihat mekanisme: logika yang keliru, pelanggaran kesepakatan, kerumitan yang tidak perlu.

Menjalankan subagen secara paralel

Claude Code bisa menjalankan beberapa subagen sekaligus. Ini mempercepat kerja ketika bagian-bagian tugasnya benar-benar independen: mempelajari tiga modul, memeriksa perubahan dari tiga sisi (keamanan, performa, tes), mengumpulkan informasi dari beberapa sumber.

Paralelisme bekerja baik untuk membaca dan buruk untuk menulis. Jika dua eksekutor sekaligus mengedit berkas yang sama, mereka saling menimpa perubahan, dan tidak ada yang menyadarinya. Dalam istilah graf agen, ini adalah state bersama tanpa aturan penggabungan. Aturan praktisnya:

• Secara paralel — penelitian, analisis, review. Secara berurutan — perubahan pada berkas yang bersinggungan.
• Jika eksekutor tetap menulis secara paralel, bagi zonanya: masing-masing hanya bekerja di berkasnya sendiri atau di salinan repositorinya sendiri (misalnya git worktree terpisah).
• Hasil digabungkan oleh satu simpul — orkestrator — bukan oleh eksekutor di antara mereka sendiri.

Kapan subagen tidak diperlukan

Skema multi-agen punya harga: lebih banyak token, lebih banyak waktu, lebih banyak tempat informasi bisa hilang saat diserahkan. Subagen Claude Code tidak selalu sepadan.

Sebelum membangun graf agen, jawab pertanyaan sederhana: siapa yang memiliki tujuan bersama, siapa yang boleh memveto dan membatalkan perubahan, dan metrik apa yang dianggap sukses. Jika jawabannya tidak ada, banyak agen hanya akan memperbanyak kebingungan yang sama.

Kesalahan umum dengan subagen

Deskripsi yang kabur

Deskripsi «asisten untuk kode» tidak membantu agen utama memilih kapan memanggilnya. Tulis pemicunya: «setelah perubahan di folder api/, sebelum commit».

Penugasan tanpa konteks

Subagen menerima tugas tanpa path, tanpa kriteria selesai, dan tanpa batasan — lalu menghabiskan separuh kerjanya untuk menebak apa yang diinginkan. Atasi dengan templat penugasan: tujuan, input, batasan, format jawaban.

Izin yang terlalu luas

Peneliti dan reviewer tidak membutuhkan izin mengedit berkas. Pembatasan tools adalah cara murah untuk menjadikan peran sebagai mekanisme, bukan sekadar permintaan dalam prompt.

Percaya pada laporan tanpa verifikasi

«Semua tes lolos» dalam jawaban subagen adalah klaim, bukan fakta. Orkestrator harus bersandar pada yang bisa diperiksa: keluaran perintah, kode keluar, baris-baris spesifik.

Ringkasnya

Subagen Claude Code adalah alat untuk tiga tujuan: menjaga konteks utama tetap bersih, memisahkan verifikasi dari eksekusi, dan memparalelkan pekerjaan yang independen. Ia dideskripsikan dengan berkas Markdown pendek di .claude/agents/, dan kualitas kerjanya hampir seluruhnya ditentukan oleh deskripsi peran, kumpulan alat, dan seberapa mandiri penugasannya. Untuk tugas kecil atau yang sangat terkait dengan dialog, satu agen tetap lebih baik. Peralihan dari satu siklus ke sistem simpul, sisi, dan state bersama dibahas dengan praktik nyata dalam kursus.