Claude Subagents คืออะไร สร้างและใช้งานอย่างไรใน Claude Code

เวลาที่เราใช้ Claude Code ทำงานกับโปรเจกต์ขนาดใหญ่ ปัญหาหนึ่งที่มักพบคือ Context ของบทสนทนาหลักเริ่มเต็มไปด้วยข้อมูลที่ไม่จำเป็นต้องเก็บไว้ทั้งหมด

ตัวอย่างเช่น เราอาจให้ Claude ค้นหาไฟล์ที่เกี่ยวข้องกับระบบ Authentication อ่าน Log หลายพันบรรทัด รัน Test Suite สำรวจ Dependency หรือค้นหาต้นเหตุของ Bug จากหลาย Module

แม้ผลลัพธ์สุดท้ายที่เราต้องการอาจมีเพียงไม่กี่ข้อ แต่ระหว่างทาง Claude ต้องอ่านไฟล์และรับ Output จำนวนมาก ซึ่งข้อมูลทั้งหมดอาจเข้าไปใช้พื้นที่ Context ของ Session หลัก

Claude Subagents ถูกออกแบบมาเพื่อแก้ปัญหานี้

เราสามารถมอบหมายงานย่อยให้ Claude อีกตัวหนึ่งไปทำใน Context ของตัวเอง แล้วให้มันส่งกลับมาเฉพาะผลลัพธ์หรือบทสรุปที่จำเป็น

แทนที่ Session หลักจะต้องอ่านข้อมูลทั้งหมดด้วยตัวเอง เราสามารถสั่งว่า

ใช้ Subagent สำรวจระบบ Authentication
ค้นหาไฟล์สำคัญ ลำดับการทำงาน และจุดที่อาจทำให้ Session หมดอายุ
จากนั้นส่งกลับมาเฉพาะข้อสรุปพร้อมชื่อไฟล์

Subagent จะออกไปสำรวจ Codebase ใน Context แยก แล้วส่งผลลัพธ์กลับมายัง Claude หลัก

แนวคิดนี้เปลี่ยน Claude Code จาก AI หนึ่งตัวที่ต้องทำทุกอย่างเอง ไปสู่ระบบที่ Claude หลักสามารถแบ่งงานให้ผู้ช่วยเฉพาะทางหลายตัวได้

Claude Subagent คืออะไร

Claude Subagent คือ Agent ย่อยที่ถูกสร้างขึ้นเพื่อรับผิดชอบงานเฉพาะประเภท

แต่ละ Subagent สามารถมีองค์ประกอบของตัวเอง เช่น

• System Prompt
• Model
• ระดับ Effort
• Tool ที่อนุญาต
• Tool ที่ไม่อนุญาต
• Permission Mode
• Skills
• MCP Servers
• Hooks
• Persistent Memory
• ข้อจำกัดจำนวนรอบการทำงาน
• Worktree แยกสำหรับแก้ไขไฟล์

Subagent ทำงานอยู่ใน Claude Code Session หลัก แต่ใช้ Context Window แยกจากบทสนทนาหลัก

เมื่อ Claude หลักส่งงานให้ Subagent ตัวนั้น Subagent จะทำงานอย่างอิสระ แล้วส่งผลลัพธ์กลับมาให้ Claude หลักสรุปหรือนำไปใช้ต่อ

ตัวอย่างโครงสร้างการทำงานคือ

ผู้ใช้
  ↓
Claude Code Session หลัก
  ↓
มอบหมายงานให้ Subagent
  ↓
Subagent อ่านไฟล์ ค้นหา หรือรันคำสั่งใน Context ของตัวเอง
  ↓
ส่งผลลัพธ์กลับให้ Session หลัก
  ↓
Claude หลักสรุปหรือลงมือทำขั้นตอนต่อไป

จุดสำคัญคือ Subagent ทั่วไปจะไม่ได้รับประวัติการสนทนาทั้งหมดของ Session หลัก

Claude หลักจะสร้างข้อความมอบหมายงาน โดยสรุปเฉพาะเป้าหมายและข้อมูลที่จำเป็น แล้วส่งให้ Subagent เริ่มทำงานจาก Context ใหม่

Subagent ช่วยเรื่องอะไร

ช่วยรักษา Context ของ Session หลัก

สมมติว่า Claude ต้องอ่าน Log 5,000 บรรทัดเพื่อค้นหา Error เพียงหนึ่งจุด

ถ้า Claude หลักทำเอง Output และข้อมูลระหว่างทางจะเข้าไปอยู่ใน Context หลักทั้งหมด

แต่ถ้าใช้ Subagent ข้อมูลจำนวนมากจะอยู่ใน Context ของ Subagent ส่วน Session หลักจะได้รับเพียงข้อสรุป เช่น

สาเหตุหลักเกิดจาก Token Refresh ทำงานหลัง Session ถูกยกเลิกแล้ว

ไฟล์ที่เกี่ยวข้อง:
- src/auth/refresh-token.ts
- src/middleware/session.ts

หลักฐาน:
- Error เกิดหลังคำขอ Refresh รอบที่สอง
- Database บันทึก Token ว่าถูกยกเลิกก่อน API Call 240 มิลลิวินาที

Context หลักจึงสะอาดกว่าและสามารถใช้ทำงานต่อได้นานขึ้น

ช่วยสร้างผู้เชี่ยวชาญเฉพาะด้าน

เราสามารถสร้าง Subagent ที่มีบทบาทแตกต่างกัน เช่น

code-reviewer
ตรวจ Bug คุณภาพโค้ด และ Security

debugger
วิเคราะห์ Error หา Root Cause และแก้ปัญหา

test-runner
รัน Test และสรุปเฉพาะ Test ที่ล้มเหลว

security-auditor
ตรวจ Authentication, Authorization และ Data Exposure

database-reviewer
ตรวจ Query, Schema และ Migration

frontend-reviewer
ตรวจ Component, Accessibility และ Performance

แต่ละตัวสามารถได้รับ Prompt และ Tool ที่เหมาะกับหน้าที่ของตัวเอง

ช่วยควบคุมขอบเขตเครื่องมือ

Subagent สำหรับ Review Code อาจไม่ควรแก้ไขไฟล์

