Buat subagent khusus

• Mempertahankan konteks dengan menjaga eksplorasi dan implementasi di luar percakapan utama Anda
• Menerapkan batasan dengan membatasi alat mana yang dapat digunakan subagent
• Menggunakan kembali konfigurasi di seluruh proyek dengan subagent tingkat pengguna
• Mengkhususkan perilaku dengan prompt sistem yang terfokus untuk domain tertentu
• Mengontrol biaya dengan merutekan tugas ke model yang lebih cepat dan lebih murah seperti Haiku

​

Subagent bawaan

• Untuk memblokir tipe bawaan tertentu, tambahkan ke permissions.deny seperti yang ditunjukkan dalam Nonaktifkan subagent tertentu.
• Untuk mencegah Claude mendelegasikan ke subagent apa pun, tolak alat Agent itu sendiri dengan permissions.deny.
• Dalam mode non-interaktif dan Agent SDK, atur CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 untuk menghapus semua tipe bawaan dan menyediakan hanya milik Anda sendiri.

​

Quickstart: buat subagent pertama Anda

/agents

A code improvement agent that scans files and suggests improvements
for readability, performance, and best practices. It should explain
each issue, show the current code, and provide an improved version.

Use the code-improver agent to suggest improvements in this project

​

Konfigurasi subagent

​

Gunakan perintah /agents

• Melihat semua subagent yang tersedia (bawaan, pengguna, proyek, dan plugin)
• Membuat subagent baru dengan setup terpandu atau generasi Claude
• Mengedit konfigurasi subagent yang ada dan akses alat
• Menghapus subagent khusus
• Melihat subagent mana yang aktif ketika duplikat ada

​

Pilih cakupan subagent

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

claude --agents @'
{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}
'@

​

Tulis file subagent

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

​

Bidang frontmatter yang didukung

​

Pilih model

• Alias model: Gunakan salah satu alias yang tersedia: sonnet, opus, haiku, atau fable
• ID model lengkap: Gunakan ID model lengkap seperti claude-opus-4-8 atau claude-sonnet-5. Menerima nilai yang sama dengan flag --model
• inherit: Gunakan model yang sama dengan percakapan utama
• Dihilangkan: Jika tidak ditentukan, default ke inherit (menggunakan model yang sama dengan percakapan utama)

1. Variabel lingkungan CLAUDE_CODE_SUBAGENT_MODEL, jika diatur ke alias model atau ID model
2. Parameter model per-invokasi
3. Frontmatter model definisi subagent
4. Model percakapan utama

​

Kontrol kemampuan subagent

​

Alat yang tersedia

• AskUserQuestion
• EnterPlanMode
• ExitPlanMode, kecuali permissionMode subagent adalah plan
• ScheduleWakeup
• WaitForMcpServers

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

​

Batasi subagent mana yang dapat dihasilkan

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

tools: Agent, Read, Bash

​

Cakupan MCP servers ke subagent

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

• --strict-mcp-config dan --bare
• Konfigurasi MCP terkelola Enterprise
• allowedMcpServers dan deniedMcpServers policies

​

Mode izin

​

Preload skills ke dalam subagent

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

​

Aktifkan memori persisten

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

• Prompt sistem subagent mencakup instruksi untuk membaca dan menulis ke direktori memori.
• Prompt sistem subagent juga mencakup 200 baris pertama atau 25KB dari MEMORY.md dalam direktori memori, mana pun yang lebih kecil, dengan instruksi untuk mengkurasi MEMORY.md jika melebihi batas itu.
• Alat Read, Write, dan Edit secara otomatis diaktifkan sehingga subagent dapat mengelola file memorinya.

• project adalah cakupan default yang direkomendasikan. Ini membuat pengetahuan subagent dapat dibagikan melalui kontrol versi. Gunakan user ketika pengetahuan subagent berlaku secara luas di seluruh proyek, atau local ketika pengetahuan tidak boleh diperiksa ke dalam kontrol versi.
• Minta subagent untuk berkonsultasi dengan memorinya sebelum memulai pekerjaan: “Review PR ini, dan periksa memori Anda untuk pola yang telah Anda lihat sebelumnya.”
• Minta subagent untuk memperbarui memorinya setelah menyelesaikan tugas: “Sekarang setelah Anda selesai, simpan apa yang Anda pelajari ke memori Anda.” Seiring waktu, ini membangun basis pengetahuan yang membuat subagent lebih efektif.
• Sertakan instruksi memori langsung dalam file markdown subagent sehingga secara proaktif mempertahankan basis pengetahuannya sendiri:
  Update your agent memory as you discover codepaths, patterns, library
  locations, and key architectural decisions. This builds up institutional
  knowledge across conversations. Write concise notes about what you found
  and where.
  

​

Aturan bersyarat dengan hooks

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

​

Nonaktifkan subagent tertentu

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

claude --disallowedTools "Agent(Explore)"

​

Tentukan hooks untuk subagent

• Dalam frontmatter subagent: Tentukan hooks yang hanya berjalan saat subagent tertentu itu aktif
• Dalam settings.json: Tentukan hooks yang berjalan dalam sesi utama ketika subagent dimulai atau berhenti

​

Hooks dalam frontmatter subagent

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

​

Hooks tingkat proyek untuk peristiwa subagent

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

​

Bekerja dengan subagent

​

