16.3 · Dùng subagent đúng cách — Khi nào nên và khi nào không

Mở đầu: Một cái búa đắt tiền không khiến mọi vấn đề đều là đinh

Hậu quả tự nhiên: bạn bắt đầu nghĩ "mọi task đều xứng đáng có subagent riêng". Team của bạn sinh ra python-expert, css-specialist, testing-guru, performance-wizard, security-auditor-v3, và một pipeline bug-reproducer → bug-diagnoser → bug-fixer gồm 3 subagent.

Vài tuần sau:

• Claude Code chậm hơn vì launch subagent có overhead
• Khi test fail, bạn không thấy error message vì test runner subagent nuốt hết output, chỉ trả về "Tests failed"
• Pipeline bug-reproducer → bug-diagnoser lost context — diagnoser không biết cái reproducer đã thử gì
• Worst: python-expert subagent thực ra không làm gì khác main thread, chỉ thêm bước indirection

Subagent không miễn phí. Mỗi lần gọi có chi phí: launch time, tokens cho system prompt, loss visibility vào intermediate work, compress findings thành summary. Chi phí này chỉ đáng khi subagent làm gì đó main thread không thể làm.

Bài này cho bạn decision rule đơn giản để judge, 3 use case đáng dùng, và 3 anti-pattern đã được Anthropic confirm bằng testing — để bạn không rơi vào bẫy "subagent hóa mọi thứ".

Decision rule: Intermediate work có quan trọng không?

Đây là câu hỏi duy nhất bạn cần hỏi:

┌──────────────────────────────────────────────────────────────┐
│                                                              │
│    Để hoàn thành task này tốt, MAIN THREAD có cần thấy       │
│    và phản ứng với intermediate work hay không?              │
│                                                              │
│                                                              │
│  ┌─────── KHÔNG ────────┐         ┌──────── CÓ ─────────┐    │
│  │                      │         │                     │    │
│  │  → Delegate subagent │         │  → Giữ ở main thread│    │
│  │                      │         │                     │    │
│  │  Bạn cần RESULT.     │         │  Bạn cần SEE IT     │    │
│  │  Không cần thấy      │         │  HAPPEN. Mỗi step   │    │
│  │  15 file đã đọc.     │         │  là input cho step  │    │
│  │                      │         │  tiếp theo.         │    │
│  └──────────────────────┘         └─────────────────────┘    │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Áp dụng rule này cho vài tình huống:

Nếu bạn không chắc — default main thread. Subagent đáng thêm khi clear rằng bạn có thể throw away intermediate work.

3 use case subagent thực sự mang lại giá trị

Use case 1: Research / exploration

Tại sao subagent win: Research là ví dụ classic. Câu hỏi rõ ràng, câu trả lời gọn, nhưng để tìm ra câu trả lời phải đọc nhiều file. Giá trị ở kết quả, không phải ở journey.

Ví dụ cụ thể:

Bạn hỏi: "Authentication trong codebase này hoạt động ra sao? Specifically, JWT được validate ở đâu?"

Không có subagent:

• Claude đọc 15 file trong src/auth/, src/middleware/, routes/
• Đọc schema file
• Trace 4-5 function call
• Main context bị fill bởi ~3000-5000 token code snippet
• Bạn chỉ muốn 1 câu trả lời

Có subagent auth-researcher:

• Subagent đọc cùng 15 file trong context isolated của nó
• Main context chỉ thấy summary:

  JWT validation happens in middleware/auth.js line 42,
  called from the Express router in route/api.js.

  Token lifecycle: 15-min access + 30-day refresh.
  Refresh logic in services/tokenService.js.

  Obstacles: tests use mocked JWT (see tests/helpers/auth.ts).

• Main context lean, bạn move on.

Use case 2: Code review (fresh perspective)

Tại sao subagent win: Đây là pattern subtle hơn. Khi Claude build feature cùng bạn qua nhiều turn, nó "involved" trong quá trình tạo code. Asking chính main thread review code đó thường cho feedback yếu — nó có bias tự nhiên về các quyết định đã đưa ra.