เราจึงสามารถอนุญาตให้ใช้เฉพาะ

Read
Glob
Grep
Bash

โดยไม่ให้ใช้

Edit
Write

ในทางกลับกัน Subagent สำหรับแก้ Bug อาจต้องมีสิทธิ์แก้ไฟล์และรัน Test

การแยก Agent ตามหน้าที่จึงช่วยลดความเสี่ยงที่ Agent จะทำสิ่งเกินขอบเขต

ช่วยแบ่งงานให้ทำพร้อมกัน

หากงานหลายส่วนไม่ขึ้นต่อกัน สามารถให้ Subagents แยกกันสำรวจได้ เช่น

ให้ Subagent ตัวที่หนึ่งสำรวจ Authentication

ให้ Subagent ตัวที่สองสำรวจ Database

ให้ Subagent ตัวที่สามสำรวจ API

ทำงานพร้อมกัน แล้วสรุป Architecture รวมกัน

เมื่อแต่ละตัวทำงานเสร็จ Claude หลักจะรวบรวมผลลัพธ์และสร้างบทสรุปรวม

Built-in Subagents ที่ Claude Code มีอยู่แล้ว

Claude Code มี Subagents พื้นฐานที่ระบบสามารถเลือกใช้โดยอัตโนมัติ

Explore

Explore เป็น Agent แบบอ่านอย่างเดียว เหมาะกับการค้นหาและทำความเข้าใจ Codebase

ตัวอย่างงานที่เหมาะกับ Explore ได้แก่

• ค้นหาไฟล์ที่เกี่ยวข้อง
• ค้นหาการเรียกใช้ Function
• สำรวจโครงสร้าง Module
• ติดตาม Data Flow
• ตรวจสอบว่า Feature ถูก Implement ไว้ที่ใด
• ค้นหา Pattern ใน Codebase

Explore ไม่ได้รับสิทธิ์ Write หรือ Edit จึงไม่สามารถเปลี่ยนแปลงไฟล์ได้

เหมาะกับคำขอเช่น

ใช้ Explore Agent ค้นหาว่าระบบคำนวณส่วนลดอยู่ที่ไหน
และสรุปเส้นทางการทำงานตั้งแต่ API ถึง Database

Plan

Plan เป็น Agent สำหรับค้นคว้า Codebase ระหว่างที่ Claude อยู่ใน Plan Mode

เมื่อ Claude ต้องสร้างแผนงาน แต่ยังไม่ควรแก้ไฟล์ Plan Agent สามารถออกไปอ่าน Codebase และรวบรวมข้อมูลที่จำเป็นให้

เหมาะกับงาน เช่น

• เตรียมแผน Refactor
• วิเคราะห์ผลกระทบก่อนเปลี่ยน Architecture
• ค้นหาไฟล์ที่ต้องแก้
• ตรวจสอบ Dependency ก่อน Implement
• วางแผน Migration

General-purpose

General-purpose เป็น Agent ที่มีความสามารถกว้างกว่า Explore และ Plan

สามารถใช้กับงานหลายขั้นตอนที่ต้องทั้งสำรวจ วิเคราะห์ รันคำสั่ง และแก้ไขไฟล์

ตัวอย่างเช่น

ใช้ General-purpose Subagent วิเคราะห์สาเหตุที่ Test ล้มเหลว
แก้ปัญหา และรัน Test ยืนยันผล

หากต้องการพฤติกรรมที่เฉพาะเจาะจงและใช้ซ้ำได้ ควรสร้าง Custom Subagent ของตัวเองแทนการพึ่ง General-purpose ทุกครั้ง

Subagent แตกต่างจาก Claude Session ปกติอย่างไร

Claude Session ปกติคือบทสนทนาหลักที่ผู้ใช้กำลังทำงานอยู่

ผู้ใช้สามารถพูดคุย ถามคำถาม แก้ Prompt และติดตามงานอย่างต่อเนื่องได้

Subagent คือผู้ช่วยที่ Claude หลักมอบหมายงานให้ และโดยทั่วไปจะส่งกลับมาเฉพาะผลลัพธ์

Subagent เหมาะกับงานที่

• มีขอบเขตชัดเจน
• ทำงานได้ค่อนข้างอิสระ
• ไม่ต้องถามผู้ใช้ตลอดเวลา
• มีข้อมูลระหว่างทางจำนวนมาก
• สามารถส่งกลับมาเป็น Summary ได้
• ต้องใช้บทบาทหรือ Tool เฉพาะทาง

Session หลักเหมาะกับงานที่

• ต้องปรับเปลี่ยนรายละเอียดร่วมกับผู้ใช้บ่อย
• มีหลายขั้นตอนที่ใช้ Context ร่วมกันมาก
• ต้องตัดสินใจระหว่างทาง
• เป็นการแก้ไขขนาดเล็กและตรงจุด
• ต้องการความต่อเนื่องของบทสนทนา

Subagent แตกต่างจาก Skill อย่างไร

Skill คือชุดความรู้ คำสั่ง หรือ Workflow ที่ Claude โหลดมาใช้

Subagent คือ Agent อีกตัวหนึ่งที่ทำงานใน Context แยก

ตัวอย่างเช่น Skill ชื่อ api-conventions อาจบอกว่า

ทุก API ต้อง Validate Input
ใช้ Error Response รูปแบบกลาง
ต้องมี Test สำหรับ Success และ Failure

แต่ Subagent ชื่อ api-developer เป็นผู้รับผิดชอบการสร้าง API Endpoint

เราสามารถกำหนดให้ api-developer โหลด Skill api-conventions ตั้งแต่เริ่มทำงานได้

หลักการจำง่าย ๆ คือ

Skill
คือความรู้หรือวิธีทำงาน

Subagent
คือผู้ปฏิบัติงานเฉพาะทาง

Skill สามารถทำงานใน Context หลักได้ ส่วน Subagent มี Context แยกของตัวเอง

Subagent แตกต่างจาก Worktree อย่างไร

Subagent คือ Agent ที่รับงานย่อย

Worktree คือพื้นที่ไฟล์และ Git Branch แยก

ถ้า Subagent มีหน้าที่อ่าน Codebase อย่างเดียว อาจไม่จำเป็นต้องมี Worktree แยก

