Tạo Custom Agent trong Claude Code: Từ file YAML đến thực chiến

Định nghĩa

Custom agent (hay subagent) trong Claude Code là một instance LLM chuyên biệt với context window riêng biệt, system prompt tùy chỉnh và tập quyền hạn tool bị giới hạn, được khai báo qua file Markdown trong thư mục .claude/agents/ để xử lý tác vụ cụ thể mà không làm ô nhiễm context của agent chính.

Giải thích chi tiết

Cấu trúc file agent: YAML frontmatter định nghĩa "hành vi"

Một custom agent được định nghĩa bằng file Markdown đơn giản với cấu trúc hai phần: YAML frontmatter chứa metadata và phần thân chứa system prompt. Dưới đây là ví dụ cấu trúc cơ bản:

---
name: security-auditor
description: Expert security auditor specializing in injection vulnerabilities, auth bypasses, and secret leakage. Use when reviewing code for security issues or before deploying to production.
model: claude-3-5-haiku-20241022
allowedTools: Read, Glob, Grep, Bash
maxTurns: 20
---

You are a paranoid security engineer. Your job is to:
1. Scan all modified files for SQL injection, XSS, and hardcoded secrets
2. Check for unsafe deserialization and path traversal
3. Report findings in Vietnamese with severity levels (Critical/High/Medium)
4. Never suggest fixes that reduce security
5. Always assume external input is malicious

Trường description đóng vai trò như function signature bằng ngôn ngữ tự nhiên. Claude sử dụng semantic similarity để quyết định có delegate task cho agent này hay không. Mô tả càng cụ thể về chuyên môn và ngữ cảnh sử dụng, agent càng được gọi đúng lúc. Trường allowedTools là rào chắn bảo mật quan trọng — ví dụ agent chỉ đọc code (Read, Glob) sẽ không thể vô tình xóa file dù bị jailbreak.

Nguyên lý hoạt động: Process Isolation cho AI

Hiểu custom agent qua analogy "virtual memory" của hệ điều hành. Khi bạn yêu cầu Claude "tìm bug rồi refactor codebase", bạn đang nạp hai chương trình nặng vào cùng một không gian RAM: Debugger (cần grep, đọc log, thử nghiệm) và Architect (cần giữ design pattern cao cấp). Chúng xung đột — thông tin trial-and-error của debugger đè lên kiến trúc của architect.

Subagent tạo ra process isolation: mỗi agent spawn trong context window sạch 200k tokens riêng. Sau khi hoàn thành, chúng trả về summary 2-5k tokens thay vì toàn bộ "suy nghĩ dài dòng" (scratchpad). Điều này ngăn chặn "context pollution" — hiện tượng intermediate reasoning (những lần thử grep sai, file đọc không liên quan) làm loãng attention của agent chính.

Điểm mấu chốt: Agent con không thể spawn agent cháu (no recursion). Điều này tránh infinite loop và exponential token cost.

Phân quyền theo mô hình Allowlist

Thay vì mặc định cho phép mọi thao tác rồi cấm sau (denylist), custom agent sử dụng default-deny: chỉ các tool liệt kê trong allowedTools mới được phép gọi. Pattern phổ biến:

• Read-only agents: Read, Glob, Grep, View — dùng cho audit, research, analysis. An toàn tuyệt đối, có thể dùng model rẻ (Haiku) cho tiết kiệm chi phí.
• Write-capable agents: Thêm Edit, Write, Bash — dùng cho implementation agents nhưng cần giám sát chặt.
• Specialized tool agents: Chỉ MCP để truy vấn database, hoặc chỉ WebFetch để research.

maxTurns giới hạn số vòng lặp suy nghĩ — ngăn agent "suy nghĩ quá nhiều" về vấn đề đơn giản hoặc bị stuck trong infinite loop khi gặp edge case.

Scope: User-level vs Project-level

Vị trí lưu file agent quyết định phạm vi sử dụng:

• ~/.claude/agents/ (User scope): Agent dùng cho mọi project trên máy. Phù hợp cho agent cá nhân như "blog-editor" (kiểm tra chính tả tiếng Việt) hoặc "api-tester" (chạy Postman-like tests).
• ./.claude/agents/ (Project scope): Agent chỉ xuất hiện khi làm việc trong repo này. Phù hợp cho agent mang tính domain-specific như "django-migration-checker" hoặc "react-performance-auditor".

Ví dụ thực tế

Security Auditor "Song song hóa" review

Bạn đang viết feature thanh toán mới tích hợp VietQR. Thay vì chờ xong rồi mới nhờ senior review, bạn chạy ngay security agent song song:

