Claude Code Agent Teams: Workflow Multi-Agent Paralel

Saya pernah punya bug yang selamat dari tiga sesi terpisah. Masing-masing menemukan penyebab yang masuk akal, menulis perbaikan yang masuk akal, dan meninggalkan gejalanya persis di tempat semula. Sesi keempat saya jalankan berbeda: saya minta lima teammate, memberi tiap orang satu hipotesis berbeda, lalu menyuruh mereka berdebat. Dua teori mati dalam empat menit karena teammate lain bisa menunjuk kode yang membantahnya.

Itulah bentuk pekerjaan yang benar-benar cocok untuk agent teams. Tulisan ini membahas cara mengaktifkannya, bedanya dengan subagent sampai ke titik yang bisa merusak orkestrasi kalau Anda menganggap keduanya sama, di mana tim itu tersimpan di disk, cara mengunci teammate dengan hook, dan batasan yang layak Anda tahu sebelum menyerahkan satu refactor ke sebuah tim.

Agent teams mati secara default, dan sakelarnya juga mengubah delegasi biasa

Agent teams masih experimental. Tanpa environment variable itu disetel, tidak ada direktori tim yang ditulis saat sesi dimulai dan Claude tidak akan memunculkan teammate bagaimanapun Anda menyusun kalimatnya. Variabel ini dibaca dari settings.json atau dari shell Anda, dan Claude Code membacanya ulang setiap kali memunculkan subagent, jadi Anda bisa mengubahnya di tengah sesi dan spawn berikutnya sudah memakai nilai yang baru.

Bagian yang mengejutkan adalah efek sampingnya. Selama teams aktif, subagent apa pun yang diberi nama oleh Claude akan diluncurkan sebagai teammate, bukan sebagai subagent. Claude memberi nama pada subagent atas inisiatifnya sendiri supaya bisa mengirim pesan ke sana nanti, sehingga sebuah tim bisa terbentuk pada delegasi yang tidak pernah Anda maksudkan sebagai kerja tim.

// ~/.claude/settings.json
// Agent teams are experimental and OFF by default. Without this
// variable no team directory is written and Claude never spawns
// a teammate, however you phrase the prompt.
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  // "in-process" (default) keeps every teammate in one terminal.
  // "auto" opens split panes when tmux or iTerm2 + it2 is present.
  "teammateMode": "in-process"
}

Team dan subagent memparalelkan hal yang berbeda

Keduanya memberi Anda lebih dari satu agent, dan di situlah kemiripannya berhenti. Subagent adalah pekerja yang dipanggil, diawasi, dan dipanen hasilnya oleh main agent. Teammate adalah sesi setara yang berbicara dengan sesama teammate dan mengambil pekerjaannya sendiri. Salah memilih membuat Anda membayar koordinasi yang tidak dibutuhkan, atau kehilangan koordinasi yang justru dibutuhkan.

Empat perbedaan yang benar-benar menentukan mana yang sebaiknya Anda pakai:

Spawning: beri nama teammate, karena namanya adalah alamatnya

Anda tidak lagi membuat tim sebagai langkah terpisah. Tool TeamCreate dan TeamDelete dihapus di v2.1.178, dan pembersihan terjadi otomatis saat sesi berakhir. Anda cukup menjelaskan peran yang diinginkan dan lead akan memunculkannya. Selalu beri nama di dalam prompt: lead memberi nama pada setiap teammate yang ia buat, dan nama itulah yang dipakai teammate lain untuk mengirim pesan. Kalau Anda membiarkan lead mengarang nama, Anda tidak bisa merujuk teammate tertentu di instruksi berikutnya.

# The lead spawns teammates from plain language. Name them —
# the name is the address other teammates send messages to.

Spawn three teammates to review PR #142:
  - security  : token handling, session management, input validation
  - perf      : N+1 queries and allocation in the hot path
  - tests     : coverage of the new branches only
Have them message each other with anything the others should
re-check, then report to me.

# Agent panel keys (in-process mode):
#   up / down   select a teammate
#   Enter       open its transcript and type to message it
#   x           stop the selected teammate
#   Ctrl+T      toggle the shared task list
#   Esc         interrupt the selected teammate's current turn

Spawning butuh sesi interaktif. Dalam mode non-interaktif dengan flag -p, termasuk sesi Agent SDK, Claude tidak memunculkan teammate dan subagent bernama tetap berjalan sebagai subagent biasa walau fiturnya aktif. Teammate juga mewarisi permission mode milik lead saat dibuat, dan Anda tidak bisa menetapkan mode per teammate pada saat spawn — hanya sesudahnya.

Di mana sebuah tim benar-benar tersimpan

Tim bukan abstraksi yang hidup di kepala model. Ia adalah sebuah direktori, dan menyadari itu mengubah sebagian besar proses debug tim menjadi sekadar membaca file. Nama tim diturunkan dari sesi: string session- diikuti delapan karakter pertama dari session id.

