Subagents

Subagent là các AI assistant chuyên biệt xử lý một loại việc cụ thể. Dùng subagent khi một việc phụ - nếu làm trực tiếp - sẽ “ngập” hội thoại chính bằng kết quả tìm kiếm, log, hay nội dung file mà bạn không cần xem lại: subagent làm việc đó trong ngữ cảnh riêng và chỉ trả về phần tóm tắt. Nên định nghĩa một subagent riêng khi bạn thấy mình liên tục giao cùng một loại việc với cùng một bộ chỉ dẫn.

Mỗi subagent chạy trong cửa sổ ngữ cảnh riêng, với system prompt, quyền dùng tool và quyền hạn (permission) độc lập. Khi Claude gặp một việc khớp với mô tả của subagent, nó giao việc cho subagent đó; subagent làm việc độc lập rồi trả kết quả về.

Subagent giúp bạn:

Giữ sạch ngữ cảnh chính - việc tìm hiểu/triển khai nằm ngoài hội thoại chính.
Ép buộc giới hạn - kiểm soát chặt tool nào subagent được dùng.
Tái sử dụng cấu hình giữa các dự án nhờ subagent cấp người dùng.
Chuyên biệt hoá hành vi bằng system prompt riêng cho từng vai trò.
Tiết kiệm chi phí bằng cách định tuyến việc sang model rẻ, nhanh hơn (ví dụ Haiku).

Claude dựa vào trường description của subagent để quyết định khi nào giao việc - mô tả càng rõ, Claude càng biết đúng lúc cần dùng.

Subagent có sẵn

Claude Code đã tích hợp sẵn vài subagent, tự động dùng khi phù hợp. Mỗi subagent kế thừa quyền hạn của hội thoại cha; hầu hết chạy với tập tool bị giới hạn.

Riêng Explore và Plan bỏ qua các file CLAUDE.md và git status của phiên cha để giữ tốc độ tìm hiểu nhanh, rẻ. Mọi subagent khác - cả built-in lẫn tự định nghĩa - đều nạp cả hai (xem phần những gì được nạp khi khởi động).

Explore - agent chỉ đọc, tối ưu cho tìm kiếm/phân tích codebase.

Model: kế thừa từ hội thoại chính, giới hạn trần ở Opus trên Claude API (nên Explore không bao giờ chạy model đắt hơn model bạn đang dùng cho phiên). Trên nền tảng khác (Bedrock, Foundry…), Explore kế thừa trực tiếp model của hội thoại chính.
Tool: chỉ tool chỉ đọc; Write và Edit bị chặn.
Nếu bạn tự định nghĩa một subagent tên Explore (cấp dự án/người dùng), nó sẽ ghi đè bản built-in và giữ nguyên trường model riêng - hữu ích nếu muốn ép Explore luôn chạy Haiku cho rẻ.
Khi gọi Explore, Claude chỉ định mức độ kỹ lưỡng: quick (tra cứu nhanh), medium (cân bằng), hoặc very thorough (phân tích toàn diện).

Plan - agent nghiên cứu dùng trong plan mode để thu thập ngữ cảnh trước khi trình bày kế hoạch.

Model: kế thừa từ hội thoại chính.
Tool: chỉ tool chỉ đọc; Write và Edit bị chặn.

general-purpose - agent đa năng cho việc phức tạp, nhiều bước, cần cả tìm hiểu lẫn chỉnh sửa.

Model: kế thừa từ hội thoại chính.
Tool: toàn bộ tool subagent được dùng (xem Tool khả dụng).

Ngoài ra còn vài agent phụ trợ, thường được gọi tự động:

Agent	Model	Khi Claude dùng
`claude`	Kế thừa	Khi việc không khớp agent chuyên biệt nào - catch-all, có mọi tool subagent có thể dùng. Cũng là agent mặc định cho một background session được dispatch, chạy theo permission mode của cấu hình bạn thay vì của phiên cha
`statusline-setup`	Sonnet	Khi bạn chạy `/statusline` để cấu hình status line
`claude-code-guide`	Haiku	Khi bạn hỏi về tính năng Claude Code

Các subagent built-in được đăng ký mặc định trong phiên tương tác. Để hạn chế:

Chặn một loại built-in cụ thể: thêm vào permissions.deny, xem Vô hiệu hoá subagent cụ thể.
Chặn Claude giao việc cho mọi subagent: từ chối chính tool Agent qua permissions.deny.
Chỉ bỏ Explore và Plan built-in: đặt biến môi trường CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 - Claude sẽ đọc/tìm file trực tiếp thay vì giao việc.
Trong non-interactive mode và Agent SDK: đặt CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 để bỏ toàn bộ built-in, chỉ dùng subagent tự cung cấp.

Ngoài các subagent có sẵn, bạn có thể tạo subagent riêng với prompt tuỳ chỉnh, giới hạn tool, permission mode, hooks, và skills.

Bắt đầu nhanh: tạo subagent đầu tiên

Subagent là file Markdown có frontmatter YAML. Cách nhanh nhất là nhờ Claude viết giúp, hoặc tự viết file.

1. Nhờ Claude tạo subagent - ví dụ mô tả điều bạn muốn và nơi lưu:

