Buat subagen kustom

Buat dan gunakan subagen AI khusus di Claude Code untuk alur kerja spesifik tugas dan manajemen konteks yang lebih baik.

Subagen 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: subagen melakukan pekerjaan itu dalam konteksnya sendiri dan mengembalikan hanya ringkasannya. Tentukan subagen kustom ketika Anda terus-menerus menjalankan jenis pekerja yang sama dengan instruksi yang sama.

Setiap subagen berjalan dalam jendela konteksnya sendiri dengan prompt sistem kustom, akses alat tertentu, dan izin independen. Subagen juga mengirimkan permintaannya sendiri, yang dihitung terhadap batas penggunaan yang sama dengan percakapan utama Anda. Ketika Claude menemukan tugas yang cocok dengan deskripsi subagen, Claude mendelegasikan ke subagen tersebut, yang bekerja secara independen dan mengembalikan hasil. Untuk melihat penghematan konteks dalam praktik, visualisasi jendela konteks menjelaskan sesi di mana subagen menangani penelitian dalam jendela terpisahnya sendiri.

[!NOTE]

Subagen bekerja dalam satu sesi. Untuk menjalankan banyak sesi independen secara paralel dan memantaunya dari satu tempat, lihat agen latar belakang. Untuk sesi terpisah yang mengirimkan pesan satu sama lain, lihat pesan lintas sesi. Untuk tim sesi yang terkoordinasi yang Claude buat dan awasi, lihat tim agen.

Subagen membantu Anda:

• Pertahankan konteks dengan menjaga eksplorasi dan implementasi di luar percakapan utama Anda
• Terapkan batasan dengan membatasi alat mana yang dapat digunakan subagen
• Gunakan kembali konfigurasi di seluruh proyek dengan subagen tingkat pengguna
• Spesialisasi perilaku dengan prompt sistem yang terfokus untuk domain tertentu
• Kontrol biaya dengan merutekan tugas ke model yang lebih cepat dan lebih murah seperti Haiku

Claude menggunakan deskripsi setiap subagen untuk memutuskan kapan mendelegasikan tugas. Ketika Anda membuat subagen, tulis deskripsi yang jelas sehingga Claude tahu kapan menggunakannya.

Deskripsi tersebut menggunakan konteks, jadi simpan deskripsi tetap singkat. Ketika deskripsi gabungan subagen Anda, kecuali yang bawaan, melebihi 15.000 token, Claude Code menampilkan peringatan saat startup dengan jumlah token total. Potong bidang description subagen Anda, dan pindahkan detail ke prompt sistem setiap subagen, yang hanya dimuat ketika subagen tersebut berjalan.

Subagent bawaan

Claude Code mencakup subagent bawaan yang Claude gunakan secara otomatis jika sesuai. Masing-masing mewarisi aturan izin percakapan induk; sebagian besar berjalan dengan set alat yang terbatas.

Explore dan Plan dimulai tanpa file CLAUDE.md Anda dan snapshot status git untuk menjaga penelitian tetap cepat dan hemat biaya. Subagent bawaan lainnya dan subagent khusus memuat keduanya, kecuali Anda menetapkan omitClaudeMd dalam definisi subagent khusus untuk memulainya tanpa file CLAUDE.md pengguna, proyek, dan lokal. Untuk rincian lengkap tentang apa yang mencapai subagent, lihat apa yang dimuat saat startup.

[tab] Explore

Agen cepat yang dioptimalkan hanya-baca untuk mencari dan menganalisis basis kode.

• Model: model percakapan utama. Ketika percakapan utama menjalankan Fable, model Explore bergantung pada cara Anda terhubung:
  • Dengan langganan Claude, akun Anthropic Console, atau LLM gateway yang dijangkau melalui ANTHROPIC_BASE_URL, Explore berjalan pada model Opus yang dirujuk oleh alias opus.
  • Di Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, Claude Platform on AWS, atau Claude apps gateway, Explore tetap menggunakan model percakapan utama.
• Tools: tool read-only; Write dan Edit ditolak
• Purpose: penemuan file, pencarian kode, eksplorasi codebase

User atau project subagent bernama Explore menimpa yang bawaan dan menyimpan bidang model miliknya sendiri, jadi tentukan satu dengan model: haiku untuk menjalankan eksplorasi pada model dengan biaya lebih rendah. Untuk memaksakan satu model ke setiap subagent, termasuk Explore, lihat Jalankan setiap subagent pada satu model.

Claude mendelegasikan ke Explore ketika perlu mencari atau memahami basis kode tanpa membuat perubahan. Ini menjaga hasil eksplorasi di luar konteks percakapan utama Anda.

Saat memanggil Explore, Claude menentukan tingkat ketelitian: quick untuk pencarian yang ditargetkan, medium untuk eksplorasi seimbang, atau very thorough untuk analisis komprehensif.

[tab] Plan

Agen penelitian yang digunakan selama plan mode untuk mengumpulkan konteks sebelum menyajikan rencana.

• Model: mewarisi dari percakapan utama, kecuali Anda menetapkan CLAUDE_CODE_SUBAGENT_MODEL dan memaksanya ke setiap subagent
• Tools: alat hanya-baca; Write dan Edit ditolak
• Purpose: penelitian basis kode untuk perencanaan

Ketika Anda dalam plan mode dan Claude perlu memahami basis kode Anda, Claude mendelegasikan penelitian ke subagent Plan sehingga output eksplorasi tetap dalam jendela konteks terpisah sementara percakapan utama tetap hanya-baca.

[tab] General-purpose

Agen yang mampu untuk tugas kompleks multi-langkah yang memerlukan eksplorasi dan tindakan.

• Model: model CLAUDE_CODE_SUBAGENT_MODEL jika Anda menetapkan satu dan tidak ada yang menetapkan model dengan cara lain, jika tidak model percakapan utama; Pilih model menyatakan urutan lengkap, dan Jalankan setiap subagent pada satu model menunjukkan cara membuat variabel menggantikan sumber-sumber tersebut
• Tools: setiap alat tersedia untuk subagent
• Purpose: penelitian kompleks, operasi multi-langkah, modifikasi kode

Claude mendelegasikan ke general-purpose ketika tugas memerlukan eksplorasi dan modifikasi, penalaran kompleks untuk menafsirkan hasil, atau beberapa langkah yang saling bergantung.

[tab] Other

Claude Code mencakup agen pembantu tambahan untuk tugas tertentu. Ini biasanya dipanggil secara otomatis, jadi Anda tidak perlu menggunakannya secara langsung.

Agen	Model	Kapan Claude menggunakannya
claude	Tidak ada miliknya sendiri; mengikuti urutan model ketika Claude menelurkannya sebagai subagent	Ketika tugas tidak sesuai dengan agen yang lebih khusus. Catch-all dengan setiap alat tersedia untuk subagent. Juga agen default untuk sesi latar belakang yang dikirim; mode izin mana yang dimulainya tergantung pada cara sesi dimulai
statusline-setup	Sonnet	Ketika Anda menjalankan /statusline untuk mengonfigurasi baris status Anda
claude-code-guide	Haiku	Ketika Anda mengajukan pertanyaan tentang fitur Claude Code

Subagent bawaan terdaftar secara default dalam sesi interaktif. Untuk membatasi mereka:

• Untuk memblokir tipe bawaan tertentu, tambahkan ke permissions.deny seperti yang ditunjukkan dalam Nonaktifkan subagent tertentu.
• Untuk mencegah Claude mendelegasikan ke subagent apa pun, tolak alat Agent itu sendiri dengan permissions.deny.
• Untuk menghapus hanya subagent bawaan Explore dan Plan, atur CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1. Claude membaca dan mengeksplorasi file secara langsung alih-alih mendelegasikan ke mereka. Memerlukan Claude Code v2.1.198 atau lebih baru.
• Dalam mode non-interaktif dan Agent SDK, atur CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 untuk menghapus semua tipe bawaan dan menyediakan hanya milik Anda sendiri.

Panggilan alat Agent yang menghilangkan subagent_type gagal dengan subagent_type is required ketika sesi tidak memiliki subagent general-purpose untuk kembali.

Selain subagent bawaan ini, Anda dapat membuat subagent Anda sendiri dengan prompt khusus, pembatasan alat, mode izin, hooks, dan skills. Bagian berikut menunjukkan cara memulai dan menyesuaikan subagent.

Mulai cepat: buat subagent pertama Anda

Subagent adalah file Markdown dengan frontmatter YAML. Untuk membuat satu, minta Claude menulisnya untuk Anda, atau tulis file sendiri.

Panduan ini membuat subagent tingkat pengguna yang meninjau kode dan menyarankan perbaikan.

1. Minta Claude membuat subagent

Di Claude Code, jelaskan subagent yang Anda inginkan dan di mana menyimpannya:

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude menulis file dengan name, description, daftar tools, model, dan system prompt.

2. Tinjau file

Buka ~/.claude/agents/code-improver.md dan konfirmasi frontmatter sesuai dengan yang Anda minta. Hasilnya terlihat seperti ini:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Karena file berada di ~/.claude/agents/, subagent tersedia di setiap proyek di mesin Anda. Untuk membatasi ke satu proyek saja, pindahkan ke direktori .claude/agents/ proyek tersebut. Pilih cakupan subagent membandingkan keduanya.

3. Coba

Minta Claude mendelegasikan ke subagent baru:

Use the code-improver agent to suggest improvements in this project

Claude mendelegasikan ke subagent baru Anda, yang memindai basis kode dan mengembalikan saran perbaikan. Dalam transkrip, delegasi muncul sebagai baris panggilan tool yang menunjukkan nama subagent diikuti oleh deskripsi tugas singkat, seperti code-improver(Suggest code improvements).

Jika Claude tidak dapat menemukan subagent baru, mulai ulang Claude Code dan coba lagi. Ini terjadi hanya ketika ~/.claude/agents/ tidak ada sebelum sesi dimulai, karena sesi yang berjalan tidak mendeteksi direktori agents yang baru dibuat.

Anda sekarang memiliki subagent yang dapat Anda gunakan di proyek apa pun di mesin Anda untuk menganalisis basis kode dan menyarankan perbaikan.

Anda juga dapat menulis file subagent secara manual, mendefinisikannya melalui flag CLI, atau mendistribusikannya melalui plugin. Bagian berikut mencakup semua opsi konfigurasi.

[!NOTE]

Menjalankan /agents mencetak pengingat untuk meminta Claude atau mengedit .claude/agents/ dan ~/.claude/agents/ secara langsung. Pada Claude Code v2.1.197 dan lebih awal, /agents membuka wizard interaktif dengan tab Running yang mencantumkan subagent aktif dan tab Library untuk membuat, mengedit, dan menghapusnya.

Mengonfigurasi subagent

Lokasi file subagent menentukan siapa yang dapat menggunakannya, dan frontmatter-nya menentukan apa yang dapat dilakukannya. Bagian ini membahas di mana file subagent disimpan dan setiap field yang didukungnya.

Memilih cakupan subagent

Simpan file subagent di lokasi yang berbeda tergantung pada cakupannya. Ketika beberapa subagent memiliki nama yang sama, Claude Code menggunakan subagent dari lokasi dengan prioritas lebih tinggi.

Subagent proyek (.claude/agents/) ideal untuk subagent yang spesifik untuk sebuah codebase. Masukkan ke dalam version control agar tim Anda dapat menggunakan dan menyempurnakannya secara kolaboratif.

