claude-howto/vi/04-subagents

Tác Nhân Con - Hướng Dẫn Tham Khảo Hoàn Chỉnh

Tác nhân con là các trợ lý AI chuyên biệt mà Claude Code có thể ủy quyền tác vụ. Mỗi tác nhân con có mục đích cụ thể, sử dụng cửa sổ bối cảnh riêng tách biệt với cuộc hội thoại chính, và có thể được cấu hình với các công cụ cụ thể và prompt hệ thống tùy chỉnh.

Mục Lục

1. Tổng Quan
2. Lợi Ích Chính
3. Vị Trí File
4. Cấu Hình
5. Tác Nhân Con Tích Hợp Sẵn
6. Quản Lý Tác Nhân Con
7. Sử Dụng Tác Nhân Con
8. Tác Nhân Có Thể Tiếp Tục
9. Chuỗi Tác Nhân Con
10. Bộ Nhớ Liên Tục Cho Tác Nhân Con
11. Tác Nhân Con Nền
12. Cô Lập Worktree
13. Hạn Chế Tác Nhân Con Có Thể Tạo
14. Lệnh CLI claude agents
15. Đội Tác Nhân (Thử Nghiệm)
16. Bảo Mật Tác Nhân Con Plugin
17. Kiến Trúc
18. Quản Lý Bối Cảnh
19. Khi Nào Sử Dụng Tác Nhân Con
20. Thực Hành Tốt Nhất
21. Ví Dụ Tác Nhân Con Trong Thư Mục Này
22. Hướng Dẫn Cài Đặt
23. Khái Niệm Liên Quan

---

Tổng Quan

Tác nhân con cho phép thực thi tác vụ được ủy quyền trong Claude Code bằng cách:

• Tạo các trợ lý AI cô lập với các cửa sổ bối cảnh riêng
• Cung cấp các prompt hệ thống tùy chỉnh cho chuyên môn chuyên biệt
• Thực thi kiểm soát truy cập công cụ để giới hạn khả năng
• Ngăn ô nhiễm bối cảnh từ các tác vụ phức tạp
• Cho phép thực thi song song của nhiều tác vụ chuyên biệt

Mỗi tác nhân con hoạt động độc lập với một trang sạch, chỉ nhận bối cảnh cụ thể cần thiết cho tác vụ của họ, sau đó trả về kết quả cho tác nhân chính để tổng hợp.

Bắt Đầu Nhanh: Sử dụng lệnh /agents để tạo, xem, chỉnh sửa, và quản lý các tác nhân con của bạn một cách tương tác.

---

Lợi Ích Chính

Lợi Ích	Mô Tả
Bảo tồn bối cảnh	Hoạt động trong bối cảnh riêng, ngăn ngắt ô nhiễm cuộc hội thoại chính
Chuyên môn hóa	Điều chỉnh tốt cho các lĩnh vực cụ thể với tỷ lệ thành công cao hơn
Khả năng tái sử dụng	Sử dụng qua các dự án khác và chia sẻ với các đội
Quyền linh hoạt	Các mức truy cập công cụ khác nhau cho các loại tác nhân con khác
Khả năng mở rộng	Nhiều tác nhân hoạt động trên các khía cạnh khác nhau đồng thời

---

Vị Trí File

Files tác nhân con có thể được lưu trữ ở nhiều vị trí với các phạm vi khác nhau:

Ưu Tiên	Loại	Vị Trí	Phạm Vi
1 (cao nhất)	Được định nghĩa qua CLI	Qua cờ --agents (JSON)	Chỉ phiên
2	Tác nhân dự án	.claude/agents/	Dự án hiện tại
3	Tác nhân người dùng	~/.claude/agents/	Tất cả dự án
4 (thấp nhất)	Tác nhân plugin	Thư mục agents/ của plugin	Qua plugins

Khi tên trùng lặp tồn tại, nguồn ưu tiên cao hơn sẽ được ưu tiên.

---

Cấu Hình

Định Dạng File

Tác nhân con được định nghĩa trong YAML frontmatter theo sau là prompt hệ thống trong markdown:

---
name: your-sub-agent-name
description: Mô tả khi nào tác nhân con này nên được gọi
tools: tool1, tool2, tool3  # Tùy chọn - kế thừa tất cả công cụ nếu bỏ qua
disallowedTools: tool4  # Tùy chọn - công cụ rõ ràng không được phép
model: sonnet  # Tùy chọn - sonnet, opus, haiku, hoặc inherit
permissionMode: default  # Tùy chọn - chế độ quyền
maxTurns: 20  # Tùy chọn - giới hạn lượt tác nhân
skills: skill1, skill2  # Tùy chọn - skills để tải trước vào bối cảnh
mcpServers: server1  # Tùy chọn - MCP servers để cung cấp
memory: user  # Tùy chọn - phạm vi bộ nhớ liên tục (user, project, local)
background: false  # Tùy chọn - chạy như tác vụ nền
effort: high  # Tùy chọn - nỗ lực lý luận (low, medium, high, max)
isolation: worktree  # Tùy chọn - cô lập git worktree
initialPrompt: "Bắt đầu bằng cách phân tích codebase"  # Tùy chọn - lượt đầu tự động gửi
hooks:  # Tùy chọn - hooks theo phạm vi component
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

Prompt hệ thống của tác nhân con của bạn ở đây. Nhiều có thể là nhiều đoạn
và nên xác định rõ vai trò, khả năng, và cách tiếp cận
của tác nhân con để giải quyết vấn đề.

Các Trường Cấu Hình