Subagent reviewer có fresh eyes:

• Nó chỉ thấy git diff và file đã modify
• Không có history của "tại sao ta chọn approach này" hay "lúc đầu ta định làm X"
• Nó apply criteria của system prompt một cách khách quan

Ví dụ:

Main thread helped you build a checkout endpoint qua 20 message. Nếu bạn hỏi chính main thread "Review đi", response thường là: "Code looks good! A few minor style suggestions." (vì nó đồng thuận với các trade-off đã bàn).

Gọi code-quality-reviewer subagent: nó không biết về 20 message kia. Nó đọc diff và thấy:

• "Missing rate limiting — any endpoint handling payment should have it"
• "Idempotency key not validated"
• "Error message exposes internal ID"

Feedback strong hơn nhiều, vì reviewer không "buy in" vào journey.

Use case 3: Custom system prompt mà main thread không có

Claude Code's main thread có default system prompt tối ưu cho: concise, code-focused response. Tốt cho coding, không phải cho mọi thứ.

Những use case cần prompt khác hẳn:

Copywriting subagent:

• Main thread voice: terse, technical
• Copywriting cần: friendly, benefit-led, persuasive, tone match brand
• Subagent với system prompt dài về voice/audience/style → output khác biệt hoàn toàn

Styling / design-system agent:

• System prompt ở-references file design system của bạn
• Khi subagent launch, file load vào context tự động
• Biết color variable, spacing scale, component pattern của bạn trước khi bắt đầu viết CSS
• Main thread không có auto-loaded context này

Legal clause auditor:

• System prompt chứa template chuẩn của hợp đồng + 10-15 ví dụ clause đã được flag
• Main thread không có domain knowledge này

Quy tắc: nếu subagent chỉ để "apply custom style" mà main thread có thể làm thông qua 1 câu prompt, không cần subagent. Chỉ tạo khi custom prompt dài đủ và được dùng lặp lại đến mức duy trì nó trong một config file có sense hơn paste-lại mỗi lần.

Bảng so sánh: Dùng main thread vs Dùng subagent

3 anti-pattern cần tránh

Anti-pattern 1: Expert persona subagent

Hiện tượng:

---
name: python-expert
description: Use this agent when you need Python expertise.
---

You are an expert Python developer with 20 years of experience.
You specialize in async patterns, type hints, and performance optimization.
Help the user with their Python problems.

Tại sao là sai:

Claude đã có toàn bộ kiến thức Python. "You are a Python expert" không add capability nào — ngược lại, nó lãng phí một cơ hội tạo subagent thực sự hữu ích.

Overhead của launching subagent (launch time, lose visibility, compress findings) chỉ đáng khi subagent làm gì đó main thread không thể:

• Apply custom system prompt ≠ default
• Keep exploratory work isolated
• Access specific files/tools via custom config

"Expert" không phải là capability khác.

Cách nhận biết: System prompt của bạn có bất kỳ cụm nào sau:

• "You are an expert..."
• "You specialize in..."
• "You have 10+ years of experience in..."
• "You are a senior [role]..."

→ Red flag. Hãy hỏi: nếu xóa hết cụm đó, subagent có làm gì khác main thread không? Nếu không → subagent này thừa.

Cách fix:

Không phải "thêm expertise" — mà thêm format, criteria, workflow cụ thể:

---
name: python-async-reviewer
description: |
  Use this agent proactively on any file in /services/ that contains
  async/await code. You MUST tell the agent which files to review.
---

When reviewing async Python code, check in order:
1. Every await is in an async function
2. No blocking I/O inside async (requests.get, file.read without aiofiles)
3. Proper asyncio.gather vs sequential await usage
4. Exception handling — unhandled asyncio.CancelledError?
5. Resource cleanup — async context managers where applicable

Output format:
[5 sections]