Subagent proyek ditemukan dengan menelusuri ke atas dari direktori kerja saat ini, sehingga setiap .claude/agents/ di antara direktori tersebut dan root repositori dipindai. Ketika lebih dari satu direktori bertingkat ini mendefinisikan name yang sama, Claude Code menggunakan definisi yang paling dekat dengan direktori kerja.

Ketika Anda menambahkan direktori dengan --add-dir atau /add-dir, Claude Code juga memuat folder .claude/agents/ miliknya, bersama dengan subagent proyek Anda. Lihat Direktori tambahan untuk mengetahui jenis konfigurasi lain yang dimuat dari --add-dir. Untuk berbagi subagent antarproyek tanpa --add-dir, gunakan ~/.claude/agents/ atau sebuah 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 mengatur definisi ke dalam subfolder seperti agents/review/ atau agents/research/. Path subdirektori tidak memengaruhi cara subagent diidentifikasi atau dipanggil, karena identitas hanya berasal dari field frontmatter name.

Jaga agar nilai name unik di seluruh pohon direktori: jika dua file di bawah direktori .claude/agents/ yang sama, termasuk subfoldernya, mendeklarasikan nama yang sama, Claude Code hanya memuat salah satunya, yang dipilih berdasarkan urutan pembacaan sistem file, bukan berdasarkan prioritas yang terdokumentasi. Di antara direktori proyek bertingkat, definisi yang paling dekat dengan direktori kerja yang menang, seperti dijelaskan di atas. Pemeriksaan penyiapan /doctor melaporkan file dalam direktori yang sama yang memiliki nama sama dan mengusulkan untuk mengganti nama atau menghapus semuanya kecuali satu.

Direktori agents/ plugin juga dipindai secara rekursif. Berbeda dengan cakupan proyek dan pengguna, subfolder di dalam direktori agents/ plugin menjadi bagian dari identifier bercakupan: file di agents/review/security.md dalam plugin my-plugin terdaftar sebagai my-plugin:review:security.

Subagent yang didefinisikan melalui CLI diberikan sebagai JSON saat meluncurkan Claude Code. Subagent ini hanya ada untuk sesi tersebut dan tidak disimpan ke disk, sehingga berguna untuk pengujian cepat atau skrip otomatisasi. Anda dapat mendefinisikan beberapa subagent dalam satu panggilan --agents:

[tab] macOS, Linux, WSL

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

[tab] Windows PowerShell

claude --agents @'
{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}
'@

Dalam mode non-interaktif, --agents juga menerima path ke file JSON yang berisi objek yang sama, untuk definisi yang terlalu besar untuk diberikan di command line. Misalnya, claude -p --agents ./agents.json "Review my changes" membaca definisi dari file tersebut. Dalam sesi interaktif, Claude Code menolak path file. Bentuk file memerlukan Claude Code v2.1.281 atau yang lebih baru.

Setiap key tingkat atas dalam JSON adalah nama sebuah agent, dan nilainya adalah definisi agent tersebut. Jangan awali nama dengan -. Sebuah definisi menerima field berikut:

• prompt: system prompt agent, setara dengan isi markdown dalam subagent berbasis file. prompt boleh kosong. Jika Anda memilih agent dengan prompt kosong dan tanpa field memory sebagai agent sesi dengan --agent, system prompt sesi dibiarkan tidak berubah. prompt kosong memerlukan Claude Code v2.1.281 atau yang lebih baru.
• Field frontmatter: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, autoCompactWindow, skills, initialPrompt, memory, effort, background, omitClaudeMd, dan isolation.
• Field yang diabaikan: color dan experimental tidak diterima di sini dan diabaikan alih-alih ditolak.

Untuk mengetahui apa yang dilakukan Claude Code terhadap nilai yang tidak dapat dimuatnya, serta flag dan environment variable yang melewati pemeriksaan tersebut, lihat Invalid --agents configuration.

Subagent terkelola di-deploy oleh administrator organisasi. Tempatkan file markdown di .claude/agents/ di dalam direktori pengaturan terkelola, menggunakan format frontmatter yang sama dengan subagent proyek dan pengguna. Definisi terkelola diutamakan daripada subagent proyek dan pengguna dengan nama yang sama.

Subagent plugin berasal dari plugin yang telah Anda instal. Subagent ini dimuat secara otomatis bersama subagent kustom Anda dan muncul di typeahead @-mention dengan nama bercakupannya. Lihat referensi komponen plugin untuk detail tentang cara membuat subagent plugin.

[!NOTE]

Untuk alasan keamanan, subagent plugin tidak mendukung field frontmatter hooks, mcpServers, atau permissionMode. Field ini diabaikan saat memuat agent dari plugin. Jika Anda membutuhkannya, salin file agent ke .claude/agents/ atau ~/.claude/agents/. Anda juga dapat menambahkan aturan ke permissions.allow di settings.json atau settings.local.json, tetapi aturan ini berlaku untuk seluruh sesi, bukan hanya subagent plugin.

Jika Anda adalah pembuat plugin, sertakan hook di hooks/hooks.json milik plugin dan server MCP di .mcp.json miliknya sebagai gantinya. Keduanya berlaku setiap kali plugin diaktifkan, bukan hanya di dalam subagent.

Anda juga dapat menggunakan ulang definisi subagent sebagai teammate tim agent: sebutkan jenis subagent saat Anda meminta Claude memunculkan teammate, dan Claude Code menerapkan sebagian definisi tersebut padanya. Menggunakan definisi subagent untuk teammate menjelaskan cakupan mana dan bagian mana yang berlaku di setiap mode tampilan.

Menulis file subagent

File subagent menggunakan frontmatter YAML untuk konfigurasi, diikuti oleh system prompt dalam Markdown:

[!NOTE]

Claude Code memantau ~/.claude/agents/ dan .claude/agents/. Ketika Anda menambahkan atau mengedit file subagent di disk, atau meminta Claude menuliskannya untuk Anda, Claude Code mendeteksi perubahan dalam beberapa detik dan delegasi berikutnya menggunakan definisi yang diperbarui, tanpa perlu memulai ulang.

Tiga kasus masih memerlukan mulai ulang:

• Pemantau hanya mencakup direktori yang sudah ada saat sesi dimulai, jadi setelah membuat file agent pertama untuk suatu cakupan di direktori agents baru, mulai ulang untuk memuatnya.
• Claude Code tidak memantau .claude/agents/ di dalam direktori yang ditambahkan dengan --add-dir atau /add-dir, jadi setelah menambahkan atau mengedit subagent di sana, mulai ulang untuk memuat perubahan.
• Sesi yang dimulai dengan --disable-slash-commands sama sekali tidak memantau direktori ini.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Frontmatter mendefinisikan metadata dan konfigurasi subagent. Isinya menjadi system prompt yang memandu perilaku subagent. Subagent hanya menerima system prompt ini ditambah detail lingkungan dasar seperti direktori kerja, bukan system prompt Claude Code.

Dalam mode non-interaktif, berikan --append-subagent-system-prompt untuk menambahkan teks Anda ke akhir system prompt setiap subagent, termasuk subagent bertingkat, kecuali subagent fork, yang menggunakan ulang prompt milik percakapan itu sendiri. Memerlukan Claude Code v2.1.205 atau yang lebih baru. Jika teks Anda terlalu panjang untuk diberikan di command line, simpan ke sebuah file dan berikan path-nya dengan --append-subagent-system-prompt-file sebagai gantinya. Flag file memerlukan Claude Code v2.1.261 atau yang lebih baru.

Subagent dimulai di direktori kerja saat ini milik percakapan utama. Di dalam subagent, perintah cd tidak bertahan di antara panggilan tool Bash atau PowerShell dan tidak memengaruhi direktori kerja percakapan utama. Untuk memberikan salinan repositori yang terisolasi kepada subagent, tetapkan isolation: worktree.

Subagent dengan isolation: worktree menjalankan perintah Bash dan PowerShell-nya di dalam worktree-nya. Perintah yang direktori kerjanya justru di-resolve ke checkout utama Anda, misalnya karena direktori worktree dihapus saat subagent sedang berjalan, gagal dengan error.

Pemeriksaan direktori kerja ini mencakup seluruh repositori yang berisi direktori tempat Anda meluncurkan Claude Code. Ketika sesi Anda berjalan di worktree tertaut miliknya sendiri, pemeriksaan ini juga mencakup checkout utama yang ditautkan oleh worktree tersebut.

Untuk perintah Bash, Claude Code juga memeriksa perintah itu sendiri dengan dua cara:

• Claude Code memblokir perintah yang mengalihkan git ke checkout utama.
• Claude Code menolak perintah ketika tidak dapat memverifikasi dari teks perintah bahwa setiap git yang dijalankan perintah tetap berada di dalam worktree, misalnya ketika nama perintah dihitung saat runtime.

Vektor pengalihan dan aturan bentuk tercantum di Cara Claude Code menegakkan isolasi. Perintah PowerShell hanya mendapatkan pemeriksaan direktori kerja.

Perintah Monitor melewati pemeriksaan direktori kerja dan isi perintah yang sama dengan perintah Bash.

Ketika percakapan utama itu sendiri berjalan terisolasi di worktree, Claude Code menerapkan pemeriksaan yang sama pada sesi dan pada setiap subagent yang dimunculkannya, termasuk subagent tanpa isolation: worktree; lihat Cara Claude Code menegakkan isolasi.

Referensi frontmatter

Konfigurasikan subagent dengan frontmatter YAML di antara penanda --- di bagian atas filenya, dan tulis system prompt-nya sebagai Markdown setelah --- penutup. Hanya name dan description yang wajib.

Nama field yang terdiri dari beberapa kata menggunakan camelCase, seperti maxTurns dan disallowedTools, dan harus persis sama dengan tabel: Claude Code mengabaikan field yang tidak dikenalinya tanpa melaporkan error.

• Untuk menemukan field yang salah eja dalam subagent yang berhasil dimuat, jalankan claude --debug di shell Anda dan cari does not recognize or apply di log debug pada ~/.claude/debug/<session-id>.txt. Log debug menyebutkan hingga lima field tingkat atas dalam file subagent yang tidak dikenali Claude Code, beserta nama yang kemungkinan dimaksud ketika ada field yang didukung yang mirip. Memerlukan Claude Code v2.1.296 atau yang lebih baru.
• Untuk mengetahui mengapa file subagent tidak dimuat, lihat File subagent yang dilewati Claude Code.

Tulis cacheTtl di dalam map experimental, bukan di tingkat atas frontmatter.

---
name: repo-auditor
description: Audits a large repository and reports what it finds
experimental:
  cacheTtl: 1h
---

File subagent yang dilewati Claude Code

Claude Code melewati file di direktori agents proyek, pengguna, atau terkelola, atau di direktori di bawah direktori yang Anda tambahkan dengan --add-dir, tanpa melaporkannya dalam sesi, ketika frontmatter memiliki salah satu masalah berikut:

• Tidak ada name: Claude Code memperlakukan file tersebut sebagai dokumentasi yang disimpan di samping agent Anda.
• --- pembuka yang bukan baris pertama file: Claude Code membaca file tersebut sebagai tidak memiliki frontmatter dan memperlakukannya sebagai dokumentasi.
• name yang diawali dengan -, mengandung :, atau lebih panjang dari 256 karakter: Claude Code melewati file tersebut dan menulis error ke log debug.
• Ada name tetapi tidak ada description: Claude Code melewati file tersebut dan menulis alasannya ke log debug.
• YAML yang tidak dapat di-parse: Claude Code tidak membaca field apa pun dari file tersebut, melewatinya, dan menulis error parse ke log debug.

