Agent của Claude Code là gì

Trang này giải thích khái niệm agent trong Claude Code, rồi đi qua một ví dụ cụ thể: khi kích hoạt một agent của My Agent Kit, nó đọc gì, dùng gì, và làm việc thế nào để hoàn thành nhiệm vụ.

Agent của Claude Code là gì

1. Khái niệm: agent là một “Claude con” có giới hạn

Một agent (còn gọi là subagent) là một phiên Claude riêng, được khởi chạy bởi Claude chính để làm một việc cụ thể. Nó không phải một con người ảo — nó là cùng model Claude, nhưng chạy với:

Thành phần	Ý nghĩa
System prompt riêng	“tính cách” + quy trình — định nghĩa trong file `.claude/agents/<tên>.md`
Context window riêng	sạch — không thấy lịch sử hội thoại của Claude chính
Bộ tool giới hạn	chỉ những tool ghi trong frontmatter `tools:` — ví dụ `code-reviewer` không có `Edit` nên không sửa được code
Model riêng	`opus` / `sonnet` / `haiku` — chọn theo độ khó của việc
Memory scope	`project` hoặc `user` — quyết định nó nhớ gì giữa các phiên

Vì sao tách agent? Hai lý do. (1) Context isolation — mỗi agent nhận brief gọn, không bị nhiễu bởi 200 tin nhắn trước đó → kết quả ổn định hơn. (2) Quyền tối thiểu — agent review code không có quyền sửa code, agent test chỉ sở hữu file test. Giới hạn tool = giới hạn rủi ro.

┌─────────────── Claude chính (orchestrator) ───────────────┐
│  Đọc yêu cầu, quyết định ủy thác việc gì cho agent nào     │
│                                                            │
│   Task(planner) ──▶┐                                       │
│                    │  agent chạy trong context window      │
│                    │  riêng, trả về 1 bản tóm tắt           │
│   Task(fullstack-  │                                       │
│         developer) │◀─ kết quả ─┐                          │
│                    │            │                          │
└────────────────────┴────────────┴──────────────────────────┘
        agent KHÔNG nói chuyện trực tiếp với user —
        chỉ Claude chính thấy kết quả và báo lại

2. Một agent gồm những gì

File .claude/agents/fullstack-developer.md (rút gọn):

---
name: fullstack-developer
description: Execute implementation phases from parallel plans...
model: sonnet
tools: Glob, Grep, Read, Edit, MultiEdit, Write, Bash, WebFetch, ...
---

You are a Senior Full-Stack Engineer executing precise implementation
plans. You write production-grade code on first pass...

## Behavioral Checklist
- [ ] Error handling: every async operation has explicit handling
- [ ] Input validation at boundaries
- [ ] Build passes before reporting complete
...

Phần	Vai trò
`name`	định danh — Claude chính gọi bằng tên này
`description`	Claude chính đọc cái này để quyết định khi nào dùng agent
`model`	engine chạy agent (`fullstack-developer` dùng `sonnet`)
`tools`	whitelist tool agent được phép gọi
Phần body	system prompt — quy trình, checklist, ràng buộc agent phải theo

3. 14 agent của My Agent Kit

Agent	Model	Có `Edit`?	Vai trò
`planner`	opus	✏️	spec → `plan.md` + phase files
`fullstack-developer`	sonnet	✏️	viết code thực tế (BE/FE/infra)
`code-simplifier`	sonnet	✏️	dọn code, giữ nguyên hành vi
`tester`	haiku	✏️ (chỉ file test)	viết & chạy test
`code-reviewer`	—	❌ chỉ đọc	quality gate trước merge
`researcher`	haiku	❌ chỉ đọc	tra cứu, tổng hợp nhiều nguồn
`debugger`	sonnet	✏️	điều tra bug / CI đỏ
`git-manager`	—	—	commit/push an toàn
`ui-ux-designer`	—	—	thiết kế UX trước khi code
`docs-manager`	—	✏️	quản lý tài liệu
`brainstormer`	—	—	mở rộng ý tưởng
`project-manager`	—	—	điều phối nhiều phase
`journal-writer`	—	✏️	ghi nhật ký phát triển
`mcp-manager`	—	—	quản lý MCP server

