Tạo subagent đầu tiên của bạn

Subagent custom là gì?

Về mặt kỹ thuật, một subagent custom trong Claude Code là một file markdown có YAML frontmatter đặt trong thư mục .claude/agents/. File này chứa 2 phần:

Cấu trúc tổng thể của một file config:

Điều hay là bạn không cần tự viết file này từ đầu. Claude Code có trình tạo tự động giúp bạn, ta sẽ dùng nó ngay bây giờ.

• Frontmatter (metadata): Cho Claude biết subagent này tên gì, khi nào nên dùng, được phép dùng tool gì, chạy trên model nào.
• Body (system prompt): Chỉ dẫn chi tiết subagent phải làm gì và báo cáo kết quả ra sao.

┌─────────────────────────────────────────────────┐
│  .claude/agents/code-quality-reviewer.md        │
├─────────────────────────────────────────────────┤
│  ┌─ YAML frontmatter ────────────────────────┐  │
│  │  name:        code-quality-reviewer       │  │
│  │  description: Use this agent when...      │  │
│  │  tools:       Bash, Grep, Read, ...       │  │
│  │  model:       sonnet                       │  │
│  │  color:       purple                       │  │
│  └───────────────────────────────────────────┘  │
│                                                 │
│  ┌─ System prompt (markdown body) ───────────┐  │
│  │                                            │  │
│  │  You are an expert code reviewer...        │  │
│  │  Your role is to examine recently          │  │
│  │  written code and identify...              │  │
│  │                                            │  │
│  │  Provide your review in this format:       │  │
│  │  1. Summary                                │  │
│  │  2. Critical Issues                        │  │
│  │  3. Major Issues                           │  │
│  │  4. ...                                    │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

3 cách để tạo subagent

Trong bài này ta tập trung vào cách /agents + AI generate. Đây cũng là cách Anthropic recommend cho đa số người dùng.

Ví dụ thực chiến: Tạo code-quality-reviewer từ 0

Ta sẽ tạo một subagent chuyên review chất lượng code và phát hiện lỗ hổng bảo mật. Đi qua từng bước.

Bước 1: Mở panel quản lý subagent

Trong Claude Code, gõ:

Panel này là trung tâm điều khiển cho mọi subagent trong project của bạn. Bạn sẽ thấy danh sách subagent hiện có (nếu có) và option Create new agent.

Bước 2: Chọn scope — Project-level hay User-level?

Đây là câu hỏi đầu tiên Claude Code hỏi:

Quy tắc thực tế: Nếu subagent encode convention của team (review checklist, deployment gate, PR template), chọn project-level. Nếu nó là thói quen cá nhân (cách bạn thích viết commit message, template note Obsidian), chọn user-level.

Với code-quality-reviewer — ta muốn cả team reviewer cùng tiêu chuẩn, nên chọn Project-level.

Bước 3: Để AI generate config

Lựa chọn tiếp theo: viết config thủ công hay để Claude Code tự generate.

Claude Code sẽ hỏi bạn một câu đơn giản kiểu:

Bạn mô tả bằng 1-3 câu, càng cụ thể càng tốt. Ví dụ:

Claude sẽ dùng input đó để generate:

Bước 4: Customize tool access

Đây là bước quan trọng nhất mà người mới thường bỏ qua. Claude Code sẽ liệt kê 5 nhóm tool:

Nguyên tắc vàng: only give what the subagent needs.

Với code reviewer — nó cần đọc code và chạy git diff, nhưng không được phép edit (vì đó là việc của human sau khi đã review). Nên:

Giới hạn tool không chỉ tránh accident (reviewer không thể vô tình sửa code khi đang phân tích), mà còn làm vai trò subagent rõ ràng hơn với bạn và team.

Bước 5: Chọn model

Với code-quality-reviewer → chọn sonnet. Code review cần reasoning nhưng không cần sâu như audit bảo mật toàn hệ thống.

Bước 6: Chọn màu và confirm

Cuối cùng, chọn một màu (purple, blue, green, ...). Màu này hiển thị trong UI để bạn dễ nhận ra subagent nào đang chạy khi có nhiều subagent trong project.

