> ## Documentation Index
> Fetch the complete documentation index at: https://huongdan.luklak.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bài 4 — Sub-agent & Đội hình Agent

> Cách một agent chính điều phối nhiều đại lý con chạy song song. Mỗi con một phòng riêng, cửa sổ ngữ cảnh cách ly, kết quả gom về.

**Điểm cốt lõi của bài này**

<Check>
  **Đại lý con (sub-agent) là cách bạn mở rộng quy mô. Mỗi sub-agent có cửa sổ ngữ cảnh riêng, chạy song song, trả về một tóm tắt ngắn — giữ cho cuộc trò chuyện chính của bạn sạch và tập trung.**
</Check>

## Mở đầu — Ẩn dụ CEO và đội chuyên gia

Hãy tưởng tượng bạn là CEO. Bạn không tự đi dịch từng hợp đồng, viết từng email marketing, rà từng file bảng lương. Bạn **thuê chuyên gia**, giao task rõ ràng, rồi nhận kết quả.

Sub-agent trong Claude Code hoạt động đúng như vậy. Agent chính (main agent) đóng vai CEO — hiểu bức tranh tổng thể, phân rã công việc, giao việc, gom kết quả. **Đại lý con (sub-agent)** là chuyên gia — nhận một task cụ thể, làm trong phòng riêng, trả về báo cáo tóm tắt.

## Vì sao cần sub-agent?

<CardGroup cols={3}>
  <Card title="Cách ly ngữ cảnh (context isolation)" icon="box" iconType="duotone">
    Task phụ như tìm file, phân tích dependency sinh ra hàng nghìn dòng output. Giao cho sub-agent → output đó nằm trong cửa sổ riêng của nó. Cuộc trò chuyện chính của bạn chỉ nhận tóm tắt 1 câu.
  </Card>

  <Card title="Chạy song song (parallelism)" icon="bolt" iconType="duotone">
    7 task độc lập → 7 sub-agent chạy cùng lúc. Thời gian = thời gian của task lâu nhất, không phải tổng thời gian.
  </Card>

  <Card title="Chuyên môn hóa (specialization)" icon="user-gear" iconType="duotone">
    Mỗi sub-agent có system prompt riêng, tool riêng, model riêng. Ví dụ: sub-agent "Explore" chỉ dùng Read/Grep/Glob (read-only), sub-agent "Writer" dùng đầy đủ tool.
  </Card>
</CardGroup>

## Cách ly ngữ cảnh — trực quan hóa

```mermaid theme={null}
flowchart TD
    subgraph MAIN ["🖥️ Cuộc trò chuyện chính của bạn"]
        U[👤 Bạn] --> P[Prompt: Nghiên cứu<br/>architecture của module X]
        P --> M[Main Agent]
        M --> Result[📋 Tóm tắt ngắn<br/>3-5 bullets]
        Result --> U
    end

    M -.delegate task.-> SUB

    subgraph SUB ["🏠 Phòng riêng của Sub-agent"]
        S[Sub-agent Explore] --> G1[Grep: tìm X trong codebase]
        S --> G2[Read: 15 file liên quan]
        S --> G3[Glob: tìm file config]
        G1 --> BUFFER[📚 Cửa sổ ngữ cảnh<br/>cách ly — hàng nghìn dòng<br/>không đổ vào trò chuyện chính]
        G2 --> BUFFER
        G3 --> BUFFER
        BUFFER --> DIST[Chắt lọc + tóm tắt]
    end

    DIST -.return summary.-> Result

    style U fill:#c8e6c9
    style M fill:#e3f2fd
    style S fill:#fff9c4
    style BUFFER fill:#ffccbc
    style Result fill:#c5e1a5
```

Mấu chốt: **cửa sổ ngữ cảnh của bạn không bị bội thực bởi hàng nghìn dòng grep output**. Sub-agent làm việc bẩn bên phòng riêng, trả về một summary sạch sẽ. Đây là cơ chế giúp bạn chạy các task lớn mà không "đốt" context window chính.

