Claude Code Subagents: Kapan dan Cara Menjalankan Tim Agen

Terakhir diperbarui: June 28, 2026

Subagent Claude Code adalah sesi Claude terpisah yang dijalankan oleh agent utama untuk satu tugas fokus, kemudian menggabungkan hasilnya kembali ke pekerjaan Anda. Minggu lalu saya mengirimkan tiga di antaranya secara paralel untuk memecah refactor menjadi skema, API, dan tes, dan mereka selesai sebelum satu sesi panjang akan menyelesaikan perencanaan. Postingan ini membahas cara mendefinisikan dan mengirimkan subagent, pola orkestrasi yang saya gunakan untuk meniru tim kecil, dan batas jujur di mana subagent menghabiskan biaya lebih dari penghematannya.

Jawaban cepat: apa itu subagent Claude Code?

Subagent adalah instance Claude dengan jendela konteksnya sendiri, prompt sistemnya sendiri, dan set alat yang sempit. Sesi utama tidak kehilangan konteks saat menjalankan satu, karena subagent bekerja secara terisolasi dan hanya mengembalikan ringkasan. Anggap saja ini seperti mendelegasikan tugas kepada rekan tim yang tidak pernah mengganggu layar Anda.

Mekanisme resminya sederhana. Anda menjatuhkan file markdown di .claude/agents/ dengan frontmatter YAML, dan Claude Code dapat memanggilnya melalui alat Task ketika sebuah tugas cocok dengan deskripsinya. Dokumentasi sub-agent adalah sumber kebenaran untuk kolom-kolom tersebut, dan repo Claude Code melacak perubahan pada format.

Definisi subagent minimal terlihat seperti ini:

---
name: migration-writer
description: Writes and runs database migrations for this repo. Use for schema changes.
tools: Read, Edit, Bash
model: inherit
---
You are a migration specialist. Always check existing migrations first, never drop columns without a confirmation step, and run the migration against the local DB before reporting done.

Setelah file itu ada, saya meminta agent utama "gunakan subagent migration-writer untuk menambahkan tabel orders" dan ia mengirimkan pekerja yang terlingkup alih-alih berjuang melalui prosesnya secara inline. Baris model: inherit menjaga biaya dan kualitas setara dengan sesi utama; menentukan model yang lebih murah seperti haiku pada subagent yang berat membaca adalah tuas nyata ketika Anda menjalankan banyak di antaranya.

Kapan harus menggunakan subagents daripada satu sesi?

Gunakan subagent ketika tugasnya berjalan lama, berat konteks, atau membutuhkan set alat yang tidak ingin Anda miliki di sesi utama. Pertahankan dalam satu sesi ketika pekerjaan itu singkat, terkait erat dengan apa yang sudah Anda lakukan, atau membutuhkan bolak-balik ketat dengan Anda.

Saya menggunakan subagent untuk pekerjaan yang jika tidak akan mencemari konteks utama saya dengan log, bacaan besar, atau coba-coba. Audit seluruh basis kode yang melakukan grep 200 file adalah kandidat sempurna, karena subagent membaca semuanya dan mengembalikan ringkasan dua paragraf sementara sesi utama saya tetap bersih.

Jika Anda baru mengenal agent itu sendiri, Panduan utama Claude Code mencakup dasar-dasarnya sebelum Anda menambahkan subagent di atasnya.

Bagaimana cara mengirimkan subagents di Claude Code?

Pengiriman terjadi dengan dua cara. Agent utama dapat memanggil alat Task sendiri ketika tugas cocok dengan deskripsi subagent, atau Anda dapat menamainya secara eksplisit dalam prompt Anda. Saya lebih suka menamainya, karena pengiriman implisit terkadang melewatkan agent yang saya inginkan.

Beberapa pola yang rutin saya jalankan:

• "Gunakan subagent code-reviewer pada diff di branch ini, lalu terapkan sarannya."
• "Kirimkan migration-writer untuk menambahkan kolom users.email_verified, dan kirimkan test-writer untuk menutupinya. Jalankan keduanya."
• "Nyalakan subagent api-docs terhadap src/routes/ dan kembalikan hanya kerangka OpenAPI."

