Cara membuat dan menggunakan Subagen di Claude Code—panduan praktis

Subagen adalah salah satu tambahan paling berguna bagi ekosistem Claude Code / Claude Agent: mereka memungkinkan Anda membagi alur kerja yang kompleks menjadi "rekan tim" AI yang lebih kecil dan spesialis, mempertahankan konteks utas utama, dan membatasi akses alat dengan aman. Artikel ini menjelaskan apa itu subagen, cara membuat dan memanggilnya (CLI, sistem berkas, dan SDK), prinsip desain Anda harus mengikuti ketika membangunnya, dan contoh kode konkret Anda dapat menyalin dan mengadaptasinya.

Apa itu Subagen?

A subagen adalah asisten AI pra-konfigurasi dengan cakupan sempit yang dapat didelegasikan pekerjaan oleh Claude Code (atau Claude Agent SDK). Setiap subagen:

Memiliki nama yang unik dan deskripsi tujuan yang jelas.
Berjalan di dalamnya jendela konteks sendiri terpisah dari percakapan utama (sehingga rangkaian detail yang panjang tidak mencemari konteks pengatur).
Dapat dikonfigurasi dengan set terbatas alat (baca/tulis file, bash, grep, alat MCP, dll.), dan dengan pilihan model tertentu.
Berisi perintah sistem (kepribadian dan instruksi subagen) yang memandu perilaku dan batasan.

Properti ini membuat subagen ideal untuk tugas yang banyak menggunakan token (penelitian, mencari log besar), sensitif terhadap keamanan (pemindaian atau alat yang berpotensi merusak), atau berulang dan ditentukan dengan baik (pemeriksaan gaya, menjalankan pengujian).

Anthropic telah melakukan iterasi dengan cepat: Claude Code CLI dan Agent SDK telah difaktorkan ulang dan diperluas ke SDK Agen Claude, dukungan plugin telah diperkenalkan untuk menggabungkan agen dan kustomisasi terkait (perintah slash, server MCP, hook), dan Keterampilan menyediakan cara untuk mengemas alur kerja domain agar dapat digunakan kembali di Claude.ai, Claude Code, dan Agent SDK. Pembaruan ini memudahkan untuk berbagi, instal, dan versi subagen di seluruh tim dan proyek. Jika Anda berencana membangun alur kerja produksi, Anda harus mengevaluasi paket plugin/keterampilan dan pola penerapan berbasis SDK.

Mengapa Subagen Penting

Tiga alasan mengapa mereka langsung berguna:

Pelestarian konteks —Pencarian, uji coba, atau pemindaian yang panjang atau berisik dilakukan di dalam subagen, alih-alih mendominasi konteks utama. Hal ini mengurangi pemborosan token dan membuat hasil lebih mudah dipahami.
Keahlian khusus — Anda dapat mengodekan pengetahuan dan perilaku domain dalam perintah sistem yang disesuaikan dengan tugas (misalnya, security-auditor yang berfokus pada rahasia, masalah ketergantungan, dan penggunaan shell yang tidak aman).
Izin yang lebih aman — membatasi alat per subagen mengurangi radius ledakan (seorang peninjau dokumen mungkin memiliki alat hanya-baca; seorang pelari pengujian memiliki Bash tapi tidak Edit).
Paralelisasi: Anda dapat menjalankan beberapa subagen secara bersamaan (misalnya: style-checker, security-scanner, test-runner) dan kemudian mengumpulkan hasil singkatnya — sebuah kemenangan besar bagi pemeriksaan independen yang mahal.

Prasyarat untuk menggunakan Subagen di Claude Code

Sebelum Anda mulai membangun Subagen, pastikan Anda memiliki hal-hal berikut:

1) Kode Claude terinstal dan terautentikasi