## Sub-agent được định nghĩa thế nào

<Info>
  Sub-agent thường được định nghĩa trong file với YAML frontmatter + markdown body. Ví dụ chính thức của Claude Code là `.claude/agents/my-agent.md`.

  **Nhưng** — và đây là điểm quan trọng — **bạn không bắt buộc phải theo cấu trúc này.** Sub-agent có thể được định nghĩa inline trong một prompt, hoặc load từ bất kỳ đường dẫn file nào. Claude Code đọc ý định bạn nói, không đọc quy ước cứng. Bài 5 sẽ cho thấy ví dụ cụ thể.
</Info>

## Hai cách gọi sub-agent

<Tabs>
  <Tab title="Tự động (automatic delegation)">
    Bạn yêu cầu một task phù hợp với description của sub-agent, Claude tự nhận ra và delegate.

    Ví dụ: bạn có sub-agent "Explore" với description *"nghiên cứu codebase"* → khi bạn hỏi *"tìm hiểu dependency của module X"*, Claude tự delegate cho Explore mà không cần bạn chỉ tên.

    Cách này phù hợp khi bạn có một bộ sub-agent ổn định và muốn để agent chính tự quyết chia việc.
  </Tab>

  <Tab title="Thủ công (explicit invocation)">
    Bạn chỉ đích danh sub-agent cần gọi.

    Ví dụ: *"Dùng sub-agent Translator dịch file này."*

    Cách này phù hợp khi bạn muốn kiểm soát chính xác ai làm gì, hoặc khi cùng một task có thể được nhiều sub-agent xử lý và bạn biết rõ mình cần ai.
  </Tab>
</Tabs>

## Sơ đồ đội hình

```mermaid theme={null}
flowchart TD
    U[Bạn] --> M[Agent chính<br/>Main Agent]
    M --> S1[Sub-agent 1<br/>Dịch file A]
    M --> S2[Sub-agent 2<br/>Dịch file B]
    M --> S3[Sub-agent 3<br/>Dịch file C]
    M --> S4[Sub-agent 4<br/>Dịch file D]
    M --> S5[Sub-agent 5<br/>Dịch file E]
    M --> S6[Sub-agent 6<br/>Dịch file F]
    M --> S7[Sub-agent 7<br/>Dịch file G]
    S1 --> M
    S2 --> M
    S3 --> M
    S4 --> M
    S5 --> M
    S6 --> M
    S7 --> M
    M --> U
    style M fill:#e3f2fd
    style U fill:#c8e6c9
```

Agent chính đứng giữa. Bạn chỉ nói chuyện với agent chính. Mỗi sub-agent sống trong một phòng riêng — không nhìn thấy phòng khác, không nhìn thấy bạn. Agent chính gom kết quả và báo lại.

## Ví dụ thực tế: 7 LAIKA function blueprints

<Frame caption="Ví dụ thực tế từ dự án Luklak: 7 sub-agent dịch 7 bản thiết kế LAIKA song song trong ~5 phút.">
  Trong dự án Luklak, chúng tôi cần dịch 7 bản thiết kế chức năng LAIKA từ tiếng Anh sang tiếng Việt. Mỗi bản khoảng 200–280 dòng, đầy bảng biểu, sơ đồ workflow, quy tắc automation — tổng khoảng 1.600 dòng.

  Thay vì làm tuần tự (1.600 dòng × tốc độ gõ = nhiều giờ), chúng tôi spawn 7 sub-agent chạy song song:

  * Marketing (183 dòng)
  * CRM (275 dòng)
  * Project (109 dòng)
  * Design (193 dòng)
  * Construction (286 dòng)
  * Contract (206 dòng)
  * Customer Success (235 dòng)

  **Thời gian thực tế**: khoảng 5 phút wall-time. Nếu làm tuần tự: khoảng 30–40 phút.

  Mỗi sub-agent nhận:

  * Context file EN cần dịch
  * Reference file VI mẫu
  * Tên file output + đường dẫn
  * Quy ước giọng điệu, thuật ngữ

  Mỗi cái chạy độc lập, không biết 6 cái còn lại đang làm. Agent chính gom kết quả, cập nhật `docs.json`, commit và push.