Subagent berjalan dalam konteksnya sendiri, jadi ia tidak dapat melihat percakapan Anda yang sedang berlangsung kecuali Anda meneruskan detailnya di prompt. Isolasi itu adalah intinya. Ketika selesai, Anda mendapatkan hasil, bukan aliran kebisingan menengah.

Pola yang saya gunakan untuk alur kerja seperti tim

Triknya adalah menyalin cara tim nyata membagi pekerjaan, lalu memetakan setiap peran ke subagent. Berikut adalah pola yang terus saya gunakan.

Riset, lalu sebarkan. Saya mengirimkan satu subagent untuk mengumpulkan konteks, membaca ringkasannya, kemudian mengirimkan beberapa subagent implementasi terhadap antarmuka bersama. Ini meniru seorang tech lead yang memperkirakan pekerjaan sebelum menyerahkan tiket.

Membangun di balik kontrak. Definisikan API atau properti komponen terlebih dahulu, lalu jalankan subagent backend dan subagent frontend secara paralel terhadap kontrak itu. Tidak ada yang memblokir yang lain, dan konflik jarang terjadi karena mereka menyentuh file yang berbeda.

Meninjau sebagai peran terpisah. Saya menyimpan subagent code-reviewer hanya dengan alat baca. Setelah setiap perubahan non-trivial, saya menjalankannya terhadap diff. Membatasi alatnya berarti ia secara harfiah tidak dapat mengedit, yang menjaga peninjauan tetap jujur.

Untuk alur kerja yang berulang seperti ini, pasangkan subagents dengan Claude Code skills: sebuah skill mengenkode langkah-langkah, dan subagent melakukan pekerjaan terisolasi. Dan jika subagent membutuhkan data luar, sambungkan ke server MCP seperti yang dijelaskan oleh Panduan integrasi Claude Code MCP.

Contoh kerja: orders dan payments

Bulan lalu saya memecah fitur orders-plus-payments menjadi tiga subagents terhadap kontrak bertipe. Kontraknya adalah satu antarmuka TypeScript untuk Order dengan status, totalCents, dan paymentId. Saya mengirimkan: subagent backend untuk mengimplementasikan pembuatan pesanan dan transisi status; subagent payments untuk menyambungkan panggilan Stripe dan menyimpan paymentId; dan subagent tes untuk menutup jalur bahagia (happy path) dan kasus tepi pengembalian dana. Ketiganya menyentuh file yang berbeda, sehingga penggabungan menjadi tiga operasi copy-paste bersih alih-alih sesi resolusi konflik. Seluruh proses memakan waktu 14 menit; pekerjaan yang sama dalam satu sesi serial memakan waktu 41 minggu sebelumnya, karena konteks tunggal terus memuat ulang dokumentasi Stripe.

Bagaimana cara mengorkestrasi pekerjaan paralel tanpa kehilangan konteks?

Sesi utama adalah koordinator Anda. Tugasnya adalah memecah pekerjaan, menyerahkan prompt terlingkup, dan menyambungkan hasil kembali bersama-sama. Jaga agar koordinator tetap ramping dan biarkan subagents yang membawa bacaan berat.

Jalankan paralel tipikal bagi saya terlihat seperti ini:

1. Tulis kontrak dan batas file di sesi utama.
2. Kirimkan dua hingga empat subagents, masing-masing dengan satu irisan dan kondisi sukses yang jelas.
3. Baca setiap ringkasan saat dikembalikan, bukan di tengah proses.
4. Gabungkan di sesi utama, menyelesaikan sambungan sendiri.
5. Jalankan subagent tes terakhir terhadap hasil terintegrasi.

Paralelisme hanya membuahkan hasil ketika irisan-irisan tersebut benar-benar independen. Jika dua subagents sama-sama mengedit schema.prisma, Anda belum memecah pekerjaan, Anda telah menciptakan masalah penggabungan. Gambarkan batas pada file dan kontrak, lalu terapkan di prompt.

Kapan subagents menambah overhead lebih banyak daripada yang mereka hemat?