Untuk melihat log debug, jalankan Claude Code dengan --debug.

Subagent plugin yang frontmatter-nya tidak memiliki name atau tidak dapat di-parse tetap dimuat, dengan nama filenya.

Memeriksa direktori agents sebelum sesi

Untuk menemukan file di direktori agents yang frontmatter-nya tidak dapat di-parse, jalankan claude plugin validate terhadap direktori tersebut, misalnya .claude/agents atau ~/.claude/agents. Claude Code hanya memeriksa direktori yang Anda sebutkan, dan tidak menandai file yang frontmatter-nya dapat di-parse tetapi tidak memiliki name. Memerlukan Claude Code v2.1.233 atau yang lebih baru.

Memilih model

Field model mengontrol model mana yang digunakan subagent:

• Alias model: gunakan salah satu alias yang tersedia: sonnet, opus, haiku, atau fable
• ID model lengkap: gunakan ID model lengkap seperti claude-opus-5-5 atau claude-sonnet-5. Menerima nilai yang sama dengan flag --model
• inherit: gunakan model yang sama dengan percakapan utama

Ketika Claude memanggil subagent, Claude juga dapat memberikan parameter model untuk pemanggilan spesifik tersebut. Pada panggilan tool Agent, parameter tersebut menerima alias model: sonnet, opus, haiku, atau fable. Claude tidak dapat memberikan ID model lengkap atau inherit pada panggilan tersebut. Claude Code me-resolve model subagent dalam urutan ini:

1. Parameter model per pemanggilan
2. Frontmatter model dari definisi subagent, di mana inherit memilih model percakapan utama
3. Environment variable CLAUDE_CODE_SUBAGENT_MODEL, ketika Anda menetapkannya ke alias model atau ID model
4. Model percakapan utama

Jika mod yang terinstal menetapkan model dalam hook agent.spawn-nya, Claude Code menggunakan model tersebut sebagai pengganti parameter per pemanggilan.

Dalam dua kasus, alias keluarga seperti opus dalam parameter per pemanggilan atau frontmatter di-resolve ke model percakapan utama alih-alih ke versi yang dirujuk alias tersebut:

• Model percakapan utama termasuk dalam keluarga tersebut: subagent berjalan pada model yang persis sama dengan percakapan utama, termasuk sufiks [1m] apa pun, sehingga mendapatkan jendela konteks yang diperluas yang sama dengan percakapan utama.
• Claude Code tidak dapat mengetahui keluarga model percakapan utama, pada penyedia selain Anthropic API: ini dapat terjadi dengan ARN application inference profile di Amazon Bedrock yang belum di-resolve Claude Code ke model pendukungnya. Kasus ini hanya mencakup alias opus, dan tidak berlaku ketika Anda menetapkan ANTHROPIC_DEFAULT_OPUS_MODEL, karena opus kemudian di-resolve ke model yang Anda tetapkan.

Alias dalam CLAUDE_CODE_SUBAGENT_MODEL selalu di-resolve ke versi yang dirujuk alias tersebut, bahkan ketika alias itu menyebutkan keluarga model percakapan utama. Menetapkan variabel ke inherit sama dengan membiarkannya tidak ditetapkan.

Menetapkan CLAUDE_CODE_SUBAGENT_MODEL saja tidak mengubah model yang digunakan subagent bawaan Explore dan Plan. Untuk mengubahnya, lihat Menjalankan setiap subagent pada satu model.

Sebelum v2.1.251, CLAUDE_CODE_SUBAGENT_MODEL berada di urutan pertama dan menimpa parameter per pemanggilan maupun frontmatter, termasuk model: inherit.

Claude Code memeriksa nilai parameter per pemanggilan, frontmatter, dan environment variable terhadap allowlist availableModels organisasi Anda. Untuk nilai yang diblokir, Claude Code menggantinya dengan model lain:

• Ketika nilai yang diblokir adalah alias keluarga seperti opus, Claude Code menjalankan subagent pada versi terbaru dari keluarga tersebut yang diizinkan allowlist, mengikuti aturan substitusi dan cakupan penyedia yang sama dengan /model. Sebelum v2.1.222, Claude Code juga menjalankan subagent pada model yang diwarisi untuk alias keluarga yang diblokir.
• Untuk nilai lain yang diblokir, pada penyedia tempat substitusi tersebut tidak beroperasi, atau ketika allowlist tidak mengizinkan versi apa pun dari keluarga tersebut, Claude Code menjalankan subagent pada model yang diwarisi. Jika Anda menetapkan CLAUDE_CODE_SUBAGENT_MODEL, Claude Code mencoba model tersebut terlebih dahulu, dengan aturan yang sama.

Dalam sesi interaktif, Claude Code menampilkan peringatan yang menyebutkan model yang diminta dan model yang digunakan subagent, untuk kedua jenis substitusi.

Untuk memeriksa model yang digunakan subagent, jalankan /tasks. Claude Code menyebutkan model pada baris subagent, dan menambahkan tingkat effort yang ditetapkan untuk subagent tersebut, jika ada. Memerlukan Claude Code v2.1.242 atau yang lebih baru.

Parameter model per pemanggilan juga berlaku ketika subagent dilanjutkan atau dikirimi pesan lanjutan, sehingga subagent tetap menggunakan model tersebut.

Sejak v2.1.198, subagent juga mewarisi konfigurasi extended thinking percakapan utama: jika thinking aktif di sesi Anda, thinking juga aktif untuk subagent, dan jika nonaktif, tetap nonaktif. Tidak ada pengaturan thinking per subagent. Sebelum v2.1.198, subagent berjalan dengan extended thinking dinonaktifkan terlepas dari pengaturan percakapan utama.

Menjalankan setiap subagent pada satu model

CLAUDE_CODE_SUBAGENT_MODEL adalah nilai default, sehingga definisi subagent atau model yang diberikan Claude tetap diutamakan daripadanya. Untuk menerapkan satu model ke setiap subagent, teammate, dan agent workflow, tetapkan juga CLAUDE_CODE_SUBAGENT_MODEL_FORCE ke 1. Memerlukan Claude Code v2.1.257 atau yang lebih baru.

• Jika Anda menetapkan kedua variabel, subagent berjalan pada model di CLAUDE_CODE_SUBAGENT_MODEL.
• Jika Anda hanya menetapkan CLAUDE_CODE_SUBAGENT_MODEL_FORCE, subagent berjalan pada model percakapan utama, kecuali subagent bawaan Explore yang berjalan pada model yang tercantum untuknya di bawah Subagent bawaan.

Misalnya, untuk menjalankan setiap subagent pada Haiku, tetapkan kedua variabel di blok env dari file pengaturan:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Untuk memeriksa bahwa pengaturan sudah berlaku, jalankan /tasks saat subagent sedang berjalan. Baris subagent menampilkan model yang digunakannya.

Selama CLAUDE_CODE_SUBAGENT_MODEL_FORCE aktif, Claude Code mengabaikan field model dalam definisi subagent, dan Claude tidak dapat memberikan model saat memulai subagent. Subagent berikut tetap berjalan pada model percakapan utama:

• Fork
• Skill yang berjalan di subagent dengan model: inherit

Memilih tingkat effort

Untuk menjalankan subagent pada tingkat effort-nya sendiri, tetapkan field effort dalam definisinya.

Ketika Anda meminta Claude menjalankan subagent non-fork pada tingkat effort tertentu, Claude juga dapat memberikan parameter effort untuk pemanggilan tersebut. Parameter ini menimpa field effort dan tetap berlaku ketika subagent dilanjutkan. Environment variable CLAUDE_CODE_EFFORT_LEVEL diutamakan daripada keduanya. Parameter per pemanggilan memerlukan Claude Code v2.1.292 atau yang lebih baru.

Ketika subagent tidak memiliki field atau parameter effort

Pada model percakapan utama, subagent berjalan pada tingkat yang Anda pilih dalam sesi, misalnya dengan /effort, atau yang ditetapkan dengan --effort. Pada model lain, tingkat tersebut tidak berlaku. Untuk memilih tingkatnya, tetapkan field effort.

Mengontrol kemampuan subagent

Anda dapat mengontrol apa yang dapat dilakukan subagent melalui akses tool, mode izin, dan aturan kondisional.

Tool yang tersedia

Subagent mewarisi tool bawaan dan tool MCP yang tersedia di percakapan utama, yang dipersempit oleh dua filter: filter pertama menghapus daftar pendek tool dari setiap subagent, dan filter kedua mengurangi kumpulan tool bawaan untuk subagent yang berjalan di latar belakang, yang merupakan default. Di macOS, Linux, dan WSL, subagent juga dapat menerima tool Glob dan Grep ketika percakapan utama tidak memilikinya, seperti dijelaskan di Perilaku tool Glob. Fork melewati kedua filter dan menerima kumpulan tool yang persis sama dengan percakapan utama. Filter pertama menghapus tool berikut, bahkan ketika tercantum di field tools:

• Agent, ketika subagent berada pada batas kedalaman; dalam fork tool tetap tercantum tetapi mengembalikan error alih-alih memunculkan subagent
• AskUserQuestion
• EndConversation, yang hanya dapat mengakhiri percakapan utama; lihat Perilaku tool EndConversation
• EnterPlanMode
• ExitPlanMode, kecuali permissionMode subagent adalah plan
• ScheduleWakeup
• WaitForMcpServers
• Workflow

Filter kedua berlaku untuk subagent yang berjalan di latar belakang. Selain Agent dan ExitPlanMode, yang mengikuti kondisi filter pertama di mana pun subagent berjalan, subagent latar belakang mempertahankan setiap tool MCP tetapi hanya tool bawaan berikut: Read, Grep, Glob, LSP, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage, dan Artifact, ditambah SubagentHandback untuk subagent yang melapor melaluinya. Claude Code menghapus setiap tool bawaan lainnya dari subagent latar belakang, baik yang diwarisi maupun yang tercantum di field tools, sehingga definisi yang sama dapat di-resolve ke tool yang berbeda di latar depan dan latar belakang. Penghapusan ini tidak melaporkan error kecuali jika penghapusan tersebut membuat daftar tools tidak di-resolve ke apa pun.

Sebelum v2.1.280, subagent latar belakang tidak dapat menggunakan LSP.

ListAgents mengikuti filter ini seperti tool bawaan lainnya: subagent latar depan mewarisinya dalam sesi yang mengaktifkan pengiriman pesan lintas sesi, dan subagent latar belakang tidak mempertahankannya.

Teammate dalam tim agent juga mempertahankan tool tugas dan tool cron: TaskCreate, TaskGet, TaskList, TaskUpdate, CronCreate, CronDelete, dan CronList. Dalam sesi tanpa tool Task, Claude Code juga tidak menyediakan tool tugas untuk subagent, bahkan ketika subagent menjalankan model yang berbeda. Teammate in-process mengikuti sesi Anda dengan cara yang sama. Untuk mengetahui apakah teammate split-pane memiliki tool tugas, lihat Ketersediaan tool Task.

Membatasi tool yang dapat digunakan subagent

Untuk membatasi tool, gunakan field tools sebagai allowlist atau field disallowedTools sebagai denylist. Jika keduanya ditetapkan, disallowedTools diterapkan terlebih dahulu, kemudian tools di-resolve terhadap kumpulan yang tersisa. Tool yang tercantum di keduanya akan dihapus.