Khác biệt: không có "expert" claim, nhưng có concrete workflow Claude phải follow — cái này main thread không tự làm được (vì nó sẽ apply default "review pattern" thay vì 5 check cụ thể này).

Anti-pattern 2: Sequential pipeline

Hiện tượng: Bạn muốn fix bug, tạo 3 subagent:

bug-reproducer → bug-diagnoser → bug-fixer

Ý tưởng: reproducer xác nhận bug reproduce được → diagnoser phân tích root cause → fixer viết patch. Nghe gọn gàng.

Tại sao fail:

Pipeline subagent chỉ work khi task thực sự độc lập. Bug fixing luôn luôn phụ thuộc step trước:

• bug-reproducer tìm ra bug reproduce chỉ khi có flag DEBUG=true. Chi tiết này phải vào context của diagnoser.
• bug-diagnoser identify rằng issue là race condition giữa 2 goroutine X và Y. Fix phải biết tên cụ thể của X, Y. Handoff dạng summary thường lost precision.
• bug-fixer viết patch. Nhưng nó không biết các constraint (legacy code không được refactor, feature flag đang bật cho 50% user...) mà reproducer đã note.

Kết quả: handoff giữa các subagent nuốt thông tin quan trọng. Main thread phải re-give context mỗi step. Tổng thời gian lâu hơn là làm bug fix trong 1 session.

Quy tắc: Pipeline work cho task map-reduce style (độc lập, song song), không cho task sequential dependency.

Ví dụ pipeline GOOD (map-reduce):

  ┌─── audit-vendor-A (độc lập) ──┐
  │                                │
  │                                ▼
  ├─── audit-vendor-B (độc lập) ──→ aggregator
  │                                ▲
  │                                │
  └─── audit-vendor-C (độc lập) ──┘

100 contract, mỗi cái audit bằng subagent riêng parallel. Khi xong, aggregator gộp thành master report.

Ví dụ pipeline BAD (sequential dependency):

bug-reproducer → bug-diagnoser → bug-fixer
      ↓               ↓               ↓
   "reproduced"  "race in X,Y"   "fix here"
      ↓               ↓
   (thiếu info    (thiếu constraint
    về flag)       legacy code)

Thông tin chi tiết rớt mất qua mỗi handoff.

Cách fix: Giữ bug fixing trong 1 main thread. Dùng subagent có thể tách biệt exploration (research-agent tìm related code) nếu hữu ích, nhưng core debug giữ ở main.

Anti-pattern 3: Test runner subagent

Hiện tượng:

---
name: test-runner
description: Use this agent to run tests and report results.
tools: Bash, Read
---

Run the test suite and report the results.

Tại sao là sai:

Khi test fail, bạn cần full output để diagnose:

• Exact assertion message
• Stack trace
• Variable values in failing context
• Console.log output
• Snapshot diff

Subagent test runner thường trả về summary kiểu:

Tests failed. 3 failures in checkout.test.ts. Recommend reviewing.

Giờ bạn phải:

• Chạy lại test để thấy output (defeating the purpose)
• Hoặc tạo "debug subagent" để đọc output (over-engineering)
• Hoặc cấu hình test runner để dump full log (phức tạp)

Testing của Anthropic đã confirm: test runner pattern perform kém nhất trong các subagent config được test. Đây là một trong những phát hiện surprising nhưng rõ rệt — không nên dùng subagent để wrap test run cho dev workflow hàng ngày.

Cách fix:

Chạy test trực tiếp từ main thread. Output full đi thẳng vào context. Main thread (hoặc bạn) có thể dùng thông tin đó để debug ngay.

$ npm test

FAIL src/checkout/api.test.ts
  ✕ POST /checkout handles idempotency (120ms)

  Expected: 200
  Received: 409

  at Object.<anonymous> (api.test.ts:47:23)

Có full context ngay. No subagent needed.

Ngoại lệ: Nếu test suite run 30 phút và bạn chỉ cần "has anything broken?" trong CI context → subagent test runner OK nếu output format bắt buộc include stack trace khi fail. Nhưng cho dev workflow hàng ngày, main thread win.