Trường	Bắt Buộc	Mô Tả
name	Có	Định danh duy nhất (chữ thường và dấu gạch ngang)
description	Có	Mô tả ngôn ngữ của mục đích. Bao gồm "use PROACTIVELY" để khuyến khích gọi tự động
tools	Không	Danh sách phân tách bằng dấu phẩy của các công cụ cụ thể. Bỏ qua để kế thừa tất cả công cụ. Hỗ trợ cú pháp Agent(agent_name) để hạn chế tác nhân con có thể tạo
disallowedTools	Không	Danh sách phân tách bằng dấu phẩy của các công cụ mà tác nhân con không được sử dụng
model	Không	Mô hình để sử dụng: sonnet, opus, haiku, ID mô hình đầy đủ, hoặc inherit. Mặc định là mô hình tác nhân con được cấu hình
permissionMode	Không	default, acceptEdits, dontAsk, bypassPermissions, plan
maxTurns	Không	Số lượng lượt tác nhân tối đa mà tác nhân con có thể thực hiện
skills	Không	Danh sách phân tách bằng dấu phẩy của các skills để tải trước. Tiêm toàn bộ nội dung skill vào bối cảnh của tác nhân con khi khởi động
mcpServers	Không	MCP servers để cung cấp cho tác nhân con
hooks	Không	Hooks theo phạm vi component (PreToolUse, PostToolUse, Stop)
memory	Không	Phạm vi thư mục bộ nhớ liên tục: user, project, hoặc local
background	Không	Đặt thành true để luôn chạy tác nhân con này như một tác vụ nền
effort	Không	Mức độ nỗ lực lý luận: low, medium, high, hoặc max
isolation	Không	Đặt thành worktree để cung cấp cho tác nhân con git worktree riêng
initialPrompt	Không	Lượt đầu tự động gửi khi tác nhân con chạy như tác nhân chính

Tùy Chọn Cấu Hình Công Cụ

Tùy Chọn 1: Kế Thừa Tất Cả Công Cụ (bỏ qua trường)

---
name: full-access-agent
description: Agent với tất cả các công cụ có sẵn
---

Tùy Chọn 2: Chỉ Định Các Công Cụ Cụ Thể

---
name: limited-agent
description: Agent với các công cụ cụ thể chỉ
tools: Read, Grep, Glob, Bash
---

Tùy Chọn 3: Truy Cập Công Cụ Có Điều Kiện

---
name: conditional-agent
description: Agent với truy cập công cụ được lọc
tools: Read, Bash(npm:*), Bash(test:*)
---

Cấu Hình Dựa Trên CLI

Định nghĩa tác nhân con cho một phiên duy nhất sử dụng cờ --agents với định dạng JSON:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Định Dạng JSON cho cờ --agents:

{
  "agent-name": {
    "description": "Required: khi nào gọi agent này",
    "prompt": "Required: prompt hệ thống cho agent",
    "tools": ["Optional", "array", "of", "tools"],
    "model": "optional: sonnet|opus|haiku"
  }
}

Ưu Tiên Định Nghĩa Tác Nhân:

Các định nghĩa tác nhân được tải với thứ tự ưu tiên này (khớp đầu tiên thắng):

1. Được định nghĩa qua CLI - cờ --agents (phiên chỉ, JSON)
2. Cấp dự án - .claude/agents/ (dự án hiện tại)
3. Cấp người dùng - ~/.claude/agents/ (tất cả dự án)
4. Cấp plugin - Thư mục agents/ của plugin

Điều này cho phép định nghĩa CLI ghi đè tất cả các nguồn khác cho một phiên duy nhất.

---

Tác Nhân Con Tích Hợp Sẵn

Claude Code bao gồm một số tác nhân con được tích hợp sẵn luôn có sẵn:

Tác Nhân	Mô Hình	Mục Đích
general-purpose	Kế thừa	Tác vụ đa bước phức tạp
Plan	Kế thừa	Nghiên cứu cho chế độ lập kế hoạch
Explore	Haiku	Khám phá codebase chỉ đọc (nhanh/trung bình/rất kỹ)
Bash	Kế thừa	Lệnh terminal trong bối cảnh riêng
statusline-setup	Sonnet	Cấu hình dòng trạng thái
Claude Code Guide	Haiku	Trả lời câu hỏi về tính năng Claude Code

Tác Nhân General-Purpose

Thuộc Tính	Giá Trị
Mô Hình	Kế thừa từ cha
Công Cụ	Tất cả công cụ
Mục Đích	Nhiệm vụ nghiên cứu phức tạp, hoạt động đa bước, chỉnh sửa code

Khi sử dụng: Tác vụ yêu cầu cả khám phá và sửa đổi với lý luận phức tạp.

Tác Nhân Plan

Thuộc Tính	Giá Trị
Mô Hình	Kế thừa từ cha
Công Cụ	Read, Glob, Grep, Bash
Mục Đích	Được sử dụng tự động trong chế độ lập kế hoạch để nghiên cứu codebase

Khi sử dụng: Khi Claude cần hiểu codebase trước khi trình bày kế hoạch.

Tác Nhân Explore

Thuộc Tính	Giá Trị
Mô Hình	Haiku (nhanh, độ trễ thấp)
Chế Độ	Chỉ đọc nghiêm ngặt
Công Cụ	Glob, Grep, Read, Bash (chỉ lệnh đọc)
Mục Đích	Tìm kiếm và phân tích codebase nhanh

Khi sử dụng: Khi tìm kiếm/hiểu code mà không thực hiện thay đổi.

Mức Độ Chuyên Sâu - Chỉ định độ sâu của khám phá:

