Panduan kapan sub-Agent berguna vs bikin ribet
Di Claude Code ada Agent tool yang bisa menjalankan sub-Agent independen di tengah percakapan. Sub-Agent punya konteks sendiri, menyelesaikan tugasnya, lalu mengembalikan hasilnya ke Agent utama.
Kedengarannya powerful, tapi dari pengalaman nyata, kebanyakan kasus kamu tidak membutuhkannya. Artikel ini menjelaskan: kapan memecah sub-Agent benar-benar berguna, dan kapan justru bikin ribet.
Kamu tidak bisa memanggil Agent tool secara langsung di CLAUDE.md atau slash command — itu adalah tool internal yang Claude Code sendiri yang memutuskan kapan menggunakannya. Tapi kamu bisa memengaruhi keputusannya lewat prompt.
Cara kerja sub-Agent:
Karakteristik penting:
- Konteks independen: Sub-Agent tidak bisa melihat riwayat percakapan utama, hanya bisa melihat prompt yang diberikan saat dijalankan
- Kompresi hasil: Berapapun file yang dibaca atau perintah yang dijalankan sub-Agent, yang dikembalikan ke Agent utama hanyalah sebuah ringkasan
- Bisa paralel: Beberapa sub-Agent bisa dijalankan bersamaan secara paralel
Ini skenario paling klasik. Kamu minta Claude Code menginvestigasi suatu masalah yang perlu dicek dari beberapa arah sekaligus.
Misalnya kamu bertanya: "Bagaimana mekanisme autentikasi di proyek ini?"
Tanpa sub-Agent, Claude Code akan eksekusi berurutan: baca auth controller → baca middleware → baca routes → baca model → baca config… satu per satu, lambat.
Dipecah jadi sub-Agent:
Jalankan 3 sub-Agent secara bersamaan:
- Agent 1: Cek logika autentikasi di layer controller dan middleware
- Agent 2: Cek desain user dan session di layer model
- Agent 3: Cek pengaturan autentikasi di file konfigurasi dan environment variable
Tiga arah jalan bersamaan, hasilnya digabung. Kamu bisa mengarahkan di CLAUDE.md seperti ini:
## Tugas Riset
Ketika perlu menginvestigasi masalah yang melibatkan beberapa modul,
utamakan menjalankan beberapa sub-Agent secara paralel untuk riset masing-masing arah,
lalu gabungkan kesimpulannya.
Context window Claude Code itu terbatas. Kalau ada sub-tugas yang perlu membaca banyak file tapi ujung-ujungnya cuma butuh satu kesimpulan, sub-Agent bisa menahan "sampah proses" di luar konteks utama.
Contoh tipikal:
Ciri khas tugas-tugas ini: input besar, output kecil. Sub-Agent mencerna informasi dalam jumlah besar secara internal, dan hanya mengembalikan intinya.
Ada tugas-tugas yang kamu tidak yakin apakah akan berantakan. Dengan sub-Agent plus parameter isolation: "worktree", dia akan bekerja di git worktree yang terpisah. Kalau rusak, tidak memengaruhi direktori kerja kamu saat ini.
## Refactoring Berisiko Tinggi
Untuk tugas refactoring skala besar, gunakan sub-Agent dengan isolasi worktree.
Pastikan hasilnya benar sebelum di-merge.
Skenario yang cocok:
- Refactoring eksperimental: tidak yakin apakah suatu pendekatan berhasil, biarkan sub-Agent coba dulu
- Membandingkan pendekatan paralel: implementasi dua cara sekaligus, bandingkan hasilnya
- Code generation: generate banyak boilerplate code, review dulu baru merge
"Ganti nama fungsi ini dari camelCase ke snake_case" — langsung kerjakan saja. Overhead menjalankan sub-Agent (membangun konteks, menunggu hasil, parsing hasilnya) justru lebih lambat daripada langsung dikerjakan.
Patokan: Kalau cukup satu Grep + satu Edit, jangan pecah Agent.
"Baca konfigurasi dulu → ubah kode berdasarkan konfigurasi → update test berdasarkan perubahan"
Tugas berantai seperti ini, setiap langkah bergantung pada hasil langkah sebelumnya. Kalau dipecah jadi sub-Agent, kamu harus passing hasil antara lewat prompt bolak-balik — ribet dan rawan kehilangan informasi. Eksekusi berurutan saja.
Sub-Agent mengembalikan ringkasan teks, bukan data terstruktur. Kalau kamu butuh sub-Agent melakukan modifikasi presisi (misalnya menyisipkan kode tertentu di baris ke-47), lebih reliable kalau langsung dikerjakan Agent utama.
Sub-Agent cocok untuk "riset lalu kasih kesimpulan", bukan "eksekusi modifikasi presisi".
Kalau percakapan baru dimulai dan context window masih kosong, tidak perlu memecah Agent demi "melindungi konteks". Tunggu sampai percakapan memanjang dan Agent utama mulai mengompresi riwayat pesan, baru pertimbangkan sub-Agent untuk tugas berat.
Ambil contoh skenario nyata: menginvestigasi semua controller yang menggunakan before_action di proyek Rails, menganalisis pola implementasi autentikasi dan otorisasi.
Tanpa sub-Agent:
Claude Code akan membaca file controller satu per satu, setiap file yang dibaca memakan konteks utama. Kalau ada 20 controller, isi file saja bisa menghabiskan banyak token. Saat akhirnya memberikan analisis, detail yang dibaca sebelumnya mungkin sudah terkompresi dan hilang.
Dengan sub-Agent:
Jalankan sub-Agent: "Baca semua controller di app/controllers/,
temukan semua callback before_action, analisis pola autentikasi dan otorisasi,
berikan ringkasan berdasarkan kategori."
Sub-Agent membaca semua file di konteksnya sendiri, mengembalikan ringkasan yang bersih. Konteks Agent utama hampir tidak terpakai, langsung dapat kesimpulan dan bisa lanjut kerja.
Kamu tidak bisa memaksa Claude Code untuk menggunakan atau tidak menggunakan sub-Agent, tapi bisa memberikan preferensi lewat CLAUDE.md:
## Preferensi Penggunaan Agent
### Tugas yang Cocok Dipecah ke Sub-Agent
- Riset lintas modul (cek 3+ direktori sekaligus)
- Pencarian dan statistik kode skala besar
- Refactoring eksploratif (dengan isolasi worktree)
### Tugas yang Tidak Perlu Sub-Agent
- Modifikasi file tunggal
- Operasi multi-langkah dengan dependensi berurutan
- Bug fix yang sudah jelas lokasi perubahannya
Apakah "proses" dari tugas ini jauh lebih besar dari "kesimpulan"-nya?
Kalau ya — gunakan sub-Agent, biarkan dia mencerna prosesnya dan hanya mengembalikan kesimpulan.
Kalau tidak — kerjakan langsung, jangan tambah layer perantara.
Sub-Agent bukan soal makin banyak makin bagus. Ini adalah tool manajemen konteks, bukan framework concurrent programming. Digunakan dengan tepat, Claude Code bisa tetap jernih di proyek besar. Digunakan salah, cuma buang-buang waktu startup.