แต่ถ้าต้องการให้ Subagent หลายตัวแก้ไขโค้ดพร้อมกัน ควรแยก Working Directory เพื่อป้องกันการเขียนไฟล์ชนกัน

สามารถกำหนดใน Subagent ว่า

isolation: worktree

เมื่อ Agent ทำงาน ระบบจะสร้าง Git Worktree ชั่วคราวให้

การเปลี่ยนแปลงของ Subagent จึงไม่เขียนทับ Working Tree ของ Session หลักโดยตรง

อย่างไรก็ตาม Worktree ไม่ได้ป้องกัน Merge Conflict หาก Agent หลายตัวแก้ส่วนเดียวกัน เมื่อรวม Branch ก็ยังต้อง Review และแก้ Conflict ตามปกติ

Subagent แตกต่างจาก Agent Teams อย่างไร

Subagents ทำงานภายใต้ Session หลัก

แต่ละตัวรับงาน ทำงาน และรายงานผลกลับให้ Claude หลัก โดยทั่วไป Subagents ไม่ได้สื่อสารกันเองโดยตรง

Agent Teams เป็นระบบที่มี Team Lead และ Teammates หลายตัว

แต่ละ Teammate เป็น Claude Code Session ที่เป็นอิสระ มีรายการงานร่วมกัน และสามารถส่งข้อความถึงกันได้

Subagents เหมาะกับงานย่อยแบบ

ไปค้นข้อมูลนี้แล้วส่งผลกลับมา

Agent Teams เหมาะกับงานที่ผู้ทำงานหลายตัวต้อง

• แลกเปลี่ยนข้อมูลกัน
• ท้าทายข้อสรุปของกันและกัน
• ประสานงานผ่าน Task List
• แบ่งระบบหลายส่วน
• ทำงานร่วมกันระยะยาว

Agent Teams มีต้นทุน Token และค่าใช้จ่ายในการประสานงานสูงกว่า จึงไม่จำเป็นสำหรับงานย่อยทั่วไป

สร้าง Subagent ด้วยคำสั่ง /agents

วิธีที่ง่ายและแนะนำที่สุดคือใช้

/agents

คำสั่งนี้เปิดหน้าจัดการ Subagents ภายใน Claude Code

โดยทั่วไปจะมีส่วนสำหรับดู Agent ที่กำลังทำงาน และส่วน Library สำหรับดูหรือสร้าง Agent

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

เปิด Claude Code ภายในโปรเจกต์ แล้วพิมพ์

/agents

เลือกสร้าง Agent ใหม่

จากนั้นเลือกว่า Agent นี้ควรเป็นแบบใด

• Personal ใช้ได้กับทุกโปรเจกต์ของคุณ
• Project ใช้เฉพาะโปรเจกต์ปัจจุบัน
• ขอบเขตอื่นอาจขึ้นอยู่กับ Environment และนโยบายองค์กร

สามารถเลือกให้ Claude ช่วยสร้าง Agent จากคำอธิบายได้ เช่น

สร้าง Agent สำหรับ Review Code

Agent ต้องอ่าน Git Diff
ตรวจ Bug, Security, Breaking Change และ Test Coverage
ห้ามแก้ไขไฟล์
รายงานผลโดยเรียงตามระดับความรุนแรง

Claude จะสร้างชื่อ Description และ System Prompt เริ่มต้นให้

จากนั้นเลือก Tool, Model, สีแสดงผล และ Memory ตามความเหมาะสม

เมื่อบันทึกแล้ว Agent จะพร้อมใช้ทันที

ตำแหน่งเก็บไฟล์ Subagents

Project Subagent

เก็บไว้ที่

.claude/agents/

ตัวอย่าง

my-project/
└── .claude/
    └── agents/
        ├── code-reviewer.md
        ├── debugger.md
        └── test-runner.md

Project Subagents เหมาะกับ Agent ที่ผูกกับ Architecture, Tool และกติกาของโปรเจกต์

สามารถ Commit เข้า Git เพื่อให้สมาชิกในทีมใช้งาน Agent ชุดเดียวกันได้

Personal Subagent

เก็บไว้ที่

~/.claude/agents/

ตัวอย่าง

~/.claude/agents/code-improver.md

Agent ในตำแหน่งนี้พร้อมใช้กับทุกโปรเจกต์ของผู้ใช้

เหมาะกับบทบาทที่ใช้ได้ทั่วไป เช่น

• Code Reviewer
• Technical Writer
• Debugger
• Accessibility Reviewer
• Test Analyst

Subagent จาก Plugin

Plugin สามารถนำ Subagents มาให้ด้วย โดยเก็บไว้ใน Directory agents/ ของ Plugin

Agent จาก Plugin จะปรากฏในรายการ /agents เช่นเดียวกับ Custom Subagents อื่น

อย่างไรก็ตาม Agent จาก Plugin มีข้อจำกัดด้านการตั้งค่าบางรายการเพื่อความปลอดภัย เช่น การกำหนด Hooks, MCP Servers และ Permission Mode โดยตรงอาจไม่ถูกนำมาใช้

โครงสร้างไฟล์ Subagent

Subagent ถูกกำหนดด้วยไฟล์ Markdown ที่มี YAML Frontmatter อยู่ด้านบน

ตัวอย่างพื้นฐานคือ

---
name: code-reviewer
description: Reviews recent code changes for bugs, security risks, and maintainability problems
tools: Read, Glob, Grep, Bash
model: sonnet
---

You are a senior code reviewer.

When invoked:

1. Inspect the current Git diff.
2. Focus on modified files.
3. Identify functional bugs.
4. Check security and data handling.
5. Look for missing tests.
6. Report unrelated changes.

Do not modify files.

Report findings in this order:

- Critical
- Warning
- Suggestion

For every finding, include:

- File path
- Explanation
- Evidence
- Recommended fix

ส่วน YAML Frontmatter ใช้กำหนด Configuration ของ Agent

ส่วนที่อยู่หลัง Frontmatter จะกลายเป็น System Prompt ของ Agent

ฟิลด์ที่สำคัญใน Subagent

name

กำหนดชื่อของ Agent

name: code-reviewer

