Skip to main content
Tips Claude Code · Pelajaran 5 dari 6 · 12 menit

Subagent Claude Code: Contoh Kapan Tugas Perlu Didelegasikan

Contoh subagent Claude Code dari repo nyata: apa yang dilihat subagent, field name, description, dan tools, kapan perlu delegasi, dan fan-out paralel aman.

Oleh Matthews WongDitinjau pada Dicek dengan Claude Code v2.1.296

Poin utama

Subagent Claude Code adalah pembantu yang mengerjakan tugas sampingan di context window-nya sendiri dan hanya mengembalikan ringkasan. Anda mendefinisikannya sebagai file Markdown di .claude/agents/ dengan name, description yang memberi tahu Claude kapan harus mendelegasikan, dan daftar tools opsional. Delegasikan pekerjaan yang berisik dan berdiri sendiri; diskusi bolak-balik dan file bersama tetap di sesi utama.

Setelah pelajaran ini, Anda bisa

  • Menulis file subagent dengan name, description, dan tools, serta memperkirakan apa yang dilihatnya saat mulai.
  • Menentukan kapan sebuah tugas cocok untuk subagent dan kapan sebaiknya tetap di percakapan utama.
  • Menyebar pekerjaan ke beberapa subagent paralel tanpa ada dua subagent yang menulis file yang sama.
Lihat cara kerjanya

Ikuti diagramnya langkah demi langkah

Tekan Putar, atau melangkah dengan panah. Setiap langkah juga ditulis di bawah diagram.

Bagaimana subagent menerima tugas dan mengembalikan ringkasan

Claude mencocokkan permintaan dengan description subagent, subagent bekerja di context window-nya sendiri, hanya laporannya yang kembali ke konteks Anda, beberapa subagent berjalan paralel, dan satu penulis menggabungkan file bersama.

Ditinjau pada 13 Oktober 2026 · Claude Code v2.1.296

Langkah 1 dari 7. Sesi utama adalah Anda dan Claude. Satu file Markdown di .claude/agents/ mendefinisikan subagent; setiap salinan yang dijalankan Claude bekerja di context window baru miliknya sendiri.

Tombol: ← → langkah · Home / End · K putar atau jeda

  1. Sesi utama adalah Anda dan Claude. Satu file Markdown di .claude/agents/ mendefinisikan subagent; setiap salinan yang dijalankan Claude bekerja di context window baru miliknya sendiri.

  2. Claude hanya melihat name dan description setiap subagent, bukan isi prompt-nya. Kalau permintaan Anda cocok dengan sebuah description, Claude menyerahkan pekerjaan itu ke subagent tersebut.

    name: blog-post-author description: Use this agent to research and draft ONE complete bilingual blog post …Tebak langkah berikutnya Claude menjalankan subagent. Apakah subagent itu melihat percakapan Anda? (Ya, seluruh percakapan sejauh ini · Tidak, hanya prompt-nya, CLAUDE.md, dan tugasnya)

  3. Claude menulis pesan tugas lalu menjalankan subagent. Subagent mulai dengan prompt-nya sendiri, file CLAUDE.md, dan snapshot git, tanpa membawa percakapan Anda sedikit pun.

  4. Setiap file yang dibaca, setiap pencarian, dan setiap draft masuk ke context window subagent, bukan milik Anda. Baris tools adalah allowlist: hanya tool itu yang boleh dipakai.

    tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch

  5. Begitu selesai, hanya laporan akhirnya yang kembali. Konteks Anda bertambah satu ringkasan saja, bukan sebanyak semua file yang dibuka subagent selama bekerja.

    Return a compact report, not the article text

  6. Tugas yang saling lepas bisa disebar ke beberapa subagent paralel. Masing-masing mengirim request sendiri dan memakai batas usage yang sama, jadi repo ini bekerja per batch lima.

    Tebak langkah berikutnya Tiga subagent butuh key di messages/en.json. Siapa yang menulis file itu? (Hanya sesi utama, satu per satu · Setiap subagent, begitu selesai)

  7. Setiap subagent hanya menulis ke folder staging miliknya. Hanya sesi utama yang menggabungkan folder-folder itu ke file message bersama, satu per satu, lalu memvalidasinya.

    node scripts/merge-blog-staging.mjs

