Subagents ของ Claude Code: การแยกบริบท orchestrator และ reviewer และเมื่อไม่จำเป็นต้องใช้

Subagents ของ Claude Code คืออะไร

Subagent คือ instance ของ agent อีกตัวที่ agent หลักเรียกให้ทำงานเฉพาะเรื่อง มันมีหน้าต่างบริบทของตัวเอง system prompt ของตัวเอง และรายการเครื่องมือที่อนุญาตของตัวเอง agent หลักส่งคำอธิบายงานให้ subagent ทำงานด้วยตัวเอง เช่น อ่านไฟล์ รันคำสั่ง แล้วส่งกลับมาเพียงข้อความสรุปสุดท้าย

คำสำคัญคือการแยกส่วน (isolation) ทุกอย่างที่ subagent อ่านระหว่างทาง เช่น ไฟล์นับสิบ ผลลัพธ์เทสต์ที่ยาว และสมมติฐานที่ไม่ถูกต้อง จะอยู่ในบริบทของมันเอง ไม่เข้าไปในบริบทของเซสชันหลัก agent หลักเห็นเพียงผลสั้น ๆ เช่น "ข้อผิดพลาดอยู่ในฟังก์ชัน X สาเหตุคือ ... มีสามจุดที่ได้รับผลกระทบ"

Subagents ของ Claude Code เป็นกรณีเฉพาะของแนวคิด multi-agent system ทั่วไป แทนที่จะเป็นลูปเดียวแบบ "คิด ทำ ตรวจ" จะกลายเป็นกราฟของหลายโหนด แต่ละโหนดมีบทบาทและความรับผิดชอบของตัวเอง

ทำไมต้องแยกบริบท

หน้าต่างบริบทคือทรัพยากรหลักของ agent ในนั้นมีคำสั่งจาก CLAUDE.md ประวัติบทสนทนา โค้ดที่อ่าน และผลลัพธ์ของคำสั่ง เมื่อ agent ใช้เวลาครึ่งชั่วโมงหาสาเหตุของบั๊ก บริบทจะเต็มไปด้วยไฟล์ที่ไม่เกี่ยวข้อง และล็อกที่มีประโยชน์จริงแค่บรรทัดเดียว

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

• การค้นหาและสำรวจ "หาทุกจุดที่เรียกฟังก์ชันการชำระเงินและอธิบายว่าทำงานอย่างไร" เป็นงานทั่วไปสำหรับ subagent
• การตรวจที่มีเสียงรบกวนมาก รันเทสต์และวิเคราะห์ตัวที่ล้มเหลว ให้ subagent ทำแล้วได้รายการสาเหตุกลับมา
• การอ่านเอกสารขนาดใหญ่ สเปกหลายร้อยหน้าที่ต้องการข้อมูลเพียงไม่กี่ข้อ ให้ subagent ดึงออกมา

วิธีตั้งค่า subagent: โฟลเดอร์ .claude/agents

subagent ที่กำหนดเองอธิบายด้วยไฟล์ Markdown ที่มี YAML header ไฟล์ของโปรเจกต์อยู่ใน .claude/agents/ ในรีโพซิทอรี และทั้งทีมเข้าถึงได้ผ่าน git ส่วนไฟล์ส่วนตัวอยู่ใน ~/.claude/agents/ และใช้ได้ในทุกโปรเจกต์ของคุณ สร้างและแก้ไข subagent แบบโต้ตอบได้ด้วยคำสั่ง /agents ใน Claude Code

---
name: code-reviewer
description: ตรวจการเปลี่ยนแปลงในโค้ดหาข้อผิดพลาดและการละเมิดกฎของโปรเจกต์ ใช้หลังจบงานและก่อน commit
tools: Read, Grep, Glob, Bash
---
คุณเป็นผู้ตรวจโค้ด ไม่ต้องแก้ไขอะไร

1. ดูการเปลี่ยนแปลง: git diff
2. ตรวจทุกการเปลี่ยนแปลงหาข้อผิดพลาดของตรรกะ การจัดการข้อผิดพลาด
   และความปลอดภัย (SQL การ escape ผลลัพธ์ ความลับ)
3. เทียบกับกฎใน AGENTS.md
4. ส่งรายการข้อสังเกต: ไฟล์ บรรทัด ปัญหา และเหตุผลว่าทำไมสำคัญ
   ถ้าไม่มีข้อสังเกต ให้เขียนแบบนั้นตรง ๆ

ความหมายของแต่ละฟิลด์:

ส่วนเนื้อหาของไฟล์คือ system prompt ของ subagent มันไม่เห็นประวัติบทสนทนาของคุณ ดังนั้นทุกอย่างที่ต้องรู้เกี่ยวกับบทบาทและรูปแบบคำตอบต้องอยู่ใน prompt หรือในงานที่ agent หลักส่งให้

