Cara mencipta dan menggunakan Subagen dalam Kod Claude— panduan praktikal

Subagen ialah salah satu tambahan yang paling berguna pada ekosistem Claude Code / Ejen Claude: mereka membenarkan anda memecahkan aliran kerja yang kompleks kepada "rakan sepasukan" AI yang lebih kecil dan pakar, mengekalkan konteks utas utama dan mengehadkan akses alat dengan selamat. Artikel ini menerangkan apakah subagen itu, bagaimana untuk mencipta dan memanggilnya (CLI, sistem fail dan SDK), the prinsip reka bentuk anda harus mengikuti apabila membinanya, dan kod sampel konkrit anda boleh menyalin dan menyesuaikan diri.

Apakah Subagen?

A subagen ialah pembantu AI yang diprakonfigurasikan dan berskop sempit yang Claude Code (atau Claude Agent SDK) boleh mewakilkan kerja. Setiap subagen:

Mempunyai nama yang unik dan penerangan tujuan yang jelas.
Berjalan di dalamnya tetingkap konteks sendiri berasingan daripada perbualan utama (rantai terperinci yang begitu panjang tidak mencemarkan konteks orkestra).
Boleh dikonfigurasikan dengan set terhad alat (fail baca/tulis, bash, grep, alat MCP, dll.), dan dengan pilihan model tertentu.
Mengandungi gesaan sistem (personaliti dan arahan subagen) yang membimbing tingkah laku dan kekangan.

Sifat ini menjadikan subagen sesuai untuk tugasan yang berat (penyelidikan, mencari log besar), sensitif keselamatan (pengimbasan atau alat yang berpotensi merosakkan), atau berulang dan dinyatakan dengan baik (pemeriksaan gaya, ujian berjalan).

Anthropic telah berulang dengan cepat: Claude Code CLI dan Agent SDK telah difaktorkan semula dan diperluaskan ke dalam SDK Agen Claude, sokongan pemalam telah diperkenalkan untuk ejen penggabungan dan penyesuaian yang berkaitan (arahan slash, pelayan MCP, cangkuk), dan Kemahiran menyediakan cara untuk membungkus aliran kerja domain untuk digunakan semula merentas Claude.ai, Kod Claude dan SDK Ejen. Kemas kini ini memudahkan untuk kongsi, pasang dan versi subagen merentas pasukan dan projek. Jika anda merancang untuk membina aliran kerja pengeluaran, anda harus menilai pembungkusan pemalam / kemahiran dan corak penggunaan berasaskan SDK.

Mengapa Subagen penting

Tiga sebab ia segera berguna:

Pemeliharaan konteks — carian panjang atau bising, ujian dijalankan atau imbasan secara langsung di dalam subagen dan bukannya mengatasi konteks utama. Itu mengurangkan pembaziran token dan menjadikan keputusan lebih mudah untuk difikirkan.
Kepakaran khusus — anda boleh mengekod pengetahuan dan tingkah laku domain dalam gesaan sistem yang disesuaikan dengan tugasan (cth, a security-auditor yang memfokuskan pada rahsia, isu pergantungan dan penggunaan cangkerang yang tidak selamat).
Keizinan yang lebih selamat — mengehadkan alat bagi setiap subagen mengurangkan jejari letupan (pengulas dokumen mungkin mempunyai alat baca sahaja; pelari ujian mempunyai Bash tetapi tidak Edit).
Keselarian: Anda boleh memutarkan berbilang subagen untuk dijalankan serentak (contohnya: style-checker, security-scanner, test-runner) dan kemudian kumpulkan keputusan ringkas mereka — kemenangan besar untuk cek mahal dan bebas.

Prasyarat untuk menggunakan Subagen dalam Kod Claude

Sebelum anda mula membina Subagen, pastikan anda mempunyai perkara berikut:

1) Kod Claude dipasang dan disahkan