• "quick" - Tìm kiếm nhanh với khám phá tối thiểu, tốt để tìm các mẫu cụ thể
• "medium" - Khám phá vừa phải, cân bằng tốc độ và sự kỹ lưỡng, cách tiếp cận mặc định
• "very thorough" - Phân tích toàn diện qua nhiều vị trí và quy ước đặt tên, có thể mất nhiều thời gian hơn

Tác Nhân Bash

Thuộc Tính	Giá Trị
Mô Hình	Kế thừa từ cha
Công Cụ	Bash
Mục Đích	Thực thi các lệnh terminal trong một cửa sổ bối cảnh riêng

Khi sử dụng: Khi chạy các lệnh shell hưởng lợi từ bối cảnh cô lập.

Tác Nhân Cấu Trình Dòng Trạng Thái

Thuộc Tính	Giá Trị
Mô Hình	Sonnet
Công Cụ	Read, Write, Bash
Mục Đích	Cấu hình hiển thị dòng trạng thái Claude Code

Khi sử dụng: Khi thiết lập hoặc tùy chỉnh dòng trạng thái.

Tác Nhân Hướng Dẫn Claude Code

Thuộc Tính	Giá Trị
Mô Hình	Haiku (nhanh, độ trễ thấp)
Công Cụ	Chỉ đọc
Mục Đích	Trả lời câu hỏi về tính năng và cách sử dụng Claude Code

Khi sử dụng: Khi người dùng hỏi về cách Claude Code hoạt động hoặc cách sử dụng các tính năng cụ thể.

---

Quản Lý Tác Nhân Con

Sử Dụng Lệnh /agents (Khuyến Nghị)

/agents

Điều này cung cấp menu tương tác để:

• Xem tất cả các tác nhân con có sẵn (tích hợp, người dùng, và dự án)
• Tạo các tác nhân con mới với thiết lập có hướng dẫn
• Chỉnh sửa các tác nhân con tùy chỉnh hiện có và truy cập công cụ
• Xóa các tác nhân con tùy chỉnh
• Xem các tác nhân con nào đang hoạt động khi có bản sao trùng lặp

Quản Lý File Trực Tiếp

# Tạo một tác nhân dự án
mkdir -p .claude/agents
cat > .claude/agents/test-runner.md << 'EOF'
---
name: test-runner
description: Use proactively to run tests and fix failures
---

You are a test automation expert. When you see code changes, proactively
run the appropriate tests. If tests fail, analyze the failures and fix
them while preserving the original test intent.
EOF

# Tạo một tác nhân người dùng (có sẵn trong tất cả dự án)
mkdir -p ~/.claude/agents

---

Sử Dụng Tác Nhân Con

Ủy Quy Tự Động

Claude chủ động ủy quyền các tác vụ dựa trên:

• Mô tả tác vụ trong yêu cầu của bạn
• Trường description trong cấu hình tác nhân con
• Bối cảnh hiện tại và các công cụ có sẵn

Để khuyến khích sử dụng chủ động, bao gồm "use PROACTIVELY" hoặc "MUST BE USED" trong trường description của bạn:

---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after writing or modifying code.
---

Gọi Rõ Ràng

Bạn có thể yêu cầu một tác nhân con cụ thể một cách rõ ràng:

> Use the test-runner subagent to fix failing tests
> Have the code-reviewer subagent look at my recent changes
> Ask the debugger subagent to investigate this error

Gọi Với @-Mention

Sử dụng tiền tố @ để đảm bảo một tác nhân con cụ thể được gọi (bỏ qua các heuristic ủy quyền tự động):

> @"code-reviewer (agent)" review the auth module

Tác Nhân Toàn Phiên

Chạy toàn bộ phiên sử dụng một tác nhân cụ thể như tác nhân chính:

# Qua cờ CLI
claude --agent code-reviewer

# Qua settings.json
{
  "agent": "code-reviewer"
}

Liệt Kê Các Tác Nhân Có Sẵn

Sử dụng lệnh claude agents để liệt kê tất cả các tác nhân được cấu hình từ tất cả các nguồn:

claude agents

---

Tác Nhân Có Thể Tiếp Tục

Tác nhân con có thể tiếp tục các cuộc hội thoại trước đó với toàn bộ bối cảnh được bảo tồn:

# Lời gọi ban đầu
> Use the code-analyzer agent to start reviewing the authentication module
# Returns agentId: "abc123"

# Tiếp tục tác nhân sau đó
> Resume agent abc123 and now analyze the authorization logic as well

Trường hợp sử dụng:

• Nghiên cứu dài chạy qua nhiều phiên
• Tinh chỉnh lặp lại mà không mất bối cảnh
• Workflow đa bước duy trì bối cảnh

---

Chuỗi Tác Nhân Con

Thực hiện nhiều tác nhân con theo trình tự:

> First use the code-analyzer subagent to find performance issues,
  then use the optimizer subagent to fix them

Điều này cho phép các workflow phức tạp nơi đầu ra của một tác nhân con được truyền vào tác nhân khác.

---

Bộ Nhớ Liên Tục Cho Tác Nhân Con

Trường memory cung cấp cho tác nhân con một thư mục liên tục tồn tại qua các cuộc hội thoại. Điều này cho phép tác nhân con xây dựng kiến thức theo thời gian, lưu trữ ghi chú, phát hiện, và bối cảnh tồn tại giữa các phiên.

Các Phạm Vi Bộ Nhớ

Phạm Vi	Thư Mục	Trường Hợp Dùng
user	~/.claude/agent-memory/<name>/	Ghi chú và tùy thích cá nhân qua tất cả dự án
project	.claude/agent-memory/<name>/	Kiến thức cụ thể dự án được chia sẻ với đội
local	.claude/agent-memory-local/<name>/	Kiến thức dự án cục bộ không được commit vào kiểm soát phiên bản

