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

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:

Á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.

┌──────────────────────────────────────────────────────────────┐
│                                                              │
│    Để 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.         │    │
│  └──────────────────────┘         └─────────────────────┘    │
│                                                              │
└──────────────────────────────────────────────────────────────┘

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:

Có subagent auth-researcher:

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:

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:

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:

Styling / design-system agent:

Legal clause auditor:

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.

• 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
• Subagent đọc cùng 15 file trong context isolated của nó
• Main context chỉ thấy summary:
• Main context lean, bạn move on.
• 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
• "Missing rate limiting — any endpoint handling payment should have it"
• "Idempotency key not validated"
• "Error message exposes internal ID"
• 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
• 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
• 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

  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).

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:

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ể:

"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:

→ 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ể:

• Apply custom system prompt ≠ default
• Keep exploratory work isolated
• Access specific files/tools via custom config
• "You are an expert..."
• "You specialize in..."
• "You have 10+ years of experience in..."
• "You are a senior [role]..."

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.

❌ Anti-pattern 1: Expert persona subagent

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:

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]

❌ Anti-pattern 2: Sequential pipeline

Ý 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:

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):

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 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.

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

bug-reproducer → bug-diagnoser → bug-fixer

3 anti-pattern cần tránh (tiếp)

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:

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

❌ Anti-pattern 3: Test runner subagent

Tại sao là sai:

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

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

Giờ bạn phải:

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.

• Exact assertion message
• Stack trace
• Variable values in failing context
• Console.log output
• Snapshot diff
• 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)

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

Run the test suite and report the results.

3 anti-pattern cần tránh (tiếp)

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.

# Main thread
$ 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)

Ví dụ theo ngành

🛠️ 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:

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:

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ạ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:

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:

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.

• Main thread: ask auth-researcher subagent — "JWT validated ở đâu? Token lifecycle? Test setup thế nào?" → lean summary
• Main thread dùng summary để plan refactor
• Main thread + dev iterate implement (subagent không can thiệp, mỗi step main thread cần thấy code build lên)
• Main thread: ask code-quality-reviewer subagent review diff → structured feedback
• Main thread apply revision
• Main thread: spawn 10 sql-auditor subagent parallel, mỗi cái audit 10 procedure
• Mỗi subagent có output format: {procedure_name, risk_level, evidence, fix_suggestion}
• Main thread aggregate 100 output thành master spreadsheet
• Team triage theo risk level
• 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
• 50 subagent clause-auditor parallel, mỗi cái xử lý 1 contract
• Output format: {clause_name, diff_vs_template, severity, recommendation}
• Aggregator subagent (hoặc main thread) gộp findings
• Lawyer chỉ xem Severity=Critical (khoảng 15-20 contract)
• 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

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:

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:

ls .claude/agents/

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

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

Bước 3: Compare 2 version:

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:

• Cụ thể tool + file cần đọc
• Workflow step-by-step (3-7 step)
• Output format 5-8 section
• 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? ___________
• 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: ___________

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

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

🎯 Decision rule duy nhất: Main thread có cần thấy và react với intermediate work không? Không → subagent. Có → giữ main thread.

🎯 3 use case subagent thực sự win: research/explore (không cần journey), code review (fresh perspective), custom system prompt main thread không có.

🎯 Anti-pattern 1 — Expert persona: "You are a Python expert" thừa. Claude đã có kiến thức đó. Subagent chỉ đáng tạo khi có workflow/format cụ thể main thread không default có.

🎯 Anti-pattern 2 — Sequential pipeline: Chỉ work với task độc lập (map-reduce). Task sequential dependency (bug fix, feature build) → information loss qua handoff, giữ main thread.

🎯 Anti-pattern 3 — Test runner: Anthropic testing đã confirm performs kém nhất. Khi test fail, bạn cần full output để debug. Chạy test ở main thread.