ควรใช้ตัวอักษรพิมพ์เล็กและเครื่องหมายขีดกลาง

ชื่อนี้ใช้สำหรับอ้างอิงและเรียก Agent

description

อธิบายว่า Agent ทำอะไรและควรถูกใช้เมื่อไร

description: Reviews recent code changes for bugs, security risks, and missing tests. Use proactively after code changes.

Description สำคัญมาก เพราะ Claude ใช้ข้อความนี้เพื่อตัดสินใจว่าจะมอบหมายงานให้ Agent ตัวใด

Description ที่กว้างเกินไป เช่น

description: Helps with code

ไม่ช่วยให้ Claude เลือก Agent ได้อย่างแม่นยำ

ควรระบุทั้งความสามารถและสถานการณ์ที่ควรใช้

tools

กำหนด Tool ที่ Agent ใช้ได้

tools: Read, Glob, Grep, Bash

หากไม่กำหนด Agent จะรับ Tool ที่มีอยู่จาก Session หลักตามค่าเริ่มต้น

สำหรับ Agent แบบ Review ควรอนุญาตเฉพาะ Tool ที่จำเป็น

สำหรับ Agent ที่ต้องแก้โค้ด อาจเพิ่ม

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

disallowedTools

ใช้ปิด Tool บางชนิด โดยยังรับ Tool อื่นจาก Session หลัก

disallowedTools: Write, Edit

รูปแบบนี้เหมาะเมื่อเราต้องการ Agent ที่ใช้ทุกอย่างได้ ยกเว้นการแก้ไฟล์

model

เลือก Model สำหรับ Agent

model: haiku

หรือ

model: sonnet

หรือ

model: opus

หรือ

model: inherit

inherit หมายถึงใช้ Model เดียวกับ Session หลัก

งานค้นหาไฟล์หรือสรุปข้อมูลที่ไม่ซับซ้อนอาจใช้ Model ที่เร็วกว่า

งานวิเคราะห์ Architecture หรือ Security ที่ซับซ้อนอาจใช้ Model ที่มีความสามารถสูงกว่า

ไม่จำเป็นต้องใช้ Model ที่ใหญ่ที่สุดกับทุก Agent

effort

กำหนดระดับความพยายามในการคิดของ Agent

effort: high

ระดับที่ใช้ได้ขึ้นอยู่กับ Model และ Claude Code เวอร์ชันปัจจุบัน

ควรกำหนดตามความซับซ้อนของงาน ไม่ควรตั้งระดับสูงสุดกับงานค้นหาไฟล์ง่าย ๆ

permissionMode

กำหนดวิธีจัดการ Permission

ตัวอย่างเช่น

permissionMode: plan

เหมาะกับ Agent ที่ต้องอ่านและวิเคราะห์โดยไม่แก้ไฟล์

permissionMode: dontAsk

หมายถึงหากการกระทำต้องถาม Permission ระบบจะปฏิเสธแทนที่จะหยุดรอคำตอบ

permissionMode: bypassPermissions

ข้าม Permission Prompt ส่วนใหญ่ จึงมีความเสี่ยงสูงและไม่ควรใช้โดยไม่จำเป็น

การจำกัด Tool ให้เหมาะสมมักปลอดภัยกว่าการเปิด Permission กว้าง ๆ

maxTurns

จำกัดจำนวน Agentic Turns

maxTurns: 20

ช่วยป้องกัน Agent ทำงานวนไปนานเกินขอบเขต

หาก Agent หยุดก่อนทำงานเสร็จ อาจต้องเพิ่มค่า หรือปรับ Prompt ให้กระชับและมีเป้าหมายชัดเจนขึ้น

background

บังคับให้ Agent ทำงานเบื้องหลัง

background: true

Session หลักสามารถทำงานอื่นต่อได้ระหว่าง Agent กำลังทำงาน

เหมาะกับงาน เช่น

• รัน Test Suite
• วิเคราะห์ Log
• ตรวจ Codebase
• สร้างรายงาน
• Research งานที่ใช้เวลาหลายขั้นตอน

isolation

แยกพื้นที่ทำงานด้วย Git Worktree

isolation: worktree

เหมาะกับ Agent ที่ต้องแก้ไขไฟล์ โดยเฉพาะเมื่อมีหลาย Agent ทำงานพร้อมกัน

color

กำหนดสีของ Agent ในรายการงานและ Transcript

color: purple

ช่วยแยก Agent หลายตัวใน Interface ได้ง่ายขึ้น

ตัวอย่าง Subagent สำหรับ Code Review

สร้างไฟล์

.claude/agents/code-reviewer.md

แล้วใส่เนื้อหา

---
name: code-reviewer
description: Reviews current code changes for bugs, security risks, maintainability issues, and missing tests. Use proactively after implementation and before commit.
tools: Read, Glob, Grep, Bash
model: sonnet
permissionMode: plan
color: purple
---

You are a senior software engineer performing a read-only code review.

Start by inspecting:

- Git status
- Git diff
- Modified files
- Relevant tests

Review for:

1. Functional correctness
2. Error handling
3. Security vulnerabilities
4. Input validation
5. Data exposure
6. Breaking changes
7. Performance problems
8. Missing or weak tests
9. Unrelated modifications
10. Project convention violations

Do not edit or create files.
Do not commit or push.

For each finding, include:

- Severity
- File path and location
- Explanation
- Evidence
- Recommended fix

If no important issue is found, state that clearly.

Agent นี้อ่านและตรวจโค้ดได้ แต่ไม่มี Edit หรือ Write จึงไม่ควรแก้ไขไฟล์

ตัวอย่าง Subagent สำหรับ Debug และแก้ Bug

สร้างไฟล์

.claude/agents/debugger.md

ใส่เนื้อหา

---
name: debugger
description: Investigates errors, failing tests, and unexpected behavior. Finds the root cause, implements a minimal fix, and verifies it.
tools: Read, Edit, Glob, Grep, Bash
model: sonnet
maxTurns: 30
color: orange
---

You are a debugging specialist.

Follow this process:

1. Capture the exact error.
2. Identify reliable reproduction steps.
3. Inspect logs and stack traces.
4. Check recent related changes.
5. Form multiple possible hypotheses.
6. Test the hypotheses using evidence.
7. Identify the root cause.
8. Implement the smallest safe fix.
9. Add or update a regression test.
10. Run the relevant tests and checks.