Tạo một subagent cá nhân tên code-improver ở ~/.claude/agents/, quét file
và đề xuất cải thiện về khả năng đọc, hiệu năng, best practice. Nó nên
giải thích từng vấn đề, cho xem code hiện tại và bản cải thiện. Chỉ cần
đọc file (không sửa), dùng model Sonnet.

Claude viết ra file với name, description, danh sách tools, model, và system prompt.

2. Xem lại file - mở ~/.claude/agents/code-improver.md, kết quả sẽ giống:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Vì file nằm ở ~/.claude/agents/, subagent khả dụng cho mọi dự án trên máy bạn. Muốn giới hạn trong một dự án, chuyển sang .claude/agents/ của dự án đó (xem Chọn phạm vi).

3. Thử ngay:

Dùng agent code-improver để rà soát dự án này

Claude giao việc cho subagent mới, nó quét codebase và trả về đề xuất cải thiện. Trong transcript, việc giao này hiện thành một dòng tool call ghi tên subagent kèm mô tả ngắn, ví dụ code-improver (Suggest code improvements).

Nếu Claude không tìm thấy subagent mới, khởi động lại Claude Code rồi thử lại - chỉ xảy ra khi ~/.claude/agents/ chưa tồn tại lúc phiên bắt đầu, vì phiên đang chạy không tự phát hiện thư mục agents mới tạo.

Ngoài viết tay, bạn cũng có thể định nghĩa subagent qua CLI flag hoặc phân phối qua plugin - các phần dưới đây bao quát toàn bộ tuỳ chọn cấu hình.

Cấu hình Subagent

Vị trí file quyết định subagent khả dụng cho ai; frontmatter quyết định nó được làm gì.

Chọn phạm vi Subagent

Vị trí	Phạm vi	Độ ưu tiên	Cách tạo
Managed settings	Toàn tổ chức	1 (cao nhất)	Triển khai qua managed settings
Flag CLI `--agents`	Phiên hiện tại	2	Truyền JSON khi khởi động Claude Code
`.claude/agents/`	Dự án hiện tại	3	Nhờ Claude, hoặc tạo file thủ công
`~/.claude/agents/`	Mọi dự án của bạn	4	Nhờ Claude, hoặc tạo file thủ công
Thư mục `agents/` của plugin	Nơi plugin được bật	5 (thấp nhất)	Cài cùng plugin

Khi nhiều subagent trùng tên, Claude Code dùng bản ở vị trí ưu tiên cao hơn.

Subagent cấp dự án (.claude/agents/) phù hợp cho subagent gắn với một codebase cụ thể - nên commit vào git để cả team dùng chung và cải tiến.

Claude Code tìm subagent dự án bằng cách đi ngược từ thư mục làm việc hiện tại lên gốc repo, quét mọi .claude/agents/ gặp trên đường đi. Từ v2.1.178, nếu nhiều thư mục lồng nhau định nghĩa cùng name, Claude Code dùng bản gần thư mục làm việc nhất.

Thư mục thêm bằng --add-dir cũng được quét: một .claude/agents/ bên trong thư mục đó nạp cùng subagent dự án. Muốn chia sẻ subagent giữa các dự án mà không cần --add-dir, dùng ~/.claude/agents/ hoặc một plugin.

Subagent cấp người dùng (~/.claude/agents/) là subagent cá nhân, khả dụng ở mọi dự án.

Claude Code quét đệ quy cả .claude/agents/ và ~/.claude/agents/, nên bạn có thể tổ chức file vào thư mục con như agents/review/ hay agents/research/ - đường dẫn thư mục con không ảnh hưởng cách subagent được nhận diện hay gọi, vì định danh chỉ đến từ trường name.

Giữ giá trị name duy nhất trong toàn bộ cây thư mục: nếu hai file cùng .claude/agents/ (kể cả thư mục con) khai cùng tên, Claude Code chỉ nạp một bản, chọn theo thứ tự đọc filesystem chứ không theo quy tắc ưu tiên rõ ràng. /doctor sẽ báo các file trùng tên trong cùng thư mục và đề xuất đổi tên/xoá bớt.

Thư mục agents/ của plugin cũng được quét đệ quy, nhưng khác với dự án/người dùng: thư mục con ở đây trở thành một phần của định danh có phạm vi - ví dụ file agents/review/security.md trong plugin my-plugin đăng ký thành my-plugin:review:security.

Subagent định nghĩa qua CLI được truyền dưới dạng JSON khi khởi động Claude Code - chỉ tồn tại trong phiên đó, không lưu ra đĩa, hữu ích để test nhanh hoặc script hoá. Có thể định nghĩa nhiều subagent trong một lệnh --agents:

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"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

Flag --agents nhận JSON với các trường frontmatter tương tự subagent dạng file: description, prompt, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, initialPrompt, memory, effort, background, isolation, color. Dùng prompt cho system prompt, tương đương phần thân markdown ở subagent dạng file.

Managed subagent do quản trị viên tổ chức triển khai - đặt file markdown trong .claude/agents/ bên trong thư mục managed settings, cùng định dạng frontmatter với subagent dự án/người dùng. Định nghĩa managed có độ ưu tiên cao hơn dự án và người dùng nếu trùng tên.

