Có một giới hạn mà bạn sẽ gặp phải với bất kỳ phiên mã hóa AI nào: cửa sổ ngữ cảnh. Nhồi nhét một cuộc trò chuyện với một lần tái cấu trúc lớn, ba vòng đầu ra kiểm tra và một đánh giá mã, và tác nhân sẽ bắt đầu mất dấu. Các subagent của Claude Code là giải pháp. Thay vì một tác nhân xử lý tất cả mọi thứ trong một ngữ cảnh, bạn tạo ra các tác nhân chuyên biệt, mỗi tác nhân có cửa sổ ngữ cảnh riêng, hướng dẫn riêng và quyền công cụ riêng. Chúng thực hiện một công việc, trả về kết quả và giữ cho luồng chính sạch sẽ. Đây là hướng dẫn xây dựng thực hành. Cách tạo một subagent tùy chỉnh dưới dạng tệp cấu hình, mỗi trường frontmatter làm gì, cách Claude quyết định ủy quyền cho nó, và cách thiết lập một cấu hình thực tế nơi một tác nhân đánh giá mã trong khi một tác nhân khác viết kiểm thử song song. Nếu bạn muốn tổng quan về khái niệm trước, bài viết của chúng tôi về subagent của Claude Code là gì và tại sao chúng quan trọng bao gồm các kiến thức cơ bản. Ở đây, chúng tôi tập trung vào việc xây dựng chúng, và vào góc độ kiểm thử API biến một subagent kiểm thử thành một bước xác minh đáng tin cậy.
TL;DR
Bạn tạo một subagent của Claude Code bằng cách viết một tệp Markdown trong ` .claude/agents/ ` với YAML frontmatter: một ` name `, một ` description ` cho Claude biết khi nào cần ủy quyền, một danh sách cho phép ` tools ` tùy chọn và một ` model ` tùy chọn. Phần nội dung của tệp trở thành lời nhắc hệ thống của subagent. Mỗi subagent chạy trong cửa sổ ngữ cảnh riêng với các công cụ riêng, để bạn có được sự cô lập ngữ cảnh, song song hóa và chuyên môn hóa. Claude tự động ủy quyền dựa trên mô tả, hoặc bạn gọi một subagent bằng tên. Tài liệu tham khảo chính thức là tài liệu subagent của Claude Code.
Subagent trong 60 giây
Một subagent là một phiên bản tác nhân riêng biệt mà tác nhân chính của Claude Code giao một nhiệm vụ cho. Tác nhân chính là kỹ sư trưởng; các subagent là các chuyên gia mà nó kéo vào. Chuyên gia làm việc trong cuộc trò chuyện riêng của mình, với cửa sổ ngữ cảnh và lời nhắc hệ thống riêng, sau đó chỉ trả về kết quả. Ba thuộc tính khiến chúng đáng để cấu hình:
- Cửa sổ ngữ cảnh riêng. Một subagent bắt đầu mới với chỉ nhiệm vụ được giao, vì vậy luồng chính không bao giờ bị lấp đầy bởi công việc trung gian của nó.
- Lời nhắc hệ thống tùy chỉnh. Bạn định hình cách nó hoạt động: một người đánh giá tìm kiếm lỗ hổng bảo mật, một người viết kiểm thử tuân thủ các quy ước của bạn.
- Công cụ có thể cấu hình. Bạn cấp cho mỗi subagent chỉ những công cụ nó cần, vì vậy một người đánh giá không thể viết và một người chạy kiểm thử chỉ có đủ quyền truy cập shell.
Đó là nền tảng khái niệm; tổng quan về khái niệm đi sâu hơn vào lý do tại sao. Phần còn lại của hướng dẫn này là về việc xây dựng chúng, đó là nguyên tắc tương tự đằng sau kiến trúc harness của Claude Code được áp dụng ở cấp độ các nhiệm vụ riêng lẻ.
Tại sao nên sử dụng subagent
Ba lý do, và chúng bổ sung cho nhau.
Cô lập ngữ cảnh. Một phiên làm việc dài sẽ giảm hiệu suất khi cửa sổ ngữ cảnh đầy. Mỗi lần đọc tệp, mỗi lần chạy kiểm thử, mỗi chủ đề phụ đều tiêu tốn ngân sách và làm loãng sự tập trung. Ủy quyền một nhiệm vụ lớn cho một subagent giữ tất cả công việc đó trong ngữ cảnh của subagent, chứ không phải ngữ cảnh chính. Tác nhân chính nhận lại một bản tóm tắt rõ ràng thay vì 50.000 token nhiễu trung gian. Sự cô lập đó cũng là một đòn bẩy chi phí, vì bạn không phải kéo một ngữ cảnh cồng kềnh qua mỗi lượt. Các ghi chú của chúng tôi về việc giảm chi phí token của tác nhân đi sâu vào khía cạnh kinh tế.
Song song hóa. Các nhiệm vụ độc lập không cần phải chạy tuần tự. Một tác nhân chính có thể điều phối nhiều subagent cùng lúc: đánh giá module này trong khi kiểm thử module kia và ghi tài liệu cho module thứ ba. Thời gian thực tế giảm xuống mức của nhiệm vụ đơn lẻ chậm nhất thay vì tổng cộng. Các quy trình làm việc động của Claude Code đẩy điều này đến giới hạn, phân tán hàng trăm subagent song song từ một phiên duy nhất.
Chuyên môn hóa. Một tác nhân tổng quát thì ổn ở mọi thứ nhưng không giỏi ở bất cứ điều gì. Một subagent với lời nhắc hệ thống chặt chẽ và các công cụ phù hợp thì rất giỏi ở một việc. Một người đánh giá được nhắc nhở là phản biện sẽ tìm thấy nhiều lỗi hơn một người tổng quát chỉ nhìn lướt qua sự khác biệt. Một người viết kiểm thử biết phong cách kiểm định của bạn sẽ tạo ra các kiểm thử mà bạn thực sự sẽ giữ lại. Bạn xây dựng một đội ngũ nhỏ các chuyên gia thay vì một người tổng quát bị quá tải.
Cách tạo một subagent tùy chỉnh
Subagent là các tệp Markdown thuần túy. Đặt các tệp cấp dự án trong ` .claude/agents/ ` và các tệp cá nhân trong ` ~/.claude/agents/ `. Mỗi tệp có YAML frontmatter và phần nội dung trở thành lời nhắc hệ thống của subagent. Đây là một người đánh giá mã:
---
name: code-reviewer
description: Reviews code changes for bugs, security issues, and convention violations. Use after writing or editing code.
tools: Read, Grep, Glob
model: sonnet
---
You are a senior code reviewer. When given a diff or a set of files:
1. Look for correctness bugs, security holes, and missed edge cases.
2. Check that the code matches the project's existing conventions.
3. Report only high-confidence issues, ranked by severity.
Be specific. Cite file and line. Do not rubber-stamp.
Các trường frontmatter:
name— định danh bạn sử dụng để gọi nó.description— đây là trường quan trọng. Claude đọc nó để quyết định khi nào tự động ủy quyền. Hãy viết nó như một trình kích hoạt rõ ràng (“Sử dụng sau khi viết mã”), chứ không phải một nhãn chung chung.tools— danh sách cho phép. Bỏ qua nó để kế thừa các công cụ của tác nhân chính, hoặc liệt kê các công cụ cụ thể để hạn chế. Một người đánh giá không thể viết mã thì không thể vô tình thay đổi nó.model— tùy chọn ghim một mô hình. Sử dụng một mô hình rẻ hơn, nhanh hơn cho các subagent cơ học và một mô hình mạnh hơn cho các tác vụ suy luận phức tạp.
Phần nội dung là lời nhắc hệ thống. Đây là nơi thể hiện sự chuyên môn hóa, vì vậy hãy viết nó như cách bạn hướng dẫn một nhân viên mới: phải làm gì, ưu tiên cái gì, và tránh cái gì. Kết hợp nó với một tệp design.md hoặc AGENTS.md của dự án sẽ cung cấp cho subagent các quy ước của bạn mà không cần lặp lại chúng trong mỗi tệp.
Cách gọi các subagent
Có hai cách để một subagent hoạt động.
Ủy quyền tự động. Claude đọc trường `description` của mỗi subagent có sẵn và tự động ủy quyền khi một nhiệm vụ phù hợp. Hoàn tất chỉnh sửa tệp và tác nhân chính có thể chuyển phần diff cho `code-reviewer` của bạn mà không cần được yêu cầu, vì mô tả nói "sử dụng sau khi viết mã." Các mô tả tốt thúc đẩy ủy quyền tốt.
Gọi rõ ràng. Bạn cũng có thể gọi nó trực tiếp: “sử dụng subagent code-reviewer trên các thay đổi trong module orders.” Đây là cách bạn buộc một chuyên gia cụ thể khi bạn không muốn để việc ủy quyền cho ngẫu nhiên.
Dù bằng cách nào, subagent chạy trong ngữ cảnh riêng của nó, thực hiện công việc và trả về kết quả cho luồng chính. Bạn thấy quá trình chuyển giao diễn ra, và bạn có thể cấu hình mức độ chi tiết hiển thị. Để xâu chuỗi các subagent thành các chuỗi xác định, lặp lại được, các lệnh slash và SDK cung cấp cho bạn nhiều quyền kiểm soát hơn so với lời nhắc ad hoc; tổng quan về Claude Code bao gồm bề mặt cấu hình.
Subagent so với Agent SDK so với các quy trình làm việc động
Chúng có sự chồng chéo, vì vậy đây là lúc mỗi loại phù hợp.
| Công cụ | Mô hình điều khiển | Tốt nhất cho |
|---|---|---|
| Subagent | Mô hình quyết định khi nào ủy quyền (hoặc bạn chỉ định tên) | Chuyên môn hóa trong phiên và song song hóa nhẹ |
| Quy trình làm việc động | Mô hình điều phối phân tán quy mô lớn trong một phiên | Hàng trăm nhiệm vụ song song, quét rộng |
| Agent SDK | Bạn viết luồng điều khiển trong mã | Vòng lặp xác định, chạy theo lịch hoặc tự động |
Subagent là tùy chọn tương tác, trong phiên: bạn đang làm việc trong Claude Code và muốn một hoặc hai chuyên gia. Khi bạn cần một vòng lặp lập trình chạy theo lịch trình mà không có sự hiện diện của con người, bạn chuyển sang Claude Agent SDK và tự viết phần điều phối. Nếu bạn đang cân nhắc giữa một tùy chọn được lưu trữ và việc tự triển khai, so sánh giữa các tác nhân được quản lý và Agent SDK của chúng tôi sẽ phân tích các đánh đổi. Ba loại này không phải là đối thủ cạnh tranh mà là các bậc thang trên một chiếc thang từ tương tác đến tự động hoàn toàn.
Một ví dụ thực tế: đánh giá và viết kiểm thử song song
Hãy kết hợp chúng lại. Giả sử bạn vừa yêu cầu tác nhân chính triển khai một endpoint orders mới. Bạn muốn nó được đánh giá và kiểm thử, và không có lý do gì để chúng phải xảy ra tuần tự. Xác định hai subagent. `code-reviewer` ở trên, cộng với một người viết kiểm thử:
---
name: api-test-writer
description: Writes API test cases for new or changed endpoints. Use after an endpoint is implemented.
tools: Read, Grep, Write, Bash
model: sonnet
---
You write API tests against the project's OpenAPI spec.
1. Read the spec and the endpoint implementation.
2. Write tests covering success, validation errors, and auth.
3. Assert status codes and validate response bodies against the schema.
4. Run the suite and report pass/fail with reasons.
Bây giờ tác nhân chính điều phối cả hai cùng lúc: người đánh giá đọc phần diff trong khi người viết kiểm thử đọc đặc tả và viết độ bao phủ. Hai chuyên gia, hai ngữ cảnh cô lập, chạy song song. Luồng chính vẫn sạch sẽ và nhận lại hai bản tóm tắt: một báo cáo đánh giá và một kết quả kiểm thử. Kết quả kiểm thử đó là phần làm cho điều này đáng tin cậy. Một subagent chạy bộ kiểm thử API của bạn là một cổng xác minh, kiểm tra xác định cho biết liệu endpoint có thực sự hoạt động hay chỉ trông có vẻ đã hoàn thành. Đây là ý tưởng cốt lõi từ các vòng lặp tác nhân mã hóa: sự tự tin của tác nhân không quan trọng, phán quyết của cổng mới quan trọng. Kết nối subagent kiểm thử với một nền tảng kiểm thử API thực tế và phản hồi sẽ sắc bén hơn. Các nhóm sử dụng Apidog trỏ subagent đến một kịch bản kiểm thử Apidog để mọi phản hồi đều được xác thực theo lược đồ, và định tuyến các cuộc gọi endpoint trực tiếp của tác nhân thông qua trình gỡ lỗi tác nhân AI của Apidog để nó kiểm tra các yêu cầu theo cách một người kiểm thử con người sẽ làm. Lấy cùng cấu hình đó, gói nó trong một vòng lặp, và bạn có quy trình làm việc tự động mà chúng tôi đã xây dựng trong các quy trình làm việc của Claude chạy mà không cần bạn. Tải xuống Apidog nếu bạn muốn cổng kiểm thử nhận biết lược đồ ngay từ đầu.
Các phương pháp hay nhất
Một vài thói quen giúp subagent hữu ích thay vì hỗn loạn.
- Một trách nhiệm cho mỗi subagent. Người đánh giá chỉ đánh giá. Người kiểm thử chỉ kiểm thử. Đừng xây dựng một subagent làm mọi thứ; đó chỉ là tác nhân chính với các bước bổ sung.
- Viết mô tả để ủy quyền. Trường `description` là cách Claude quyết định gọi subagent của bạn. Hãy biến nó thành một trình kích hoạt rõ ràng, không phải là một tiêu đề. “Sử dụng sau khi chỉnh sửa mã để đánh giá lỗi” tốt hơn “Người đánh giá mã.”
- Cấp đặc quyền tối thiểu. Chỉ liệt kê các công cụ mà mỗi subagent cần. Một người đánh giá không có quyền ghi không thể thay đổi những gì nó đang đánh giá. Điều này quan trọng hơn khi các lần chạy không được giám sát.
- Ghim mô hình phù hợp cho từng công việc. Các subagent cơ học có thể chạy trên một mô hình nhanh hơn, rẻ hơn. Giữ mô hình mạnh nhất cho các subagent thực hiện suy luận phức tạp. Điều này kiểm soát cả tốc độ và chi phí.
- Trả về kết quả có cấu trúc. Yêu cầu subagent báo cáo theo một định dạng nhất quán (một phán quyết, một danh sách các vấn đề, một kết quả đạt/không đạt). Đầu ra có cấu trúc dễ dàng hơn cho tác nhân chính, và cho bạn, để hành động.
- Đừng lồng ghép quá mức. Các subagent gọi subagent gọi subagent sẽ khó theo dõi và tốn kém. Giữ cấu trúc phân cấp nông.
Những điều này phản ánh các mô hình kết nối công cụ trong quy trình làm việc tác nhân mà chúng tôi đã đề cập, và chúng vẫn đúng dù bạn có hai hay hai mươi subagent.
Khi nào nên sử dụng subagent (và khi nào không)
Subagent là một công cụ, không phải là mặc định. Biết khi nào nên bỏ qua chúng sẽ giúp thiết lập của bạn nhanh chóng và rẻ tiền. Hãy sử dụng subagent khi một nhiệm vụ **có giới hạn, độc lập và nhiều nhiễu**. Một đánh giá mã có giới hạn (có một điểm kết thúc rõ ràng), độc lập (không cần trạng thái chạy của luồng chính), và nhiều nhiễu (tạo ra nhiều thông tin đọc trung gian mà bạn không muốn làm tắc nghẽn ngữ cảnh chính). Tương tự đối với việc viết một bộ kiểm thử, tái tạo lỗi, hoặc kiểm tra một module về các vấn đề bảo mật. Đây là những ủy quyền hoàn hảo: cô lập công việc, nhận lại một phán quyết. Bỏ qua subagent khi nhiệm vụ **nhỏ, liên kết chặt chẽ hoặc tuần tự với công việc chính**. Đổi tên một biến, sửa một lỗi một dòng, hoặc bất cứ điều gì mà tác nhân chính đã có ngữ cảnh cần thiết trong tầm nhìn thì không có lợi từ việc chuyển giao. Việc tạo ra một subagent ở đó chỉ làm tăng độ trễ và một chuyến đi khứ hồi ngữ cảnh mà không mang lại lợi ích gì. Nếu tác nhân chính phải giải thích một nửa cuộc trò chuyện để hướng dẫn subagent, hãy giữ nó trong luồng chính. Quy tắc chung: ủy quyền công việc đủ độc lập để mô tả trong một đoạn văn và đủ giá trị để chạy song song. Một endpoint mới để đánh giá và kiểm thử thì phù hợp. Một lỗi chính tả thì không. Khi bạn mở rộng sang nhiều subagent đồng thời, các mô hình điều phối trong quy trình làm việc động sẽ đảm nhiệm, nhưng phán đoán tương tự vẫn áp dụng: song song hóa các tác vụ độc lập, giữ các tác vụ liên kết chặt chẽ với nhau.
Những lỗi thường gặp
- Mô tả mơ hồ. Nếu `description` chỉ là một nhãn, ủy quyền tự động sẽ không kích hoạt khi bạn mong đợi. Hãy viết nó như một trình kích hoạt sử dụng.
- Một subagent cồng kềnh. Nhồi nhét mọi công việc vào một subagent duy nhất sẽ làm mất đi lợi ích chuyên môn hóa. Hãy chia nhỏ theo trách nhiệm.
- Thừa hưởng tất cả công cụ theo mặc định. Để `tools` chưa được đặt sẽ cấp cho subagent mọi thứ mà tác nhân chính có. Tốt cho công việc đáng tin cậy, rủi ro cho bất kỳ thứ gì tự động. Hãy chủ động tạo danh sách cho phép.
- Không có subagent xác minh. Một thiết lập đánh giá và xây dựng mà không có cổng kiểm thử sẽ đưa ra mã trông có vẻ đúng nhưng lại gặp lỗi ở các trường hợp biên. Luôn bao gồm một subagent thực sự chạy các kiểm thử.
- Đối xử với subagent như SDK. Subagent được điều phối bởi mô hình và trong phiên. Nếu bạn cần luồng điều khiển xác định, theo lịch trình, đó là công việc của Agent SDK, chứ không phải một đống subagent.
Làm đúng những điều này và một vài subagent được phân tách rõ ràng sẽ biến Claude Code từ một trợ lý bận rộn duy nhất thành một nhóm nhỏ, tập trung. Bài viết về việc xây dựng các tác nhân hiệu quả của Anthropic đưa ra một lập luận rộng hơn: cấu trúc xung quanh mô hình tốt hơn một lời nhắc lớn hơn.
Các câu hỏi thường gặp
Subagent của Claude Code là gì? Đó là một phiên bản tác nhân riêng biệt mà tác nhân chính của Claude Code ủy quyền. Mỗi subagent có cửa sổ ngữ cảnh riêng, một lời nhắc hệ thống tùy chỉnh và một bộ công cụ có thể cấu hình. Nó thực hiện một nhiệm vụ tập trung và trả về kết quả, giữ cho cuộc trò chuyện chính sạch sẽ và cho phép bạn chạy các chuyên gia song song.
Làm thế nào để tạo một subagent của Claude Code? Tạo một tệp Markdown trong ` .claude/agents/ ` (dự án) hoặc ` ~/.claude/agents/ ` (cá nhân). Thêm YAML frontmatter với ` name `, ` description `, ` tools ` tùy chọn và ` model ` tùy chọn, sau đó viết lời nhắc hệ thống vào phần nội dung. Mô tả cho Claude biết khi nào nên tự động ủy quyền cho nó.
Claude quyết định sử dụng subagent nào bằng cách nào? Nó đọc trường `description` của mỗi subagent có sẵn và tự động ủy quyền khi một nhiệm vụ phù hợp. Bạn cũng có thể gọi một subagent rõ ràng bằng tên, ví dụ “sử dụng subagent code-reviewer.” Các mô tả rõ ràng, theo kiểu trình kích hoạt làm cho việc ủy quyền tự động trở nên đáng tin cậy.
Sự khác biệt giữa subagent và Claude Agent SDK là gì? Subagent là tác nhân trong phiên và được điều phối bởi mô hình: bạn đang làm việc trong Claude Code và nó kéo các chuyên gia vào. Agent SDK là lập trình, nơi bạn viết luồng điều khiển trong mã cho các lần chạy xác định hoặc không giám sát. Sử dụng subagent cho chuyên môn hóa tương tác, SDK cho các vòng lặp theo lịch trình.
Các subagent có thể chạy song song không? Có. Tác nhân chính có thể điều phối nhiều subagent cùng lúc cho các nhiệm vụ độc lập, vì vậy việc đánh giá, kiểm thử và ghi tài liệu diễn ra cùng nhau thay vì tuần tự. Đối với việc phân tán quy mô lớn, các quy trình làm việc động của Claude Code mở rộng điều này đến nhiều subagent song song trong một phiên duy nhất.
Subagent giúp kiểm thử API như thế nào? Xác định một subagent viết và chạy các kiểm thử API của bạn dựa trên đặc tả OpenAPI. Nó trở thành một cổng xác minh kiểm tra xem một endpoint có thực sự hoạt động hay không, chứ không chỉ là liệu nó có vẻ đã hoàn thành. Việc trỏ nó đến một nền tảng như Apidog làm cho phản hồi nhận biết được lược đồ, để mọi phản hồi đều được xác thực theo hợp đồng.
Điểm mấu chốt
Các subagent của Claude Code giải quyết vấn đề mà một cửa sổ ngữ cảnh không thể chứa mọi thứ. Bằng cách cấp cho mỗi nhiệm vụ ngữ cảnh, hướng dẫn và công cụ riêng, bạn đổi một tác nhân duy nhất bị quá tải lấy một đội ngũ nhỏ các chuyên gia làm việc song song và báo cáo lại một cách sạch sẽ. Thiết lập chỉ là một tệp Markdown, và lợi ích là sự tập trung, tốc độ và khả năng đặt đúng mô hình vào đúng công việc. Bắt đầu với hai: một người đánh giá và một người kiểm thử. Viết mô tả chặt chẽ để Claude tự động ủy quyền, chỉ cấp cho mỗi subagent các công cụ nó cần, và biến người kiểm thử thành một cổng xác minh thực sự bằng cách trỏ nó vào bộ kiểm thử API của bạn. Đối với bất cứ điều gì liên quan đến endpoint, Apidog cung cấp cho cổng đó một lược đồ để kiểm tra; tải xuống và để một subagent kiểm thử chứng minh mã của bạn hoạt động trước khi bạn đọc phần diff.