Claude Code Subagents: คู่มือครบเครื่องเรื่อง AI Agent Delegation

ผู้เขียน Sathish Raju อธิบายว่า Subagent คือทางแก้ปัญหา context window เต็มใน Claude Code — แยกงานที่กิน context ออกไปทำในหน้าต่างของตัวเอง คงคุณภาพบทสนทนาหลักไว้ ไม่ใช่การเพิ่มความฉลาด แต่คือการรักษาคุณภาพ context ที่มีอยู่

“Your context window is not infinite. Subagents are how you stop treating it like it is — and start building AI workflows that actually scale.”

Subagent คืออะไร

Subagent = “instance Claude ที่มีชื่อ แยกอิสระ มี system prompt ของตัวเอง มี context window ของตัวเอง มีรายการ tool ที่ใช้ได้ของตัวเอง มี permission mode ของตัวเอง” เมื่อได้รับ task จะทำงานอิสระ ส่งคืนเฉพาะผลลัพธ์สุดท้าย ไม่รบกวน context หลัก

คุณค่าสำคัญ: Subagent ไม่ได้เพิ่มความฉลาดของ Claude แต่ รักษาคุณภาพของ context ที่มีอยู่ เพราะ session ยาว ๆ จะกิน context ด้วย tool output ซ้ำ ๆ พอเกิน 2/3 คุณภาพ response ก็ลดลง

3 built-in subagent ตัวอย่าง:

• Explore — read-only ใช้ Haiku เน้นเร็ว+ประหยัด
• Plan — รวบรวม context ก่อนวางแผน
• General-purpose — ทำได้ทั้ง explore + modify

โครงสร้าง Subagent Definition

แต่ละ subagent เป็นไฟล์ Markdown มี YAML frontmatter ระบุ config (ชื่อ, description, tool ที่ใช้ได้, model, permission) body คือ system prompt ที่นิยาม behavior

ตัวอย่าง Security Reviewer:

---
name: security-reviewer
description: Security-focused code reviewer. Use proactively after writing
             authentication, authorization, or data-handling code.
tools: Read, Grep, Glob
model: opus
effort: high
permissionMode: default
---

You are a senior application security engineer. Your role is to review code
for security vulnerabilities before it ships.

When invoked:
1. Run `git diff HEAD` to see recent changes
2. Identify highest-risk areas: auth flows, input handling, data exposure
3. Check for: SQL injection, XSS, IDOR, missing auth checks, secrets in code
4. Report findings as: CRITICAL / HIGH / MEDIUM / LOW with line references
5. Suggest minimal fixes — do not rewrite code

Return structured report. Do not modify files.

Field description ทำหน้าที่เป็น routing trigger — Claude match user request กับ description เพื่อตัดสินใจว่าจะ auto-delegate ไปที่ subagent ไหน

Subagent อยู่ที่ไหน + ลำดับความสำคัญ

1. Session-defined agents (สูงสุด)
2. Project agents (.claude/agents/)
3. User agents (~/.claude/agents/)
4. Plugin agents (ต่ำสุด)

Project-level = specialist ของทีม commit ลง repo ทุกคนใช้เหมือนกัน · User-level = tool ส่วนตัวใช้ข้ามทุก project

/agents  # สร้างแบบ interactive แนะนำ
# หรือสร้างมือ:
mkdir -p .claude/agents
touch .claude/agents/dependency-auditor.md

# ตรวจสอบว่ามองเห็น:
/agents  # แสดง agent ทั้งหมดแยก scope

3 Subagent Production-Ready

1. Dependency Auditor (read-only)

---
name: dependency-auditor
description: Review dependencies and lockfiles for upgrade opportunities,
             security vulnerabilities, and supply-chain risks.
tools: Read, Grep, Glob, Bash
disallowedTools: Edit, Write
permissionMode: plan
model: sonnet
isolation: true
---

You are a dependency security specialist. Audit this project's dependencies
and report findings. Never modify files.

Steps:
1. Find package.json / requirements.txt / go.mod / Cargo.toml
2. Read lockfiles
3. Check for: outdated major versions, known CVEs, suspicious packages,
   overly broad version ranges
4. For each finding: package name, current version, recommended version, risk

Format output as a table. Be specific.

2. Test Runner + Fixer

---
name: test-runner
description: Run test suite, isolate failures, and propose minimal fixes.
             Triggers on "run tests", "fix failing tests".
