Subagen Claude Code: Struktur, Lima Peran, dan Orkestrasi

Apa Itu Subagen di Claude Code, dan Mengapa Itu Bukan “Skill Lain”?#

Dokumentasi Claude Code mendefinisikannya seperti ini:

Dengan istilah yang mudah dipahami pengusaha: bayangkan sebuah agensi real estat. Ada direktur, pemasar, pengacara, dan manajer penjualan. Satu pegawai yang berganti-ganti di antara semua peran ini bukanlah sebuah tim; dia adalah orang yang kewalahan. Sebuah tim terbentuk ketika setiap orang memiliki konteks dan bidang tanggung jawab sendiri, sementara direktur hanya membagikan tugas dan menyatukan hasilnya.

Subagen di Claude Code bekerja dengan cara yang sama. Obrolan utama adalah direktur. Subagen adalah spesialis dengan tugas yang cakupannya sempit, konteks sendiri, dan kumpulan alat sendiri. Ketika tugas sesuai dengan deskripsi seorang spesialis, direktur mendelegasikannya—tanpa tenggelam dalam detail.

5 Tujuan Anthropic Membuat Subagen

Dokumentasi Anthropic mencantumkan tepat lima alasan untuk membuat subagen sendiri:

Hal paling praktis dalam daftar ini bagi orang yang bukan pemrogram adalah pengendalian biaya. Anda dapat mengirim tugas riset berat ke model Haiku yang murah sambil melanjutkan percakapan utama dengan Sonnet atau Opus. Penghematan token berbanding lurus.

Periksa Dukungan Penyarangan untuk Versi yang Terpasang

Templat dalam panduan ini memakai satu sesi utama yang mendelegasikan langsung kepada pekerja. Jangan menganggap dokumentasi lama yang menyatakan “subagen tidak dapat membuat subagen lain” sebagai aturan abadi: perilaku penyarangan bergantung pada versi terpasang dan alat yang diizinkan. Panduan subagen bertingkat terpisah membahas resep khusus versi. Verifikasi dukungan pada instalasi Anda sebelum merencanakan delegasi lebih dalam.

Apa Perbedaan Subagen dengan Skill, Slash Command, dan Hook?#

Panduan sebelumnya tentang Skills menjelaskan bahwa Skills dan slash command di Claude Code pada dasarnya telah digabung menjadi satu format. Namun, subagen adalah entitas yang berbeda—bukan sekadar “skill yang lebih besar”.

Tabel ringkasan empat mekanisme:

Cara yang baik untuk mengatakannya dalam panduan berbahasa Inggris: Skills adalah resep; subagen adalah rekan kerja khusus.

Put simply: skills are recipes; subagents are specialized colleagues.

Dalam praktiknya, cara kerjanya seperti ini: Skills aktif secara otomatis ketika deskripsinya cocok dengan tugas, sedangkan subagen dipanggil secara eksplisit—entah obrolan utama memutuskan untuk mendelegasikan atau Anda memanggilnya berdasarkan nama.

Pohon Keputusan: “Mana yang Sebaiknya Saya Pilih?”

Saat Anda berpikir, “Saya perlu Claude melakukan X,” telusuri empat pertanyaan ini:

1. Apakah ini pengetahuan yang harus selalu tersedia? Misalnya, “kami melokalkan ke bahasa pilihan pengguna,” atau “kami tidak menggunakan tanda pisah panjang.” Masukkan ke CLAUDE.md.
2. Apakah ini metodologi pemicu yang sekarang Anda lakukan secara manual? Misalnya, “Saya menulis laporan penjualan setiap Senin.” Buat skill.
3. Apakah ini tugas yang akan memakai konteks obrolan utama, atau dapat dijalankan secara paralel? Misalnya, “riset mendalam dari 30 sumber,” atau “audit keamanan saat saya menulis fitur baru.” Buat subagen.
4. Apakah Anda membutuhkan respons otomatis terhadap suatu peristiwa di Claude Code? Misalnya, “jalankan linter setelah setiap Edit.” Tulis hook.

90% tugas pengusaha termasuk dalam dua kategori pertama. Subagen adalah alat tingkat lanjut, untuk saat Anda beralih dari “satu tugas pada satu waktu” ke orkestrasi.

Di Mana Subagen Disimpan, dan Mana yang Diutamakan?#

