Định tuyến model cho subagent: để Haiku làm việc vặt, Opus lo việc khó

Khi dùng Claude Code lâu, bạn sẽ nhận ra phần lớn token không đổ vào việc “nghĩ” mà vào việc đọc: dò file, grep, đọc log, liệt kê nơi gọi một hàm. Giao những việc này cho model mạnh nhất là phí. Subagent cho phép tách các việc đó ra, chạy trong context riêng, với model rẻ hơn — còn model lớn chỉ tập trung vào thiết kế, quyết định và review.

Subagent là gì?

Subagent là một trợ lý AI chuyên biệt bên trong phiên Claude Code. Mỗi subagent có:

• Context window riêng — output dài dòng (kết quả tìm kiếm, log, nội dung file) không làm đầy hội thoại chính; subagent chỉ trả về kết quả tóm gọn.
• System prompt riêng — tập trung vào một vai.
• Bộ tool và quyền riêng — ví dụ chỉ đọc, không sửa.
• Model riêng — đây là chìa khoá để tiết kiệm.

Lưu ý: request của subagent vẫn tính vào cùng hạn mức với phiên chính. Tiết kiệm đến từ việc dùng model rẻ hơn và giữ context chính gọn, chứ không phải “miễn phí”.

Subagent có sẵn trong Claude Code

Explore và Plan bỏ qua file CLAUDE.md và snapshot git status để chạy nhanh, rẻ hơn.

Tạo subagent của riêng bạn

Cách nhanh nhất: mô tả subagent bạn muốn cho Claude và nói lưu ở đâu — Claude sẽ tự viết file. Hoặc tự tạo file Markdown theo mẫu:

---
name: code-scout
description: Tìm file, đọc log, liệt kê nơi dùng một hàm. Use proactively khi cần khảo sát codebase.
tools: Read, Glob, Grep
model: haiku
---
Bạn là trợ lý khảo sát code. Chỉ đọc, không sửa.
Trả về danh sách file + số dòng liên quan, tối đa 20 mục,
mỗi mục kèm 1 câu giải thích vì sao liên quan.

Phần frontmatter (YAML giữa hai dấu ---) là cấu hình; phần thân Markdown trở thành system prompt của subagent. Chỉ name và description là bắt buộc.

Lưu file ở đâu?

Trùng tên thì vị trí ưu tiên cao hơn thắng. Claude Code theo dõi các thư mục này, sửa file là có hiệu lực sau vài giây, không cần khởi động lại.

Các trường frontmatter đáng dùng

Claude chọn model cho subagent theo thứ tự nào?

1. Tham số model mà Claude truyền khi gọi subagent (nếu có).
2. Trường model trong frontmatter (inherit = model của phiên chính).
3. Biến môi trường CLAUDE_CODE_SUBAGENT_MODEL.
4. Model của phiên chính.

Muốn ép mọi subagent chạy một model (ví dụ để khống chế chi phí cả team), đặt cả hai biến trong settings.json:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Khi bật FORCE, trường model trong frontmatter bị bỏ qua (cần Claude Code v2.1.257 trở lên). Gõ /tasks để xem subagent đang chạy dùng model nào.

Gợi ý phân vai theo model

Gọi subagent

• Tự động: Claude so khớp yêu cầu với description. Thêm cụm “use proactively” để Claude chủ động giao việc.
• Bằng lời: “Dùng subagent code-scout để tìm mọi nơi gọi createOrder”.
• @-mention: gõ @ rồi chọn subagent — đảm bảo đúng subagent đó chạy.
• Cả phiên: claude --agent code-scout để phiên chính mang luôn tool và model của subagent.
• Tạm thời qua CLI: claude --agents '{...JSON...}' — chỉ tồn tại trong phiên, không ghi ra đĩa.

Giới hạn cần biết

• Mặc định chạy tối đa 20 subagent cùng lúc; lồng nhau tối đa 3 tầng dưới phiên chính.
• Subagent khởi động với context mới: không thấy lịch sử hội thoại của bạn. Quy tắc quan trọng phải nhắc lại trong prompt giao việc.
• Subagent mới cần thời gian thu thập context — việc nhỏ, cần hỏi qua lại nhiều thì làm luôn ở phiên chính nhanh hơn.

Áp dụng thế nào?

• Dev: Tạo 2–3 subagent dùng hằng ngày: code-scout (haiku, chỉ đọc), test-runner (haiku/sonnet, chạy và tóm tắt test), reviewer (opus, chỉ đọc). Theo dõi mức dùng trong một tuần để thấy chênh lệch.
• Tech Lead: Commit thư mục .claude/agents/ vào repo để cả team dùng chung một bộ vai, giống như chia sẻ cấu hình linter.
• PM: Khi team than “hết quota Claude Code giữa tuần”, định tuyến model cho subagent là một trong những cách rẻ nhất để kéo dài hạn mức trước khi nâng gói.