Claude Code Subagents: Bila dan Bagaimana Menjalankan Pasukan Agen

Dikemaskini kali terakhir: June 28, 2026

Subagent Claude Code ialah sesi Claude berasingan yang diaktifkan oleh ejen utama untuk satu tugas fokus, kemudian menggabungkan hasilnya kembali ke dalam kerja anda. Saya menghantar tiga daripadanya secara selari minggu lepas untuk membahagikan refactor kepada skema, API, dan ujian, dan ia selesai sebelum satu sesi panjang akan selesai merancang. Artikel ini meliputi cara menentukan dan menghantar subagent, corak orkestrasi yang saya gunakan untuk meniru pasukan kecil, dan sempadan jujur di mana subagent kos lebih daripada penjimatan mereka.

Jawapan ringkas: apakah sub-agen Claude Code?

Sub-agen ialah satu insatan Claude dengan jendela konteksnya sendiri, prompt sistemnya sendiri, dan set alat yang sempit. Sesi utama tidak kehilangan konteks apabila ia menjalankan sub-agen tersebut, kerana sub-agen berfungsi secara terasing dan hanya mengembalikan ringkasan. Anggaplah ia seperti mendelegasikan tugas kepada rakan sepasukan yang tidak pernah menyekat skrin anda.

Mekanisme rasmi ini mudah. Anda meletakkan fail markdown dalam .claude/agents/ dengan frontmatter YAML, dan Claude Code boleh memanggilnya melalui alat Task apabila suatu tugas sepadan dengan deskripsinya. Dokumentasi sub-agen adalah sumber kebenaran untuk medan-medannya, dan repo Claude Code menjejaki perubahan pada format tersebut.

Definisi sub-agen yang minimum kelihatan seperti ini:

---
name: migration-writer
description: Writes and runs database migrations for this repo. Use for schema changes.
tools: Read, Edit, Bash
model: inherit
---
You are a migration specialist. Always check existing migrations first, never drop columns without a confirmation step, and run the migration against the local DB before reporting done.

Setelah fail itu wujud, saya meminta agen utama "gunakan sub-agen migration-writer untuk menambah jadual orders" dan ia menghantar pekerja skop (scoped worker) menggantikan dengan melakukan secara inline. Baris model: inherit mengekalkan kos dan kualiti setanding dengan sesi utama; menetapkan model yang lebih murah seperti haiku pada sub-agen yang berat bacaan adalah daya ungkit sebenar apabila anda menjalankan banyak daripadanya.

Bila anda patut menggunakan subagent berbanding satu sesi?

Gunakan subagent apabila tugas itu berjalan lama, berat konteks, atau memerlukan set alat yang anda tidak mahu dalam sesi utama. Kekalkannya dalam satu sesi apabila kerja itu pendek, berkait rapat dengan apa yang sudah anda lakukan, atau memerlukan interaksi balas-membalas yang ketat dengan anda.

Saya menggunakan subagents untuk kerja yang jika tidak akan mencemarkan konteks utama saya dengan log, bacaan besar, atau percubaan dan kesilapan. Audit seluruh codebase yang melakukan grep pada 200 fail adalah calon sempurna, kerana subagent membaca semuanya dan menyerahkan ringkasan dua perenggan manakala sesi utama saya kekal bersih.

Jika anda baharu dengan agen itu sendiri, Claude Code ultimate guide merangkumi asas-asas sebelum anda menambah subagents di atasnya.

Bagaimana anda menghantar sub-agen dalam Claude Code?

Penghantaran berlaku dalam dua cara. Agen utama boleh memanggil alat Task dengan sendirinya apabila tugas itu sesuai dengan deskripsi sub-agen, atau anda boleh menamakannya secara eksplisit dalam prompt anda. Saya lebih suka menamakannya, kerana penghantaran tersirat kadangkala akan melangkaukan agen yang saya mahukan.

Beberapa corak yang saya jalankan secara berkala:

• "Use the code-reviewer subagent on the diff in this branch, then apply its suggestions."
• "Dispatch migration-writer to add a users.email_verified column, and dispatch test-writer to cover it. Run both."
• "Spin up the api-docs subagent against src/routes/ and return only the OpenAPI skeleton."