Contoh ini menggunakan tools untuk hanya mengizinkan Read, Grep, Glob, dan Bash. Subagent tidak dapat mengedit file, menulis file, atau menggunakan tool MCP apa pun:

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

Contoh ini menggunakan disallowedTools untuk mewarisi kumpulan tool subagent kecuali Write dan Edit. Subagent mempertahankan Bash, tool MCP, dan sisa kumpulannya:

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

Ketika tidak ada apa pun dalam daftar tools yang di-resolve ke sebuah tool, misalnya karena setiap entri salah eja atau menyebutkan tool yang tidak tersedia untuk subagent, Claude Code biasanya menolak meluncurkan subagent dan tool Agent mengembalikan error yang menyebutkan entri yang tidak ter-resolve; lihat Agent would be spawned with zero tools untuk pesan tersebut dan cara memperbaiki setiap entri.

Field tools dan disallowedTools juga menerima entri untuk seluruh server MCP:

Contoh ini menghapus setiap tool dari server MCP github sambil mempertahankan tool dari server lain dan tool bawaan dalam kumpulan subagent:

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

Entri disallowedTools dengan specifier, seperti Bash(git push *), tetap menghapus seluruh tool dari subagent, bukan hanya perintah yang cocok. Untuk mempertahankan Bash dan memblokir perintah tertentu, tambahkan aturan deny Bash seperti Bash(git push *) ke permissions.deny di pengaturan Anda. Aturan ini berlaku untuk percakapan utama dan untuk subagent.

Nama server MCP yang mengandung garis bawah ganda

Jika subagent tidak mendapatkan satu pun tool dari server MCP yang namanya mengandung __, seperti reports__v2, periksa entri mcp__ subagent:

• Di tools: tulis mcp__ diikuti nama lengkap server dan __*, seperti mcp__reports__v2__*. Tanpa __* di akhir, mcp__reports__v2 tidak cocok dengan tool mana pun dari server tersebut.
• Di disallowedTools: cari mcp__reports atau mcp__reports__*, entri yang menahan server bernama reports. Dengan salah satu entri tersebut, subagent juga kehilangan setiap tool reports__v2, karena nama tool tersebut juga diawali dengan mcp__reports__. Untuk hanya menahan tool dari server reports, cantumkan satu per satu, seperti mcp__reports__run_query.

Membatasi subagent yang dapat dimunculkan

Ketika agent berjalan sebagai thread utama dengan claude --agent, agent tersebut dapat memunculkan subagent menggunakan tool Agent. Untuk membatasi jenis subagent yang dapat dimunculkannya, gunakan sintaks Agent(agent_type) di field tools.

[!NOTE]

Di versi 2.1.63, tool Task diganti namanya menjadi Agent. Referensi Task(...) yang sudah ada di pengaturan dan definisi agent tetap berfungsi sebagai alias.

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

Ini adalah allowlist: hanya subagent worker dan researcher yang dapat dimunculkan. Jika agent mencoba memunculkan jenis lain, permintaan gagal dan agent hanya melihat jenis yang diizinkan dalam prompt-nya. Untuk memblokir agent tertentu sambil mengizinkan semua yang lain, gunakan permissions.deny sebagai gantinya.

Untuk mengizinkan pemunculan subagent apa pun tanpa batasan, gunakan Agent tanpa tanda kurung:

tools: Agent, Read, Bash

Jika Anda sama sekali menghilangkan Agent dari daftar tools, agent tidak dapat memunculkan subagent apa pun dengan tool Agent.

Sintaks allowlist Agent(agent_type) hanya berlaku untuk agent yang berjalan sebagai thread utama dengan claude --agent. Dalam definisi subagent, mencantumkan Agent di tools memungkinkan subagent tersebut memunculkan subagent-nya sendiri selama batas kedalaman mengizinkannya, tetapi daftar jenis apa pun di dalam tanda kurung diabaikan.

Membatasi server MCP pada subagent

Gunakan field mcpServers untuk memberikan subagent akses ke server MCP yang tidak tersedia di percakapan utama. Server inline yang didefinisikan di sini terhubung saat subagent dimulai, dengan tunduk pada aturan kepercayaan untuk folder file agent, dan terputus saat subagent selesai. Referensi string berbagi koneksi sesi induk.

[!NOTE]

Field mcpServers berlaku di kedua konteks tempat file agent dapat berjalan:

• Sebagai subagent, yang dimunculkan melalui tool Agent atau @-mention
• Sebagai sesi utama, yang diluncurkan dengan --agent atau pengaturan agent

Ketika agent adalah sesi utama, definisi server inline terhubung saat startup bersama server dari .mcp.json dan file pengaturan, di bawah aturan kepercayaan untuk folder file agent yang sama. Di /mcp, server remote (HTTP atau SSE) yang pernah Anda gunakan sebelumnya dapat menampilkan status cached sebagai gantinya; Claude Code menghubungkannya ketika Claude pertama kali memanggil salah satu tool-nya.

Setiap entri dalam daftar berupa definisi server inline atau string yang merujuk ke server MCP yang sudah dikonfigurasi di sesi Anda:

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

Definisi inline menggunakan skema yang sama dengan entri server .mcp.json, dengan nama server sebagai key, dan mendukung jenis stdio, http, sse, dan ws.

Untuk sepenuhnya menjauhkan server MCP dari percakapan utama dan menghindari deskripsi tool-nya menghabiskan konteks di sana, definisikan server tersebut secara inline di sini, bukan di .mcp.json. Subagent mendapatkan tool-nya; percakapan induk tidak.

Pembatasan MCP yang berlaku untuk sesi utama juga mencakup server yang dideklarasikan di frontmatter subagent:

• --strict-mcp-config dan --bare
• Konfigurasi MCP terkelola enterprise
• Kebijakan allowedMcpServers dan deniedMcpServers

Ketika salah satu dari ini memblokir server, Claude Code melewatinya dan menampilkan peringatan yang menyebutkan server yang diblokir.

Pembatasan pengaturan terkelola berlaku untuk setiap subagent terlepas dari cara subagent tersebut didefinisikan. --strict-mcp-config tidak memfilter server yang Anda berikan secara inline melalui --agents atau opsi agents SDK, karena itu merupakan input eksplisit dari pemanggil.

Kepercayaan yang diperlukan untuk server MCP inline

Claude Code memuat server MCP inline dari file agent di direktori .claude/agents/ proyek Anda, atau di .claude/agents/ milik direktori --add-dir, hanya setelah Anda memercayai folder asal file agent tersebut. Sebelum v2.1.238, Claude Code memuat server ini tanpa memeriksa kepercayaan.

• Kepercayaan yang tidak dihitung: kepercayaan folder induk, dan kepercayaan otomatis yang didapat sesi -p atau SDK untuk hook di file pengaturan
• Hingga saat itu: Claude Code melewati setiap server inline dalam file agent tersebut dan menulis key projects["<path>"].hasTrustDialogAccepted yang tepat untuk ~/.claude.json ke log debug
• Direktori --add-dir: direktori di luar repositori workspace tepercaya Anda memerlukan entri kepercayaannya sendiri, karena file .claude/agents/-nya tidak mewarisi kepercayaan workspace Anda

Claude Code memuat dua jenis server tanpa memeriksa kepercayaan untuk folder asal file agent:

• Nama yang merujuk ke server yang sudah Anda konfigurasi
• Server inline dalam file agent dari ~/.claude/agents/, dalam file yang Anda berikan dengan --agents atau opsi agents SDK, atau dalam file yang disediakan oleh pengaturan terkelola

Mode izin

Tetapkan permissionMode untuk memilih mode izin yang digunakan subagent. Gunakan nilai konfigurasi mode, sehingga mode Manual adalah default. Jika Anda membiarkannya tidak ditetapkan, subagent mewarisi mode izin percakapan utama.

Mode izin percakapan utama menentukan apakah Claude Code menggunakan nilai yang Anda tetapkan:

• Ketika percakapan utama berada dalam bypassPermissions, acceptEdits, atau auto mode, subagent berjalan dalam mode yang sama dan Claude Code mengabaikan permissionMode yang Anda tetapkan. Dalam auto mode, pengklasifikasi mengevaluasi panggilan tool subagent dengan aturan block dan allow percakapan utama. Ketika subagent selesai, pengklasifikasi juga meninjau pekerjaannya dan laporan akhirnya sebelum laporan dikirimkan, seperti yang dijelaskan di Cara auto mode menangani subagent.

  Jika subagent meminta izin saat percakapan utama berada dalam bypassPermissions, periksa apakah panggilan tool-nya termasuk tindakan yang tidak disetujui otomatis oleh mode mana pun.

• Ketika percakapan utama berada dalam mode plan, subagent tetap dalam plan mode apa pun permissionMode yang Anda tetapkan, kecuali jika subagent berjalan sebagai teammate tim agent di bawah aturan tim agent. Jika Anda menetapkan dontAsk, subagent juga tidak meminta persetujuan Anda: tindakan yang akan diminta persetujuannya oleh plan mode justru ditolak.

• Ketika percakapan utama berada dalam mode default atau dontAsk, subagent berjalan dalam mode izin yang Anda tetapkan. Subagent justru mempertahankan mode izin percakapan utama dalam kasus berikut:

  • Anda menetapkan bypassPermissions. Pengecualian bypassPermissions memerlukan Claude Code v2.1.267 atau yang lebih baru.
  • Anda menetapkan auto dan auto mode tidak tersedia untuk subagent, misalnya ketika file pengaturan menetapkan disableAutoMode atau model subagent tidak mendukung auto mode.

permissionMode menerima nilai berikut, dan manual sebagai alias untuk default:

Memuat skill terlebih dahulu ke dalam subagent

Gunakan field skills untuk menyuntikkan konten skill ke dalam konteks subagent saat startup. Ini memberikan pengetahuan domain kepada subagent tanpa mengharuskannya menemukan dan memuat skill selama eksekusi.

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

Konten lengkap setiap skill yang tercantum disuntikkan ke dalam konteks subagent saat startup, hingga 32 nama berbeda pertama dalam daftar. Field ini mengontrol skill mana yang dimuat terlebih dahulu, bukan skill mana yang dapat diakses subagent: tanpa field ini, subagent tetap dapat menemukan dan memanggil skill proyek, pengguna, dan plugin melalui tool Skill selama eksekusi. Untuk sepenuhnya mencegah subagent memanggil skill, hilangkan Skill dari daftar tools atau tambahkan ke disallowedTools.

Anda tidak dapat memuat terlebih dahulu skill yang menetapkan disable-model-invocation: true, karena pemuatan terlebih dahulu mengambil dari kumpulan skill yang sama yang dapat dipanggil Claude. Ini termasuk skill bawaan /verify, yang tidak dapat dijalankan Claude sendiri.

Jika skill yang tercantum tidak ada atau dinonaktifkan, misalnya oleh kebijakan organisasi Anda, Claude Code melewatinya dan mencatat peringatan ke log debug.

[!NOTE]

Ini adalah kebalikan dari menjalankan skill di subagent. Dengan skills di subagent, subagent mengontrol system prompt dan memuat konten skill. Dengan context: fork di skill, konten skill disuntikkan ke dalam agent yang Anda tentukan. Dalam kedua kasus, subagent dimulai tanpa riwayat percakapan Anda.

Mengaktifkan memori persisten