Claude Code lưu file vào:

• Một name (slug, unique identifier)
• Một description (chỉ dẫn cho main agent biết khi nào nên gọi subagent này)
• Một system prompt (toàn bộ chỉ dẫn cho subagent)
• ✅ Read-only: Glob, Grep, Read
• ✅ Execution: Bash (để git diff)
• ❌ Edit tools: không cần
• ❌ MCP tools: không cần (trừ khi bạn có MCP chuyên về security)

┌────────────────────────────────────────────────┐
│  ☐ Read-only tools    (Glob, Grep, Read)       │
│  ☐ Edit tools         (Edit, Write, MultiEdit) │
│  ☐ Execution tools    (Bash, BashOutput)       │
│  ☐ MCP tools          (các tool từ MCP server) │
│  ☐ Other tools        (TodoWrite, WebSearch,   │
│                        WebFetch,...)           │
└────────────────────────────────────────────────┘

/agents

Bước 6: Chọn màu và confirm

Bước 7: Mở file config xem Claude đã viết gì

Đây là lúc bạn kiểm tra và chỉnh sửa. Một config điển hình:

.claude/agents/code-quality-reviewer.md

Bước 7: Mở file config xem Claude đã viết gì

Hãy đi qua từng field:

Bước 8: Thêm từ "proactively" nếu muốn Claude tự gọi

Mặc định Claude sẽ gọi subagent khi bạn explicitly nói "review code này" hoặc "chạy code-quality-reviewer". Nếu bạn muốn Claude tự gọi sau mỗi lần sửa code đáng kể, thêm từ "proactively" vào description:

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. Examples:\n<example>Context: User just finished implementing a new feature.\nuser: 'I've added the checkout endpoint'\nassistant: 'Let me run code-quality-reviewer on the changes.'</example>
tools: Bash, Glob, Grep, Read
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.

When invoked:
1. Run `git diff` to see what changed.
2. Read the modified files to understand full context.
3. Analyze against the criteria below.

[... continue with criteria and output format ...]

Bước 8: Thêm từ "proactively" nếu muốn Claude tự gọi

Từ khóa "proactively" là tín hiệu Claude đã được train để nhận ra — nó tăng tần suất tự gọi subagent.

Bước 9: Thêm example conversations (bước upgrade quan trọng)

Claude quyết định dùng subagent nào dựa trên description. Nhưng mô tả thuần túy ("Use this for code review") nhiều khi quá mơ hồ. Ví dụ hội thoại cụ thể giúp Claude hiểu rõ hơn:

description: Proactively review any code changes for quality issues...

Bước 9: Thêm example conversations (bước upgrade quan trọng)

Quy tắc: thêm 2-3 example thực tế thay vì viết description lý thuyết. Claude học từ pattern tốt hơn từ rule.

Kết quả

Bạn vừa tạo xong subagent code-quality-reviewer. Giờ:

Thời gian tiết kiệm (minh hoạ): Từ "paste 10 dòng instruction mỗi lần review" → "chỉ cần gõ 'review'". Bonus chính không phải tốc độ, mà consistency: subagent không quên criteria nào kể cả khi bạn mệt.

• Trong Claude Code, thử sửa một file bất kỳ, rồi gõ: "Review these changes."
• Claude sẽ tự nhận ra pattern và gọi code-quality-reviewer trong một context window riêng biệt.
• Kết quả trả về là một report có cấu trúc, main session của bạn không bị đầy bởi 15 file mà subagent đã đọc.

description: |
  Use this agent when you need to review code for quality and security. Examples:
  <example>
  Context: User has just finished implementing a new feature.
  user: 'I just finished implementing the checkout endpoint'
  assistant: 'I'll run code-quality-reviewer on the changes.'
  </example>
  <example>
  Context: Pre-merge check.
  user: 'Ready to merge PR #123'
  assistant: 'Before merging, let me have code-quality-reviewer look at the diff.'
  </example>

Ví dụ theo ngành

🛠️ Engineering — Test Writer subagent