Avoid unrelated refactoring.

Finish with:

- Root cause
- Evidence
- Files changed
- Test results
- Remaining risks

Agent นี้ได้รับ Edit จึงสามารถแก้ไฟล์ได้ แต่ไม่มี Write หากไม่ต้องการให้สร้างไฟล์ใหม่

หากต้องเพิ่ม Test File ใหม่ ต้องเพิ่ม Write เข้าไปด้วย

ตัวอย่าง Subagent สำหรับสำรวจ Architecture

---
name: architecture-researcher
description: Researches project architecture, module boundaries, dependencies, and data flow without modifying files.
tools: Read, Glob, Grep, Bash
model: haiku
permissionMode: plan
background: true
color: blue
---

You are a software architecture researcher.

Investigate the requested topic.

Identify:

- Entry points
- Main modules
- Data flow
- Dependencies
- Shared components
- External integrations
- Important configuration
- Architectural constraints
- Potential coupling risks

Do not modify files.

Return a concise summary with exact file paths.

Agent นี้เหมาะกับการสำรวจ Codebase เบื้องหลัง โดยไม่ทำให้ Session หลักเต็มไปด้วยผลลัพธ์จากการค้นหา

วิธีเรียกใช้ Subagent

เรียกผ่านภาษาธรรมชาติ

สามารถระบุชื่อ Agent ใน Prompt ได้ เช่น

ใช้ code-reviewer Subagent ตรวจการเปลี่ยนแปลงปัจจุบัน

หรือ

ให้ debugger Subagent วิเคราะห์ Test ที่ล้มเหลวและแก้ Root Cause

Claude จะพิจารณาว่าควรมอบหมายงานตามคำขอหรือไม่

เรียกด้วย @-mention

พิมพ์ @ แล้วเลือก Agent จากรายการ เช่น

@"code-reviewer (agent)" ตรวจระบบ Authentication ที่เพิ่งแก้

การเลือก Agent ด้วย @-mention ช่วยยืนยันว่า Claude ต้องใช้ Agent ตัวนั้นกับงานนี้

ข้อความทั้งหมดของผู้ใช้ยังถูกส่งให้ Claude หลัก ซึ่งจะนำไปสร้าง Task Prompt สำหรับ Subagent

ให้ Claude เลือกอัตโนมัติ

หาก Description ของ Agent ชัดเจน Claude สามารถเลือกใช้เองเมื่อพบงานที่ตรงกัน

ตัวอย่าง Description

description: Reviews code for quality and security. Use proactively after code changes.

คำว่า Use proactively ช่วยส่งสัญญาณให้ Claude พิจารณาใช้ Agent โดยไม่ต้องรอให้ผู้ใช้ระบุชื่อทุกครั้ง

อย่างไรก็ตามไม่ควรสร้าง Agent หลายตัวที่มี Description ใกล้เคียงกันมาก เพราะ Claude อาจเลือกไม่ถูก

ใช้ Agent เป็นตัวหลักทั้ง Session

สามารถเปิด Claude Code โดยใช้ Agent ที่กำหนดเป็น Main Agent ได้

claude --agent code-reviewer

ในกรณีนี้ Agent ไม่ได้เป็นเพียงผู้ช่วยย่อย แต่ System Prompt, Model และ Tool ของ Agent จะกลายเป็น Configuration หลักของ Session

เหมาะกับ Session ที่มีจุดประสงค์เฉพาะ เช่น

claude --agent security-reviewer

หรือ

claude --agent debugger

สามารถกำหนด Agent เริ่มต้นของโปรเจกต์ใน .claude/settings.json ได้ด้วย

{
  "agent": "code-reviewer"
}

ควรใช้วิธีนี้เฉพาะโปรเจกต์หรือ Workflow ที่ต้องการบทบาทดังกล่าวเป็นค่าเริ่มต้นจริง ๆ

ให้ Subagent ทำงานเบื้องหลัง

สามารถบอก Claude ได้ตรง ๆ ว่า

ใช้ test-runner Subagent รัน Test Suite ในเบื้องหลัง
แล้วส่งกลับมาเฉพาะ Test ที่ล้มเหลวและ Error ที่สำคัญ

หรือกำหนดในไฟล์ Agent ว่า

background: true

Subagent ที่ทำงานเบื้องหลังจะไม่ Block Session หลัก เราจึงสามารถทำงานอื่นต่อได้

ถ้า Agent ต้องการ Permission ระบบสามารถแสดง Prompt กลับมาที่ Session หลัก พร้อมระบุว่า Agent ตัวใดกำลังขอสิทธิ์

สามารถใช้

/agents

เพื่อดู Subagents ที่กำลังทำงานหรือเพิ่งทำงานเสร็จ

และใช้

/tasks

เพื่อดูรายการงานเบื้องหลังของ Session ปัจจุบัน

ใช้หลาย Subagents พร้อมกัน

ตัวอย่างคำสั่งคือ

ใช้ Subagent แยกกันสามตัวเพื่อสำรวจระบบนี้พร้อมกัน

ตัวที่หนึ่งตรวจ Authentication และ Authorization
ตัวที่สองตรวจ Database และ Data Model
ตัวที่สามตรวจ API และ Error Handling

แต่ละตัวต้องทำงานแบบอ่านอย่างเดียว
จากนั้นรวบรวมผลเป็น Architecture Review เดียว

วิธีนี้เหมาะเมื่อทั้งสามเส้นทางสามารถสำรวจได้อย่างอิสระ

ไม่เหมาะเมื่อผลลัพธ์ของงานแรกจำเป็นต้องใช้ก่อนเริ่มงานที่สอง เพราะการทำพร้อมกันอาจทำให้ Agent ขาดข้อมูลหรือทำงานซ้ำ

นอกจากนี้ Subagent ทุกตัวใช้ Token ของตัวเอง ยิ่งเปิดพร้อมกันมากก็ยิ่งใช้ทรัพยากรมากขึ้น

ใช้ Subagents ต่อกันเป็นสายงาน

สามารถใช้ Agent หลายตัวตามลำดับได้ เช่น

