🤖 Tạo Sub-Agent Chuyên Biệt Trong Claude Code Với File .claude/agents/
Bạn đã bao giờ thấy Claude Code cố gắng làm mọi thứ cùng một lúc, rồi lại làm sai? Có một cách để chia nhỏ công việc ra cho từng agent chuyên biệt, mỗi agent chỉ làm đúng một việc thôi.
🗂️ Custom Sub-Agent Là Gì?
Claude Code cho phép bạn tạo custom sub-agents bằng cách đặt file markdown vào thư mục .claude/agents/ trong project. Mỗi file là một agent riêng, với system prompt và danh sách tools được định nghĩa rõ ràng.
Thay vì một agent làm tất cả, bạn có thể có code-reviewer, test-writer, security-auditor hoạt động độc lập. Mỗi agent chỉ biết đúng việc của mình.
📄 Cấu Trúc Một File Agent
Một file agent cơ bản trông như thế này:
---
name: security-auditor
description: Chuyên review bảo mật, check OWASP top 10
tools: Read, Grep
---
Bạn là chuyên gia bảo mật. Khi review code, hãy kiểm tra:
- SQL injection, XSS, CSRF
- OWASP Top 10
- Hardcoded credentials
- Input validation
Chỉ đọc file, không chỉnh sửa gì cả.
Phần frontmatter định nghĩa tên, mô tả, và tools được phép. System prompt nằm bên dưới, tập trung hoàn toàn vào nhiệm vụ của agent đó.
🔧 Ví Dụ Thực Tế: Hai Agent Thường Dùng
code-reviewer.md: chỉ có quyền Read, system prompt tập trung vào security patterns và code quality. Agent này không bao giờ ghi file, tránh hoàn toàn việc tự ý sửa code của bạn.
test-writer.md: có quyền Read và Write, system prompt chuyên về testing patterns, biết cách tạo unit test, integration test phù hợp với framework bạn đang dùng.
Hai agent, hai mục đích rõ ràng, không chồng chéo.
⚡ Cách Dùng Trong Claude Code
Sau khi tạo file xong, bạn có hai cách kích hoạt:
Gõ /agents để xem danh sách tất cả custom agents đang có. Claude Code sẽ liệt kê tên và description của từng agent.
Hoặc dùng Task tool, Claude sẽ tự động chọn agent phù hợp dựa trên description bạn đã viết. Ví dụ khi task là "review bảo mật cho file này", Task tool sẽ chọn security-auditor thay vì chạy agent mặc định.
Custom agents kế thừa MCP tools từ session cha, nhưng bạn có thể giới hạn lại chỉ còn những tools cần thiết.
🧠 Tại Sao Context Nhỏ Hơn Lại Tốt Hơn?
Đây là điểm cốt lõi. Khi system prompt tập trung vào một nhiệm vụ duy nhất, context window của agent nhỏ gọn hơn nhiều so với agent làm tất cả mọi thứ. Context nhỏ hơn nghĩa là ít bị hallucinate hơn, câu trả lời chuẩn xác hơn, và cost token thấp hơn theo thời gian.
Một security-auditor chỉ cần biết về OWASP, không cần biết cách viết test hay deploy. Đơn giản vậy thôi.
📁 Đặt File Ở Đâu?
.claude/agents/ trong project là project-level agents, chỉ hoạt động trong project đó. Bạn cũng có thể đặt ở ~/.claude/agents/ để dùng cho mọi project.
Mỗi team member clone repo về là có ngay bộ agents đã được cấu hình sẵn. Không cần setup lại.
Bạn đang dùng agent kiểu one-size-fits-all hay đã thử chia nhỏ ra chưa? Với project của bạn, agent nào bạn nghĩ sẽ hữu ích nhất?