Trước: "Mỗi lần implement feature mới, tôi viết 3-4 unit test. Nhưng team review hay complain test của tôi miss edge case. Tôi lại phải viết lại."

Với subagent test-writer (tools: Read, Write, Bash):

📊 Data Engineering — Migration Validator subagent

Trước: "Mỗi lần viết migration SQL, tôi phải nhớ check: có lock bảng lâu không, có backfill default đúng không, có rollback plan không. Cứ sót thì Friday deploy panic."

Với subagent migration-validator (tools: Read, Grep, Bash):

📣 Marketing — Tone Checker subagent

Trước: "Brand guideline của công ty dài 30 trang. Mỗi content writer hiểu một kiểu. Copy lên landing page nhiều khi lạc tone."

Với subagent brand-tone-checker (tools: Read, Grep):

⚖️ Legal — Contract Clause Auditor

Trước: "Mỗi contract vendor mới, legal team phải đối chiếu với template chuẩn. 3 tiếng/hợp đồng."

Với subagent clause-auditor (tools: Read, Glob; model: opus):

⚙️ DevOps — Deployment Checker subagent

Trước: "Trước mỗi prod deploy, SRE phải chạy qua checklist 12 mục: DB migration ran? Env var set? Feature flag status? Canary plan?..."

Với subagent deploy-precheck (tools: Bash, Read, Grep):

• System prompt chỉ rõ: "Cho mỗi function public, viết test cho: happy path, invalid input, boundary values, empty collection, concurrency-safe nếu applicable."
• Output format ép subagent liệt kê từng case trước khi viết code.
• Kết quả minh hoạ: Số case coverage tăng rõ vì subagent không quên check list, review rounds giảm đáng kể.
• Được giao chỉ đọc file trong db/migrations/
• System prompt: "Check 5 risks: lock duration, NOT NULL add on non-empty table, missing default, no rollback, order-dependent FK change."
• Kết quả minh hoạ: Team nhận ra các migration risky sớm hơn, thay vì đến Friday deploy mới panic.
• System prompt load 1 số snippet example "approved copy" và "rejected copy"
• Description: "Use proactively on any .md or .mdx file in /content/ before publishing."
• Kết quả minh hoạ: Phần lớn tone issue được bắt trước khi lên Head of Marketing — rút chu kỳ approval xuống còn một-hai vòng thay vì qua lại nhiều lần.
• System prompt yêu cầu: "So sánh contract với template ở /legal/templates/vendor-master.md. Flag mọi clause khác biệt, phân loại Critical/Material/Minor."
• Kết quả minh hoạ: Lawyer không cần đọc toàn bộ hợp đồng từ đầu — chỉ review list clause đã flag, tập trung vào Critical. Thời gian review rút ngắn rõ rệt.
• System prompt ép đi qua 12 checkpoint, mỗi cái có cách verify cụ thể (grep log, curl health endpoint,...)
• Output có "Obstacles Encountered" section (sẽ học ở Bài 16.2)
• Kết quả minh hoạ: SRE thay vì chạy tay 12 check, chỉ cần đọc report do subagent sinh ra — tiết kiệm đáng kể thời gian pre-deploy.

Prompt mẫu: 5 template description sẵn dùng

Khi AI-generate config, bạn có thể paste gợi ý description dạng template. Dưới đây là 5 pattern đã được test.

1. Research / Read-only agent

2. Code reviewer (pre-merge)

Use this agent proactively for read-only research tasks. It should explore
the codebase to answer specific questions without modifying any files.
Examples:
<example>user: "How does our auth flow work?" → launch research-agent</example>

Prompt mẫu: 5 template description sẵn dùng (tiếp)

3. Documentation updater

Use this agent to review recently changed or staged code for quality,
security, and best practice compliance. Must tell the agent precisely
which files to review. Return structured report with severity levels.

Prompt mẫu: 5 template description sẵn dùng (tiếp)

4. Copywriting / tone transformation

Use this agent when code changes affect public API or user-facing docs.
It should read changed files, locate related docs, and draft updates.
Does not commit — only proposes edits for human review.

Prompt mẫu: 5 template description sẵn dùng (tiếp)

