Tạo một subagent

Claude Code có sẵn các subagent, nhưng bạn cũng có thể tự tạo riêng. Subagent tùy chỉnh chuyên về những việc cụ thể - như review code, viết test, hay kiểm tra tài liệu. Chúng được định nghĩa dưới dạng file markdown kèm YAML frontmatter, cho Claude biết khi nào nên dùng subagent và nó nên hành xử ra sao.

Tạo một subagent

Cách dễ nhất để tạo subagent là dùng lệnh /agents. Lệnh này mở giao diện chính để quản lý subagent của bạn. Từ đó, chọn Create new agent.

Trước tiên bạn sẽ được hỏi chọn phạm vi (scope) cho subagent:

• Project-level - chỉ khả dụng trong project hiện tại.
• User-level - dùng chung cho mọi project trên máy của bạn.

Tiếp theo, bạn chọn cách tạo. Bạn có thể tự viết cấu hình bằng tay, nhưng cách được khuyến nghị là để Claude tự sinh ra nó. Chỉ cần mô tả điều bạn muốn subagent làm, Claude sẽ tạo ra tên, mô tả, và system prompt dựa trên yêu cầu của bạn.

Luồng tạo agent mới, với hai lựa chọn: để Claude tự sinh cấu hình, hoặc tự tay cấu hình.

Tuỳ chỉnh tool

Trong lúc tạo, bạn có cơ hội tuỳ chỉnh subagent được truy cập những tool nào. Các nhóm tool gồm:

• Tool chỉ-đọc (read-only)
• Tool chỉnh sửa (edit)
• Tool thực thi (execution)
• Tool MCP
• Các tool khác

Hãy nghĩ xem subagent của bạn thực sự cần gì. Một code reviewer có lẽ không cần tool chỉnh sửa - nó nên đọc và phân tích code, không thay đổi nó. Tuy nhiên, bạn có thể muốn giữ tool thực thi để nó dễ dàng xác định các thay đổi đang chờ xử lý hơn.

Bước chọn tool trong quá trình tạo agent.

Chọn model và màu

Sau khi cấu hình tool, bạn chọn model Claude nào sẽ vận hành subagent. Các lựa chọn gồm:

• Haiku - tốt nhất cho các tác vụ nhanh, nhẹ.
• Sonnet - điểm cân bằng tốt giữa tốc độ và chiều sâu.
• Opus - tốt nhất cho phân tích phức tạp.
• Inherit - dùng bất kỳ model nào hội thoại chính của bạn đang chạy.

Cuối cùng, bạn chọn một màu. Màu này hiện trong UI để bạn nhanh chóng biết subagent nào đang hoạt động. Đây là một chi tiết nhỏ, nhưng hữu ích khi bạn chạy nhiều subagent cùng lúc.

Bước chọn màu nền cho agent.

File cấu hình

Khi hoàn tất, file cấu hình subagent được lưu vào project của bạn (thường ở .claude/agents/ten-agent-cua-ban.md). Đây là hình dạng một file cấu hình subagent điển hình:

---
name: code-quality-reviewer
description: Use this agent when you need to review recently written or modified code for quality, security, and best practice compliance.
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch
model: sonnet
color: purple
---

You are an expert code reviewer specializing in quality assurance, security best practices, and
adherence to project standards. Your role is to thoroughly examine recently written or modified code
and identify issues that could impact reliability, security, maintainability, or performance.

Hãy phân tích từng field:

• name - định danh duy nhất cho subagent. Đây là cách bạn tham chiếu tới nó, hoặc bằng cách hỏi Claude trực tiếp, hoặc gõ @agent code-quality-reviewer trong tin nhắn của bạn.
• description - kiểm soát khi nào Claude quyết định dùng subagent này. Trường này phải là một dòng duy nhất (dùng ký tự xuống dòng đã escape \n nếu cần ngắt dòng). Bạn có thể đưa vào các đoạn hội thoại mẫu để giúp Claude hiểu khi nào nên giao việc.
• tools - liệt kê các tool subagent được truy cập. Mặc định khớp với những gì bạn đã chọn lúc tạo, nhưng bạn có thể sửa danh sách này bất cứ lúc nào.
• model - chỉ định model Claude nào được dùng: sonnet, opus, haiku, hoặc inherit.
• color - màu UI để nhận diện subagent.

System prompt

Phần thân của file markdown (mọi thứ nằm dưới YAML frontmatter) chính là system prompt. Đây là nơi bạn đưa ra chỉ dẫn cho subagent: nó nên tập trung vào điều gì, nên phân tích thế nào, và nên báo cáo phát hiện lại cho agent chính ra sao.

Một system prompt được viết tốt chính là khác biệt giữa một subagent hữu ích và một subagent lạc đề. Hãy cụ thể về việc subagent nên tìm kiếm gì và nên cấu trúc output của nó ra sao.

Để Claude tự động dùng subagent của bạn

Nếu bạn muốn Claude giao việc cho subagent mà không cần bạn yêu cầu tường minh, hãy thêm từ “proactively” vào field description. Ví dụ:

description: Proactively suggest running this agent after major code changes...

Bạn cũng có thể thêm các đoạn hội thoại mẫu vào description để giúp Claude hiểu những tình huống cụ thể nên dùng subagent. Ví dụ càng cụ thể, Claude càng giỏi trong việc nhận ra khi nào nên giao việc.

Kiểm tra subagent của bạn

Sau khi tạo subagent, hãy kiểm tra nó bằng cách thực hiện vài thay đổi code và yêu cầu Claude review chúng.

Yêu cầu Claude Code dùng subagent code-reviewer để review các thay đổi gần đây.

Nếu subagent không được dùng khi bạn kỳ vọng, hãy quay lại kiểm tra phần description. Thêm các ví dụ và tình huống kích hoạt cụ thể hơn sẽ giúp Claude hiểu khi nào nên giao việc cho subagent của bạn.

Nguồn

Dịch từ bài giảng “Creating a subagent”, khóa Introduction to subagents trên Claude Academy.