# Trong khi bạn code ở main session...
claude spawn security-auditor "Review src/payment/*.ts for injection risks in VietQR integration"

Agent này (chạy Haiku cho rẻ) chỉ được phép Read và Grep. Nó quét file, tìm các pattern như req.query nối chuỗi SQL hoặc hardcoded API keys của Momo/GrabPay, rồi báo cáo: "Phát hiện 2 lỗi: Line 45 có SQL injection, Line 78 hardcoded JWT secret". Bạn nhận báo cáo sau 30 giây trong khi vẫn đang viết code — không cần context switch.

Database Query Validator cho Data Team

Team data của Tiki muốn đảm bảo mọi query đều có index tương ứng trước khi mùa sale 11/11 đến. Tạo agent query-validator với prompt: "Kiểm tra mọi câu SQL trong thư mục migrations/ có sử dụng EXPLAIN không, xác nhận không có full table scan trên bảng lớn hơn 10 triệu rows."

Agent này dùng MCP kết nối PostgreSQL (mcp__postgres__query), chạy EXPLAIN ANALYZE, rồi trả về báo cáo migration nào cần thêm index cho bảng orders và inventory. Chạy song song 5-6 migration files cùng lúc nhờ tính chất isolate của subagents.

"Fix Typo" Agent cho Content Writers

Team content của Zalo OA cần sửa lỗi chính tả hàng loạt file Markdown trước khi publish. Tạo agent content-fix với allowedTools: Read, Edit (không có Bash để tránh xóa nhầm), model Haiku cho nhanh. Họ chỉ cần nói: "Sửa lỗi 'nhà phát triẻn' thành 'nhà phát triển' và 'công nghệ thôn tin' thành 'công nghệ thông tin' trong folder /blog". Agent chạy riêng, không ảnh hưởng đến session chính của developer đang làm việc.

Ứng dụng

Developer độc lập (Freelancer/Indie hacker) Dùng custom agent để parallelize cognitive load. Ví dụ: đang refactor frontend ở main session, nhờ agent "backend-checker" kiểm tra xem API có breaking changes không khiến app Shopee affiliate của bạn bị lỗi. Hai tác vụ chạy song song thay vì tuần tự, giảm thời gian deliver 40-60%.

Tech Lead/Senior Engineer Tạo fleet of reviewers: 4 agents chạy đồng thời trên cùng một PR — agent A tìm security, agent B check performance, agent C verify test coverage, agent D review architecture. Mỗi agent trả về summary ngắn, bạn chỉ cần synthesize thay vì đọc từng dòng code. Đây là pattern "9 parallel subagents" cộng đồng đang áp dụng để giải quyết bottleneck review ở các startup VN đang scale nhanh.

Non-coder/Product Manager Dùng agent để delegate research. Ví dụ: cần hiểu codebase cũ của hệ thống CRM công ty trước khi viết spec, nhưng không muốn "bẩn" context hiện tại bằng hàng chục file legacy code viết bằng Laravel từ 2019. Spawn "code-archaeologist" agent chỉ để explore và vẽ sơ đồ dependency, trong khi PM giữ main session sạch để viết PRD.

Doanh nghiệp/Team lớn Chuẩn hóa agent trong ./.claude/agents/ để đảm bảo mọi developer tuân thủ quy trình. Ví dụ: "pre-commit-security" agent tự động chạy trước khi cho phép commit, hoặc "api-contract-validator" kiểm tra mọi PR có cập nhật OpenAPI spec không — rất hữu ích cho các ngân hàng đang chuyển đổi số cần tuân thủ nghiêm ngặt API governance.

So sánh

Kết luận: Agent phù hợp khi bạn cần cognitive isolation — tách biệt suy nghĩ để tránh nhiễu. Skill phù hợp cho khuôn mẫu (templates) và automation lặp lại. MCP là cầu nối ra thế giới bên ngoài. Trong thực tế, bạn thường kết hợp: Custom agent sử dụng MCP để truy vấn DB, và trigger bằng Skill.

Bài viết liên quan

Cùng cụm:

• Subagents là gì? 6 built-in agents giải thích - Hiểu cơ chế context isolation và cách Claude quyết định delegate
• Agent tools và permissions - Chi tiết về allowlist, denylist và model override cho từng agent
• Agent Memory - Cách subagents lưu trữ và truy xuất thông tin qua user/project/local scope
• 10 Agent mẫu - Code-reviewer, debugger, test-engineer... các pattern sẵn có để copy

Đọc tiếp:

• Agent Teams - Chạy nhiều Claude song song với --teammate-mode, vượt qua giới hạn "không có inter-agent communication" của single session
• Tự động Code Review - Áp dụng custom agent vào CI/CD pipeline với /loop và GitHub Actions