5. Migration / schema validator

Use this agent for creating or editing marketing copy. Tone: friendly,
benefit-led, not technical. Audience: non-engineer decision makers.
Structure: hook, 3 key benefits, CTA. Return final draft only.

Prompt mẫu: 5 template description sẵn dùng (tiếp)

Use this agent proactively after any file in /db/migrations/ is edited.
Check for: lock duration, nullable-to-not-null on non-empty tables,
default value correctness, rollback completeness. Report severity per risk.

Anti-patterns — Những sai lầm khi tạo subagent

❌ Description quá vague

Hiện tượng:

Tại sao là sai: Claude sẽ hoặc không gọi (quá generic), hoặc gọi sai tình huống. "Review code" ứng với 100 scenario khác nhau.

Cách đúng: Description cụ thể về khi nào và với input gì:

description: Use this agent to review code.

❌ Description quá vague

❌ Grant "full tools" theo mặc định

Hiện tượng: Khi prompt hỏi tool, bạn tick All vì "cho chắc".

Tại sao là sai:

Cách đúng: Chỉ grant tool subagent thực sự cần. Nếu role là "phân tích + báo cáo", loại Edit/Write ngay từ đầu.

❌ Copy system prompt từ ChatGPT "You are an expert ___"

Hiện tượng:

• Reviewer vô tình edit file → chaos
• Subagent role bị blur, bạn không biết nó làm gì khác ngoài nhiệm vụ chính
• Khó debug khi output không như mong đợi

description: |
  Use this agent to review recently modified code (via git diff) for quality
  and security. You MUST tell the agent precisely which files to review.
  Examples: [2-3 ví dụ concrete]

❌ Copy system prompt từ ChatGPT "You are an expert ___"

Tại sao là sai: Claude đã có kiến thức expert Python. Prompt dạng "claim expertise" không thêm capability nào — ngược lại khiến subagent "diễn vai" thay vì tập trung vào format output bạn cần. (Xem sâu hơn ở Bài 16.3.)

Cách đúng: Prompt phải cho biết task cụ thể, output format, criteria. Ví dụ:

You are an expert Python developer with 20 years of experience.
Analyze this code for me.

Anti-patterns — Những sai lầm khi tạo subagent (tiếp)

❌ Quên test trước khi tin tưởng

Hiện tượng: Tạo xong subagent, push config lên git, pair với CI hook, đi ăn trưa.

Tại sao là sai: Subagent chưa được test với edge case. Vài ngày sau team complain "reviewer bỏ qua SQL injection" — ra là description thiếu keyword, hoặc system prompt thiếu instruction check auth.

Cách đúng: Sau khi tạo, test ít nhất 3 lần với input thực:

❌ Chọn sai scope (project vs user)

Hiện tượng: Tạo subagent theo convention của team X nhưng chọn user-level, → bị gọi khi đang làm ở project team Y (không cùng convention).

Cách đúng: Nếu subagent encode team convention, project-level. Cá nhân cross-project, user-level. Không chắc → project-level (an toàn hơn, không "rò rỉ" sang project khác).

❌ Không thêm example conversation

Hiện tượng: Description chỉ là lý thuyết:

• 1 lần với code clean → reviewer approve
• 1 lần với code có bug cố ý → reviewer flag đúng
• 1 lần với edge case (file rất dài, multi-language) → reviewer vẫn structured

You review code for bugs and security issues.
When invoked:
1. Run `git diff`
2. Read modified files
3. Return report with sections: Critical / Major / Minor / Recommendations

❌ Không thêm example conversation

Tại sao là sai: Claude hiểu pattern từ example tốt hơn từ rule. Không example → Claude hoặc gọi quá ít, hoặc quá nhiều.

Cách đúng: Thêm 2-3 <example> vào description với context + user message + expected response. Xem sâu ở Bài 16.2.

description: Use this agent for code review.

Áp dụng ngay

Bài tập 1: Tạo code-quality-reviewer đầu tiên (~15 phút)

Bước 1: Mở Claude Code trong một project của bạn (hoặc clone một repo public để thử).