Cách Hoạt Động

• 200 dòng đầu tiên của MEMORY.md trong thư mục bộ nhớ được tự động tải vào prompt hệ thống của tác nhân con
• Các công cụ Read, Write, và Edit được tự động bật cho tác nhân con để quản lý các file bộ nhớ của nó
• Tác nhân con có thể tạo các file bổ sung trong thư mục bộ nhớ của mình khi cần

Ví Dụ Cấu Hình

---
name: researcher
memory: user
---

You are a research assistant. Use your memory directory to store findings,
track progress across sessions, and build up knowledge over time.

Check your MEMORY.md file at the start of each session to recall previous context.

graph LR
    A["Subagent<br/>Session 1"] -->|writes| M["MEMORY.md<br/>(persistent)"]
    M -->|loads into| B["Subagent<br/>Session 2"]
    B -->|updates| M
    M -->|loads into| C["Subagent<br/>Session 3"]

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#e1f5fe,stroke:#333,color:#333
    style C fill:#e1f5fe,stroke:#333,color:#333
    style M fill:#f3e5f5,stroke:#333,color:#333

---

Tác Nhân Con Nền

Tác nhân con có thể chạy trong nền, giải phóng cuộc hội thoại chính cho các tác vụ khác.

Cấu Hình

Đặt background: true trong frontmatter để luôn chạy tác nhân con như một tác vụ nền:

---
name: long-runner
background: true
description: Performs long-running analysis tasks in the background
---

Phím Tắt Nhan

Phím Tắt	Hành Động
Ctrl+B	Chạy nền một tác vụ tác nhân con đang chạy
Ctrl+F	Giết tất cả các tác nhân nền (nhấn hai lần để xác nhận)

Vô Hiệu hóa Tác Vụ Nền

Đặt biến môi trường để vô hiệu hóa hỗ trợ tác vụ nền hoàn toàn:

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

---

Cô Lập Worktree

Thiết lập isolation: worktree cung cấp cho tác nhân con git worktree riêng, cho phép nó thực hiện các thay đổi một cách độc lập mà không ảnh hưởng đến cây làm việc chính.

Cấu Hình

---
name: feature-builder
isolation: worktree
description: Implements features in an isolated git worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

Cách Hoạt Động

graph TB
    Main["Main Working Tree"] -->|spawns| Sub["Subagent with<br/>Isolated Worktree"]
    Sub -->|makes changes in| WT["Separate Git<br/>Worktree + Branch"]
    WT -->|no changes| Clean["Auto-cleaned"]
    WT -->|has changes| Return["Returns worktree<br/>path and branch"]

    style Main fill:#e1f5fe,stroke:#333,color:#333
    style Sub fill:#f3e5f5,stroke:#333,color:#333
    style WT fill:#e8f5e9,stroke:#333,color:#333
    style Clean fill:#fff3e0,stroke:#333,color:#333
    style Return fill:#fff3e0,stroke:#333,color:#333

• Tác nhân con hoạt động trong git worktree của nó trên một nhánh riêng
• Nếu tác nhân con không thực hiện thay đổi, worktree được tự động dọn dẹp
• Nếu có thay đổi, đường dẫn worktree và tên nhánh được trả về cho tác nhân chính để xem xét hoặc hợp nhất

---

Hạn Chế Tác Nhân Con Có Thể Tạo

Bạn có thể kiểm soát các tác nhân con mà một tác nhân con cho phép tạo bằng cách sử dụng cú pháp Agent(agent_type) trong trường tools. Điều này cung cấp một cách để cho phép danh sách các tác nhân con cụ thể cho ủy quyền.

Lưu ý: Trong v2.1.63, công cụ Task đã được đổi tên thành Agent. Các tham chiếu Task(...) hiện có vẫn hoạt động như bí danh.

Ví Dụ

---
name: coordinator
description: Coordinates work between specialized agents
tools: Agent(worker, researcher), Read, Bash
---

You are a coordinator agent. You can delegate work to the "worker" and
"researcher" subagents only. Use Read and Bash for your own exploration.

Trong ví dụ này, tác nhân con coordinator chỉ có thể tạo các tác nhân con worker và researcher. Nó không thể tạo bất kỳ tác nhân con nào khác, ngay cả khi chúng được định nghĩa ở nơi khác.

---

Lệnh CLI claude agents

Lệnh claude agents liệt kê tất cả các tác nhân được cấu hình được nhóm theo nguồn (tích hợp, cấp người dùng, cấp dự án):

claude agents

Lệnh này:

• Hiển thị tất cả các tác nhân có sẵn từ tất cả các nguồn
• Nhóm các tác nhân theo vị trí nguồn của chúng
• Chỉ định ghi đè khi một tác nhân ở mức ưu tiên cao hơn che một tác nhân ở mức thấp hơn (ví dụ: tác nhân cấp dự án với cùng tên như tác nhân cấp người dùng)

---

Đội Tác Nhân (Thử Nghiệm)

Agent Teams điều phối nhiều phiên Claude Code hoạt động cùng nhau trên các tác vụ phức tạp. Không giống tác nhân con (được ủy quyền subtask và trả về kết quả), đồng nghiệp hoạt động độc lập với bối cảnh của riêng và giao tiếp trực tiếp qua hệ thống mailbox chia sẻ.

Lưu ý: Agent Teams là thử nghiệm và yêu cầu Claude Code v2.1.32+. Bật trước khi sử dụng.