Hierarki subagen memiliki lima tingkat, diurutkan dari prioritas tertinggi ke terendah:

Logika prioritasnya sama seperti untuk Skills dan CLAUDE.md: organisasi mengesampingkan CLI, CLI mengesampingkan proyek, proyek mengesampingkan pribadi, dan pribadi mengesampingkan plugin.

Hal yang Perlu Diketahui tentang Pemuatan

Subagen dimuat saat sesi Claude Code dimulai. Jika Anda mengedit berkas agen secara manual di disk, perubahan tidak akan diterapkan sampai Anda memulai ulang sesi. Pengeditan melalui UI interaktif /agents langsung diterapkan.

Satu subagen per cakupan berarti satu berkas. Jika .claude/agents/ berisi code-reviewer.md dan code-reviewer.md lain di sebelahnya (misalnya, dari cadangan lama), Claude Code akan diam-diam mengabaikan salah satunya. Tidak akan ada pemberitahuan.

Subagen plugin merupakan hal yang terpisah. Subagen ini memiliki pembatasan keamanan: mereka tidak mendukung kolom hooks, mcpServers, dan permissionMode. Ini mencegah pemasangan plugin pihak ketiga memberinya izin untuk menjalankan kode sembarang di mesin Anda.

Struktur Berkas Subagen: Frontmatter dan Isi#

Contoh minimal dari dokumentasi resmi—hanya 9 baris:

---
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.

Itu sudah cukup. Jika pengguna berkata “tinjau PR saya” di obrolan utama, Claude mencocokkan “reviewer / code / quality” dengan deskripsi dan mendelegasikan tugas kepada subagen. Subagen membaca diff, menulis komentar, lalu mengembalikan ringkasan ke obrolan utama. Obrolan utama tidak dipenuhi log dan analisis perantara.

Skema Frontmatter Lengkap

Kolom model: haiku adalah contoh “pengendalian biaya” yang disebutkan dalam daftar lima tujuan. Jika Anda memiliki agen riset yang membaca 50 halaman dokumentasi, jalankan dengan Haiku untuk menghemat biaya hingga 5–7 kali dibandingkan Opus.

Kolom isolation: worktree menangani masalah penting: subagen membuat perubahan yang berpotensi berbahaya (refaktorisasi, migrasi), tetapi Anda tidak ingin subagen menyentuh salinan kerja Anda. Tetapkan isolation: worktree, dan Claude Code akan membuat salinan sementara proyek melalui git; subagen bekerja di sana dan mengembalikan diff untuk ditinjau.

Isi Berkas Adalah Prompt Sistem

Setelah frontmatter terdapat Markdown biasa—itulah prompt sistem subagen. Tidak diperlukan struktur khusus, tetapi pola ini sudah terbukti:

1. Siapa Anda — satu kalimat: “Anda adalah peninjau kode,” “Anda adalah auditor keamanan,” “Anda adalah pengelola dokumentasi.”
2. Kapan Anda dipanggil dan apa yang pertama kali dilakukan — 2–3 tindakan pertama setelah menerima tugas.
3. Daftar periksa pemeriksaan atau langkah — 5–10 poin yang diikuti subagen.
4. Apa yang Anda kembalikan — format laporan akhir. Ini penting: jika Anda tidak menentukan format, subagen akan menghasilkan “esai” alih-alih ringkasan terstruktur.
5. Apa yang TIDAK Anda lakukan — batasan yang eksplisit. Tanpa bagian ini, subagen akan mulai berimprovisasi.

Batasi isi berkas hingga 200–500 baris. Jika lebih panjang, pindahkan referensi yang panjang ke berkas lain di dekatnya dan tautkan dari prompt.

Cara Menulis Deskripsi agar Claude Pasti Memanggil Subagen Anda#

Masalah umum adalah menyiapkan subagen untuk tinjauan kode, tetapi Claude mengerjakan semuanya sendiri tanpa menggunakan agen. Biasanya hanya ada satu alasan: deskripsi ditulis sebagai “Helper for code review.” Claude tidak memahami kapan harus memicunya.

Rumus Deskripsi Efektif (3 Bagian)

Bagian 1 — fungsinya. Satu kalimat tentang hasilnya, bukan prosesnya. Bukan “menganalisis kode,” melainkan “menemukan kerentanan dalam kode dan mengembalikan daftar yang mencantumkan tingkat keparahan dan perbaikan.”

