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

Mở đầu: Mỗi lần review code, bạn đều viết lại cùng một checklist

1. Có input validation ở boundary không?
2. Query SQL có bị N+1 không?
3. Secret hay credential có bị commit vào code không?
4. Error handling có bắt đúng những edge case quan trọng không?
5. Test coverage cho logic mới có đủ không?

Bạn làm việc này mỗi tuần, cho mỗi PR. Đã mấy năm rồi.

Và mỗi lần dùng Claude Code để review, bạn đều paste lại cùng một đoạn instruction dài cả chục dòng: "Hãy review code với các tiêu chí sau..." Mất 2-3 phút mỗi lần, và nếu hôm nay bạn paste thiếu một tiêu chí, Claude sẽ miss đúng cái đó.

Sẽ thế nào nếu bạn có thể "đóng gói" toàn bộ checklist đó thành một nhân vật tên là code-quality-reviewer, và chỉ cần nói với Claude "review PR này" — Claude sẽ tự biết gọi đúng nhân vật đó, với đúng instruction, đúng tool, đúng mức độ nghiêm khắc?

Đó chính là subagent. Bài này sẽ dạy bạn tạo subagent đầu tiên từ 0, cấu hình nó đúng cách, và test nó trước khi tin tưởng giao việc.

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:

• 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.

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

┌─────────────────────────────────────────────────┐
│  .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. ...                                    │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

Đ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ờ.

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õ:

/agents

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:

What should this subagent do?

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

Make a subagent that reviews recently written or modified code for quality issues, security vulnerabilities, and compliance with best practices. It should look at changes via git diff and return a structured report.

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

• 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)

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:

┌────────────────────────────────────────────────┐
│  ☐ 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,...)           │
└────────────────────────────────────────────────┘

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:

• 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)

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:

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

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:

---
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 ...]

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:

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

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: |
  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>

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ờ:

• 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.

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.

Ví dụ theo ngành

📝 Về các case studies dưới đây: Đây là pattern minh hoạ mô tả cách subagent có thể được cấu hình cho từng ngành. Số liệu "Kết quả" là ước lượng illustrative — không phải đo lường từ customer cụ thể. Mục đích là giúp bạn hình dung shape của setup, không phải benchmark cam kết.

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):

• 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ể.

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):

• Đượ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.

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):

• 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.

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):

• 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.

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 é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

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>

2. Code reviewer (pre-merge)

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.

3. Documentation updater

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.

4. Copywriting / tone transformation

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.

5. Migration / schema validator

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:

description: Use this agent to review code.

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 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]

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:

• 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

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:

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

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 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

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:

• 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

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:

description: Use this agent for code review.

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.

Á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:

Create a subagent that reviews recently modified code for quality issues (naming, readability), security risks (injection, secret exposure, auth bypass), and best practice compliance. It should run git diff, read changed files, and return a structured report.

Bước 4: Ở Tool customization:

• 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)

Bước 5

Model → sonnet. Color → bất kỳ.

Bước 6

Mở file .claude/agents/code-quality-reviewer.md. Ghi vào sổ:

• 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: ___________

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:

Review the code I just changed.

Bước 3: Quan sát:

• 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?

Bước 4: Ghi lại:

• 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: ___________

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).

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:

• 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

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.

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

Tài liệu tham khảo

• Anthropic: Claude Code subagents documentation
• Slash command reference: /agents trong Claude Code
• Example config: .claude/agents/ trong repo của bạn