</Frame>

## Khi KHÔNG nên dùng sub-agent

<Warning>
  Không phải task nào cũng cần sub-agent. Tránh dùng khi:

  * **Task đơn giản, chạy nhanh** — delegation overhead không đáng.
  * **Task cần nhiều bước phụ thuộc lẫn nhau** — làm tuần tự rõ ràng hơn, dễ debug hơn.
  * **Bạn cần xem chi tiết mọi tool call** — sub-agent chạy khuất, chỉ trả về tóm tắt; bạn mất khả năng quan sát từng bước.
</Warning>

## Tự kiểm tra

<AccordionGroup>
  <Accordion title="Câu 1: Sub-agent có chia sẻ cửa sổ ngữ cảnh với agent chính không?" icon="circle-question">
    **Không.** Mỗi sub-agent có cửa sổ ngữ cảnh riêng. Agent chính chỉ nhận tóm tắt kết quả — đó chính là lợi ích "cách ly ngữ cảnh (context isolation)". Nhờ vậy, hàng nghìn dòng output trung gian của sub-agent không làm đầy bàn làm việc của agent chính.
  </Accordion>

  <Accordion title="Câu 2: Nếu tôi cần dịch 10 file giống nhau, nên spawn 10 sub-agent?" icon="circle-question">
    **Tùy.** Nếu các file độc lập nhau → có, chạy song song tiết kiệm thời gian. Nếu file này phụ thuộc kết quả file kia (ví dụ: file 2 cần đọc glossary do file 1 sinh ra) → không, làm tuần tự rõ ràng hơn.
  </Accordion>

  <Accordion title="Câu 3: Sub-agent có bắt buộc định nghĩa trong thư mục `.claude/agents/`?" icon="circle-question">
    **Không.** Đó chỉ là convention chính thức. Bạn có thể định nghĩa inline trong prompt, hoặc trong bất kỳ file nào — Claude đọc ý định, không đọc cấu trúc cứng. Bài 5 sẽ minh họa một kiến trúc agent thực tế không theo convention mặc định mà vẫn chạy tốt.
  </Accordion>
</AccordionGroup>

## Bài tập

<Steps>
  <Step title="Xem danh sách skill của Lulu">
    Mở thư mục `luklak-mintlify-docs/Lulu/02-skills/` (nếu có), hoặc đọc trước danh sách 8 skill sẽ xuất hiện ở Bài 5.
  </Step>

  <Step title="Chọn 3 skill để thử">
    Gợi ý: `translate-en-to-vi`, `quality-gate-review`, `glossary-lookup`.
  </Step>

  <Step title="Ghép skill với task">
    Với mỗi task dưới đây, chọn skill phù hợp:

    * *"Kiểm tra bài viết tiếng Việt này có dùng sai thuật ngữ không"* → `quality-gate-review`
    * *"Dịch bài EN sang tiếng Việt theo chuẩn Lulu"* → `translate-en-to-vi`
    * *"Thuật ngữ này nên dịch là gì?"* → `glossary-lookup`
  </Step>

  <Step title="Viết một prompt mẫu">
    Viết một prompt yêu cầu agent chính gọi 1 skill cho 1 task cụ thể của bạn. Ví dụ: *"Dùng skill translate-en-to-vi để dịch file `intro.md` sang tiếng Việt, output ra `intro.vi.md`."*
  </Step>
</Steps>

## Tiếp theo?

* [Bài 5 — Ví dụ thực tế: Lulu DocOps](/06-academy/claude-code/vi-du-thuc-te-lulu)
* [Quay lại Bài 3 — Công cụ & Vòng lặp](/06-academy/claude-code/cong-cu-va-vong-lap)