Sub-Agent ใน Claude Code ทำงานยังไง — คู่มือครบ

Kinjal Radadiya คู่มือครบเรื่อง sub-agent ใน Claude Code — architecture, built-in agent, การสร้าง custom, use case 4 แบบ, parallel processing, best practice, และ trade-off ที่ต้องรู้

Sub-Agent คืออะไร

Sub-agent = AI assistant ที่ specialize ใน Claude Code รันอิสระเพื่อจัดการ task เฉพาะ. แทนที่จะมี general-purpose AI ตัวเดียวทำทุกอย่าง → สร้างทีม specialist แต่ละคน expert เรื่องของตัวเอง มี tool + context เฉพาะ

Key Characteristic

Independent Context Window — Sub-agent แต่ละตัวมี context space แยก ป้องกัน cross-contamination ระหว่าง task

Custom System Prompt — sub-agent ทุกตัวมี system prompt เฉพาะ นิยาม personality, expertise, workflow

Selective Tool Access — คุมได้ว่า sub-agent ตัวไหนใช้ tool อะไรได้ เช่น code reviewer มีแค่ Read + Grep · developer agent มี Read/Write/Edit/Bash

Automatic Invocation — Claude Code delegate task ไปให้ sub-agent เหมาะสม auto ได้ หรือคุณ invoke เจาะจงด้วยชื่อก็ได้

Architecture

1. Task Recognition — main agent วิเคราะห์ request ว่าควรใช้ specialist มั้ย
2. Agent Selection — Claude Code auto-select หรือรับ request ที่ระบุชื่อ
3. Isolated Execution — sub-agent รับ task รันใน context ตัวเอง ใช้ tool ที่ assign ทำตาม system prompt เฉพาะ
4. Result Aggregation — ทำเสร็จส่งกลับเฉพาะข้อมูลที่เกี่ยวข้อง
5. No Nested Delegation — sub-agent สร้าง sub-agent ต่อไม่ได้ = single-level
6. Resumable Subagents — persistent sub-agent ที่ pause + resume บทสนทนาได้ ทุกตัวมี agentId เฉพาะ · conversation history save ที่ agent-{agentId}.jsonl · resume ด้วย agentId เดียว = restore context ครบ. เหมาะ long-running / multi-step research

Built-in Sub-Agent

Plan Sub-Agent

เมื่อ Claude รันใน plan mode (non-execution) ใช้ Plan sub-agent เพื่อ:

1. ดู project
2. รวบรวมข้อมูลที่เกี่ยวข้อง
3. สร้างแผนชัดก่อนลงมือ

User: [In plan mode] Help me refactor the authentication module
Claude: Let me research your authentication implementation first...
[Internally invokes Plan sub-agent to explore auth-related files]
[Plan sub-agent searches codebase and returns findings]
Claude: Based on my research, here's my proposed plan...

สร้าง Custom Sub-Agent

โครง Config

---
name: agent-name
description: When this agent should be invoked
tools: Read, Write, Edit, Bash, Glob, Grep
---

You are a [role description and expertise areas]...
[Agent-specific checklists, patterns, and guidelines]...

ขั้นตอนสร้าง

1. รัน /agents
2. เลือก scope — Project-level (.claude/agents/) หรือ User-level (ทุก project)
3. นิยาม name, description, tools, system prompt

Tool Access Level

Read-only agents (reviewers, auditors): Read, Grep, Glob
Research agents (analysts):             Read, Grep, Glob, WebFetch, WebSearch
Code writers (developers):              Read, Write, Edit, Bash, Glob, Grep
Documentation agents:                   Read, Write, Edit, Glob, Grep, WebFetch, WebSearch

Practical Use Case

1. Code Review Agent

---
name: code-reviewer
description: Review code for quality, security, and best practices
tools: Read, Grep, Glob
---
You are a senior code reviewer with 15+ years of experience.
Review checklist:
1. Security: SQL injection, XSS, CSRF vulnerabilities
2. Performance: N+1 queries, inefficient algorithms
3. Style: consistent naming, proper commenting
4. Testing: adequate test coverage
5. Documentation: clear, accurate documentation

