เป้าหมาย
เข้าใจว่า "agent ที่โผล่ขึ้นมาทำงานพร้อมกัน" ตอนสั่งงาน Claude Code คืออะไร ตั้งค่า subagent ของตัวเองได้ (tool, โมเดล, สิทธิ์, background) สั่งให้แตกงานกี่ตัวและแบ่งงานอย่างไรให้ได้ผล และตัดสินใจได้ว่างานไหนคุ้ม งานไหนเสียเงินเปล่า (บทนี้ต่อยอดจากหัวข้อ subagent ในบท 6d-04)
หลักการ
Subagent คืออะไร
เมื่อ Claude เรียก tool ชื่อ Agent จะเกิด subagent ซึ่งคือ Claude อีกตัวที่:
- เริ่มด้วย context ใหม่ว่างเปล่า ไม่เห็นประวัติแชตของเรา เห็นแค่ข้อความมอบหมายงานที่ Claude ตัวหลักเขียนให้ + system prompt ของมัน + CLAUDE.md + git status
- ทำงานหลายเทิร์นด้วย tool ของตัวเอง แล้ว ส่งกลับแค่สรุปสุดท้าย ผลลัพธ์ยาวๆ (log เทสต์, ไฟล์ที่อ่าน 30 ไฟล์) จึงไม่ไปรก context หลัก
- รันพร้อมกันได้หลายตัว และ subagent ซ้อน subagent ได้ลึก 3 ชั้น
ผลที่ตามมา: ข้อความมอบหมายงานคือทุกอย่างที่มันรู้ ถ้า Claude ตัวหลักเขียนสั่งไม่ครบ subagent ก็ทำผิดทิศ
Subagent ที่ติดมากับ Claude Code
| ชื่อ | ทำอะไร | แก้ไฟล์ได้ไหม |
|---|---|---|
Explore |
ค้นและวิเคราะห์โค้ด มีระดับ quick / medium / very thorough | ❌ (Write/Edit ถูกปิด) |
Plan |
ค้นข้อมูลระหว่าง plan mode | ❌ |
general-purpose |
งานหลายขั้นที่ต้องค้นและลงมือ | ✅ |
claude |
ตัวกลางสำหรับงานทั่วไป | ✅ |
statusline-setup, claude-code-guide |
งานเฉพาะ (ตั้ง status line, ตอบคำถามเรื่อง Claude Code) | จำกัด |
ที่เห็น "Explore ×3" ขึ้นมาพร้อมกันตอนถามคำถามกว้างๆ คือ Claude ตัดสินใจเองว่าจะแตกงานค้นหา
Claude เรียก subagent เมื่อไร
| วิธี | ตัวอย่าง |
|---|---|
| อัตโนมัติ | Claude อ่าน description ของ subagent ทุกตัว แล้วเลือกเองเมื่องานตรง (ใส่คำว่า "use proactively" ใน description เพื่อให้เรียกบ่อยขึ้น) |
| สั่งด้วยภาษาคน | ใช้ subagent code-reviewer ตรวจไฟล์ที่แก้ |
| @-mention | พิมพ์ @agent-code-reviewer ตรวจ auth หรือเลือกจากรายการที่ขึ้นหลังพิมพ์ @ |
| ทั้ง session เป็น agent นั้น | claude --agent code-reviewer หรือ "agent": "code-reviewer" ใน settings |
Subagent ≠ agent teams ≠ workflow ≠ หลาย session
| ใช้เมื่อ | สถานะ | |
|---|---|---|
| Subagents | แตกงาน 2–5 ชิ้นในเทิร์นเดียว แล้วรวมผลกลับมาที่ตัวหลัก | ใช้ได้ทั่วไป |
| Agent teams | หลาย session ที่คุยกันเองได้ มี task list ร่วม (เปิดด้วย CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) |
ทดลอง กิน token มาก (เอกสารระบุราว 7 เท่าเมื่อ teammate อยู่ใน plan mode) |
| Workflows | สคริปต์ที่สั่ง agent เป็นสิบเป็นร้อยตัว เช่น /deep-research |
สำหรับงานใหญ่มาก |
| หลาย session ใน worktree | งานแก้โค้ดยาวที่อิสระต่อกัน (บท 7d-05) | คุมเองทั้งหมด |
ตั้งค่า ⚙️
ไฟล์ subagent: .claude/agents/<ชื่อ>.md (โปรเจกต์) หรือ ~/.claude/agents/<ชื่อ>.md (ทุกโปรเจกต์)
| ฟิลด์ | ค่า | แนะนำเริ่มต้น |
|---|---|---|
name, description |
บังคับ · description = "ใช้เมื่อไร" | เขียนเงื่อนไขชัดๆ เช่น "ใช้หลังแก้โค้ดเสร็จทุกครั้ง" |
tools / disallowedTools |
รายชื่อ tool ที่ให้ใช้ / ห้ามใช้ (ไม่ใส่ tools = ได้ทุก tool ของตัวหลัก) |
งานอ่าน: Read, Grep, Glob |
model |
haiku sonnet opus fable ชื่อรุ่นเต็ม หรือ inherit |
งานค้น/นับ/สรุป → haiku · งานรีวิว → sonnet |
effort |
low medium high xhigh max |
งานง่าย low |
maxTurns |
เพดานเทิร์น (ถึงแล้วผลถูกระบุว่ายังไม่ครบ และสั่งทำต่อได้) | 10–20 |
permissionMode |
default acceptEdits auto dontAsk plan bypassPermissions |
ไม่ใส่ (ใช้ตามตัวหลัก) |
background |
true = รันเบื้องหลังเสมอ |
งานยาวที่ไม่ต้องรอผล |
isolation |
worktree = ทำงานใน git worktree ชั่วคราว ไฟล์ไม่ชนกับตัวหลัก |
subagent ที่แก้โค้ดพร้อมกันหลายตัว |
skills, mcpServers, hooks, memory, omitClaudeMd, color |
โหลด skill ล่วงหน้า, MCP เฉพาะตัว, hook เฉพาะตัว, ความจำถาวร, ข้าม CLAUDE.md, สีในหน้าจอ | ใส่เมื่อจำเป็นเท่านั้น |
ชื่อซ้ำกันใช้ลำดับนี้: managed settings → --agents → .claude/agents/ → ~/.claude/agents/ → plugin
สร้าง subagent: เขียนไฟล์เอง หรือสั่ง Claude สร้าง subagent ชื่อ ... ใน .claude/agents/ (คำสั่ง /agents ในรุ่นปัจจุบันแค่แสดงคำแนะนำนี้ ไม่ได้เปิดตัวช่วยสร้างแล้ว)
ตั้งค่าระดับ session / เครื่อง
| ตั้งอะไร | ที่ไหน | ค่าเริ่มต้น → แนะนำ |
|---|---|---|
| จำนวนที่รันพร้อมกันได้สูงสุด | env CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS |
20 → ลดเหลือ 4–6 ถ้าอยากกันค่าใช้จ่ายบานปลาย |
| ความลึกของการซ้อน | env CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH |
3 → 1 = ห้าม subagent สร้าง subagent ต่อ |
โมเดลของ subagent ทุกตัวที่ไม่ได้ระบุ model |
env CLAUDE_CODE_SUBAGENT_MODEL (เช่น haiku) |
ใช้โมเดลเดียวกับตัวหลัก → haiku หรือ sonnet ถ้าตัวหลักเป็น Opus |
| ปิด subagent บางตัว | "permissions": {"deny": ["Agent(Explore)"]} หรือ deny Agent ทั้งหมด |
— |
| ปิดเฉพาะ Explore/Plan | env CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 |
— |
| subagent แบบชั่วคราว (ไม่สร้างไฟล์) | claude --agents '{"ชื่อ": {"description": "...", "prompt": "...", "tools": [...], "model": "haiku"}}' |
เหมาะกับสคริปต์และ -p |
ใส่ env ถาวรได้ใน settings.json ใต้ "env": {...} · ตรวจผลด้วย /tasks (ดู subagent ที่รันอยู่/เพิ่งจบ)
สิทธิ์: subagent ไม่ได้สิทธิ์เพิ่มจาก tools
toolsบอกว่า subagent เห็น tool อะไร แต่การ อนุญาตให้ใช้ ยังเป็นไปตามกฎ permission ของ session (allow/deny,--allowedTools)- ถ้าตัวหลักอยู่ใน
bypassPermissions,acceptEditsหรือautosubagent จะใช้โหมดของตัวหลัก (ค่าpermissionModeของ subagent ถูกข้าม) - background subagent ที่ขอสิทธิ์ จะขึ้นถามในหน้าจอหลักพร้อมชื่อ subagent กด Esc = ปฏิเสธเฉพาะครั้งนั้น
สั่งให้แตกงาน "กี่ตัว" และ "สั่งอย่างไร"
เอกสารทางการไม่ได้กำหนดจำนวนที่แนะนำสำหรับ subagent (สำหรับ agent teams แนะนำเริ่ม 3–5 และบอกว่า 3 ตัวที่โฟกัสมักดีกว่า 5 ตัวที่กระจัดกระจาย) หลักที่ใช้ได้จริง:
- จำนวน = จำนวนชิ้นงานที่แยกกันได้จริง ไม่ใช่ตัวเลขที่อยากได้ งานที่พึ่งกันให้ทำตามลำดับ
- เริ่มที่ 2–4 ตัว ตัวหลักต้องอ่านสรุปทุกตัวแล้วรวมผล ยิ่งมากยิ่งเสียเวลาและ token ตรงนี้
- ระบุให้ครบใน prompt: จำนวน, เกณฑ์แบ่งงานที่ไม่ทับกัน, subagent ตัวไหน, รูปแบบและความยาวของผลที่ต้องส่งกลับ, ขั้นรวมผล
แบ่งงานให้ subagent Explore 3 ตัวทำพร้อมกัน:
ตัวที่ 1 = src/api/ ตัวที่ 2 = src/ui/ ตัวที่ 3 = src/jobs/
แต่ละตัวหาจุดที่เรียก fetch() โดยไม่มี timeout ส่งกลับเป็นตาราง ไฟล์:บรรทัด / โค้ด 1 บรรทัด ไม่เกิน 20 แถว
ห้ามแก้ไฟล์ เมื่อครบทั้ง 3 ตัว ให้รวมเป็นตารางเดียว เรียงตามความเสี่ยงลองเลย 🧪
ทดลอง A — ดู subagent ในตัวทำงาน เปิด claude ในโปรเจกต์ที่มีหลายโฟลเดอร์ แล้วสั่ง
ใช้ subagent Explore 2 ตัวทำพร้อมกัน: ตัวแรกสรุปโครงสร้างโฟลเดอร์ src ตัวที่สองสรุปว่าโปรเจกต์รันเทสต์อย่างไร
แต่ละตัวส่งกลับไม่เกิน 10 บรรทัด แล้วรวมเป็นสรุปเดียว ห้ามแก้ไฟล์→ ผลที่ควรได้: เห็น subagent 2 แถวทำงานพร้อมกัน แต่ละแถวมีจำนวน tool call ของตัวเอง และ context หลักได้แค่สรุป · ระหว่างนั้นกด Ctrl+B เพื่อส่งงานที่กำลังรันไปเบื้องหลัง แล้วพิมพ์ /tasks เพื่อดูสถานะ
ทดลอง B — วัดต้นทุนจริง: ตัวเดียว vs subagent 3 ตัว (ต้องมี jq · รันใน repo เดียวกันทั้งสองแบบ)
Q="นับว่าโฟลเดอร์ระดับบนสุดแต่ละโฟลเดอร์ใน src มีไฟล์กี่ไฟล์ และไฟล์ไหนยาวที่สุด ตอบเป็นตาราง"
claude -p "$Q ทำเองโดยไม่ใช้ subagent" --permission-mode dontAsk \
--allowedTools "Read" "Glob" "Grep" "Bash(wc *)" "Bash(ls *)" --disallowedTools "Agent" \
--output-format json < /dev/null | jq '{num_turns, total_cost_usd, duration_ms}'
claude -p "$Q ให้แบ่งงานให้ subagent Explore 3 ตัวทำพร้อมกันแล้วรวมผล" --permission-mode dontAsk \
--allowedTools "Read" "Glob" "Grep" "Bash(wc *)" "Bash(ls *)" "Agent" \
--output-format json < /dev/null | jq '{num_turns, total_cost_usd, duration_ms}'→ ผลที่เราวัดได้ (โปรเจกต์ขนาดกลาง ตัวหลักเป็น Opus):
| แบบ | ต้นทุน | เวลา |
|---|---|---|
| ทำเองตัวเดียว | ~$0.26 | ~20 วินาที |
| Explore 3 ตัว (ใช้โมเดลเดียวกับตัวหลัก) | ~$1.20 | ~17 วินาที |
subagent 3 ตัวที่ตั้ง model: haiku (ทดลอง C) |
~$0.36 (ตัวหลัก $0.36 + Haiku ทั้งสามรวม < $0.01) | ~18 วินาที |
งานเล็กแบบนี้ แตกงานแล้ว แพงขึ้นเกือบ 5 เท่าแต่เร็วขึ้นแค่ไม่กี่วินาที การตั้งโมเดลเล็กช่วยได้มาก แต่ก็ยังแพงกว่าทำเอง
ทดลอง C — subagent ชั่วคราวที่ใช้ Haiku
claude -p "นับไฟล์ในแต่ละโฟลเดอร์ระดับบนสุดของ src โดยแบ่งให้ subagent file-counter 3 ตัวทำพร้อมกันแล้วรวมผล" \
--agents '{"file-counter":{"description":"นับไฟล์และวัดความยาวไฟล์ในโฟลเดอร์ที่ได้รับมอบหมาย อ่านอย่างเดียว","prompt":"นับไฟล์และความยาว (บรรทัด) ตามที่ได้รับมอบหมาย รายงานเป็นตารางสั้นที่สุด ห้ามแก้ไฟล์","tools":["Glob","Bash"],"model":"haiku"}}' \
--permission-mode dontAsk --allowedTools "Read" "Glob" "Grep" "Bash(wc *)" "Bash(ls *)" "Agent" \
--output-format json < /dev/null | jq '{total_cost_usd, models: (.modelUsage | map_values(.costUSD))}'→ ผลที่ควรได้: models แยกต้นทุนของ Opus (ตัวหลัก) กับ Haiku (subagent) ให้เห็น
→ สิ่งที่เราเจอจริง: subagent ลองรัน Bash คำสั่งอื่นนอกเหนือ wc/ls แล้ว ถูกปฏิเสธ แม้จะใส่ Bash ใน tools แล้ว เพราะ allowlist ของ session ยังคุมอยู่ — นี่คือหลักฐานว่า tools ไม่ได้ให้สิทธิ์เพิ่ม
ทดลอง D — subagent ประจำโปรเจกต์ที่ประหยัด
mkdir -p .claude/agents
cat > .claude/agents/log-digger.md <<'EOF'
---
name: log-digger
description: อ่าน log หรือผลเทสต์ยาวๆ แล้วสรุปเฉพาะ error สำคัญ ใช้ทุกครั้งที่ต้องอ่าน output เกิน 100 บรรทัด
tools: Read, Grep, Glob
model: haiku
effort: low
maxTurns: 10
background: true
---
อ่านไฟล์ที่ได้รับมอบหมาย สรุปเป็น: จำนวน error, 5 error ที่สำคัญที่สุด (ไฟล์:บรรทัด + ข้อความ 1 บรรทัด), สาเหตุที่น่าจะเป็น
ห้ามแก้ไฟล์ ห้ามเดา ถ้าไม่พบ error ให้บอกตรงๆ
EOF→ ทดสอบ: ใช้ log-digger สรุป error ใน [ไฟล์ log] · ระหว่างรอ พิมพ์ถามเรื่องอื่นต่อได้ เพราะเป็น background
ถ้าพัง
| อาการ | สาเหตุที่พบบ่อย |
|---|---|
| Claude ไม่เรียก subagent ของเรา | description ไม่บอก "ใช้เมื่อไร" ชัดพอ → เขียนใหม่หรือสั่งชื่อตรงๆ / @agent-ชื่อ |
| subagent ทำผิดทิศ | ข้อความมอบหมายงานขาดบริบท (มันไม่เห็นแชตเรา) → ระบุไฟล์ เกณฑ์ และรูปแบบผลให้ครบใน prompt |
ขึ้น Concurrent subagent limit reached |
ชนเพดานจำนวนพร้อมกัน → ลดจำนวน หรือปรับ CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS |
subagent ใช้ tool ไม่ได้ทั้งที่ใส่ใน tools |
ถูก permission ของ session ปฏิเสธ → เพิ่มใน allow rules หรือ --allowedTools |
| ค่าใช้จ่ายสูงผิดปกติ | subagent ใช้ Opus ตามตัวหลัก → ตั้ง model: haiku หรือ CLAUDE_CODE_SUBAGENT_MODEL |
ข้อดี / ข้อเสีย
| ✅ ข้อดี | ❌ ข้อเสีย |
|---|---|
| context หลักสะอาด เพราะได้แค่สรุป ทำงานยาวได้นานขึ้นก่อน compact | แพงขึ้นชัดเจน: subagent แต่ละตัวโหลด system prompt + CLAUDE.md + อ่านไฟล์ซ้ำเอง (วัดได้ ~4.5 เท่าในงานเล็ก) |
| งานค้นหา/อ่านที่แยกกันจริง ทำพร้อมกันได้ | งานเล็กแทบไม่เร็วขึ้น เพราะตัวหลักต้องรอทุกตัวแล้วรวมผล |
| แยก tool/สิทธิ์/โมเดลต่องานได้ (เช่น reviewer อ่านอย่างเดียว) | subagent ไม่เห็นแชตเรา ถ้าสั่งไม่ครบจะทำผิดทิศ และเราตรวจระหว่างทางได้ยากกว่า |
| ใช้โมเดลเล็กกับงานง่าย ลดต้นทุนได้มาก | สรุปที่ส่งกลับอาจตัดรายละเอียดสำคัญ หรือรายงานผิดโดยที่ตัวหลักไม่ได้ตรวจซ้ำ |
| background ทำให้เราคุยงานอื่นต่อได้ | subagent ที่แก้ไฟล์พร้อมกันในโฟลเดอร์เดียวชนกันได้ (ต้องใช้ isolation: worktree) |
ใช้เมื่อ: ต้องอ่าน/ค้นของเยอะที่แยกส่วนกันได้, อยากแยกสิทธิ์ (รีวิวแบบอ่านอย่างเดียว), output ยาวที่ไม่อยากให้รก context
ไม่ควรใช้เมื่อ: งานเล็กที่ทำเองจบใน 2–3 tool call, งานที่ขั้นตอนพึ่งกัน, งานที่ต้องการให้เราเห็นทุกขั้นตอน, หรือตอนที่กำลังจะชนลิมิตการใช้งาน
ทางเลือกที่ง่ายกว่า: สั่งให้ Claude ใช้ grep/rg ตรงๆ หรือแบ่งเป็นสองคำสั่งต่อกันเอง มักได้ผลพอกันในราคาถูกกว่า
สังเกตอะไร
- ที่เห็น agent หลายตัวโผล่ขึ้นมาเองคือ Claude ตัดสินใจแตกงาน ถ้าไม่อยากให้ทำ ให้สั่ง "ไม่ต้องใช้ subagent" หรือ deny
Agent - คุณภาพของงานแบบแตกงานขึ้นกับ "ใบสั่งงาน" ที่ตัวหลักเขียน ไม่ใช่จำนวน agent
- ดูต้นทุนจริงจาก
modelUsageใน JSON ทุกครั้งที่เปลี่ยนวิธีแตกงาน แทนการเดาว่าเร็วขึ้นหรือถูกลง
สรุปจำง่าย
Subagent = Claude ตัวใหม่ context ว่าง รู้แค่ใบสั่งงาน — แตกเฉพาะงานที่แยกกันได้จริง เริ่ม 2–4 ตัว ใช้โมเดลเล็ก และวัดต้นทุนก่อนเชื่อว่าคุ้ม