Tiến độ sẽ không được lưu. Trình duyệt đang chặn lưu dữ liệu (thường do chế độ ẩn danh). Bạn vẫn học bình thường, nhưng đóng tab là mất tiến độ.
Phần luyện tập cần bật JavaScript. Bài đọc vẫn xem được bình thường.Về bài đọc
Docs nói gọn: định nghĩa subagent khi bạn cứ tạo cùng một kiểu trợ lý với cùng một hướng dẫn. Lợi ích so với subagent có sẵn:
- Hướng dẫn cố định: bạn viết một lần, mọi lần giao việc đều theo.
- Giới hạn công cụ: một reviewer chỉ được đọc, không thể lỡ tay sửa file.
- Chọn model: việc đơn giản chạy trên model nhanh, rẻ hơn.
- Dùng chung: commit vào repo là cả team có cùng trợ lý.
Cách nhanh nhất để có file đầu tiên là nhờ Claude viết: "Create a test-writer subagent in .claude/agents/ that…". Lệnh /agents ở bản hiện tại chỉ nhắc bạn làm vậy, hoặc sửa thẳng thư mục agents. Dù Claude viết hay bạn viết, hãy mở file ra đọc lại, vì đó là thứ quyết định subagent được làm gì.
Subagent là một file Markdown, giống skill ở cấp 3: frontmatter YAML ở đầu, nội dung bên dưới.
---
name: code-reviewer
description: Reviews code for quality and best practices. Use after code changes.
tools: Read, Grep, Glob
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and give
specific, actionable feedback on quality, security and tests.namevàdescriptionlà hai trường bắt buộc.descriptionnói khi nào Claude nên giao việc cho subagent này, nên viết như description của skill: làm gì, khi nào dùng.- Phần thân là system prompt của subagent (bộ hướng dẫn gốc định hình cách nó làm việc). Điểm quan trọng: subagent nhận prompt này cộng vài thông tin môi trường như thư mục làm việc, chứ không nhận system prompt của Claude Code. Điều gì bạn muốn nó làm thì phải viết ra.
Những lỗi khiến subagent không hoạt động như bạn nghĩ:
- Thiếu
description, hoặc---không nằm ở dòng đầu: Claude Code bỏ qua cả file. - Sai tên trường: tên nhiều từ viết kiểu camelCase, như
disallowedTools,maxTurns. Viếtdisallowed-toolsthì trường đó bị bỏ qua mà không báo lỗi. Chạyclaude --debugvà tìm "does not recognize or apply" trong log để thấy trường bị bỏ qua.
Không cần khởi động lại: Claude Code theo dõi thư mục agents, và vài giây sau khi bạn lưu file, lần giao việc tiếp theo đã dùng bản mới.
Vị trí file quyết định ai dùng được subagent:
| Vị trí | Dùng được ở | Ưu tiên |
|---|---|---|
| Cài đặt managed của tổ chức | Cả tổ chức | 1 (cao nhất) |
Cờ --agents khi mở phiên (JSON) |
Chỉ phiên đó | 2 |
.claude/agents/ trong repo |
Dự án này | 3 |
~/.claude/agents/ |
Mọi dự án trên máy bạn | 4 |
Thư mục agents/ của plugin |
Nơi bật plugin | 5 |
Hai chỗ bạn dùng nhiều nhất là .claude/agents/ cho subagent gắn với một codebase (commit để cả team dùng và cùng cải thiện) và ~/.claude/agents/ cho trợ lý cá nhân dùng ở mọi dự án. Nếu hai nơi có subagent trùng name, nơi ưu tiên cao hơn thắng. Tên file không cần trùng name, nhưng đặt giống nhau thì dễ tìm hơn.
Có hai cách giới hạn công cụ:
toolslà danh sách cho phép: chỉ những công cụ ghi ra mới dùng được.tools: Read, Grep, Globtạo ra một subagent chỉ đọc. Bỏ trống thì subagent thừa hưởng mọi công cụ dành cho subagent.disallowedToolslà danh sách chặn: thừa hưởng tất cả, trừ những công cụ ghi ra.disallowedTools: Write, Editvẫn giữ Bash nhưng không cho sửa file.
Một cái bẫy: disallowedTools: Bash(git push *) không chỉ chặn git push mà gỡ toàn bộ Bash khỏi subagent. Muốn giữ Bash và chặn một lệnh cụ thể, thêm luật deny Bash(git push *) vào permissions.deny trong cài đặt; luật đó áp cho cả hội thoại chính lẫn mọi subagent.
Nên nhớ thêm: subagent chạy nền (mặc định) chỉ giữ một bộ công cụ rút gọn, gồm những thứ hay dùng như Read, Grep, Glob, Bash, Edit, Write. tools cũng không giới hạn được thư mục. "Chỉ sửa test/" là hướng dẫn trong system prompt, không phải luật. Muốn chặn cứng thì dùng hook ở cấp 6.
Trường permissionMode đặt permission mode riêng cho subagent, nhưng chỉ có tác dụng khi hội thoại chính đang ở chế độ mặc định. Nếu hội thoại chính ở auto mode hay acceptEdits, subagent theo mode của hội thoại chính.
Trường model nhận sonnet, opus, haiku, fable, một ID đầy đủ như claude-sonnet-5-5, hoặc inherit. Không ghi gì thì subagent chạy cùng model với hội thoại gọi nó.
Khi nhiều nơi cùng đặt model, Claude Code lấy theo thứ tự:
- model Claude truyền khi gọi subagent (khi bạn yêu cầu, ví dụ "dùng haiku cho việc này");
- trường
modeltrong file; - biến môi trường
CLAUDE_CODE_SUBAGENT_MODEL; - model của hội thoại chính.
Chọn theo độ khó của việc. Tìm kiếm, liệt kê, tóm tắt log là việc đơn giản, chạy trên model nhanh và rẻ như haiku là đủ. Viết test hay review cần suy luận tốt hơn thì dùng sonnet hoặc để mặc định. Trường effort đặt mức effort riêng cho subagent nếu cần. Muốn biết subagent thực sự chạy model nào, mở /tasks: dòng của subagent ghi rõ model.
Tạo .claude/agents/test-writer.md:
---
name: test-writer
description: Writes and runs tests for todo-api routes. Use proactively when a route is added or changed, or when a bug needs a regression test.
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
color: green
---
You write tests for todo-api. The project uses node:test; tests live in test/todos.test.js.
1. Read the route in src/routes/ and the existing tests first; reuse their helpers
2. Add tests only under test/. Never edit files in src/, even if a test fails
3. Cover the happy path, the error statuses (400, 404) and the { error: "..." } body
4. Run npm test
5. Report: the tests you added, which pass, which fail and why. A failing test that exposes a real bug is a good result: say so, don't fix src/Khi thử thật, chúng tôi gặp một điều đáng nhớ. Với yêu cầu "thêm test cho trường hợp xóa một todo hai lần" mà không nhắc tên, Claude tự làm luôn trong hội thoại chính, dù description có "Use proactively". Việc nhỏ như vậy, Claude thấy tự làm nhanh hơn. "Use proactively" chỉ khuyến khích Claude giao việc, không bảo đảm. Muốn chắc chắn thì gọi tên:
Use the test-writer agent to add a regression test for deleting the same todo twicehoặc gõ @ rồi chọn test-writer (agent) trong danh sách gợi ý. Lần đó Claude giao việc ngay. Subagent chạy trên Sonnet trong khi hội thoại chính chạy Opus, chỉ sửa test/todos.test.js, và báo test mới lỗi vì API trả 500 thay vì 404. Đó đúng là bug cố ý của todo-api, và nó không tự ý sửa src/.
Giờ đến phần "chạy song song". Vì subagent chạy nền, bạn có thể giao cho test-writer viết test cho phần lỗi của PATCH /todos/:id, trong lúc ở hội thoại chính bạn cùng Claude làm một việc khác không đụng tới test/. Hai việc không phụ thuộc nhau, nên không ai phải chờ ai.
Còn vài trường bạn sẽ gặp ở bài sau: skills để nạp sẵn skill, memory để subagent tự ghi nhớ qua các phiên, isolation: worktree để nó làm trên một bản sao riêng của repo. Bài 4.3 dùng chúng để dựng ba mẫu subagent hay gặp nhất: reviewer, tester và debugger.