2. Test Automation Agent

---
name: test-automator
description: Design and execute comprehensive test suites
tools: Read, Write, Edit, Bash, Glob, Grep
---
You are a QA automation engineer.
Workflow: analyze requirements → design test cases (happy path,
edge cases, error conditions, integration points) → write automated
tests → execute and validate → report pass/fail status.

3. Security Auditor Agent

---
name: security-auditor
description: Perform security analysis and vulnerability detection
tools: Read, Grep, Glob
---
You are a security specialist. Audit checklist: authentication/
authorization flaws, input validation, sensitive data exposure,
misconfigurations, vulnerable dependencies, insecure cryptography,
API security. Report findings with severity, location, description,
remediation, references (OWASP, CWE).

4. Database Architect Agent

---
name: database-architect
description: Design and optimize database structures
tools: Read, Write, Edit, Bash, Glob, Grep
---
You are a database architect. Design normalized schemas, create
efficient indexes, optimize queries, plan migrations, ensure data
integrity.

Parallel Processing

Launch หลาย sub-agent พร้อมกันได้:

Explore the codebase using 4 tasks in parallel.
● Task(Explore backend structure)
● Task(Explore frontend components)
● Task(Explore database migrations)
● Task(Explore test suites)

Parallelism cap ที่ 10 concurrent agent — เกินนั้น queue + batch

ประโยชน์ของ Sub-Agent

1. Context Efficiency — return เฉพาะข้อมูลเกี่ยวข้อง preserve main context
2. Task Specialization — แต่ละ sub-agent optimize สำหรับงานเฉพาะ
3. Workflow Consistency — shared sub-agent = standard ของทีม
4. Security Control — จำกัด tool access ตาม agent type
5. Scalability — เพิ่ม specialist ได้โดยไม่ล้น agent ตัวเดียว
6. Reusability — sub-agent ที่ design ดี = ใช้ข้าม project ได้

Best Practice

1. Assign Clear, Non-Overlapping Role — แยก test-automator + code-reviewer ไม่ใช่ตัวเดียวทำทั้งคู่
2. Minimize Tool Access — principle of least privilege
3. Write Detailed System Prompt — role, workflow, checklist, output format, communication protocol
4. Use Descriptive Name — python-backend-developer, security-vulnerability-scanner
5. Optimize Description for Auto-Invocation — description เจาะจง = trigger ถูก
6. Start Small + Iterate — เริ่ม 1-2 ตัว refine จาก project จริง
7. Document Agents — เก็บ wiki/README ของทีม
8. Version Control — เก็บ config ใน git

Challenge + Limitation

• Context Amnesia — sub-agent เริ่ม clean slate ยกเว้น resume
• Debugging Complexity — trace issue หลาย agent ยาก — distributed reasoning
• Setup Overhead — ลงทุนก่อน overkill สำหรับ task one-off
• Performance — launch sub-agent เพิ่ม latency
• Management Burden — agent เยอะ = maintain + coordinate ตลอด

When Sub-Agent vs Main

ใช้ Sub-Agent เมื่อ: ต้อง specialist ซ้ำ ๆ, domain-specific deep focus, ต้อง role-specific tool access, standardize ทีม, process ข้อมูลเยอะ, ต้องการ auto-delegation

ใช้ Main Agent เมื่อ: task ง่าย/one-off, ต้อง explicit control, งานต้อง context ต่อเนื่อง, ความเร็วสำคัญกว่า specialization, prototype

Quick Start: Sub-Agent ตัวแรก

/agents  → Create new agent → choose scope

name: code-formatter
description: Format code according to project style guidelines
tools: Read, Write, Edit

System prompt:
You are a code formatting specialist. Read provided files, apply
consistent formatting per the project style guide, fix indentation/
spacing/line breaks, organize imports, return neatly formatted code.
Always preserve functionality while improving readability.

Welcome to the world of multi-agent development!

แหล่งที่มา: “How Sub-Agents Work in Claude Code: A Complete Guide” โดย Kinjal Radadiya ตีพิมพ์ 6 พ.ย. 2025 บน Medium · อ่านต้นฉบับ