Apa yang sebenarnya dilihat subagent Claude Code?

Subagent adalah pekerja terpisah di dalam sesi Anda. Ia punya context window, system prompt, dan daftar tool sendiri, dan saat selesai hanya laporan akhirnya yang kembali ke percakapan utama. Itulah gunanya: pekerjaan sampingan yang bisa membanjiri konteks Anda dengan hasil pencarian, log, atau isi file dikerjakan di tempat lain.

Baca selengkapnya (2)

Subagent mulai hampir kosong. Subagent custom menerima isi file-nya sebagai system prompt, pesan tugas yang ditulis Claude saat mendelegasikan, semua file CLAUDE.md yang dimuat sesi Anda, snapshot git status, dan skill yang di-preload oleh definisinya. Ia tidak melihat percakapan Anda, skill yang sudah Anda panggil, file yang sudah dibaca Claude, maupun auto memory. Karena itu repo ini menulis batasan pentingnya langsung di file agent: subagent tidak pernah ikut membaca obrolan tempat Anda menjelaskannya.

Pengecualiannya adalah fork. /subtask menjalankan subagent yang mewarisi seluruh percakapan, jadi Anda tidak perlu menjelaskan ulang, tetapi awal yang bersih itu hilang. Tool call milik fork tetap tidak masuk ke konteks Anda, dan hanya hasilnya yang kembali.

Bagaimana menulis file subagent dengan name, description, dan tools?

Subagent adalah satu file Markdown: YAML frontmatter, lalu system prompt. Simpan di .claude/agents/ supaya tim ikut memakainya lewat git, atau di ~/.claude/agents/ agar tersedia di semua proyek. Yang wajib hanya name dan description. Claude memutuskan kapan harus mendelegasikan dengan membaca description, jadi tulis sebagai pemicu: apa yang dikerjakan agent dan kapan dipakai. Description ikut memakan konteks, jadi buat singkat dan taruh detailnya di body, yang baru dimuat saat subagent berjalan.

Baca selengkapnya (2)

tools adalah allowlist. Kalau dikosongkan, subagent mewarisi semua tool yang tersedia untuk subagent; kalau diisi beberapa tool, hanya itu yang didapat, sedangkan disallowedTools justru menghapus tool. model menerima sonnet, opus, haiku, fable, model ID lengkap, atau inherit. Model yang dikirim Claude untuk satu pemanggilan menang lebih dulu, lalu frontmatter, lalu variabel CLAUDE_CODE_SUBAGENT_MODEL, terakhir model percakapan utama. blog-post-author di repo ini memakai inherit, jadi selalu mengikuti model sesi utama.

Sekarang subagent dibuat lewat percakapan atau edit file. Sejak v2.1.198, /agents hanya menampilkan pengingat untuk meminta Claude atau mengedit .claude/agents/ langsung, jadi tutorial yang masih menampilkan wizard pembuatan agent menjelaskan versi lama. Claude Code memantau folder agents dan membaca file baru atau yang berubah dalam hitungan detik, kecuali folder itu belum ada saat sesi dimulai.

Kapan sebuah tugas sebaiknya didelegasikan ke subagent?

Delegasikan kalau pekerjaannya berisik, berdiri sendiri, dan bisa diakhiri dengan ringkasan: menjalankan test suite, menggali log, meriset beberapa modul, atau menyusun satu dokumen utuh. Delegasikan juga kalau Anda ingin membatasi dengan tegas apa yang boleh disentuh pekerjanya. Di repo ini, menyusun satu artikel blog punya bentuk persis seperti itu: banyak membaca dan mengecek sumber, satu bundel file keluar, satu laporan singkat kembali.

Baca selengkapnya (1)