ให้ code-reviewer ตรวจหาปัญหาด้าน Performance ก่อน

เมื่อได้ผลแล้ว ให้ optimizer แก้เฉพาะปัญหาที่ reviewer ยืนยัน

จากนั้นให้ test-runner รัน Test และตรวจ Regression

Workflow จะมีลักษณะดังนี้

Code Reviewer
  ↓
ส่ง Findings ให้ Claude หลัก
  ↓
Claude หลักส่ง Findings ที่เกี่ยวข้องให้ Optimizer
  ↓
Optimizer แก้ไข
  ↓
Test Runner ตรวจสอบผล

Claude หลักทำหน้าที่ประสานงานและส่ง Context ที่จำเป็นจาก Agent หนึ่งไปยังอีก Agent หนึ่ง

Subagent สามารถสร้าง Subagent ต่อได้

Subagent สามารถได้รับ Tool ชื่อ Agent เพื่อมอบหมายงานย่อยต่อให้ Subagent ตัวอื่น

ตัวอย่าง Agent ประสานงาน

---
name: review-coordinator
description: Coordinates specialized reviewers for comprehensive code reviews
tools: Agent, Read, Bash
model: sonnet
---

Coordinate a complete review.

Delegate:

- Security review to security-reviewer
- Test review to test-reviewer
- Performance review to performance-reviewer

Collect their findings.
Remove duplicates.
Resolve conflicting conclusions using evidence.
Return one prioritized review.

การสร้าง Agent ซ้อนกันเหมาะกับงานขนาดใหญ่ที่ Agent หลักย่อยต้องแบ่งงานต่อ

แต่ไม่ควรสร้างโครงสร้างซับซ้อนโดยไม่จำเป็น เพราะทำให้ติดตามงานยาก ใช้ Token มาก และเพิ่มต้นทุนการประสานงาน

Claude Code จำกัดความลึกของ Subagent ที่ซ้อนกันไว้ ไม่สามารถสร้างต่อไปได้ไม่สิ้นสุด

โหลด Skills ให้ Subagent

สามารถกำหนด Skills ที่ควรโหลดตั้งแต่ Agent เริ่มทำงาน

skills:
  - api-conventions
  - error-handling-patterns

ตัวอย่าง

---
name: api-developer
description: Implements API endpoints using the project's API conventions
tools: Read, Edit, Write, Glob, Grep, Bash
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints following all preloaded conventions.

Before editing:

1. Inspect related endpoints.
2. Identify reusable services.
3. Confirm validation and error patterns.

After editing:

1. Add tests.
2. Run typecheck.
3. Run related tests.
4. Review the final diff.

เนื้อหาเต็มของ Skills ที่ระบุจะถูกโหลดเข้า Context ของ Agent ตั้งแต่เริ่มต้น

เหมาะกับการแยก

Agent
รับผิดชอบว่าใครเป็นผู้ทำงาน

Skill
รับผิดชอบว่าผู้ทำงานต้องใช้กฎหรือ Workflow ใด

เชื่อม MCP เฉพาะ Subagent

สามารถกำหนด MCP Server ที่มีไว้สำหรับ Agent ตัวนั้นได้

ตัวอย่างเช่น Browser Tester ที่ใช้ Playwright MCP

---
name: browser-tester
description: Tests web features in a real browser and reports UI problems
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
---

Test the requested feature in the browser.

Check:

- Main user flow
- Loading states
- Error states
- Responsive layout
- Console errors
- Broken interactions

Return reproduction steps and screenshots when useful.

ข้อดีของการกำหนด MCP เฉพาะ Subagent คือ Tool Description ของ MCP นั้นไม่จำเป็นต้องเข้าไปใช้ Context ของ Session หลัก

Agent จะเชื่อมต่อ MCP เมื่อเริ่มทำงานและหยุดการเชื่อมต่อเมื่อทำงานเสร็จ

ก่อนใช้ MCP Package ภายนอกควรตรวจสอบแหล่งที่มา Version และสิทธิ์ที่ MCP สามารถเข้าถึงได้

สร้าง Memory ให้ Subagent

Subagent สามารถมี Persistent Memory เพื่อสะสมความรู้ระหว่าง Session ได้

ตัวอย่าง

memory: project

Memory มีขอบเขตหลัก เช่น

user
ใช้ความรู้ร่วมกันในหลายโปรเจกต์

project
เก็บความรู้เฉพาะโปรเจกต์และสามารถแชร์ผ่าน Git ได้

local
เก็บความรู้เฉพาะโปรเจกต์ แต่ไม่ต้องการ Commit

ตัวอย่าง Code Reviewer ที่มี Memory

---
name: code-reviewer
description: Reviews code and remembers project-specific patterns and recurring problems
tools: Read, Glob, Grep, Bash
memory: project
---

Review the requested changes.

Before starting:

1. Consult your memory for project conventions and recurring issues.
2. Inspect the current diff.
3. Compare the changes against previously learned patterns.

After completing the review:

1. Update memory with stable architectural facts.
2. Record recurring mistakes.
3. Do not store temporary task details or unverified assumptions.

Memory ช่วยให้ Agent เรียนรู้ว่าโปรเจกต์ใช้ Pattern ใด มีปัญหาประจำที่ใด และส่วนใดต้องระวัง

แต่ไม่ควรให้ Agent บันทึกทุกอย่างลง Memory เพราะข้อมูลเก่า ผิด หรือเป็นเพียงข้อสันนิษฐานอาจส่งผลต่อการทำงานในอนาคต

ควรบันทึกเฉพาะข้อมูลที่ตรวจสอบได้และมีประโยชน์ระยะยาว

Resume Subagent เดิม

โดยปกติการเรียก Subagent แต่ละครั้งจะสร้าง Instance ใหม่และเริ่ม Context ใหม่

แต่ Subagent ที่ทำงานเสร็จแล้วสามารถถูก Resume เพื่อทำงานต่อจากประวัติเดิมได้

ตัวอย่าง

ใช้ code-reviewer ตรวจ Authentication Module

เมื่อ Agent ส่งผลลัพธ์กลับมาแล้ว สามารถสั่งต่อว่า