Subagents menambahkan latensi, token, dan biaya koordinasi. Penyerahan ringkasan kehilangan detail, jadi apa pun yang membutuhkan kesinambungan mendalam adalah pilihan buruk. Jujurlah tentang pertukaran nilai sebelum Anda menggunakannya.

Saya menjalankan tolok ukur pada satu feature branch: satu subagent per microservice versus sesi tunggal yang berjalan secara berurutan. Untuk lima layanan yang longgar terikat, paralel menang sekitar 40 persen dalam waktu jam dinding. Untuk tiga layanan yang berbagi model data, sesi tunggal lebih cepat, karena penggabungan dan penjelasan ulang memakan keuntungan paralel.

Pelajaran: paralelisme menghargai kemandirian dan menghukum keterikatan (coupling). Jika irisan Anda berbagi status, jangan diparalelkan.

Apa saja kesalahan umum?

• Terlalu banyak subagents. Saya membatasi satu sesi maksimal tiga hingga lima. Melebihi itu, biaya koordinasi melebihi keuntungan paralel.
• Prompt yang samar. "Perbaiki auth" gagal. "Tambahkan endpoint refresh JWT di /auth/refresh, mengembalikan { token }, dengan tes" berhasil.
• Tidak ada kriteria sukses. Nyatakan apa artinya selesai. "Migrasi diterapkan secara lokal dan pengujian rollback dilakukan" lebih baik daripada "tangani skema".
• Set alat yang salah. Berikan reviewer hanya alat baca. Berikan agen deploy perintah persis yang dibutuhkannya, tidak ada yang lebih luas.
• Mengabaikan kegagalan. Jika subagent mengembalikan error, bacalah itu. Mencoba ulang secara membabi buta menghabiskan token dan menyembunyikan masalah nyata.
• Melewatkan penggabungan. Subagents mengembalikan hasil; Anda masih memiliki kepemilikan integrasi. Alokasikan waktu nyata untuk itu.

Kesalahan termahal adalah memperlakukan subagents sebagai paralelisme gratis untuk apa pun. Mereka adalah pekerja yang terlingkup di balik batas ringkasan, dan batas itu memiliki biaya.

Ringkasan

Subagents mengubah Claude Code menjadi sesuatu yang terasa seperti tim kecil: koordinator ramping yang mengirimkan pekerja terlingkup yang masing-masing membawa konteksnya sendiri dan melaporkan hasilnya. Definisikan mereka di .claude/agents/, kirimkan dengan alat Task, dan jaga sesi utama Anda tetap bersih dengan mendorong bacaan berat dan peran berulang ke subagents.

Gunakan mereka ketika pekerjaan lama, berat konteks, atau membutuhkan set alat terbatas. Lewati mereka untuk tugas singkat, terikat, interaktif di mana penyerahan ringkasan kehilangan terlalu banyak. Gambarkan batas pada file dan kontrak, batasi satu sesi maksimal beberapa agen, dan selalu alokasikan waktu untuk menggabungkan hasilnya sendiri.

Satu peringatan nyata: subagents melipatgandakan throughput, bukan penilaian. Mereka akan dengan senang hati membangun hal yang salah secara paralel di empat konteks terisolasi. Pekerjaan koordinasi, definisi kontrak, dan peninjauan akhir masih jatuh pada Anda, jadi daya ungkit hanya muncul ketika irisan-irisan benar-benar independen dan kriteria suksesnya tepat. Jika Anda menginginkan latar belakang yang lebih dalam tentang protokol yang menggerakkan banyak pengkabelan alat ini, penjelas MCP adalah bacaan selanjutnya yang bagus, dan dokumentasi Claude Code mencakup pengaturan yang tidak saya ulangi di sini.

Kredit Gambar

• Tim pengembang bekerja bersama dengan komputer di kantor teknologi modern — foto oleh Rebrand Cities di Pexels
• Kode pemrograman berwarna-warni pada monitor komputer — foto oleh inna mykytas di Pexels
• Seorang pengembang menulis kode di laptop di depan beberapa monitor — foto oleh Christina Morillo di Pexels
• Dua programmer fokus pada pengkodean berdampingan di kantor modern — foto oleh Rebrand Cities di Pexels