Instal Claude Code CLI atau gunakan integrasi web/IDE. Dokumentasi memulai dan pengaturan CometAPI daftar metode instalasi yang didukung (paket global npm atau penginstal asli) dan tunjukkan cara memverifikasi instalasi Anda dengan claude --version / claude doctorAnda juga akan membutuhkan API Komet akun (Menggunakan kunci CometAPI untuk mengakses kode Claude lebih murah dan lebih nyaman daripada model resmi.) sebagaimana tercantum dalam Quickstart.

2) Node / lingkungan (untuk beberapa jalur instalasi) dan perkakas shell dasar

Jika Anda menginstal melalui paket npm, Anda harus memiliki Node.js (Node 18+ umum digunakan dalam contoh). Jika Anda ingin menggunakan SDK Agen (JavaScript/TypeScript atau Python), Anda memerlukan proyek dengan dependensi SDK yang terpasang. Banyak tutorial mengasumsikan penggunaan perkakas pengembang standar (git, bash, opsional). gh CLI untuk alur kerja GitHub).

3) Tata letak proyek & CLAUDE.md

Praktik terbaik adalah menyimpan dokumen pembantu tingkat repo (CLAUDE.md) dan menempatkan agen yang memiliki cakupan proyek di .claude/agents/ Jadi, rekan satu tim mewarisinya. File CLAUDE.md ditarik ke dalam konteks Claude secara otomatis dan membantu memandu perilaku secara konsisten di seluruh sesi. Setiap subagen adalah file Markdown dengan frontmatter YAML. Contoh minimal:

---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after code changes to check security, style, and maintainability.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer. When invoked:
1. Run `git diff` to identify modified files.
2. Focus review on changed code paths.
3. List security issues, probable false positives, and suggested fixes.
4. Provide a short, prioritized action list.

Return results in JSON with fields: summary, issues.

name adalah pengenal huruf kecil.
description panduan pemanggilan dan pencocokan otomatis.
tools membatasi akses alat (tidak mewarisi semuanya).
model dapat sonnet, opus, haiku, atau inherit.

4) Izin & server MCP (opsional tetapi umum)

Jika alur kerja Anda menggunakan server Model Context Protocol (MCP) atau alat eksternal (Puppeteer, Sentry, alat REST kustom), pastikan server MCP Anda dikonfigurasi dan dapat diakses. Untuk operasi sensitif (tulis, bash, git commit), pertimbangkan dengan saksama daftar putih dan per agen. tools penentuan ruang lingkup.

Cara membuat Subagen di Claude Code

Anda dapat membuat subagen dengan tiga cara utama: melalui CLI interaktif (/agents), sebagai file markdown sistem berkas, atau secara terprogram melalui SDK Agen. Berikut adalah opsi langkah demi langkah:

Claude Code mendukung tiga cara praktis untuk membuat subagen:

CLI interaktif /agents UI — tercepat untuk pembuatan berulang dalam satu sesi.
Berbasis sistem berkas — membuat file Markdown dengan frontmatter YAML di .claude/agents/ (tingkat proyek) atau ~/.claude/agents/ (tingkat pengguna). Agen proyek memiliki prioritas lebih tinggi.
Terprogram (SDK Agen) — mendefinisikan subagen dalam kode melalui agents parameter saat Anda memanggil query(); direkomendasikan untuk aplikasi berbasis SDK. Pendekatan ini ideal ketika subagen harus dibuat secara dinamis atau disematkan dalam aplikasi.

Alur interaktif cepat (langkah pertama yang disarankan)

Jalankan Claude Code di terminal Anda atau buka palet perintah di VS Code.
Jalankan antarmuka subagents dengan perintah slash:

/agents

Pilih Buat Agen Baru, pilih cakupan tingkat proyek atau tingkat pengguna, isi nama/deskripsi/alat/perintah sistem, lalu simpan. Anda dapat membuat draf dengan Claude lalu menyempurnakannya. Setelah disimpan, agen tersedia di /agents dan dapat dipanggil secara eksplisit atau otomatis.