Bagian 2 — kapan harus dipicu. 3–5 frasa dalam tanda kutip, seperti permintaan yang benar-benar dibuat pengguna. Jangan menebak—lihat riwayat obrolan dan ungkapan nyata.

Bagian 3 — kapan TIDAK dipicu. 1–2 frasa tentang tugas serupa yang seharusnya tidak ditanggapi subagen ini. Tanpa bagian ini, dua agen serupa akan terus bertabrakan.

Frasa Ajaib “Gunakan Secara Proaktif”

Dokumentasi resmi Anthropic membuat rekomendasi langsung:

Dengan kata lain, secara bawaan Claude cenderung tidak memanggil subagen jika deskripsinya tidak memiliki sinyal yang jelas. Tambahkan “use proactively” atau “use immediately after writing code,” dan aktivasi akan meningkat tajam.

Contoh Deskripsi yang Kuat

description: |
  Expert code review specialist. Proactively reviews code for quality,
  security, and maintainability. Use immediately after writing or
  modifying code. Returns prioritized list of issues with severity
  and fix recommendations.
  Do not invoke for documentation changes, README edits, or commit
  message rewrites - these are handled by doc-maintainer.

Yang berfungsi di sini:

• Kata kerja “reviews” + “returns” menentukan hasil konkret, bukan proses.
• “Proactively” dan “immediately after” merupakan pemicu eksplisit.
• “Do not invoke for...” menutup kemungkinan bentrok dengan subagen serupa.
• Bahasa Inggris dalam description adalah hal yang lazim. Claude lebih cocok mengenalinya dalam bahasa Inggris.

5 Peran Subagen Siap Pakai yang Berfungsi dalam 10 Menit#

Setiap peran di bawah ini adalah satu berkas, .claude/agents/<name>.md. Setelah membuat berkas, mulai ulang Claude Code, buka /agents, lalu periksa apakah agen baru muncul dalam daftar. Setelah itu, Anda dapat memanggilnya dengan @agent-name.

1. code-reviewer — tinjau kode setelah setiap perubahan

Ini adalah contoh resmi dari dokumentasi Anthropic yang disesuaikan dengan alur kerja:

---
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
model: inherit
color: blue
---

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

Saat dipanggil:
1. Baca diff dan daftar file berubah yang diberikan sesi utama. Jika belum ada, minta sesi utama menyediakannya.
2. Gunakan Read, Grep, dan Glob untuk memeriksa file relevan.
3. Kembalikan temuan tanpa mengubah file atau menjalankan perintah shell.

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
- Test coverage adequate
- Performance considerations addressed

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

Format: for each issue - file:line + 1 sentence why it's a problem + concrete fix.

Kuncinya adalah tools: Read, Grep, Glob: reviewer memiliki alat baca dan pencarian file, tanpa akses Bash, Write, atau Edit. Sesi utama menyiapkan diff dan memberikannya kepada reviewer. Instruksi untuk hanya menjalankan git diff tidak akan membatasi alat Bash yang diberikan sepenuhnya.

2. security-auditor — temukan kerentanan dan kebocoran

Peran ini memakai opus untuk penalaran lebih mendalam dan pembatasan alat Read, Grep, Glob yang sama. Memori persisten tidak disertakan pada templat hanya-baca ini karena mengaktifkan memori agen juga memberinya kemampuan menulis memori:

---
name: security-auditor
description: |
  Security audit specialist. Use proactively to find OWASP Top 10
  vulnerabilities, exposed secrets, injection risks, broken auth.
  Run before any deploy or merge to main.
tools: Read, Grep, Glob
model: opus
color: red
---

You are a security auditor. Find exploitable vulnerabilities, not style issues.

Audit checklist:
- SQL / NoSQL injection
- XSS (stored, reflected, DOM-based)
- CSRF / SSRF risks
- Hardcoded secrets (API keys, tokens, passwords)
- Broken auth / session management
- Insecure deserialization
- Missing input validation
- Path traversal
- Open redirects
- Insecure direct object references (IDOR)

For each finding:
- Severity: Critical / High / Medium / Low
- File:line
- Attack scenario in 1–2 sentences
- Fix recommendation with code example

Skip linter or style noise. Report only exploitable issues.

Dari sisi alat, peran ini hanya-baca, dengan model: opus untuk pemeriksaan kompleks seperti rantai kerentanan.

3. research-agent — riset mendalam dari 8+ sumber