Biarkan pekerjaan di percakapan utama kalau butuh diskusi bolak-balik, kalau perencanaan, implementasi, dan testing berbagi banyak konteks, kalau perubahannya kecil dan terarah, atau kalau kecepatan respons penting, karena subagent baru harus mengumpulkan konteksnya sendiri dulu. Untuk pertanyaan tentang hal yang sudah ada di sesi, /btw menjawab dari konteks saat ini tanpa tool dan tanpa menambah riwayat. Prosedur yang ingin dipakai ulang di konteks utama itu wujudnya skill, bukan subagent.

Bagaimana menjalankan subagent Claude Code secara paralel tanpa tabrakan?

Claude bisa menjalankan beberapa subagent sekaligus, dan di sesi interaktif semuanya berjalan di background sementara Anda tetap bekerja; /tasks menampilkan daftarnya. Batas kerasnya longgar: secara default, menjalankan subagent ke-21 secara bersamaan gagal dengan pesan Concurrent subagent limit reached, dan subagent bersarang berhenti di tiga lapis. Batas yang sebenarnya adalah usage. Setiap subagent mengirim request sendiri dan memakai batas usage yang sama dengan sesi utama, dan setiap laporan yang dikembalikannya masuk ke konteks Anda.

Baca selengkapnya (2)

Tabrakan muncul dari file bersama, bukan dari banyaknya agent. Repo ini akhirnya memegang empat aturan. Beri setiap agent folder output sendiri, yang ditegakkan validator per-post dengan menolak folder berisi lebih dari satu entri. Hanya sesi utama yang boleh menulis file bersama seperti messages/en.json dan messages/id.json. Gabungkan saat notifikasi selesai datang, bukan saat file pertama kali muncul, karena agent sering masih memperbaiki hasilnya. Kalau agent berhenti di tengah jalan, lanjutkan agent itu alih-alih mengulang dari nol, karena subagent yang dilanjutkan masih menyimpan seluruh riwayatnya.

Isolasi juga ada batasnya. isolation: worktree memberi subagent salinan repositori sendiri, tetapi folder temp di luar repo tetap dipakai bersama. /rewind pun biasanya tidak mengembalikan edit yang dibuat subagent, jadi commit dulu sebelum fan-out dan jadikan git sebagai tombol undo.

Cara situs ini melakukannya

Konfigurasi nyata di balik pelajaran ini

Kutipan dari repositori yang membangun dan men-deploy situs ini, apa adanya.

.claude/agents/blog-post-author.md:1-6
---
name: blog-post-author
description: Use this agent to research and draft ONE complete bilingual blog post for this repository as a staged, validated bundle — the article component plus the EN and ID fragments, the registry entry with SEO meta, and five bilingual FAQs. Dispatch it when the user asks for a new post, a batch of posts (one agent per post, run them in parallel), or a rewrite of an existing post's content. It stages and self-validates but deliberately does NOT merge, generate covers, or commit — the main session owns those steps. Examples: "write a post about Postgres advisory locks", "draft five posts on Bluetooth printing", "rewrite the ERP approval post with real numbers".
tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
model: inherit
---

Satu-satunya subagent custom di repo ini. Description-nya ditulis sebagai daftar pemicu dan langsung menyebut batasnya: agent ini menyiapkan dan memvalidasi, sesi utama yang menggabungkan dan commit. Baris tools tidak memuat Agent, jadi ia tidak bisa menjalankan subagent lain, dan model: inherit membuatnya selalu memakai model yang sedang dipakai sesi utama.

.claude/agents/blog-post-author.md:80-87
# Boundaries

- **Do not** run `merge-blog-staging.mjs`, `merge-blog-faqs.mjs`, or any git
  command. The main session merges, generates covers, builds and commits.
- **Do not** edit `messages/en.json`, `messages/id.json`, `lib/blog-*.ts` or
  `[slug]/page.tsx` — the merge script owns those six files.
- **Do not** fetch or add images. Report what figure would help and where; the
  main session sources or draws it.

Aturan satu penulis, ditulis di prompt agent itu sendiri karena subagent tidak pernah melihat percakapan tempat aturan itu dijelaskan. Semua file yang disentuh banyak artikel sekaligus menjadi milik merge script, dan hanya sesi utama yang menjalankan script itu.