Ví dụ theo ngành

📝 Về các case studies dưới đây: Đây là pattern minh hoạ cho decision rule và anti-pattern. Số liệu so sánh (ngày/giờ) là ước lượng illustrative từ experience chung, không phải đo lường benchmark.

Engineering — Research + Review combo (sử dụng đúng cách)

Tình huống: Senior dev nhận task refactor authentication module. Chưa quen codebase.

Workflow đúng:

1. Main thread: ask auth-researcher subagent — "JWT validated ở đâu? Token lifecycle? Test setup thế nào?" → lean summary
2. Main thread dùng summary để plan refactor
3. Main thread + dev iterate implement (subagent không can thiệp, mỗi step main thread cần thấy code build lên)
4. Main thread: ask code-quality-reviewer subagent review diff → structured feedback
5. Main thread apply revision

Kết quả minh hoạ: Refactor xong nhanh hơn đáng kể so với approach "main thread tự explore từ đầu". Main context không bị overload bởi 15-20 file explored.

Data Engineering — Parallel audit (map-reduce đúng cách)

Tình huống: Data team cần audit 100 stored procedure cho SQL injection risk.

Workflow đúng:

1. Main thread: spawn 10 sql-auditor subagent parallel, mỗi cái audit 10 procedure
2. Mỗi subagent có output format: {procedure_name, risk_level, evidence, fix_suggestion}
3. Main thread aggregate 100 output thành master spreadsheet
4. Team triage theo risk level

Kết quả minh hoạ: 100 procedure được audit song song — tổng thời gian ≈ thời gian audit 1 procedure chậm nhất, thay vì tổng 100 procedure. Nếu làm sequential trong main thread: context overflow + nhiều giờ chờ.

Marketing — Custom copywriting prompt (justified)

Tình huống: Marketing team viết 20 email campaign mỗi tháng. Cần consistent voice.

Workflow đúng:

• Tạo email-copywriter subagent với system prompt 200 dòng về brand voice, audience persona, sample good/bad copy
• Mỗi campaign: main thread → subagent → draft → human polish

Tại sao justified

200 dòng brand voice quá dài để paste mỗi lần. Subagent một lần tạo → reuse 20 lần/tháng. Chi phí ROI rõ.

Tại sao KHÔNG phải expert anti-pattern

Không có "you are a copywriter" claim — là concrete voice guide + sample. Main thread không có voice guide này tự động.

Legal — Parallel clause audit (map-reduce)

Tình huống: Legal team nhận 50 contract vendor mới từ một vụ acquisition.

Workflow đúng:

1. 50 subagent clause-auditor parallel, mỗi cái xử lý 1 contract
2. Output format: {clause_name, diff_vs_template, severity, recommendation}
3. Aggregator subagent (hoặc main thread) gộp findings
4. Lawyer chỉ xem Severity=Critical (khoảng 15-20 contract)

Kết quả minh hoạ: Tổng thời gian rút xuống đáng kể so với review tuần tự. Consistency cao hơn rõ rệt — cùng 1 template/criteria áp dụng cho mọi contract, không bị drift giữa các lawyer khác nhau.

DevOps — Sai cách: sequential deploy pipeline

Tình huống: Team muốn tạo pipeline pre-check → deploy → smoke-test → rollback-if-fail bằng 4 subagent.

Tại sao fail:

• deploy subagent không biết kết quả chính xác của pre-check (chỉ thấy summary "all checks pass")
• Nếu smoke test fail, rollback subagent không biết rollback đến đâu (cần deploy history từ step 2)
• Mỗi handoff lost chi tiết

Cách đúng: Dùng Makefile/shell script/CI runner để orchestrate. Subagent chỉ wrap 1 khâu cần custom logic (ví dụ: smoke-tester với criteria specific), còn lại để deterministic tool chạy.

Anti-patterns phụ — Các trường hợp edge case

Subagent quá specific — "review-typescript-interface-files-only"