วิธีเรียก subagent

agent หลักเลือก subagent เองได้ถ้างานตรงกับ description แต่การขอให้ชัดเจนน่าเชื่อถือกว่า เช่น "ใช้ subagent code-reviewer เพื่อตรวจการเปลี่ยนแปลง" การใส่วลีอย่าง "ใช้เชิงรุก" ใน description เพิ่มโอกาสให้ agent เรียกเองโดยไม่ต้องเตือน แต่ไม่รับประกัน

Subagent สำหรับสำรวจ

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

---
name: explorer
description: ค้นหาในโค้ดเบสเพื่อตอบคำถามว่าอะไรอยู่ที่ไหนและทำงานอย่างไร ใช้เมื่อต้องอ่านไฟล์จำนวนมากเพื่อได้คำตอบสั้น ๆ
tools: Read, Grep, Glob
---
คุณสำรวจโค้ดและไม่แก้ไขอะไร
ส่งกลับ: คำตอบสั้น ๆ ของคำถาม รายการไฟล์พร้อมบรรทัดที่อ้างอิง
และสิ่งที่ตรวจสอบไม่ได้

subagent แบบนี้มีประโยชน์มากตอนเริ่มงาน agent หลักได้แผนที่ของจุดที่ต้องดูโดยไม่ต้องเสียบริบทไปกับการอ่านทุกอย่าง แล้วทำงานต่อด้วยไฟล์ที่เจาะจงแล้ว

รูปแบบ orchestrator และ executor

รูปแบบ multi-agent ที่พบบ่อยที่สุดคือ agent orchestrator หนึ่งตัวที่ถือแผนและภาพรวม แล้วมอบขั้นตอนเฉพาะให้ executor orchestrator ไม่ได้อ่านโค้ดทั้งหมดเอง แต่กำหนดงาน รับผลลัพธ์ และตัดสินใจว่าจะทำอะไรต่อ

1. orchestrator แบ่งงานเป็นส่วนอิสระและเขียนคำสั่งที่ครบในตัวสำหรับแต่ละส่วน: เป้าหมาย จุดที่ต้องค้นหา เกณฑ์ว่าเสร็จ และรูปแบบของคำตอบ
2. executor ทำตามคำสั่งในบริบทของตัวเอง
3. orchestrator รวบรวมคำตอบ ตรวจว่าส่วนต่าง ๆ เข้ากันได้ และสั่งขั้นตอนถัดไปหรือย้อนกลับ

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

executor ควรส่งอะไรกลับมา

กำหนดรูปแบบคำตอบไว้ล่วงหน้า: รายการไฟล์ ผลลัพธ์ สาเหตุที่พบ และสิ่งที่ตรวจไม่ได้ คำตอบที่มีโครงสร้างสั้นช่วยประหยัดบริบทของ orchestrator และข้อ "สิ่งที่ยังไม่ได้ตรวจ" ป้องกันความมั่นใจที่ผิดที่ เพราะ executor เหมือน agent ทั่วไปมักรายงานว่าสำเร็จ

reviewer แยกต่างหาก: ทำไมต้องแยกผู้ตัดสินออกจากผู้ลงมือทำ

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

reviewer ในบริบทแยกไม่มีปัญหาเหล่านี้ มันไม่รู้ประวัติการตัดสินใจ เห็นเพียง diff และกฎของโปรเจกต์ และประเมินผลลัพธ์ด้วยสายตาใหม่ เป็นหลักการเดียวกับทีมจริง ผู้เขียนไม่ควรอนุมัติ pull request ของตัวเอง

• ให้ reviewer มีเพียงเครื่องมืออ่านและรันการตรวจ โดยไม่มีสิทธิ์แก้ไขไฟล์ เพื่อไม่ให้มัน "แก้เงียบ ๆ" แทนที่จะรายงานปัญหา
• ระบุเกณฑ์การตรวจให้ชัด ว่าอะไรนับเป็นข้อผิดพลาด และกฎใดของโปรเจกต์บังคับ
• การตัดสินใจว่าจะจัดการข้อสังเกตอย่างไรเป็นหน้าที่ของ orchestrator หรือมนุษย์ reviewer หาปัญหา executor แก้ปัญหา

reviewer ไม่ได้มาแทนการตรวจเชิงกลไก เทสต์ linter และการตรวจ type เป็นโหนดที่กำหนดผลได้แน่นอน และเชื่อถือได้กว่าโมเดลใด ๆ reviewer จับสิ่งที่กลไกมองไม่เห็น เช่น ตรรกะที่ผิด การละเมิดข้อตกลง หรือความซับซ้อนที่ไม่จำเป็น