.claude/skills/publishing-blog-posts/SKILL.md:209-216
## Batching many posts

Batches of five work well. Beyond that a single validation failure costs too
much rework.

- **One folder per post**, named for the slug: `agent-epson-escpos`,
  `agent-flutter-permissions`, … The merge reads every `agent-*` folder, so five
  folders is still one merge — and each post keeps its per-post validation.

Asal angka batch lima. Lima folder tetap berarti satu kali merge, dan setiap artikel tetap divalidasi sendiri, jadi satu draft yang gagal hanya membuat satu folder dikerjakan ulang, bukan seluruh batch.

Yang sering rusak

Kesalahan yang benar-benar membuang waktu

  • Dua agent menulis satu file bersama

    messages/en.json dan messages/id.json harus punya pohon key yang identik. Penulis paralel saling menimpa key, dan kerusakannya baru terlihat belakangan sebagai error build yang sulit dilacak. Setiap agent menaruh key-nya di folder sendiri; sesi utama yang menuliskannya, satu bundel demi satu bundel.

  • Menyebar agent selebar yang diizinkan tool

    Batas concurrent-nya dua puluh, tetapi usage habis lebih dulu. Repo ini pernah menjalankan sekitar dua puluh agent riset sekaligus, dan sebagian besar terputus oleh batas usage di tengah menulis, sehingga pekerjaan setengah jadi itu harus diulang. Batch berisi empat atau lima agent selesai dengan rapi.

  • Folder temp bersama ikut tertimpa

    Bahkan dengan batch yang kecil, tiga agent pernah saling menghapus file staging di direktori temp yang sama. Salin setiap bundel ke tempat aman begitu agent-nya melapor, lalu validasi lagi tepat sebelum merge. isolation: worktree tidak akan menolong di sini, karena yang diisolasi repositorinya, bukan folder temp.

  • Mengira /rewind bisa membatalkan kerja subagent

    Checkpoint mencatat edit file dari sesi utama. Edit dari subagent yang berjalan di background tidak dikembalikan oleh /rewind, begitu juga perubahan lewat Bash. Commit dulu sebelum fan-out dan kembalikan dengan git.

  • Yang akan saya ubah di sini: description yang panjang

    Description blog-post-author panjangnya sekitar 660 karakter. Dokumentasi meminta description yang singkat, karena semuanya duduk di konteks dan Claude Code memberi peringatan kalau totalnya melewati 15.000 token. Dengan satu agent biayanya kecil; agent berikutnya di repo ini akan diberi description dua baris dan detailnya disimpan di body.

Percakapan utama, subagent, atau fork: di mana tugas sebaiknya berjalan
Mulai denganSemua yang sudah adaPrompt-nya, CLAUDE.md, snapshot git, pesan tugasSalinan seluruh percakapan
Yang masuk ke konteks AndaSetiap file dan outputSatu laporan akhirSatu hasil akhir
Paling cocok untukDiskusi bolak-balik, edit kecil yang terarahKerja berisik yang berdiri sendiri dan bisa diringkasTugas sampingan yang butuh seluruh latar belakang
/rewind mengembalikan edit-nyaYa, edit lewat tool fileTidak: pakai gitTidak: pakai git
Coba sendiri

Lakukan di komputer Anda sendiri

Anda butuh Claude Code dan satu repositori git berisi beberapa folder file Markdown. Anda akan menulis satu subagent, menjalankannya sendirian, menyebarnya paralel, dan membiarkan laporan bersama tetap dipegang sesi utama.

  1. Buat .claude/agents/link-checker.md. Description menjelaskan kapan agent ini dipakai, baris tools tidak menyertakan Edit dan Write, dan body menetapkan satu-satunya tempat ia boleh menulis.

    ---
name: link-checker
description: Checks every external link in ONE folder of Markdown files and reports broken ones. Use for link audits.
tools: Read, Grep, Glob, Bash
model: inherit
---