Pola ini dijelaskan Anthropic sendiri dalam artikelnya tentang sistem riset multi-agen. Kuncinya adalah format keluaran yang eksplisit dan larangan menumpahkan hasil mentah:

---
name: research-agent
description: |
  Deep web research specialist. Use proactively for fact-finding,
  competitive analysis, gathering external documentation, comparing
  approaches across multiple sources.
tools: WebFetch, WebSearch, Read, Write
model: sonnet
maxTurns: 30
color: purple
---

You are a research analyst. Goal: synthesized brief, not raw search dumps.

Process:
1. Decompose the question into 3–5 sub-queries
2. WebSearch each sub-query, fetch top 3–5 sources per query
3. Cross-verify claims across at least 2 independent sources
4. Reject SEO-farm and aggregator content; prefer primary sources
5. Quote verbatim with URL attribution for any specific claim
6. Return: TL;DR (3 bullets) + Findings + Sources (8+ domains minimum)

Anti-patterns to avoid:
- Don't cite a fact from a single source
- Don't paraphrase quotes as if they were verbatim
- Don't return raw search result dumps to the parent
- Don't include filler intro / outro ("Hope this helps")

maxTurns: 30 adalah perlindungan agar riset tidak berlanjut tanpa henti. Anthropic melaporkan angka ini dalam sistem multi-agen mereka:

Sembilan puluh persen merujuk pada tugas tolok ukur riset. Dalam praktiknya, peningkatannya lebih kecil untuk tugas bisnis, tetapi skalanya kurang lebih serupa.

4. doc-maintainer — jaga agar dokumentasi tetap selaras dengan kode

Peran ini menggunakan model: haiku—contoh khas “pengendalian biaya.” Dokumentasi tidak memerlukan Opus; Haiku dapat mengerjakannya dengan biaya sepertiga:

---
name: doc-maintainer
description: |
  Documentation sync specialist. Use after merging features to update
  README, API docs, CHANGELOG. Reads recent commits, identifies
  undocumented changes, updates docs proactively.
tools: Read, Write, Edit, Glob, Grep, Bash
model: haiku
memory: project
color: green
---

You maintain documentation in sync with code.

When invoked:
1. Run `git log --since="last release"` to see recent changes
2. Read README.md, docs/, CHANGELOG.md
3. Identify gaps: new features without docs, removed APIs still
   documented, version mismatches

Output:
- Updated files (use Edit, not Write - preserve existing structure)
- CHANGELOG.md entry in Keep-A-Changelog format
- List of changes you made (actual diff summary, not paraphrase)

Style rules:
- Active voice, present tense
- Code examples must be copy-pasteable
- No marketing language ("powerful", "robust", "seamless")
- No filler ("This guide will help you...")

5. refactor-agent — refaktorisasi aman melalui worktree

Peran ini menggunakan isolation: worktree—subagen bekerja di salinan repositori terpisah, dan Anda hanya menggabungkan hasilnya jika sudah sesuai:

---
name: refactor-agent
description: |
  Safe refactor specialist. Use for renames, extracts, inlines that
  shouldn't touch your working copy until reviewed. Runs in a
  temporary git worktree.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
isolation: worktree
permissionMode: acceptEdits
color: yellow
---

You refactor code without changing behavior.

Strict rules:
1. Tests must pass BEFORE and AFTER the refactor.
   If pre-refactor tests fail, STOP and report.
2. One atomic refactor per commit (extract, rename, inline).
3. Never change public APIs without explicit instruction.
4. Never modify tests unless they test the refactored implementation
   directly.

Process:
- Run test suite -> baseline
- Make atomic refactor
- Run test suite -> verify
- Commit with conventional message: refactor(scope): what

Return: summary of changes + worktree path so user can diff and merge.

Dengan peran ini, masalah refaktorisasi yang paling merepotkan—“saya merusaknya dan tidak tahu cara mengembalikannya”—dapat dihindari: salinan asli tetap utuh, sementara subagen bekerja di worktree terisolasi.

Bagaimana Mengintegrasikan Subagen dengan CLAUDE.md, Skills, dan Second Brain?#

Menjalankan 5 Subagen Secara Paralel: Orkestrator + Pekerja#