Plugin subagent đến từ các plugin bạn đã cài, tự nạp cùng subagent tuỳ chỉnh và hiện trong typeahead @-mention dưới tên có phạm vi.

Định nghĩa subagent từ mọi phạm vi trên cũng khả dụng cho agent teams: khi triệu tập một teammate, bạn có thể tham chiếu một loại subagent và teammate dùng tools/model của nó, với phần thân định nghĩa được nối thêm vào system prompt của teammate.

Viết file Subagent

File subagent dùng YAML frontmatter để cấu hình, theo sau là system prompt viết bằng Markdown:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Frontmatter định nghĩa metadata/cấu hình; phần thân trở thành system prompt điều khiển hành vi subagent. Subagent chỉ nhận system prompt này cộng vài chi tiết môi trường cơ bản (như thư mục làm việc) - không nhận toàn bộ system prompt của Claude Code.

Một subagent khởi động ở thư mục làm việc hiện tại của hội thoại chính. Lệnh cd bên trong subagent không giữ lại giữa các lần gọi Bash/PowerShell và không ảnh hưởng thư mục làm việc của hội thoại chính. Muốn cấp cho subagent một bản sao repo độc lập, đặt isolation: worktree (xem bảng trường bên dưới).

Các trường frontmatter được hỗ trợ

Chỉ name và description là bắt buộc.

