Bài 8 — Subagents

#Vấn đề: một session không thể gánh mọi thứ

Bạn đang refactor module authentication. Task lớn, nhiều file. Mỗi lần agent đọc thêm file, context window phình thêm. Đến file thứ 15, agent bắt đầu quên những gì bạn nói ở đầu session. Đến file thứ 20, nó gợi ý lại giải pháp mà bạn đã reject 10 phút trước.

Bạn thử /compact — context ngắn lại, nhưng bản tóm tắt bỏ sót chi tiết quan trọng. Bạn thử /clear — mất toàn bộ context, phải giải thích lại từ đầu.

Đây là giới hạn cố hữu của single session. Và đây chính là lý do subagents tồn tại.

#Subagents là gì?

Subagent là một agent con được tạo ra để xử lý một task cụ thể. Điểm quan trọng nhất: subagent có context window riêng — nó không chia sẻ context với session chính.

Think of nó như thuê một freelancer cho một phần việc cụ thể. Bạn giao task, freelancer làm xong, trả kết quả. Bạn không cần freelancer biết toàn bộ dự án — chỉ cần biết phần liên quan đến task của nó.

Khi bạn giao một task lớn cho Claude Code, agent chính có thể tự động spawn subagents. Mỗi subagent:

• Có context window riêng — không phình context của session chính
• Chỉ nhận thông tin cần thiết cho task của nó
• Trả kết quả về cho agent chính
• Kết thúc sau khi hoàn thành — context của nó được giải phóng

#Tại sao phải tách subagents?

#Vấn đề context window

Giả dụ bạn có task: "Tìm và fix tất cả TypeScript errors trong src/". Project có 200 file, 15 lỗi rải rác khắp nơi.

Cách tiếp cận một session:

1. Agent đọc file 1 → tìm lỗi → sửa
2. Agent đọc file 2 → tìm lỗi → sửa
3. ...lặp lại cho 15 file
4. Đến file thứ 10, context window đầy
5. Agent quên mất đã sửa file 3 → gợi ý sửa lại
6. Bạn phải can thiệp, giải thích, mất thời gian

Cách tiếp cận với subagents:

1. Agent chính phân tích task, chia thành 5 nhóm file
2. Spawn 5 subagents, mỗi subagent xử lý 1 nhóm
3. Mỗi subagent có context riêng — chỉ chứa file của nhóm nó
4. Kết quả trả về agent chính — tổng hợp, báo cáo
5. Context của session chính vẫn sạch

#Song song hóa

Subagents chạy song song. 5 subagents cùng lúc nhanh hơn 1 agent xử lý tuần tự 5 lần. Với task lớn, hiệu suất cải thiện rõ rệt.

#Agent teams: nhiều agent cùng chạy

Agent teams là mở rộng của subagents — nhiều agents chạy đồng thời, mỗi agent phụ trách một phần của task phức tạp.

Ví dụ thực tế. Task: "Tạo feature checkout mới — bao gồm frontend component, API endpoint, database migration, và test."

Thay vì một agent làm tuần tự 4 phần:

1. Agent 1: Tạo frontend component trong src/components/Checkout.tsx
2. Agent 2: Tạo API endpoint trong src/api/checkout.ts
3. Agent 3: Viết database migration trong migrations/add_checkout_table.sql
4. Agent 4: Viết test cho cả 3 phần trên

4 agents chạy đồng thời. Agent chính tổng hợp kết quả khi tất cả hoàn thành.

Lưu ý quan trọng: agent teams hoạt động tốt nhất khi các task độc lập — không phụ thuộc vào kết quả của nhau. Nếu agent 2 cần biết interface mà agent 1 tạo ra, bạn cần chia phase: phase 1 tạo interface, phase 2 các agents song song dựa trên interface đó.

#Background agents: chạy ngầm, quay lại sau

Background agents là subagents chạy trong background — bạn không cần ngồi chờ.

Khi bạn giao task cho background agent, nó sẽ:

1. Nhận task
2. Chạy ngầm trong background
3. Bạn tiếp tục làm việc khác
4. Khi hoàn thành, bạn kiểm tra kết quả tại claude.ai/code

Khi nào dùng background agents:

• Task lớn, mất nhiều thời gian (refactor 50+ file, chạy full test suite)
• Task bạn không cần kết quả ngay (generate documentation, analyze codebase)
• Muốn làm song song nhiều task

Ví dụ:

> Chạy background agent: phân tích toàn bộ codebase và tạo document
  cho tất cả public APIs trong src/

Agent spawn background task, bạn tiếp tục coding. 10 phút sau, vào claude.ai/code xem kết quả.

⚠️ Cẩn thận: Background agents không phải "set and forget"

Background agents vẫn có thể gặp lỗi, đọc sai file, hoặc tạo output không đúng ý. Hãy kiểm tra kết quả khi chúng hoàn thành — đừng assume mọi thứ đều OK chỉ vì không có error message. Đặc biệt với task generate code, luôn review diff trước khi merge.

#Skills: gói workflow dùng lại được