ให้ code-reviewer ตัวเดิมตรวจ Authorization Logic ต่อ
โดยใช้ข้อค้นพบจากรอบก่อน

Subagent ที่ถูก Resume จะยังมีประวัติ Tool Calls, Results และ Context ก่อนหน้า

Built-in Explore และ Plan เป็น Agent แบบใช้งานครั้งเดียว จึงไม่เหมาะกับงานที่ต้อง Resume ต่อเนื่อง

หากต้องทำงานหลายรอบ ควรใช้ General-purpose หรือ Custom Subagent

Fork แตกต่างจาก Named Subagent อย่างไร

Named Subagent เช่น code-reviewer เริ่มจาก Context ใหม่ โดยมี System Prompt, Model และ Tool ตามไฟล์ Agent

Fork เป็น Subagent ที่รับสำเนาประวัติการสนทนาทั้งหมดจาก Session หลัก ณ เวลาที่ Fork

เหมาะกับกรณีที่งานย่อยต้องรู้เรื่องราวที่คุยกันมาทั้งหมด และการสรุปใหม่อาจทำให้รายละเอียดหาย

ตัวอย่าง

/fork เขียน Unit Test จาก Implementation และข้อตกลงทั้งหมดที่คุยกันมา

Fork จะเห็น Context เดียวกับ Session หลักตอนที่ถูกสร้าง แต่ Tool Calls ภายใน Fork จะไม่เข้ามาทำให้บทสนทนาหลักรก จะกลับมาเพียงผลลัพธ์สุดท้าย

Named Subagent เหมาะกับบทบาทที่ใช้ซ้ำและต้องการ Tool หรือ Model เฉพาะ

Fork เหมาะกับงานข้างเคียงที่ต้องพึ่ง Context ปัจจุบันจำนวนมาก

ข้อควรระวังเรื่อง CLAUDE.md

Custom Subagents ส่วนใหญ่สามารถรับกติกาจาก CLAUDE.md และ Memory Hierarchy ของโปรเจกต์ได้

แต่ Built-in Explore และ Plan ถูกออกแบบให้ทำงานเร็วและประหยัด จึงไม่โหลด CLAUDE.md และ Git Status แบบเดียวกับ Agent อื่น

หากมีกฎสำคัญที่ Explore ต้องรู้ เช่น

ห้ามสำรวจ vendor/
ระบบเก่าใน legacy/ ถูกเลิกใช้แล้ว
ให้ใช้เฉพาะ apps/api-v2/

ควรระบุในข้อความมอบหมายงานโดยตรง ไม่ควรหวังว่า Explore จะอ่านกฎทั้งหมดจาก CLAUDE.md

ข้อควรระวังเรื่อง Permission

Subagent ได้รับ Permission Context จาก Session หลัก และอาจมี Permission Mode เพิ่มเติมจาก Configuration ของตัวเอง

การกำหนด

permissionMode: bypassPermissions

อาจทำให้ Agent รันคำสั่งหรือแก้ไฟล์โดยไม่ถามในหลายกรณี

ไม่ควรเปิดใช้เพียงเพราะไม่ต้องการกดอนุมัติบ่อย

แนวทางที่ปลอดภัยกว่าคือ

• จำกัด Tool ให้เหลือเฉพาะที่จำเป็น
• ใช้ Read-only Agent สำหรับการ Review
• ใช้ plan สำหรับงานวิเคราะห์
• ใช้ Hooks ตรวจคำสั่งที่เสี่ยง
• ใช้ Worktree สำหรับ Agent ที่แก้ไฟล์
• ใช้ Git Commit และ Diff เป็นจุดตรวจสอบ
• ให้ CI ตรวจงานอีกครั้งก่อน Merge

ข้อควรระวังเรื่องการแก้ไฟล์ชนกัน

Subagents ที่ทำงานใน Working Directory เดียวกันสามารถแก้ไฟล์ชนกันได้

หากต้องให้ Agent หลายตัว Implement พร้อมกัน ควรกำหนด

isolation: worktree

หรือแบ่งความรับผิดชอบให้ชัด เช่น

Agent A แก้เฉพาะ apps/web/

Agent B แก้เฉพาะ apps/api/

Agent C เพิ่ม Test ใน tests/integration/

หลีกเลี่ยงการให้หลาย Agent แก้ไฟล์ส่วนกลางเดียวกัน เช่น

package.json
shared routes
database schema
global configuration

ถ้าจำเป็นต้องแก้ไฟล์ร่วมกัน ควรทำตามลำดับแทนการทำพร้อมกัน

ข้อควรระวังเรื่อง Token

Subagent ทุกตัวมี Context และการใช้ Model ของตัวเอง

การเปิด Agent หลายตัวพร้อมกันไม่ได้ทำให้งานเร็วขึ้นโดยไม่มีต้นทุน

ตัวอย่างเช่น หากเปิด Agent ห้าตัวให้ทุกตัวอ่าน Codebase เดียวกัน Agent ทั้งห้าอาจทำงานซ้ำและใช้ Token มากโดยไม่ได้เพิ่มคุณค่ามากนัก

ควรใช้ Subagents เมื่อ

• งานแยกจากกันจริง
• Output ระหว่างทางมีจำนวนมาก
• ต้องการผู้เชี่ยวชาญเฉพาะด้าน
• ต้องการ Tool Restrictions
• ต้องการทำงานพร้อมกัน
• ผลลัพธ์สามารถส่งกลับเป็น Summary ได้

ไม่ควรใช้กับการแก้ข้อความหนึ่งบรรทัดหรือคำถามสั้น ๆ ที่ Claude หลักตอบได้ทันที

แนวทางออกแบบ Subagent ให้ทำงานได้ดี

ให้ Agent มีหน้าที่เดียวที่ชัดเจน

Agent ที่ดีควรเก่งเรื่องใดเรื่องหนึ่ง เช่น

code-reviewer
debugger
test-runner
security-reviewer
api-developer

หลีกเลี่ยง Agent ชื่อ

super-agent
do-everything
general-helper

เพราะขอบเขตที่กว้างทำให้ Description ไม่ช่วยในการเลือกใช้ และ Prompt มักเต็มไปด้วยกฎที่ขัดกัน

เขียน Description ให้บอกทั้งหน้าที่และเวลาที่ควรใช้