Quá narrow → dùng 1-2 lần/tháng, không xứng công tạo. Gộp vào subagent rộng hơn với description cover case đó.

Subagent quá rộng — "general-helper"

"Do anything the user asks" = không có role. Chỉ là main thread với extra overhead. Tạo subagent có specific responsibility hoặc không tạo.

Subagent không bao giờ được Claude gọi tự động

Nếu 2 tuần không thấy Claude gọi subagent → kiểm tra description (xem Bài 16.2). Hoặc subagent đó thực ra không đáng tồn tại (task rất hiếm) → consider delete.

Duplicate subagent với overlapping description

Team có code-reviewer-v1 và code-reviewer-v2. Claude không biết gọi cái nào → random. Consolidate thành 1.

Áp dụng ngay

Bài tập 1: Audit list subagent hiện có (~15 phút)

Bước 1: List tất cả subagent trong project của bạn:

ls .claude/agents/

Bước 2: Với mỗi subagent, tự trả lời 3 câu:

Bước 3: Subagent nào check KHÔNG cho cả 2 câu đầu → candidate to archive/delete. Subagent nào check YES đủ 2 câu → giữ.

Bài tập 2: Redesign một expert-persona subagent (~15 phút)

Bước 1: Tìm (hoặc tưởng tượng) 1 subagent với system prompt dạng:

You are an expert [role] with [years] of experience...

Bước 2: Rewrite thành concrete workflow — bỏ expert claim, thêm:

• Cụ thể tool + file cần đọc
• Workflow step-by-step (3-7 step)
• Output format 5-8 section

Bước 3: Compare 2 version:

• Version cũ dùng subagent có khác với main thread không? ___________
• Version mới có workflow nào main thread không tự làm? ___________
• Bạn có tin tưởng version mới hơn không? Tại sao? ___________

Bài tập 3 (reflection): Lập kế hoạch subagent cho 1 tuần (~10 phút)

Nhìn lại 1 tuần qua, list 5 task Claude Code đã làm trong session chính:

Sau khi điền, count:

• Task nào bạn đã sai "direction" (dùng subagent khi không nên, hoặc ngược lại): ___________
• Pattern nhận ra: ___________

Mẹo nâng cao

Mẹo 1: Subagent parallel cho task "embarrassingly parallel"

Nếu task là 100 lần làm cùng 1 thứ độc lập (audit 100 file, process 100 record, review 100 PR), subagent parallel là sweet spot. Main thread orchestrate, mỗi subagent 1 unit of work.

Mẹo 2: Context preservation via subagent

Khi main context của bạn gần đầy (> 150k token), spin up subagent cho task nặng (research, review dài) để giữ main context sống lâu hơn. Đây là context engineering — subagent là công cụ quản lý context, không chỉ workflow.

Mẹo 3: Subagent chỉ justify khi reuse ≥ 10 lần

Task one-off: paste prompt vào main thread nhanh hơn. Task lặp lại ≥ 10 lần/tháng với cùng criteria → subagent có ROI. Dưới ngưỡng đó, overhead tạo/maintain subagent không xứng.

Mẹo 4: Dùng built-in subagent trước khi tạo custom

Claude Code có sẵn Explore (fast code search), Plan (research + planning). Thử built-in trước, chỉ tạo custom khi workflow cần prompt đặc biệt.

Mẹo 5: Test runner ngoại lệ — CI only

Nếu thực sự cần "run tests as subagent" cho CI workflow (không dev daily), bắt buộc output format bao gồm full stack trace và log cho mỗi fail. Và vẫn chấp nhận: dev debug local sẽ prefer chạy test trực tiếp.

Tóm tắt bài học

Tài liệu tham khảo

• Anthropic: "Building the future of agents with Claude" (2025-10-02) — multi-agent pattern, orchestrator-subagent, 100-200 tools splitting
• Anthropic Research blog: multi-agent training, deep research architecture
• Nội bộ Bài 16.1 (creation), Bài 16.2 (design)