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

สั่ง Claude Code ให้หาว่าโค้ดส่วนไหนยังเรียก API ตัวเก่า มันเปิดอ่านไปสามสิบไฟล์ พอกลับมาทำงานหลัก context ก็เหลือไม่ถึงครึ่ง sub-agent มีไว้แก้ปัญหานี้

Sub-agent ใน Claude Code คืออะไร

Sub-agent คือ agent อีกตัวที่ Claude Code แตกออกไปทำงานเฉพาะเรื่องแทน agent หลัก แต่ละตัวทำงานใน context window ของตัวเอง มี system prompt สิทธิ์ และชุดเครื่องมือของตัวเอง ทำเสร็จแล้วส่งกลับมาแค่บทสรุป ไม่ใช่ทุกไฟล์ที่อ่านมา

เทียบกับทีมงานจริง agent หลักคือหัวหน้าที่กำลังคุยงานกับคุณ เจองานค้นข้อมูลยาวๆ ก็ส่งให้ลูกทีมไปทำ ลูกทีมไล่อ่านเอกสารมาทั้งกอง แล้วกลับมารายงานสั้นๆ ว่าเจออะไร หัวหน้าไม่ต้องแบกเอกสารทั้งกองไว้บนโต๊ะ

ตามเอกสารของ Claude Code สิ่งที่ sub-agent เห็นตอนเริ่มงานมีสามอย่าง

• system prompt ของ sub-agent ตัวนั้น พร้อมรายละเอียดสภาพแวดล้อม เช่น โฟลเดอร์ที่ทำงาน (ไม่ใช่ system prompt ของ Claude Code)
• ข้อความมอบหมายงานที่ agent หลักเขียนสรุปให้
• ไฟล์ CLAUDE.md ทุกระดับที่ agent หลักโหลด ยกเว้น Explore กับ Plan ที่ข้ามส่วนนี้

สิ่งที่ sub-agent ไม่เห็นคือประวัติการคุยของคุณ ไฟล์ที่ agent หลักอ่านไปแล้ว และ skill ที่เคยเรียกใช้ เพราะมันเริ่มจาก context ว่างที่แยกขาดจากกัน ข้อนี้เป็นทั้งจุดแข็งและข้อจำกัดของ sub-agent

ทำไมต้องใช้ sub-agent

Sub-agent ช่วยสามเรื่องหลัก คือรักษา context ของงานหลักให้สะอาด แบ่งงานไปทำพร้อมกันได้ และให้งานบางประเภทมีคำสั่งเฉพาะกับสิทธิ์ที่แคบกว่า agent หลัก

1. context หลักไม่บวม งานที่ผลลัพธ์ยาว เช่น รันชุดเทสต์ อ่าน log หรือค้นทั้งโปรเจกต์ ผลดิบจะอยู่ใน context ของ sub-agent กลับมาแค่บทสรุป agent หลักจึงทำงานต่อได้นานขึ้นก่อนต้อง compact (context window คืออะไร)
2. ทำงานขนานกันได้ สั่งได้เช่น "ใช้ sub-agent แยกกันสำรวจโมดูล auth, database และ API พร้อมกัน" แต่ละตัวทำส่วนของตัวเองแล้วส่งผลกลับมารวม
3. คำสั่งเฉพาะทางและสิทธิ์จำกัด sub-agent สำหรับรีวิวโค้ดอาจมีแค่เครื่องมืออ่านไฟล์ แก้อะไรไม่ได้เลย ส่วนตัวที่เขียนเทสต์ได้สิทธิ์รันคำสั่งเพิ่ม
4. เลือกโมเดลแยกได้ งานค้นหาง่ายๆ ตั้งให้ใช้โมเดลที่เล็กกว่า เช่น Haiku เพื่อประหยัดโควตา

Sub-agent ที่มีในตัว Claude Code มีอะไรบ้าง

Claude Code มี sub-agent ในตัวที่ Claude เรียกใช้เองเมื่อเหมาะ ตัวหลักคือ Explore สำหรับค้นและอ่านโค้ด Plan สำหรับหาข้อมูลระหว่าง plan mode และ general-purpose สำหรับงานหลายขั้นที่ต้องทั้งสำรวจและลงมือแก้

ตอนเรียก Explore Claude จะเลือกระดับความละเอียดด้วย คือ quick สำหรับหาจุดเดียว medium สำหรับสำรวจทั่วไป และ very thorough สำหรับวิเคราะห์ทั้งระบบ นอกจากนี้ยังมีตัวช่วยเล็กๆ อย่าง statusline-setup ที่ทำงานตอนสั่ง /statusline และ claude-code-guide ที่ตอบคำถามเรื่องฟีเจอร์ของ Claude Code

ข้อควรรู้คือ Explore กับ Plan ไม่โหลด CLAUDE.md และเป็นงานครั้งเดียว เรียกกลับมาทำต่อไม่ได้ ถ้ากฎของโปรเจกต์สำคัญกับงานค้นหานั้น ให้ระบุไว้ในคำสั่งเลย