Trường	Bắt buộc	Mô tả
`name`	Có	Định danh duy nhất, chữ thường và dấu gạch ngang. Hooks nhận giá trị này qua `agent_type`. Tên file không cần trùng. Tên không được chứa `:` (dành riêng cho định danh phạm vi plugin như `my-plugin:reviewer`)
`description`	Có	Khi nào Claude nên giao việc cho subagent này
`tools`	Không	Tool subagent được dùng. Nếu bỏ trống, kế thừa mọi tool khả dụng cho subagent. Muốn nạp trước Skill, dùng trường `skills` thay vì liệt kê `Skill` ở đây
`disallowedTools`	Không	Tool bị cấm, loại khỏi danh sách kế thừa hoặc chỉ định
`model`	Không	`sonnet`, `opus`, `haiku`, `fable`, một model ID đầy đủ, hoặc `inherit`. Mặc định `inherit`
`permissionMode`	Không	`default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`, hoặc `manual` (alias của `default`). Bị bỏ qua với plugin subagent
`maxTurns`	Không	Số lượt agentic tối đa trước khi subagent dừng
`skills`	Không	Skill nạp sẵn vào ngữ cảnh subagent lúc khởi động (nội dung đầy đủ, không chỉ mô tả)
`mcpServers`	Không	MCP server khả dụng cho subagent này. Mỗi mục là tên server đã cấu hình sẵn, hoặc định nghĩa inline. Bị bỏ qua với plugin subagent
`hooks`	Không	Hooks vòng đời gắn riêng cho subagent này. Bị bỏ qua với plugin subagent
`memory`	Không	Phạm vi bộ nhớ bền vững: `user`, `project`, hoặc `local`
`background`	Không	`true` để luôn chạy nền, ngay cả khi Claude cần kết quả ngay. Nếu bỏ trống, Claude tự quyết - từ v2.1.198 mặc định chạy nền
`effort`	Không	Mức effort riêng cho subagent, ghi đè mức của phiên. Mặc định kế thừa phiên. Tuỳ chọn: `low`, `medium`, `high`, `xhigh`, `max`
`isolation`	Không	`worktree` để chạy subagent trong một git worktree tạm - bản sao repo độc lập, nhánh mặc định từ default branch chứ không phải `HEAD` của phiên cha. Tự dọn dẹp nếu subagent không thay đổi gì
`color`	Không	Màu hiển thị trong task list/transcript: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`
`initialPrompt`	Không	Tự động gửi như lượt đầu tiên khi agent này chạy làm agent chính (qua `--agent` hoặc setting `agent`). Lệnh và skill được xử lý; được thêm trước prompt do người dùng nhập

Chọn model

Trường model quyết định model AI subagent dùng:

Alias model: sonnet, opus, haiku, fable.
Model ID đầy đủ: ví dụ claude-opus-5 hoặc claude-sonnet-5, nhận cùng giá trị với flag --model.
inherit: dùng cùng model với hội thoại chính.
Bỏ trống: mặc định inherit.

Khi Claude gọi một subagent, nó có thể kèm tham số model riêng cho lần gọi đó. Claude Code phân giải model theo thứ tự:

Biến môi trường CLAUDE_CODE_SUBAGENT_MODEL, nếu đặt thành một alias hoặc model ID.
Tham số model theo lần gọi.
Trường model trong định nghĩa subagent.
Model của hội thoại chính.

Claude Code đối chiếu các giá trị này với allowlist availableModels của tổ chức bạn (nếu có); nếu bị chặn, nó thay bằng model khác - với alias theo họ model (như opus), nó dùng phiên bản mới nhất trong họ đó mà allowlist cho phép; với giá trị khác bị chặn, nó rơi về model kế thừa. Trong phiên tương tác, Claude Code hiển thị cảnh báo nêu rõ model yêu cầu và model thực tế dùng.

Từ v2.1.198, subagent cũng kế thừa cấu hình extended thinking của hội thoại chính: bật ở phiên thì bật ở subagent, tắt thì tắt theo - không có setting thinking riêng cho từng subagent.

Kiểm soát năng lực của Subagent

Tool khả dụng

Subagent kế thừa tool built-in và MCP tool khả dụng ở hội thoại chính, được thu hẹp qua hai lớp lọc: lớp đầu loại bỏ một số tool khỏi mọi subagent, lớp sau thu hẹp thêm tập tool built-in cho subagent chạy nền (mặc định). Fork bỏ qua cả hai lớp lọc, nhận nguyên tập tool của hội thoại chính.

Lớp lọc đầu tiên loại các tool sau, kể cả khi có trong tools:

Agent (khi subagent đã ở giới hạn độ sâu - xem nesting)
AskUserQuestion
EndConversation (chỉ kết thúc được hội thoại chính)
EnterPlanMode
ExitPlanMode (trừ khi permissionMode của subagent là plan)
ScheduleWakeup
TaskOutput
WaitForMcpServers
Workflow

Lớp lọc thứ hai áp dụng cho subagent chạy nền: ngoài Agent và ExitPlanMode (theo điều kiện ở trên), subagent nền giữ mọi MCP tool nhưng chỉ giữ các tool built-in sau: Read, Grep, Glob, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage, Artifact. Mọi tool built-in khác bị loại - dù được kế thừa hay khai trong tools - nên cùng một định nghĩa subagent có thể cho ra tập tool khác nhau tuỳ chạy nền hay chạy trước (foreground).

Teammate trong agent teams giữ thêm các tool task và cron: TaskCreate, TaskGet, TaskList, TaskUpdate, CronCreate, CronDelete, CronList.

Dùng tools làm allowlist hoặc disallowedTools làm denylist. Ví dụ chỉ cho phép Read, Grep, Glob, Bash - subagent không sửa/ghi file, không dùng MCP tool nào:

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

Ví dụ dùng disallowedTools để kế thừa mọi tool trừ Write và Edit:

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

Nếu khai cả hai, disallowedTools được áp dụng trước, tools xử lý trên phần còn lại. Tool nằm trong cả hai sẽ bị loại.

Nếu không mục nào trong tools phân giải được thành tool hợp lệ (ví dụ viết sai chính tả hoặc tên tool không khả dụng cho subagent), Claude Code thường từ chối khởi chạy subagent và trả lỗi nêu tên các mục không hợp lệ.

Cả hai trường còn nhận pattern cấp MCP server: mcp__<server> hoặc mcp__<server>__* để cấp/loại toàn bộ tool của một server. Trong disallowedTools, mcp__* loại toàn bộ MCP tool từ mọi server:

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

Giới hạn subagent nào được phép tạo

Khi một agent chạy làm main thread qua claude --agent, nó có thể tạo subagent bằng tool Agent. Để giới hạn loại subagent nó được tạo, dùng cú pháp Agent(agent_type) trong tools:

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

Đây là allowlist: chỉ worker và researcher được tạo; nếu agent cố tạo loại khác, yêu cầu thất bại. Muốn chặn vài agent cụ thể còn lại cho phép tất cả, dùng permissions.deny (xem Vô hiệu hoá subagent cụ thể).

Cho phép tạo mọi subagent không giới hạn: dùng Agent không có ngoặc. Bỏ hẳn Agent khỏi tools thì agent không tạo được subagent nào.

Cú pháp allowlist Agent(agent_type) chỉ áp dụng khi agent chạy làm main thread qua --agent. Trong định nghĩa subagent thông thường, khai Agent trong tools cho phép subagent đó tạo subagent con (trong giới hạn độ sâu), nhưng danh sách loại trong ngoặc bị bỏ qua.

Giới hạn MCP server theo subagent

Dùng trường mcpServers để cấp cho subagent quyền dùng MCP server không có sẵn ở hội thoại chính. Server định nghĩa inline được kết nối lúc subagent khởi động và ngắt khi xong; tham chiếu bằng tên dùng chung kết nối của phiên cha.

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Định nghĩa inline: chỉ dành riêng cho subagent này
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Tham chiếu theo tên: dùng lại server đã cấu hình sẵn
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

Định nghĩa inline dùng cùng schema với entry trong .mcp.json, hỗ trợ các loại stdio, http, sse, ws. Muốn giữ một MCP server ngoài hội thoại chính (để không tốn ngữ cảnh với mô tả tool của nó ở đó), định nghĩa inline ở đây thay vì trong .mcp.json - subagent nhận tool, hội thoại chính thì không.

Các giới hạn MCP áp dụng cho phiên chính (--strict-mcp-config, --bare, cấu hình MCP managed cấp tổ chức, policy allowedMcpServers/deniedMcpServers) cũng áp dụng cho server khai trong frontmatter subagent. Khi một trong số này chặn một server, Claude Code bỏ qua server đó và hiện cảnh báo.

Permission mode

Trường permissionMode kiểm soát cách subagent xử lý các permission prompt:

Mode	Hành vi
`default`	Kiểm tra quyền chuẩn, có hỏi xác nhận
`acceptEdits`	Tự chấp nhận chỉnh sửa file và lệnh filesystem thông dụng trong thư mục làm việc/`additionalDirectories`
`auto`	Auto mode: một bộ phân loại nền rà soát lệnh và ghi vào thư mục được bảo vệ
`dontAsk`	Tự chối mọi permission prompt (trừ tool đã cho phép tường minh); `AskUserQuestion` và tool đánh dấu `requiresUserInteraction` vẫn bị chối dù đã cho phép
`bypassPermissions`	Bỏ qua toàn bộ permission prompt
`plan`	Plan mode (chỉ đọc, không sửa)

Nếu hội thoại cha đang ở bypassPermissions hoặc acceptEdits, mode đó được ưu tiên và subagent không ghi đè được. Nếu cha ở auto mode, subagent kế thừa auto mode và permissionMode trong frontmatter bị bỏ qua.

Nạp trước Skill vào Subagent

Dùng trường skills để bơm nội dung skill vào ngữ cảnh subagent ngay khi khởi động, cho subagent kiến thức chuyên môn mà không cần tự khám phá/nạp skill trong lúc chạy:

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

Trường này chỉ kiểm soát skill nào được nạp sẵn - không giới hạn skill subagent được phép dùng: nếu bỏ trống, subagent vẫn có thể tự khám phá và gọi skill dự án/người dùng/plugin qua tool Skill lúc chạy. Muốn cấm hẳn việc gọi skill, bỏ Skill khỏi tools hoặc thêm vào disallowedTools.

Không thể nạp trước skill đặt disable-model-invocation: true (bao gồm skill /verify tích hợp sẵn) - những skill này chỉ bạn gọi được, nên không nạp trước được.

Bộ nhớ bền vững (persistent memory)

Trường memory cấp cho subagent một thư mục bền vững, tồn tại qua nhiều hội thoại, để nó tích luỹ kiến thức theo thời gian (mẫu codebase, kinh nghiệm debug, quyết định kiến trúc…):

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

Phạm vi	Vị trí	Dùng khi
`user`	`~/.claude/agent-memory/<tên-agent>/`	Cần nhớ kinh nghiệm xuyên suốt mọi dự án
`project`	`.claude/agent-memory/<tên-agent>/`	Kiến thức riêng cho dự án, chia sẻ được qua version control
`local`	`.claude/agent-memory-local/<tên-agent>/`	Riêng cho dự án nhưng không nên commit

Đây là một phần của auto memory: nếu bạn tắt auto memory (autoMemoryEnabled hoặc CLAUDE_CODE_DISABLE_AUTO_MEMORY), trường memory mất tác dụng.

Khi bật memory: system prompt của subagent gồm chỉ dẫn đọc/ghi thư mục memory, cộng 200 dòng hoặc 25KB đầu của MEMORY.md (tuỳ cái nào đến trước), kèm chỉ dẫn tự dọn dẹp nếu vượt giới hạn; các tool Read/Write/Edit được tự động bật để subagent quản lý file memory của nó.

Mẹo dùng: chọn project làm mặc định (chia sẻ được qua git); nhắc subagent kiểm tra memory trước khi bắt đầu việc và cập nhật memory sau khi xong; có thể viết thẳng chỉ dẫn “hãy cập nhật memory khi phát hiện pattern/kiến trúc mới” ngay trong file markdown của subagent để nó chủ động tự duy trì.

Rule có điều kiện bằng hooks

Muốn kiểm soát tool linh hoạt hơn (cho phép một số thao tác của tool, chặn số khác), dùng hook PreToolUse để xác thực trước khi tool chạy. Ví dụ dưới đây tạo subagent chỉ cho phép truy vấn database chỉ-đọc:

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

Claude Code truyền input hook dưới dạng JSON qua stdin. Script xác thực đọc JSON này, trích lệnh Bash, và thoát với mã 2 để chặn thao tác ghi:

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Chặn thao tác ghi SQL (không phân biệt hoa/thường)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

Trên macOS/Linux, cấp quyền thực thi cho script: chmod +x ./scripts/validate-readonly-query.sh - nếu không, hook sẽ lỗi thay vì chặn được gì. Trên Windows, viết hook script bằng PowerShell và thêm shell: powershell vào entry hook.

Vô hiệu hoá subagent cụ thể

Thêm vào mảng deny trong settings, dùng định dạng Agent(subagent-name):

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

Áp dụng cho cả subagent built-in lẫn tự tạo. Cũng có thể dùng flag CLI:

claude --disallowedTools "Agent(Explore)"

Định nghĩa hooks cho Subagent

Subagent có thể định nghĩa hooks chạy trong vòng đời của nó, theo hai cách:

Trong frontmatter của subagent: hook chỉ chạy khi subagent đó đang hoạt động.
Trong settings.json: hook toàn phiên, cũng kích hoạt bên trong subagent - PreToolUse/PostToolUse chạy cho tool call của subagent giống như ở hội thoại chính; SubagentStart/SubagentStop chạy khi subagent bắt đầu/kết thúc.

Hooks trong frontmatter

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

Khi agent được gọi làm subagent, hook Stop trong frontmatter tự động chuyển thành sự kiện SubagentStop lúc chạy.

Để hook frontmatter của một subagent cấp dự án chạy được, bạn cần chấp nhận workspace trust cho thư mục chứa file agent đó. Hook của subagent cấp người dùng (~/.claude/agents/) và định nghĩa truyền qua --agents chạy không cần bước này.

Hook cấp dự án cho sự kiện subagent

Cấu hình trong settings.json, phản ứng với sự kiện vòng đời subagent ở hội thoại chính:

Sự kiện	Input matcher	Khi kích hoạt
`SubagentStart`	Tên loại agent	Khi subagent bắt đầu chạy
`SubagentStop`	Tên loại agent	Khi subagent hoàn thành

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

Làm việc với Subagent

Giao việc tự động

Claude tự động giao việc dựa trên mô tả yêu cầu của bạn, trường description của subagent, và ngữ cảnh hiện tại. Muốn khuyến khích giao việc chủ động, thêm cụm như “use proactively” vào description.

Gọi Subagent tường minh

Khi giao việc tự động chưa đủ, bạn có thể tự yêu cầu - ba cách, từ gợi ý một lần đến mặc định cho cả phiên:

Ngôn ngữ tự nhiên - chỉ cần nêu tên subagent trong prompt, Claude tự quyết định có giao việc không:

Dùng subagent test-runner để sửa các test đang fail
Nhờ subagent code-reviewer xem lại các thay đổi gần đây

@-mention - gõ @ và chọn subagent từ danh sách gợi ý, đảm bảo đúng subagent đó chạy thay vì để Claude tự chọn:

@"code-reviewer (agent)" xem lại phần thay đổi auth

Toàn bộ tin nhắn vẫn gửi tới Claude, Claude tự viết task prompt cho subagent dựa trên yêu cầu của bạn - @-mention chỉ quyết định subagent nào được gọi, không quyết định nội dung prompt nó nhận. Subagent từ plugin hiện trong danh sách gợi ý dưới tên có phạm vi (ví dụ my-plugin:code-reviewer).

Chạy cả phiên như một subagent - dùng flag --agent <name> để main thread mang system prompt, giới hạn tool, và model của subagent đó:

claude --agent code-reviewer

System prompt của subagent thay thế hoàn toàn system prompt mặc định của Claude Code (như --system-prompt). File CLAUDE.md và project memory vẫn nạp bình thường. Cách này hoạt động với cả subagent built-in lẫn tự tạo, và lựa chọn được giữ khi resume phiên.

Muốn đặt mặc định cho mọi phiên trong một dự án, đặt trong .claude/settings.json:

{
  "agent": "code-reviewer"
}

Flag CLI ghi đè setting nếu cả hai cùng tồn tại.

Chạy Subagent trước (foreground) hay chạy nền (background)

Foreground: chặn hội thoại chính đến khi hoàn tất; permission prompt chuyển thẳng cho bạn.
Background: chạy song song trong khi bạn tiếp tục làm việc khác. Khi subagent nền gặp tool call cần permission, prompt hiện lên ở phiên chính, nêu rõ subagent nào đang hỏi - bạn duyệt để nó tiếp tục, hoặc Esc để chối riêng lệnh đó mà không dừng subagent.

Từ v2.1.198, subagent mặc định chạy nền; Claude chỉ chạy foreground khi cần kết quả ngay để tiếp tục. Bạn cũng có thể tự điều khiển: nhờ Claude chạy nền/trước, hoặc nhấn Ctrl+B để đưa một task đang chạy vào nền.

Kết quả của subagent nền đến Claude dưới dạng thông báo hoàn tất ở lượt sau - Claude đợi thông báo đó rồi mới báo kết quả; nếu bạn hỏi tiến độ trước, Claude sẽ báo là subagent vẫn đang chạy.

Muốn tắt hoàn toàn chức năng chạy nền, đặt biến môi trường CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1.

Quét nội dung đầu ra của Subagent

Claude Code quét báo cáo cuối cùng của mỗi subagent trước khi Claude đọc - vì subagent có thể đã đọc file, trang web, hoặc kết quả lệnh mà bạn chưa từng xem, và nội dung từ các nguồn đó có thể chứa chỉ dẫn nhắm vào hội thoại chính. Việc quét không xoá hay sửa nội dung, chỉ chèn thêm dấu hiệu: chèn backslash vào văn bản giả dạng output của Claude Code (như tag <system-reminder> hoặc dòng bắt đầu bằng Human:/Assistant:), hoặc thêm một dòng đánh dấu khi báo cáo giả dạng các tag/nhắc tới permission setting nhạy cảm như bypassPermissions.

Việc quét không đánh giá nội dung có ác ý hay không, và không thay đổi việc một chỉ dẫn trong báo cáo có thể làm gì - mọi tool call vẫn đi qua permission check và sandboxing bình thường của phiên. Đây không phải cách thay thế cho việc giới hạn năng lực subagent.

Các pattern thường dùng

Cô lập thao tác nhiều output - chạy test, tải tài liệu, xử lý log file có thể tốn nhiều ngữ cảnh; giao cho subagent để phần output dài ở lại trong ngữ cảnh riêng, chỉ phần tóm tắt liên quan quay về:

Dùng subagent để chạy test suite và chỉ báo cáo các test fail kèm error message

Nghiên cứu song song - với các hướng tìm hiểu độc lập, triệu tập nhiều subagent chạy đồng thời:

Nghiên cứu song song module authentication, database, và API bằng các subagent riêng biệt

Mỗi subagent tự khám phá phần của mình, sau đó Claude tổng hợp kết quả. Cách này hiệu quả nhất khi các hướng nghiên cứu không phụ thuộc lẫn nhau.

Nối chuỗi subagent - với quy trình nhiều bước, để Claude dùng các subagent theo trình tự, mỗi subagent hoàn thành việc và trả kết quả cho Claude, Claude chuyển ngữ cảnh liên quan sang subagent tiếp theo:

Dùng subagent code-reviewer tìm vấn đề hiệu năng, sau đó dùng subagent optimizer để sửa

Khi nào dùng subagent, khi nào dùng hội thoại chính

Dùng hội thoại chính khi: việc cần qua lại thường xuyên/tinh chỉnh lặp lại; nhiều giai đoạn (plan, implement, test) chia sẻ nhiều ngữ cảnh chung; bạn đang làm một thay đổi nhanh, có mục tiêu rõ; độ trễ quan trọng (subagent khởi động từ đầu, có thể mất thời gian gom ngữ cảnh).

Dùng subagent khi: việc tạo ra output dài dòng bạn không cần giữ lại; bạn muốn ép giới hạn tool/quyền cụ thể; việc tự chứa và có thể trả về dưới dạng tóm tắt.

Cân nhắc dùng Skill thay vì subagent khi bạn muốn prompt/quy trình tái sử dụng chạy trong ngữ cảnh hội thoại chính thay vì ngữ cảnh cô lập.

Cho phép Subagent tạo Subagent con

Mặc định, một subagent có thể tạo subagent con của riêng nó, tối đa ba tầng dưới hội thoại chính. Ở giới hạn độ sâu, Claude Code không cấp tool Agent cho subagent nữa (trừ fork), nên subagent ở giới hạn tự làm việc được giao và chỉ trả về một bản tóm tắt.

Nesting phù hợp cho việc bị chia nhỏ thành nhiều nhiệm vụ con song song - ví dụ một subagent review triệu tập một subagent verify cho từng finding - để kết quả trung gian không lọt vào hội thoại chính của bạn; chỉ tóm tắt của subagent cấp cao nhất quay về.

Đổi giới hạn bằng biến môi trường CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, ví dụ giới hạn 2 tầng trong settings.json:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

Đặt 1 để tắt hẳn nesting. Muốn một subagent cụ thể không được tạo con dù nesting đang bật (ví dụ subagent review cần giữ chỉ-đọc), bỏ Agent khỏi tools của nó hoặc thêm vào disallowedTools.

Giới hạn số Subagent chạy đồng thời

Khác với giới hạn độ sâu ở trên, giới hạn này ngăn Claude tạo thêm subagent khi có quá nhiều subagent đang chạy cùng lúc - không giới hạn tổng số subagent Claude có thể tạo trong cả phiên. Mặc định, khi 20 subagent đang chạy, việc tạo thêm sẽ lỗi Concurrent subagent limit reached; việc tạo thành công trở lại khi số lượng đang chạy giảm xuống dưới ngưỡng. Đổi ngưỡng bằng biến môi trường CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.

Quản lý ngữ cảnh Subagent

Những gì được nạp khi khởi động

Mỗi subagent khởi động với cửa sổ ngữ cảnh mới, cô lập - không thấy lịch sử hội thoại của bạn, skill đã gọi, hay file Claude đã đọc trước đó. Claude soạn một tin nhắn giao việc tóm tắt nhiệm vụ, và subagent làm việc từ đó. Ngoại lệ là fork - kế thừa nguyên hội thoại cha thay vì bắt đầu từ đầu.

Ngữ cảnh khởi đầu của một subagent thường (không phải fork) gồm:

System prompt: prompt riêng của agent cộng chi tiết môi trường Claude Code thêm vào - không phải toàn bộ system prompt của Claude Code.
Task message: prompt giao việc Claude viết khi bàn giao.
File CLAUDE.md: mọi cấp trong hệ thống CLAUDE.md mà hội thoại chính nạp (kể cả ~/.claude/CLAUDE.md, rule dự án, CLAUDE.local.md, file managed policy). Explore và Plan bỏ qua phần này.
Git status: ảnh chụp lúc phiên cha bắt đầu - vắng mặt nếu thư mục làm việc không phải git repo hoặc includeGitInstructions là false. Explore và Plan cũng bỏ qua.
Skill nạp sẵn: nội dung đầy đủ skill khai trong trường skills. Agent built-in không nạp trước skill.
Danh sách agent cùng phiên: một system reminder liệt kê main và các agent có tên khác trong phiên, mỗi cái là một giá trị to hợp lệ cho SendMessage - chỉ hiện khi subagent có tool SendMessage và có ít nhất một agent khác được đặt tên.

Một số state ở hội thoại chính không đến được subagent thường: output style (subagent chạy system prompt riêng, không theo output style của bạn); auto memory của hội thoại chính (muốn subagent có memory riêng, dùng trường memory); kích thước cửa sổ ngữ cảnh (theo model của chính subagent, không theo model cha).

Resume Subagent

Mỗi lần gọi subagent tạo một instance mới với ngữ cảnh sạch. Muốn tiếp tục việc của một subagent đã có thay vì bắt đầu lại, nhờ Claude resume nó - subagent giữ nguyên toàn bộ lịch sử hội thoại (tool call, kết quả, lý luận trước đó) và tiếp tục đúng chỗ đã dừng.

Khi một subagent hoàn tất, Claude nhận agent ID của nó. Explore và Plan chạy một lần và không trả agent ID, nên không resume được - dùng general-purpose hoặc subagent tự tạo khi cần tiếp tục việc.

Dùng subagent code-reviewer để review module authentication
[Agent hoàn tất]

Tiếp tục review đó, giờ phân tích thêm logic authorization
[Claude resume subagent với đầy đủ ngữ cảnh từ lần trước]

Một subagent đã hoàn tất, khi nhận SendMessage, tự động resume ở chế độ nền mà không cần gọi Agent mới. Bạn cũng có thể hỏi Claude về agent ID để tham chiếu tường minh, hoặc tìm trong transcript tại ~/.claude/projects/{project}/{sessionId}/subagents/ (mỗi transcript là agent-{agentId}.jsonl).

Transcript subagent tồn tại độc lập với hội thoại chính: không bị ảnh hưởng khi hội thoại chính compact (lưu file riêng), tồn tại xuyên suốt phiên (resume được cả sau khi khởi động lại Claude Code, miễn resume cùng session), và tự động bị dọn dẹp sau chu kỳ lưu trữ (mặc định 30 ngày).

Auto-compaction

Subagent hỗ trợ auto-compaction dùng cùng logic với hội thoại chính - điều kiện kích hoạt giống nhau, và CLAUDE_AUTOCOMPACT_PCT_OVERRIDE cũng áp dụng cho subagent.

Fork hội thoại hiện tại

Fork là một dạng subagent kế thừa toàn bộ hội thoại tính đến thời điểm đó thay vì bắt đầu từ đầu - mất đi tính cô lập đầu vào mà subagent thường cung cấp: fork thấy cùng system prompt, tool, model, và lịch sử tin nhắn với phiên chính, nên bạn có thể giao việc phụ mà không cần giải thích lại bối cảnh. Tool call của fork vẫn nằm ngoài hội thoại của bạn, chỉ kết quả cuối cùng quay về - cửa sổ ngữ cảnh chính vẫn sạch. Dùng fork khi một subagent có tên sẽ cần quá nhiều bối cảnh để hữu ích, hoặc khi muốn thử nhiều hướng song song từ cùng một điểm xuất phát.

Chạy một fork bằng lệnh /subtask kèm nhiệm vụ:

/subtask viết unit test cho các thay đổi ở parser tới giờ

Fork xuất hiện trong panel dưới ô nhập prompt, chạy nền trong khi bạn tiếp tục làm việc; khi xong, kết quả đến như một tin nhắn trong hội thoại chính.

Panel theo dõi và điều khiển fork đang chạy

Phím	Hành động
`↑` / `↓`	Di chuyển giữa các dòng
`Enter`	Mở transcript của fork được chọn, gửi tin nhắn tiếp theo
`x`	Đóng fork đã xong hoặc dừng fork đang chạy
`Esc`	Trả focus về ô nhập prompt

Fork khác gì so với subagent có tên

	Fork	Subagent có tên
Ngữ cảnh	Toàn bộ lịch sử hội thoại	Ngữ cảnh mới với prompt được truyền
System prompt & tool	Giống phiên chính	Từ file định nghĩa subagent
Model	Giống phiên chính	Theo trường `model` của subagent
Prompt cache	Dùng chung với phiên chính	Cache riêng

Vì system prompt và tool của fork giống hệt phiên cha, request đầu tiên của nó tái sử dụng prompt cache của cha - khiến fork rẻ hơn tạo subagent mới cho các việc cần cùng ngữ cảnh. Một fork không thể tạo fork con.

Ví dụ Subagent

Best practice: thiết kế subagent tập trung (mỗi subagent giỏi đúng một việc), viết description chi tiết (Claude dựa vào đó để quyết định giao việc), giới hạn tool tối thiểu cần thiết, và commit subagent dự án vào version control để chia sẻ với team.

Code reviewer - chỉ đọc

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

Debugger - được phép sửa code

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

Data scientist - workflow chuyên biệt ngoài lập trình thuần

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

Database query validator - dùng hook để xác thực

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

Script xác thực đọc JSON hook qua stdin, trích lệnh, và chặn nếu là thao tác ghi SQL:

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

System prompt đã dặn subagent từ chối yêu cầu ghi, nên hook đóng vai trò lớp chặn dự phòng: nếu subagent vẫn thử ghi, Claude Code chặn lệnh và subagent nhận lại thông báo lỗi từ script.

Bước tiếp theo

Phân phối subagent qua plugin để chia sẻ giữa các team/dự án.
Chạy Claude Code theo chương trình (headless) bằng Agent SDK cho CI/CD và tự động hoá.
Dùng MCP server để cấp cho subagent quyền truy cập tool và dữ liệu bên ngoài.