ระดับ 6d · บทที่ 5/8

Subagents ลงลึก — ให้ AI แตกงานไปทำพร้อมกัน กี่ตัว สั่งอย่างไร และคุ้มเมื่อไร

⏱ 40 นาทีลองในClaude ↗

เป้าหมาย

เข้าใจว่า "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 หรือ auto subagent จะใช้โหมดของตัวหลัก (ค่า permissionMode ของ subagent ถูกข้าม)
  • background subagent ที่ขอสิทธิ์ จะขึ้นถามในหน้าจอหลักพร้อมชื่อ subagent กด Esc = ปฏิเสธเฉพาะครั้งนั้น

สั่งให้แตกงาน "กี่ตัว" และ "สั่งอย่างไร"

เอกสารทางการไม่ได้กำหนดจำนวนที่แนะนำสำหรับ subagent (สำหรับ agent teams แนะนำเริ่ม 3–5 และบอกว่า 3 ตัวที่โฟกัสมักดีกว่า 5 ตัวที่กระจัดกระจาย) หลักที่ใช้ได้จริง:

  1. จำนวน = จำนวนชิ้นงานที่แยกกันได้จริง ไม่ใช่ตัวเลขที่อยากได้ งานที่พึ่งกันให้ทำตามลำดับ
  2. เริ่มที่ 2–4 ตัว ตัวหลักต้องอ่านสรุปทุกตัวแล้วรวมผล ยิ่งมากยิ่งเสียเวลาและ token ตรงนี้
  3. ระบุให้ครบใน 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 ตัว ใช้โมเดลเล็ก และวัดต้นทุนก่อนเชื่อว่าคุ้ม