Subagent adalah asisten AI khusus yang menangani jenis tugas tertentu. Gunakan satu ketika tugas sampingan akan membanjiri percakapan utama Anda dengan hasil pencarian, log, atau konten file yang tidak akan Anda referensikan lagi: subagent melakukan pekerjaan itu dalam konteksnya sendiri dan hanya mengembalikan ringkasan. Tentukan subagent khusus ketika Anda terus menelurkan jenis pekerja yang sama dengan instruksi yang sama. Setiap subagent berjalan di jendela konteksnya sendiri dengan prompt sistem khusus, akses alat tertentu, dan izin independen. Ketika Claude menemukan tugas yang sesuai dengan deskripsi subagent, Claude mendelegasikan ke subagent tersebut, yang bekerja secara independen dan mengembalikan hasil. Untuk melihat penghematan konteks dalam praktik, visualisasi jendela konteks menjelaskan sesi di mana subagent menangani penelitian di jendela terpisahnya sendiri.Documentation Index
Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
Subagent bekerja dalam satu sesi. Untuk menjalankan banyak sesi independen secara paralel dan memantaunya dari satu tempat, lihat agen latar belakang. Untuk sesi yang berkomunikasi satu sama lain, lihat tim agen.
- Mempertahankan konteks dengan menjaga eksplorasi dan implementasi di luar percakapan utama Anda
- Menerapkan batasan dengan membatasi alat mana yang dapat digunakan subagent
- Menggunakan kembali konfigurasi di seluruh proyek dengan subagent tingkat pengguna
- Mengkhususkan perilaku dengan prompt sistem yang terfokus untuk domain tertentu
- Mengontrol biaya dengan merutekan tugas ke model yang lebih cepat dan lebih murah seperti Haiku
- Subagent bawaan
- Cara membuat subagent Anda sendiri
- Opsi konfigurasi lengkap
- Pola untuk bekerja dengan subagent
- Subagent yang di-fork
- Contoh subagent
Subagent bawaan
Claude Code mencakup subagent bawaan yang Claude gunakan secara otomatis jika sesuai. Masing-masing mewarisi izin percakapan induk dengan pembatasan alat tambahan.- Explore
- Plan
- General-purpose
- Other
Agen cepat yang dioptimalkan hanya-baca untuk mencari dan menganalisis basis kode.
- Model: Haiku (cepat, latensi rendah)
- Tools: Alat hanya-baca (akses ditolak ke alat Write dan Edit)
- Purpose: Penemuan file, pencarian kode, eksplorasi basis kode
Quickstart: buat subagent pertama Anda
Subagent didefinisikan dalam file Markdown dengan frontmatter YAML. Anda dapat membuatnya secara manual atau menggunakan perintah/agents.
Panduan ini memandu Anda melalui pembuatan subagent tingkat pengguna dengan perintah /agents. Subagent meninjau kode dan menyarankan perbaikan untuk basis kode.
Pilih lokasi
Beralih ke tab Library, pilih Create new agent, kemudian pilih Personal. Ini menyimpan subagent ke
~/.claude/agents/ sehingga tersedia di semua proyek Anda.Hasilkan dengan Claude
Pilih Generate with Claude. Ketika diminta, jelaskan subagent:Claude menghasilkan pengenal, deskripsi, dan prompt sistem untuk Anda.
Pilih alat
Untuk reviewer hanya-baca, batalkan pilihan semuanya kecuali Read-only tools. Jika Anda membiarkan semua alat dipilih, subagent mewarisi semua alat yang tersedia untuk percakapan utama.
Pilih model
Pilih model mana yang digunakan subagent. Untuk agen contoh ini, pilih Sonnet, yang menyeimbangkan kemampuan dan kecepatan untuk menganalisis pola kode.
Pilih warna
Pilih warna latar belakang untuk subagent. Ini membantu Anda mengidentifikasi subagent mana yang berjalan di UI.
Konfigurasi memori
Pilih User scope untuk memberikan subagent direktori memori persisten di
~/.claude/agent-memory/. Subagent menggunakan ini untuk mengumpulkan wawasan di seluruh percakapan, seperti pola basis kode dan masalah berulang. Pilih None jika Anda tidak ingin subagent mempertahankan pembelajaran.Konfigurasi subagent
Gunakan perintah /agents
Perintah/agents membuka antarmuka bertab untuk mengelola subagent. Tab Running menunjukkan subagent langsung dan memungkinkan Anda membuka atau menghentikannya. Tab Library memungkinkan Anda:
- Melihat semua subagent yang tersedia (bawaan, pengguna, proyek, dan plugin)
- Membuat subagent baru dengan setup terpandu atau generasi Claude
- Mengedit konfigurasi subagent yang ada dan akses alat
- Menghapus subagent khusus
- Melihat subagent mana yang aktif ketika duplikat ada
Pilih cakupan subagent
Subagent adalah file Markdown dengan frontmatter YAML. Simpan mereka di lokasi berbeda tergantung cakupan. Ketika beberapa subagent berbagi nama yang sama, lokasi prioritas lebih tinggi menang.| Lokasi | Cakupan | Prioritas | Cara membuat |
|---|---|---|---|
| Pengaturan terkelola | Seluruh organisasi | 1 (tertinggi) | Digunakan melalui pengaturan terkelola |
Flag CLI --agents | Sesi saat ini | 2 | Lewatkan JSON saat meluncurkan Claude Code |
.claude/agents/ | Proyek saat ini | 3 | Interaktif atau manual |
~/.claude/agents/ | Semua proyek Anda | 4 | Interaktif atau manual |
Direktori agents/ plugin | Tempat plugin diaktifkan | 5 (terendah) | Diinstal dengan plugins |
.claude/agents/) ideal untuk subagent khusus untuk basis kode. Periksa mereka ke kontrol versi sehingga tim Anda dapat menggunakannya dan meningkatkannya secara kolaboratif.
Subagent proyek ditemukan dengan berjalan naik dari direktori kerja saat ini. Direktori yang ditambahkan dengan --add-dir memberikan akses file saja dan tidak dipindai untuk subagent. Untuk berbagi subagent di seluruh proyek, gunakan ~/.claude/agents/ atau plugin.
Subagent pengguna (~/.claude/agents/) adalah subagent pribadi yang tersedia di semua proyek Anda.
Claude Code memindai .claude/agents/ dan ~/.claude/agents/ secara rekursif, sehingga Anda dapat mengorganisir definisi ke dalam subfolder seperti agents/review/ atau agents/research/. Jalur subdirektori tidak mempengaruhi cara subagent diidentifikasi atau dipanggil, karena identitas hanya berasal dari bidang frontmatter name. Jaga nilai name tetap unik di seluruh pohon: jika dua file dalam satu cakupan mendeklarasikan nama yang sama, Claude Code menyimpan satu dan membuang yang lain tanpa peringatan.
Direktori agents/ plugin juga dipindai secara rekursif. Tidak seperti cakupan proyek dan pengguna, subfolder di dalam direktori agents/ plugin menjadi bagian dari pengenal yang dibatasi cakupan: file di agents/review/security.md dalam plugin my-plugin terdaftar sebagai my-plugin:review:security.
Subagent yang ditentukan CLI dilewatkan sebagai JSON saat meluncurkan Claude Code. Mereka hanya ada untuk sesi itu dan tidak disimpan ke disk, menjadikannya berguna untuk pengujian cepat atau skrip otomasi. Anda dapat mendefinisikan beberapa subagent dalam satu panggilan --agents:
- macOS, Linux, WSL
- Windows PowerShell
--agents menerima JSON dengan frontmatter yang sama bidang subagent berbasis file: description, prompt, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, initialPrompt, memory, effort, background, isolation, dan color. Gunakan prompt untuk prompt sistem, setara dengan badan markdown dalam subagent berbasis file.
Subagent terkelola digunakan oleh administrator organisasi. Tempatkan file markdown dalam .claude/agents/ di dalam direktori pengaturan terkelola, menggunakan format frontmatter yang sama dengan subagent proyek dan pengguna. Definisi terkelola mengambil alih subagent proyek dan pengguna dengan nama yang sama.
Subagent plugin berasal dari plugins yang telah Anda instal. Mereka muncul di /agents bersama subagent khusus Anda. Lihat referensi komponen plugin untuk detail tentang membuat subagent plugin.
Untuk alasan keamanan, subagent plugin tidak mendukung bidang frontmatter
hooks, mcpServers, atau permissionMode. Bidang-bidang ini diabaikan saat memuat agen dari plugin. Jika Anda membutuhkannya, salin file agen ke dalam .claude/agents/ atau ~/.claude/agents/. Anda juga dapat menambahkan aturan ke permissions.allow dalam settings.json atau settings.local.json, tetapi aturan-aturan ini berlaku untuk seluruh sesi, bukan hanya subagent plugin.tools dan model-nya, dengan badan definisi ditambahkan ke prompt sistem rekan kerja sebagai instruksi tambahan. Lihat tim agen untuk bidang frontmatter mana yang berlaku pada jalur itu.
Tulis file subagent
File subagent menggunakan frontmatter YAML untuk konfigurasi, diikuti oleh prompt sistem dalam Markdown:Subagent dimuat saat awal sesi. Jika Anda menambah atau mengedit file subagent secara langsung di disk, restart sesi Anda untuk memuatnya. Subagent yang dibuat melalui antarmuka
/agents berlaku segera tanpa restart.cd tidak bertahan antara panggilan alat Bash atau PowerShell dan tidak mempengaruhi direktori kerja percakapan utama. Untuk memberikan subagent salinan repositori yang terisolasi sebagai gantinya, atur isolation: worktree.
Bidang frontmatter yang didukung
Bidang berikut dapat digunakan dalam frontmatter YAML. Hanyaname dan description yang diperlukan.
| Bidang | Diperlukan | Deskripsi |
|---|---|---|
name | Ya | Pengenal unik menggunakan huruf kecil dan tanda hubung. Hooks menerima nilai ini sebagai agent_type. Nama file tidak harus cocok |
description | Ya | Kapan Claude harus mendelegasikan ke subagent ini |
tools | Tidak | Alat yang dapat digunakan subagent. Mewarisi semua alat jika dihilangkan. Untuk memuat Skills ke dalam konteks, gunakan bidang skills daripada mencantumkan Skill di sini |
disallowedTools | Tidak | Alat untuk ditolak, dihapus dari daftar yang diwarisi atau ditentukan |
model | Tidak | Model untuk digunakan: sonnet, opus, haiku, ID model lengkap (misalnya, claude-opus-4-7), atau inherit. Default ke inherit |
permissionMode | Tidak | Mode izin: default, acceptEdits, auto, dontAsk, bypassPermissions, atau plan. Diabaikan untuk subagent plugin |
maxTurns | Tidak | Jumlah maksimum putaran agentic sebelum subagent berhenti |
skills | Tidak | Skills untuk dimuat ke dalam konteks subagent saat startup. Konten skill lengkap disuntikkan, bukan hanya deskripsi. Subagent masih dapat memanggil project, user, dan plugin skills yang tidak tercantum melalui alat Skill |
mcpServers | Tidak | MCP servers tersedia untuk subagent ini. Setiap entri adalah nama server yang mereferensikan server yang sudah dikonfigurasi (misalnya, "slack") atau definisi inline dengan nama server sebagai kunci dan konfigurasi MCP server lengkap sebagai nilai. Diabaikan untuk subagent plugin |
hooks | Tidak | Lifecycle hooks yang dibatasi pada subagent ini. Diabaikan untuk subagent plugin |
memory | Tidak | Cakupan memori persisten: user, project, atau local. Memungkinkan pembelajaran lintas sesi |
background | Tidak | Atur ke true untuk selalu menjalankan subagent ini sebagai background task. Default: false |
effort | Tidak | Tingkat usaha ketika subagent ini aktif. Menimpa tingkat usaha sesi. Default: mewarisi dari sesi. Opsi: low, medium, high, xhigh, max; tingkat yang tersedia tergantung pada model |
isolation | Tidak | Atur ke worktree untuk menjalankan subagent dalam git worktree sementara, memberikannya salinan repositori yang terisolasi. Worktree secara otomatis dibersihkan jika subagent tidak membuat perubahan |
color | Tidak | Warna tampilan untuk subagent dalam daftar tugas dan transkrip. Menerima red, blue, green, yellow, purple, orange, pink, atau cyan |
initialPrompt | Tidak | Auto-submitted sebagai putaran pengguna pertama ketika agen ini berjalan sebagai agen sesi utama (melalui --agent atau pengaturan agent). Commands dan skills diproses. Ditambahkan di depan prompt yang disediakan pengguna apa pun |
Pilih model
Bidangmodel mengontrol model AI mana yang digunakan subagent:
- Alias model: Gunakan salah satu alias yang tersedia:
sonnet,opus, atauhaiku - ID model lengkap: Gunakan ID model lengkap seperti
claude-opus-4-7atauclaude-sonnet-4-6. Menerima nilai yang sama dengan flag--model - inherit: Gunakan model yang sama dengan percakapan utama
- Dihilangkan: Jika tidak ditentukan, default ke
inherit(menggunakan model yang sama dengan percakapan utama)
model untuk invokasi spesifik itu. Claude Code menyelesaikan model subagent dalam urutan ini:
- Variabel lingkungan
CLAUDE_CODE_SUBAGENT_MODEL, jika diatur - Parameter
modelper-invokasi - Frontmatter
modeldefinisi subagent - Model percakapan utama
Kontrol kemampuan subagent
Anda dapat mengontrol apa yang dapat dilakukan subagent melalui akses alat, mode izin, dan aturan bersyarat.Alat yang tersedia
Subagent dapat menggunakan salah satu alat internal Claude Code. Secara default, subagent mewarisi semua alat dari percakapan utama, termasuk alat MCP. Untuk membatasi alat, gunakan bidangtools (allowlist) atau bidang disallowedTools (denylist). Contoh ini menggunakan tools untuk secara eksklusif mengizinkan Read, Grep, Glob, dan Bash. Subagent tidak dapat mengedit file, menulis file, atau menggunakan alat MCP apa pun:
disallowedTools untuk mewarisi setiap alat dari percakapan utama kecuali Write dan Edit. Subagent menyimpan Bash, alat MCP, dan semuanya yang lain:
disallowedTools diterapkan terlebih dahulu, kemudian tools diselesaikan terhadap kumpulan yang tersisa. Alat yang tercantum di keduanya dihapus.
Batasi subagent mana yang dapat dihasilkan
Ketika agen berjalan sebagai thread utama denganclaude --agent, agen dapat menelurkan subagent menggunakan alat Agent. Untuk membatasi jenis subagent mana yang dapat dihasilkan, gunakan sintaks Agent(agent_type) dalam bidang tools.
Dalam versi 2.1.63, alat Task diganti nama menjadi Agent. Referensi
Task(...) yang ada dalam pengaturan dan definisi agen masih berfungsi sebagai alias.worker dan researcher yang dapat dihasilkan. Jika agen mencoba menelurkan jenis lain, permintaan gagal dan agen hanya melihat jenis yang diizinkan dalam promptnya. Untuk memblokir agen tertentu sambil mengizinkan semua yang lain, gunakan permissions.deny sebagai gantinya.
Untuk mengizinkan penelur subagent apa pun tanpa pembatasan, gunakan Agent tanpa tanda kurung:
Agent dihilangkan dari daftar tools sepenuhnya, agen tidak dapat menelurkan subagent apa pun. Pembatasan ini hanya berlaku untuk agen yang berjalan sebagai thread utama dengan claude --agent. Subagent tidak dapat menelurkan subagent lain, jadi Agent(agent_type) tidak berpengaruh dalam definisi subagent.
Cakupan MCP servers ke subagent
Gunakan bidangmcpServers untuk memberikan subagent akses ke MCP servers yang tidak tersedia dalam percakapan utama. Server inline yang ditentukan di sini terhubung saat subagent dimulai dan terputus saat selesai. Referensi string berbagi koneksi sesi induk.
Bidang
mcpServers berlaku dalam kedua konteks di mana file agen dapat berjalan:- Sebagai subagent, dihasilkan melalui alat Agent atau @-mention
- Sebagai sesi utama, diluncurkan dengan
--agentatau pengaturanagent
.mcp.json dan file pengaturan..mcp.json (stdio, http, sse, ws), dikunci dengan nama server.
Untuk menjaga MCP server di luar percakapan utama sepenuhnya dan menghindari deskripsi alatnya mengonsumsi konteks di sana, tentukan secara inline di sini daripada di .mcp.json. Subagent mendapatkan alat; percakapan induk tidak.
Mode izin
BidangpermissionMode mengontrol bagaimana subagent menangani prompt izin. Subagent mewarisi konteks izin dari percakapan utama dan dapat menimpa mode, kecuali ketika mode induk mengambil alih seperti yang dijelaskan di bawah.
| Mode | Perilaku |
|---|---|
default | Pemeriksaan izin standar dengan prompt |
acceptEdits | Auto-terima edit file dan perintah sistem file umum untuk jalur di direktori kerja atau additionalDirectories |
auto | Auto mode: pengklasifikasi latar belakang meninjau perintah dan penulisan direktori yang dilindungi |
dontAsk | Auto-tolak prompt izin (alat yang secara eksplisit diizinkan masih berfungsi) |
bypassPermissions | Lewati prompt izin |
plan | Plan mode (eksplorasi hanya-baca) |
bypassPermissions atau acceptEdits, ini mengambil alih dan tidak dapat ditimpa. Jika induk menggunakan auto mode, subagent mewarisi auto mode dan permissionMode apa pun dalam frontmatternya diabaikan: pengklasifikasi mengevaluasi panggilan alat subagent dengan aturan blok dan izin yang sama dengan sesi induk.
Preload skills ke dalam subagent
Gunakan bidangskills untuk menyuntikkan konten skill ke dalam konteks subagent saat startup. Ini memberikan subagent pengetahuan domain tanpa memerlukan penemuan dan pemuatan skills selama eksekusi.
Skill dari daftar tools atau tambahkan ke disallowedTools.
Anda tidak dapat preload skills yang menetapkan disable-model-invocation: true, karena preloading menarik dari set skills yang sama yang dapat diinvokasi Claude. Jika skill yang tercantum hilang atau dinonaktifkan, Claude Code melewatinya dan mencatat peringatan ke debug log.
Ini adalah kebalikan dari menjalankan skill dalam subagent. Dengan
skills dalam subagent, subagent mengontrol prompt sistem dan memuat konten skill. Dengan context: fork dalam skill, konten skill disuntikkan ke dalam agen yang Anda tentukan. Keduanya menggunakan sistem yang mendasar yang sama.Aktifkan memori persisten
Bidangmemory memberikan subagent direktori persisten yang bertahan di seluruh percakapan. Subagent menggunakan direktori ini untuk membangun pengetahuan seiring waktu, seperti pola basis kode, wawasan debugging, dan keputusan arsitektur.
| Cakupan | Lokasi | Gunakan ketika |
|---|---|---|
user | ~/.claude/agent-memory/<name-of-agent>/ | subagent harus mengingat pembelajaran di seluruh semua proyek |
project | .claude/agent-memory/<name-of-agent>/ | pengetahuan subagent spesifik proyek dan dapat dibagikan melalui kontrol versi |
local | .claude/agent-memory-local/<name-of-agent>/ | pengetahuan subagent spesifik proyek tetapi tidak boleh diperiksa ke dalam kontrol versi |
- Prompt sistem subagent mencakup instruksi untuk membaca dan menulis ke direktori memori.
- Prompt sistem subagent juga mencakup 200 baris pertama atau 25KB dari
MEMORY.mddalam direktori memori, mana pun yang lebih kecil, dengan instruksi untuk mengkurasiMEMORY.mdjika melebihi batas itu. - Alat Read, Write, dan Edit secara otomatis diaktifkan sehingga subagent dapat mengelola file memorinya.
Tips memori persisten
-
projectadalah cakupan default yang direkomendasikan. Ini membuat pengetahuan subagent dapat dibagikan melalui kontrol versi. Gunakanuserketika pengetahuan subagent berlaku secara luas di seluruh proyek, ataulocalketika pengetahuan tidak boleh diperiksa ke dalam kontrol versi. - Minta subagent untuk berkonsultasi dengan memorinya sebelum memulai pekerjaan: “Review PR ini, dan periksa memori Anda untuk pola yang telah Anda lihat sebelumnya.”
- Minta subagent untuk memperbarui memorinya setelah menyelesaikan tugas: “Sekarang setelah Anda selesai, simpan apa yang Anda pelajari ke memori Anda.” Seiring waktu, ini membangun basis pengetahuan yang membuat subagent lebih efektif.
-
Sertakan instruksi memori langsung dalam file markdown subagent sehingga secara proaktif mempertahankan basis pengetahuannya sendiri:
Aturan bersyarat dengan hooks
Untuk kontrol yang lebih dinamis atas penggunaan alat, gunakan hooksPreToolUse untuk memvalidasi operasi sebelum dijalankan. Ini berguna ketika Anda perlu mengizinkan beberapa operasi alat sambil memblokir yang lain.
Contoh ini membuat subagent yang hanya mengizinkan kueri database hanya-baca. Hook PreToolUse menjalankan skrip yang ditentukan dalam command sebelum setiap perintah Bash dijalankan:
shell: powershell ke entri hook seperti yang ditunjukkan dalam menjalankan hooks dalam PowerShell.
Nonaktifkan subagent tertentu
Anda dapat mencegah Claude menggunakan subagent tertentu dengan menambahkannya ke arraydeny dalam pengaturan Anda. Gunakan format Agent(subagent-name) di mana subagent-name cocok dengan bidang nama subagent.
--disallowedTools:
Tentukan hooks untuk subagent
Subagent dapat mendefinisikan hooks yang berjalan selama siklus hidup subagent. Ada dua cara untuk mengonfigurasi hooks:- Dalam frontmatter subagent: Tentukan hooks yang hanya berjalan saat subagent tertentu itu aktif
- Dalam
settings.json: Tentukan hooks yang berjalan dalam sesi utama ketika subagent dimulai atau berhenti
Hooks dalam frontmatter subagent
Tentukan hooks langsung dalam file markdown subagent. Hooks ini hanya berjalan saat subagent spesifik itu aktif dan dibersihkan saat selesai.Frontmatter hooks terjadi ketika agen dihasilkan sebagai subagent melalui alat Agent atau @-mention, dan ketika agen berjalan sebagai sesi utama melalui
--agent atau pengaturan agent. Dalam kasus sesi-utama mereka berjalan bersama hook apa pun yang ditentukan dalam settings.json.| Peristiwa | Input Matcher | Kapan itu terjadi |
|---|---|---|
PreToolUse | Nama alat | Sebelum subagent menggunakan alat |
PostToolUse | Nama alat | Setelah subagent menggunakan alat |
Stop | (tidak ada) | Ketika subagent selesai (dikonversi ke SubagentStop saat runtime) |
PreToolUse dan menjalankan linter setelah edit file dengan PostToolUse:
Stop dalam frontmatter secara otomatis dikonversi ke peristiwa SubagentStop.
Hooks tingkat proyek untuk peristiwa subagent
Konfigurasi hooks dalamsettings.json yang merespons peristiwa siklus hidup subagent dalam sesi utama.
| Peristiwa | Input Matcher | Kapan itu terjadi |
|---|---|---|
SubagentStart | Nama jenis agen | Ketika subagent mulai dijalankan |
SubagentStop | Nama jenis agen | Ketika subagent selesai |
db-agent dimulai, dan skrip cleanup ketika subagent apa pun berhenti:
Bekerja dengan subagent
Pahami delegasi otomatis
Claude secara otomatis mendelegasikan tugas berdasarkan deskripsi tugas dalam permintaan Anda, bidangdescription dalam konfigurasi subagent, dan konteks saat ini. Untuk mendorong delegasi proaktif, sertakan frasa seperti “use proactively” dalam bidang deskripsi subagent Anda.
Panggil subagent secara eksplisit
Ketika delegasi otomatis tidak cukup, Anda dapat meminta subagent sendiri. Tiga pola meningkat dari saran satu kali ke default sesi-lebar:- Bahasa alami: sebutkan subagent dalam prompt Anda; Claude memutuskan apakah akan mendelegasikan
- @-mention: menjamin subagent berjalan untuk satu tugas
- Sesi-lebar: seluruh sesi menggunakan prompt sistem subagent, pembatasan alat, dan model melalui flag
--agentatau pengaturanagent
@ dan pilih subagent dari typeahead, dengan cara yang sama Anda @-mention file. Ini memastikan subagent tertentu berjalan daripada meninggalkan pilihan kepada Claude:
my-plugin:code-reviewer atau my-plugin:review:security ketika plugin mengorganisir agen ke dalam subfolder. Subagent background bernama yang saat ini berjalan dalam sesi juga muncul di typeahead, menunjukkan status mereka di samping nama. Anda juga dapat mengetik mention secara manual tanpa menggunakan picker: @agent-<name> untuk subagent lokal, atau @agent- diikuti dengan nama yang dibatasi untuk subagent plugin, misalnya @agent-my-plugin:code-reviewer.
Jalankan seluruh sesi sebagai subagent. Lewatkan --agent <name> untuk memulai sesi di mana thread utama itu sendiri mengambil prompt sistem subagent, pembatasan alat, dan model:
--system-prompt melakukannya. File CLAUDE.md dan memori proyek masih dimuat melalui aliran pesan normal. Nama agen muncul sebagai @<name> di header startup sehingga Anda dapat mengonfirmasi itu aktif.
Ini berfungsi dengan subagent bawaan dan khusus, dan pilihan bertahan ketika Anda melanjutkan sesi.
Untuk subagent yang disediakan plugin, lewatkan nama yang dibatasi: claude --agent <plugin-name>:<agent-name>. Jika plugin menempatkan agen dalam subfolder dari direktori agents/ nya, sertakan subfolder dalam nama yang dibatasi, misalnya claude --agent my-plugin:review:security.
Untuk menjadikannya default untuk setiap sesi dalam proyek, atur agent dalam .claude/settings.json:
Jalankan subagent di foreground atau background
Subagent dapat berjalan di foreground (blocking) atau background (concurrent):- Subagent foreground memblokir percakapan utama sampai selesai. Prompt izin dilewatkan kepada Anda saat muncul.
- Subagent background berjalan secara bersamaan sementara Anda terus bekerja. Mereka berjalan dengan izin yang sudah diberikan dalam sesi dan auto-deny setiap panggilan alat yang sebaliknya akan meminta. Jika subagent background perlu mengajukan pertanyaan klarifikasi, panggilan alat itu gagal tetapi subagent terus.
- Minta Claude untuk “run this in the background”
- Tekan Ctrl+B untuk menempatkan tugas yang sedang berjalan di background
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS ke 1. Lihat Environment variables.
Ketika fork mode diaktifkan, setiap spawn subagent berjalan di background terlepas dari bidang background. Fork masih menampilkan prompt izin di terminal Anda saat terjadi; subagent bernama auto-deny apa pun yang sebaliknya akan meminta, seperti dijelaskan di atas.
Pola umum
Isolasi operasi volume tinggi
Salah satu penggunaan paling efektif untuk subagent adalah mengisolasi operasi yang menghasilkan jumlah output besar. Menjalankan tes, mengambil dokumentasi, atau memproses file log dapat mengonsumsi konteks yang signifikan. Dengan mendelegasikan ini ke subagent, output verbose tetap dalam konteks subagent sementara hanya ringkasan relevan yang kembali ke percakapan utama Anda.Jalankan penelitian paralel
Untuk investigasi independen, hasilkan beberapa subagent untuk bekerja secara bersamaan:Rantai subagent
Untuk alur kerja multi-langkah, minta Claude untuk menggunakan subagent secara berurutan. Setiap subagent menyelesaikan tugasnya dan mengembalikan hasil ke Claude, yang kemudian melewatkan konteks relevan ke subagent berikutnya.Pilih antara subagent dan percakapan utama
Gunakan percakapan utama ketika:- Tugas memerlukan bolak-balik yang sering atau penyempurnaan iteratif
- Beberapa fase berbagi konteks yang signifikan (perencanaan → implementasi → pengujian)
- Anda membuat perubahan cepat dan tertarget
- Latensi penting. Subagent dimulai segar dan mungkin memerlukan waktu untuk mengumpulkan konteks
- Tugas menghasilkan output verbose yang Anda tidak butuhkan dalam konteks utama Anda
- Anda ingin menerapkan pembatasan alat atau izin tertentu
- Pekerjaan mandiri dan dapat mengembalikan ringkasan
/btw sebagai gantinya dari subagent. Ini melihat konteks penuh Anda tetapi tidak memiliki akses alat, dan jawabannya dibuang daripada ditambahkan ke riwayat.
Subagent tidak dapat menelurkan subagent lain. Jika alur kerja Anda memerlukan delegasi bersarang, gunakan Skills atau rantai subagent dari percakapan utama.
Kelola konteks subagent
Lanjutkan subagent
Setiap invokasi subagent membuat instance baru dengan konteks segar. Untuk melanjutkan pekerjaan subagent yang ada daripada memulai dari awal, minta Claude untuk melanjutkannya. Subagent yang dilanjutkan mempertahankan riwayat percakapan lengkap mereka, termasuk semua panggilan alat sebelumnya, hasil, dan penalaran. Subagent melanjutkan tepat di mana ia berhenti daripada memulai segar. Ketika subagent selesai, Claude menerima ID agennya. Claude menggunakan alatSendMessage dengan ID agen sebagai bidang to untuk melanjutkannya. Alat SendMessage hanya tersedia ketika tim agen diaktifkan melalui CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
Untuk melanjutkan subagent, minta Claude untuk melanjutkan pekerjaan sebelumnya:
SendMessage, ia auto-resume di background tanpa memerlukan invokasi Agent baru.
Anda juga dapat meminta Claude untuk ID agen jika Anda ingin mereferensikannya secara eksplisit, atau temukan ID dalam file transkrip di ~/.claude/projects/{project}/{sessionId}/subagents/. Setiap transkrip disimpan sebagai agent-{agentId}.jsonl.
Transkrip subagent bertahan secara independen dari percakapan utama:
- Pemadatan percakapan utama: Ketika percakapan utama dipadatkan, transkrip subagent tidak terpengaruh. Mereka disimpan dalam file terpisah.
- Persistensi sesi: Transkrip subagent bertahan dalam sesi mereka. Anda dapat melanjutkan subagent setelah memulai ulang Claude Code dengan melanjutkan sesi yang sama.
- Pembersihan otomatis: Transkrip dibersihkan berdasarkan pengaturan
cleanupPeriodDays(default: 30 hari).
Auto-compaction
Subagent mendukung pemadatan otomatis menggunakan logika yang sama dengan percakapan utama. Secara default, auto-compaction dipicu pada kapasitas sekitar 95%. Untuk memicu pemadatan lebih awal, aturCLAUDE_AUTOCOMPACT_PCT_OVERRIDE ke persentase yang lebih rendah (misalnya, 50). Lihat environment variables untuk detail.
Peristiwa pemadatan dicatat dalam file transkrip subagent:
preTokens menunjukkan berapa banyak token yang digunakan sebelum pemadatan terjadi.
Fork percakapan saat ini
Subagent yang di-fork bersifat eksperimental dan memerlukan Claude Code v2.1.117 atau lebih baru. Perilaku dan konfigurasi mungkin berubah di rilis mendatang. Aktifkan mereka dengan menetapkan variabel lingkungan
CLAUDE_CODE_FORK_SUBAGENT ke 1. Variabel ini dihormati dalam mode interaktif dan melalui SDK atau claude -p.- Claude menelurkan fork setiap kali Claude akan menggunakan subagent general-purpose. Subagent bernama seperti Explore masih menelurkan seperti sebelumnya.
- Setiap spawn subagent berjalan di background, apakah itu fork atau subagent bernama. Atur
CLAUDE_CODE_DISABLE_BACKGROUND_TASKSke1untuk menjaga spawn tetap sinkron. - Perintah
/forkmenelurkan fork daripada bertindak sebagai alias untuk/branch.
/fork diikuti oleh direktif. Claude Code memberi nama fork dari kata-kata pertama direktif. Contoh berikut mem-fork percakapan untuk draft kasus uji sementara Anda melanjutkan dengan implementasi dalam sesi utama:
Amati dan arahkan fork yang sedang berjalan
Fork yang sedang berjalan muncul di panel di bawah input prompt, dengan satu baris untuk sesi utama dan satu untuk setiap fork. Gunakan kunci ini untuk berinteraksi dengan panel:| Kunci | Tindakan |
|---|---|
↑ / ↓ | Pindah antar baris |
Enter | Buka transkrip fork yang dipilih dan kirimkan pesan tindak lanjut |
x | Tutup fork yang selesai atau hentikan yang sedang berjalan |
Esc | Kembalikan fokus ke input prompt |
Bagaimana fork berbeda dari subagent bernama
Fork mewarisi segalanya yang dimiliki sesi utama pada saat spawn. Subagent bernama dimulai dari definisinya sendiri.| Fork | Subagent bernama | |
|---|---|---|
| Konteks | Riwayat percakapan lengkap | Konteks segar dengan prompt yang Anda lewatkan |
| Prompt sistem dan alat | Sama dengan sesi utama | Dari file definisi subagent |
| Model | Sama dengan sesi utama | Dari bidang model subagent |
| Izin | Prompt muncul di terminal Anda | Pra-disetujui sebelum peluncuran, kemudian auto-ditolak |
| Prompt cache | Dibagikan dengan sesi utama | Cache terpisah |
isolation: "worktree" sehingga edit file fork ditulis ke git worktree terpisah daripada checkout Anda.
Keterbatasan
MenetapkanCLAUDE_CODE_FORK_SUBAGENT=1 mengaktifkan fork mode dalam sesi interaktif, non-interactive mode, dan Agent SDK. Fork tidak dapat menelurkan fork lebih lanjut.
Contoh subagent
Contoh-contoh ini mendemonstrasikan pola efektif untuk membangun subagent. Gunakan mereka sebagai titik awal, atau hasilkan versi yang disesuaikan dengan Claude.Peninjau kode
Subagent hanya-baca yang meninjau kode tanpa memodifikasinya. Contoh ini menunjukkan cara merancang subagent yang terfokus dengan akses alat terbatas (tidak ada Edit atau Write) dan prompt terperinci yang menentukan dengan tepat apa yang harus dicari dan cara memformat output.Debugger
Subagent yang dapat menganalisis dan memperbaiki masalah. Tidak seperti peninjau kode, yang ini mencakup Edit karena memperbaiki bug memerlukan memodifikasi kode. Prompt menyediakan alur kerja yang jelas dari diagnosis ke verifikasi.Data scientist
Subagent khusus domain untuk pekerjaan analisis data. Contoh ini menunjukkan cara membuat subagent untuk alur kerja khusus di luar tugas pengkodean khas. Ini secara eksplisit menetapkanmodel: sonnet untuk analisis yang lebih mampu.
Validator kueri database
Subagent yang memungkinkan akses Bash tetapi memvalidasi perintah untuk mengizinkan hanya kueri SQL hanya-baca. Contoh ini menunjukkan cara menggunakan hooksPreToolUse untuk validasi bersyarat ketika Anda memerlukan kontrol lebih halus daripada bidang tools.
command dalam konfigurasi hook Anda:
shell: powershell ke entri hook. Lihat menjalankan hooks dalam PowerShell.
Hook menerima JSON melalui stdin dengan perintah Bash dalam tool_input.command. Kode keluar 2 memblokir operasi dan mengirimkan pesan kesalahan kembali ke Claude. Lihat Hooks untuk detail tentang kode keluar dan Hook input untuk skema input lengkap.
Langkah berikutnya
Sekarang setelah Anda memahami subagent, jelajahi fitur terkait ini:- Distribusikan subagent dengan plugins untuk berbagi subagent di seluruh tim atau proyek
- Jalankan Claude Code secara terprogram dengan Agent SDK untuk CI/CD dan otomasi
- Gunakan MCP servers untuk memberikan subagent akses ke alat dan data eksternal