You check links in exactly one folder, named in the task.
Write results only to reports/links-FOLDER.json, where FOLDER is that folder's name.
Never edit the Markdown files. Return the number of links checked
and each broken link with its HTTP status, nothing else.

  2. Minta satu kali jalan dan perhatikan di panel di bawah prompt. Lalu jalankan /context: percakapan Anda hanya bertambah sebesar laporannya, bukan semua halaman yang diambilnya.

    Use the link-checker subagent to check docs/guides
/context

  3. Sebar paralel: tiga folder, tiga subagent. Buka /tasks selama mereka berjalan.

    Run three link-checker subagents in parallel, one each for docs/guides, docs/api and docs/blog
/tasks

  4. Biarkan file bersama dipegang sesi utama: minta Claude menggabungkan tiga laporan itu sendiri, lalu pastikan tidak ada subagent yang menyentuh reports/links.json.

    Merge reports/links-*.json into reports/links.json yourself. Do not delegate this step.

  5. Lanjutkan, jangan ulang: minta checker yang sudah selesai mengerjakan hal tambahan, lalu perhatikan ia melanjutkan dengan riwayatnya, bukan mulai dari nol.

    Continue that docs/guides link check and also list any redirects
Kuis singkat

Tiga pertanyaan sebelum lanjut

Pilih jawaban untuk melihat kenapa benar atau salah. Tidak ada yang disimpan atau dinilai, jadi tebak saja dengan bebas.

  1. 1.Anda menghabiskan sepuluh menit menjelaskan ke Claude bahwa draft tidak boleh menyentuh messages/en.json. Claude mendelegasikan draft itu ke subagent custom, yang lalu mengedit file tersebut. Kenapa?
  2. 2.Ada empat tugas hari ini. Mana yang sebaiknya Anda serahkan ke subagent?
  3. 3.Anda ingin subagent reviewer yang hanya bisa membaca kode, jadi baris tools tidak Anda tulis di file-nya. Tool apa saja yang bisa dipakainya?
Pikirkan dulu

Jawab dalam hati, lalu cek

  1. 1.Apa yang tidak dilihat subagent custom saat mulai?Lihat jawabannya

    Jawaban:Percakapan Anda, skill yang sudah Anda panggil, file yang sudah dibaca Claude, dan auto memory Anda. Yang ia terima adalah prompt-nya sendiri, pesan tugas dari Claude, file CLAUDE.md Anda, snapshot git status, dan skill yang di-preload.

  2. 2.Batas concurrent default-nya 20. Kenapa repo ini memakai batch berisi lima?Lihat jawabannya

    Jawaban:Setiap subagent memakai batas usage yang sama dengan sesi utama, dan setiap laporannya masuk ke konteks Anda. Gelombang yang terlalu lebar dan terkena batas di tengah menulis meninggalkan pekerjaan setengah jadi, dan di atas lima agent satu kegagalan validasi memakan terlalu banyak kerja ulang.

  3. 3.Dua subagent sama-sama perlu menambah key ke messages/en.json. Desain apa yang aman?Lihat jawabannya

    Jawaban:Tidak ada yang menulisnya. Masing-masing menaruh key-nya di folder sendiri, lalu sesi utama menggabungkannya satu per satu dan memvalidasi. Satu file bersama, satu penulis.

  4. 4.Anda mengetik /agents dan berharap muncul wizard pembuatan agent. Apa yang terjadi di versi sekarang?Lihat jawabannya

    Jawaban:Sejak v2.1.198, perintah itu hanya menampilkan pengingat untuk meminta Claude membuat atau mengelola subagent, atau mengedit .claude/agents/ maupun ~/.claude/agents/ secara langsung. Jelaskan subagent yang Anda inginkan, atau tulis file-nya sendiri.

Pelajari lebih dalam

Bahasan mendalam terkait di situs ini

Sumber

Sumber primer yang diperiksa pada tanggal riset. Ikuti tautannya untuk versi terbaru.

Pelajaran sebelumnyaHooks Claude Code: Contoh Guardrail yang Selalu BerjalanPelajaran berikutnyaCara Hemat Token Claude Code: Konteks, Compaction, dan Scope