สร้าง sub-agent เองอย่างไร

Sub-agent ที่สร้างเองคือไฟล์ Markdown หนึ่งไฟล์ ส่วนหัวเป็น YAML front matter บอกชื่อ คำอธิบาย เครื่องมือ และโมเดล เนื้อหาด้านล่างคือ system prompt วางไว้ที่ .claude/agents/ สำหรับโปรเจกต์ หรือ ~/.claude/agents/ สำหรับทุกโปรเจกต์ของคุณ

ณ พฤศจิกายน 2569 เอกสารแนะนำสองทาง คือบอก Claude ให้เขียนไฟล์ให้ เช่น "สร้าง sub-agent ชื่อ test-writer ไว้ใน .claude/agents/ สำหรับเขียนเทสต์หลังแก้โค้ด" หรือเขียนไฟล์เอง ส่วนคำสั่ง /agents ในเวอร์ชันปัจจุบันแค่แสดงข้อความเตือนให้ทำสองวิธีนี้ (ใน Claude Code v2.1.197 และเก่ากว่า /agents ยังเปิดหน้าจอสร้างและแก้ agent ให้)

ตัวอย่างไฟล์ .claude/agents/test-writer.md ที่ใช้ได้ทันที

---
name: test-writer
description: Writes and runs unit tests for code that was just changed. Use proactively after a feature or bug fix is done.
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
---

คุณคือผู้เขียนเทสต์ของโปรเจกต์นี้

1. อ่านไฟล์ที่เพิ่งแก้ แล้วหาโฟลเดอร์เทสต์และรูปแบบเทสต์ที่โปรเจกต์ใช้อยู่
2. เขียนเทสต์ให้ครอบคลุมกรณีปกติ กรณีขอบ และบั๊กที่เพิ่งแก้
3. รันเฉพาะเทสต์ที่เกี่ยวข้อง แล้วแก้เทสต์จนผ่าน
4. ห้ามแก้โค้ดที่ไม่ใช่เทสต์ ถ้าเทสต์พังเพราะบั๊กจริง ให้หยุดแล้วรายงาน

ตอบกลับสั้นๆ ว่าเพิ่มไฟล์อะไร รันคำสั่งอะไร และผลเป็นอย่างไร

ปกติไม่ต้องรีสตาร์ต Claude Code จะเห็นไฟล์ใหม่หรือไฟล์ที่แก้ภายในไม่กี่วินาที ยกเว้นตอนเพิ่งสร้างโฟลเดอร์ agents ครั้งแรก ต้องเปิด session ใหม่ ถ้าชื่อซ้ำกัน ลำดับความสำคัญคือ managed settings ขององค์กร, flag --agents, โฟลเดอร์ของโปรเจกต์, โฟลเดอร์ของผู้ใช้ แล้วจึงเป็น plugin

ยังมีฟิลด์อื่นอีก เช่น background, isolation: worktree สำหรับให้ทำงานใน git worktree ชั่วคราว, memory, effort และ color ดูรายการเต็มได้ในหน้า Subagents ของเอกสาร Claude Code ส่วนเรื่อง MCP server ที่ใส่ใน mcpServers อ่านพื้นฐานได้ที่ MCP คืออะไร

Codex CLI มีแบบเดียวกันไหม

Codex CLI ก็มี subagent ณ พฤศจิกายน 2569 เอกสารของ Codex ระบุ agent ในตัวไว้สามตัว คือ default, worker และ explorer ส่วน agent ที่สร้างเองเป็นไฟล์ TOML ใน ~/.codex/agents/ หรือ .codex/agents/ ต้องมี name, description และ developer_instructions ข้อต่างคือ Codex จะแตก subagent เมื่อคุณสั่งตรงๆ หรือเมื่อคำสั่งในโปรเจกต์บอกให้ทำ และดูตัวที่กำลังทำงานได้ด้วย /subagents (การตั้งค่าอื่นของ Codex ดูได้ใน คู่มือ Codex CLI)

# .codex/agents/reviewer.toml
name = "reviewer"
description = "Reviews changes for bugs, security issues and missing tests."
developer_instructions = """
Review the diff like an owner. Do not edit files.
"""

Claude เลือกใช้ sub-agent ตอนไหน

Claude ตัดสินใจส่งงานให้ sub-agent จากคำขอของคุณ ฟิลด์ description ของแต่ละตัว และบริบทของงานตอนนั้น ถ้าอยากให้ใช้ตัวไหนแน่ๆ ให้เรียกชื่อตรงๆ หรือ @-mention