Skills là các workflow được đóng gói, load on demand. Thay vì mỗi lần giải thích lại cách làm một task, bạn tạo skill — một lần — rồi gọi lại bất kỳ lúc nào.

Ví dụ: Bạn có workflow review PR — đọc diff, check convention, chạy test, tóm tắt thay đổi. Thay vì mỗi lần gõ 5 câu lệnh, bạn tạo skill:

/review-pr

Skill tự động thực hiện toàn bộ workflow.

Skills khác subagents ở điểm nào? Skills là định nghĩa workflow (cái gì cần làm). Subagents là cách thực thi (ai làm, context nào). Bạn có thể có skill mà bên trong spawn nhiều subagents.

#Khi nào dùng subagents vs một session?

#Anti-pattern: làm tất cả trong một session

Đây là sai lầm phổ biến nhất khi mới bắt đầu dùng Claude Code cho task lớn.

❌ "Refactor toàn bộ module user: sửa model, sửa controller, sửa routes,
   sửa test, migrate database, cập nhật documentation — tất cả trong
   một session."

Session sẽ đầy context sau 15-20 phút. Agent quên, lặp, sai. Bạn frustrated.

✅ "Refactor module user — chia thành các subtask:
   1. Migration database schema
   2. Cập nhật model layer
   3. Cập nhật controller layer
   4. Cập nhật routes
   5. Fix test
   Chạy mỗi subtask trong subagent riêng, tổng hợp kết quả."

Mỗi subagent có context sạch, focused vào task của nó. Agent chính chỉ cần biết tổng hợp — context nhẹ hơn nhiều.

#Demo: Quan sát subagents trong thực tế

Mở Claude Code trong một project có nhiều file:

cd ~/my-project
claude

Thử một task mà agent tự nhiên muốn spawn subagents:

> Tìm tất cả console.log trong src/, liệt kê file và dòng,
  rồi đề xuất cách thay thế bằng structured logging

Với project lớn, agent sẽ tự động chia task — mỗi subagent scan một phần của src/. Quan sát trong output: bạn sẽ thấy nhiều agents chạy đồng thời, mỗi agent báo cáo phần của nó.

Nếu agent không tự spawn, bạn có thể gợi ý:

> Dùng subagents để scan song song: mỗi agent xử lý 1 thư mục con trong src/

#Cách tối ưu khi dùng subagents

1. Chia task rõ ràng trước khi spawn. Mô tả cụ thể subagent cần làm gì, file nào liên quan, output mong muốn là gì.

2. Giới hạn scope mỗi subagent. Đừng giao "fix toàn bộ project" cho một subagent — chia nhỏ.

3. Tổng hợp kết quả ở session chính. Agent chính nhận output từ subagents, tổng hợp, báo cáo cho bạn. Bạn không cần đọc output thô từ từng subagent.

4. Dùng background cho task lớn. Nếu task mất hơn 5 phút, spawn background agent thay vì ngồi chờ.

5. Kết hợp với /clear. Sau khi tổng hợp subagents, /clear session chính để giải phóng context cho task tiếp theo.

#Bài tập thực hành

#Bài tập 1: Quan sát subagent tự nhiên

Mở Claude Code trong project có 10+ file trong src/. Gửi prompt:

> Kiểm tra tất cả file trong src/ có import deprecated không.
  Liệt kê file, dòng, và import nào cần thay thế.

Quan sát: agent có tự spawn subagents không? Nếu có, bao nhiêu subagents? Nếu không, thử lại với hướng dẫn rõ ràng hơn.

#Bài tập 2: So sánh một session vs subagents

Chọn một task phức tạp (ví dụ: tìm và fix tất cả ESLint errors trong src/).

• Lần 1: Chạy trong một session. Ghi lại thời gian, số lần context đầy, số lần phải can thiệp.
• Lần 2: Hướng dẫn agent dùng subagents. Ghi lại thời gian, số lần context đầy, số lần phải can thiệp.

So sánh kết quả.

#Bài tập 3: Thử background agent

Spawn một background agent cho task lớn:

> Chạy background agent: phân tích codebase và tạo README cho project này,
  bao gồm: mô tả project, cách cài đặt, cấu trúc thư mục, cách đóng góp.

Tiếp tục làm việc khác trong session chính. Sau 5-10 phút, kiểm tra kết quả tại claude.ai/code.

#Tổng kết

Subagents giải quyết giới hạn lớn nhất của single session: context window bị đầy khi task lớn. Mỗi subagent có context riêng, chạy song song, và giải phóng context sau khi hoàn thành. Background agents nâng cao hơn nữa — chạy ngầm, bạn kiểm tra kết quả sau.

Nguyên tắc: task nhỏ dùng một session, task lớn dùng subagents, task rất lớn dùng background agents. Đừng cố gánh mọi thứ trong một context window.

Bài tiếp theo: Hướng dẫn chi tiết cách tạo và quản lý CLAUDE.md — file mà agent đọc mỗi session, nơi bạn ghi convention, context, và hướng dẫn cho agent.