Orkestrasi paralel adalah pengaturan “konduktor + orkestra”. Konduktor memegang rencana, tidak menulis not, dan memeriksa permainan para musisi. Jika seseorang memainkan not yang salah, konduktor memintanya mengulang alih-alih mencoba menyelesaikannya sendiri.

Analogi yang lebih dekat bagi pengusaha adalah agensi pemasaran yang menyiapkan strategi untuk klien baru. Seorang analis mengerjakan SWOT, yang lain menganalisis pesaing, orang ketiga menyusun profil audiens, analis senior menyaring hipotesis yang tidak sesuai anggaran, dan manajer proyek menyusun presentasi akhir. Di Claude Code, alur ini dimulai dengan satu kalimat—dan pemeriksa sudah menjadi bagian dari proses, bukan baru datang setelahnya.

Prompt Orkestrasi Minimal

Satu kalimat dalam obrolan utama sudah cukup:

Launch five subagents in parallel: three research-agents on different sources
(Anthropic docs, GitHub repos, AI bloggers), one critic-agent to filter out
weak conclusions, and one summary-agent for the final document.

Context: I am writing a guide about X. Target length: 2,000 words with sources.
Before starting, each one reads CLAUDE.md.

Claude lalu mendelegasikan tugas kepada lima agen. Masing-masing bekerja dalam konteksnya sendiri: agen riset menggunakan sumber masing-masing, pengkritik menyaring, dan agen ringkasan menyusun hasilnya. Hanya ringkasan akhir yang kembali ke obrolan utama.

Kapan Paralelisme Menguntungkan

Tidak selalu. Eksekusi paralel hanya masuk akal jika:

1. Tugas-tugasnya independen. Jika research-agent #2 menunggu hasil research-agent #1, tidak akan ada paralelisme—mereka pada dasarnya bekerja berurutan.
2. Tugas-tugasnya memakan waktu lama. Memparalelkan “hapus spasi di akhir baris” tidak ada gunanya; waktu untuk menjalankan subagen akan menghabiskan keuntungannya.
3. Anda memiliki batas penggunaan yang cukup. Lebih lanjut tentang ini di bagian terpisah di bawah—subagen paralel menghabiskan token dengan cepat.

Multi-Agent v2 dari Anthropic: Langkah Berikutnya

Pada Mei 2026, Anthropic merilis Multi-Agent Orchestration v2 dengan tiga perbedaan penting dari pendekatan klasik yang menjalankan subagen secara paralel. Lebih lanjut tentang ini di bagian berikutnya.

Hal Baru di Multi-Agent v2: Orkestrasi, Hasil, Dreaming#

Multi-Agent Orchestration: Sistem Berkas Bersama + Check-in di Tengah Alur Kerja

Anthropic menjelaskan fitur ini seperti berikut:

Perbedaan utama dari subagen klasik adalah sistem berkas bersama. Sebelumnya, setiap subagen bekerja dalam isolasi penuh, dan pertukaran hanya terjadi melalui ringkasan yang dikembalikan. Kini para spesialis dapat menulis ke folder bersama, dan agen pemimpin membaca hasil seiring pekerjaan berlangsung, bukan hanya di akhir. Ini mengatasi masalah “semua orang bekerja seharian, lalu ternyata dua orang menggunakan pendekatan yang tidak cocok satu sama lain.”

Kedua adalah check-in di tengah alur kerja. Agen pemimpin dapat berhenti sejenak dan bertanya kepada spesialis mana pun “bagaimana perkembangannya,” lalu menyesuaikan rencana keseluruhan. Ini mirip dengan cara kerja manajer tim sungguhan.

Outcomes: Rubrik, Bukan Petunjuk Langkah demi Langkah

Dengan Outcomes, Anda menulis kriteria keberhasilan, dan agen mencari cara untuk mencapainya. Agen penilai terpisah memeriksa hasilnya dalam konteksnya sendiri agar tidak “terkontaminasi” oleh penalaran agen utama.

Sepuluh persen untuk tugas menantang merupakan peningkatan besar. Terutama ketika tugas dirumuskan sebagai “susun artikel panjang yang memenuhi kriteria kualitas ini,” alih-alih “ikuti langkah 1–7.”

Dreaming: Agen Mengumpulkan Pengalaman Antar-Sesi

Ini adalah fitur yang paling baru secara konsep. Agen menelusuri sesi sebelumnya, menemukan pola dalam keberhasilan dan kesalahan, lalu memperbarui penyimpanan memori. Anda dapat mengatur peninjauan manual sebelum perubahan diterapkan, atau membiarkannya mengedit memori sendiri.