tools: Read, Bash, Grep, Edit
model: sonnet
maxTurns: 20
---

You are a test automation specialist. Your goal is a green test suite.

Workflow:
1. Run the test command
2. Read failing test output carefully
3. Trace failure to source file, not test file
4. Make minimal change to fix root cause
5. Re-run tests to confirm
6. If cannot fix in 3 attempts, report findings and stop

Never delete tests or skip assertions.
Report fix with line numbers changed.

3. Research Agent with Persistent Memory

---
name: researcher
description: Long-running research assistant for deep-dive questions about
             libraries, APIs, architecture patterns, technical concepts.
tools: Read, Bash, Glob, Grep
model: opus
effort: high
memory: user
---

You are a technical researcher who remembers what you've investigated before.

When invoked:
1. Check MEMORY.md for relevant prior investigations
2. Conduct thorough research using available tools
3. After answering, update MEMORY.md with: question asked, key findings,
   sources consulted, follow-up questions

Keep MEMORY.md concise — prioritize findings over process.

Explore → Plan → Execute Pattern

งานซับซ้อนควรใช้ pipeline 3 phase:

1. Explore: agent map ไฟล์ที่เกี่ยวข้อง (ถูก, read-only)
2. Plan: agent ออกแบบแนวทาง (analytical)
3. Execute: คนตรวจ + อนุมัติแผน ก่อนแก้ไฟล์

“The key insight is that the human review gate goes between Plan and Execute, not between Explore and Plan.”

ตัวอย่าง Claude.md delegation rules:

## Agent Delegation Rules

### Explore-Plan-Execute pipeline
For ANY task touching more than 3 files or involving refactoring:
1. Invoke explore subagent to map relevant files
2. Use output to invoke plan subagent with specific scope
3. Present plan for approval
4. Only then invoke execute with approved plan as context

### Direct execution (no subagents)
- Quick targeted fixes (1 file, <20 lines)
- Changes to files already in conversation context
- Tasks needing frequent back-and-forth feedback

### Domain routing
- Frontend (React/CSS): @frontend-agent
- Backend (API/DB): @backend-agent
- Tests: @test-runner (use proactively after code changes)

Parallel vs Sequential

Task ที่ไม่มี dependency = parallel ได้ · Task ที่ต้องรอกัน = sequential เท่านั้น. แต่ระวัง: “overhead ของ launching subagent มีจริง — แต่ละตัวเริ่ม fresh เสีย turn แรก ๆ กับการสร้างความเข้าใจ local”

Parallelize task ที่ใช้เวลาระดับนาที = ประหยัดชัด. Parallelize task ระดับวินาที = แพงกว่า sequential

Model Routing + Cost Optimization

Subagent แต่ละตัวใช้ model ต่างกันได้ — ประหยัดค่าใช้จ่ายมาก

• Main session: Opus (reasoning, architecture, synthesis)
• Implementation: Sonnet (search, code implementation)
• File discovery: Haiku (~15× ถูกกว่า Opus ต่อ token)

export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-5-20250929"

claude --model claude-opus-4-6
# ผล: Opus coordinate, Sonnet implement, Haiku explore

Subagent vs Agent Teams

• Subagent — session เดียว delegate task ให้ worker แยก
• Agent Teams — หลาย session Claude Code คุยกันโดยตรง (experimental ต้องเปิด CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)

“Use subagents when workers do not need to communicate with each other. Use Agent Teams when your teammates need to share discoveries mid-task, challenge each other’s assumptions, or coordinate on cross-cutting changes.”

งาน dev 2026 ส่วนใหญ่ subagent เพียงพอ — stable เข้าใจง่าย ตรงกับวิธีคิดแบบ task decomposition

สรุปภาพใหญ่

Subagent = การคิดใหม่เรื่องความสัมพันธ์ dev-AI

“The skill that matters in 2026 is not writing better prompts. It is knowing how to decompose work — identifying which tasks are self-contained, which outputs can be summarized cleanly, where the human review gates belong, and which specialist agent should own which domain.”

คือ systems design apply กับ AI workflow — Subagent รองรับวิธีคิดแบบนี้โดยตรง

แหล่งที่มา: “Claude Code Subagents: The Complete Guide to AI Agent Delegation” โดย Sathish Raju ตีพิมพ์ 4 เม.ย. 2026 บน Medium · อ่านต้นฉบับ