Ada batasan yang Anda capai dengan setiap sesi pengkodean AI tunggal: jendela konteks. Jika satu percakapan diisi dengan refactor yang luas, tiga putaran hasil pengujian, dan tinjauan kode, agen mulai kehilangan jejak. Sub-agen Claude Code adalah solusinya. Alih-alih satu agen menangani semuanya dalam satu konteks, Anda membuat pekerja yang terfokus, masing-masing dengan jendela konteksnya sendiri, instruksinya sendiri, dan izin alatnya sendiri. Mereka melakukan satu pekerjaan, mengembalikan hasil, dan menjaga utas utama tetap bersih.
Ini adalah panduan pembangunan langsung. Cara membuat sub-agen kustom sebagai file konfigurasi, apa fungsi setiap bidang frontmatter, bagaimana Claude memutuskan untuk mendelegasikannya, dan cara menyusun pengaturan praktis di mana satu agen meninjau kode sementara agen lain menulis pengujian secara paralel. Jika Anda ingin gambaran konseptual terlebih dahulu, artikel kami tentang apa itu sub-agen Claude Code dan mengapa mereka penting membahas dasar-dasarnya. Di sini kami fokus pada pembangunannya, dan pada sudut pandang pengujian API yang mengubah sub-agen pengujian menjadi langkah verifikasi yang dapat Anda percaya.
TL;DR
Anda membuat sub-agen Claude Code dengan menulis file Markdown di .claude/agents/ dengan frontmatter YAML: sebuah name, sebuah description yang memberi tahu Claude kapan harus mendelegasikan, sebuah tools allowlist opsional, dan sebuah model opsional. Isi file menjadi prompt sistem sub-agen. Setiap sub-agen berjalan dalam jendela konteksnya sendiri dengan alatnya sendiri, sehingga Anda mendapatkan isolasi konteks, paralelisme, dan spesialisasi. Claude mendelegasikan secara otomatis berdasarkan deskripsi, atau Anda memanggil sub-agen berdasarkan nama. Referensi resmi adalah dokumentasi sub-agen Claude Code.
Sub-agen dalam 60 detik
Sub-agen adalah instans agen terpisah yang kepadanya agen Claude Code utama menyerahkan tugas. Agen utama adalah insinyur utama; sub-agen adalah spesialis yang dipanggilnya. Spesialis bekerja dalam percakapannya sendiri, dengan jendela konteksnya sendiri dan prompt sistem, kemudian hanya mengembalikan hasilnya. Tiga properti membuatnya layak untuk dikonfigurasi:
- Jendela konteksnya sendiri. Sub-agen memulai dari awal hanya dengan tugas yang diberikan kepadanya, sehingga utas utama tidak pernah terisi dengan pekerjaan perantaranya.
- Prompt sistem kustom. Anda membentuk perilakunya: seorang peninjau yang mencari celah keamanan, penulis tes yang mengikuti konvensi Anda.
- Alat yang dapat dikonfigurasi. Anda memberikan setiap sub-agen hanya alat yang dibutuhkan, sehingga peninjau tidak dapat menulis dan pelari tes hanya mendapatkan akses shell yang cukup.
Itu adalah dasar konseptual; gambaran umum konseptual membahas lebih dalam tentang alasannya. Sisa panduan ini adalah tentang membangunnya, yang merupakan prinsip yang sama di balik harness agen Claude Code yang diterapkan pada tingkat tugas individu.
Mengapa menggunakan sub-agen
Tiga alasan, dan semuanya saling terkait.
Isolasi konteks. Sesi yang panjang akan menurun seiring dengan terisinya jendela konteks. Setiap pembacaan file, setiap eksekusi tes, setiap penyimpangan menghabiskan anggaran dan mengurangi fokus. Mendelegasikan tugas besar ke sub-agen menjaga semua pekerjaan itu dalam konteks sub-agen, bukan yang utama. Agen utama mendapatkan kembali ringkasan yang bersih alih-alih 50.000 token dari *noise* perantara. Isolasi itu juga merupakan pengungkit biaya, karena Anda tidak menyeret konteks yang membengkak melalui setiap giliran. Catatan kami tentang mengurangi biaya token agen membahas ekonominya.
Paralelisme. Tugas independen tidak perlu berjalan satu demi satu. Agen utama dapat mengirim beberapa sub-agen sekaligus: meninjau modul ini saat menguji yang itu saat mendokumentasikan yang ketiga. Waktu *wall-clock* turun ke tugas tunggal terlama alih-alih jumlahnya. Alur kerja dinamis Claude Code mendorong ini hingga batasnya, menyebarkan ratusan sub-agen paralel dari satu sesi.
Spesialisasi. Agen umum bagus dalam segala hal dan hebat dalam tidak ada apa-apa. Sub-agen dengan prompt sistem yang ketat dan alat yang tepat sangat baik dalam satu hal. Peninjau yang diminta untuk bersikap antagonis menemukan lebih banyak *bug* daripada generalis yang melirik *diff*. Penulis tes yang mengetahui gaya *assertion* Anda menghasilkan tes yang benar-benar akan Anda pertahankan. Anda membangun tim kecil spesialis alih-alih satu generalis yang kewalahan.
Cara membuat sub-agen kustom
Sub-agen adalah file Markdown biasa. Letakkan yang tingkat proyek di .claude/agents/ dan yang pribadi di ~/.claude/agents/. Setiap file memiliki frontmatter YAML dan isi yang menjadi prompt sistem sub-agen.
Berikut adalah peninjau kode:
---
name: code-reviewer
description: Reviews code changes for bugs, security issues, and convention violations. Use after writing or editing code.
tools: Read, Grep, Glob
model: sonnet
---
You are a senior code reviewer. When given a diff or a set of files:
1. Look for correctness bugs, security holes, and missed edge cases.
2. Check that the code matches the project's existing conventions.
3. Report only high-confidence issues, ranked by severity.
Be specific. Cite file and line. Do not rubber-stamp.
Bidang frontmatter:
name— pengidentifikasi yang Anda gunakan untuk memanggilnya.description— ini yang penting. Claude membacanya untuk memutuskan kapan harus mendelegasikan secara otomatis. Tulis sebagai pemicu yang jelas (“Gunakan setelah menulis kode”), bukan label yang tidak jelas.tools— daftar yang diizinkan (allowlist). Hilangkan untuk mewarisi alat agen utama, atau daftarkan yang spesifik untuk membatasinya. Peninjau yang tidak bisa menulis kode tidak bisa secara tidak sengaja mengubahnya.model— secara opsional mengunci model. Gunakan model yang lebih murah dan cepat untuk sub-agen mekanis dan yang lebih kuat untuk penalaran yang sulit.
Isinya adalah prompt sistem. Di sinilah spesialisasi berada, jadi tulislah seperti Anda akan memberi pengarahan kepada karyawan baru: apa yang harus dilakukan, apa yang harus diprioritaskan, apa yang harus dihindari. Memasangkannya dengan proyek design.md atau AGENTS.md memberikan sub-agen konvensi Anda tanpa mengulanginya di setiap file.
Cara memanggil sub-agen
Ada dua cara sub-agen berjalan.
Delegasi otomatis. Claude membaca bidang description dari setiap sub-agen yang tersedia dan mendelegasikan sendiri ketika tugas cocok. Setelah selesai mengedit file, agen utama dapat menyerahkan *diff* ke code-reviewer Anda tanpa diberitahu, karena deskripsi mengatakan "gunakan setelah menulis kode." Deskripsi yang baik mendorong delegasi yang baik.
Pemanggilan eksplisit. Anda juga bisa menamainya secara langsung: "gunakan sub-agen *code-reviewer* pada perubahan di modul pesanan." Ini adalah cara Anda memaksa spesialis tertentu ketika Anda tidak ingin menyerahkan delegasi pada kebetulan.
Bagaimanapun, sub-agen berjalan dalam konteksnya sendiri, melakukan pekerjaan, dan mengembalikan hasil ke utas utama. Anda melihat serah terima terjadi, dan Anda dapat mengonfigurasi seberapa banyak detail yang muncul. Untuk merantai sub-agen menjadi urutan yang deterministik dan dapat diulang, perintah *slash* dan SDK memberi Anda lebih banyak kontrol daripada *prompt* ad-hoc; gambaran umum Claude Code mencakup permukaan konfigurasi.
Sub-agen vs. Agent SDK vs. alur kerja dinamis
Ini tumpang tindih, jadi inilah kapan masing-masing cocok.
| Alat | Model kontrol | Terbaik untuk |
|---|---|---|
| Sub-agen | Model memutuskan kapan harus mendelegasikan (atau Anda menamai satu) | Spesialisasi dalam sesi dan paralelisme ringan |
| Alur kerja dinamis | Model mengatur *fan-out* besar dalam satu sesi | Ratusan tugas paralel, sapuan luas |
| Agent SDK | Anda menulis alur kontrol dalam kode | Loop deterministik, berjalan terjadwal atau tanpa pengawasan |
Sub-agen adalah opsi dalam sesi, percakapan: Anda bekerja di Claude Code dan menginginkan satu atau dua spesialis. Saat Anda membutuhkan *loop* terprogram yang berjalan sesuai jadwal tanpa kehadiran manusia, Anda beralih ke Claude Agent SDK dan menulis orkestrasinya sendiri. Jika Anda mempertimbangkan opsi yang di-host versus membuat sendiri, perbandingan agen terkelola vs Agent SDK kami menjelaskan *trade-off*nya. Ketiganya bukanlah pesaing melainkan anak tangga pada tangga dari interaktif ke otomatis sepenuhnya.
Contoh praktis: tinjauan paralel dan penulisan tes
Mari satukan. Katakanlah Anda baru saja meminta agen utama mengimplementasikan *endpoint* pesanan baru. Anda ingin itu ditinjau dan diuji, dan tidak ada alasan itu terjadi secara berurutan.
Definisikan dua sub-agen. code-reviewer di atas, ditambah penulis tes:
---
name: api-test-writer
description: Writes API test cases for new or changed endpoints. Use after an endpoint is implemented.
tools: Read, Grep, Write, Bash
model: sonnet
---
You write API tests against the project's OpenAPI spec.
1. Read the spec and the endpoint implementation.
2. Write tests covering success, validation errors, and auth.
3. Assert status codes and validate response bodies against the schema.
4. Run the suite and report pass/fail with reasons.
Sekarang agen utama mengirim keduanya sekaligus: peninjau membaca *diff* sementara penulis tes membaca *spec* dan menulis *coverage*. Dua spesialis, dua konteks terisolasi, berjalan secara paralel. Utas utama tetap bersih dan mendapatkan kembali dua ringkasan: laporan tinjauan dan hasil tes.
Hasil tes itulah yang membuat ini dapat dipercaya. Sub-agen yang menjalankan *suite* API Anda adalah *gate* verifikasi, pemeriksaan deterministik yang menyatakan apakah *endpoint* benar-benar berfungsi daripada apakah terlihat sudah selesai. Ini adalah ide inti dari loop agen pengkodean: kepercayaan diri agen tidak dihitung, keputusan *gate* lah yang dihitung. Hubungkan sub-agen tes dengan platform tes API sungguhan dan umpan baliknya akan lebih tajam. Tim yang menggunakan Apidog mengarahkan sub-agen ke skenario tes Apidog sehingga setiap respons divalidasi skemanya, dan mengarahkan panggilan *endpoint* langsung agen melalui debugger agen AI Apidog sehingga ia memeriksa permintaan seperti yang akan dilakukan penguji manusia. Ambil pengaturan yang sama, bungkus dalam *loop*, dan Anda akan memiliki alur kerja tanpa pengawasan yang kami bangun dalam alur kerja Claude yang berjalan tanpa Anda. Unduh Apidog jika Anda ingin *test gate* peka skema secara *out of the box*.
Praktik terbaik
Beberapa kebiasaan membuat sub-agen tetap berguna alih-alih kacau.
- Satu tanggung jawab per sub-agen. Peninjau meninjau. Penguji menguji. Jangan membangun sub-agen serba guna; itu hanya agen utama dengan langkah-langkah tambahan.
- Tulis deskripsi untuk delegasi. Bidang
descriptionadalah bagaimana Claude memutuskan untuk memanggil sub-agen Anda. Jadikan itu pemicu yang jelas, bukan judul. “Gunakan setelah mengedit kode untuk meninjau *bug*” lebih baik daripada “Peninjau kode.” - Berikan hak istimewa paling rendah. Daftar hanya alat yang dibutuhkan setiap sub-agen. Peninjau tanpa akses tulis tidak dapat mengubah apa yang sedang ditinjaunya. Ini lebih penting saat *run* tidak diawasi.
- Kunci model yang tepat per pekerjaan. Sub-agen mekanis dapat berjalan pada model yang lebih cepat dan lebih murah. Simpan model terkuat untuk sub-agen yang melakukan penalaran yang sulit. Ini mengontrol kecepatan dan biaya.
- Kembalikan hasil terstruktur. Minta sub-agen untuk melaporkan dalam bentuk yang konsisten (putusan, daftar masalah, lulus/gagal). Output terstruktur lebih mudah bagi agen utama, dan bagi Anda, untuk ditindaklanjuti.
- Jangan terlalu banyak bersarang. Sub-agen memanggil sub-agen yang memanggil sub-agen menjadi sulit diikuti dan mahal. Jaga hierarki tetap dangkal.
Ini mencerminkan pola pengkabelan yang kami bahas dalam pola pengkabelan alat alur kerja agensi, dan berlaku apakah Anda memiliki dua sub-agen atau dua puluh.
Kapan harus menggunakan sub-agen (dan kapan tidak)
Sub-agen adalah alat, bukan *default*. Mengetahui kapan harus melewatkannya akan menjaga pengaturan Anda cepat dan murah.
Gunakan sub-agen ketika tugas terbatas, independen, dan bising. Tinjauan kode terbatas (memiliki akhir yang jelas), independen (tidak memerlukan status berjalan dari utas utama), dan bising (menghasilkan banyak pembacaan perantara yang tidak ingin Anda menyumbat konteks utama). Sama untuk menulis *suite* tes, mereproduksi *bug*, atau mengaudit modul untuk masalah keamanan. Ini adalah delegasi yang sempurna: isolasi pekerjaan, dapatkan kembali putusan.
Lewati sub-agen ketika tugasnya kecil, sangat terkait, atau berurutan dengan pekerjaan utama. Mengganti nama variabel, memperbaiki *bug* satu baris, atau apa pun di mana agen utama sudah memiliki konteks yang diperlukan dalam pandangan tidak akan mendapat manfaat dari serah terima. Memunculkan sub-agen di sana hanya menambah latensi dan *round-trip* konteks tanpa keuntungan. Jika agen utama harus menjelaskan separuh percakapan untuk memberi pengarahan kepada sub-agen, pertahankan di utas utama.
Aturan praktis: delegasikan pekerjaan yang cukup mandiri untuk dijelaskan dalam satu paragraf dan cukup berharga untuk dijalankan secara paralel. *Endpoint* baru untuk ditinjau dan diuji cocok. Koreksi *typo* tidak. Saat Anda menskalakan ke banyak sub-agen bersamaan, pola orkestrasi dalam alur kerja dinamis akan mengambil alih, tetapi penilaian yang sama berlaku: paralelkan yang independen, pertahankan pekerjaan yang terkait bersama.
Kesalahan umum
- Deskripsi yang tidak jelas. Jika
descriptionadalah label, delegasi otomatis tidak akan aktif saat Anda harapkan. Tulislah sebagai pemicu penggunaan. - Satu sub-agen yang membengkak. Memasukkan setiap pekerjaan ke dalam satu sub-agen membunuh manfaat spesialisasi. Pisahkan berdasarkan tanggung jawab.
- Mewarisi semua alat secara *default*. Membiarkan
toolstidak diatur memberikan sub-agen semua yang dimiliki agen utama. Bagus untuk pekerjaan yang dipercaya, berisiko untuk apa pun yang otomatis. Izinkan secara sengaja. - Tidak ada sub-agen verifikasi. Pengaturan tinjauan dan pembangunan tanpa *test gate* mengirimkan kode yang terlihat benar tetapi rusak di tepi. Selalu sertakan sub-agen yang benar-benar menjalankan tes.
- Memperlakukan sub-agen seperti SDK. Sub-agen diutus model dan dalam sesi. Jika Anda membutuhkan alur kontrol deterministik dan terjadwal, itu adalah tugas Agent SDK, bukan tumpukan sub-agen.
Lakukan ini dengan benar dan beberapa sub-agen yang dilingkup dengan baik mengubah Claude Code dari satu asisten yang sibuk menjadi tim kecil yang terfokus. Membangun agen yang efektif dari Anthropic membuat kasus yang lebih luas: struktur di sekitar model mengalahkan *prompt* yang lebih besar.
Pertanyaan yang sering diajukan
Apa itu sub-agen Claude Code? Ini adalah instans agen terpisah yang didelegasikan oleh agen Claude Code utama. Setiap sub-agen memiliki jendela konteksnya sendiri, prompt sistem kustom, dan serangkaian alat yang dapat dikonfigurasi. Ia melakukan tugas terfokus dan mengembalikan hasilnya, menjaga percakapan utama tetap bersih dan memungkinkan Anda menjalankan spesialis secara paralel.
Bagaimana cara membuat sub-agen Claude Code? Buat file Markdown di .claude/agents/ (proyek) atau ~/.claude/agents/ (pribadi). Tambahkan frontmatter YAML dengan name, description, tools opsional, dan model opsional, lalu tulis prompt sistem di isinya. Deskripsi memberi tahu Claude kapan harus mendelegasikannya secara otomatis.
Bagaimana Claude memutuskan sub-agen mana yang akan digunakan? Ia membaca bidang description dari setiap sub-agen yang tersedia dan mendelegasikan secara otomatis ketika tugas cocok. Anda juga dapat memanggilnya secara eksplisit berdasarkan nama, seperti "gunakan sub-agen *code-reviewer*." Deskripsi yang jelas dan bergaya pemicu membuat delegasi otomatis dapat diandalkan.
Apa perbedaan antara sub-agen dan Claude Agent SDK? Sub-agen dalam sesi dan diutus model: Anda bekerja di Claude Code dan ia memanggil spesialis. Agent SDK bersifat terprogram, di mana Anda menulis alur kontrol dalam kode untuk *run* yang deterministik atau tanpa pengawasan. Gunakan sub-agen untuk spesialisasi interaktif, SDK untuk *loop* terjadwal.
Bisakah sub-agen berjalan secara paralel? Ya. Agen utama dapat mengirim beberapa sub-agen sekaligus untuk tugas independen, sehingga peninjauan, pengujian, dan dokumentasi terjadi bersamaan daripada berurutan. Untuk *fan-out* skala besar, alur kerja dinamis Claude Code memperluas ini ke banyak sub-agen paralel dalam satu sesi.
Bagaimana sub-agen membantu pengujian API? Definisikan sub-agen yang menulis dan menjalankan tes API Anda terhadap *spec* OpenAPI. Ini menjadi *gate* verifikasi yang memeriksa apakah *endpoint* benar-benar berfungsi, bukan hanya apakah terlihat sudah selesai. Mengarahkannya ke platform seperti Apidog membuat umpan balik peka skema, sehingga setiap respons divalidasi terhadap kontrak.
Poin penting
Sub-agen Claude Code memecahkan masalah bahwa satu jendela konteks tidak dapat menampung segalanya. Dengan memberikan setiap tugas konteksnya sendiri, instruksi, dan alat, Anda menukar satu agen yang kewalahan dengan tim kecil spesialis yang bekerja secara paralel dan melaporkan kembali dengan bersih. Pengaturannya hanyalah file Markdown, dan imbalannya adalah fokus, kecepatan, dan kemampuan untuk menempatkan model yang tepat pada pekerjaan yang tepat.
Mulailah dengan dua: peninjau dan penguji. Tulis deskripsi yang ketat agar Claude mendelegasikan sendiri, berikan masing-masing hanya alat yang dibutuhkan, dan jadikan penguji *gate* verifikasi nyata dengan mengarahkannya ke *suite* API Anda. Untuk apa pun yang menyentuh *endpoint*, Apidog memberikan *gate* itu skema untuk diperiksa; unduh itu dan biarkan sub-agen tes membuktikan kode Anda berfungsi sebelum Anda membaca *diff*nya.