---
title: "Subagent trong Claude Code: context riêng, quyền hạn và cách điều phối"
description: "Subagent trong Claude Code là đơn vị thực thi có context, system prompt, model và phạm vi công cụ riêng, giúp cách ly log cùng dữ liệu trung gian khỏi phiên chính nhưng không mặc nhiên tách biệt filesystem. Delegation hiệu quả khi nhiệm vụ có ranh giới, quyền hạn và đầu ra rõ ràng—đặc biệt với chạy test, khảo sát codebase, review độc lập hoặc tra cứu tài liệu—đồng thời cần cân nhắc chi phí tái tạo context, xung đột khi sửa file và các lớp kiểm soát như permission, hook hoặc worktree."
date: 2026-07-23T01:32:07.000Z
reviewed_at: 2026-07-23T07:28:50.814Z
author: "GPT-5.6"
reviewer: "Nguyễn Ngọc Nam"
tags: ["Claude Code", "AI Agents", "Developer Tools"]
lang: vi
canonical: https://namnn.com/blog/subagent-trong-claude-code-context-rieng-quyen-han-va-cach-dieu-phoi/
---
Một phiên Claude Code điều tra lỗi authentication có thể bắt đầu bằng vài dòng log, rồi nhanh chóng mở rộng thành hàng chục file cấu hình, middleware, route handler và test. Phần lớn dữ liệu đọc được chỉ hữu ích trong vài phút: một stack trace đã xác định xong nguyên nhân, một danh sách kết quả tìm kiếm không còn cần thiết, hay toàn bộ output của test suite trong khi người dùng thực ra chỉ cần biết ba test nào fail.
Nếu tất cả dữ liệu ấy đi thẳng vào cuộc hội thoại chính, context window sẽ dần chứa nhiều thông tin trung gian hơn thông tin cần thiết cho quyết định tiếp theo. Đây là bài toán mà subagent trong Claude Code được thiết kế để giải quyết. Agent chính giao một task có ranh giới rõ cho một agent chuyên biệt; subagent xử lý task trong context riêng, sử dụng bộ tool và quyền đã được cấu hình, sau đó trả kết quả về phiên đã khởi tạo nó.1
Cách triển khai này nghe giống việc “mở thêm một Claude”, nhưng mô tả đó chưa đủ chính xác. Subagent không chỉ là một cửa sổ chat phụ. Nó là một đơn vị thực thi có system prompt riêng, context riêng, cấu hình model riêng và phạm vi tool có thể khác agent chính. Hiểu đúng các ranh giới này quyết định việc delegation giúp giảm tải hay chỉ khiến cùng một vấn đề bị đọc lại nhiều lần.
## Mô hình thực thi: tách context, không mặc nhiên tách filesystem
Một custom subagent thường được định nghĩa bằng file Markdown. Cấu hình dùng chung trong project nằm tại `.claude/agents/`; cấu hình cá nhân, dùng được ở nhiều project, nằm tại `~/.claude/agents/`. Claude Code còn hỗ trợ subagent do tổ chức quản lý, khai báo tạm thời qua cờ `--agents` và phân phối trong plugin. Khi nhiều định nghĩa trùng tên, vị trí khai báo quyết định độ ưu tiên.1
File subagent gồm hai phần:
- YAML frontmatter mô tả tên, điều kiện sử dụng, model, tool, permission mode và các khả năng bổ sung.
- Phần Markdown phía dưới trở thành system prompt chuyên biệt của subagent.
Khi agent chính gọi `Agent` tool, Claude Code khởi tạo một context window mới. Context đó nhận system prompt của subagent, task prompt do agent chính biên soạn và một số thông tin môi trường cần thiết. Với custom subagent thông thường, toàn bộ lịch sử hội thoại của phiên chính không được sao chép sang context mới. Các file agent chính đã đọc cũng không tự xuất hiện trong đó; subagent phải đọc lại những file cần cho task của mình.1
```mermaid
flowchart LR
U[Người dùng] --> M[Agent chính]
M -->|Task prompt có phạm vi| A[Agent tool]
A --> S[Context riêng của subagent]
S --> T[Đọc code, gọi tool, chạy test]
T --> R[Kết quả đã cô đọng]
R --> M
M --> U
```
Điểm đáng chú ý nằm ở chiều ngược lại: tool call, kết quả tìm kiếm và output trung gian của subagent không được chèn nguyên khối vào lịch sử của agent chính. Agent chính nhận phần kết quả mà subagent trả về. Nếu task tạo ra hàng nghìn dòng log nhưng kết quả cuối chỉ gồm nguyên nhân, vị trí code và lệnh tái hiện, phần nhiễu còn lại được giữ ngoài context chính.
Tuy nhiên, isolation về context không đồng nghĩa với isolation ở tầng filesystem. Theo mặc định, subagent bắt đầu trong current working directory của phiên chính. Nếu được cấp `Write`, `Edit` hoặc một `Bash` command có khả năng thay đổi file, nó có thể tác động lên cùng working tree. Hai subagent chạy song song và cùng sửa một file vì thế có thể tạo xung đột như hai tiến trình bình thường.
Claude Code hỗ trợ `isolation: worktree` cho trường hợp cần một bản checkout tách biệt. Khi đó, command của subagent chạy trong một git worktree tạm thay vì working tree chính. Đây là biện pháp hữu ích cho task có chỉnh sửa code, nhưng nó không thay thế việc chia phạm vi: hai nhánh sửa cùng một logic vẫn cần được tổng hợp và review trước khi merge.1
```mermaid
flowchart TD
A[Agent chính] --> B{Cần sửa file?}
B -->|Không| C[Subagent read-only]
B -->|Có| D{Có thể đụng cùng file?}
D -->|Không| E[Phạm vi file tách biệt]
D -->|Có hoặc chưa chắc| F[Worktree riêng hoặc xử lý tuần tự]
```
## Cấu trúc một file subagent
Một subagent review bảo mật có thể được khai báo như sau:
```markdown
---
name: security-reviewer
description: Review thay đổi authentication và authorization sau khi implementation hoàn tất. Use proactively khi diff chạm tới session, token, permission hoặc access control.
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
model: sonnet
permissionMode: plan
maxTurns: 20
---
Bạn là security reviewer cho codebase này.
Đọc diff, các caller trực tiếp, test và cấu hình liên quan. Không sửa file.
Chỉ báo cáo finding có bằng chứng từ code hiện tại.
Với mỗi finding, cung cấp:
- file và dòng liên quan;
- điều kiện kích hoạt;
- tác động bảo mật;
- bằng chứng trong code;
- cách kiểm chứng hoặc test tái hiện.
Không báo cáo một khả năng thuần lý thuyết nếu không chỉ ra được đường đi dữ liệu
hoặc quyền hạn dẫn tới tác động.
```
Chỉ `name` và `description` là bắt buộc. Dẫu vậy, một cấu hình thực tế thường cần mô tả rõ hơn vì mỗi trường kiểm soát một phần khác nhau của quá trình thực thi.1
### `name` và `description`
`name` là định danh của subagent. Giá trị nên ngắn, dùng chữ thường và dấu gạch nối, chẳng hạn `security-reviewer`, `test-runner` hoặc `api-researcher`.
`description` không đơn thuần là chú thích cho người đọc file. Claude dùng trường này, kết hợp với yêu cầu hiện tại và context của phiên chính, để quyết định khi nào nên delegate. Một description chỉ ghi “review code” có phạm vi quá rộng; agent chính khó phân biệt nó với một reviewer hiệu năng, reviewer bảo mật hay reviewer về convention.
Description tốt nên trả lời được hai câu hỏi:
- Subagent giải quyết loại task nào?
- Nó nên được gọi vào thời điểm hoặc điều kiện nào?
Ví dụ, “Review authentication và authorization sau khi implementation hoàn tất” cụ thể hơn “Security expert”. Nếu muốn khuyến khích Claude chủ động delegate, documentation của Anthropic đề xuất đưa tín hiệu như “use proactively” vào description.1
### `tools` và `disallowedTools`
`tools` là allowlist. Nếu cấu hình `Read, Grep, Glob, Bash`, subagent không được cấp `Write`, `Edit` hay các MCP tool không có trong danh sách. Ngược lại, nếu bỏ trường `tools`, subagent kế thừa tập tool khả dụng cho subagent rồi tiếp tục chịu các bộ lọc của runtime.
`disallowedTools` là denylist áp dụng trên tập tool được kế thừa hoặc khai báo. Trong ví dụ trên, việc vừa dùng allowlist vừa chặn `Write, Edit` hơi dư về mặt kỹ thuật, nhưng thể hiện rõ ý định read-only cho người review cấu hình. Với cấu hình ngắn hơn, có thể chỉ dùng:
```yaml
tools: Read, Grep, Glob, Bash
```
Hoặc nếu muốn giữ hầu hết tool nhưng loại bỏ khả năng ghi file:
```yaml
disallowedTools: Write, Edit
```
Cần lưu ý rằng cấp `Bash` vẫn có thể mở ra command thay đổi workspace, gọi network hoặc tác động tới dịch vụ bên ngoài, tuỳ permission của phiên và môi trường chạy. “Không có `Write`” vì thế chưa đủ để khẳng định subagent hoàn toàn read-only. Nếu yêu cầu an toàn nghiêm ngặt, nên giới hạn cả command được phép chạy bằng permission rules hoặc `PreToolUse` hook.
### `model`, `effort` và `maxTurns`
`model` cho phép chọn model theo độ khó của task. Có thể dùng alias như `haiku`, `sonnet`, `opus`, `fable`, dùng model ID đầy đủ hoặc đặt `inherit`. Nếu bỏ trường này, subagent mặc định kế thừa model của cuộc hội thoại chính. Claude Code còn có thứ tự phân giải model giữa environment variable, tham số của lần gọi, frontmatter và model của phiên chính, nên frontmatter không phải lúc nào cũng là nguồn có độ ưu tiên cao nhất.1
Một chiến lược hợp lý là dùng model nhanh cho khảo sát có tiêu chí rõ, rồi dành model mạnh hơn cho việc tổng hợp hoặc review đòi hỏi suy luận sâu. Tuy nhiên, dùng model rẻ hơn không tự động giảm tổng chi phí nếu subagent phải đọc lại quá nhiều context hoặc trả về báo cáo quá dài.
`effort` điều chỉnh mức suy luận khi model hỗ trợ. `maxTurns` đặt giới hạn số vòng agentic trước khi subagent dừng. Hai trường này hữu ích với task có nguy cơ mở rộng không kiểm soát, chẳng hạn khảo sát toàn monorepo bằng một mô tả mơ hồ.
### `permissionMode` không thay thế tool restriction
`permissionMode` xác định cách subagent xử lý quyền, với các giá trị được hỗ trợ như `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan` và `manual` trong các phiên bản tương ứng. Trường này cần được xem cùng `tools`, `disallowedTools`, permission rules của phiên và chính sách tổ chức.1
Chẳng hạn, `permissionMode: plan` thể hiện rõ subagent được thiết kế cho phân tích, nhưng một cấu hình an toàn vẫn nên loại bỏ tool ghi file nếu không cần. Ngược lại, cấp `Write` trong allowlist không bảo đảm mọi thao tác ghi đều được thực thi; permission system và hook vẫn có thể yêu cầu xác nhận hoặc chặn thao tác.
## Subagent thực sự nhận được context nào?
Một lỗi thiết kế phổ biến là giao task như sau:
```text
Kiểm tra cách sửa vừa rồi có ổn không.
```
Agent chính hiểu “cách sửa vừa rồi” vì nó đã tham gia toàn bộ cuộc hội thoại. Custom subagent mới khởi tạo thì không nhất thiết biết thay đổi nào đang được nói tới, mục tiêu ban đầu là gì hoặc quyết định nào đã bị loại bỏ. Nó có thể đọc `git diff`, nhưng diff không chứa mọi ràng buộc nghiệp vụ.
Task prompt tốt cần đóng gói phần context tối thiểu để subagent làm việc độc lập:
```text
Review diff hiện tại của module auth.
Mục tiêu thay đổi: từ chối refresh token đã bị revoke trước khi phát hành access token mới.
Phạm vi cần đọc: src/auth, middleware gọi refresh service và test liên quan.
Không sửa file. Chỉ báo cáo lỗi có đường đi thực thi cụ thể.
Kết quả gồm severity, file:dòng, điều kiện kích hoạt và test tái hiện.
```
Cấu trúc này gồm bốn thành phần:
- Mục tiêu cần kiểm chứng.
- Phạm vi code hoặc dữ liệu được phép khảo sát.
- Ràng buộc hành động.
- Contract của output.
Output contract đặc biệt quan trọng. Nếu chỉ yêu cầu “hãy review”, subagent có thể trả một bài giải thích dài, làm mất phần context vừa tiết kiệm được. Nếu yêu cầu mỗi finding phải có severity, vị trí, bằng chứng và test tái hiện, kết quả trở nên dễ tổng hợp và dễ kiểm chứng hơn.
Tách context cũng tạo ra một trade-off. Subagent loại bỏ nhiễu khỏi phiên chính, nhưng phải tái xây dựng phần context cần thiết bằng cách đọc code và nhận task prompt. Delegation chỉ có lợi khi chi phí tái xây dựng này thấp hơn lượng output trung gian được cách ly hoặc giá trị chuyên môn hoá mà subagent mang lại.
## Foreground, background và cách kết quả quay về
Subagent có thể chạy foreground hoặc background. Foreground chặn luồng tiếp tục của agent chính cho tới khi task hoàn tất. Chế độ này phù hợp khi quyết định tiếp theo phụ thuộc trực tiếp vào kết quả, chẳng hạn phải xác định test nào fail trước khi sửa code.
Background cho phép agent chính tiếp tục làm việc trong lúc subagent xử lý task độc lập. Theo documentation hiện tại, Claude Code mặc định ưu tiên chạy subagent ở background và chuyển sang foreground khi cần kết quả ngay. Background subagent có tập built-in tool hẹp hơn foreground; khi gặp tool call cần quyền, yêu cầu xác nhận có thể được chuyển về phiên chính để người dùng quyết định.1
```mermaid
sequenceDiagram
participant U as Người dùng
participant M as Agent chính
participant S as Subagent background
U->>M: Yêu cầu phân tích module auth và billing
M->>S: Khảo sát auth
M->>M: Tiếp tục đọc billing
S-->>M: Thông báo hoàn tất + báo cáo auth
M->>M: Đối chiếu hai luồng
M-->>U: Kết luận tổng hợp
```
Background không làm cho hai task độc lập về dữ liệu. Nếu agent chính thay đổi file mà subagent đang đọc, kết quả có thể phản ánh hai thời điểm khác nhau của working tree. Với task review, nên chốt rõ đối tượng cần review, chẳng hạn commit, diff hoặc trạng thái file tại thời điểm bắt đầu.
Claude Code lưu transcript của subagent riêng với transcript chính. Transcript này có thể tồn tại trong session, không bị xoá chỉ vì cuộc hội thoại chính được compact và có thể được resume trong cùng session. Subagent cũng hỗ trợ auto-compaction theo cơ chế tương tự phiên chính khi context của chính nó tăng lên.1
## Bốn use case có lợi rõ rệt
### 1. Cách ly output của test và log
Test suite, build log và trace thường tạo ra nhiều dữ liệu nhưng chỉ một phần nhỏ cần đưa về agent chính. Đây là trường hợp subagent có tỷ lệ lợi ích trên chi phí cao.
Một `test-runner` có thể được cấu hình như sau:
```markdown
---
name: test-runner
description: Chạy test suite được chỉ định và phân tích test fail. Dùng khi output test có thể dài hoặc cần lặp lại nhiều lần.
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 15
---
Chạy đúng lệnh test được giao. Không sửa source code.
Nếu test fail, trả về:
1. tên test;
2. error message và stack frame liên quan;
3. file source có khả năng gây lỗi, kèm bằng chứng;
4. lệnh tối thiểu để tái hiện.
Không chép toàn bộ log. Giữ tối đa 20 dòng output cho mỗi lỗi, trừ khi phần dài hơn
là bằng chứng bắt buộc.
```
Task prompt có thể là:
```text
Dùng test-runner chạy test của package auth bằng `pnpm test auth`.
Chỉ phân tích test fail; không sửa file.
```
Giới hạn số dòng output không chỉ làm báo cáo ngắn hơn. Nó buộc subagent phân biệt bằng chứng với dữ liệu phụ, nhờ đó agent chính nhận được đầu vào phù hợp cho bước sửa lỗi.
### 2. Khảo sát nhiều vùng code độc lập
Trong một hệ thống lớn, câu hỏi “request này đi qua đâu?” có thể chia thành các nhánh tương đối độc lập: authentication, dữ liệu, cache và API bên ngoài. Mỗi subagent đọc một vùng rồi agent chính tổng hợp call path.
```text
Khảo sát song song ba phạm vi:
- auth-researcher: cách request được xác thực và gắn user context;
- data-researcher: repository và bảng được truy cập;
- api-researcher: endpoint bên ngoài và retry policy.
Mỗi báo cáo phải nêu entry point, call path, file:dòng và điểm chưa xác minh.
Không sửa file.
```
Cách chia này hiệu quả khi các nhánh không cần trao đổi liên tục. Nếu data flow chỉ hiểu được sau khi biết chính xác claim do auth tạo ra, chạy tuần tự có thể tốt hơn: auth-researcher trả contract trước, rồi agent chính chuyển phần liên quan cho data-researcher.
Một rủi ro khác là tổng output tăng theo số subagent. Bốn báo cáo dài 2.000 từ vẫn tiêu thụ nhiều context của phiên chính, dù từng quá trình khảo sát đã được cách ly. Vì vậy, parallelism cần đi cùng output contract chặt chẽ.
### 3. Review độc lập sau implementation
Agent vừa viết code thường đã hình thành một giả thuyết mạnh về cách giải pháp hoạt động. Giao review cho subagent có prompt và tiêu chí riêng tạo ra một lần đọc độc lập hơn, dù không thể xem đây là bằng chứng rằng review hoàn toàn không có bias.
Reviewer nên được yêu cầu đọc không chỉ diff mà cả caller, test và cấu hình liên quan. Chỉ đọc các dòng thay đổi dễ bỏ qua contract bị phá ở nơi khác.
```text
Dùng security-reviewer kiểm tra diff hiện tại.
Tập trung vào authorization bypass, token lifecycle và dữ liệu nhạy cảm trong log.
Phải đọc caller trực tiếp và test liên quan.
Không sửa file; bỏ qua nhận xét thuần style.
```
Có thể nối nhiều subagent thành pipeline tuần tự:
```mermaid
flowchart LR
I[Implementation] --> R[Security reviewer]
R --> V[Verifier kiểm chứng finding]
V --> M[Agent chính quyết định sửa]
```
Ở đây, reviewer tìm finding; verifier cố gắng tái hiện hoặc bác bỏ từng finding; agent chính mới quyết định thay đổi code. Cấu trúc này giảm nguy cơ một nhận xét thiếu bằng chứng được chuyển thẳng thành implementation.
### 4. Tra cứu documentation bằng MCP chuyên biệt
Một subagent có thể được cấp MCP server riêng bằng `mcpServers`. Inline MCP server chỉ kết nối khi subagent chạy và ngắt khi hoàn tất. Cách làm này vừa giới hạn capability theo task, vừa tránh đưa toàn bộ mô tả tool của server vào context chính.1
```markdown
---
name: browser-tester
description: Kiểm tra UI flow trong trình duyệt và thu thập bằng chứng trực quan.
tools: Read, Grep, Glob
mcpServers:
- playwright:
type: stdio
command: npx
args: ["-y", "@playwright/mcp@latest"]
---
Kiểm tra đúng route và state được giao. Không sửa source code.
Trả về các bước tái hiện, trạng thái quan sát được và đường dẫn screenshot.
```
MCP tool vẫn cần được xem như một capability có tác động thật. Nếu server có thể gửi message, chỉnh issue hoặc thay đổi dữ liệu, chỉ cấp nó cho subagent có nhiệm vụ và permission phù hợp.
## Hook, skill và persistent memory
Tool allowlist chỉ phân biệt theo tên tool. Nó không thể diễn đạt quy tắc như “được chạy `SELECT`, nhưng không được chạy `UPDATE`” nếu cả hai đều đi qua `Bash`. Trường hợp này cần `PreToolUse` hook để kiểm tra input trước khi command được thực thi.
```yaml
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-command.sh"
```
Hook nhận dữ liệu tool call qua `stdin` dưới dạng JSON. Script có thể phân tích command, trả exit code phù hợp và chặn thao tác vi phạm chính sách. Đây là kiểm soát xác định ở runtime, không phụ thuộc vào việc model có tuân thủ một câu nhắc trong prompt hay không.1
Subagent cũng có thể preload skill bằng trường `skills`. Nội dung đầy đủ của skill được đưa vào context khi khởi tạo, phù hợp với workflow cần quy trình hoặc rubric ổn định. Điểm khác biệt nằm ở nơi workflow chạy: skill dùng trong phiên chính không tạo context isolation; skill preload cho subagent trở thành kiến thức vận hành của một context riêng.
Trường `memory` cho phép duy trì bộ nhớ qua nhiều session với scope `user`, `project` hoặc `local`. Khi bật memory, Claude Code cung cấp chỉ dẫn và công cụ cần thiết để subagent quản lý thư mục memory. Cơ chế này hữu ích cho reviewer cần ghi lại convention, vị trí module hoặc lỗi lặp lại, nhưng memory không phải nguồn chân lý. Ghi chú cũ có thể lỗi thời sau refactor, nên prompt vẫn phải yêu cầu đối chiếu với code hiện tại trước khi kết luận.1
## Nested subagent, fork và agent team không phải một khái niệm
Subagent mặc định không được phép tự spawn subagent khác. Claude Code hiện cho phép bật nested spawning bằng `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`. Khi nesting được bật và subagent có `Agent` tool, nó có thể chia task tiếp xuống tầng dưới. Chỉ kết quả của subagent cấp trên cần quay về phiên chính, nên dữ liệu trung gian của cả nhánh có thể được giữ ngoài context chính.1
Nesting phù hợp khi task được delegate có cấu trúc phân rã tự nhiên, chẳng hạn reviewer tạo một verifier độc lập cho từng finding. Nó không phù hợp để che một task prompt quá rộng. Mỗi tầng mới làm tăng token usage, latency và số điểm cần quan sát khi kết quả sai.
Forked subagent lại giải quyết bài toán khác. Thay vì bắt đầu với context mới, fork kế thừa lịch sử hội thoại, system prompt, model và tool của phiên chính tại thời điểm tách. Tool call phát sinh sau đó vẫn ở nhánh riêng và chỉ kết quả cuối quay về. Fork phù hợp khi task phụ cần gần như toàn bộ background hiện có, khiến việc đóng gói lại context cho custom subagent trở nên tốn kém.1
Agent team là một cơ chế điều phối rộng hơn. Mỗi teammate là một Claude Code session độc lập; các teammate có thể giao tiếp trực tiếp, dùng task list chung và được người dùng tương tác riêng. Anthropic hiện đánh dấu agent teams là tính năng experimental và lưu ý rằng nó tiêu thụ nhiều token hơn, đồng thời có overhead về phối hợp, resume và shutdown.2
| Cơ chế | Context ban đầu | Giao tiếp | Phù hợp với |
|---|---|---|---|
| Custom subagent | Context mới, prompt chuyên biệt | Chủ yếu trả kết quả về agent gọi | Task hẹp, output lớn, quyền chuyên biệt |
| Fork | Sao chép context của phiên chính | Kết quả quay về phiên chính | Nhánh phụ cần nhiều background sẵn có |
| Nested subagent | Context mới ở từng tầng | Kết quả đi ngược lên cây điều phối | Task có thể phân rã tiếp nhưng cần giữ output trung gian ngoài phiên chính |
| Agent team | Session độc lập cho từng teammate | Teammate có thể trao đổi trực tiếp | Công việc song song dài, cần phối hợp giữa nhiều owner |
## Khi nào không nên delegate?
Một thay đổi nhỏ trong một file thường không bù được latency khởi tạo và chi phí đọc lại context. Nếu agent chính vừa đọc đúng function cần sửa, giao cho subagent đổi một điều kiện có thể khiến code bị đọc lần thứ hai mà không tạo thêm giá trị kiểm chứng.
Không nên delegate khi các bước phụ thuộc chặt vào quyết định ngay trước đó. Một quy trình liên tục xen kẽ giữa phân tích yêu cầu, sửa code và hỏi lại người dùng cần context chung để tránh sai lệch. Chia nó thành nhiều subagent có thể làm mỗi agent chỉ nhìn thấy một phần của chuỗi quyết định.
Các dấu hiệu nên giữ task ở phiên chính gồm:
- Task cần hỏi đáp thường xuyên với người dùng.
- Nhiều giai đoạn dùng chung gần như toàn bộ context.
- Thay đổi nhỏ, rõ vị trí và có lệnh kiểm chứng ngắn.
- Kết quả của nhánh này quyết định ngay input của nhánh khác.
- Chi phí khởi tạo và đọc lại code lớn hơn lượng output cần cách ly.
- Nhiều worker có khả năng chỉnh cùng file hoặc cùng cấu trúc dữ liệu.
Subagent cũng không phải ranh giới bảo mật tuyệt đối. Prompt “không sửa file” là chỉ dẫn hành vi; tool restriction, permission rules, hook và worktree mới là các lớp kiểm soát kỹ thuật. Với thao tác có thể ảnh hưởng production, dữ liệu hoặc dịch vụ bên ngoài, vẫn cần cơ chế xác nhận và policy ở tầng thực thi.
## Cách thiết kế một task có thể delegate
Tôi thường dùng năm câu hỏi trước khi giao việc cho subagent:
1. **Đầu ra cuối cùng là gì?** Nếu không thể mô tả output trong vài dòng, task có thể vẫn quá rộng.
2. **Subagent cần đọc những gì?** Chỉ rõ module, diff, log hoặc documentation thay vì yêu cầu “xem toàn bộ project”.
3. **Nó được phép làm gì?** Phân biệt đọc, chạy test, sửa file, truy cập network và gọi dịch vụ ngoài.
4. **Khi nào task được xem là hoàn tất?** Đặt tiêu chí kiểm chứng, giới hạn số vòng và điều kiện dừng.
5. **Agent chính cần nhận lại bao nhiêu dữ liệu?** Quy định format và giới hạn độ dài để tránh đưa phần nhiễu trở lại context chính.
Một task prompt có contract tương đối đầy đủ có thể viết như sau:
```text
Mục tiêu: xác định nguyên nhân ba test refresh-token đang fail.
Phạm vi:
- đọc src/auth/refresh.ts;
- đọc caller trực tiếp và test liên quan;
- được chạy `pnpm test auth --runInBand`;
- không sửa file và không gọi network.
Kết quả:
- root cause có bằng chứng từ code hoặc log;
- file:dòng liên quan;
- lệnh tái hiện tối thiểu;
- tối đa hai hướng sửa cùng trade-off;
- ghi rõ phần nào chưa xác minh.
Dừng sau khi xác định được root cause hoặc sau 12 lượt tool call.
```
Prompt này không bắt subagent đoán phạm vi, không giao quyền rộng hơn nhu cầu và không yêu cầu nó tự quyết định implementation. Nếu kết quả đủ bằng chứng, agent chính có thể dùng nó để đề xuất thay đổi hoặc chuyển sang một task riêng đã được phê duyệt.
## Đo hiệu quả thay vì đếm số agent
Số subagent được tạo không phản ánh chất lượng điều phối. Một workflow dùng sáu agent nhưng mỗi agent đọc lại cùng một thư mục, trả cùng một nhận xét và tạo báo cáo dài có thể tốn nhiều thời gian hơn một phiên duy nhất.
Có thể đánh giá delegation bằng bốn đại lượng thực dụng:
- **Context được cách ly:** lượng log, kết quả tìm kiếm hoặc file content không cần đưa về phiên chính.
- **Chi phí tái xây dựng context:** số file và quyết định subagent phải đọc lại trước khi bắt đầu công việc thực sự.
- **Mức độc lập của task:** khả năng hoàn tất mà không cần trao đổi liên tục với agent chính.
- **Khả năng kiểm chứng của output:** kết quả có file, dòng, command hoặc bằng chứng đủ để kiểm tra lại hay không.
Nếu context được cách ly lớn, chi phí tái xây dựng thấp và output có thể kiểm chứng, subagent thường là lựa chọn hợp lý. Nếu subagent phải nhận gần như toàn bộ lịch sử, liên tục chờ quyết định và trả về một bản tường thuật dài, task nên ở phiên chính hoặc dùng fork khi phù hợp.
## Checklist triển khai
Trước khi đưa một custom subagent vào workflow của team, nên kiểm tra:
- `description` nói rõ loại task và thời điểm sử dụng.
- System prompt quy định phạm vi, tiêu chí hoàn tất và output contract.
- `tools` chỉ chứa capability thực sự cần.
- `Bash` và MCP tool được xem xét theo tác động, không chỉ theo tên.
- Task ghi file có worktree hoặc phạm vi file không chồng lấn.
- Background task không phụ thuộc vào file đang được agent khác sửa.
- Model và effort tương xứng với độ khó.
- `maxTurns` hoặc điều kiện dừng ngăn khảo sát kéo dài không cần thiết.
- Hook được dùng cho quy tắc cần thực thi xác định.
- Memory luôn được đối chiếu với source hiện tại.
- Báo cáo cuối chứa bằng chứng nhưng không chép toàn bộ output trung gian.
Ranh giới nhiệm vụ vẫn là phần quan trọng nhất. Subagent không tự biến một yêu cầu mơ hồ thành workflow tốt; nó chỉ thực thi yêu cầu đó trong một context khác. Khi input đủ rõ, quyền được giới hạn theo nhu cầu và output có contract cụ thể, context riêng mới tạo ra lợi ích thật: agent chính giữ được mạch quyết định, còn phần khảo sát nhiều dữ liệu được xử lý ở nơi thích hợp hơn.
## Tài liệu tham khảo
- Anthropic. Create custom subagents. Claude Code Docs. Truy cập ngày 23/07/2026.
- Anthropic. Orchestrate teams of Claude Code sessions. Claude Code Docs. Truy cập ngày 23/07/2026.