ตัวอย่างที่ดีคือ

description: Reviews recent code changes for correctness, security, and missing tests. Use after implementation and before commit.

Description ควรตอบให้ได้ว่า

Agent นี้ทำอะไร

Claude ควรใช้ Agent นี้เมื่อไร

ให้สิทธิ์เท่าที่จำเป็น

Reviewer ไม่ควรมี Edit ถ้าไม่ต้องแก้ไฟล์

Researcher ไม่จำเป็นต้องมี Write

Database Reader ควรมี Hook ป้องกัน Query ที่เขียนข้อมูล

หลัก Least Privilege ช่วยลดทั้งความเสี่ยงและโอกาสที่ Agent จะออกนอกขอบเขต

กำหนดรูปแบบผลลัพธ์

อย่าบอกเพียงว่า

ตรวจ Code ให้หน่อย

ควรกำหนด Output เช่น

รายงานผลตามระดับ Critical, Warning และ Suggestion

ทุก Finding ต้องมีชื่อไฟล์ หลักฐาน ผลกระทบ และวิธีแก้

หากไม่พบปัญหาสำคัญให้ระบุอย่างชัดเจน

เมื่อ Output มีโครงสร้าง Claude หลักจะนำผลไปใช้ต่อได้ง่ายขึ้น

ให้ Agent คืนเฉพาะข้อมูลที่จำเป็น

จุดประสงค์ของ Subagent คือแยก Context

ถ้า Agent ส่งผลการค้นหาหลายพันบรรทัดกลับมาทั้งหมด ข้อดีด้าน Context จะลดลง

ควรเขียนว่า

Return a concise summary.
Include only relevant evidence and exact file paths.
Do not return complete logs or entire files.

ชุด Subagents เริ่มต้นที่เหมาะกับทีมพัฒนา

ทีมไม่จำเป็นต้องสร้าง Agent จำนวนมากตั้งแต่วันแรก

สามารถเริ่มจากสี่บทบาท

Architecture Researcher

สำรวจระบบและส่งกลับมาเฉพาะโครงสร้างสำคัญ

Debugger

หา Root Cause แก้ปัญหา และยืนยันด้วย Test

Code Reviewer

ตรวจงานแบบ Read-only ก่อน Commit หรือ Pull Request

Test Runner

รัน Test ขนาดใหญ่ใน Context แยก และสรุปเฉพาะ Failure

เมื่อ Workflow เริ่มชัดจึงค่อยเพิ่ม Security Reviewer, Database Reviewer, API Developer หรือบทบาทอื่นตามปัญหาที่เกิดขึ้นจริง

ตัวอย่าง Workflow ใช้ Subagents อย่างเป็นระบบ

สมมติว่าต้องเพิ่มระบบ Two-Factor Authentication

เริ่มจากสั่ง Session หลักว่า

ใช้ architecture-researcher สำรวจ Authentication ปัจจุบัน
ค้นหา Login Flow, Session Storage และ User Model
ส่งกลับมาเฉพาะไฟล์สำคัญและข้อจำกัด

เมื่อได้ข้อมูลแล้วให้ Claude หลักสร้างแผน

จากนั้นมอบหมาย Implementation

ใช้ api-developer เพิ่ม Backend สำหรับ Two-Factor Authentication
ทำงานใน Worktree แยก

มอบหมาย Frontend ให้ Agent อีกตัว

ใช้ frontend-developer สร้างหน้ากรอกรหัสและ Error States
ทำงานใน Worktree แยก

เมื่อรวมงานแล้วใช้

ให้ test-runner รัน Test ที่เกี่ยวข้อง
และส่งกลับมาเฉพาะ Failure พร้อมสาเหตุ

สุดท้ายใช้

ให้ code-reviewer ตรวจ Diff ทั้งหมดแบบอ่านอย่างเดียว
เน้น Security, Account Lockout และ Recovery Flow

ใน Workflow นี้ Session หลักทำหน้าที่วางเป้าหมาย ตัดสินใจ และรวมผลลัพธ์

Subagents ทำหน้าที่สำรวจ Implement ทดสอบ และ Review ตามความเชี่ยวชาญ

บทสรุป

Claude Subagents คือผู้ช่วยเฉพาะทางที่ทำงานภายใน Claude Code Session โดยใช้ Context ของตัวเอง

ประโยชน์สำคัญไม่ได้มีเพียงการทำหลายงานพร้อมกัน แต่รวมถึงการรักษา Context หลัก การแยกบทบาท การจำกัด Tool การเลือก Model ให้เหมาะกับงาน และการสร้าง Workflow ที่ใช้ซ้ำได้

เริ่มต้นได้ง่ายที่สุดด้วยคำสั่ง

/agents

จากนั้นสร้าง Agent ที่มีหน้าที่ชัดเจน กำหนด Description ให้ Claude รู้ว่าเมื่อไรควรใช้ จำกัด Tool เท่าที่จำเป็น และกำหนดรูปแบบผลลัพธ์ที่ต้องการ

Project Subagents ควรเก็บไว้ใน

.claude/agents/

ส่วน Agent ส่วนตัวที่ต้องการใช้ทุกโปรเจกต์ควรเก็บไว้ใน

~/.claude/agents/

สามารถเรียกด้วยภาษาธรรมชาติ ใช้ @-mention หรือเปิดทั้ง Session ด้วย

claude --agent <agent-name>

Subagent ไม่ควรถูกใช้กับทุกงาน แต่ควรใช้เมื่อภารกิจมีขอบเขตชัด มีข้อมูลระหว่างทางจำนวนมาก ต้องการความเชี่ยวชาญเฉพาะ หรือสามารถแยกไปทำอย่างอิสระแล้วส่งกลับมาเป็นบทสรุปได้

เมื่อออกแบบอย่างเหมาะสม Claude Code จะไม่ได้เป็นเพียง Agent หนึ่งตัวที่ทำงานตามคำสั่ง แต่จะกลายเป็นระบบที่มี Claude หลักทำหน้าที่ประสานงาน และมีผู้ช่วยเฉพาะทางคอยสำรวจ พัฒนา ทดสอบ และตรวจสอบงานอย่างเป็นระบบ