Anthropic melaporkan bahwa Harvey (perusahaan teknologi hukum) mengalami peningkatan keberhasilan sekitar enam kali lipat dalam tugas penyusunan dokumen hukum setelah menerapkan Dreaming. Fitur ini sudah digunakan dalam produksi, bukan hanya dalam demo.

Artinya bagi Pengusaha yang Tidak Memprogram

Multi-Agent Orchestration saat ini tersedia melalui Claude Agent SDK, bukan secara langsung di CLI Claude Code. Namun, arahnya jelas: orkestrasi beralih dari “Anda menjalankan N subagen secara manual” ke “Anda menjelaskan tugas, lalu agen pemimpin memutuskan kepada siapa dan bagaimana tugas didelegasikan.” Jika baru mulai menggunakan subagen, belum perlu khawatir tentang v2. Pelajari pola klasik “1 obrolan utama + 3–5 subagen dengan peran berbeda”, lalu dalam 3–6 bulan Anda dapat beralih secara alami ke Managed Agents.

7 Kesalahan yang Membuat Subagen Gagal#

Kesalahan 1. Deskripsi “Helper for X” Tidak Memicu

Gejalanya: Anda menulis subagen, memeriksa strukturnya, semuanya valid, tetapi Claude tidak memanggilnya untuk permintaan pengguna. Alasannya hampir selalu sama: deskripsinya abstrak, seperti “Helper for code review.” Perbaikannya: tulis 3–5 frasa nyata dari pengguna dalam tanda kutip langsung di deskripsi, ditambah “use proactively” / “use immediately after.”

Kesalahan 2. Membuat Subagen Padahal yang Dibutuhkan Skill

Biaya subagen lebih tinggi daripada Skill—subagen membuat konteks sendiri, memuat prompt sistem sendiri, dan menggunakan lebih banyak token. Jika tugasnya singkat, tidak akan memakai konteks utama, dan dapat dikerjakan dalam satu kali proses, tugas itu sebaiknya ditangani Skill, bukan subagen. Contoh anti-pola: subagen format-validator yang memeriksa skema JSON terhadap 20 aturan. Ini seharusnya berupa Skill: satu model, tidak perlu isolasi, tidak ada konteks tambahan yang dimuat.

Kesalahan 3. Sejak Awal Menjalankan “60 Agen Paralel”

Ini ilusi yang paling umum. Anda melihat cuitan yang mengatakan, “Saya punya 1,500 agen yang bekerja,” lalu berpikir, “Saya juga harus begitu.” Dalam praktiknya, 60 agen menghabiskan batas paket Pro dalam satu jam, menghasilkan tumpukan hasil yang saling bertentangan, dan pada akhirnya Anda tidak menyelesaikan apa pun.

Seorang praktisi di Medium mengatakannya seperti ini:

Perbaikannya: mulai dengan satu subagen untuk satu tugas. Setelah menguasainya, tambahkan agen kedua dengan peran berbeda. Setelah menguasai orkestrasi dua agen, lanjutkan ke tim beranggotakan 3–5 agen. Beralih dari “kemarin baru memasang Claude Code” ke “hari ini menjalankan 20 agen secara paralel” dijamin akan merusak kode dan menghabiskan batas penggunaan.

Kesalahan 4. Memberikan Semua Alat kepada Setiap Agen

Jika peninjau kode Anda memiliki akses ke Bash, Write, dan WebFetch, itu adalah celah keamanan dan biaya yang besar. Peninjau tidak seharusnya memiliki izin menulis berkas, apalagi mengakses internet.

Perbaikannya: batasi tools secara ketat. Peninjau kode hanya mendapat Read, Grep, Glob. Auditor keamanan mendapat alat baca/pencarian yang sama dan diff dari sesi utama. Menambahkan Bash memberi kemampuan shell; itu tidak otomatis membatasi agen pada git diff. Agen riset mendapat WebFetch, WebSearch, Read, Write. Jangan berikan izin kepada subagen melebihi yang dibutuhkan untuk satu tugas tertentu.

Kesalahan 5. Subagen Menumpahkan Hasil Mentah ke Konteks Utama