Sub-agen itu berjalan dalam konteksnya sendiri, jadi ia tidak dapat melihat perbualan anda yang sedang berlangsung melainkan anda memasukkan butiran tersebut dalam prompt. Isolasi itulah intinya. Apabila ia selesai, anda mendapat hasil, bukan aliran kebisingan antara.

Corak yang Saya Gunakan untuk Aliran Kerja Seperti Pasukan

Triknya ialah menyalin cara pasukan sebenar membahagikan kerja, kemudian memetakan setiap peranan kepada sub-agen. Berikut adalah corak yang saya sering gunakan semula.

Penyelidikan, kemudian kembangkan. Saya menghantar satu sub-agen untuk mengumpul konteks, membaca ringkasannya, kemudian menghantar beberapa sub-agen pelaksanaan terhadap antara muka yang dikongsi. Ini mencerminkan seorang ketua teknikal yang merancang skop kerja sebelum mengeluarkan tiket.

Membina di belakang kontrak. Tentukan API atau prop komponen dahulu, kemudian jalankan sub-agen backend dan sub-agen frontend secara selari terhadap kontrak itu. Kedua-duanya tidak menghalang yang lain, dan konflik jarang berlaku kerana ia menyentuh fail yang berbeza.

Semakan sebagai peranan berasingan. Saya menyimpan sub-agen penyemak kod dengan hanya alat bacaan. Selepas sebarang perubahan yang tidak remeh, saya menjalankannya terhadap diff. Mengehadkan alatnya bermaksud ia secara literal tidak boleh menyunting, yang memastikan semakan itu jujur.

Untuk aliran kerja yang boleh diulang seperti ini, pasangkan sub-agen dengan Claude Code skills: satu kemahiran menyulitkan langkah-langkah itu, dan sub-agen melakukan kerja terpencil. Dan jika sub-agen memerlukan data luaran, sambungkannya ke pelayan MCP seperti yang diterangkan oleh Claude Code MCP integration guide.

Contoh kerja: pesanan dan pembayaran

Bulan lepas saya membahagikan ciri pesanan-plus-pembayaran kepada tiga sub-agen terhadap kontrak bertipe. Kontrak itu ialah satu antara muka TypeScript tunggal untuk Order dengan status, totalCents, dan paymentId. Saya menghantar: sub-agen backend untuk melaksanakan penciptaan pesanan dan peralihan status; sub-agen pembayaran untuk menyambungkan panggilan Stripe dan menyimpan paymentId; dan sub-agen ujian untuk meliputi laluan bahagia (happy path) dan kes tepi pemulangan wang (refund edge case). Ketiga-tiga sub-agen itu menyentuh fail yang berbeza, jadi penggabungan itu adalah tiga operasi salin-tampal bersih berbanding sesi penyelesaian konflik. Keseluruhan larian mengambil masa 14 minit; kerja yang sama dalam satu sesi siri mengambil masa 41 pada minggu sebelumnya, kerana konteks tunggal terus memuat semula dokumentasi Stripe.

Bagaimana anda mengorkestrasi kerja selari tanpa kehilangan konteks?

Sesi utama adalah pengkoordinasi anda. Tugasnya adalah untuk memecahkan kerja, mengeluarkan prompt yang disempadankan (scoped), dan menyambung semula hasilnya. Pastikan pengkoordinator kekal ringkas dan biarkan sub-agen mengendalikan bacaan berat.

Larian selari yang tipikal untuk saya kelihatan seperti ini:

1. Tulis kontrak dan sempadan fail dalam sesi utama.
2. Hantar dua hingga empat sub-agen, setiap satu dengan satu segmen (slice) dan syarat kejayaan yang jelas.
3. Baca setiap ringkasan apabila ia kembali, bukan semasa larian.
4. Gabungkan dalam sesi utama, selesaikan sendiri sambungan (seams) tersebut.
5. Jalankan sub-agen ujian terakhir terhadap hasil yang digabungkan.

Paralel hanya berbaloi apabila segmen-segmen itu benar-benar bebas. Jika dua sub-agen mengubah suai schema.prisma, anda tidak membahagikan kerja; anda telah mencipta masalah penggabungan (merge problem). Lukiskan sempadan pada fail dan kontrak, kemudian laksanakan ia dalam prompt.

Kapan subagent menambah lebih banyak beban berbanding penjimatan?