Subagents vs Agent Teams

Khía Cát	Subagents	Agent Teams
Mô hình ủy quyền	Cha ủy quyền subtask, đợi kết quả	Trưởng đội chỉ định công việc, đồng nghiệp thực thi độc lập
Bối cảnh	Bối cảnh mới cho mỗi subtask, kết quả được chắt ngắn lại	Mỗi đồng nghiệp duy trì bối cảnh liên tục riêng
Sự điều phối	Tuần tự hoặc song song, được quản lý bởi cha	Danh sách việc chia sẻ với quản lý dependency tự động
Giao tiếp	Chỉ giá trị trả về	Nhắn tin liên-tác tác nhân qua mailbox
Tiếp tục phiên	Được hỗ trợ	Không được hỗ trợ với đồng nghiệp trong quá trình
Tốt nhất cho	Subtask được xác định rõ, tốt	Các dự án đa file lớn yêu cầu làm việc song song

Bật Agent Teams

Đặt biến môi trường hoặc thêm vào settings.json của bạn:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Hoặc trong settings.json:

{
  "env": {
    "CLAUDE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Bắt đầu một đội

Sau khi bật, yêu cầu Claude làm việc với đồng nghiệp trong prompt của bạn:

User: Build the authentication module. Use a team — one teammate for the API endpoints,
      one for the database schema, and one for the test suite.

Claude sẽ tạo đội, chỉ định tác vụ, và điều phối công việc tự động.

Chế độ hiển thị

Kiểm soát cách hiển thị hoạt động của đồng nghiệp:

Chế Độ	Cờ	Mô Tả
Auto	--teammate-mode auto	Tự động chọn chế độ hiển thị tốt nhất cho terminal của bạn
In-process	--teammate-mode in-process	Hiển thị đầu ra đồng nghiệp nội tuyến trong terminal hiện tại (mặc định)
Split-panes	--teammate-mode tmux	Mỗi đồng nghiệp trong một pane tmux hoặc iTerm2 riêng

claude --teammate-mode tmux

Bạn cũng có thể đặt chế độ hiển thị trong settings.json:

{
  "teammateMode": "tmux"
}

Lưu ý: Chế độ split-pane yêu cầu tmux hoặc iTerm2. Nó không có sẵn trong terminal VS Code, Windows Terminal, hoặc Ghostty.

Điều hướng

Sử dụng Shift+Down để điều hướng giữa các đồng nghiệp trong chế độ split-pane.

Cấu hình đội

Cấu hình đội được lưu trữ tại ~/.claude/teams/{team-name}/config.json.

Kiến Trúc

graph TB
    Lead["Team Lead<br/>(Coordinator)"]
    TaskList["Shared Task List<br/>(Dependencies)"]
    Mailbox["Mailbox<br/>(Messages)"]
    T1["Teammate 1<br/>(Own Context)"]
    T2["Teammate 2<br/>(Own Context)"]
    T3["Teammate 3<br/>(Own Context)"]

    Lead -->|assigns tasks| TaskList
    Lead -->|sends messages| Mailbox
    TaskList -->|picks up work| T1
    TaskList -->|picks up work| T2
    TaskList -->|picks up work| T3
    T1 -->|reads/writes| Mailbox
    T2 -->|reads/writes| Mailbox
    T3 -->|reads/writes| Mailbox
    T1 -->|updates status| TaskList
    T2 -->|updates status| TaskList
    T3 -->|updates status| TaskList

    style Lead fill:#e1f5fe,stroke:#333,color:#333
    style TaskList fill:#fff9c4,stroke:#333,color:#333
    style Mailbox fill:#f3e5f5,stroke:#333,color:#333
    style T1 fill:#e8f5e9,stroke:#333,color:#333
    style T2 fill:#e8f5e9,stroke:#333,color:#333
    style T3 fill:#e8f5e9,stroke:#333,color:#333

Thành phần chính:

• Team Lead: Phiên Claude Code chính tạo đội, chỉ định tác vụ, và điều phối
• Shared Task List: Danh sách tác vụ được đồng bộ hóa với theo dõi dependency tự động
• Mailbox: Hệ thống nhắn tin liên-tác nhân để đồng nghiệp giao tiếp trạng thái và điều phối
• Teammates: Các phiên Claude Code độc lập, mỗi phiên với cửa sổ bối cảnh riêng

Giao việc và lập kế hoạch tác vụ

Đội trưởng chia nhỏ công việc thành các tác vụ và chỉ định chúng cho đồng nghiệp. Danh sách việc chia sẻ xử lý:

• Quản lý dependency tự động — các tác vụ chờ các dependency của chúng hoàn thành
• Theo dõi trạng thái — đồng nghiệp cập nhật trạng thái tác vụ khi họ làm việc
• Nhắn tin liên-tác nhân — đồng nghiệp gửi tin qua mailbox để điều phối (ví dụ: "Database schema is ready, you can start writing queries")

Quy trình phê duyệt kế hoạch

Đối với các tác vụ phức tạp, đội trưởng tạo một kế hoạch thực thi trước khi đồng nghiệp bắt đầu làm việc. Người dùng xem xét và phê duyệt kế hoạch, đảm bảo cách tiếp cận của đội phù hợp với kỳ vọng trước bất kỳ thay đổi code nào.

Sự kiện hook cho đội

Agent Teams giới thiệu hai sự kiện hook bổ sung:

Sự Kiện	Kích Hoạt Khi	Trường Hợp Dùng
TeammateIdle	Một đồng nghiệp hoàn thành tác vụ hiện tại và không có công việc đang chờ	Kích hoạt thông báo, chỉ định tác vụ tiếp theo
TaskCompleted	Một tác vụ trong danh sách việc chia sẻ được đánh dấu hoàn thành	Chạy xác nhận, cập nhật dashboards, chuỗi công việc phụ thuộc

Thực hành tốt nhất

• Kích thước đội: Giữ đội ở mức 3-5 đồng nghiệp để điều phối tối ưu
• Kích thước tác vụ: Chia việc thành các tác vụ mất 5-15 phút mỗi tác — đủ nhỏ để song song hóa, đủ lớn để có ý nghĩa
• Tránh xung đột file: Gán các file hoặc thư mục khác nhau cho các đồng nghiệp khác nhau để ngăn xung đột merge
• Bắt đầu đơn giản: Sử dụng chế độ in-process cho đội đầu tiên của bạn; chuyển sang split-panes khi thoải mái
• Mô tả tác vụ rõ ràng: Cung cấp mô tả tác vụ cụ thể, có thể hành động để đồng nghiệp có thể làm việc độc lập

Hạn Chế

• Thử nghiệm: Hành vi tính năng có thể thay đổi trong các phiên bản tương lai
• Không tiếp tục phiên: Đồng nghiệp trong quá trình không thể được tiếp tục sau khi phiên kết thúc
• Một đội mỗi phiên: Không thể tạo các đội lồng nhau hoặc nhiều đội trong một phiên
• Lãnh đạo cố định: Vai trò đội trưởng không thể chuyển cho đồng nghiệp
• Hạn chế split-pane: Yêu cầu tmux/iTerm2; không có sẵn trong terminal VS Code, Windows Terminal, hoặc Ghostty
• Không có đội đa phiên: Đồng nghiệp chỉ tồn tại trong phiên hiện tại

Cảnh báo: Agent Teams là thử nghiệm. Thử nghiệm với công việc không quan trọng trước và giám sát điều phối đồng nghiệp cho hành vi bất ngờ.

---

Bảo Mật Tác Nhân Con Plugin

Tác nhân con do plugin cung cấp có các khả năng frontmatter bị hạn chế để bảo mật. Các trường sau không được phép trong định nghĩa tác nhân con plugin:

• hooks - Không thể định nghĩa lifecycle hooks
• mcpServers - Không thể cấu hình MCP servers
• permissionMode - Không thể ghi đè cài đặt quyền

Điều này ngăn chặn plugins nâng cao đặc quyền hoặc thực thi các lệnh tùy ý qua hooks tác nhân con.

---

Kiến Trúc

Kiến Trúc Cấp Cao

graph TB
    User["User"]
    Main["Main Agent<br/>(Coordinator)"]
    Reviewer["Code Reviewer<br/>Subagent"]
    Tester["Test Engineer<br/>Subagent"]
    Docs["Documentation<br/>Subagent"]

    User -->|asks| Main
    Main -->|delegates| Reviewer
    Main -->|delegates| Tester
    Main -->|delegates| Docs
    Reviewer -->|returns result| Main
    Tester -->|returns result| Main
    Docs -->|returns result| Main
    Main -->|synthesizes| User

Vòng Đời Tác Nhân Con

sequenceDiagram
    participant User
    participant MainAgent as Main Agent
    participant CodeReviewer as Code Reviewer<br/>Subagent
    participant Context as Separate<br/>Context Window

    User->>MainAgent: "Build new auth feature"
    MainAgent->>MainAgent: Analyze task
    MainAgent->>CodeReviewer: "Review this code"
    CodeReviewer->>Context: Initialize clean context
    Context->>CodeReviewer: Load reviewer instructions
    CodeReviewer->>CodeReviewer: Perform review
    CodeReviewer-->>MainAgent: Return findings
    MainAgent->>MainAgent: Incorporate results
    MainAgent-->>User: Provide synthesis

---

Quản Lý Bối Cảnh

graph TB
    A["Main Agent Context<br/>50,000 tokens"]
    B["Subagent 1 Context<br/>20,000 tokens"]
    C["Subagent 2 Context<br/>20,000 tokens"]
    D["Subagent 3 Context<br/>20,000 tokens"]

    A -->|Clean slate| B
    A -->|Clean slate| C
    A -->|Clean slate| D

    B -->|Results only| A
    C -->|Results only| A
    D -->|Results only| A

    style A fill:#e1f5fe
    style B fill:#fff9c4
    style C fill:#fff9c4
    style D fill:#fff9c4

Điểm Chính

• Mỗi tác nhân con nhận một cửa sổ bối cảnh mới mà không có lịch sử hội thoại chính
• Chỉ bối cảnh liên quan được truyền cho tác nhân con cho tác vụ cụ thể của họ
• Kết quả được chắt ngắn trở lại tác nhân chính
• Điều này ngăn hết token bối cảnh trên các dự án dài

Cân Nhắc Hiệu Suất

• Hiệu quả bối cảnh - Tác nhân bảo toàn bối cảnh chính, cho phép các phiên dài hơn
• Độ trễ - Tác nhân con bắt đầu với trang sạch và có thể thêm độ trễ khi thu thập bối cảnh ban đầu

Hành Vi Chính

• Không tạo lồng nhau - Tác nhân con không thể tạo các tác nhân con khác
• Quyền nền - Tác nhân con nền tự động từ chối bất kỳ quyền nào không được phê duyệt trước
• Chạy nền - Nhấn Ctrl+B để chạy nền một tác vụ đang chạy
• Bản ghi - Bản ghi tác nhân con được lưu tại ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl
• Tự động nén - Bối cảnh tác nhân con tự động nén ở ~95% dung lượng (ghi đè qua biến môi trường CLAUDE_AUTOCOMPACT_PCT_OVERRIDE)

---

Khi Nào Sử Dụng Tác Nhân Con

Tình Huống	Sử Dụng Tác Nhân	Tại Sao
Tính năng phức tạp với nhiều bước	Có	Tách biệt mối quan tâm, ngăn ô nhiễm bối cảnh
Review code nhanh	Không	Chi phí không cần thiết
Thực thi tác vụ song song	Có	Mỗi tác nhân con có bối cảnh riêng
Cần chuyên môn hóa	Có	Prompt hệ thống tùy chỉnh
Phân tích dài chạy	Có	Ngăn cạn bối cảnh chính
Tác vụ đơn	Không	Thêm độ trễ không cần thiết

---

Thực Hành Tốt Nhất

Nguyên Tắc Thiết Kế

Nên Làm:

• Bắt đầu với tác nhân do Claude tạo - Tạo tác nhân ban đầu với Claude, sau đó lặp để tùy chỉnh
• Thiết kế tác nhân con tập trung - Một trách nhiệm rõ ràng thay vì một làm mọi thứ
• Viết prompt chi tiết - Bao gồm hướng dẫn cụ thể, ví dụ, và ràng buộc
• Giới hạn truy cập công cụ - Chỉ cấp các công cụ cần thiết cho mục đích của tác nhân con
• Kiểm soát phiên bản - Kiểm tra các tác nhân dự án vào kiểm soát phiên bản để hợp tác đội

Không Nên:

• Tạo các tác nhân con chồng lấp với cùng vai trò
• Cung cấp cho tác nhân con quyền truy cập công cụ không cần thiết
• Sử dụng tác nhân con cho các tác vụ đơn giản, một bước
• Trộn lẫn mối quan tâm trong prompt của một tác nhân con
• Quên chuyển bối cảnh cần thiết

Thực Hành Prompt Hệ Thống Tốt Nhất

1. Cụ Thể Về Vai Trò

   Bạn là một chuyên gia review code chuyên về [các lĩnh vực cụ thể]
   

2. Xác Định Ưu Tiên Rõ Ràng

   Review ưu tiên (theo thứ):
   1. Vấn Đề Bảo Mật
   2. Vấn Đề Hiệu Suất
   3. Chất Lượng Code
   

3. Chỉnh Định Định Dạng Đầu Ra

   Với mỗi vấn đề cung cấp: Mức Độ, Danh Mục, Vị Trí, Mô Tả, Sửa, Tác Động
   

4. Bao Gồm Các Bước Hành Động

   Khi được gọi:
   1. Chạy git diff để xem các thay đổi gần đây
   2. Tập trung vào các file đã sửa đổi
   3. Bắt đầu review ngay lập tức
   

Chiến Lược Truy Cập Công Cụ

1. Bắt Đầu Hạn Chế: Bắt đầu chỉ với các công cụ thiết yếu
2. Mở Rộng Chỉ Khi Cần: Thêm công cụ khi yêu cầu đòi hỏi
3. Chỉ Đọc Khi Có Thể: Sử dụng Read/Grep cho các tác nhân phân tích
4. Thực Thi Trong Sandbox: Giới hạn các lệnh Bash cho các mẫu cụ thể

---

Ví Dụ Tác Nhân Con Trong Thư Mục Này

Thư mục này chứa các ví dụ tác nhân con đã sẵn sàng sử dụng:

1. Code Reviewer (code-reviewer.md)

Mục Đích: Phân tích chất lượng và khả năng duy trì code toàn diện

Công Cụ: Read, Grep, Glob, Bash

Chuyên Môn Hóa:

• Phát hiện lỗ hổng bảo mật
• Xác định cơ hội tối ưu hóa hiệu suất
• Đánh giá khả năng duy trì
• Phân tích phủ vùng test

Sử Dụng Khi: Bạn cần review code tự động với tập trung vào chất lượng và bảo mật

---

2. Test Engineer (test-engineer.md)

Mục Đích: Chiến lược test, phân tích phủ vùng, và testing tự động

Công Cụ: Read, Write, Bash, Grep

Chuyên Môn Hóa:

• Tạo unit test
• Thiết kế test tích hợp
• Xác định các trường hợp ngoại lệ
• Phân tích phủ vùng (>80% mục tiêu)

Sử Dụng Khi: Bạn cần tạo bộ test toàn diện hoặc phân tích phủ vùng

---

3. Documentation Writer (documentation-writer.md)

Mục Đích: Tài liệu kỹ thuật, tài liệu API, và hướng dẫn người dùng

Công Cụ: Read, Write, Grep

Chuyên Môn Hóa:

• Tài liệu hóa endpoint API
• Tạo hướng dẫn người dùng
• Tài liệu hóa kiến trúc
• Cải thiện chú thích code

Sử Dụng Khi: Bạn cần tạo hoặc cập nhật tài liệu dự án

---

4. Secure Reviewer (secure-reviewer.md)

Mục Đích: Review code tập trung vào bảo mật với quyền tối thiểu

Công Cụ: Read, Grep

Chuyên Môn Hóa:

• Phát hiện lỗ hổng bảo mật
• Vấn đề xác thực/uỷ quyền
• Rủi ro lộ dữ liệu
• Xác định các cuộc tấn công tiêm nhiễm

Sử Dụng Khi: Bạn cần các audit bảo mật mà không có khả năng sửa đổi

---

5. Implementation Agent (implementation-agent.md)

Mục Đích: Khả năng triển khai đầy đủ cho phát triển tính năng

Công Cụ: Read, Write, Edit, Bash, Grep, Glob

Chuyên Môn Hóa:

• Triển khai tính năng
• Tạo code
• Thực thi build và test
• Sửa đổi codebase

Sử Dụng Khi: Bạn cần một tác nhân con để triển khai tính năng từ đầu đến cuối

---

6. Debugger (debugger.md)

Mục Đích: Chuyên gia debug cho lỗi, thất bại test, và hành vi bất ngờ

Công Cụ: Read, Edit, Bash, Grep, Glob

Chuyên Môn Hóa:

• Phân tích nguyên nhân gốc
• Điều tra lỗi
• Giải quyết thất bại test
• Triển khai sửa tối thiểu

Sử Dụng Khi: Bạn gặp bugs, lỗi, hoặc hành vi bất ngờ

---

7. Data Scientist (data-scientist.md)

Mục Đích: Chuyên gia phân tích dữ liệu cho các truy vấn SQL và thông tin dữ liệu

Công Cụ: Bash, Read, Write

Chuyên Môn Hóa:

• Tối ưu hóa truy vấn SQL
• Hoạt động BigQuery
• Phân tích và hình ảnh hóa dữ liệu
• Thông tin thống kê

Sử Dụng Khi: Bạn cần phân tích dữ liệu, truy vấn SQL, hoặc hoạt động BigQuery

---

Hướng Dẫn Cài Đặt

Phương Pháp 1: Sử Dụng Lệnh /agents (Khuyến Nghị)

/agents

Sau đó:

1. Chọn 'Create New Agent'
2. Chọn cấp dự án hoặc cấp người dùng
3. Mô tả tác nhân con của bạn chi tiết
4. Chọn các công cụ để cấp quyền truy cập (hoặc bỏ trống để kế thừa tất cả)
5. Lưu và sử dụng

Phương Pháp 2: Sao Chép Vào Dự Án

Sao chép các file tác nhân vào thư mục .claude/agents/ của dự án của bạn:

# Điều hướng đến dự án của bạn
cd /path/to/your/project

# Tạo thư mục agents nếu chưa tồn tại
mkdir -p .claude/agents

# Sao chép tất cả file agent từ thư mục này
cp /path/to/04-subagents/*.md .claude/agents/

# Xóa README (không cần trong .claude/agents)
rm .claude/agents/README.md

Phương Pháp 3: Sao Chép Vào Thư Mục Người Dùng

Đối với các tác nhân có sẵn trong tất cả các dự án của bạn:

# Tạo thư mục agents người dùng
mkdir -p ~/.claude/agents

# Sao chép các tác nhân
cp /path/to/04-subagents/code-reviewer.md ~/.claude/agents/
cp /path/to/04-subagents/debugger.md ~/.claude/agents/
# ... sao chép những cái khác khi cần

Xác Minh

Sau khi cài đặt, xác minh các tác nhân được nhận diện:

/agents

Bạn sẽ thấy các tác nhân đã cài của bạn được liệt kê cùng với các tác nhân được tích hợp sẵn.

---

Cấu Trúc File

project/
├── .claude/
│   └── agents/
│       ├── code-reviewer.md
│       ├── test-engineer.md
│       ├── documentation-writer.md
│       ├── secure-reviewer.md
│       ├── implementation-agent.md
│       ├── debugger.md
│       └── data-scientist.md
└── ...

---

Khái Niệm Liên Quan

Tính Năng Liên Quan

• Lệnh Slash - Các lối tắt do người dùng gọi
• Bộ Nhớ - Bối cảnh liên tục qua phiên
• Skills - Khả năng tự động có thể tái sử dụng
• Giao Thức MCP - Truy cập dữ liệu bên ngoài thời gian thực
• Hooks - Tự động hóa lệnh shell dựa trên sự kiện
• Plugins - Các gói tiện ích mở rộng

So Sánh Với Tính Năng Khác

Tính Năng	Do Người Dùng Gọi	Tự Động Gọi	Liên Tục	Truy Cấp Bên Ngoài	Bối Cảnh Cô Lập
Lệnh Slash	Có	Không	Không	Không	Không
Tác Nhân Con	Có	Có	Không	Không	Có
Bộ Nhớ	Tự động	Tự động	Có	Không	Không
MCP	Tự động	Có	Không	Có	Không
Skills	Có	Có	Không	Không	Không

Mẫu Tích Hợp

graph TD
    User["User Request"] --> Main["Main Agent"]
    Main -->|Uses| Memory["Memory<br/>(Context)"]
    Main -->|Queries| MCP["MCP<br/>(Live Data)"]
    Main -->|Invokes| Skills["Skills<br/>(Auto Tools)"]
    Main -->|Delegates| Subagents["Subagents<br/>(Specialists)"]

    Subagents -->|Use| Memory
    Subagents -->|Query| MCP
    Subagents -->|Isolated| Context["Clean Context<br/>Window"]

---

Tài Nguyên Thêm

• Tài Liệu Tác Nhân Con Chính Thức
• Tham Khảo CLI - Cờ --agents và các tùy chọn CLI khác
• Hướng Dẫn Plugins - Để gói tác nhân với các tính năng khác
• Hướng Dẫn Skills - Đối các khả năng tự động gọi
• Hướng Dẫn Bộ Nhớ - Đối bối cảnh liên tục
• Hướng Dẫn Hooks - Đối tự động hóa dựa trên sự kiện

---

Cập nhật lần cuối: Tháng 3 năm 2026

Hướng dẫn này bao gồm cấu hình tác nhân con hoàn chỉnh, các mẫu ủy quyền, và thực hành tốt nhất cho Claude Code.