Jika agen riset mengembalikan “ini semua 30 halaman yang saya temukan; silakan cari tahu sendiri” ke obrolan utama, Anda kehilangan keunggulan utama subagen: isolasi dari kebisingan. Perbaikannya: wajibkan format keluaran secara eksplisit dalam prompt sistem subagen. “Kembalikan HANYA: TL;DR 3 butir + daftar 5 sumber. TANPA dump kode, TANPA hasil pencarian mentah.” Format ini harus ketat—subagen tidak boleh bebas “mengubahnya menjadi esai.”

Kesalahan 6. Pemanggilan Samar: Permintaan Delegasi yang Tidak Jelas

Subagen tidak dapat melihat riwayat dialog utama. Subagen memulai dengan konteks bersih + CLAUDE.md + apa pun yang Anda tulis secara eksplisit kepadanya. Jika Anda menulis “perbaiki autentikasi,” subagen akan mengarang informasi. Sebaliknya: “Perbaiki putaran pengalihan OAuth yang menyebabkan pengguna dialihkan ke /login alih-alih /dashboard setelah berhasil masuk. Berkas: src/lib/auth.ts.”

Aturan yang jelas: saat mendelegasikan, berikan konteks kepada subagen sebanyak yang akan Anda berikan kepada kontraktor baru yang baru bergabung dengan proyek.

Kesalahan 7. Agen Berdasarkan Peran, Bukan Berdasarkan Tugas

Pola yang menggoda adalah: “mari buat frontend-developer, backend-developer, dan qa-engineer, lalu minta mereka bekerja sebagai tim.” Ini tidak berhasil. Setiap “peran” kehilangan konteks tentang keseluruhan proyek, dan mereka tidak dapat menyepakati detail karena tidak dapat melihat satu sama lain.

Perbaikannya: subagen sebaiknya menangani tugas berulang dengan hasil yang jelas, bukan sebuah peran. Bukan “frontend-developer”, melainkan “explore-ui-tree”, “refactor-component”, “audit-accessibility”. Setiap subagen berbasis tugas mengerjakan satu pekerjaan spesifik dan mengembalikan satu hasil spesifik.

Berapa Biaya Subagen Paralel, dan Kapan Menguntungkan?#

Paket Pro akan habis dalam satu jam jika Anda menjalankan 5 subagen paralel untuk tugas kompleks. Max 5x ($100) adalah batas minimum yang realistis untuk pekerjaan paralel rutin. Untuk tim dan Enterprise, persoalan biaya sudah ditangani pada tingkat anggaran alat.

Untuk kiat menghemat token di Claude Code, lihat panduan terpisah tentang batas penggunaan. Untuk subagen, aturan utamanya adalah subagen menguntungkan jika tugas membutuhkan setidaknya 10 menit kerja terfokus. Jika tugas lebih singkat, jangan membuat subagen; kerjakan di obrolan utama atau dengan Skill.

Bagaimana Mengintegrasikan Subagen dengan CLAUDE.md, Skills, dan Second Brain?#

Subagen bergantung pada tiga hal yang sebaiknya sudah ada dalam proyek Anda sebelum membuat spesialis pertama:

1. CLAUDE.md yang tepat. Subagen membaca CLAUDE.md sebelum mulai—ini adalah “kontrak kerjanya.” Tanpanya, subagen tidak memahami konteks proyek, batasannya, atau nadanya. Subagen akan mengarang.

2. Skills dasar. Skill adalah metodologi yang dikemas. Subagen hanya memuat Skills yang dibutuhkannya, bukan semuanya sekaligus. Tanpa Skills, subagen mengulang pekerjaan yang sama dari awal setiap kali.

3. Second Brain: struktur pengetahuan. Folder business/ (atau padanannya dalam bidang Anda) adalah pustaka yang dibaca semua subagen. Tanpanya, subagen memberikan jawaban ChatGPT rata-rata yang tidak berbeda dari jawaban orang lain.

Membalik urutan ini berarti mendapatkan sensasi tanpa hasil. “Saya punya 60 subagen paralel” dengan folder business/ kosong berarti 60 sesi ChatGPT rata-rata dengan pendekatan yang sama.

Cara tercepat untuk memulai adalah menyalin code-reviewer dari contoh pertama di atas ke .claude/agents/code-reviewer.md, memulai ulang Claude Code, dan memanggil @agent-code-reviewer pada commit berikutnya. Dalam 5 menit, Anda akan tahu apakah membutuhkan subagen atau obrolan utama sudah cukup.