Subagent menambah latensi, token, dan kos koordinasi. Penyerahan ringkasan kehilangan perincian, jadi apa-apa yang memerlukan kesinambungan mendalam adalah tidak sesuai. Jujurlah tentang pertukaran ini sebelum anda menggunakannya.

Saya pernah menjalankan ujian tolok ukur pada cawangan ciri: satu subagent bagi setiap perkhidmatan mikro berbanding sesi tunggal yang melalui mereka mengikut urutan. Untuk lima perkhidmatan yang kurang berkait rapat, secara selari menang dengan kira-kira 40 peratus masa jam dinding. Bagi tiga perkhidmatan yang berkongsi model data, sesi tunggal lebih pantas, kerana penggabungan dan penerangan semula menelan keuntungan selari itu.

Pelajarannya: paralelisme memberi ganjaran kepada kebebasan dan menghukum pengaitan (coupling). Jika hirisan anda berkongsi keadaan (state), jangan lakukan secara selari.

Apakah kesilapan biasa?

• Terlalu banyak subagents. Saya hadkan satu larian pada tiga hingga lima. Melebihi itu, kos koordinasi mengatasi keuntungan selari.
• Prompt yang kabur. "Fix the auth" gagal. "Add a JWT refresh endpoint at /auth/refresh, returning { token }, with a test" berjaya.
• Tiada kriteria kejayaan. Nyatakan apa maksud 'selesai'. "Migration applied locally and rollback tested" lebih baik daripada "handle the schema".
• Set alat yang salah. Beri pengulas hanya alat bacaan (read tools). Berikan agen deploy arahan tepat yang diperlukan, tiada apa-apa yang lebih luas.
• Mengabaikan kegagalan. Jika subagent mengembalikan ralat (error), bacalah ia. Mencuba semula secara buta membakar tokens dan menyembunyikan masalah sebenar.
• Melangkau penggabungan (merge). Subagents mengembalikan hasil; anda masih memiliki integrasi. Peruntukkan masa sebenar untuknya.

Kesilapan yang paling mahal ialah menganggap subagents sebagai keupayaan selari percuma untuk apa-apa sahaja. Mereka adalah pekerja skop di sebalik sempadan ringkasan, dan sempadan itu mempunyai kos.

Ringkasan

Subagents mengubah Claude Code menjadi sesuatu yang terasa seperti pasukan kecil: seorang koordinator cekap yang menghantar pekerja bersempadan (scoped workers) yang masing-masing membawa konteks sendiri dan melaporkan semula hasil. Tentukan mereka dalam .claude/agents/, hantar dengan alat Task, dan kekalkan sesi utama anda bersih dengan memindahkan bacaan berat dan peranan berulang ke subagents.

Gunakan mereka apabila kerja itu panjang, padat konteks (context-heavy), atau memerlukan set alat yang terhad. Tinggalkan penggunaannya untuk tugas interaktif yang pendek dan berkait rapat di mana penyerahan ringkasan kehilangan terlalu banyak. Tetapkan sempadan pada fail dan kontrak, hadkan larian kepada beberapa agen, dan sentiasa peruntukkan masa untuk menggabungkan hasil itu sendiri.

Satu peringatan sebenar: subagents menggandakan kadar throughput, bukan penilaian. Mereka akan dengan gembira membina perkara yang salah secara selari merentasi empat konteks terasing. Kerja koordinasi, definisi kontrak, dan semakan akhir masih bergantung pada anda, jadi kelebihan itu hanya muncul apabila hirisan-hirisan itu benar-benar bebas dan kriteria kejayaan adalah tepat. Jika anda mahukan latar belakang yang lebih mendalam mengenai protokol yang menggerakkan banyak pendawaian alat ini, MCP explainer adalah bacaan seterusnya yang bagus, dan Claude Code docs meliputi tetapan yang saya tidak ulangi di sini.

Kredit Imej

• Pasukan pembangun yang bekerja bersama di komputer dalam pejabat teknologi moden — photo by Rebrand Cities on Pexels
• Kod pengaturcaraan berwarna-warni pada monitor komputer — photo by inna mykytas on Pexels
• Seorang pembangun menulis kod pada komputer riba di hadapan pelbagai monitor — photo by Christina Morillo on Pexels
• Dua pengaturcara yang fokus pada pengekodan bersebelahan di pejabat moden — photo by Rebrand Cities on Pexels