Field memory memberikan subagent direktori persisten yang bertahan antarpercakapan. Subagent menggunakan direktori ini untuk membangun pengetahuan dari waktu ke waktu, seperti pola codebase, wawasan debugging, dan keputusan arsitektur.

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

Pilih cakupan berdasarkan seberapa luas memori harus berlaku:

Memori subagent adalah bagian dari auto memory: jika Anda mematikan auto memory, dengan pengaturan autoMemoryEnabled atau CLAUDE_CODE_DISABLE_AUTO_MEMORY, field memory tidak berpengaruh dan subagent diluncurkan tanpa instruksi memori atau akses tool memori yang dijelaskan di bawah.

Ketika memori diaktifkan:

• System prompt subagent mencakup instruksi untuk membaca dan menulis ke direktori memori.
• System prompt subagent juga mencakup 200 baris pertama atau 25KB pertama dari MEMORY.md di direktori memori, mana yang lebih dulu tercapai, dengan instruksi untuk merapikan MEMORY.md jika melebihi batas tersebut.
• Tool Read, Write, dan Edit diaktifkan secara otomatis agar subagent dapat mengelola file memorinya.

Tips memori persisten

• project adalah cakupan default yang direkomendasikan. Cakupan ini membuat pengetahuan subagent dapat dibagikan melalui version control.

• Minta subagent untuk merujuk memorinya sebelum mulai bekerja: "Review this PR, and check your memory for patterns you've seen before."

• Minta subagent untuk memperbarui memorinya setelah menyelesaikan tugas: "Now that you're done, save what you learned to your memory." Seiring waktu, ini membangun basis pengetahuan yang membuat subagent lebih efektif.

• Sertakan instruksi memori langsung di file markdown subagent agar subagent secara proaktif memelihara basis pengetahuannya sendiri:

  Update your agent memory as you discover codepaths, patterns, library
  locations, and key architectural decisions. This builds up institutional
  knowledge across conversations. Write concise notes about what you found
  and where.
  

Aturan kondisional dengan hook

Untuk kontrol yang lebih dinamis atas penggunaan tool, gunakan hook PreToolUse untuk memvalidasi operasi sebelum dieksekusi. Ini berguna ketika Anda perlu mengizinkan sebagian operasi dari suatu tool sambil memblokir yang lain.

Contoh ini membuat subagent yang hanya mengizinkan kueri database read-only. Hook PreToolUse menjalankan skrip yang ditentukan di command sebelum setiap perintah Bash dieksekusi:

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

Claude Code memberikan input hook sebagai JSON melalui stdin ke perintah hook. Skrip validasi membaca JSON ini, mengekstrak perintah Bash, dan keluar dengan kode 2 untuk memblokir operasi tulis:

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

Di macOS dan Linux, jadikan skrip dapat dieksekusi, atau hook akan gagal alih-alih memblokir apa pun:

chmod +x ./scripts/validate-readonly-query.sh

Untuk menguji aturan tersebut, minta subagent menjalankan pernyataan UPDATE: skrip keluar dengan kode 2, Claude Code memblokir perintah, dan subagent melihat pesan Blocked: Only SELECT queries are allowed.

Lihat Input hook untuk skema input lengkap dan exit code untuk mengetahui bagaimana exit code memengaruhi perilaku. Di Windows, tulis skrip hook di PowerShell dan tambahkan shell: powershell ke entri hook seperti yang ditunjukkan di menjalankan hook di PowerShell.

Menonaktifkan subagent tertentu

Anda dapat mencegah Claude menggunakan subagent tertentu dengan menambahkannya ke array deny di pengaturan Anda. Gunakan format Agent(subagent-name) di mana subagent-name cocok dengan field name subagent.

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

Ini berfungsi untuk subagent bawaan maupun kustom. Anda juga dapat menggunakan flag CLI --disallowedTools:

claude --disallowedTools "Agent(Explore)"

Lihat dokumentasi Izin untuk detail lebih lanjut tentang aturan izin.

Mendefinisikan hook untuk subagent

Subagent dapat mendefinisikan hook yang berjalan selama siklus hidup subagent. Ada dua cara untuk mengonfigurasi hook:

• Di frontmatter subagent: definisikan hook yang hanya berjalan saat subagent tersebut aktif
• Di settings.json: definisikan hook tingkat sesi yang juga dipicu di dalam subagent. Event tool seperti PreToolUse dan PostToolUse dipicu untuk panggilan tool subagent dengan cara yang sama seperti di percakapan utama, dan SubagentStart serta SubagentStop dipicu saat subagent dimulai atau selesai

Hook dari file pengaturan, pengaturan kebijakan terkelola, dan plugin semuanya berlaku di dalam subagent, sehingga hook PreToolUse di settings.json juga berjalan sebelum setiap tool yang digunakan subagent.

Hook di frontmatter subagent

Definisikan hook langsung di file markdown subagent. Hook ini hanya berjalan saat subagent tertentu tersebut aktif dan dibersihkan saat subagent selesai.

[!NOTE]

Hook frontmatter dipicu ketika agent dimunculkan sebagai subagent melalui tool Agent atau @-mention, dan ketika agent berjalan sebagai sesi utama melalui --agent atau pengaturan agent. Dalam kasus sesi utama, hook tersebut berjalan bersama hook apa pun yang didefinisikan di settings.json.

Agar hook frontmatter subagent tingkat proyek dapat berjalan, terima dialog kepercayaan workspace untuk folder yang berisi file agent. Hook dari subagent tingkat pengguna di ~/.claude/agents/ dan dari definisi yang Anda berikan dengan --agents berjalan tanpa langkah ini. Jika Anda menambahkan folder dengan --add-dir dari luar repositori workspace tepercaya Anda, percayai folder tersebut secara terpisah: hook .claude/agents/-nya tidak mewarisi pemberian kepercayaan workspace.

Hingga Anda memercayai folder tersebut, subagent tetap berjalan, tetapi Claude Code melewati hook frontmatter-nya dan mencatat error ke log debug yang menjelaskan cara memercayai folder tersebut. Ini adalah aturan yang lebih ketat daripada aturan untuk hook di file pengaturan: memercayai folder induk tidak cukup, dan sesi -p tidak dihitung sebagai tepercaya. Apa yang berjalan sebelum Anda memercayai folder membandingkan keduanya.

Semua event hook didukung. Event yang paling umum untuk subagent adalah:

Contoh ini memvalidasi perintah Bash dengan hook PreToolUse dan menjalankan linter setelah edit file dengan PostToolUse:

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

Ketika agent dipanggil sebagai subagent, hook Stop di frontmatter secara otomatis dikonversi menjadi event SubagentStop.

Hook tingkat proyek untuk event subagent

Konfigurasikan hook di settings.json yang merespons event siklus hidup subagent di sesi utama.

Kedua event mendukung matcher untuk menargetkan jenis agent tertentu berdasarkan nama. Nilai matcher adalah name frontmatter agent untuk subagent tingkat proyek dan tingkat pengguna, atau identifier bercakupan plugin seperti my-plugin:db-agent untuk subagent plugin. Nama bercakupan mengandung titik dua, sehingga dievaluasi sebagai regular expression tanpa anchor; beri anchor dengan ^ dan $, seperti ^my-plugin:db-agent$, agar hanya cocok dengan agent tersebut.

Contoh ini menjalankan skrip penyiapan hanya saat subagent db-agent dimulai, dan skrip pembersihan saat subagent apa pun berhenti:

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

Lihat Hooks untuk format konfigurasi hook yang lengkap.

Bekerja dengan subagent

Pahami delegasi otomatis

Claude secara otomatis mendelegasikan tugas berdasarkan deskripsi tugas dalam permintaan Anda, bidang description dalam konfigurasi subagent, dan konteks saat ini. Untuk mendorong delegasi proaktif, sertakan frasa seperti "use proactively" dalam bidang deskripsi subagent Anda.

Jaga deskripsi tetap singkat: Claude Code menampilkan peringatan startup ketika deskripsi gabungan subagent Anda melampaui batas 15.000 token, dan masih memuat setiap subagent.

Jika subagent dikirim dalam plugin, Anda dapat mengukur seberapa andal Claude mendelegasikan ke dalamnya di seluruh prompt realistis daripada memeriksa satu per satu: claude plugin eval menjalankan setiap prompt dengan dan tanpa plugin dan menilai hasilnya.

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 berjalan sebagai subagent itu melalui flag --agent atau pengaturan agent

Untuk bahasa alami, tidak ada sintaks khusus. Sebutkan subagent dan Claude biasanya mendelegasikan:

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

@-mention subagent. Ketik @ dan pilih subagent dari typeahead, dengan cara yang sama Anda @-mention file. Ini memastikan subagent tertentu berjalan daripada meninggalkan pilihan kepada Claude:

@"code-reviewer (agent)" look at the auth changes

Pesan lengkap Anda masih pergi ke Claude, yang menulis prompt tugas subagent berdasarkan apa yang Anda minta. @-mention mengontrol subagent mana yang Claude panggil, bukan prompt apa yang diterima.

Subagent yang disediakan oleh plugin yang diaktifkan muncul di typeahead dengan nama yang dibatasi, seperti my-plugin:code-reviewer atau my-plugin:review:security ketika plugin mengorganisir agent 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. Saat Anda mengetik formulir ini, typeahead menampilkan kecocokan file daripada agent. Penyebutan agent masih diselesaikan saat Anda mengirimkan.

Jalankan seluruh sesi sebagai subagent. Lewatkan --agent <name> untuk memulai sesi di mana thread utama itu sendiri mengambil pembatasan tool dan model subagent:

claude --agent code-reviewer

Kecuali prompt agent kosong, system prompt subagent kustom menggantikan system prompt Claude Code default sepenuhnya, dengan cara yang sama --system-prompt melakukannya. File CLAUDE.md dan memori proyek masih dimuat melalui aliran pesan normal, bahkan ketika definisi agent menetapkan omitClaudeMd. Jika Anda menjalankan sesi dengan -p sebagai agent kustom yang memiliki prompt sendiri, sesi juga dimulai tanpa snapshot status git.

Nama agent 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: Claude Code memulihkan pembatasan tool dan model agent bersama dengan percakapan. Jika agent tidak lagi ada saat Anda melanjutkan, sesi berlanjut dengan tool default dan menampilkan peringatan yang menyebutkan agent. Untuk system prompt dalam kedua kasus, lihat Flag system prompt dalam percakapan yang dilanjutkan.

Untuk subagent yang disediakan plugin, Anda dapat melewatkan hanya nama agent dan Claude Code akan menemukannya:

claude --agent security-reviewer

Jika beberapa plugin menyediakan agent dengan nama yang sama, lewatkan nama yang dibatasi untuk membedakan:

claude --agent my-plugin:security-reviewer

Jika plugin menempatkan agent 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:

{
  "agent": "code-reviewer"
}

Flag CLI menimpa pengaturan jika keduanya ada.

Jalankan subagent di foreground atau background

Subagent dapat berjalan di foreground atau background:

• Subagent foreground memblokir percakapan utama sampai selesai. Permintaan izin diteruskan kepada Anda saat muncul.
• Subagent background berjalan secara bersamaan sementara Anda terus bekerja. Ketika subagent background mencapai panggilan tool yang memerlukan izin, Claude Code menampilkan permintaan izin di sesi utama Anda dan menyebutkan subagent yang bertanya. Setujui untuk membiarkan subagent melanjutkan, atau tekan Esc untuk menolak panggilan tool itu saja tanpa menghentikan subagent.