Subagen berbasis sistem berkas (Markdown + YAML frontmatter)

Subagen disimpan sebagai file Markdown dengan frontmatter YAML. Tempatkan di:

Ruang lingkup proyek: .claude/agents/*.md (prioritas tertinggi)
Cakupan pengguna: ~/.claude/agents/*.md

Struktur berkas dasar:

---
name: code-reviewer
description: "Review recent code changes for security and style."
tools: Read, Grep, Glob, Bash  # optional; omit to inherit

model: sonnet  # optional; or 'inherit'

---
You are a senior code reviewer with expertise in security, performance, and best practices.
When reviewing:
- Identify security vulnerabilities
- Prioritize clarity and maintainability
- Always provide concise examples and suggested fixes
- If unsure, ask for the minimal reproducible snippet

Beberapa catatan implementasi:

name harus huruf kecil dengan tanda hubung.
Menghilangkan tools akan membiarkan subagen mewarisi semua alat dari utas utama; mencantumkan alat secara eksplisit akan menegakkan model hak istimewa paling rendah.
penggunaan model: 'inherit' untuk perilaku yang konsisten dengan utas utama, atau tentukan alias model (misalnya, sonnet, opus, haiku).

Definisi CLI JSON (penggunaan ad hoc/sesi)

Anda dapat menentukan subagen sementara secara inline saat meluncurkan sesi:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer.",
    "prompt": "You are a senior code reviewer. Focus on security and best practices.",
    "tools": ,
    "model": "sonnet"
  }
}'

Agen yang ditentukan CLI berguna untuk menjalankan skrip atau eksperimen; agen ini memiliki prioritas lebih rendah daripada agen proyek tetapi lebih tinggi daripada agen pengguna.

Definisi terprogram (SDK Agen — direkomendasikan untuk aplikasi)

Jika Anda sedang membangun aplikasi atau otomatisasi, tentukan subagen secara terprogram melalui SDK Agen agents parameter (ini adalah opsi yang paling terintegrasi). Contoh (TypeScript):

import { query } from '@anthropic-ai/claude-agent-sdk';

async function runReview() {
  const result = await query({
    prompt: "Assess the authentication module for security issues",
    options: {
      agents: {
        "code-reviewer": {
          description: "Expert code review specialist",
          prompt: `You are a code review specialist...`,
          tools: ,
          model: "sonnet"
        },
        "test-runner": {
          description: "Runs the test suite and analyzes failures",
          prompt: `You run tests and summarize failures...`,
          tools: ,
          model: "sonnet"
        }
      }
    }
  });

  console.log(result);
}

SDK juga menerima agen berbasis sistem berkas (akan memuat .claude/agents/ (file) jika Anda lebih suka pola tersebut. Agen terprogram sangat ampuh untuk alur kerja dinamis dan integrasi CI.

Untuk Python, claude-agent-sdk paket mendukung pola serupa: Anda dapat menggunakan query() or ClaudeSDKClient dan konfigurasikan opsi, alat, dan server MCP secara terprogram. Lihat repositori Python SDK untuk contoh panduan cepat.

Cara memanggil subagen

Delegasi otomatis

Kode Claude bisa secara otomatis Pilih subagen ketika perintah pengguna sesuai dengan tujuan subagen. Ini berguna untuk orkestrasi latar belakang di mana agen utama mengarahkan tugas ke spesialis yang tepat secara otomatis. Andalkan deskripsi subagen yang jelas dan perintah sistem yang terfokus untuk meningkatkan akurasi pemilihan otomatis.

Pemanggilan eksplisit (disarankan untuk kejelasan)

Anda dapat secara eksplisit memanggil agen dalam percakapan:

> Use the code-reviewer subagent to check my recent changes

Pemanggilan eksplisit bersifat deterministik dan direkomendasikan untuk alur produksi di mana Anda ingin menghindari delegasi yang tidak terduga.

Pola orkestrasi SDK

Pola umum dalam aplikasi SDK:

Garpu + kumpulkan: Luncurkan beberapa subagen secara paralel, kumpulkan jawaban ringkas setiap agen, lalu rangkum/gabungkan hasilnya di agen utama.
Lingkaran pengawas:Orkestrasi menugaskan tugas kepada subagen, memeriksa hasil, dan menerimanya atau meminta perhitungan ulang/klarifikasi.
Eksekusi kotak pasir: Memberikan kemampuan yang berpotensi membahayakan (menyebarkan, menjalankan skrip) ke agen yang dibatasi secara ketat dan memerlukan persetujuan manusia yang eksplisit sebelum mengeksekusi.

Pola ini dipetakan ke implementasi praktis menggunakan manajemen sesi, kait, dan alat MCP SDK Agen.

Cara membuat subagen yang berguna, aman, dan dapat dikomposisi

1) Tanggung jawab tunggal dan perintah yang jelas

Setiap subagen harus memiliki satu tujuan yang jelas dan perintah sistem yang menentukan batasan, kriteria keberhasilan, dan format keluaran. Jika keluaran yang diinginkan terstruktur (JSON, daftar poin, patch kode), instruksikan subagen secara tepat untuk mengurangi kesalahan penguraian.

2) Hak istimewa paling rendah untuk alat

Berikan hanya alat yang dibutuhkan subagen. Misalnya, peninjau dokumen tidak memerlukan Write or BashDefault ke baca-saja jika memungkinkan dan tingkatkan izin alat secara eksplisit bila diperlukan. Ini mengurangi risiko dan menyederhanakan audit.

3) Kembalikan keluaran yang ringkas dan terstruktur

Subagen harus kembali jawaban singkat dan final alih-alih jejak pemikiran yang panjang. Pola yang umum adalah: melakukan pekerjaan berat dalam konteks subagen, lalu mengembalikan ringkasan singkat dengan lampiran (patch, referensi berkas, JSON). Ini memaksimalkan efisiensi konteks untuk orkestrator.

4) Testabilitas dan versi

Simpan berkas subagen di kontrol versi, buat uji CI yang menjalankan uji coba nyata terhadap input kecil, dan pin model/toolset. Jika Anda mengandalkan Keterampilan dan plugin, terapkan pasar plugin/pola versi untuk mengelola pemutakhiran dan pengembalian.

5) Kait audit dan titik pemeriksaan yang melibatkan manusia

Gunakan kait SDK untuk mencegat pemanggilan alat (kait PreToolUse) dan mewajibkan persetujuan manusia untuk tindakan destruktif. Catat semua pemanggilan alat untuk audit yang dapat diputar ulang. SDK menyediakan kait dan mesin izin untuk mendukung pola ini.

Contoh aplikasi — alur kerja kecil seperti produksi

Berikut adalah contoh ringkas yang memperlihatkan bagian-bagian umum: agen sistem berkas, pemanggilan SDK yang menggunakan dua agen (satu untuk peninjauan, satu untuk pengujian), dan orkestrasi sederhana.

1) Agen sistem berkas: `.claude/agents/code-reviewer.md`

---
name: code-reviewer
description: Use PROACTIVELY after code changes. Perform security, style, and maintainability review on modified files.
tools: Read, Grep, Glob
model: inherit
---
You are a meticulous senior code reviewer. When invoked:
1. Run `git diff --name-only` to find modified files.
2. For each modified file, read and look for security issues, suspicious patterns, or maintainability problems.
3. Return JSON:
{
  "summary": "one-line summary",
  "issues": ,
  "recommended_changes": 
}

2) Orkestrasi terprogram (Node.js)

import { query } from '@anthropic-ai/claude-agent-sdk';
import fs from 'fs';

async function runPipeline() {
  const result = query({
    prompt: 'Run PR checks: security review then unit tests.',
    options: {
      agents: {
        'code-reviewer': {
          description: 'Use PROACTIVELY after code changes; output JSON with issues.',
          prompt: fs.readFileSync('./.claude/agents/code-reviewer.md', 'utf8'),
          tools: ,
          model: 'sonnet'
        },
        'test-runner': {
          description: 'Run test suite and summarize failing tests.',
          prompt: `You are a test-runner. Execute tests and return JSON { summary, failing_tests[] }`,
          tools: 
        }
      }
    }
  });

  for await (const message of result) {
    // Implement streaming logic: messages may include subagent outputs
    console.log(message);
  }
}

runPipeline().catch(console.error);

Catatan: itu code-reviewer disimpan dalam repo untuk digunakan kembali oleh tim; panggilan SDK menunjukkan agen terprogram yang diutamakan dan tools cakupan mencegah penulisan yang tidak disengaja.

Topik & pola lanjutan

Konfigurasi agen dinamis

Buat pabrik agen berparameter yang memilih model dan set alat tergantung pada lingkungan (dev vs. prod) atau tingkat keparahan (misalnya, strict vs balanced mode keamanan). Contoh SDK menunjukkan cara membuat definisi agen saat runtime.

Paralelisasi

Pisahkan beberapa agen analisis baca-saja secara paralel (gaya, keamanan, cakupan pengujian) dan agregasi keluaran JSON mereka di utas utama. Hal ini sangat mengurangi waktu tunggu untuk repositori besar.

Agen yang disediakan plugin

Plugin dapat menyediakan subagen yang dikemas dengan manifes plugin; mereka muncul di /agents bersama agen kustom dan dapat dipanggil secara eksplisit. Gunakan ini untuk mendistribusikan agen standar ke seluruh tim.

Dimana penggunaan kode Claude CLI paling direkomendasikan

Sangat menggembirakan untuk mengumumkan bahwa CometAPI kini sepenuhnya mendukung Claude Code cli yang canggih. Anda hanya perlu menginstal Claude Code dan mengautentikasi dengan kunci API Comet dan alamat dasar yang diperoleh untuk menggunakan model API Comet pada Claude Code.

Mengapa menggunakan kode claude melalui CometAPI?

Fitur-fitur utama Kecerdasan Buatan: Mudah menghasilkan, men-debug, dan mengoptimalkan kode menggunakan model yang dibuat khusus untuk pengembang.

Pemilihan Model yang Fleksibel: Berbagai model kami yang komprehensif memungkinkan Anda mengembangkan dengan lebih lancar.
Integrasi yang Lancar: API selalu tersedia. Integrasikan Claude Code langsung ke alur kerja Anda yang sudah ada dalam hitungan menit.
Menggunakan Claude Code melalui CometAPI akan menghemat lebih banyak biayaAPI Claude yang disediakan oleh CometAPI mendapatkan diskon 20% dari harga resmi dan diperbarui dengan model terbaru oleh pihak resmi.

Siap menggunakan Claude Code cli? konsultasikan Panduan API untuk petunjuk rinci.

Jika Anda ingin mengetahui lebih banyak tips, panduan, dan berita tentang AI, ikuti kami di VK, X dan Discord!

Lihat Juga Bagaimana Cara Menginstal dan Menjalankan Kode Claude melalui CometAPI?

Pesan terakhir

Perlakukan Subagen sebagai persona mikro yang dapat digunakan kembali dan memiliki versiMulailah dari yang kecil: buatlah doc-reviewer dan test-runner untuk repo, periksa mereka ke .claude/agents/, dan mengotomatiskannya di CI menggunakan headless claude -pUlangi perintah Anda, tambahkan keluaran terstruktur, dan perketat izin alat.

Model mental yang paling membantu: bayangkan Claude sebagai manajer proyek dan subagen sebagai spesialis dalam tim. Manajer mendelegasikan tugas-tugas yang dirumuskan dengan jelas, mengumpulkan hasil kerja para spesialis, dan menulis laporan akhir. Seiring waktu, Anda akan melihat peningkatan dalam keandalan, kemampuan pengujian, dan kemampuan untuk mengotomatiskan sebagian besar alur kerja pengembang.

Apa itu Subagen?

Mengapa Subagen Penting

Prasyarat untuk menggunakan Subagen di Claude Code

1) Kode Claude terinstal dan terautentikasi

2) Node / lingkungan (untuk beberapa jalur instalasi) dan perkakas shell dasar

3) Tata letak proyek & CLAUDE.md

4) Izin & server MCP (opsional tetapi umum)

Cara membuat Subagen di Claude Code

Alur interaktif cepat (langkah pertama yang disarankan)

Subagen berbasis sistem berkas (Markdown + YAML frontmatter)

Definisi CLI JSON (penggunaan ad hoc/sesi)

Definisi terprogram (SDK Agen — direkomendasikan untuk aplikasi)

Cara memanggil subagen

Delegasi otomatis

Pemanggilan eksplisit (disarankan untuk kejelasan)

Pola orkestrasi SDK

Cara membuat subagen yang berguna, aman, dan dapat dikomposisi

1) Tanggung jawab tunggal dan perintah yang jelas

2) Hak istimewa paling rendah untuk alat

3) Kembalikan keluaran yang ringkas dan terstruktur

4) Testabilitas dan versi

5) Kait audit dan titik pemeriksaan yang melibatkan manusia

Contoh aplikasi — alur kerja kecil seperti produksi

1) Agen sistem berkas: `.claude/agents/code-reviewer.md`

2) Orkestrasi terprogram (Node.js)

Topik & pola lanjutan

Konfigurasi agen dinamis

Paralelisasi

Agen yang disediakan plugin

Dimana penggunaan kode Claude CLI paling direkomendasikan

Mengapa menggunakan kode claude melalui CometAPI?

Pesan terakhir

Baca Selengkapnya

500+ Model dalam Satu API

Cara membuat dan menggunakan Subagen di Claude Code—panduan praktis

Apa itu Subagen?

Mengapa Subagen Penting

Prasyarat untuk menggunakan Subagen di Claude Code

1) Kode Claude terinstal dan terautentikasi

2) Node / lingkungan (untuk beberapa jalur instalasi) dan perkakas shell dasar

3) Tata letak proyek & CLAUDE.md

4) Izin & server MCP (opsional tetapi umum)

Cara membuat Subagen di Claude Code

Alur interaktif cepat (langkah pertama yang disarankan)

Subagen berbasis sistem berkas (Markdown + YAML frontmatter)

Definisi CLI JSON (penggunaan ad hoc/sesi)

Definisi terprogram (SDK Agen — direkomendasikan untuk aplikasi)

Cara memanggil subagen

Delegasi otomatis

Pemanggilan eksplisit (disarankan untuk kejelasan)

Pola orkestrasi SDK

Cara membuat subagen yang berguna, aman, dan dapat dikomposisi

1) Tanggung jawab tunggal dan perintah yang jelas

2) Hak istimewa paling rendah untuk alat

3) Kembalikan keluaran yang ringkas dan terstruktur

4) Testabilitas dan versi

5) Kait audit dan titik pemeriksaan yang melibatkan manusia

Contoh aplikasi — alur kerja kecil seperti produksi

1) Agen sistem berkas: .claude/agents/code-reviewer.md

2) Orkestrasi terprogram (Node.js)

Topik & pola lanjutan

Konfigurasi agen dinamis

Paralelisasi

Agen yang disediakan plugin

Dimana penggunaan kode Claude CLI paling direkomendasikan

Mengapa menggunakan kode claude melalui CometAPI?

Pesan terakhir

Baca Selengkapnya

500+ Model dalam Satu API

1) Agen sistem berkas: `.claude/agents/code-reviewer.md`