# Where a team actually lives on disk. The name is
# "session-" plus the first eight characters of the session id.

~/.claude/teams/session-a1b2c3d4/config.json      # members, agent ids, pane ids
~/.claude/teams/session-a1b2c3d4/inboxes/*.json   # one mailbox per agent
~/.claude/tasks/session-a1b2c3d4/                 # the shared task list

# config.json holds live runtime state — do not hand-author it.
# The teams directory is removed when the session exits; the tasks
# directory persists, so a resumed session keeps its task list.

Mailbox tiap agent adalah file JSON, dan Claude Code memvalidasi setiap entri saat membacanya. Entri yang tidak sesuai format pesan dilaporkan lalu dihapus, dan pesan yang valid tetap terkirim. Sebelum v2.1.207, satu entri rusak saja memicu error berulang setiap detik dan memblokir pengiriman untuk mailbox itu sampai Anda menghapus filenya manual. Sebuah pesan baru dilaporkan terkirim ketika penulisan ke mailbox penerima benar-benar berhasil, jadi disk penuh berarti pengirim menerima error, bukan pesan yang hilang diam-diam.

Kunci teammate dengan hook, bukan dengan harapan

Kegagalan yang paling sering saya temui adalah teammate yang memutuskan pekerjaannya selesai padahal type-check masih merah. Ada tiga hook yang menyala pada event siklus hidup tim, dan ketiganya memakai konvensi yang sama: keluar dengan exit code 2 untuk menolak transisi dan mengirim teks stderr Anda kembali ke agent sebagai umpan balik.

// .claude/settings.json — a teammate that says it is done
// but left the type-check red goes back to work. Exit code 2
// sends the stderr text back as feedback and keeps it running.
{
  "hooks": {
    "TeammateIdle": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx tsc --noEmit || { echo 'tsc is red — fix it before going idle' >&2; exit 2; }"
          }
        ]
      }
    ]
  }
}

• TeammateIdle berjalan saat teammate hendak idle — tempat yang tepat untuk gate build, lint, atau test.
• TaskCreated berjalan saat sebuah task dibuat, sehingga Anda bisa menolak task yang terlalu kabur untuk diverifikasi.
• TaskCompleted berjalan sebelum task ditandai selesai, dan di situlah pemeriksaan coverage atau diff seharusnya dipasang.

Berapa biaya sebuah tim, dan ukuran yang sepadan

Pemakaian token naik kira-kira linier terhadap jumlah teammate aktif, karena masing-masing adalah context window terpisah yang membaca file sendiri. Panduan Anthropic sendiri menyarankan mulai dari tiga sampai lima teammate untuk sebagian besar workflow, dengan lima atau enam task per teammate — tiga teammate yang fokus rutin mengalahkan lima yang berpencar, dan setelah titik tertentu tambahan teammate berhenti mempercepat apa pun sambil tetap menagih penuh.

Ada biaya kedua yang kurang kelihatan. Request dari teammate in-process berada di luar bucket prompt cache milik percakapan utama, jadi cache-nya hanya bertahan lima menit secara default, bukan satu jam, bahkan pada langganan berbayar. Pada tim yang berpikir agak lama di antara giliran, itu berarti Anda membayar pemrosesan ulang prefix berkali-kali.

Batasan yang layak diketahui sebelum menyerahkan refactor ke sebuah tim

Agent teams diberi label experimental dan label itu memang berarti. Ini batasan yang mengubah cara saya memakainya:

• Resume sesi tidak memulihkan teammate in-process. Setelah resume, lead bisa mencoba mengirim pesan ke teammate yang sudah tidak ada; suruh saja ia membuat yang baru.
• Hanya ada satu tim per sesi dan tidak ada tim bersarang. Teammate tidak bisa membuat teammate sendiri, dan lead tidak bisa diganti atau dinaikkan dari salah satu teammate.
• Status task sering tertinggal. Teammate kadang lupa menandai task selesai, dan itu memblokir semua task yang bergantung padanya — periksa task list sebelum menyimpulkan tim macet pada pekerjaannya, bukan pada pembukuannya.
• Mode split pane butuh tmux atau iTerm2 dengan CLI it2, dan tidak jalan di terminal bawaan VS Code, Windows Terminal, atau Ghostty. Mode in-process jalan di mana saja.
• Dua teammate yang mengedit file yang sama akan saling menimpa. Bagi pekerjaannya supaya tiap teammate memegang kumpulan file yang berbeda, atau pakai worktree.

Aturan yang akhirnya saya pakai sengaja dibuat sempit: pakai tim ketika nilainya datang dari perbedaan pendapat, dan pakai subagent ketika nilainya datang dari jawabannya. Review paralel, hipotesis yang saling bersaing, dan pekerjaan lintas lapisan semuanya diuntungkan oleh teammate yang bisa saling menantang. Apa pun yang berurutan, apa pun yang menyentuh file yang sama, dan apa pun yang cuma butuh ringkasan kembali akan lebih murah dan lebih andal sebagai subagent.