• ปล่อยให้ Claude เลือกเอง เอกสารแนะนำให้ใส่วลีอย่าง "use proactively" ใน description ถ้าอยากให้หยิบไปใช้บ่อยขึ้น
• สั่งเป็นภาษาธรรมดา เช่น "ใช้ sub-agent test-writer เขียนเทสต์ให้ฟังก์ชันที่เพิ่งแก้"
• @-mention พิมพ์ @"test-writer (agent)" ตามด้วยงาน เพื่อบังคับให้ใช้ตัวนั้น
• ใช้ทั้ง session เปิดด้วย claude --agent test-writer ให้ทั้ง session ทำงานตามคำสั่งของ agent ตัวนั้น

sub-agent ทำงานได้สองแบบ แบบ foreground คือ agent หลักรอจนเสร็จ แบบ background คือทำไปพร้อมกับที่คุณทำงานอื่น และ sub-agent ยังแตก sub-agent ของตัวเองต่อได้ลึกสุดสามชั้นใต้บทสนทนาหลักเป็นค่าเริ่มต้น ถ้าไม่ต้องการ ให้ตั้ง CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1

description ที่ดีบอกทั้งงานและจังหวะ เช่น "Reviews code for security issues. Use after changes to auth or payment code." ดีกว่า "Code reviewer" เฉยๆ ถ้ามีหลายตัวที่ description คล้ายกัน Claude อาจเลือกผิดตัว

Sub-agent ใช้ token เท่าไร และเมื่อไรไม่ควรใช้

Sub-agent ทุกตัวส่งคำขอไปที่โมเดลเองและใช้ token ของตัวเอง แยกจากบทสนทนาหลัก ถ้าใช้แพ็ก Pro หรือ Max คำขอของ sub-agent ก็นับรวมใน 5-hour limit และ weekly limit ด้วย การรันหลายตัวพร้อมกันจึงทำให้โควตาหมดเร็วขึ้น (Claude Code ติด limit)

sub-agent ช่วยให้ context หลักเล็กลง แต่ token รวมของงานไม่ได้ลดลงเสมอ เพราะ sub-agent เริ่มจาก context ว่าง ต้องอ่านไฟล์ที่เกี่ยวข้องใหม่เอง (token คืออะไร) วิธีคุมค่าใช้จ่ายที่เอกสารแนะนำ

• ตั้ง model: haiku ให้ sub-agent ที่ทำงานง่าย
• เปิด /usage บนแพ็ก Pro, Max, Team หรือ Enterprise เพื่อดูว่า sub-agent กินสัดส่วนการใช้งานไปเท่าไร
• ค่าเริ่มต้นรัน sub-agent พร้อมกันได้ 20 ตัว ลดลงได้ด้วย CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS

งานที่ควรทำในบทสนทนาหลักแทน ตามคำแนะนำของเอกสาร คืองานที่ต้องโต้ตอบกันบ่อย งานหลายช่วงที่ต้องใช้ context ร่วมกัน เช่น วางแผน ลงมือ และทดสอบเรื่องเดียวกัน การแก้เล็กๆ ที่รู้อยู่แล้วว่าแก้ตรงไหน และงานที่อยากได้คำตอบเร็ว เพราะ sub-agent ต้องเริ่มเก็บข้อมูลจากศูนย์ กฎจำง่ายคือ ถ้างานสรุปผลเป็นข้อความสั้นๆ ได้และคุณไม่ต้องเห็นขั้นตอนระหว่างทาง ส่งให้ sub-agent ถ้างานต้องรู้ทุกอย่างที่คุยกันมา ทำในบทสนทนาหลัก

ใช้ sub-agent กับ buzzAI

buzzAI ไม่คิดค่า token และไม่มีโควตารายวันหรือรายสัปดาห์ token ที่ sub-agent ใช้เพิ่มจึงไม่ทำให้ค่าใช้จ่ายเพิ่ม สิ่งที่จำกัดแทนคือจำนวน agent ที่รันพร้อมกัน แพ็ก Personal รันได้ทีละ 1 agent ถ้าเครื่องมือของคุณแตก sub-agent ก็ยังใช้ได้ แต่ sub-agent จะผลัดกันทำงานทีละตัว ส่วนแพ็กบริษัท (Studio, Starter, Team, Business) รันได้ 1–8 agent พร้อมกันตามแพ็ก เหมาะกับงานที่สั่ง sub-agent หลายตัวทำขนานกัน

แต่ละ sub-agent ทำงานภายในขนาด context ของแพ็ก (Personal 64K ถึง 256K แพ็กบริษัท 256K) ในเวลาทำการ จันทร์–ศุกร์ 08:00–20:00 น. แพ็กบริษัทได้คิวก่อน แพ็ก Personal จึงอาจต้องรอคิว ใช้กับ Claude Code ผ่าน ANTHROPIC_BASE_URL โดยใช้โมเดล open-weight Qwen3.8-27B ตอนนี้ API ยังไม่เปิดใช้ทั่วไป รอบที่ 1 เป็น waitlist และเราจะส่ง API key ทางอีเมลเมื่อมีผู้สมัครครบโควต้าที่กำหนด ดูแพ็กได้ที่หน้าราคา