Để ý code-reviewer và researcher không có Edit/Write — chúng chỉ đọc và báo cáo. Đó là thiết kế cố ý: reviewer không được tự “sửa” cái nó review, tránh nó vừa viết vừa chấm điểm chính mình.

4. Ví dụ: kích hoạt `fullstack-developer` — nó làm gì từng bước

Tình huống: bạn gõ /mk:cook "thêm endpoint POST /api/todos". Sau khi planner đã tạo phase file, Claude chính ủy thác phase implement cho fullstack-developer.

Bước 0 — Claude chính giao việc

Claude chính gọi tool Task với một brief tự chứa (không kèm lịch sử chat):

Task(fullstack-developer):
  "Implement Phase 2 từ plans/250522-todos/phase-2-api.md.
   File ownership: src/routes/todos.ts, src/db/todos.ts.
   Spec: phần 'POST /api/todos' trong docs/api-spec.md."

Bước 1 — Agent khởi động trong context sạch

Agent đọc system prompt của chính nó (fullstack-developer.md) → biết nó là “Senior Full-Stack Engineer”, phải qua Behavioral Checklist trước khi báo xong. Body agent có dòng:

IMPORTANT: Follow rules in .claude/rules/development-rules.md IMPORTANT: Activate relevant skills from .claude/skills/*

→ nên việc đầu tiên agent làm là đọc tài liệu nền.

Bước 2 — Agent ĐỌC gì

Đọc	Bằng tool	Để làm gì
`plans/.../phase-2-api.md`	`Read`	biết chính xác phải làm gì, file nào được sửa
`docs/api-spec.md`	`Read`	hiểu contract của endpoint
`.claude/rules/development-rules.md`	`Read`	coding convention của kit
`.claude/skills/cook/SKILL.md`	`Read`	kỷ luật implement code
code hiện có quanh `src/routes/`	`Grep` / `Glob`	khớp style, không phá pattern sẵn có

Bước 3 — Agent DÙNG gì để làm việc

Dùng	Tool	Khi nào
Định vị code liên quan	`Grep`, `Glob`	trước khi sửa — tránh đoán
Tra API thư viện hiện tại	`WebFetch` (qua skill `docs-seeker`)	thay vì đoán API theo trí nhớ
Viết / sửa file	`Write`, `Edit`, `MultiEdit`	chỉ file trong “File Ownership”
Chạy build / typecheck / test	`Bash`	tự kiểm tra trước khi báo xong
Cập nhật trạng thái phase	`TaskUpdate`	cho orchestrator theo dõi tiến độ

Bước 4 — Agent tự kiểm trước khi báo xong

Trước khi kết thúc, agent chạy lại Behavioral Checklist của chính nó: error handling đủ chưa, có validate input ở biên chưa, build có pass không, có để TODO chặn correctness không, có sửa nhầm file ngoài ownership không.

Bước 5 — Agent trả kết quả về Claude chính

Agent không nói với user. Nó trả một bản tóm tắt về Claude chính:

✓ Phase 2 done.
  - src/routes/todos.ts: thêm handler POST /api/todos (validate body, 400 nếu sai)
  - src/db/todos.ts: thêm insertTodo()
  - npm run build: pass · npm test: 4 pass
  - Không đụng file ngoài ownership.

Claude chính nhận tóm tắt này, rồi tự verify lại (chạy lại build/test — nguyên tắc trust but verify), sau đó mới chuyển sang agent kế trong chain (code-simplifier → tester → code-reviewer).

planner ──▶ fullstack-developer ──▶ code-simplifier ──▶ tester ──▶ code-reviewer
  (bạn vừa xem con này) ▲

5. Agent vs Skill — đừng nhầm

	Agent	Skill
Là gì	người làm — một phiên Claude	kiến thức/quy trình — một file `.md`
Có context riêng?	Có	Không — chỉ là tài liệu được nạp vào
Viết code?	Có (nếu có tool `Edit`)	Không bao giờ
Ví dụ	`fullstack-developer`	`cook`, `mk:plan`, `docs-seeker`

Một câu để nhớ: agent làm, skill là cái agent đọc theo khi làm. Code luôn do một agent viết, không phải do skill.

Chi tiết cách phối hợp: Lõi bất biến.

Xem thêm

Workflow Guides — chọn agent/skill theo loại project
Lõi bất biến — chuỗi 5 agent đầy đủ
Rules of thumb — nguyên tắc dùng agent