Subagent mana yang berjalan di background

Tanpa konfigurasi apa pun, subagent yang Claude hasilkan dari percakapan utama Anda dimulai di background.

• claude -p dan Agent SDK: Claude dapat menunggu, berdasarkan penilaiannya sendiri atau ketika Anda memintanya.
• Sesi terminal interaktif, VS Code, dan sesi aplikasi desktop di mesin Anda: agar Claude dapat menunggu subagent, matikan fork mode, yang aktif secara default.

Untuk skill dengan context: fork, Claude Code mengikuti aturan dalam Jalankan skills dalam subagent sebagai gantinya, apakah fork mode aktif atau tidak.

Biarkan Claude menunggu subagent

1. Matikan fork mode dengan mengatur CLAUDE_CODE_FORK_SUBAGENT ke 0, misalnya dalam settings.json:

   {
     "env": {
       "CLAUDE_CODE_FORK_SUBAGENT": "0"
     }
   }
   

2. Jalankan claude lagi dari shell Anda, atau buka percakapan VS Code baru.

3. Minta Claude untuk menunggu ketika Anda memerlukan hasil terlebih dahulu, misalnya "run the reviewer subagent and wait for its report".

Untuk tetap bekerja selagi Claude menunggu, tekan Ctrl+B di terminal atau klik Run in background di VS Code.

Jika Anda mengatur environment variable CLAUDE_CODE_DISABLE_BACKGROUND_TASKS ke 1 alih-alih mematikan fork mode, Claude menunggu subagent selesai sebelum melanjutkan. Perintah background juga dimatikan, dan Ctrl+B tidak memindahkan apa pun ke background.

Tool, izin, dan hasil subagent background

Subagent background berjalan dengan set tool bawaan yang lebih kecil daripada subagent foreground, kecuali untuk fork percakapan dan subagent foreground yang dilanjutkan.

Subagent background menampilkan setiap permintaan izin di sesi utama Anda. Ketika Anda menjawab salah satu permintaan izin tersebut dengan pilihan yang berlangsung melampaui panggilan tool itu, seperti hibah yang berlangsung untuk sisa sesi, Claude Code menerapkan jawaban Anda ke seluruh sesi, termasuk percakapan utama Anda.

Subagent background dapat meninggalkan perintah Bash atau PowerShell background berjalan melampaui akhir giliran. Ketika perintah itu berakhir, Claude Code mengirim notifikasi ke subagent.

Hasil subagent background mencapai Claude sebagai notifikasi penyelesaian dalam giliran yang lebih baru. Claude menunggu notifikasi itu sebelum melaporkan hasil subagent, dan jika Anda bertanya tentang kemajuan terlebih dahulu, itu melaporkan bahwa subagent masih berjalan.

Subagent yang selesai di panel dan daftar tugas

Claude Code menghapus baris subagent background dari panel subagent di bawah input prompt dengan salah satu dari dua cara, tergantung bagaimana subagent berakhir:

• Ketika subagent selesai dengan sukses, Claude Code menghapus barisnya segera dan, kecuali dalam mode pembaca layar, menampilkan /tasks to see subagents di footer selama 30 detik. Selama 30 detik itu, jalankan /tasks dan tekan Enter pada subagent untuk membuka transkrip. Sebelum v2.1.232, Claude Code menyimpan baris selama 30 detik setelah subagent selesai, sama seperti yang gagal, dan tidak menampilkan petunjuk footer.
• Ketika subagent gagal atau Anda menghentikannya, Claude Code menyimpan barisnya selama 30 detik. Untuk menghapus baris lebih cepat, pilih dan tekan x.

Subagent background yang selesai tetap terdaftar dalam /tasks, ditandai selesai dan diurutkan di bawah pekerjaan yang sedang berjalan, selama 30 detik yang sama dengan petunjuk footer. Tampilan detailnya tetap terbuka ketika subagent selesai. Subagent yang gagal atau yang Anda hentikan meninggalkan daftar. Sebelum v2.1.208, subagent yang selesai meninggalkan daftar saat itu selesai dan tampilan detailnya ditutup.

Nama subagent

Jika Anda memulai sesi dengan tim agent diaktifkan, Claude dapat memberi subagent nama dengan melewatkan parameter name pada panggilan tool Agent. Claude dapat melakukannya sendiri, tanpa bertanya kepada Anda terlebih dahulu. Nama membuat subagent dapat dialamatkan: Claude dapat mengirim pesan atau melanjutkannya berdasarkan nama setelah selesai.

Dalam sesi interaktif dengan tim agent diaktifkan, subagent yang Claude hasilkan dari percakapan utama dengan name diluncurkan sebagai anggota tim sebagai gantinya, kecuali panggilan adalah fork atau melewatkan isolation pada panggilan itu sendiri. Nilai isolation dalam frontmatter subagent tidak mencegahnya, dan anggota tim kemudian berjalan di direktori kerja sesi utama. Lihat Bagaimana Claude memulai tim agent.

Kesalahan API dalam subagent

Ketika sesuatu memotong respons subagent di tengah-aliran, dan respons parsial berisi teks tetapi tidak ada panggilan tool, Claude Code meminta subagent untuk melanjutkan daripada mengakhiri run. Ini terjadi dalam sesi interaktif juga. Run berakhir pada kesalahan hanya setelah kelanjutan itu habis.

Subagent yang run-nya berakhir pada kesalahan API, seperti batas penggunaan atau kesalahan server berulang, melaporkan kegagalan itu kembali ke Claude. Apa yang Claude terima tergantung di mana subagent berjalan:

• Foreground: jika rate limit, kelebihan beban, atau kesalahan server memotong subagent yang sudah menghasilkan output teks, tool Agent mengembalikan output parsial itu dengan catatan bahwa subagent dipotong dan tidak menyelesaikan tugasnya. Subagent yang tidak menghasilkan apa pun, atau yang output-nya hanya panggilan tool, gagal dengan Agent terminated early due to an API error, diikuti oleh detail kesalahan.
• Background: subagent ditandai gagal, dan pesan yang Claude terima saat berakhir menyebutkan kesalahan API dan menyertakan output terakhir subagent, jadi pekerjaan parsial tidak hilang.

Jika laporan subagent dibuka dengan baris berikut, subagent tersebut selesai menggunakan model fallback:

⚠ This agent switched to <model> because its earlier model could not be used.

Ketika Anda mengonfigurasi rantai model fallback dan subagent mengalami kegagalan yang dicakup rantai, seperti model-nya tidak tersedia, Claude Code beralih subagent ke model pertama dalam rantai yang menerima permintaan. Subagent terus bekerja daripada berakhir pada kesalahan.

Setelah kesalahan API yang mendasar hilang, minta Claude untuk mencoba ulang tugas atau lanjutkan subagent.

Pemindaian output subagent

Claude Code memindai laporan akhir setiap subagent sebelum Claude membacanya. Subagent mungkin telah membaca file, halaman web, atau output perintah yang tidak pernah Anda tinjau, dan teks dari sumber tersebut dapat membawa instruksi yang ditujukan ke percakapan utama. Pemindaian tidak pernah menghapus atau menulis ulang apa pun; itu membuat dua jenis perubahan yang mungkin Anda perhatikan dalam laporan:

• Penyisipan backslash: pemindaian menyisipkan backslash ke dalam teks yang meniru output Claude Code itu sendiri, seperti tag <system-reminder> atau baris yang dimulai dengan Human: atau Assistant:, sehingga peniruan dibaca sebagai teks biasa daripada disalahartikan sebagai bagian dari percakapan.
• Baris penanda: pemindaian menambahkan baris yang dimulai dengan [harness: subagent output matched instruction-shaped pattern(s): ketika laporan meniru tag seperti <system-reminder> atau menyebutkan pengaturan izin seperti bypassPermissions atau --dangerously-skip-permissions. Penyebutan pengaturan izin mendapatkan baris penanda, tetapi teks itu sendiri tetap seperti yang ditulis.

Pemindaian tidak menilai apakah konten berbahaya, dan itu tidak mengubah apa yang dapat dilakukan instruksi dalam laporan: panggilan tool yang dilaporkan mengarahkan Claude untuk membuat masih melalui pemeriksaan izin sesi dan sandboxing. Ini bukan pengganti untuk membatasi apa yang dapat dijangkau subagent.

Laporan yang kembali ke Claude sebagai hasil subagent juga tiba di bawah header yang menandainya sebagai output subagent. Header menyatakan bahwa instruksi atau klaim persetujuan di dalam laporan adalah kata-kata subagent dan tidak membawa otoritas dari Anda.

Laporan subagent background tiba di dalam notifikasi penyelesaian, yang ditandai sebagai peristiwa otomatis daripada pesan dari Anda.

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.

Use a subagent to run the test suite and report only the failing tests with their error messages

Jalankan penelitian paralel

Untuk investigasi independen, hasilkan beberapa subagent untuk bekerja secara bersamaan:

Research the authentication, database, and API modules in parallel using separate subagents

Setiap subagent mengeksplorasi areanya secara independen, kemudian Claude mensintesis temuan. Ini berfungsi terbaik ketika jalur penelitian tidak saling bergantung.

[!WARNING]

Ketika subagent selesai, hasil mereka kembali ke percakapan utama Anda. Menjalankan banyak subagent yang masing-masing mengembalikan hasil terperinci dapat mengonsumsi konteks yang signifikan, dan setiap subagent menghabiskan token-nya sendiri saat berjalan.

Untuk pekerjaan yang perlu terus berjalan secara paralel atau tidak akan muat dalam satu context window, jalankan dalam sesi terpisah dan biarkan Claude meneruskan temuan di antara mereka.

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.

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

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, seperti perencanaan, implementasi, dan pengujian
• Anda membuat perubahan cepat dan tertarget
• Latensi penting. Subagent yang bukan fork dimulai segar dan mungkin memerlukan waktu untuk mengumpulkan konteks

Gunakan subagent ketika:

• Tugas menghasilkan output verbose yang Anda tidak butuhkan dalam konteks utama Anda
• Anda ingin menerapkan pembatasan tool atau izin tertentu
• Pekerjaan mandiri dan dapat mengembalikan ringkasan

Pertimbangkan Skills sebagai gantinya ketika Anda menginginkan prompt atau alur kerja yang dapat digunakan kembali yang berjalan dalam konteks percakapan utama daripada konteks subagent yang terisolasi.

Untuk pertanyaan tentang sesuatu yang sudah ada dalam percakapan Anda, gunakan /btw sebagai gantinya dari subagent. Ini tidak memiliki akses tool, dan jawabannya tidak ditambahkan ke riwayat.

Biarkan subagent menghasilkan subagent mereka sendiri

Secara default, subagent dapat menghasilkan subagent-nya sendiri, hingga tiga lapisan di bawah percakapan utama. Pada batas kedalaman, Claude Code menahan tool Agent dari setiap subagent kecuali fork, jadi subagent pada batas melakukan pekerjaan yang didelegasikan itu sendiri dan mengembalikan satu ringkasan. Fork pada batas menyimpan Agent dalam daftar tool yang diwariskan, tetapi tool mengembalikan kesalahan daripada menghasilkan.

Subagent bersarang cocok untuk tugas yang didelegasikan yang itu sendiri terbagi menjadi subtask paralel, seperti subagent reviewer yang mengirimkan verifier per temuan. Secara default, subagent yang menghasilkan menunggu laporan setiap subagent bersarang:

• Sesi terminal interaktif: hanya ringkasan subagent tingkat atas yang kembali kepada Anda, karena subagent yang meluncurkan subagent background menunggu hasil mereka sebelum selesai.
• claude -p dan Agent SDK: subagent yang menghasilkan menunggu selama fork mode aktif. Jika Anda mematikan fork mode, subagent bersarang dimulai di background sebagai gantinya. Subagent yang menghasilkan tidak menunggu subagent bersarang background, yang melaporkan ke percakapan utama Anda jika berjalan lebih lama daripada subagent yang menghasilkannya.

Untuk mengubah batas, atur CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH ke jumlah lapisan subagent yang Anda inginkan di bawah percakapan utama Anda. Misalnya, entri ini dalam settings.json membatasi nesting pada dua lapisan:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

Dengan nilai ini, subagent Anda dapat mendelegasikan ke lapisan kedua mereka sendiri, dan lapisan kedua itu tidak dapat mendelegasikan lebih lanjut. Atur 1 untuk mematikan nesting.

Subagent bersarang dikonfigurasi dengan cara yang sama seperti subagent tingkat atas dan diselesaikan dari cakupan yang sama. Untuk menjaga satu subagent agar tidak menghasilkan sementara nesting aktif, seperti reviewer yang harus tetap read-only, hilangkan Agent dari daftar tools atau tambahkan ke disallowedTools.

Dalam terminal, Claude Code menampilkan subagent bersarang sebagai pohon dalam panel subagent di bawah input prompt dan menandai setiap baris yang masih memiliki keturunan dalam panel dengan hitungan (+N) mereka. Buka baris untuk melihat saudara dan anak langsung subagent itu dengan jalur kembali ke main.

Batas subagent bersamaan

Dua batas mengontrol penggunaan subagent, masing-masing dengan variabelnya sendiri: yang ini menghentikan Claude dari menghasilkan lebih banyak subagent sementara terlalu banyak berjalan, dan batas kedalaman membatasi seberapa dalam subagent bersarang. Tidak ada batas pada jumlah total subagent yang dapat Claude hasilkan selama sesi.

Secara default, ketika 20 subagent berjalan dalam sesi, menghasilkan yang lain dengan tool Agent gagal dengan Concurrent subagent limit reached, dan kesalahan memberi tahu Claude untuk tidak mencoba ulang. Menghasilkan berhasil lagi ketika hitungan yang berjalan turun di bawah batas. Untuk mengubah batas, atur CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS ke bilangan bulat positif apa pun. Sesi dengan ultracode aktif dikecualikan: batas tidak diterapkan di sana. Memerlukan Claude Code v2.1.217 atau lebih baru.

Batas hanya memblokir subagent yang Claude hasilkan dengan tool Agent, tetapi run lain menempati slot yang sama:

• Fork dalam sesi yang Anda mulai dengan /subtask menempati slot saat berjalan dan tidak pernah diblokir oleh batas.
• Melanjutkan subagent yang sudah selesai menempati slot segar tanpa memeriksa batas, jadi resume dapat mendorong hitungan yang berjalan melampaui batas.

Agent yang fitur lain jalankan, seperti agent workflow dan anggota tim agent, mengikuti batas mereka sendiri sebagai gantinya.

Kelola konteks subagent

Apa yang dimuat saat startup

Setiap subagent dimulai dengan context window yang segar dan terisolasi. Ini tidak melihat riwayat percakapan Anda, skills yang sudah Anda panggil, atau file yang sudah Claude baca. Claude menyusun pesan delegasi yang merangkum tugas, dan subagent bekerja dari sana. Pengecualiannya adalah fork, yang mewarisi percakapan induk daripada memulai segar.

Konteks awal subagent non-fork berisi:

• System prompt: prompt agent itu sendiri ditambah detail lingkungan yang Claude Code tambahkan, bukan system prompt Claude Code. Subagent khusus mendefinisikan milik mereka dalam badan markdown atau bidang prompt. Agent bawaan memiliki prompt yang telah ditentukan sebelumnya.
• Pesan tugas: prompt delegasi yang Claude tulis saat menyerahkan pekerjaan.
• File CLAUDE.md: setiap level dari hierarki CLAUDE.md yang dimuat percakapan utama, termasuk ~/.claude/CLAUDE.md, aturan proyek, CLAUDE.local.md, file kebijakan terkelola, dan file AGENTS.md apa pun yang dimuat sebagai instruksi proyek. Agent Explore dan Plan bawaan melewati ini. Subagent yang definisinya menetapkan omitClaudeMd hanya memuat file kebijakan terkelola, atau tidak ada sama sekali ketika definisi berasal dari pengaturan terkelola.
• Status Git: snapshot yang dibaca Claude Code dari repositori Anda saat subagent dimulai. Untuk subagent di worktree-nya sendiri dari repositori tersebut, snapshot menampilkan branch, status, dan commit terbaru worktree tersebut. Tidak ada di luar repositori Git atau kapan pun snapshot dimatikan; lihat includeGitInstructions. Explore dan Plan tetap melewatinya dalam kondisi apa pun.
• Skills yang dimuat sebelumnya: konten lengkap dari skill apa pun yang dinamai dalam bidang skills agent. Agent bawaan tidak memuat skills sebelumnya.
• Daftar saudara: system reminder yang mencantumkan main dan setiap agent bernama lainnya dalam sesi, masing-masing nilai to yang valid untuk SendMessage. Daftar muncul hanya ketika tool subagent mencakup SendMessage dan setidaknya satu agent lain memiliki nama, baik Claude menamakannya saat memunculkannya atau berjalan sebagai anggota tim agent. Ini adalah snapshot yang diambil ketika subagent dimulai, jadi agent yang dinamai nanti tidak muncul.

Untuk meluncurkan salah satu subagent Anda sendiri tanpa file CLAUDE.md pengguna, proyek, dan lokal, atur omitClaudeMd: true dalam frontmatter atau --agents JSON. Untuk Explore, Plan, dan subagent dengan omitClaudeMd, CLAUDE.md subdirektori dan aturan berbasis path yang cocok tetap dimuat ketika subagent bekerja dengan file di sana.

Percakapan utama masih memiliki CLAUDE.md penuh Anda saat membaca hasil subagent ini, jadi sebagian besar aturan tidak perlu mencapai subagent itu sendiri. Jika aturan harus, seperti "abaikan direktori vendor/," nyatakan kembali dalam prompt yang Anda berikan Claude saat mendelegasikan.

Anda tidak dapat mengubah subagent mana yang menerima status git. Hanya Explore dan Plan yang melewatinya.

Beberapa status percakapan utama tidak pernah mencapai subagent non-fork:

• Gaya output: subagent menjalankan system prompt-nya sendiri, jadi gaya output Anda tidak membentuk responsnya, kecuali dalam fork.
• Auto memory: auto memory percakapan utama tidak dimuat. Untuk memberi subagent memori persisten miliknya sendiri, gunakan bidang memory.
• Ukuran context window: context window subagent diukur oleh modelnya sendiri, bukan induk. Mendelegasikan ke model dengan window yang lebih kecil memberikan subagent itu window yang lebih kecil.

Lanjutkan subagent

Setiap invokasi subagent membuat instance baru daripada melanjutkan yang sebelumnya. 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 tool sebelumnya, hasil, dan penalaran. Jika subagent menghasilkan subagent background miliknya sendiri, riwayat itu mencakup hasil yang mereka berikan saat berjalan. Sebelum v2.1.304, subagent yang dikirimi pesan atau dilanjutkan oleh Claude tepat setelah selesai dapat melupakan pekerjaan terbarunya.

• Ketika subagent selesai, Claude menerima ID agent-nya.
• Agent bawaan Explore dan Plan adalah one-shot dan tidak mengembalikan ID agent, jadi Claude tidak dapat melanjutkan mereka. Gunakan general-purpose atau subagent khusus ketika Anda perlu melanjutkan pekerjaan.
• Ketika subagent berhenti pada batas maxTurns, Claude Code menandai output yang dikembalikan sebagai parsial, dan Claude dapat melanjutkan subagent untuk meneruskan pekerjaannya.

Claude menggunakan tool SendMessage dengan ID agent atau nama agent sebagai bidang to untuk melanjutkannya. SendMessage tidak memerlukan tim agent untuk diaktifkan; hanya pesan protokol tim terstruktur seperti shutdown_request dan plan_approval_response yang melakukannya. Melampaui subagent dan rekan tim, dalam sesi di mana cross-session messaging diaktifkan, Claude dapat menggunakan tool yang sama untuk mengirim pesan sesi Claude Code Anda yang lain, di mesin ini atau melampaui.

Untuk melanjutkan subagent, minta Claude untuk melanjutkan pekerjaan sebelumnya:

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

Ketika Claude mengirim pesan subagent yang selesai dengan tool SendMessage, subagent melanjutkan di background tanpa invokasi Agent baru. Hal yang sama berlaku untuk subagent yang Claude hentikan dengan tool TaskStop, setelah run yang dihentikan telah keluar. Run yang dilanjutkan menyimpan set tool dari tempat subagent pertama kali berjalan dan dapat terus membaca prompt cache yang dihangatkan run asli.

Subagent yang memiliki tool SendMessage dapat mengirim pesan itu juga. Dalam sesi interaktif, agent yang dilanjutkan kemudian melaporkan kembali ke subagent yang melanjutkannya, bukan ke percakapan utama Anda. Subagent itu menunggu hasil sebelum menyelesaikan pekerjaan miliknya sendiri. Ketika subagent mengirim pesan ke agent yang dilaporkannya, seperti peluncurnya sendiri, Claude Code melanjutkan agent itu tanpa mengarahkan ulang hasilnya.

Subagent yang Anda hentikan sendiri, dengan x dalam /tasks atau permintaan SDK stop_task, tidak auto-resume. Jika Claude mengirimnya pesan, pesan ditolak dan Claude diberitahu agent dibatalkan.

Sementara baris subagent itu masih dalam panel subagent, ketik ke dalam transkrip untuk melanjutkannya sendiri. Setelah itu, pesan dari Claude dapat auto-resume lagi.

Melanjutkan memulai run baru dari agent di bawah ID yang sama, jadi subagent yang sudah gagal atau selesai menunjukkan sebagai berjalan lagi dalam daftar tugas dan dalam peristiwa tugas Agent SDK.

SendMessage memeriksa bahwa nama masih merujuk ke agent yang sama yang dicapai sebelumnya dalam percakapan. Jika agent yang lebih baru telah mengambil nama, seperti agent background yang di-spawn ulang yang menggunakannya kembali, Claude Code menolak pengiriman daripada mengirimkannya ke agent yang salah, dan kesalahan melaporkan agent mana yang sekarang dicapai nama sehingga Claude dapat menargetkan ulang. Untuk mencapai agent sebelumnya sementara masih berjalan, Claude mengalamatkannya dengan ID agent yang diterima saat menghasilkan agent itu. Pemeriksaan dibatasi pada percakapan saat ini dan direset pada /clear.

Subagent memperlakukan pesan dari agent yang meluncurkannya sebagai arahan tugas normal, termasuk koreksi arah di tengah tugas, dan bertindak atas pesan tersebut dalam pengaturan izinnya sendiri. Dua batas tetap berlaku terlepas dari siapa yang mengirim pesan: tidak ada pesan dari agent apa pun yang dihitung sebagai persetujuan Anda untuk permintaan izin yang tertunda, dan tidak ada pesan agent yang dapat mengubah pengaturan izin subagent, CLAUDE.md, atau konfigurasi. Hanya sistem izin atau pesan Anda sendiri yang dapat memberikan persetujuan.

Anda juga dapat meminta Claude untuk ID agent 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:

• Compaction percakapan utama: ketika percakapan utama di-compact, 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: Claude Code menghapus transkrip subagent setelah periode retensi cleanupPeriodDays, 30 hari secara default, mengikuti aturan sweep retensi.

Kirim pesan ke subagent berdasarkan nama setelah restart

[!NOTE]

Untuk subagent yang diluncurkan sebagai anggota tim, lihat batasan tim agent sebagai gantinya.

Jika Claude tidak dapat mengirim pesan ke subagent berdasarkan nama setelah Anda memulai ulang Claude Code dan melanjutkan sesi, berikan ID agent subagent tersebut kepada Claude sebagai gantinya. Nama yang diberikan Claude dari percakapan utama sejak compaction terakhirnya tetap bertahan setelah restart. Nama dari sebelum compaction tersebut tidak bertahan. Untuk menemukan ID dari sebuah nama, cari nama tersebut di file agent-{agentId}.meta.json di ~/.claude/projects/{project}/{sessionId}/subagents/.

Setelah satu pesan berdasarkan ID, nama subagent berfungsi kembali, kecuali agent yang lebih baru telah mengambil nama tersebut. Sebelum v2.1.299, tidak ada nama yang bertahan setelah restart, dan pengiriman berdasarkan nama ditolak bahkan ketika ID agent masih berfungsi.

Auto-compaction

Subagent mendukung compaction otomatis. Compaction dipicu saat context window milik subagent itu sendiri terisi, dan CLAUDE_AUTOCOMPACT_PCT_OVERRIDE berlaku untuk subagent juga. Lihat environment variables untuk kapan override berlaku.

Peristiwa compaction dicatat dalam file transkrip subagent:

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

Nilai preTokens menunjukkan berapa banyak token yang digunakan sebelum compaction terjadi.

Atur jendela auto-compact untuk satu subagent

Agar satu subagent melakukan compaction lebih awal daripada yang seharusnya, atur autoCompactWindow dalam frontmatter-nya ke jumlah token dari 100000 hingga 1000000. Jika Anda menetapkan CLAUDE_CODE_AUTO_COMPACT_WINDOW, subagent menggunakan jendela dari variabel tersebut sebagai gantinya dan bidang ini tidak berpengaruh, kecuali Claude Code mengabaikan nilai variabel tersebut. Memerlukan Claude Code v2.1.296 atau lebih baru.

Frontmatter ini mengatur autoCompactWindow ke 200.000 token untuk subagent yang membaca file log panjang:

---
name: log-reader
description: Reads long log files and reports the errors it finds
autoCompactWindow: 200000
---

Tulis nilai sebagai bilangan bulat biasa seperti 200000, karena dalam frontmatter Claude Code membaca 200k sebagai 200, yang berada di luar rentang yang diizinkan. Subagent tetap dimuat dan melakukan compaction seolah-olah bidang tersebut tidak ada. Untuk memeriksa apakah Claude Code mengabaikan nilai Anda, jalankan claude --debug di shell Anda dan cari invalid autoCompactWindow di log debug.

Jika nilai berada dalam rentang dan Anda masih tidak melihat perubahan, periksa penyebab berikut:

• Nilai tidak berada di bawah jendela auto-compact yang seharusnya diwarisi subagent: untuk melakukan compaction lebih awal, atur nilai di bawah jendela tersebut.
• Anda menjalankan seluruh sesi sebagai subagent ini dengan --agent atau pengaturan agent: bidang ini tidak berpengaruh di sana. Untuk mengatur jendela sesi, lihat Atur jendela auto-compact.

Fork percakapan saat ini

[!NOTE]

Ketika tampilan agent dimatikan, /subtask tidak tersedia dan /fork memulai subagent yang di-fork sebagai gantinya; jika tidak, /fork menyalin seluruh sesi ke sesi latar belakang baru.

Fork adalah subagent yang mewarisi seluruh percakapan sejauh ini daripada memulai segar. Ini menghilangkan isolasi input yang sebaliknya disediakan subagent: fork melihat prompt sistem yang sama, alat, model, dan riwayat pesan sebagai sesi utama, sehingga Anda dapat menyerahkan tugas sampingan tanpa menjelaskan situasinya lagi. Panggilan alat fork sendiri masih tetap keluar dari percakapan Anda dan hanya hasil akhirnya yang kembali, sehingga jendela konteks utama Anda tetap bersih. Gunakan fork ketika subagent lain mana pun memerlukan terlalu banyak latar belakang untuk berguna, atau ketika Anda ingin mencoba beberapa pendekatan secara paralel dari titik awal yang sama.

Claude dapat memulai fork sendiri selama mode fork aktif, sebagaimana halnya secara default. Untuk menghentikan fork, lihat Nonaktifkan mode fork.

Anda dapat memulai fork sendiri dengan /subtask diikuti oleh tugas, terlepas dari apakah mode fork diaktifkan atau tidak. Claude Code memberi nama fork dari kata-kata pertama tugas. Contoh berikut mem-fork percakapan untuk membuat draf kasus uji sementara Anda melanjutkan implementasi dalam sesi utama:

/subtask draft unit tests for the parser changes so far

Fork muncul di panel di bawah prompt Anda dan berjalan di latar belakang sementara Anda terus bekerja. Ketika selesai, hasilnya tiba sebagai pesan dalam percakapan utama Anda. Bagian berikutnya mencakup kontrol panel untuk menonton dan mengarahkan fork saat berjalan.

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.

Ketika fork selesai dengan sukses, Claude Code menghapus barisnya. Claude Code menyimpan baris fork yang gagal atau yang Anda hentikan selama 30 detik, sama seperti untuk subagent latar belakang lainnya. Sebelum v2.1.232, Claude Code juga menyimpan baris fork yang selesai selama 30 detik.

Gunakan kunci ini untuk berinteraksi dengan panel:

Dengan transkrip fork atau subagent terbuka, pesan tindak lanjut dan skills dikirim ke agent tersebut. Pada Claude Code v2.1.314 atau lebih baru, /btw menjawab dari transkrip yang terbuka. Perintah bawaan lainnya dikirim ke percakapan utama Anda, dengan pengaman berikut:

• /compact, /clear, dan /rewind bekerja pada percakapan utama, sehingga Claude Code meminta Anda untuk mengonfirmasi sebelum menjalankan salah satunya dari tampilan ini.
• /model dan /fast mengatur model dan fast mode percakapan utama, bukan milik agent yang dilihat, sehingga keduanya tidak berjalan dari tampilan ini. Sebuah pemberitahuan menjelaskan alasannya.

Agar agent yang dilihat membaca pesan Anda sebelum pekerjaan yang sedang ditunggunya selesai, kirimkan dengan Ctrl+Enter atau Ctrl+X Ctrl+S. Setiap perintah shell atau subagent yang ditunggu agent dan dapat dipindahkan ke latar belakang akan pindah ke sana dan terus berjalan. Ketika agent sedang menulis respons, atau menunggu pekerjaan yang tidak dapat dipindahkan ke latar belakang, agent tetap melanjutkan dan membaca pesan Anda setelah itu selesai. Memerlukan Claude Code v2.1.286 atau lebih baru.

Bagaimana fork berbeda dari subagent lainnya

Fork mewarisi segalanya yang dimiliki sesi utama pada saat spawn. Subagent lainnya dimulai segar dari definisinya.

Karena system prompt fork dan definisi tool identik dengan induk, permintaan pertamanya menggunakan kembali prompt cache induk. Karena penggunaan kembali tersebut, fork lebih murah daripada subagent segar untuk tugas yang memerlukan konteks yang sama.

Ketika Claude menelurkan fork melalui alat Agent, Claude dapat melewatkan isolation: "worktree" sehingga edit file fork ditulis ke git worktree terpisah daripada checkout Anda. Fork tidak dapat menelurkan fork lebih lanjut.

Nonaktifkan mode fork

Mode fork memungkinkan Claude memulai fork sendiri. Untuk menghentikan Claude dari memulai fork:

• Hentikan fork saja: tambahkan "Agent(fork)" ke permissions.deny dalam pengaturan Anda.
• Nonaktifkan mode fork: atur CLAUDE_CODE_FORK_SUBAGENT ke 0, dengan mengikuti langkah-langkah di Biarkan Claude menunggu subagent.

Selama mode fork aktif, Claude juga tidak dapat menunggu subagent dalam sesi terminal interaktif, VS Code, atau desktop di mesin Anda. Mode fork aktif secara default sejak Claude Code v2.1.302, dan dalam sesi terminal interaktif sejak v2.1.232.

Contoh subagent

Contoh-contoh ini mendemonstrasikan pola efektif untuk membangun subagent. Gunakan mereka sebagai titik awal, atau hasilkan versi yang disesuaikan dengan Claude.

[!TIP]

Best practices:

• Desain subagent yang terfokus: setiap subagent harus unggul dalam satu tugas spesifik
• Tulis deskripsi yang menonjolkan satu subagent: Claude menggunakan deskripsi untuk memutuskan kapan mendelegasikan. Buat setiap deskripsi cukup spesifik untuk merutekan ke subagent yang tepat, dan pertahankan set gabungan dalam anggaran deskripsi 15.000-token
• Batasi akses alat: berikan hanya izin yang diperlukan untuk keamanan dan fokus
• Periksa ke dalam kontrol versi: bagikan subagent proyek dengan tim Anda

Peninjau kode

Subagent hanya-baca yang meninjau kode tanpa memodifikasinya. Contoh ini menunjukkan cara merancang subagent yang terfokus dengan akses alat terbatas yang mengecualikan Edit dan Write, dan prompt terperinci yang menentukan dengan tepat apa yang harus dicari dan cara memformat output.

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

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.

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

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 menetapkan model: sonnet untuk analisis yang lebih mampu.

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

Validator kueri database

Subagent yang memungkinkan akses Bash tetapi memvalidasi perintah untuk mengizinkan hanya kueri SQL hanya-baca. Contoh ini menunjukkan cara menggunakan hooks PreToolUse untuk validasi bersyarat ketika Anda memerlukan kontrol lebih halus daripada bidang tools.

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

Claude Code melewatkan input hook sebagai JSON melalui stdin ke perintah hook. Skrip validasi membaca JSON ini, mengekstrak perintah yang sedang dijalankan, dan memeriksanya terhadap daftar operasi penulisan SQL. Jika operasi penulisan terdeteksi, skrip keluar dengan kode 2 untuk memblokir eksekusi dan mengembalikan pesan kesalahan ke Claude melalui stderr.

Buat skrip validasi di mana saja dalam proyek Anda. Jalur harus cocok dengan bidang command dalam konfigurasi hook Anda:

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

Di macOS dan Linux, buat skrip dapat dieksekusi:

chmod +x ./scripts/validate-readonly-query.sh

Di Windows, tulis skrip validasi dalam PowerShell dan tambahkan 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.

Prompt sistem memberitahu subagent untuk menolak permintaan penulisan, jadi hook adalah backstop: jika subagent mencoba penulisan bagaimanapun, Claude Code memblokir perintah dan subagent melihat pesan Blocked: Write operations not allowed. Use SELECT queries only..

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