Pahami delegasi otomatis

​

Panggil subagent secara eksplisit

• Bahasa alami: sebutkan subagent dalam prompt Anda; Claude memutuskan apakah akan mendelegasikan
• @-mention: menjamin subagent berjalan untuk satu tugas
• Sesi-lebar: seluruh sesi menggunakan prompt sistem subagent, pembatasan alat, dan model melalui flag --agent atau pengaturan agent

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

@"code-reviewer (agent)" look at the auth changes

claude --agent code-reviewer

claude --agent security-reviewer

claude --agent my-plugin:security-reviewer

{
  "agent": "code-reviewer"
}

​

Jalankan subagent di foreground atau background

• Subagent foreground memblokir percakapan utama sampai selesai. Prompt izin dilewatkan kepada Anda saat muncul.
• Subagent background berjalan secara bersamaan sementara Anda terus bekerja. Mulai dari v2.1.186, ketika subagent background mencapai panggilan alat yang memerlukan izin, prompt muncul di sesi utama Anda dan menyebutkan subagent yang bertanya. Setujui untuk membiarkan subagent melanjutkan, atau tekan Esc untuk menolak panggilan alat itu saja tanpa menghentikan subagent. Sebelum v2.1.186, subagent background auto-deny setiap panggilan alat yang sebaliknya akan meminta.

• Minta Claude untuk “run this in the background”
• Tekan Ctrl+B untuk menempatkan tugas yang sedang berjalan di background

​

Pola umum

​

Isolasi operasi volume tinggi

Use a subagent to run the test suite and report only the failing tests with their error messages

​

Jalankan penelitian paralel

Research the authentication, database, and API modules in parallel using separate subagents

​

Rantai subagent

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

​

Pilih antara subagent dan percakapan utama

• Tugas memerlukan bolak-balik yang sering atau penyempurnaan iteratif
• Beberapa fase berbagi konteks yang signifikan, seperti perencanaan, implementasi, dan pengujian
• Anda membuat perubahan cepat dan tertarget
• Latensi penting. Subagent dimulai segar dan mungkin memerlukan waktu untuk mengumpulkan konteks

• Tugas menghasilkan output verbose yang Anda tidak butuhkan dalam konteks utama Anda
• Anda ingin menerapkan pembatasan alat atau izin tertentu
• Pekerjaan mandiri dan dapat mengembalikan ringkasan

​

Hasilkan subagent bersarang

​

Kelola konteks subagent

​

Apa yang dimuat saat startup

• Prompt sistem: prompt agen itu sendiri ditambah detail lingkungan yang Claude Code tambahkan, bukan prompt sistem Claude Code lengkap. Subagent khusus mendefinisikan milik mereka dalam badan markdown atau bidang prompt. Agen bawaan memiliki prompt yang telah ditentukan sebelumnya.
• Pesan tugas: prompt delegasi yang Claude tulis ketika menyerahkan pekerjaan.
• CLAUDE.md dan memori: setiap level dari hierarki memori yang dimuat percakapan utama, termasuk ~/.claude/CLAUDE.md, aturan proyek, CLAUDE.local.md, dan file kebijakan yang dikelola. Agen Explore dan Plan bawaan melewati ini.
• Status Git: snapshot yang diambil di awal sesi induk. Tidak ada ketika direktori kerja bukan repositori Git atau ketika includeGitInstructions adalah false. Explore dan Plan melewatinya terlepas.
• Skills yang dimuat sebelumnya: konten lengkap dari skill apa pun yang dinamai dalam bidang skills agen. Agen bawaan tidak memuat skills sebelumnya.

​

Lanjutkan subagent

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

• Pemadatan percakapan utama: Ketika percakapan utama dipadatkan, transkrip subagent tidak terpengaruh. Mereka disimpan dalam file terpisah.
• Persistensi sesi: Transkrip subagent bertahan dalam sesi mereka. Anda dapat melanjutkan subagent setelah memulai ulang Claude Code dengan melanjutkan sesi yang sama.
• Pembersihan otomatis: Transkrip dibersihkan berdasarkan pengaturan cleanupPeriodDays, yang default ke 30 hari.

​

Auto-compaction

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

​

Fork percakapan saat ini

• Claude dapat menelurkan fork dengan meminta tipe subagent fork secara eksplisit. Spawn tanpa tipe subagent masih menggunakan subagent general-purpose, dan subagent bernama seperti Explore masih menelurkan seperti sebelumnya.
• Setiap spawn subagent berjalan di background, apakah itu fork atau subagent bernama. Atur CLAUDE_CODE_DISABLE_BACKGROUND_TASKS ke 1 untuk menjaga spawn tetap sinkron.

/fork draft unit tests for the parser changes so far

​

Amati dan arahkan fork yang sedang berjalan

​

Bagaimana fork berbeda dari subagent bernama

​

Keterbatasan

​

Contoh subagent

​

Peninjau kode

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

​

Debugger

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

​

Data scientist

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

​

Validator kueri database

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

chmod +x ./scripts/validate-readonly-query.sh

​

Langkah berikutnya

• Distribusikan subagent dengan plugins untuk berbagi subagent di seluruh tim atau proyek
• Jalankan Claude Code secara terprogram dengan Agent SDK untuk CI/CD dan otomasi
• Gunakan MCP servers untuk memberikan subagent akses ke alat dan data eksternal