Pasang CLI Kod Claude atau gunakan penyepaduan web/IDE. Dokumen Mula Pantas dan persediaan CometAPI senaraikan kaedah pemasangan yang disokong (pakej global npm atau pemasang asli) dan tunjukkan cara untuk mengesahkan pemasangan anda dengan claude --version / claude doctor. Anda juga memerlukan a CometAPI akaun (Menggunakan kunci CometAPI untuk mengakses kod Claude adalah lebih murah dan lebih mudah daripada model rasmi.) seperti yang dinyatakan dalam Quickstart.

2) Nod / persekitaran (untuk beberapa laluan pemasangan) dan perkakas shell asas

Jika anda memasang melalui pakej npm anda sepatutnya mempunyai Node.js (Node 18+ adalah perkara biasa dalam contoh). Jika anda berhasrat untuk menggunakan Agent SDK (JavaScript/TypeScript atau Python) anda memerlukan projek dengan kebergantungan SDK dipasang. Banyak tutorial menganggap alat pembangun standard (git, bash, pilihan gh CLI untuk aliran kerja GitHub).

3) Susun atur projek & CLAUDE.md

Amalan terbaik ialah menyimpan dokumen pembantu peringkat repo (CLAUDE.md) dan meletakkan ejen skop projek .claude/agents/ jadi rakan sepasukan mewarisi mereka. Fail CLAUDE.md ditarik ke dalam konteks Claude secara automatik dan membantu membimbing tingkah laku secara konsisten merentas sesi, setiap subagen ialah fail Markdown dengan frontmatter YAML. Contoh minima:

---
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 ialah pengecam huruf kecil.
description membimbing seruan dan pemadanan automatik.
tools menyekat akses alat (meninggalkan untuk mewarisi segala-galanya).
model boleh sonnet, opus, haiku, Atau inherit.

4) Kebenaran & pelayan MCP (pilihan tetapi biasa)

Jika aliran kerja anda menggunakan pelayan Model Context Protocol (MCP) atau alatan luaran (Puppeteer, Sentry, alatan REST tersuai), pastikan pelayan MCP anda dikonfigurasikan dan boleh dicapai. Untuk operasi sensitif (tulis, bash, git commit) pertimbangkan senarai yang dibenarkan dan setiap ejen tools skop.

Bagaimana untuk mencipta Subagen dalam Kod Claude

Anda boleh mencipta subagen dalam tiga cara utama: melalui CLI interaktif (/agents), sebagai fail penurunan nilai sistem fail, atau secara pengaturcaraan melalui Agen SDK. Di bawah adalah pilihan langkah demi langkah:

Kod Claude menyokong tiga cara praktikal untuk mencipta subagen:

CLI Interaktif /agents UI — terpantas untuk penciptaan berulang dalam sesi.
berasaskan sistem fail — buat fail Markdown dengan frontmatter YAML masuk .claude/agents/ (peringkat projek) atau ~/.claude/agents/ (peringkat pengguna). Ejen projek mempunyai keutamaan yang lebih tinggi.
Programmatic (Agent SDK) — tentukan subagen dalam kod melalui agents parameter apabila anda memanggil query(); disyorkan untuk apl dipacu SDK. Pendekatan ini sesuai apabila subagen mesti dicipta secara dinamik atau dibenamkan dalam aplikasi.

Aliran interaktif pantas (langkah pertama yang disyorkan)

Mulakan Kod Claude dalam terminal anda atau buka palet arahan dalam Kod VS.
Jalankan antara muka subagen dengan arahan slash:

/agents

Pilih Buat Ejen Baharu, pilih skop peringkat projek atau peringkat pengguna, isikan nama/huraian/alat/gesaan sistem dan simpan. Anda boleh menjana draf dengan Claude dan kemudian memperhalusinya. Setelah disimpan, ejen boleh didapati di /agents dan boleh digunakan secara eksplisit atau automatik.

Subagen berasaskan sistem fail (Markdown + frontmatter YAML)

Subagen disimpan sebagai fail Markdown dengan frontmatter YAML. Letakkannya di:

Skop projek: .claude/agents/*.md (keutamaan tertinggi)
Skop pengguna: ~/.claude/agents/*.md

Struktur fail asas:

---
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 nota pelaksanaan:

name mestilah huruf kecil dengan sempang.
Meninggalkan tools akan membiarkan subagen mewarisi semua alatan utas utama; alat penyenaraian secara eksplisit menguatkuasakan model yang paling tidak istimewa.
Penggunaan model: 'inherit' untuk tingkah laku yang konsisten dengan utas utama, atau nyatakan alias model (cth, sonnet, opus, haiku).

Definisi CLI JSON (penggunaan ad hoc/sesi)

Anda boleh menentukan subagen sementara sebaris apabila melancarkan 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"
  }
}'

Ejen yang ditakrifkan CLI berguna untuk larian atau percubaan berskrip; mereka mempunyai keutamaan yang lebih rendah daripada ejen projek tetapi lebih tinggi daripada ejen pengguna.

Takrifan program (SDK Agen — disyorkan untuk apl)

Jika anda sedang membina aplikasi atau automasi, tentukan subagen secara pemprograman melalui SDK Agen agents parameter (ini adalah pilihan yang paling bersepadu). 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 ejen berasaskan sistem fail (ia akan dimuatkan .claude/agents/ fail) jika anda lebih suka corak itu. Ejen pengaturcaraan berkuasa untuk aliran kerja dinamik dan penyepaduan CI.

Untuk Python, the claude-agent-sdk pakej menyokong corak yang serupa: anda boleh gunakan query() or ClaudeSDKClient dan konfigurasikan pilihan, alatan dan pelayan MCP secara pengaturcaraan. Lihat repo Python SDK untuk sampel permulaan pantas.

Bagaimana untuk memanggil subagen

Perwakilan automatik

Claude Code boleh secara automatik pilih subagen apabila gesaan pengguna sepadan dengan tujuan subagen. Ini berguna untuk orkestrasi latar belakang di mana ejen utama mengarahkan tugas kepada pakar yang betul secara automatik. Bergantung pada perihalan subagen yang jelas dan gesaan sistem terfokus untuk meningkatkan ketepatan pemilihan automatik.

Seruan eksplisit (disyorkan untuk kejelasan)

Anda boleh memanggil ejen secara eksplisit dalam perbualan:

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

Seruan eksplisit adalah deterministik dan disyorkan untuk aliran pengeluaran yang anda mahu mengelakkan perwakilan yang tidak dijangka.

Corak orkestra SDK

Corak biasa dalam apl SDK:

Garpu + kumpul: Lancarkan berbilang subagen secara selari, kumpulkan jawapan ringkas setiap ejen, kemudian rumuskan/gabungkan hasil dalam ejen utama.
Gelung penyelia: Orkestra memberikan tugas kepada subagen, memeriksa keputusan, dan sama ada menerimanya atau meminta pengiraan semula/penjelasan.
Pelaksanaan kotak pasir: Berikan keupayaan yang berpotensi berbahaya (kerahkan, jalankan skrip) kepada ejen yang dikekang ketat dan memerlukan cangkuk kelulusan manusia yang jelas sebelum melaksanakan.

Corak ini dipetakan kepada pelaksanaan praktikal menggunakan pengurusan sesi, cangkuk dan alatan MCP Agen SDK.

Bagaimana untuk membuat subagen yang berguna, selamat, dan boleh dibuat

1) Tanggungjawab tunggal dan arahan yang jelas

Setiap subagen harus mempunyai satu tujuan yang jelas dan gesaan sistem yang menentukan sempadan, kriteria kejayaan dan format output. Jika output yang diingini berstruktur (JSON, senarai bullet, patch kod), arahkan subagen dengan tepat untuk mengurangkan ralat penghuraian.

2) Keistimewaan paling sedikit untuk alatan

Berikan hanya alat yang diperlukan oleh subagen. Sebagai contoh, penyemak dokumen tidak perlu Write or Bash. Lalai kepada baca sahaja jika boleh dan tingkatkan kebenaran alat secara eksplisit apabila diperlukan. Ini mengurangkan risiko dan memudahkan pengauditan.

3) Kembalikan output padat dan berstruktur

Subagen harus kembali ringkas, jawapan muktamad daripada jejak pemikiran yang telah lama berjalan. Corak biasa ialah: lakukan kerja berat dalam konteks subagen, kemudian kembalikan ringkasan ringkas dengan lampiran (tampalan, rujukan fail, JSON). Ini memaksimumkan kecekapan konteks untuk orkestra.

4) Kebolehujian dan versi

Simpan fail subagen dalam kawalan versi, buat ujian CI yang menggunakan larian sebenar terhadap input kecil dan model/set alat pin. Jika anda bergantung pada Kemahiran dan pemalam, pakai corak pasaran/versi pemalam untuk mengurus peningkatan dan pemulangan semula.

5) Cangkuk audit dan pusat pemeriksaan manusia dalam gelung

Gunakan cangkuk SDK untuk memintas seruan alat (cangkuk PreToolUse) dan memerlukan kelulusan manusia untuk tindakan yang merosakkan. Log semua panggilan alat untuk audit boleh main semula. SDK menyediakan mesin cangkuk dan kebenaran untuk menyokong corak ini.

Sampel aplikasi — saluran paip kecil seperti pengeluaran

Di bawah ialah contoh padat yang menunjukkan bahagian biasa: ejen sistem fail, seruan SDK yang menggunakan dua ejen (satu untuk semakan, satu untuk ujian) dan orkestrasi mudah.

1) Ejen sistem fail: `.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 program (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);

Nota: yang code-reviewer disimpan dalam repo untuk kegunaan semula pasukan; panggilan SDK menunjukkan ejen program diutamakan dan tools skop menghalang penulisan tidak sengaja.

Topik & corak lanjutan

Konfigurasi ejen dinamik

Buat kilang ejen berparameter yang memilih model dan set alatan bergantung pada persekitaran (dev vs. prod) atau tahap keterukan (cth, strict vs balanced mod keselamatan). Contoh SDK menunjukkan cara menjana definisi ejen pada masa jalan.

Selari

Pusingkan berbilang ejen analisis baca sahaja secara selari (gaya, keselamatan, liputan ujian) dan agregat output JSON mereka dalam urutan utama. Ini sangat mengurangkan masa jam dinding untuk repo yang besar.

Ejen yang dibekalkan pemalam

Pemalam boleh menyediakan subagen yang dibungkus dengan manifes pemalam; mereka muncul dalam /agents bersama ejen tersuai dan boleh digunakan secara eksplisit. Gunakan ini untuk mengedarkan ejen standard ke seluruh pasukan.

Tempat untuk menggunakan kod Claude cli paling disyorkan

Sangat teruja mengumumkan bahawa CometAPI kini menyokong sepenuhnya cli Claude Code yang berkuasa. Anda hanya perlu memasang Kod Claude dan mengesahkan dengan kunci API Comet dan alamat asas yang diperolehi untuk menggunakan model API Komet pada Kod Claude.

Mengapa menggunakan kod klaude melalui CometAPI?

Ciri Kecerdasan Buatan Teratas: Menjana, nyahpepijat dan mengoptimumkan kod dengan mudah menggunakan model yang dibina khusus untuk pembangun.

Pemilihan Model Fleksibel: Rangkaian model kami yang komprehensif membolehkan anda membangun dengan lebih lancar.
Penyepaduan Lancar: API sentiasa tersedia. Sepadukan Kod Claude terus ke dalam aliran kerja sedia ada anda dalam beberapa minit.
Menggunakan Kod Claude melalui CometAPI akan menjimatkan lebih banyak kos. API Claude yang disediakan oleh CometAPI adalah diskaun 20% daripada harga rasmi dan dikemas kini dengan model terkini oleh pihak rasmi.

Bersedia untuk menggunakan Claude Code cli? berunding dengan Panduan API untuk arahan terperinci.

Jika anda ingin mengetahui lebih banyak petua, panduan dan berita tentang AI, ikuti kami VK, X and Perpecahan!

Akhir fikiran

Layan Subagen sebagai boleh diguna semula, persona mikro versi. Mulakan kecil: buat a doc-reviewer dan test-runner untuk repo, semak mereka masuk .claude/agents/, dan mengautomasikannya dalam CI menggunakan tanpa kepala claude -p. Ulangi gesaan anda, tambahkan output berstruktur dan ketatkan kebenaran alat.

Model mental yang paling membantu: bayangkan Claude sebagai pengurus projek dan subagen sebagai pakar dalam pasukan. Pengurus mewakilkan tugas dengan perkataan yang jelas, mengagregat hasil penyampaian pakar dan menulis laporan akhir. Lama kelamaan anda akan melihat peningkatan dalam kebolehpercayaan, kebolehujian dan keupayaan untuk mengautomasikan sebahagian besar aliran kerja pembangun.

Apakah Subagen?

Mengapa Subagen penting

Prasyarat untuk menggunakan Subagen dalam Kod Claude

1) Kod Claude dipasang dan disahkan

2) Nod / persekitaran (untuk beberapa laluan pemasangan) dan perkakas shell asas

3) Susun atur projek & CLAUDE.md

4) Kebenaran & pelayan MCP (pilihan tetapi biasa)

Bagaimana untuk mencipta Subagen dalam Kod Claude

Aliran interaktif pantas (langkah pertama yang disyorkan)

Subagen berasaskan sistem fail (Markdown + frontmatter YAML)

Definisi CLI JSON (penggunaan ad hoc/sesi)

Takrifan program (SDK Agen — disyorkan untuk apl)

Bagaimana untuk memanggil subagen

Perwakilan automatik

Seruan eksplisit (disyorkan untuk kejelasan)

Corak orkestra SDK

Bagaimana untuk membuat subagen yang berguna, selamat, dan boleh dibuat

1) Tanggungjawab tunggal dan arahan yang jelas

2) Keistimewaan paling sedikit untuk alatan

3) Kembalikan output padat dan berstruktur

4) Kebolehujian dan versi

5) Cangkuk audit dan pusat pemeriksaan manusia dalam gelung

Sampel aplikasi — saluran paip kecil seperti pengeluaran

1) Ejen sistem fail: `.claude/agents/code-reviewer.md`

2) Orkestrasi program (Node.js)

Topik & corak lanjutan

Konfigurasi ejen dinamik

Selari

Ejen yang dibekalkan pemalam

Tempat untuk menggunakan kod Claude cli paling disyorkan

Mengapa menggunakan kod klaude melalui CometAPI?

Akhir fikiran

Baca Lagi

500+ Model dalam Satu API

Cara mencipta dan menggunakan Subagen dalam Kod Claude— panduan praktikal

Apakah Subagen?

Mengapa Subagen penting

Prasyarat untuk menggunakan Subagen dalam Kod Claude

1) Kod Claude dipasang dan disahkan

2) Nod / persekitaran (untuk beberapa laluan pemasangan) dan perkakas shell asas

3) Susun atur projek & CLAUDE.md

4) Kebenaran & pelayan MCP (pilihan tetapi biasa)

Bagaimana untuk mencipta Subagen dalam Kod Claude

Aliran interaktif pantas (langkah pertama yang disyorkan)

Subagen berasaskan sistem fail (Markdown + frontmatter YAML)

Definisi CLI JSON (penggunaan ad hoc/sesi)

Takrifan program (SDK Agen — disyorkan untuk apl)

Bagaimana untuk memanggil subagen

Perwakilan automatik

Seruan eksplisit (disyorkan untuk kejelasan)

Corak orkestra SDK

Bagaimana untuk membuat subagen yang berguna, selamat, dan boleh dibuat

1) Tanggungjawab tunggal dan arahan yang jelas

2) Keistimewaan paling sedikit untuk alatan

3) Kembalikan output padat dan berstruktur

4) Kebolehujian dan versi

5) Cangkuk audit dan pusat pemeriksaan manusia dalam gelung

Sampel aplikasi — saluran paip kecil seperti pengeluaran

1) Ejen sistem fail: .claude/agents/code-reviewer.md

2) Orkestrasi program (Node.js)

Topik & corak lanjutan

Konfigurasi ejen dinamik

Selari

Ejen yang dibekalkan pemalam

Tempat untuk menggunakan kod Claude cli paling disyorkan

Mengapa menggunakan kod klaude melalui CometAPI?

Akhir fikiran

Baca Lagi

500+ Model dalam Satu API

1) Ejen sistem fail: `.claude/agents/code-reviewer.md`