การรัน subagent แบบขนาน

Claude Code รัน subagent หลายตัวพร้อมกันได้ ซึ่งช่วยให้เร็วขึ้นเมื่อส่วนต่าง ๆ ของงานเป็นอิสระจริง เช่น ศึกษาสามโมดูล หรือตรวจการเปลี่ยนแปลงจากสามมุม (ความปลอดภัย ประสิทธิภาพ เทสต์) หรือรวบรวมข้อมูลจากหลายแหล่ง

การขนานทำงานได้ดีกับการอ่านและแย่กับการเขียน หาก subagent สองตัวแก้ไฟล์เดียวกันพร้อมกัน พวกมันจะทับการเปลี่ยนแปลงของกันและกันโดยไม่มีใครรู้ ในภาษาของกราฟ agent นี่คือ shared state ที่ไม่มีกฎการรวม แนวทางปฏิบัติ:

• ขนาน: การสำรวจ การวิเคราะห์ การรีวิว ส่วนการแก้ไขในไฟล์ที่ทับซ้อนกันให้ทำตามลำดับ
• ถ้า executor ต้องเขียนพร้อมกันจริง ให้แบ่งโซน: แต่ละตัวทำงานเฉพาะในไฟล์ของตัวเอง หรือในสำเนาของรีโพซิทอรีเอง (เช่น git worktree แยก)
• ให้โหนดเดียวคือ orchestrator เป็นผู้รวมผล ไม่ใช่ให้ executor คุยกันเอง

เมื่อไม่จำเป็นต้องใช้ subagent

รูปแบบ multi-agent มีต้นทุน คือโทเคนมากขึ้น เวลามากขึ้น และมีจุดที่ข้อมูลสูญหายระหว่างการส่งต่องานเพิ่มขึ้น subagent ของ Claude Code ไม่ได้คุ้มค่าเสมอไป

ก่อนสร้างกราฟของ agent ให้ตอบคำถามง่าย ๆ ก่อน: ใครเป็นเจ้าของเป้าหมายรวม ใครมีสิทธิ์คัดค้านและย้อนการเปลี่ยนแปลง และอะไรนับเป็นความสำเร็จ ถ้าตอบไม่ได้ agent หลายตัวจะเพิ่มความสับสนเท่านั้น

ข้อผิดพลาดที่พบบ่อยกับ subagent

คำอธิบายที่คลุมเครือ

คำอธิบายอย่าง "ผู้ช่วยด้านโค้ด" ไม่ช่วยให้ agent หลักเลือกได้ว่าเมื่อไรควรเรียก ให้เขียนตัวกระตุ้นที่ชัดเจน: "หลังการเปลี่ยนแปลงในโฟลเดอร์ api/ ก่อน commit"

คำสั่งที่ไม่มีบริบท

subagent ได้งานโดยไม่มีพาธ เกณฑ์ว่าเสร็จ หรือข้อจำกัด แล้วต้องใช้ครึ่งหนึ่งของงานไปกับการเดาว่าต้องการอะไร แก้ด้วยเทมเพลตของคำสั่ง: เป้าหมาย ข้อมูลนำเข้า ข้อจำกัด รูปแบบคำตอบ

สิทธิ์กว้างเกินไป

ผู้สำรวจและ reviewer ไม่จำเป็นต้องมีสิทธิ์แก้ไขไฟล์ การจำกัด tools เป็นวิธีที่ถูกที่สุดในการทำให้บทบาทเป็นกลไก ไม่ใช่แค่คำขอใน prompt

เชื่อรายงานโดยไม่ตรวจ

"เทสต์ทั้งหมดผ่าน" ในคำตอบของ subagent เป็นข้ออ้าง ไม่ใช่ข้อเท็จจริง orchestrator ต้องอิงกับสิ่งที่ตรวจได้ คือผลลัพธ์ของคำสั่ง รหัสผลลัพธ์ และบรรทัดที่เจาะจง

สรุป

Subagents ของ Claude Code มีประโยชน์สามอย่าง คือรักษาบริบทหลักให้สะอาด แยกการตรวจออกจากการลงมือทำ และกระจายงานอิสระให้ทำพร้อมกัน ถูกกำหนดด้วยไฟล์ Markdown สั้น ๆ ใน .claude/agents/ และคุณภาพการทำงานขึ้นกับคำอธิบายบทบาท ชุดเครื่องมือ และความครบถ้วนของคำสั่งเป็นหลัก ถ้างานเล็กหรือพึ่งการสนทนาแน่น agent เดียวยังดีกว่า การเปลี่ยนจากลูปเดียวไปเป็นระบบของโหนด เส้นเชื่อม และ shared state ถูกอธิบายและนำไปใช้จริงในคอร์สนี้