Tim agent memerlukan Claude Code v2.1.32 atau lebih baru. Periksa versi Anda dengan
claude --version.- Kapan menggunakan tim agent, termasuk use case terbaik dan bagaimana perbandingannya dengan subagents
- Memulai tim
- Mengendalikan rekan tim, termasuk mode tampilan, penugasan tugas, dan delegasi
- Best practices untuk pekerjaan paralel
Kapan menggunakan tim agent
Tim agent paling efektif untuk tugas di mana eksplorasi paralel menambah nilai nyata. Lihat contoh use case untuk skenario lengkap. Use case terkuat adalah:- Penelitian dan review: beberapa rekan tim dapat menyelidiki aspek berbeda dari masalah secara bersamaan, kemudian berbagi dan menantang temuan satu sama lain
- Modul atau fitur baru: rekan tim dapat masing-masing memiliki bagian terpisah tanpa saling mengganggu
- Debugging dengan hipotesis bersaing: rekan tim menguji teori berbeda secara paralel dan berkumpul pada jawaban lebih cepat
- Koordinasi lintas-layer: perubahan yang mencakup frontend, backend, dan test, masing-masing dimiliki oleh rekan tim berbeda
Bandingkan dengan subagents
Baik tim agent maupun subagents memungkinkan Anda memparalelkan pekerjaan, tetapi mereka beroperasi berbeda. Pilih berdasarkan apakah pekerja Anda perlu berkomunikasi satu sama lain:
| Subagents | Tim agent | |
|---|---|---|
| Context | Context window sendiri; hasil kembali ke pemanggil | Context window sendiri; sepenuhnya independen |
| Komunikasi | Melaporkan hasil kembali ke agent utama saja | Rekan tim saling mengirim pesan secara langsung |
| Koordinasi | Agent utama mengelola semua pekerjaan | Daftar tugas bersama dengan self-coordination |
| Terbaik untuk | Tugas terfokus di mana hanya hasil yang penting | Pekerjaan kompleks yang memerlukan diskusi dan kolaborasi |
| Biaya token | Lebih rendah: hasil diringkas kembali ke context utama | Lebih tinggi: setiap rekan tim adalah instance Claude terpisah |
Aktifkan tim agent
Tim agent dinonaktifkan secara default. Aktifkan dengan mengatur variabel environmentCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS ke 1, baik di environment shell Anda atau melalui settings.json:
settings.json
Mulai tim agent pertama Anda
Setelah mengaktifkan tim agent, beri tahu Claude untuk membuat tim agent dan jelaskan tugas dan struktur tim yang Anda inginkan dalam bahasa alami. Claude membuat tim, menelurkan rekan tim, dan mengoordinasikan pekerjaan berdasarkan prompt Anda. Contoh ini bekerja dengan baik karena tiga peran independen dan dapat mengeksplorasi masalah tanpa menunggu satu sama lain:Kontrol tim agent Anda
Beri tahu lead apa yang Anda inginkan dalam bahasa alami. Ini menangani koordinasi tim, penugasan tugas, dan delegasi berdasarkan instruksi Anda.Pilih mode tampilan
Tim agent mendukung dua mode tampilan:- In-process: semua rekan tim berjalan di dalam terminal utama Anda. Gunakan Shift+Down untuk bersiklus melalui rekan tim dan ketik untuk mengirim pesan kepada mereka secara langsung. Bekerja di terminal apa pun, tidak ada setup tambahan yang diperlukan.
- Split panes: setiap rekan tim mendapat pane-nya sendiri. Anda dapat melihat output semua orang sekaligus dan klik ke dalam pane untuk berinteraksi secara langsung. Memerlukan tmux, atau iTerm2.
tmux memiliki keterbatasan yang diketahui pada sistem operasi tertentu dan secara tradisional bekerja paling baik di macOS. Menggunakan tmux -CC di iTerm2 adalah entrypoint yang disarankan ke tmux."auto", yang menggunakan split panes jika Anda sudah berjalan di dalam session tmux, dan in-process sebaliknya. Pengaturan "tmux" mengaktifkan mode split-pane dan auto-detects apakah akan menggunakan tmux atau iTerm2 berdasarkan terminal Anda. Untuk mengganti, atur teammateMode di settings.json Anda:
it2 CLI. Untuk menginstal secara manual:
- tmux: instal melalui package manager sistem Anda. Lihat tmux wiki untuk instruksi spesifik platform.
- iTerm2: instal
it2CLI, kemudian aktifkan Python API di iTerm2 → Settings → General → Magic → Enable Python API.
Tentukan rekan tim dan model
Claude memutuskan jumlah rekan tim untuk dihasilkan berdasarkan tugas Anda, atau Anda dapat menentukan dengan tepat apa yang Anda inginkan:Perlukan persetujuan rencana untuk rekan tim
Untuk tugas kompleks atau berisiko, Anda dapat memerlukan rekan tim untuk merencanakan sebelum mengimplementasikan. Rekan tim bekerja dalam mode rencana read-only sampai lead menyetujui pendekatan mereka:Berbicara dengan rekan tim secara langsung
Setiap rekan tim adalah session Claude Code penuh dan independen. Anda dapat mengirim pesan ke rekan tim mana pun secara langsung untuk memberikan instruksi tambahan, mengajukan pertanyaan lanjutan, atau mengalihkan pendekatan mereka.- Mode in-process: gunakan Shift+Down untuk bersiklus melalui rekan tim, kemudian ketik untuk mengirim pesan kepada mereka. Tekan Enter untuk melihat session rekan tim, kemudian Escape untuk mengganggu giliran mereka saat ini. Tekan Ctrl+T untuk toggle daftar tugas.
- Mode split-pane: klik ke dalam pane rekan tim untuk berinteraksi dengan session mereka secara langsung. Setiap rekan tim memiliki tampilan penuh dari terminal mereka sendiri.
Tetapkan dan klaim tugas
Daftar tugas bersama mengoordinasikan pekerjaan di seluruh tim. Lead membuat tugas dan rekan tim mengerjakannya. Tugas memiliki tiga status: pending, in progress, dan completed. Tugas juga dapat bergantung pada tugas lain: tugas pending dengan dependensi yang tidak terselesaikan tidak dapat diklaim sampai dependensi tersebut selesai. Lead dapat menugaskan tugas secara eksplisit, atau rekan tim dapat self-claim:- Lead menugaskan: beri tahu lead tugas mana yang diberikan kepada rekan tim mana
- Self-claim: setelah menyelesaikan tugas, rekan tim mengambil tugas unassigned, unblocked berikutnya sendiri
Matikan rekan tim
Untuk mengakhiri session rekan tim dengan baik:Bersihkan tim
Ketika Anda selesai, minta lead untuk membersihkan:Terapkan quality gates dengan hooks
Gunakan hooks untuk menerapkan aturan ketika rekan tim menyelesaikan pekerjaan atau tugas selesai:TeammateIdle: berjalan ketika rekan tim akan idle. Keluar dengan kode 2 untuk mengirim umpan balik dan membuat rekan tim tetap bekerja.TaskCompleted: berjalan ketika tugas ditandai selesai. Keluar dengan kode 2 untuk mencegah penyelesaian dan mengirim umpan balik.
Bagaimana tim agent bekerja
Bagian ini mencakup arsitektur dan mekanik di balik tim agent. Jika Anda ingin mulai menggunakannya, lihat Kontrol tim agent Anda di atas.Bagaimana Claude memulai tim agent
Ada dua cara tim agent dimulai:- Anda meminta tim: berikan Claude tugas yang menguntungkan dari pekerjaan paralel dan secara eksplisit minta tim agent. Claude membuat satu berdasarkan instruksi Anda.
- Claude mengusulkan tim: jika Claude menentukan tugas Anda akan menguntungkan dari pekerjaan paralel, mungkin menyarankan membuat tim. Anda mengonfirmasi sebelum melanjutkan.
Arsitektur
Tim agent terdiri dari:| Komponen | Peran |
|---|---|
| Team lead | Session Claude Code utama yang membuat tim, menelurkan rekan tim, dan mengoordinasikan pekerjaan |
| Rekan tim | Instance Claude Code terpisah yang masing-masing bekerja pada tugas yang ditugaskan |
| Daftar tugas | Daftar item pekerjaan bersama yang diklaim dan diselesaikan rekan tim |
| Mailbox | Sistem pesan untuk komunikasi antar agent |
- Konfigurasi tim:
~/.claude/teams/{team-name}/config.json - Daftar tugas:
~/.claude/tasks/{team-name}/
members dengan nama setiap rekan tim, agent ID, dan tipe agent. Rekan tim dapat membaca file ini untuk menemukan anggota tim lainnya.
Izin
Rekan tim dimulai dengan pengaturan izin lead. Jika lead berjalan dengan--dangerously-skip-permissions, semua rekan tim juga demikian. Setelah dihasilkan, Anda dapat mengubah mode rekan tim individual, tetapi Anda tidak dapat mengatur mode per-rekan tim pada waktu spawn.
Context dan komunikasi
Setiap rekan tim memiliki context window-nya sendiri. Ketika dihasilkan, rekan tim memuat konteks proyek yang sama seperti session reguler: CLAUDE.md, MCP servers, dan skills. Mereka juga menerima spawn prompt dari lead. Riwayat percakapan lead tidak terbawa. Bagaimana rekan tim berbagi informasi:- Pengiriman pesan otomatis: ketika rekan tim mengirim pesan, mereka dikirimkan secara otomatis ke penerima. Lead tidak perlu polling untuk update.
- Notifikasi idle: ketika rekan tim selesai dan berhenti, mereka secara otomatis memberi tahu lead.
- Daftar tugas bersama: semua agent dapat melihat status tugas dan mengklaim pekerjaan yang tersedia.
- message: kirim pesan ke satu rekan tim spesifik
- broadcast: kirim ke semua rekan tim secara bersamaan. Gunakan dengan hemat, karena biaya skala dengan ukuran tim.
Penggunaan token
Tim agent menggunakan token secara signifikan lebih banyak daripada satu session. Setiap rekan tim memiliki context window-nya sendiri, dan penggunaan token skala dengan jumlah rekan tim aktif. Untuk penelitian, review, dan pekerjaan fitur baru, token tambahan biasanya berharga. Untuk tugas rutin, satu session lebih cost-effective. Lihat biaya token tim agent untuk panduan penggunaan.Contoh use case
Contoh-contoh ini menunjukkan bagaimana tim agent menangani tugas di mana eksplorasi paralel menambah nilai.Jalankan code review paralel
Seorang reviewer tunggal cenderung tertarik pada satu jenis masalah pada satu waktu. Membagi kriteria review menjadi domain independen berarti keamanan, kinerja, dan test coverage semuanya mendapat perhatian menyeluruh secara bersamaan. Prompt menugaskan setiap rekan tim lensa yang berbeda sehingga mereka tidak tumpang tindih:Investigasi dengan hipotesis bersaing
Ketika akar penyebab tidak jelas, satu agent cenderung menemukan satu penjelasan yang masuk akal dan berhenti mencari. Prompt melawan ini dengan membuat rekan tim secara eksplisit adversarial: pekerjaan setiap orang bukan hanya menyelidiki teori mereka sendiri tetapi menantang yang lain.Best practices
Berikan rekan tim konteks yang cukup
Rekan tim memuat konteks proyek secara otomatis, termasuk CLAUDE.md, MCP servers, dan skills, tetapi mereka tidak mewarisi riwayat percakapan lead. Lihat Context dan komunikasi untuk detail. Sertakan detail spesifik tugas dalam spawn prompt:Pilih ukuran tim yang sesuai
Tidak ada batas keras pada jumlah rekan tim, tetapi batasan praktis berlaku:- Biaya token skala linear: setiap rekan tim memiliki context window-nya sendiri dan mengkonsumsi token secara independen. Lihat biaya token tim agent untuk detail.
- Overhead koordinasi meningkat: lebih banyak rekan tim berarti lebih banyak komunikasi, koordinasi tugas, dan potensi konflik
- Diminishing returns: di luar titik tertentu, rekan tim tambahan tidak mempercepat pekerjaan secara proporsional
Ukuran tugas dengan tepat
- Terlalu kecil: overhead koordinasi melebihi manfaat
- Terlalu besar: rekan tim bekerja terlalu lama tanpa check-in, meningkatkan risiko usaha yang terbuang
- Tepat: unit self-contained yang menghasilkan deliverable yang jelas, seperti fungsi, file test, atau review
Tunggu rekan tim selesai
Kadang-kadang lead mulai mengimplementasikan tugas sendiri alih-alih menunggu rekan tim. Jika Anda memperhatikan ini:Mulai dengan penelitian dan review
Jika Anda baru mengenal tim agent, mulai dengan tugas yang memiliki batas yang jelas dan tidak memerlukan penulisan kode: review PR, penelitian library, atau investigasi bug. Tugas-tugas ini menunjukkan nilai eksplorasi paralel tanpa tantangan koordinasi yang datang dengan implementasi paralel.Hindari konflik file
Dua rekan tim mengedit file yang sama menyebabkan overwrites. Pecah pekerjaan sehingga setiap rekan tim memiliki set file berbeda.Monitor dan kemudi
Periksa kemajuan rekan tim, alihkan pendekatan yang tidak berfungsi, dan sintesis temuan saat tiba. Membiarkan tim berjalan tanpa diawasi terlalu lama meningkatkan risiko usaha yang terbuang.Troubleshooting
Rekan tim tidak muncul
Jika rekan tim tidak muncul setelah Anda meminta Claude untuk membuat tim:- Dalam mode in-process, rekan tim mungkin sudah berjalan tetapi tidak terlihat. Tekan Shift+Down untuk bersiklus melalui rekan tim aktif.
- Periksa bahwa tugas yang Anda berikan Claude cukup kompleks untuk menjamin tim. Claude memutuskan apakah akan menelurkan rekan tim berdasarkan tugas.
- Jika Anda secara eksplisit meminta split panes, pastikan tmux diinstal dan tersedia di PATH Anda:
- Untuk iTerm2, verifikasi
it2CLI diinstal dan Python API diaktifkan di preferensi iTerm2.
Terlalu banyak permission prompts
Permintaan izin rekan tim naik ke lead, yang dapat menciptakan gesekan. Pre-approve operasi umum di pengaturan izin Anda sebelum menelurkan rekan tim untuk mengurangi gangguan.Rekan tim berhenti pada error
Rekan tim dapat berhenti setelah mengalami error alih-alih pulih. Periksa output mereka menggunakan Shift+Down dalam mode in-process atau dengan mengklik pane dalam mode split, kemudian baik:- Berikan instruksi tambahan kepada mereka secara langsung
- Hasilkan rekan tim pengganti untuk melanjutkan pekerjaan
Lead shutdown sebelum pekerjaan selesai
Lead dapat memutuskan tim selesai sebelum semua tugas benar-benar selesai. Jika ini terjadi, beri tahu untuk terus. Anda juga dapat memberi tahu lead untuk menunggu rekan tim selesai sebelum melanjutkan jika mulai melakukan pekerjaan alih-alih mendelegasikan.Orphaned tmux sessions
Jika session tmux bertahan setelah tim berakhir, mungkin tidak sepenuhnya dibersihkan. Daftar session dan bunuh yang dibuat oleh tim:Keterbatasan
Tim agent bersifat eksperimental. Keterbatasan saat ini untuk diketahui:- Tidak ada session resumption dengan rekan tim in-process:
/resumedan/rewindtidak mengembalikan rekan tim in-process. Setelah melanjutkan session, lead dapat mencoba mengirim pesan ke rekan tim yang tidak lagi ada. Jika ini terjadi, beri tahu lead untuk menelurkan rekan tim baru. - Status tugas dapat tertinggal: rekan tim kadang-kadang gagal menandai tugas sebagai selesai, yang memblokir tugas dependen. Jika tugas tampak terjebak, periksa apakah pekerjaan benar-benar selesai dan perbarui status tugas secara manual atau beri tahu lead untuk mendorong rekan tim.
- Shutdown dapat lambat: rekan tim menyelesaikan permintaan atau tool call saat ini sebelum shutdown, yang dapat memakan waktu.
- Satu tim per session: lead hanya dapat mengelola satu tim pada satu waktu. Bersihkan tim saat ini sebelum memulai yang baru.
- Tidak ada tim bersarang: rekan tim tidak dapat menelurkan tim atau rekan tim mereka sendiri. Hanya lead yang dapat mengelola tim.
- Lead tetap: session yang membuat tim adalah lead seumur hidupnya. Anda tidak dapat mempromosikan rekan tim ke lead atau mentransfer kepemimpinan.
- Izin ditetapkan pada spawn: semua rekan tim dimulai dengan mode izin lead. Anda dapat mengubah mode rekan tim individual setelah spawn, tetapi Anda tidak dapat mengatur mode per-rekan tim pada waktu spawn.
- Split panes memerlukan tmux atau iTerm2: mode in-process default bekerja di terminal apa pun. Mode split-pane tidak didukung di integrated terminal VS Code, Windows Terminal, atau Ghostty.
Langkah berikutnya
Jelajahi pendekatan terkait untuk pekerjaan paralel dan delegasi:- Delegasi ringan: subagents menelurkan agent pembantu untuk penelitian atau verifikasi dalam session Anda, lebih baik untuk tugas yang tidak memerlukan koordinasi inter-agent
- Session paralel manual: Git worktrees memungkinkan Anda menjalankan beberapa session Claude Code sendiri tanpa koordinasi tim otomatis
- Bandingkan pendekatan: lihat perbandingan subagent vs tim agent untuk rincian side-by-side