Bước 2: Gõ /agents → Create new agent → Project-level → AI generate.

Bước 3: Khi được hỏi mô tả, paste:

Bước 4: Ở Tool customization:

Bước 5: Model → sonnet. Color → bất kỳ.

Bước 6: Mở file .claude/agents/code-quality-reviewer.md. Ghi vào sổ:

Bài tập 2: Test + debug (~15 phút)

Bước 1: Sửa một file bất kỳ trong project — ví dụ thêm một function có lỗi cố ý (biến chưa dùng, hoặc nhận input không validate).

Bước 2: Trong Claude Code, nói:

Bước 3: Quan sát:

Bước 4: Ghi lại:

Bài tập 3 (thử thách): Nhân bản 1 subagent cho role khác (~20 phút)

Dùng code-quality-reviewer vừa tạo làm starting point, tạo thêm accessibility-reviewer tập trung vào WCAG compliance cho HTML/JSX. Giữ cùng structure output, chỉ đổi criteria.

Compare 2 file .md xem sự khác biệt nằm ở đâu (hầu hết là ở system prompt body, không phải frontmatter).

• ✅ Read-only tools
• ✅ Execution tools (Bash cho git diff)
• ❌ Edit tools
• ❌ MCP tools
• ❌ Other (trừ khi bạn muốn nó web search for CVE)
• Tên field nào bạn thấy khó hiểu nhất: ___________
• Phần system prompt có bao nhiêu dòng: ___________
• Claude có tự generate example conversations không: ___________
• Claude có gọi code-quality-reviewer không? (Bạn sẽ thấy UI hiển thị subagent đang chạy, màu theo cấu hình của bạn.)
• Nếu không gọi, đó là dấu hiệu description chưa đủ specific. Mở file config, thêm 1 <example> giống case bạn vừa test.
• Nếu gọi, đọc kỹ output. Nó có bắt đúng bug bạn cố ý không? Output có structured không?
• Subagent có được gọi tự động không: Có / Không
• Nếu không, bạn đã sửa gì trong description: ___________
• Bug cố ý có bị flag không: Có / Không
• Format output có dễ đọc không: ___________

Mẹo nâng cao

💡 Mẹo 1: Version control cho subagent project-level

Project-level subagent nằm trong .claude/agents/ được commit vào git. Treat nó như code:

💡 Mẹo 2: Thử haiku cho subagent lặp đi lặp lại

Nếu subagent làm task đơn giản nhưng gọi 100 lần/tuần (ví dụ: "kiểm tra có secret trong diff không"), dùng haiku tiết kiệm token đáng kể mà chất lượng vẫn ổn. Chỉ escalate lên sonnet/opus khi rõ ràng Haiku sai.

💡 Mẹo 3: Đừng tạo subagent cho việc đơn lẻ

Nếu task chỉ làm 1-2 lần, paste prompt trực tiếp nhanh hơn tạo subagent. Subagent xứng đáng đầu tư thời gian chỉ khi bạn sẽ dùng ≥ 10 lần.

• PR review cho thay đổi subagent cũng nghiêm như code
• Write CHANGELOG khi thay đổi criteria (để team biết tiêu chuẩn review đã thay đổi)
• Test subagent sau mỗi major edit — giống unit test cho tool của bạn

Tóm tắt bài học

🎯 Subagent custom = markdown + YAML frontmatter, đặt trong .claude/agents/. Frontmatter định hướng khi nào Claude gọi + tool nào được dùng, body là system prompt điều khiển chất lượng.

🎯 /agents slash command là cách nhanh nhất để tạo, với option AI-generate giúp bạn có draft tốt trong 2 phút.

🎯 Chọn scope đúng: project-level cho team convention, user-level cho thói quen cá nhân cross-project.

🎯 Hạn chế tool access ngay từ đầu — chỉ grant tool subagent thực sự cần. Reviewer không cần Edit. Research không cần Write.

🎯 Test 3 lần trước khi tin tưởng: happy path, bug cố ý, edge case. Nếu subagent không được Claude tự gọi, lỗi thường ở description — thêm example cụ thể sẽ fix.