# Hướng dẫn sử dụng Skill Agent AI (Antigravity Kit)

# Chương 1: Giới thiệu chung

# Trang 1.1: Tổng quan về Antigravity Kit (Định nghĩa, mục tiêu và lợi ích).

## 1. Antigravity Kit là gì?

**Antigravity Kit** là một bộ mẫu (template) toàn diện dành cho AI Agent, được thiết kế để nâng cao đáng kể năng lực của các trợ lý lập trình AI — đặc biệt là **Google Gemini** (dùng trong môi trường Antigravity CLI).

Bộ kit này không phải là một ứng dụng độc lập. Thay vào đó, nó đóng vai trò là **"não bộ mở rộng"** — một hệ thống quy tắc, kiến thức chuyên sâu và quy trình làm việc được cài đặt vào trong dự án của bạn. Khi AI đọc và hiểu các quy tắc này, nó sẽ hoạt động giống như một chuyên gia thực thụ thay vì một trợ lý AI thông thường.

> **Tóm lại:** Antigravity Kit biến AI trợ lý thành một đội ngũ chuyên gia kỹ thuật hoàn chỉnh, sẵn sàng làm việc cùng bạn theo đúng tiêu chuẩn và quy trình chuyên nghiệp nhất.

## 2. Mục tiêu

Bộ kit được xây dựng với các mục tiêu cụ thể sau:

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-m%E1%BB%A5c-ti%C3%AAu-m%C3%B4-t%E1%BA%A3-ti%C3%AAu-"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mục tiêu</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mô tả</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Tiêu chuẩn hóa**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Đảm bảo AI luôn áp dụng các tiêu chuẩn code, thiết kế và kiến trúc nhất quán trong mọi dự án.</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Chuyên môn hóa**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Trang bị cho AI kiến thức sâu theo từng lĩnh vực (Frontend, Backend, Bảo mật, Mobile...) thay vì kiến thức chung chung.</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Tự động hóa**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Cung cấp các quy trình làm việc (Workflows) được định nghĩa sẵn để AI có thể thực hiện các tác vụ phức tạp một cách có hệ thống.</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Tăng tốc**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Giúp đội ngũ phát triển xây dựng phần mềm nhanh hơn mà không giảm chất lượng.</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Phối hợp đa AI**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Cho phép nhiều AI Agent cùng phối hợp làm việc song song trên một dự án phức tạp.</td></tr></tbody></table>

</div>## 3. Thành phần chính

Antigravity Kit bao gồm **3 thành phần cốt lõi**, được cài đặt vào trong thư mục `.agent/` của mỗi dự án:

### 3.1. Agents (Đặc vụ AI) — 20 Agent

Là các "nhân cách chuyên gia" được cấu hình sẵn để AI có thể đóng vai trò của họ khi cần thiết.

**Ví dụ các Agent tiêu biểu:**

- `frontend-specialist`: Chuyên gia giao diện web (React, Next.js, Tailwind).
- `backend-specialist`: Chuyên gia logic API và máy chủ (Node.js, FastAPI).
- `security-auditor`: Chuyên gia bảo mật, kiểm tra lỗ hổng và OWASP.
- `debugger`: Chuyên gia phân tích và sửa lỗi có hệ thống.
- `project-planner`: Chuyên gia lập kế hoạch và phân rã công việc.
- `orchestrator`: Điều phối nhiều Agent cùng làm việc cho tác vụ phức tạp.
- *(và 14 Agent khác bao gồm Mobile, Game, DevOps, QA, SEO...)*

### 3.2. Skills (Kỹ năng) — 36 Skills

Là các gói kiến thức chuyên sâu mà Agent có thể tải và áp dụng tùy theo từng ngữ cảnh.

**Ví dụ các Skills tiêu biểu:**

- `react-best-practices`: Tối ưu hiệu năng React &amp; Next.js theo tiêu chuẩn Vercel.
- `api-patterns`: Thiết kế API chuẩn REST / GraphQL / tRPC.
- `database-design`: Thiết kế schema, chiến lược index, tối ưu truy vấn.
- `systematic-debugging`: Quy trình 4 bước để tìm và sửa lỗi có bằng chứng.
- `vulnerability-scanner`: Phân tích bảo mật theo OWASP 2025.
- `ui-ux-pro-max`: Bộ 50 phong cách thiết kế giao diện cao cấp.

### 3.3. Workflows (Quy trình làm việc) — 11 Workflows

Là các quy trình được định nghĩa sẵn, kích hoạt bằng **lệnh gạch chéo** (`/`), giúp AI thực hiện toàn bộ một tác vụ phức tạp theo đúng trình tự.

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-l%E1%BB%87nh-t%C3%A1c-v%E1%BB%A5-%2Fbrainst"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Lệnh</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Tác vụ</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/brainstorm`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Lên ý tưởng và so sánh các giải pháp</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/plan`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tạo kế hoạch chi tiết trước khi viết code</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/create`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Xây dựng ứng dụng/tính năng mới từ đầu</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/enhance`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Cải tiến và nâng cấp code hiện có</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/debug`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Sửa lỗi theo quy trình 4 giai đoạn</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/test`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tạo và chạy bộ kiểm thử tự động</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/ui-ux-pro-max`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tạo landing page chất lượng cao</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/deploy`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Triển khai ứng dụng lên môi trường production</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/preview`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Quản lý server xem trước ở máy cục bộ</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/status`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Xem tổng quan tiến độ dự án</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/orchestrate`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Điều phối nhiều Agent phối hợp cùng lúc</td></tr></tbody></table>

</div>---

## 4. Cách thức hoạt động

Antigravity Kit hoạt động theo nguyên tắc **"Đọc – Hiểu – Áp dụng"**:

**Bước 1: Cài đặt vào dự án.** Khi bạn chạy lệnh cài đặt, một thư mục `.agent/` sẽ được tạo ra trong dự án của bạn. Thư mục này chứa toàn bộ cấu hình cho 20 Agent, 36 Skills và 11 Workflows.

**Bước 2: AI chủ động đọc cấu hình.** Khi bạn mở cuộc trò chuyện với AI trong dự án, AI sẽ đọc các file cấu hình trong thư mục `.agent/` — bao gồm file quy tắc chính `GEMINI.md` và file kiến trúc

<div id="bkmrk--1">  
</div><span class="inline-flex break-all leading-tight">ARCHITECTURE.md</span>.

**Bước 3: Hệ thống Định tuyến thông minh (Intelligent Routing) tự kích hoạt.** Khi bạn đặt câu hỏi hoặc yêu cầu AI làm gì đó, hệ thống sẽ **tự động phân tích** yêu cầu và kích hoạt Agent chuyên gia phù hợp nhất. **Bạn không cần phải gõ tên Agent thủ công.**

```html
Ví dụ:
Bạn: "Thêm xác thực JWT vào API"
AI:  🤖 Đang áp dụng kiến thức của @security-auditor + @backend-specialist...
     [AI phân tích bảo mật và đề xuất triển khai đúng chuẩn]
Bạn: "Sửa lỗi button dark mode bị lẫn màu"
AI:  🤖 Đang áp dụng kiến thức của @frontend-specialist...
     [AI kiểm tra logic CSS và đưa ra fix cụ thể]
```

**Bước 4: Skills được tải tự động theo yêu cầu.** Agent được kích hoạt sẽ chỉ tải đúng các module kiến thức (Skills) cần thiết cho tác vụ hiện tại. Ví dụ: `backend-specialist` khi làm việc với database sẽ tải thêm skill `database-design`, không tải các skill không liên quan.

---

## 5. Lợi ích thực tế

**Đối với lập trình viên cá nhân:**

- Nhận được phản hồi ở mức độ chuyên gia thay vì câu trả lời chung chung.
- Có một "đồng đội AI" hiểu ngữ cảnh dự án và tuân theo tiêu chuẩn nhất quán.
- Tiết kiệm thời gian tra cứu tài liệu và học các pattern mới.

**Đối với đội nhóm phát triển:**

- Đảm bảo mọi thành viên sử dụng AI theo cùng một bộ tiêu chuẩn đã được đội ngũ thống nhất.
- Dễ dàng chia sẻ "kiến thức dự án" giữa các thành viên thông qua việc commit thư mục `.agent/` vào Git.
- Rút ngắn thời gian onboarding cho thành viên mới.

---

## 6. Thống kê nhanh

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-th%C3%A0nh-ph%E1%BA%A7n-s%E1%BB%91-l%C6%B0%E1%BB%A3ng-"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Thành phần</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Số lượng</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mức độ bao phủ</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Specialist Agents</td><td class="px-3 py-2 leading-snug border border-gray-500/20">20</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Web, Mobile, Game, DevOps, Security, QA, SEO...</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Domain Skills</td><td class="px-3 py-2 leading-snug border border-gray-500/20">36</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Frontend, Backend, DB, Testing, Cloud, Architecture...</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Slash Workflows</td><td class="px-3 py-2 leading-snug border border-gray-500/20">11</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Toàn bộ vòng đời phát triển phần mềm</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Scripts kiểm tra</td><td class="px-3 py-2 leading-snug border border-gray-500/20">2 Master + 18</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Security, Lint, Schema, Tests, UX, SEO, Lighthouse</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Tổng độ bao phủ</td><td class="px-3 py-2 leading-snug border border-gray-500/20">~90%</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Các lĩnh vực phát triển web và mobile</td></tr></tbody></table>

</div>> **Ghi chú:** Bộ kit này tương thích và được thiết kế để hoạt động tốt nhất với công cụ Antigravity CLI. Tuy nhiên, các Agent và Skill đều là các file Markdown tiêu chuẩn, có thể được áp dụng cho bất kỳ AI Code Assistant nào hỗ trợ đọc file cấu hình từ workspace (như Cursor, Windsurf, GitHub Copilot...).

# Trang 1.2: Lộ trình phát triển và các thành phần chính (Agents, Skills, Workflows).

## 1. Lịch sử phát triển

Antigravity Kit được phát triển bởi **vudovn** và liên tục được cải tiến dựa trên nhu cầu thực tế từ cộng đồng. Dự án tuân theo chuẩn **Semantic Versioning** (Phiên bản ngữ nghĩa).

### Phiên bản 2.0.0 — Ra mắt chính thức

**Đây là phiên bản nền tảng**, định hình toàn bộ kiến trúc của Antigravity Kit với đầy đủ 3 thành phần cốt lõi:

- Hệ thống **20 AI Agent** chuyên gia theo từng lĩnh vực.
- **37 Skills** — các module kiến thức chuyên sâu có thể tải theo yêu cầu.
- **11 Slash Workflows** — các quy trình làm việc kích hoạt bằng lệnh gạch chéo.
- **CLI Tool** (`ag-kit`) để cài đặt và cập nhật bộ kit một cách dễ dàng.

### Phiên bản 2.0.1 — Tháng 01/2026

**Tập trung vào chất lượng và chuẩn hóa quy trình:**

- Bổ sung <div>  
    </div>**<span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">AGENT\_FLOW.md</span></span></span>** — tài liệu luồng kiến trúc AI Agent toàn diện.
- Tài liệu hóa chính thức **Giao thức Định tuyến Agent** (Agent Routing Checklist) — các bước bắt buộc trước khi AI viết code hoặc thiết kế.
- Tài liệu hóa **Cổng Socratic** (Socratic Gate Protocol) — quy trình hỏi làm rõ yêu cầu trước khi triển khai.
- **Hợp nhất 2 Skills thành 1:** `nextjs-best-practices` + `react-patterns` → `react-best-practices` (gọn hơn, mạnh hơn).
- Thêm Skill mới: `web-design-guidelines` — Chuẩn thiết kế web chuyên nghiệp với hơn 100 quy tắc về UX và Accessibility.
- **Làm rõ thuật ngữ quan trọng:** "Parallel Execution" được đổi thành "Sequential Multi-Domain Execution" để phản ánh chính xác cách AI thực sự hoạt động.

### Phiên bản 2.0.2 — Tháng 02/2026

**Mở rộng sang hệ sinh thái Rust:**

- Thêm Skill mới: **`rust-pro`** — Lập trình hệ thống chuyên sâu với Rust 1.75+ (async, Tokio, axum).
- Cải thiện Workflow `orchestrate.md`.

---

## 2. Kiến trúc tổng thể

Toàn bộ hệ thống Antigravity Kit hoạt động theo mô hình **"Tải theo yêu cầu" (Load on-demand)**:

```html
[ Yêu cầu của người dùng ]
           │
           ▼
[ Hệ thống Định tuyến thông minh ]
   (Đọc GEMINI.md + ARCHITECTURE.md)
           │
           ▼
[ Chọn Agent phù hợp ]
  (frontend-specialist? backend-specialist? debugger?...)
           │
           ▼
[ Agent tải Skills cần thiết ]
  (react-best-practices, api-patterns, systematic-debugging...)
           │
           ▼
[ Trả lời ở cấp độ chuyên gia ]

```

Luồng này đảm bảo rằng:

- AI **không** lãng phí tài nguyên bằng cách tải toàn bộ kiến thức cùng một lúc.
- Mỗi câu trả lời được hỗ trợ bởi **đúng loại kiến thức chuyên sâu** phù hợp với vấn đề.

---

## 3. Thành phần 1: Agents (Đặc vụ AI)

### 3.1. Khái niệm

Mỗi Agent là một **file Markdown** (<span class="inline-flex break-all leading-tight">.md</span>) được lưu trong `.agent/agents/`. File này chứa phần cấu hình YAML và bản mô tả nhân cách/vai trò chuyên môn của AI khi đóng vai trò Agent đó.

**Cấu trúc một file Agent:**

```yaml
---
name: frontend-specialist
description: Frontend architect expert for web applications
tools: Read, Edit, Write, Bash
skills: react-best-practices, frontend-design, tailwind-patterns
---

# Frontend Specialist

Bạn là một kiến trúc sư Frontend cấp cao...
[Các quy tắc, hành vi và kiến thức chuyên sâu về Frontend]

```

### 3.2. Danh sách 20 Agents và vai trò

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-agent-chuy%C3%AAn-m%C3%B4n-orc"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Agent</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Chuyên môn</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`orchestrator`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Điều phối nhiều Agent phối hợp cho tác vụ phức tạp</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`project-planner`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Khám phá yêu cầu và lập kế hoạch chi tiết</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`frontend-specialist`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Giao diện Web (React, Next.js, Tailwind CSS)</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`backend-specialist`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">API, Business Logic, Cơ sở dữ liệu</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`database-architect`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Thiết kế Schema và tối ưu SQL</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`mobile-developer`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">iOS, Android, React Native</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`game-developer`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Logic game, cơ học trò chơi</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`devops-engineer`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">CI/CD, Docker, hạ tầng</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`security-auditor`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra bảo mật và tuân thủ</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`penetration-tester`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Bảo mật tấn công (Offensive Security)</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`test-engineer`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chiến lược kiểm thử toàn diện</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`debugger`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Phân tích nguyên nhân gốc rễ của lỗi</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`performance-optimizer`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tốc độ tải và Web Vitals</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`seo-specialist`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Xếp hạng tìm kiếm và khả năng hiển thị</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`documentation-writer`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Hướng dẫn sử dụng và tài liệu kỹ thuật</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`product-manager`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Yêu cầu nghiệp vụ và câu chuyện người dùng</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`product-owner`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chiến lược sản phẩm và quản lý backlog</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`qa-automation-engineer`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm thử E2E và CI Pipeline</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`code-archaeologist`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Phân tích và tái cấu trúc code cũ (Legacy)</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`explorer-agent`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Khám phá và phân tích codebase hiện có</td></tr></tbody></table>

</div>### 3.3. Cách Agent phối hợp với Skills

Mỗi Agent trong phần cấu hình `skills:` liệt kê các Skills mà Agent đó được phép truy cập. Khi Agent nhận được yêu cầu, nó sẽ quyết định xem cần tải Skills nào và đọc chúng để có đủ kiến thức.

**Ví dụ:**

- `backend-specialist` sử dụng: `api-patterns`, `nodejs-best-practices`, `database-design`
- `security-auditor` sử dụng: `vulnerability-scanner`, `red-team-tactics`
- `debugger` sử dụng: `systematic-debugging`

---

## 4. Thành phần 2: Skills (Kỹ năng)

### 4.1. Khái niệm

Skills là **gói kiến thức module** — không phải code cứng nhắc, mà là các **nguyên lý và khung ra quyết định** giúp AI hiểu *tại sao* nên làm theo cách này thay vì chỉ copy một pattern có sẵn.

> **Khác biệt cốt lõi:** Skills giúp AI đưa ra quyết định phù hợp với ngữ cảnh dự án cụ thể của bạn, không phải câu trả lời mẫu chung chung.

### 4.2. Cấu trúc thư mục một Skill

```html
.agent/skills/
└── react-best-practices/
    ├── SKILL.md          # (Bắt buộc) Siêu dữ liệu và hướng dẫn chính
    ├── sections/         # (Tùy chọn) Hướng dẫn chi tiết từng phần
    ├── examples/         # (Tùy chọn) Ví dụ triển khai tham khảo
    ├── scripts/          # (Tùy chọn) Script Python/Bash hỗ trợ
    └── assets/           # (Tùy chọn) Hình ảnh, logo

```

### 4.3. Danh sách 36 Skills theo nhóm

**Frontend &amp; UI (5 Skills)**

- `react-best-practices` — Tối ưu React &amp; Next.js (57 quy tắc từ Vercel).
- `web-design-guidelines` — Kiểm toán UI web — 100+ quy tắc Accessibility, UX, Performance.
- `tailwind-patterns` — Tailwind CSS v4 và các tiện ích hiện đại.
- `frontend-design` — Hệ thống thiết kế và các UI/UX pattern.
- `ui-ux-pro-max` — 50 phong cách, 21 bảng màu, 50 font chữ.

**Backend &amp; API (4 Skills)**

- `api-patterns` — Thiết kế API (REST, GraphQL, tRPC).
- `nestjs-expert` — NestJS modules, Dependency Injection.
- `nodejs-best-practices` — Node.js async pattern và kiến trúc.
- `python-patterns` — Tiêu chuẩn Python, FastAPI, Django.

**Database (2 Skills)**

- `database-design` — Thiết kế schema và tối ưu hóa.
- `prisma-expert` — Prisma ORM và migrations.

**TypeScript/JavaScript (1 Skill)**

- `typescript-expert` — Lập trình kiểu nâng cao, hiệu năng.

**Cloud &amp; Infrastructure (3 Skills)**

- `docker-expert` — Container hóa và Docker Compose.
- `deployment-procedures` — CI/CD và quy trình deploy.
- `server-management` — Quản lý hạ tầng máy chủ.

**Testing &amp; Quality (5 Skills)**

- `testing-patterns` — Jest, Vitest và các chiến lược kiểm thử.
- `webapp-testing` — Kiểm thử E2E bằng Playwright.
- `tdd-workflow` — Phát triển hướng kiểm thử (TDD).
- `code-review-checklist` — Tiêu chuẩn review code.
- `lint-and-validate` — Linting và validation.

**Security (2 Skills)**

- `vulnerability-scanner` — Kiểm tra bảo mật, OWASP 2025.
- `red-team-tactics` — Bảo mật tấn công, chiến thuật red team.

**Architecture &amp; Planning (4 Skills)**

- `app-builder` — Tạo khung ứng dụng full-stack.
- `architecture` — Các mẫu thiết kế hệ thống.
- `plan-writing` — Lập kế hoạch và phân rã công việc.
- `brainstorming` — Đặt câu hỏi Socratic để làm rõ yêu cầu.

**Mobile (1 Skill), Game (1 Skill), SEO (2 Skills), Shell/CLI (2 Skills), Other (6 Skills)**

- *(Bao gồm: `mobile-design`, `game-development`, `seo-fundamentals`, `geo-fundamentals`, `bash-linux`, `powershell-windows`, `clean-code`, `behavioral-modes`, `parallel-agents`, `mcp-builder`, `documentation-templates`, `i18n-localization`, `performance-profiling`, `systematic-debugging`, `rust-pro`)*

---

## 5. Thành phần 3: Workflows (Quy trình làm việc)

### 5.1. Khái niệm

Workflow là các **file Markdown** được lưu trong `.agent/workflows/`. Mỗi file định nghĩa một quy trình từng bước cụ thể để thực hiện một tác vụ lập trình phổ biến.

**Cách kích hoạt:** Gõ lệnh gạch chéo tương ứng trong cửa sổ chat với AI.

```html
/tên-workflow [mô tả yêu cầu]

```

### 5.2. Tính năng Turbo

Một số bước trong Workflow được đánh dấu `// turbo`. Điều này có nghĩa là AI có thể **tự động chạy lệnh terminal an toàn** ở bước đó mà không cần dừng lại để hỏi bạn, giúp tăng tốc độ thực hiện.

### 5.3. Tùy chỉnh Workflow

Bạn hoàn toàn có thể tự tạo Workflow riêng bằng cách:

1. Tạo file `.md` mới trong thư mục `.agent/workflows/`.
2. Thêm phần mô tả ở đầu file và các bước thực hiện bên dưới.
3. Gọi Workflow bằng cách gõ `/tên-file` trong chat.

**Ví dụ tạo Workflow tùy chỉnh:**

```markdown
---
description: Deploy ứng dụng lên môi trường staging
---

# Quy trình Deploy Staging

1. Chạy toàn bộ test suite
2. Build production bundle
3. Deploy lên server staging
4. Chạy smoke test để xác minh

```

## 6. Thành phần bổ sung: Scripts kiểm tra

Ngoài 3 thành phần chính, Antigravity Kit còn cung cấp **2 script kiểm tra tổng thể** bằng Python trong thư mục `.agent/scripts/`:

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-script-m%E1%BB%A5c-%C4%91%C3%ADch-khi-"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Script</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mục đích</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Khi nào dùng</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`checklist.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra ưu tiên (Core checks)</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Trong quá trình phát triển, trước khi commit</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`verify_all.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra toàn diện (Full suite)</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Trước khi release lên production</td></tr></tbody></table>

</div>**Checklist.py kiểm tra theo thứ tự ưu tiên:**

- **P0:** Bảo mật (Lỗ hổng, secrets bị lộ).
- **P1:** Chất lượng code (Lint, Type check).
- **P2:** Kiểm tra Schema cơ sở dữ liệu.
- **P3:** Chạy bộ test tự động.
- **P4:** Kiểm tra UX và Accessibility.
- **P5:** Kiểm tra SEO.
- **P6:** Hiệu năng (Lighthouse — cần cung cấp URL).

---

> **Lưu ý về phiên bản:** Thông tin trong tài liệu này phản ánh bộ kit **phiên bản 2.0.2**. Để xem lịch sử thay đổi đầy đủ, tham khảo file `CHANGELOG.md` trong thư mục gốc của dự án hoặc trang [GitHub của dự án](https://github.com/vudovn/antigravity-kit).

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--6" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5"><div class="font-sans text-sm text-ide-text-color opacity-60">  
</div><div class="flex flex-row gap-2 justify-end">  
</div></div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1">  
</div></div></div></div></div>

# Chương 2: Cài đặt & Thiết lập hệ thống

# Trang 2.1: Yêu cầu hệ thống (Chi tiết về phiên bản Node.js >= 16 và Python >= 3.10).

## 1. Tóm tắt yêu cầu

Trước khi cài đặt Antigravity Kit, hãy đảm bảo máy tính của bạn đã đáp ứng các yêu cầu tối thiểu sau:

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-th%C3%A0nh-ph%E1%BA%A7n-phi%C3%AAn-b%E1%BA%A3n"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Thành phần</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Phiên bản tối thiểu</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mục đích sử dụng</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Node.js**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">16.0 hoặc mới hơn</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chạy công cụ CLI `ag-kit` và ứng dụng web</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**npm** hoặc **yarn**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Đi kèm với Node.js</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Quản lý gói phụ thuộc</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Python**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">3.10 hoặc mới hơn</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chạy các script kiểm tra tự động của Kit</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Git**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Bất kỳ phiên bản nào</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Cập nhật Kit và quản lý phiên bản</td></tr></tbody></table>

</div>---

## 2. Node.js

### Tại sao cần Node.js?

Công cụ dòng lệnh `ag-kit` được xây dựng trên nền tảng Node.js. Bạn cần Node.js để:

- Chạy lệnh `npx @vudovn/ag-kit init` để cài đặt bộ kit.
- Sử dụng lệnh `ag-kit` nếu cài đặt toàn cục.

### Kiểm tra phiên bản Node.js

Mở Terminal (Command Prompt / PowerShell) và chạy:

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--1" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```bash
bash
node --version
```

Kết quả hợp lệ phải hiển thị phiên bản **&gt;= 16.0**, ví dụ: `v20.11.0`.

### Cài đặt Node.js

Nếu chưa có, tải và cài đặt từ trang chính thức:

- **Khuyến nghị:** [nodejs.org](https://nodejs.org/) — Chọn phiên bản **LTS (Long Term Support)** để đảm bảo ổn định.

> **Mẹo:** Nên cài đặt phiên bản Node.js LTS mới nhất (hiện tại là **Node.js 20.x LTS**) để có sự tương thích tốt nhất với tất cả các gói npm hiện đại.

---

## 3. Python

### Tại sao cần Python?

Các script kiểm tra chất lượng tự động của Antigravity Kit (<span class="inline-flex break-all leading-tight">checklist.py</span>, <span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">verify\_all.py</span></span></span>) và nhiều script con trong từng Skill đều được viết bằng Python. Để các tính năng tự động hóa hoạt động, Python phải:

1. Được cài đặt trên máy tính.
2. Có thể gọi bằng lệnh `python` (hoặc `python3`) từ bất kỳ vị trí nào trong Terminal.

### Kiểm tra phiên bản Python

```bash
python --version

```

Kết quả hợp lệ phải hiển thị phiên bản **&gt;= 3.10**, ví dụ: `Python 3.12.1`.

### Cài đặt Python (Windows)

<div id="bkmrk-t%E1%BA%A3i-t%E1%BB%AB-python.org.-t">1. Tải từ [python.org](https://www.python.org/downloads/).
2. Trong quá trình cài đặt, **bắt buộc phải tích chọn** vào ô **"Add Python to PATH"** ở màn hình đầu tiên của trình cài đặt.
3. Sau khi cài xong, mở lại Terminal mới và chạy `python --version` để xác nhận.

  
</div>> <div>**Lưu ý quan trọng (Windows):** Nếu bỏ qua bước tích chọn "Add Python to PATH", lệnh `python` sẽ không được nhận dạng và các script kiểm tra của Kit sẽ không hoạt động. Bạn có thể khắc phục bằng cách gỡ cài đặt và cài lại Python với tùy chọn đó.</div>

### Cài đặt Python (macOS / Linux)

```bash
# macOS (dùng Homebrew)
brew install python3

# Ubuntu / Debian
sudo apt update && sudo apt install python3 python3-pip

```

## 4. Git

### Tại sao cần Git?

- Lệnh `ag-kit update` dùng Git để tải phiên bản mới nhất của bộ kit từ GitHub.
- Cho phép bạn commit thư mục `.agent/` vào repository của dự án để chia sẻ cấu hình với cả đội.

### Kiểm tra phiên bản Git

```bash
bash
git --version
```

Kết quả hợp lệ ví dụ: `git version 2.43.0`.

### Cài đặt Git

- **Windows:** Tải từ [git-scm.com](https://git-scm.com/).
- **macOS:** Chạy `brew install git` hoặc cài Xcode Command Line Tools.
- **Linux:** `sudo apt install git` (Ubuntu/Debian) hoặc `sudo dnf install git` (Fedora).

---

## 5. Kiểm tra nhanh toàn bộ hệ thống

Chạy các lệnh sau để kiểm tra tất cả thành phần cùng lúc:

```bash
node --version   # Kiểm tra Node.js
npm --version    # Kiểm tra npm
python --version # Kiểm tra Python
git --version    # Kiểm tra Git

```

Nếu tất cả đều trả về số phiên bản hợp lệ, hệ thống của bạn đã sẵn sàng để cài đặt Antigravity Kit.

---

## 6. Hệ điều hành được hỗ trợ

Antigravity Kit tương thích với tất cả các hệ điều hành phổ biến:

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-h%E1%BB%87-%C4%91i%E1%BB%81u-h%C3%A0nh-tr%E1%BA%A1ng-t"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Hệ điều hành</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Trạng thái</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Ghi chú</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Windows 10/11**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Được hỗ trợ đầy đủ</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Có thể dùng Command Prompt, PowerShell hoặc Windows Terminal</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**macOS**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Được hỗ trợ đầy đủ</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Khuyến nghị dùng iTerm2 hoặc Terminal tích hợp sẵn</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Linux (Ubuntu, Debian, Fedora...)**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Được hỗ trợ đầy đủ</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Dùng bất kỳ terminal chuẩn nào</td></tr></tbody></table>

</div>---

> **Sau khi đảm bảo đủ các yêu cầu trên**, hãy chuyển sang **Trang 2.2: Hướng dẫn cài đặt nhanh** để tiến hành cài đặt Antigravity Kit vào dự án của bạn.

# Trang 2.2: Hướng dẫn cài đặt nhanh (Sử dụng lệnh npx).

## 1. Trước khi bắt đầu

Đảm bảo các yêu cầu hệ thống đã được đáp ứng (tham khảo **Trang 2.1: Yêu cầu hệ thống**):

- ✅ Node.js &gt;= 16.0
- ✅ Python &gt;= 3.10 (trong PATH)
- ✅ Git

---

## 2. Phương pháp 1: Cài đặt nhanh bằng `npx` (Khuyến nghị)

Đây là cách **nhanh nhất và đơn giản nhất** để bắt đầu. Bạn không cần cài bất kỳ thứ gì lên toàn bộ máy tính.

### Bước 1: Di chuyển vào thư mục dự án

Mở Terminal và di chuyển vào thư mục gốc của dự án bạn muốn cài đặt:

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--1" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```bash
bash
cd đường/dẫn/đến/dự-án-của-bạn
```

**Ví dụ:**

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--2" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="5" data-line-number="5" data-line-start="5"><div class="line-content"></div></div></div></div></div></div>```bash
bash
# Windows
cd C:\Users\ten-ban\Projects\my-awesome-project


# macOS / Linux
cd ~/Projects/my-awesome-project
```

### Bước 2: Chạy lệnh cài đặt

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--3" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```bash
bash
npx @vudovn/ag-kit init
```

`npx` sẽ tự động tải công cụ `ag-kit` về (tạm thời) và chạy lệnh khởi tạo. Bạn **không cần** cài đặt gì trước đó.

### Bước 3: Chờ quá trình hoàn tất

Quá trình cài đặt sẽ tự động:

1. Kết nối với GitHub để tải phiên bản mới nhất.
2. Tạo thư mục `.agent/` trong dự án của bạn.
3. Bơm toàn bộ 20 Agents, 36 Skills và 11 Workflows vào đó.

Khi hiển thị thông báo thành công, quá trình cài đặt đã hoàn tất.

---

## 3. Phương pháp 2: Cài đặt toàn cục (`Global Install`)

Phương pháp này phù hợp nếu bạn làm việc với **nhiều dự án khác nhau** và muốn dùng lệnh `ag-kit` từ bất kỳ đâu.

### Bước 1: Cài đặt `ag-kit` lên toàn bộ máy

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--5" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```bash
bash
npm install -g @vudovn/ag-kit
```

Lệnh này chỉ cần chạy **một lần duy nhất** trên máy tính của bạn.

### Bước 2: Xác nhận cài đặt thành công

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--6" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```bash
bash
ag-kit --version
```

Nếu hiển thị số phiên bản, cài đặt toàn cục đã thành công.

### Bước 3: Khởi tạo vào từng dự án

Mỗi khi muốn tích hợp vào một dự án mới, di chuyển vào thư mục dự án đó và chạy:

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--7" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"></div></div></div></div></div></div>```bash
bash
cd đường/dẫn/đến/dự-án
ag-kit init
```

---

## 4. Điều gì xảy ra sau khi cài đặt?

Sau khi cài đặt thành công, một thư mục `.agent/` sẽ xuất hiện trong dự án của bạn với cấu trúc như sau:

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--9" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5"><div class="font-sans text-sm text-ide-text-color opacity-60">  
</div><div class="flex flex-row gap-2 justify-end">  
</div></div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1">  
</div><div class="code-line" data-line-end="12" data-line-number="12" data-line-start="12"><div class="line-content"></div></div></div></div></div></div>```html
your-project/
├── src/
├── package.json
├── ...
└── .agent/ ← Thư mục mới được tạo ra
├── ARCHITECTURE.md # Tài liệu kiến trúc tổng thể của Kit
├── AGENT_FLOW.md # Sơ đồ luồng hoạt động của các Agent
├── agents/ # 20 file cấu hình Specialist Agent
├── skills/ # 36 thư mục Knowledge Module (Skills)
├── workflows/ # 11 file quy trình làm việc (Workflows)
├── rules/ # Quy tắc hành vi toàn cục (GEMINI.md)
└── scripts/ # Script kiểm tra Python tổng thể
```

Từ thời điểm này, khi bạn mở dự án và bắt đầu trò chuyện với AI, nó sẽ tự động đọc các cấu hình trong thư mục `.agent/` và hoạt động như một đội chuyên gia.

---

## 5. Quan trọng: Cấu hình <span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">.gitignore</span></span></span>

### Vấn đề

Nếu bạn đang dùng các trình soạn thảo AI như **Cursor** hoặc **Windsurf**, việc thêm `.agent/` vào

<div id="bkmrk--11">  
</div><span class="inline-flex break-all leading-tight">.gitignore</span> sẽ khiến IDE không index được thư mục này. Hậu quả là các **Slash Commands** (như `/plan`, `/debug`) sẽ **không xuất hiện** trong dropdown gợi ý của chat.

### Giải pháp được khuyến nghị

**Không** thêm `.agent/` vào file

<div id="bkmrk--12">  
</div><span class="inline-flex break-all leading-tight">.gitignore</span> chung của dự án. Thay vào đó, thêm vào file **local git exclude** (chỉ áp dụng trên máy tính của bạn):

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--13" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"></div></div></div></div></div></div>```bash
bash
# Mở file local exclude
echo ".agent/" >> .git/info/exclude
```

Cách này giúp:

- ✅ Git **không** track thư mục `.agent/` lên remote repository.
- ✅ IDE vẫn **index** được thư mục để Slash Commands hoạt động.
- ✅ Thư mục `.agent/` hoàn toàn **cục bộ** (local) và không ảnh hưởng đến <div>  
    </div><span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">.gitignore</span></span></span> chung.

> **Lưu ý:** Nếu bạn muốn **chia sẻ cấu hình Kit** với toàn bộ đội ngũ (khuyến nghị cho các dự án nhóm), hãy commit thư mục `.agent/` bình thường vào Git. Cách này đảm bảo mọi người trong đội đều dùng cùng một bộ Agent, Skill và Workflow đã được thống nhất.

---

## 6. Cập nhật lên phiên bản mới

Khi có phiên bản mới của Antigravity Kit, bạn có thể cập nhật bằng lệnh:

```bash
bash
ag-kit update
```

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--15" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>> ⚠️ **Cảnh báo:** Lệnh `update` sẽ **xóa và thay thế toàn bộ** thư mục `.agent/` bằng phiên bản mới nhất. Nếu bạn có các Workflow hoặc Agent tùy chỉnh, hãy **sao lưu** trước khi cập nhật.

---

## 7. Xử lý sự cố thường gặp

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-v%E1%BA%A5n-%C4%91%E1%BB%81-nguy%C3%AAn-nh%C3%A2n-g"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Vấn đề</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Nguyên nhân</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Giải pháp</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`npx: command not found`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Node.js chưa được cài đặt</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Cài đặt Node.js từ nodejs.org</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`ag-kit: command not found`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Cài đặt toàn cục chưa thành công</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chạy lại `npm install -g @vudovn/ag-kit`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Thư mục `.agent/` đã tồn tại</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Đã cài đặt trước đó</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Thêm tham số `--force`: `ag-kit init --force`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Script Python không chạy</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Python không có trong PATH</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Cài lại Python với tùy chọn "Add to PATH"</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Slash commands không hiện</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`.agent/` bị trong <div>  
</div><span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">.gitignore</span></span></span></td><td class="px-3 py-2 leading-snug border border-gray-500/20">Dùng <div>  
</div><span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">.git/info/exclude</span></span></span> thay thế (xem Mục 5)</td></tr></tbody></table>

</div>---

> **Bước tiếp theo:** Sau khi cài đặt thành công, hãy đọc **Trang 3.1: AI Agents và cơ chế định tuyến thông minh** để hiểu cách tận dụng tối đa bộ kit.

# Trang 2.3: Cài đặt toàn cục (Global Install) và cấu hình biến môi trường PATH.

## 1. Cài đặt toàn cục là gì?

**Cài đặt toàn cục (Global Install)** có nghĩa là bộ công cụ `ag-kit` được cài đặt ở cấp độ **toàn bộ hệ thống** thay vì chỉ trong một dự án cụ thể. Sau khi cài toàn cục, bạn có thể gõ lệnh `ag-kit` từ bất kỳ thư mục nào trên máy tính.

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-%C2%A0-c%C3%A0i-%C4%91%E1%BA%B7t-nhanh-%28npx"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20"> </th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Cài đặt nhanh (`npx`)</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Cài đặt toàn cục (`npm -g`)</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Tốc độ lần đầu**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chậm hơn (phải tải mỗi lần)</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Nhanh hơn (đã có sẵn)</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Cần cài trước**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Không</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Có</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Phù hợp khi**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Dùng thỉnh thoảng</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Dùng thường xuyên, nhiều dự án</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Cập nhật**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tự động lấy bản mới nhất</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Cần chạy lại lệnh cài</td></tr></tbody></table>

</div>---

## 2. Cài đặt toàn cục lên hệ thống

### Bước 1: Mở Terminal với quyền phù hợp

- **Windows:** Mở **PowerShell** hoặc **Command Prompt** (không cần quyền Admin nếu npm được cài bình thường).
- **macOS/Linux:** Mở **Terminal** thông thường.

### Bước 2: Chạy lệnh cài đặt toàn cục

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--1" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```bash
bash
npm install -g @vudovn/ag-kit
```

`-g` là tham số báo cho npm biết đây là cài đặt toàn cục (global).

### Bước 3: Xác nhận cài đặt thành công

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--2" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```bash
bash
ag-kit --version
```

Nếu hiển thị số phiên bản (ví dụ: `2.0.2`), cài đặt đã thành công.

### Bước 4: Khởi tạo cho từng dự án

Mỗi khi cần dùng cho một dự án mới, chỉ cần:

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--3" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"></div></div></div></div></div></div>```bash
bash
cd đường/dẫn/dự-án
ag-kit init
```

---

## 3. Biến môi trường PATH là gì và tại sao quan trọng?

**PATH** là một biến môi trường của hệ thống. Nó chứa danh sách các thư mục mà hệ điều hành sẽ tự động tìm kiếm khi bạn gõ một lệnh trong Terminal.

**Ví dụ dễ hiểu:** Khi bạn gõ `ag-kit init`, hệ điều hành sẽ duyệt qua từng thư mục trong biến PATH để tìm xem có file thực thi tên `ag-kit` ở đâu không. Nếu tìm thấy → chạy. Nếu không → báo lỗi "command not found".

**Vì sao điều này quan trọng với Antigravity Kit?**

- Lệnh `ag-kit` cần có trong PATH để bạn gọi được từ mọi nơi.
- Lệnh `python` cần có trong PATH để các **script kiểm tra tự động** của Kit có thể chạy được.

---

## 4. Kiểm tra và cấu hình PATH

### Kiểm tra PATH hiện tại

**Windows (PowerShell):**

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--6" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```powershell
powershell
$env:PATH -split ";"
```

**macOS / Linux:**

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--7" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```bash
bash
echo $PATH
```

### Kiểm tra `ag-kit` có trong PATH chưa

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--8" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="3" data-line-number="3" data-line-start="3"><div class="line-content"></div></div></div></div></div></div>```bash
bash
# Tất cả hệ điều hành
where ag-kit # Windows
which ag-kit # macOS / Linux
```

Nếu lệnh trên trả về đường dẫn (ví dụ: `C:\Users\ten-ban\AppData\Roaming\npm\ag-kit`), bạn đã cấu hình đúng.

### Kiểm tra `python` có trong PATH chưa

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--9" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"></div></div></div></div></div></div>```bash
bash
where python # Windows
which python # macOS / Linux
```

---

## 5. Cấu hình PATH thủ công (khi gặp lỗi)

### Windows — Thêm thư mục npm global vào PATH

**B1:** Tìm thư mục npm global:

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--11" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```powershell
powershell
npm config get prefix
```

Kết quả thường là: `C:\Users\ten-ban\AppData\Roaming\npm`

**B2:** Thêm vào PATH:

1. Mở **Settings** → tìm kiếm "Environment Variables".
2. Nhấn "**Edit the system environment variables**".
3. Chọn biến **Path** trong phần "User variables" → nhấn **Edit**.
4. Nhấn **New** → dán đường dẫn từ Bước 1 vào.
5. Nhấn **OK** và **khởi động lại Terminal**.

**B3:** Xác nhận lại:

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--12" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```powershell
powershell
ag-kit --version
```

### macOS / Linux — Thêm vào `.bashrc` hoặc `.zshrc`

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--13" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="11" data-line-number="11" data-line-start="11"><div class="line-content"></div></div></div></div></div></div>```bash
bash
# Tìm thư mục npm global
npm config get prefix
# Thường là: /usr/local hoặc /home/ten-ban/.npm-global


# Thêm vào file cấu hình shell
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
# Hoặc cho bash:
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc


# Áp dụng thay đổi
source ~/.zshrc # hoặc source ~/.bashrc
```

---

## 6. Quy trình làm việc điển hình với nhiều dự án

Đây là quy trình khuyến nghị khi bạn làm việc với nhiều dự án trên cùng một máy:

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--15" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5"><div class="font-sans text-sm text-ide-text-color opacity-60">  
</div><div class="flex flex-row gap-2 justify-end">  
</div></div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1">  
</div><div class="code-line" data-line-end="9" data-line-number="9" data-line-start="9"><div class="line-content"></div></div></div></div></div></div>```html
1. Cài đặt một lần:
npm install -g @vudovn/ag-kit


2. Cho mỗi dự án mới:
cd my-new-project
ag-kit init


3. Cập nhật định kỳ (không làm thường xuyên):
ag-kit update ← chạy trong thư mục dự án
```

---

## 7. Gỡ cài đặt toàn cục (khi cần)

Nếu bạn muốn gỡ bỏ cài đặt toàn cục:

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--17" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```html
bash
npm uninstall -g @vudovn/ag-kit
```

> **Lưu ý:** Gỡ cài đặt toàn cục không xóa bất kỳ thư mục `.agent/` nào đã được tạo trong các dự án. Để xóa khỏi một dự án cụ thể, hãy xóa thủ công thư mục `.agent/` đó.

# Trang 2.4: Giải thích cấu trúc thư mục .agent/ (Agents, Skills, Workflows, Rules, Scripts).

## 1. Tổng quan cấu trúc

Sau khi chạy lệnh `ag-kit init`, thư mục `.agent/` được tạo ra trong dự án của bạn với cấu trúc như sau:

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5"><div class="font-sans text-sm text-ide-text-color opacity-60">  
</div><div class="flex flex-row gap-2 justify-end">  
</div></div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1">  
</div><div class="code-line" data-line-end="9" data-line-number="9" data-line-start="9"><div class="line-content">  
</div></div></div></div></div></div>```html
.agent/
├── ARCHITECTURE.md # Tài liệu kiến trúc tổng thể
├── AGENT_FLOW.md # Sơ đồ luồng hoạt động chi tiết
├── mcp_config.json # Cấu hình MCP servers (tích hợp bên thứ 3)
├── agents/ # 20 file cấu hình Specialist Agent
├── skills/ # 36 thư mục kiến thức chuyên sâu
├── workflows/ # 11 file quy trình làm việc
├── rules/ # Quy tắc hành vi toàn cục (GEMINI.md)
└── scripts/ # Script kiểm tra tổng thể (Python)
```

Mỗi thư mục có một vai trò cụ thể và rõ ràng. Dưới đây là giải thích chi tiết từng thành phần.

---

## 2. File <span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">ARCHITECTURE.md</span></span></span>

**Đây là "bản đồ hệ thống"** dành cho AI.

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-m%E1%BB%A5c-n%E1%BB%99i-dung-m%E1%BB%A5c-%C4%91%C3%ADc"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mục</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Nội dung</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Mục đích**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Cung cấp cái nhìn tổng thể về toàn bộ kiến trúc của Kit cho AI</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Nội dung**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Danh sách đầy đủ 20 Agents (vai trò + Skills sử dụng), 36 Skills (phân loại theo nhóm), 11 Workflows (mô tả ngắn) và 2 master scripts</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Ai đọc**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">AI đọc file này đầu tiên khi khởi động để hiểu hệ sinh thái</td></tr></tbody></table>

</div>> **Lưu ý:** Không nên sửa file này trừ khi bạn thêm Agent hoặc Skill tùy chỉnh và muốn AI biết về chúng.

---

## 3. File <span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">AGENT\_FLOW.md</span></span></span>

**Đây là "hướng dẫn vận hành"** — mô tả chi tiết cách AI phải hành xử.

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-m%E1%BB%A5c-n%E1%BB%99i-dung-m%E1%BB%A5c-%C4%91%C3%ADc-1"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mục</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Nội dung</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Mục đích**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tài liệu hóa giao thức định tuyến Agent, bước kiểm tra bắt buộc và cổng Socratic</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Nội dung**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Quy trình từng bước để AI chọn Agent, Checklist bắt buộc trước khi viết code, mô tả luồng làm việc từ yêu cầu đến kết quả</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Phiên bản**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Được thêm vào từ phiên bản 2.0.1</td></tr></tbody></table>

</div>---

## 4. File <span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">mcp\_config.json</span></span></span>

**Cấu hình tích hợp dịch vụ bên thứ 3** thông qua giao thức MCP (Model Context Protocol).

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--7" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="7" data-line-number="7" data-line-start="7"><div class="line-content">  
</div></div></div></div></div></div>```json
json
{
"mcpServers": {
"context7": { ... }, // Tích hợp Context7 (tài liệu thư viện real-time)
"shadcn": { ... } // Tích hợp ShadCN UI
// Có thể thêm các MCP server khác tại đây
}
}
```

> **Lưu ý:** Để sử dụng, bạn cần copy file cấu hình này đến đúng vị trí mà Antigravity CLI nhận diện (thường là `~/.gemini/antigravity/mcp_config.json`). Xem tài liệu Antigravity CLI để biết thêm chi tiết.

---

## 5. Thư mục `agents/` — 20 Specialist Agents

### Cấu trúc

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--9" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5"><div class="font-sans text-sm text-ide-text-color opacity-60">  
</div><div class="flex flex-row gap-2 justify-end">  
</div></div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1">  
</div><div class="code-line" data-line-end="7" data-line-number="7" data-line-start="7"><div class="line-content">  
</div></div></div></div></div></div>```html
.agent/agents/
├── orchestrator.md
├── frontend-specialist.md
├── backend-specialist.md
├── security-auditor.md
├── debugger.md
└── ... (16 file khác)
```

### Vai trò

Mỗi file <span class="inline-flex break-all leading-tight">.md</span> là cấu hình đầy đủ cho một Agent chuyên gia. File bao gồm:

- **Phần YAML** (giữa `---`): `name`, `description`, `tools`, và quan trọng nhất là `skills` — danh sách các Skills Agent này được phép truy cập.
- **Phần Markdown**: Mô tả nhân cách, vai trò chuyên môn, các quy tắc hành vi riêng của Agent đó.

### Ví dụ nội dung một file Agent

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--10" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="16" data-line-number="16" data-line-start="16"><div class="line-content">  
</div></div></div></div></div></div>```yaml
yaml
---
name: frontend-specialist
description: Frontend architect for modern web applications
tools: Read, Edit, Write, Bash
skills: react-best-practices, frontend-design, tailwind-patterns, web-design-guidelines
---


# Frontend Specialist


Bạn là một kiến trúc sư Frontend cấp cao với 10+ năm kinh nghiệm...


## Quy tắc bắt buộc
- Luôn ưu tiên Core Web Vitals (LCP, CLS, INP)
- Không dùng màu tím/violet trong thiết kế (Purple Ban)
- Áp dụng mobile-first responsive design
...
```

---

## 6. Thư mục `skills/` — 36 Knowledge Modules

### Cấu trúc

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--12" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5"><div class="font-sans text-sm text-ide-text-color opacity-60">  
</div><div class="flex flex-row gap-2 justify-end">  
</div></div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1">  
</div><div class="code-line" data-line-end="18" data-line-number="18" data-line-start="18"><div class="line-content">  
</div></div></div></div></div></div>```html
.agent/skills/
├── react-best-practices/
│ ├── SKILL.md # (Bắt buộc) Metadata và hướng dẫn chính
│ ├── sections/ # Hướng dẫn chi tiết theo từng phần
│ └── scripts/ # Script Python/Bash hỗ trợ (nếu có)
├── api-patterns/
│ └── SKILL.md
├── vulnerability-scanner/
│ ├── SKILL.md
│ └── scripts/
│ ├── security_scan.py
│ └── dependency_analyzer.py
├── frontend-design/
│ ├── SKILL.md
│ └── scripts/
│ ├── ux_audit.py
│ └── accessibility_checker.py
└── ... (32 thư mục khác)
```

### Vai trò

- Mỗi thư mục là một **gói kiến thức độc lập** cho một lĩnh vực cụ thể.
- File <div>  
    </div><span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">SKILL.md</span></span></span> là bộ não của mỗi Skill, chứa các nguyên lý ra quyết định thay vì code mẫu cứng nhắc.
- Thư mục `scripts/` (nếu có) chứa các công cụ thực thi Python/Bash để Agent có thể tự chạy kiểm tra.

### Skills có script đặc biệt

Các Skills sau có kèm script Python để thực hiện kiểm tra tự động:

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-skill-scripts-t%C3%A1c-d%E1%BB%A5"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skill</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Scripts</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Tác dụng</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`vulnerability-scanner`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`security_scan.py`, `dependency_analyzer.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Quét lỗ hổng bảo mật</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`lint-and-validate`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`lint_runner.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra chất lượng code</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`database-design`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`schema_validator.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra tính nhất quán DB schema</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`testing-patterns`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`test_runner.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chạy bộ test tự động</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`frontend-design`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`ux_audit.py`, `accessibility_checker.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra UX và Accessibility</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`seo-fundamentals`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`seo_checker.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra các yếu tố SEO</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`performance-profiling`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`bundle_analyzer.py`, `lighthouse_audit.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Đo lường hiệu năng</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`webapp-testing`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`playwright_runner.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chạy E2E test</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`mobile-design`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`mobile_audit.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra giao diện mobile</td></tr></tbody></table>

</div>---

## 7. Thư mục `workflows/` — 11 Slash Commands

### Cấu trúc

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--14" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5"><div class="font-sans text-sm text-ide-text-color opacity-60">  
</div><div class="flex flex-row gap-2 justify-end">  
</div></div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1">  
</div><div class="code-line" data-line-end="12" data-line-number="12" data-line-start="12"><div class="line-content">  
</div></div></div></div></div></div>```html
.agent/workflows/
├── brainstorm.md
├── create.md
├── debug.md
├── deploy.md
├── enhance.md
├── orchestrate.md
├── plan.md
├── preview.md
├── status.md
├── test.md
└── ui-ux-pro-max.md
```

### Vai trò

Mỗi file <span class="inline-flex break-all leading-tight">.md</span> là định nghĩa đầy đủ cho một quy trình làm việc. File bao gồm:

- **Phần YAML**: `description` — mô tả ngắn gọn kích hoạt thứ gì trong IDE.
- **Phần Markdown**: Các bước thực hiện chi tiết, quyết định điều kiện, và các `// turbo` annotation (cho phép AI tự chạy lệnh an toàn ở bước đó).

### Cách thêm Workflow tùy chỉnh

Bạn có thể thêm Workflow riêng bằng cách tạo file mới:

```html
.agent/workflows/my-custom-workflow.md
```

Sau đó gọi bằng lệnh `/my-custom-workflow` trong chat với AI.

---

## 8. Thư mục `rules/` — Quy tắc toàn cục

### Cấu trúc

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--16" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5"><div class="font-sans text-sm text-ide-text-color opacity-60">  
</div><div class="flex flex-row gap-2 justify-end">  
</div></div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1">  
</div><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content">  
</div></div></div></div></div></div>```html
.agent/rules/
└── GEMINI.md # File quy tắc chính, luôn được áp dụng
```

### Vai trò của `GEMINI.md`

Đây là file **quan trọng nhất** trong toàn bộ hệ thống. Nó chứa:

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-ph%E1%BA%A7n-n%E1%BB%99i-dung-tier-0"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Phần</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Nội dung</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**TIER 0 — Universal Rules**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Quy tắc luôn áp dụng: Xử lý ngôn ngữ, code sạch, nhận thức phụ thuộc file</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Request Classifier**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Bảng phân loại yêu cầu (Question, Survey, Simple Code, Complex Code, Design...)</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Intelligent Routing**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Giao thức tự động chọn Agent phù hợp</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Agent Routing Checklist**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Các bước bắt buộc AI phải làm trước khi viết code</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**TIER 1 — Code Rules**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Quy tắc khi viết code: Chọn project type, Socratic Gate</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Gemini Mode Mapping**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Ánh xạ Plan/Ask/Edit mode sang Agent tương ứng</td></tr></tbody></table>

</div>> **Tùy chỉnh:** `GEMINI.md` có thể được chỉnh sửa để thêm các quy tắc riêng của dự án hoặc tổ chức. Ví dụ: thêm quy tắc về naming convention, ngôn ngữ bình luận code, hay các pattern cấm dùng.

---

## 9. Thư mục `scripts/` — Master Validation Scripts

### Cấu trúc

```html
.agent/scripts/
├── checklist.py # Kiểm tra ưu tiên (P0→P6)
├── verify_all.py # Kiểm tra toàn diện (bao gồm Lighthouse, Playwright)
├── auto_preview.py # Tự động khởi chạy server xem trước
└── session_manager.py # Quản lý trạng thái phiên làm việc AI
```

### So sánh hai main scripts

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-ti%C3%AAu-ch%C3%AD-checklist.p"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Tiêu chí</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20"><div>  
</div><span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">checklist.py</span></span></span></th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20"><div>  
</div><span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">verify\_all.py</span></span></span></th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Khi nào dùng**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Phát triển hàng ngày, trước commit</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Trước khi release production</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Tốc độ**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Nhanh (dừng ngay khi có lỗi nghiêm trọng)</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chậm hơn (chạy toàn bộ)</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Yêu cầu**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Không cần URL</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Cần cung cấp URL để chạy Lighthouse &amp; Playwright</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Phạm vi kiểm tra**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Security, Lint, Schema, Tests, UX, SEO</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tất cả của checklist + Lighthouse, Playwright, Bundle, Mobile, i18n</td></tr></tbody></table>

</div>### Cách chạy thủ công

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--18" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="5" data-line-number="5" data-line-start="5"><div class="line-content">  
</div></div></div></div></div></div>```bash
bash
# Kiểm tra cơ bản (từ thư mục gốc dự án)
python .agent/scripts/checklist.py .


# Kiểm tra toàn diện (cần server đang chạy)
python .agent/scripts/verify_all.py . --url http://localhost:3000
```

---

## 10. Sơ đồ quan hệ giữa các thành phần

```html
rules/GEMINI.md ← (1) AI đọc quy tắc đầu tiên
│
▼
ARCHITECTURE.md ← (2) AI hiểu toàn bộ hệ sinh thái
│
▼
agents/*.md ← (3) AI đóng vai Agent phù hợp
│
▼
skills/*/SKILL.md ← (4) Agent tải kiến thức cần thiết
│
▼
skills/*/scripts/*.py ← (5) Script chạy kiểm tra tự động
│
▼
scripts/checklist.py ← (6) Tổng hợp kết quả và báo cáo
```

> Hiểu rõ cấu trúc này giúp bạn dễ dàng **tùy chỉnh và mở rộng** bộ kit theo nhu cầu dự án của mình mà không làm ảnh hưởng đến phần còn lại của hệ thống.

# Chương 3: Khám phá các khái niệm cốt lõi (Core Concepts)

# Trang 3.1: AI Agents - Các đặc vụ chuyên gia và cơ chế định tuyến thông minh (Intelligent Routing).

## 1. Agent là gì?

**Agent** là một "nhân cách AI chuyên gia" được cấu hình sẵn với kiến thức sâu, công cụ và hành vi riêng biệt cho một lĩnh vực cụ thể trong phát triển phần mềm.

Hãy hình dung Agent như một chuyên viên tư vấn: thay vì hỏi một người biết tất cả một cách chung chung, bạn đang nói chuyện trực tiếp với **kiến trúc sư Frontend**, **chuyên gia bảo mật**, hay **kỹ sư kiểm thử** tùy theo từng vấn đề.

---

## 2. Hệ thống Định tuyến thông minh (Intelligent Routing)

### Cơ chế hoạt động

Điểm đặc biệt quan trọng nhất: **bạn không cần phải gọi tên Agent thủ công**. Hệ thống sẽ tự động phân tích yêu cầu của bạn và kích hoạt (các) Agent phù hợp nhất.

```html
Yêu cầu của bạn
│
▼
Hệ thống phân tích (Silent Analysis)
│
▼
Phát hiện lĩnh vực (Frontend? Backend? Security?...)
│
▼
Chọn Agent chuyên gia tương ứng
│
▼
Thông báo cho bạn Agent đang được dùng:
🤖 Đang áp dụng kiến thức của @[agent-name]...
│
▼
Trả lời ở cấp độ chuyên gia
```

### Ví dụ thực tế

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-y%C3%AAu-c%E1%BA%A7u-c%E1%BB%A7a-b%E1%BA%A1n-agen"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Yêu cầu của bạn</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Agent được kích hoạt</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">"Thêm xác thực JWT vào API"</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`@security-auditor` + `@backend-specialist`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">"Sửa lỗi nút dark mode bị lệch màu"</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`@frontend-specialist`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">"Login trả về lỗi 500 ngẫu nhiên"</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`@debugger`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">"Thiết kế schema cho bảng users và orders"</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`@database-architect`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">"Viết unit test cho service xác thực"</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`@test-engineer`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">"Tối ưu tốc độ tải trang"</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`@performance-optimizer`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">"Lập kế hoạch tính năng thanh toán"</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`@project-planner`</td></tr></tbody></table>

</div>### Ghi đè thủ công (Override)

Nếu bạn muốn buộc sử dụng một Agent cụ thể, chỉ cần đề cập tên trong yêu cầu:

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-%22d%C3%B9ng-security-audit" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5"><div class="font-sans text-sm text-ide-text-color opacity-60">  
</div><div class="flex flex-row gap-2 justify-end"></div></div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"><span class="mtk1">"Dùng security-auditor để review toàn bộ phần auth của tôi"</span></div></div><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><span class="mtk1">"Nhờ debugger phân tích lỗi này theo quy trình 4 bước"</span></div></div></div></div></div></div>---

## 3. Checklist bắt buộc trước khi AI viết code

Trước khi thực hiện bất kỳ tác vụ code hoặc thiết kế nào, AI **bắt buộc** phải hoàn thành checklist sau:

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-b%C6%B0%E1%BB%9Bc-ki%E1%BB%83m-tra-n%E1%BA%BFu-ch"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Bước</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Kiểm tra</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Nếu chưa làm</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">1</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Đã xác định đúng Agent cho lĩnh vực này chưa?</td><td class="px-3 py-2 leading-snug border border-gray-500/20">→ Dừng lại. Phân tích lại lĩnh vực yêu cầu.</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">2</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Đã đọc file cấu hình của Agent chưa?</td><td class="px-3 py-2 leading-snug border border-gray-500/20">→ Dừng lại. Mở và đọc `.agent/agents/{agent}.md`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">3</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Đã thông báo Agent đang dùng cho người dùng chưa?</td><td class="px-3 py-2 leading-snug border border-gray-500/20">→ Dừng lại. Thêm thông báo `🤖 Đang áp dụng @[agent]...`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">4</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Đã tải các Skills cần thiết từ frontmatter chưa?</td><td class="px-3 py-2 leading-snug border border-gray-500/20">→ Dừng lại. Kiểm tra trường `skills:` và đọc chúng.</td></tr></tbody></table>

</div>---

## 4. Danh sách đầy đủ 20 Agents

### Nhóm Quản lý &amp; Điều phối

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-agent-chuy%C3%AAn-m%C3%B4n-ski"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Agent</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Chuyên môn</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skills sử dụng</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`orchestrator`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Điều phối nhiều Agent làm việc song song cho tác vụ phức tạp</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`parallel-agents`, `behavioral-modes`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`project-planner`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Khám phá yêu cầu, lập kế hoạch và phân rã công việc</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`brainstorming`, `plan-writing`, `architecture`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`product-manager`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Yêu cầu nghiệp vụ, user stories</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`plan-writing`, `brainstorming`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`product-owner`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chiến lược sản phẩm, quản lý backlog, định nghĩa MVP</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`plan-writing`, `brainstorming`</td></tr></tbody></table>

</div>### Nhóm Phát triển

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-agent-chuy%C3%AAn-m%C3%B4n-ski-1"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Agent</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Chuyên môn</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skills sử dụng</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`frontend-specialist`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Giao diện Web (React, Next.js, Tailwind CSS)</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`react-best-practices`, `frontend-design`, `tailwind-patterns`, `web-design-guidelines`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`backend-specialist`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">API, Business Logic, máy chủ</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`api-patterns`, `nodejs-best-practices`, `database-design`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`database-architect`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Thiết kế schema, SQL, tối ưu truy vấn</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`database-design`, `prisma-expert`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`mobile-developer`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">iOS, Android, React Native, Flutter</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`mobile-design`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`game-developer`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Logic game, cơ học trò chơi</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`game-development`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`devops-engineer`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">CI/CD, Docker, hạ tầng cloud</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`deployment-procedures`, `docker-expert`</td></tr></tbody></table>

</div>### Nhóm Chất lượng &amp; Bảo mật

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-agent-chuy%C3%AAn-m%C3%B4n-ski-2"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Agent</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Chuyên môn</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skills sử dụng</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`security-auditor`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra bảo mật, tuân thủ OWASP</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`vulnerability-scanner`, `red-team-tactics`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`penetration-tester`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Bảo mật tấn công (Offensive Security)</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`red-team-tactics`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`test-engineer`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chiến lược kiểm thử toàn diện</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`testing-patterns`, `tdd-workflow`, `webapp-testing`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`qa-automation-engineer`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm thử E2E và CI Pipeline</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`webapp-testing`, `testing-patterns`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`debugger`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Phân tích nguyên nhân gốc rễ của lỗi</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`systematic-debugging`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`performance-optimizer`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tối ưu hiệu năng và Core Web Vitals</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`performance-profiling`</td></tr></tbody></table>

</div>### Nhóm Chuyên biệt

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-agent-chuy%C3%AAn-m%C3%B4n-ski-3"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Agent</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Chuyên môn</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skills sử dụng</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`seo-specialist`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Xếp hạng tìm kiếm, khả năng hiển thị (SEO + GEO)</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`seo-fundamentals`, `geo-fundamentals`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`documentation-writer`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Hướng dẫn sử dụng, tài liệu kỹ thuật</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`documentation-templates`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`code-archaeologist`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Phân tích và tái cấu trúc code cũ (Legacy code)</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`clean-code`, `code-review-checklist`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`explorer-agent`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Khám phá và phân tích codebase hiện có</td><td class="px-3 py-2 leading-snug border border-gray-500/20">*(không có skill cố định, dùng ngữ cảnh)*</td></tr></tbody></table>

</div>---

## 5. Khi nào nên sử dụng Agent nào?

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-t%C3%ACnh-hu%E1%BB%91ng-agent-ph%C3%B9"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Tình huống</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Agent phù hợp</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Bắt đầu dự án mới, chưa biết thiết kế thế nào</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`project-planner` → sau đó `orchestrator`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Xây dựng trang web, component UI</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`frontend-specialist`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Tạo API endpoint, kết nối database</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`backend-specialist`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Thiết kế bảng DB, model dữ liệu</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`database-architect`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Phát hiện lỗ hổng bảo mật</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`security-auditor`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Ứng dụng bị lỗi không rõ nguyên nhân</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`debugger`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Muốn viết test cho code hiện có</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`test-engineer`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Trang web tải chậm, điểm Lighthouse thấp</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`performance-optimizer`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Cần lên kế hoạch triển khai sản phẩm</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`project-planner` + `devops-engineer`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Cần phân tích một codebase lạ</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`explorer-agent`</td></tr></tbody></table>

</div>---

## 6. Agents làm việc cùng nhau

Các Agent có thể **phối hợp** để giải quyết các vấn đề phức tạp đa lĩnh vực. Sử dụng Agent `orchestrator` để điều phối:

**Ví dụ:** Xây dựng hệ thống đăng nhập hoàn chỉnh

```html
orchestrator điều phối:
├── database-architect → Thiết kế bảng users
├── backend-specialist → Viết API authentication
├── security-auditor → Review bảo mật, kiểm tra JWT
├── frontend-specialist → Xây dựng form login
└── test-engineer → Viết test cho toàn bộ flow
```

> **Lưu ý thực tế:** AI thực sự xử lý tuần tự (không song song thực sự), nhưng `orchestrator` quản lý ngữ cảnh và đảm bảo mỗi phần được thực hiện đúng bởi "góc nhìn" của Agent chuyên gia tương ứng.

# Trang 3.2: Skills - Hệ thống kỹ năng và kiến thức chuyên sâu cho AI.

## 1. Skill là gì?

**Skill** là một gói kiến thức chuyên biệt chứa các nguyên lý, mẫu thiết kế (patterns) và khung ra quyết định (decision-making framework) cho một lĩnh vực cụ thể.

### Skills khác gì so với template code thông thường?

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-%C4%90%E1%BA%B7c-%C4%91i%E1%BB%83m-template-co" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Đặc điểm</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Template Code Thông thường</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skill trong Antigravity Kit</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Bản chất**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Code mẫu cứng nhắc để copy</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Nguyên lý để suy nghĩ và quyết định</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Tính linh hoạt**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Cố định, áp sát một pattern</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Thích nghi theo ngữ cảnh dự án</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Kết quả**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Code giống nhau cho mọi trường hợp</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Code phù hợp với yêu cầu cụ thể</td></tr></tbody></table>

</div></div></div></div></div></div></div>> **Ví dụ:** Thay vì đưa cho bạn một template API cố định, Skill `api-patterns` dạy AI *cách quyết định* khi nào dùng REST, khi nào dùng GraphQL, và khi nào dùng tRPC dựa trên ngữ cảnh dự án của bạn.

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content">---

</div></div></div></div></div></div>## 2. Cách Skills được tải (Load on-demand)

Skills **không** được tải toàn bộ một lúc. Chúng được tải **theo yêu cầu** theo 3 cơ chế:

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-c%E1%BA%A5u-h%C3%ACnh-agent%3A%C2%A0m%E1%BB%97i-" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content">1. **Cấu hình Agent:** Mỗi Agent trong YAML frontmatter liệt kê các Skills nó được phép truy cập (trường `skills:`).
2. **Ngữ cảnh tác vụ:** Khi nhận yêu cầu, AI đọc mô tả của các Skills có liên quan và chỉ tải những Skill thực sự cần thiết.
3. **Đọc có chọn lọc:** Chỉ đọc các section cần thiết trong **<span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">SKILL.md</span></span></span>**, không đọc toàn bộ để tối ưu hiệu suất.

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="11" data-line-number="11" data-line-start="11"><div class="line-content"></div></div></div></div></div></div></div></div></div></div></div></div>```html
Ví dụ:
Yêu cầu: "Tạo API endpoint cho giỏ hàng"
│
▼
backend-specialist được kích hoạt
│
▼
Tải: api-patterns + nodejs-best-practices + database-design
│
▼
Không tải: mobile-design, seo-fundamentals, red-team-tactics...
```

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--1" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="11" data-line-number="11" data-line-start="11"><div class="line-content"></div></div></div></div></div></div>---

</div></div></div></div></div></div>## 3. Cấu trúc một Skill

```html
.agent/skills/react-best-practices/
├── SKILL.md # Bắt buộc — Metadata, nguyên lý chính, khung quyết định
├── sections/ # Tùy chọn — Hướng dẫn chi tiết theo từng chủ đề nhỏ
├── examples/ # Tùy chọn — Ví dụ triển khai tham khảo thực tế
├── scripts/ # Tùy chọn — Script Python/Bash có thể chạy tự động
└── assets/ # Tùy chọn — Hình ảnh, assets tham khảo
```

**Phần đầu của**

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-skill.md%C2%A0%28frontmatte" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content">**<span class="inline-flex break-all leading-tight">SKILL.md</span> (Frontmatter YAML):**</div></div></div></div></div></div><div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--2" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="5" data-line-number="5" data-line-start="5"><div class="line-content"></div></div></div></div></div></div></div></div></div></div></div></div>```html
yaml
---
name: react-best-practices
description: React & Next.js performance optimization from Vercel Engineering.
allowed-tools: Read, Write, Edit, Bash
---
```

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--3" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="5" data-line-number="5" data-line-start="5"><div class="line-content"></div></div></div></div></div></div>---

</div></div></div></div></div></div>## 4. Danh sách đầy đủ 36 Skills theo nhóm

### 🎨 Frontend &amp; UI (5 Skills)

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-skill-m%C3%B4-t%E1%BA%A3-react-be" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skill</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mô tả</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`react-best-practices`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tối ưu React &amp; Next.js — 57 quy tắc từ Vercel Engineering</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`web-design-guidelines`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm toán UI web — 100+ quy tắc về Accessibility, UX, Performance</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`tailwind-patterns`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tailwind CSS v4, CSS-first config, container queries</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`frontend-design`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Hệ thống thiết kế, bảng màu, typography, micro-animations</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`ui-ux-pro-max`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">**50 phong cách** thiết kế, **21 bảng màu**, **50 font chữ** chuyên nghiệp</td></tr></tbody></table>

</div></div></div></div></div></div></div>### ⚙️ Backend &amp; API (4 Skills)

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-skill-m%C3%B4-t%E1%BA%A3-api-patt" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skill</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mô tả</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`api-patterns`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Thiết kế API: REST vs GraphQL vs tRPC, versioning, pagination</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`nestjs-expert`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">NestJS modules, DI container, decorators, Guards</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`nodejs-best-practices`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Node.js async patterns, bảo mật, kiến trúc module</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`python-patterns`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">FastAPI, Django, async vs sync, type hints, Pydantic v2</td></tr></tbody></table>

</div></div></div></div></div></div></div>### 🗄️ Database (2 Skills)

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-skill-m%C3%B4-t%E1%BA%A3-database" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skill</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mô tả</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`database-design`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Thiết kế schema, chiến lược indexing, tránh N+1 query</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`prisma-expert`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Prisma ORM, migrations, relations, query optimization</td></tr></tbody></table>

</div></div></div></div></div></div></div>### 📝 TypeScript / JavaScript (1 Skill)

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-skill-m%C3%B4-t%E1%BA%A3-typescri" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skill</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mô tả</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`typescript-expert`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Lập trình kiểu nâng cao (generics, conditional types), hiệu năng biên dịch</td></tr></tbody></table>

</div></div></div></div></div></div></div>### ☁️ Cloud &amp; Infrastructure (3 Skills)

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-skill-m%C3%B4-t%E1%BA%A3-docker-e" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skill</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mô tả</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`docker-expert`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Containerization, Docker Compose, multi-stage builds</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`deployment-procedures`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">CI/CD, chiến lược deploy 5 giai đoạn, rollback</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`server-management`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Quản lý process, monitoring, scaling</td></tr></tbody></table>

</div></div></div></div></div></div></div>### 🧪 Testing &amp; Quality (5 Skills)

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-skill-m%C3%B4-t%E1%BA%A3-testing-" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skill</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mô tả</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`testing-patterns`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Pyramid kiểm thử, Jest/Vitest, AAA pattern, mocking</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`webapp-testing`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">E2E testing, Playwright, audit chiến lược sâu</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`tdd-workflow`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Vòng lặp RED-GREEN-REFACTOR, test-first development</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`code-review-checklist`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tiêu chuẩn review code: chất lượng, bảo mật, best practice</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`lint-and-validate`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">ESLint, Prettier, TypeScript strict mode</td></tr></tbody></table>

</div></div></div></div></div></div></div>### 🔒 Security (2 Skills)

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-skill-m%C3%B4-t%E1%BA%A3-vulnerab" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skill</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mô tả</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`vulnerability-scanner`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">OWASP 2025, Supply Chain Security, phân tích lỗ hổng</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`red-team-tactics`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chiến thuật tấn công theo MITRE ATT&amp;CK, báo cáo penetration test</td></tr></tbody></table>

</div></div></div></div></div></div></div>### 🏗️ Architecture &amp; Planning (4 Skills)

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-skill-m%C3%B4-t%E1%BA%A3-app-buil" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skill</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mô tả</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`app-builder`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tạo khung ứng dụng full-stack, chọn tech stack, phối hợp Agent</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`architecture`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">ADR (Architecture Decision Records), đánh đổi trade-off</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`plan-writing`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Phân rã công việc, định nghĩa phụ thuộc, tiêu chí xác minh</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`brainstorming`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Giao thức Socratic: đặt câu hỏi làm rõ trước khi triển khai</td></tr></tbody></table>

</div></div></div></div></div></div></div>### 📱 Mobile (1 Skill)

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-skill-m%C3%B4-t%E1%BA%A3-mobile-d" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skill</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mô tả</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`mobile-design`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Touch interaction, Mobile-first, iOS/Android conventions</td></tr></tbody></table>

</div></div></div></div></div></div></div>### 🎮 Game Development (1 Skill)

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-skill-m%C3%B4-t%E1%BA%A3-game-dev" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skill</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mô tả</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`game-development`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Logic game, cơ học vật lý, vòng lặp game loop</td></tr></tbody></table>

</div></div></div></div></div></div></div>### 🔍 SEO &amp; Growth (2 Skills)

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-skill-m%C3%B4-t%E1%BA%A3-seo-fund" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skill</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mô tả</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`seo-fundamentals`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">E-E-A-T, Core Web Vitals, Google algorithm principles</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`geo-fundamentals`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Generative Engine Optimization (tối ưu cho AI search: ChatGPT, Perplexity)</td></tr></tbody></table>

</div></div></div></div></div></div></div>### 💻 Shell / CLI (2 Skills)

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-skill-m%C3%B4-t%E1%BA%A3-bash-lin" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skill</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mô tả</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`bash-linux`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Linux commands, piping, error handling, scripting</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`powershell-windows`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">PowerShell operators, quản lý lỗi, pitfalls</td></tr></tbody></table>

</div></div></div></div></div></div></div>### 🔧 Other (6 Skills)

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-skill-m%C3%B4-t%E1%BA%A3-clean-co" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skill</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mô tả</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`clean-code`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tiêu chuẩn code sạch toàn cục, không over-engineering</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`behavioral-modes`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Các chế độ hoạt động AI (brainstorm, implement, debug, ship...)</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`parallel-agents`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Mẫu điều phối đa Agent, phân chia công việc độc lập</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`mcp-builder`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Xây dựng MCP Server, thiết kế tool &amp; resource patterns</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`documentation-templates`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Cấu trúc README, API docs, comment code</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`i18n-localization`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Phát hiện hardcoded string, quản lý translations, RTL</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`performance-profiling`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Core Web Vitals, đo lường, bundle analysis</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`systematic-debugging`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Quy trình 4 giai đoạn: Discovery → Hypothesis → Verification → Resolution</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`rust-pro`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Rust 1.75+, async/await, Tokio, axum, systems programming</td></tr></tbody></table>

</div>---

</div></div></div></div></div></div>## 5. Skills đặc biệt kèm theo công cụ thực thi

Các Skills sau không chỉ cung cấp kiến thức mà còn có **scripts Python** để Agent có thể tự động kiểm tra:

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-skill-script-t%C3%A1c-d%E1%BB%A5n" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skill</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Script</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Tác dụng</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`vulnerability-scanner`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`security_scan.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Quét lỗ hổng bảo mật trong dependencies</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`lint-and-validate`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`lint_runner.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chạy ESLint, kiểm tra type errors</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`database-design`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`schema_validator.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra tính nhất quán schema DB</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`testing-patterns`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`test_runner.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chạy bộ test tự động (Jest/Vitest)</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`frontend-design`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`ux_audit.py`, `accessibility_checker.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra UX Laws và WCAG Accessibility</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`seo-fundamentals`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`seo_checker.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra meta tags, cấu trúc heading</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`performance-profiling`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`lighthouse_audit.py`, `bundle_analyzer.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Đo lường Lighthouse score và bundle size</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`webapp-testing`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`playwright_runner.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chạy E2E test với Playwright</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`mobile-design`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`mobile_audit.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra responsive và touch targets</td></tr></tbody></table>

</div>---

</div></div></div></div></div></div>## 6. Cách Skills được tích hợp với Agents (ví dụ thực tế)

```html
frontend-specialist.md:
---
skills: react-best-practices, frontend-design, tailwind-patterns, web-design-guidelines
---


Khi yêu cầu: "Tạo component card sản phẩm đẹp và dễ tiếp cận"
│
Agent tải:
├── react-best-practices → Áp dụng Server Components, tránh re-render thừa
├── frontend-design → Chọn bảng màu, spacing hợp lý
├── tailwind-patterns → Viết class Tailwind đúng chuẩn v4
└── web-design-guidelines → Đảm bảo ARIA labels, contrast ratio
```

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--4" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="12" data-line-number="12" data-line-start="12"><div class="line-content"></div></div></div></div></div></div>  
</div></div></div></div></div></div>

# Trang 3.3: Workflows - Quy trình làm việc tự động thông qua các lệnh gạch chéo (/).

## 1. Workflow là gì?

**Workflow** là các quy trình được định nghĩa sẵn theo từng bước để hoàn thành một tác vụ lập trình phổ biến. Mỗi Workflow đảm bảo tính **nhất quán** và **đúng chuẩn** cho dù bạn yêu cầu bao nhiêu lần.

### Workflow giải quyết vấn đề gì?

Không có Workflow, kết quả AI trả về cho cùng một yêu cầu có thể khác nhau mỗi lần. Với Workflow, AI luôn đi theo đúng quy trình đã được định nghĩa — đảm bảo không bỏ sót bước nào.

---

## 2. Cách kích hoạt và sử dụng

### Cú pháp cơ bản

```html
/tên-workflow [mô tả yêu cầu]
```

### Ví dụ thực tế

```bash
bash
/brainstorm hệ thống thanh toán cho SaaS app
/plan trang e-commerce với giỏ hàng và checkout
/create ứng dụng todo có dark mode và đồng bộ real-time
/debug form submit không hoạt động, không báo lỗi gì
/test src/services/auth.ts
/ui-ux-pro-max landing page cho startup fintech, tông màu xanh navy
```

---

## 3. Tính năng Turbo (`// turbo`)

Một số bước trong Workflow được đánh dấu `// turbo`. Khi gặp dấu này:

- AI có thể **tự động thực thi** lệnh terminal an toàn mà không cần dừng lại hỏi bạn.
- Nếu toàn bộ Workflow có nhãn `// turbo-all`: mọi lệnh terminal trong Workflow đều tự chạy.

> **Lợi ích:** Tăng tốc độ đáng kể cho các tác vụ lặp đi lặp lại như chạy test, lint check, hay preview server.

---

## 4. Danh sách 11 Workflows và hướng dẫn chi tiết

---

### `/brainstorm` — Lên ý tưởng có cấu trúc

**Mục đích:** Khám phá ít nhất 3 phương án tiếp cận khác nhau cho một vấn đề trước khi viết code. AI sẽ phân tích ưu/nhược điểm và mức độ nỗ lực của từng phương án, sau đó đưa ra khuyến nghị.

**Khi nào dùng:**

- Bắt đầu một tính năng mới và chưa chắc về hướng triển khai.
- Cần so sánh các công nghệ hoặc kiến trúc khác nhau.
- Muốn đảm bảo đã cân nhắc đủ các lựa chọn trước khi commit.

**Ví dụ:**

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-%2Fbrainstorm-chi%E1%BA%BFn-l%C6%B0" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5"><div class="font-sans text-sm text-ide-text-color opacity-60">  
</div><div class="flex flex-row gap-2 justify-end"></div></div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"><span class="mtk1">/brainstorm chiến lược quản lý state cho ứng dụng có 50+ màn hình</span></div></div><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><span class="mtk1">/brainstorm lựa chọn database: PostgreSQL vs MongoDB cho hệ thống IoT</span></div></div></div></div></div></div>**Lưu ý quan trọng:** Chỉ đưa ra ý tưởng, **chưa viết code** ở bước này. Sau khi chọn phương án xong mới dùng `/create` hoặc `/enhance` để triển khai.

---

### `/plan` — Lập kế hoạch dự án

**Mục đích:** Kích hoạt Agent `project-planner` để tạo ra một file kế hoạch chi tiết (`PLAN-{tên}.md`). **Không viết code** trong quá trình này.

**Quy trình:**

1. Bạn mô tả dự án hoặc tính năng.
2. AI đặt câu hỏi làm rõ (Socratic Questions) về yêu cầu, ràng buộc, tech stack.
3. Bạn trả lời các câu hỏi.
4. AI tạo file `docs/PLAN-tên-dự-án.md` với danh sách tác vụ và phân công Agent.

**Ví dụ:**

```bash
/plan hệ thống quản lý nhân sự với phân quyền RBAC
/plan tích hợp cổng thanh toán VNPay vào ứng dụng Next.js
```

---

### `/create` — Tạo ứng dụng/tính năng mới

**Mục đích:** Trình thuật sĩ tạo ứng dụng hoàn chỉnh. Từ mô tả yêu cầu đến code chạy được.

**Quy trình:**

1. Bạn mô tả ứng dụng cần tạo.
2. AI phân tích và đề xuất tech stack.
3. Bạn xác nhận (Y) để tiến hành.
4. Các Agent chuyên gia triển khai từng phần (DB → Backend → Frontend → Tests).

**Ví dụ:**

```bash
/create blog cá nhân với Next.js, MDX và hệ thống comments
/create REST API cho ứng dụng quản lý thư viện sách
```

---

### `/enhance` — Cải tiến code hiện có

**Mục đích:** Thêm tính năng mới vào codebase hiện tại một cách "phẫu thuật" — không làm hỏng code đang chạy.

**Khác `/create` ở điểm nào?**

- `/create` → Xây từ đầu (greenfield).
- `/enhance` → Sửa chữa và bổ sung vào hệ thống đang chạy (brownfield).

**Quy trình:**

1. AI phân tích codebase hiện có (đọc các file liên quan).
2. Lập kế hoạch thay đổi tối thiểu cần thiết.
3. Triển khai tính năng mới cùng với bài test tương ứng.
4. Chạy kiểm tra để đảm bảo không có regression.

**Ví dụ:**

```bash
/enhance thêm tính năng dark mode toggle vào ứng dụng
/enhance tích hợp real-time notifications dùng WebSocket
```

---

### `/debug` — Sửa lỗi có hệ thống

**Mục đích:** Kích hoạt Agent `debugger` để điều tra lỗi theo giao thức 4 giai đoạn nghiêm ngặt.

**4 giai đoạn:**

1. **Discovery (Khám phá):** Thu thập log, báo cáo lỗi, các bước tái hiện.
2. **Hypothesis (Giả thuyết):** Đưa ra danh sách nguyên nhân tiềm năng, sắp xếp theo khả năng xảy ra.
3. **Verification (Xác minh):** Kiểm tra từng giả thuyết bằng bằng chứng cụ thể (không đoán mò).
4. **Resolution (Giải quyết):** Áp dụng bản sửa lỗi và thêm regression test.

**Ví dụ:**

```bash
/debug API trả về 403 dù đã đăng nhập đúng
/debug animation bị giật trên mobile Safari
```

---

### `/test` — Tạo và chạy kiểm thử

**Mục đích:** Tự động hóa toàn bộ quy trình kiểm thử.

**Các chức năng:**

```bash
bash
/test # Chạy toàn bộ test suite hiện có
/test src/auth.ts # Tạo test cases cho file cụ thể (ở đây là auth.ts)
/test coverage # Báo cáo độ bao phủ (coverage report)
```

**Kết quả trả về:** File test mới (`tests/auth.test.ts`), số lượng test cases, tỉ lệ coverage.

---

### `/ui-ux-pro-max` — Thiết kế UI nâng cao

**Mục đích:** Tạo landing page hoặc giao diện chất lượng cao theo phong cách cụ thể trong thời gian ngắn.

**Tích hợp với NextLevelBuilder:** Bạn có thể chọn phong cách từ thư viện tại [nextlevelbuilder.io](https://ui-ux-pro-max-skill.nextlevelbuilder.io/#styles) và dán vào lệnh.

**Kết quả trả về:**

- HTML semantic chuẩn SEO.
- Components có thể tái sử dụng.
- Micro-animations và responsive design.

**Ví dụ:**

```bash
/ui-ux-pro-max tạo landing page SaaS với glassmorphism cards, pricing 3 tới, testimonials
/ui-ux-pro-max portfolio cá nhân cho designer, phong cách minimalist với dark mode
```

---

### `/deploy` — Triển khai ứng dụng

**Mục đích:** Quy trình 5 giai đoạn để triển khai an toàn lên môi trường production.

**5 giai đoạn:** Pre-flight checks → Build → Test → Deploy → Verify.

**Ví dụ:**

```bash
/deploy lên Vercel
/deploy lên VPS với Nginx và PM2
```

---

### `/preview` — Quản lý server xem trước

**Mục đích:** Khởi động, dừng hoặc kiểm tra trạng thái server phát triển cục bộ.

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--12" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="3" data-line-number="3" data-line-start="3"><div class="line-content"></div></div></div></div></div></div>```bash
bash
/preview start # Khởi động server (tự nhận diện Next.js, Vite...)
/preview stop # Dừng server
/preview # Kiểm tra trạng thái hiện tại
```

---

### `/status` — Xem tổng quan dự án

**Mục đích:** Hiển thị bảng điều khiển (dashboard) tổng thể: thông tin dự án, tech stack, tiến độ các Agent, trạng thái server.

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--14" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```bash
bash
/status
```

---

### `/orchestrate` — Điều phối đa Agent

**Mục đích:** Kích hoạt `orchestrator` để phối hợp nhiều Agent chuyên gia cùng giải quyết một vấn đề lớn, phức tạp đòi hỏi nhiều góc nhìn chuyên môn.

**Khi nào dùng:** Tác vụ yêu cầu đồng thời Frontend + Backend + Security + QA.

**Ví dụ:**

```bash
/orchestrate build toàn bộ hệ thống authentication (DB + API + UI + Tests + Security review)
```

---

## 5. Tạo Workflow tùy chỉnh của riêng bạn

Bất kỳ ai cũng có thể thêm Workflow riêng phù hợp với quy trình nội bộ của đội:

**Bước 1:** Tạo file trong `.agent/workflows/`:

```bash
.agent/workflows/code-review.md
```

**Bước 2:** Viết nội dung theo format:

```bash
markdown
---
description: Tiến hành code review theo tiêu chuẩn nội bộ của đội
---


# Code Review Workflow


1. Đọc toàn bộ diff thay đổi
// turbo
2. Kiểm tra security issues
3. Kiểm tra performance implications
4. Kiểm tra code style theo team conventions
5. Tạo báo cáo review với mức ưu tiên (critical/major/minor)
```

**Bước 3:** Gọi bằng lệnh:

```bash
/code-review
```

---

## 6. Tóm tắt nhanh — Chọn Workflow nào?

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-t%C3%ACnh-hu%E1%BB%91ng-workflow-"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Tình huống</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Workflow</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Chưa biết nên làm theo hướng nào</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/brainstorm`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Cần kế hoạch trước khi code</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/plan`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Xây dự án/tính năng mới từ đầu</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/create`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Thêm tính năng vào dự án hiện có</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/enhance`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Cần giao diện đẹp nhanh</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/ui-ux-pro-max`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Ứng dụng bị lỗi không rõ nguyên nhân</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/debug`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Muốn kiểm thử code</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/test`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Sẵn sàng đưa lên production</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/deploy`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Muốn xem app đang chạy</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/preview start`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Muốn biết dự án đang ở đâu</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/status`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Tác vụ cần nhiều chuyên gia cùng lúc</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/orchestrate`</td></tr></tbody></table>

</div>

# Chương 4: Hướng dẫn sử dụng công cụ dòng lệnh (CLI Reference)

# Trang 4.1: Lệnh khởi tạo và quản lý dự án (ag-kit init, ag-kit status).

## 1. Tổng quan về công cụ CLI `ag-kit`

Công cụ dòng lệnh `ag-kit` là giao diện chính để quản lý vòng đời của Antigravity Kit trong các dự án. Nó cung cấp 3 lệnh chính:

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-l%E1%BB%87nh-ch%E1%BB%A9c-n%C4%83ng-ag-ki"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Lệnh</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Chức năng</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`ag-kit init`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Khởi tạo (cài đặt) bộ kit vào dự án</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`ag-kit update`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Cập nhật bộ kit lên phiên bản mới nhất</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`ag-kit status`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra trạng thái cài đặt hiện tại</td></tr></tbody></table>

</div>Trang này tập trung vào **`ag-kit init`** và **`ag-kit status`**.

---

## 2. Lệnh `ag-kit init` — Khởi tạo bộ kit

### Mục đích

Lệnh này cài đặt toàn bộ thư mục `.agent/` vào dự án của bạn, bao gồm tất cả Agents, Skills, Workflows, quy tắc và scripts.

### Cú pháp

```bash
bash
ag-kit init [options]
```

### Hành vi mặc định (không có options)

Khi chạy `ag-kit init` mà không có tham số bổ sung:

1. Kết nối với GitHub để tải phiên bản mới nhất từ nhánh <span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">main</span></span></span>.
2. Tạo thư mục `.agent/` trong thư mục **hiện tại** (nơi bạn đang đứng trong terminal).
3. Sao chép toàn bộ 20 Agents, 36 Skills, 11 Workflows cùng các file cấu hình.
4. Thông báo kết quả: thành công hay thất bại.

### Ví dụ sử dụng cơ bản

```bash
bash
# Di chuyển vào thư mục dự án
cd /đường/dẫn/đến/dự-án


# Khởi tạo
ag-kit init
```

### Điều kiện thành công

- ✅ Kết nối internet hoạt động.
- ✅ Quyền ghi vào thư mục hiện tại.
- ✅ Thư mục `.agent/` chưa tồn tại (nếu đã tồn tại cần thêm `--force`).

---

## 3. Kịch bản khởi tạo phổ biến

## Kịch bản 1: Dự án mới hoàn toàn

```bash
bash
# Tạo thư mục dự án
mkdir my-project
cd my-project


# Khởi tạo dự án (ví dụ Next.js)
npx create-next-app@latest .


# Cài đặt Antigravity Kit
ag-kit init
```

### Kịch bản 2: Thêm vào dự án đang có sẵn

```bash
bash
# Di chuyển vào dự án hiện tại
cd /projects/existing-project


# Cài đặt Kit (sẽ không ảnh hưởng code hiện tại)
ag-kit init
```

### Kịch bản 3: Cài đặt vào thư mục con cụ thể

```bash
bash
ag-kit init --path ./packages/my-app
```

```bash
bash
ag-kit init --path ./packages/my-app
```

### Kịch bản 4: Khởi tạo lại sau khi thử nghiệm

```bash
bash
# Ghi đè lên .agent/ cũ
ag-kit init --force
```

---

## 4. Cấu trúc kết quả sau `ag-kit init`

```html
dự-án-của-bạn/
├── src/ (code dự án của bạn - không bị ảnh hưởng)
├── package.json (không bị ảnh hưởng)
└── .agent/ ← CHỈ THÊ MỤC NÀY ĐƯỢC TẠO MỚI
├── ARCHITECTURE.md
├── AGENT_FLOW.md
├── mcp_config.json
├── agents/ (20 Agent files)
├── skills/ (36 Skill directories)
├── workflows/ (11 Workflow files)
├── rules/
│ └── GEMINI.md
└── scripts/
├── checklist.py
├── verify_all.py
├── auto_preview.py
└── session_manager.py
```

> **Đảm bảo an toàn:** Lệnh `init` chỉ tạo thư mục `.agent/`. Nó **không** sửa đổi, không xóa, và không ảnh hưởng đến bất kỳ file code nào trong dự án của bạn.

---

## 5. Lệnh `ag-kit status` — Kiểm tra trạng thái cài đặt

### Mục đích

Kiểm tra xem bộ kit đã được cài đặt đúng cách chưa và hiển thị thông tin về phiên bản đang dùng.

Cú pháp

```bash
bash
ag-kit status
```

### Thông tin hiển thị

Lệnh này sẽ kiểm tra và báo cáo:

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-m%E1%BB%A5c-ki%E1%BB%83m-tra-tr%E1%BA%A1ng-t"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mục kiểm tra</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Trạng thái tốt</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Trạng thái lỗi</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Thư mục `.agent/`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Tồn tại</td><td class="px-3 py-2 leading-snug border border-gray-500/20">❌ Không tìm thấy</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">File <div>  
</div><span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">ARCHITECTURE.md</span></span></span></td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Tìm thấy</td><td class="px-3 py-2 leading-snug border border-gray-500/20">❌ Thiếu</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Thư mục `agents/`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Đủ 20 Agent</td><td class="px-3 py-2 leading-snug border border-gray-500/20">⚠️ Thiếu file</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Thư mục `skills/`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Đủ 36 Skill</td><td class="px-3 py-2 leading-snug border border-gray-500/20">⚠️ Thiếu thư mục</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Thư mục `workflows/`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Đủ 11 Workflow</td><td class="px-3 py-2 leading-snug border border-gray-500/20">⚠️ Thiếu file</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Phiên bản cài đặt</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ v2.0.x</td><td class="px-3 py-2 leading-snug border border-gray-500/20">ℹ️ Có bản mới hơn</td></tr></tbody></table>

</div>### Ví dụ kết quả

```html
Antigravity Kit Status
======================
✅ Installation: Found at ./.agent/
✅ Version: 2.0.2
✅ Agents: 20 found
✅ Skills: 36 found
✅ Workflows: 11 found
ℹ️ Latest version: 2.0.2 (up to date)
```

---

## 6. Quy trình xác minh sau khi cài đặt

Sau khi chạy `ag-kit init`, thực hiện các bước sau để xác nhận mọi thứ hoạt động:

**Bước 1:** Kiểm tra thư mục đã được tạo

```bash
bash
ls .agent/ # macOS / Linux
dir .agent\ # Windows
```

**Bước 2:** Kiểm tra trạng thái qua CLI

```bash
bash
ag-kit status
```

**Bước 3:** Thử mở AI Chat trong IDE và gõ thử một lệnh

```bash
/status
```

Nếu AI nhận ra lệnh và hiển thị thông tin dự án, cài đặt đã thành công hoàn toàn.

---

## 7. Sự cố thường gặp với lệnh `init`

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-l%E1%BB%97i-nguy%C3%AAn-nh%C3%A2n-gi%E1%BA%A3i"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Lỗi</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Nguyên nhân</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Giải pháp</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`ag-kit: command not found`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chưa cài toàn cục hoặc PATH chưa đúng</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chạy `npm install -g @vudovn/ag-kit`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`.agent/ already exists`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Đã cài đặt trước đó</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Thêm `--force` để ghi đè</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`Permission denied`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Không có quyền ghi</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chạy terminal với quyền admin hoặc đổi owner thư mục</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`Network error`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Không có kết nối internet</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra mạng và thử lại</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`Repository not found`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tên package sai</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Đảm bảo dùng đúng `@vudovn/ag-kit`</td></tr></tbody></table>

</div>

# Trang 4.2: Cập nhật phiên bản và quản lý dữ liệu (ag-kit update).

## 1. Lệnh `ag-kit update` — Cập nhật bộ kit

### Mục đích

Cập nhật toàn bộ nội dung thư mục `.agent/` lên phiên bản mới nhất từ repository chính thức.

### Cú pháp

```bash
bash
ag-kit update [options]
```

---

## 2. Điều gì xảy ra khi chạy `ag-kit update`?

Lệnh này thực hiện các bước theo thứ tự:

```html
1. Kết nối đến GitHub để lấy phiên bản mới nhất
│
▼
2. So sánh phiên bản hiện tại với phiên bản mới nhất
│
▼
3. ⚠️ XÓA toàn bộ thư mục .agent/ hiện tại
│
▼
4. Tải về và giải nén phiên bản mới
│
▼
5. Tạo lại .agent/ với nội dung mới
│
▼
6. Báo cáo kết quả cập nhật
```

<p class="callout warning">⚠️ **Cảnh báo quan trọng:** Bước 3 là **xóa hoàn toàn** thư mục `.agent/`. Nếu bạn đã tùy chỉnh Agent, Skill hoặc Workflow trong thư mục này, **tất cả sẽ bị mất** nếu không sao lưu trước.</p>

## 3. Chiến lược sao lưu trước khi cập nhật

### Phương án 1: Sao lưu thủ công (Đơn giản nhất)

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--1" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="8" data-line-number="8" data-line-start="8"><div class="line-content"></div></div></div></div></div></div>```bash
bash
# Tạo bản sao thư mục .agent/
cp -r .agent/ .agent-backup/ # macOS / Linux
xcopy .agent .agent-backup /E /I # Windows


# Thực hiện cập nhật
ag-kit update


# Sau khi cập nhật, merge lại các tùy chỉnh của bạn thủ công
```

### Phương án 2: Dùng Git (Khuyến nghị cho dự án nhóm)

Nếu thư mục `.agent/` đã được commit vào Git:

```bash
bash
# Commit trạng thái hiện tại để lưu lịch sử
git add .agent/
git commit -m "backup: save custom .agent configs before update"


# Cập nhật Kit
ag-kit update


# Nếu cần khôi phục tùy chỉnh, dùng git diff để xem sự khác biệt
git diff HEAD~1 .agent/
```

### Phương án 3: Tách biệt tùy chỉnh (Bền vững nhất)

Tạo các file tùy chỉnh riêng biệt thay vì sửa file gốc:

- Thêm Agent tùy chỉnh: `.agent/agents/my-team-agent.md` *(file mới, không ghi đè file gốc)*
- Thêm Workflow tùy chỉnh: `.agent/workflows/my-deploy.md` *(file mới)*
- **Không sửa** các file Agent/Skill gốc (ví dụ không sửa `frontend-specialist.md`)

Với phương án này, sau khi `update`, các file gốc được cập nhật, còn các file tùy chỉnh của bạn vẫn giữ nguyên.

---

## 4. Khi nào nên cập nhật?

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-t%C3%ACnh-hu%E1%BB%91ng-h%C3%A0nh-%C4%91%E1%BB%99ng"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Tình huống</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Hành động</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Phiên bản mới có tính năng bạn cần</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Nên cập nhật</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Có bản vá lỗi (bugfix) quan trọng</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Nên cập nhật</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Cần kiểm tra tương thích trước</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Đọc CHANGELOG trước, rồi cập nhật</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Đang giữa dự án phức tạp</td><td class="px-3 py-2 leading-snug border border-gray-500/20">⚠️ Cân nhắc — cập nhật sau khi hoàn thành sprint</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Đã tùy chỉnh nhiều file gốc</td><td class="px-3 py-2 leading-snug border border-gray-500/20">⚠️ Sao lưu kỹ trước khi cập nhật</td></tr></tbody></table>

</div>---

## 5. Kiểm tra CHANGELOG trước khi cập nhật

Trước khi chạy lệnh update, hãy đọc file <span class="inline-flex break-all leading-tight">CHANGELOG.md</span> để biết những thay đổi trong phiên bản mới:

```bash
bash
# Xem CHANGELOG trên GitHub
# https://github.com/vudovn/antigravity-kit/blob/main/CHANGELOG.md
```

Mỗi phiên bản mới thường ghi rõ:

- **Added:** Thứ gì mới được thêm vào.
- **Changed:** Thứ gì thay đổi (có thể ảnh hưởng đến tùy chỉnh của bạn).
- **Removed:** Thứ gì bị xóa (cẩn thận nếu bạn đang phụ thuộc vào nó).
- **Fixed:** Lỗi nào đã được vá.

---

## 6. Cập nhật từ một nhánh cụ thể

Nếu bạn muốn thử nghiệm phiên bản chưa phát hành chính thức:

```bash
bash
# Cập nhật từ nhánh 'dev' (thử nghiệm)
ag-kit update --branch dev


# Quay về nhánh chính thức
ag-kit update --branch main
```

> **Lưu ý:** Chỉ dùng nhánh `dev` cho mục đích thử nghiệm, không dùng trên môi trường production.

---

## 7. Rollback (Hoàn tác cập nhật)

Antigravity Kit không có lệnh rollback tích hợp. Để hoàn tác:

**Nếu đã sao lưu thủ công:**

```bash
bash
# Xóa .agent/ mới
rm -rf .agent/


# Khôi phục bản cũ
cp -r .agent-backup/ .agent/
```

**Nếu đang dùng Git:**

```bash
bash
# Khôi phục về commit trước khi update
git checkout HEAD~1 -- .agent/
```

**Nếu muốn cài lại một phiên bản cụ thể:** Hiện tại chưa có cú pháp chọn phiên bản cụ thể trong CLI. Cách làm thủ công là:

1. Clone repository về: `git clone https://github.com/vudovn/antigravity-kit.git`
2. Checkout tag phiên bản mong muốn: `git checkout v2.0.1`
3. Sao chép thư mục `.agent/` vào dự án của bạn.

---

## 8. Cập nhật trong môi trường CI/CD

Nếu bộ kit là một phần trong quy trình CI/CD của đội:

```yaml
yaml
# Ví dụ trong GitHub Actions
- name: Install/Update Antigravity Kit
run: ag-kit init --quiet --force
# (hoặc ag-kit update --quiet)
```

Tham số `--quiet` giúp ẩn bớt output không cần thiết trong log CI/CD.

# Trang 4.3: Các tham số nâng cao (Sử dụng --force, --path, --quiet).

## 1. Tổng quan các tham số

Công cụ `ag-kit` hỗ trợ nhiều tham số (options/flags) để tinh chỉnh hành vi cho từng tình huống cụ thể.

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-tham-s%E1%BB%91-l%E1%BB%87nh-%C3%A1p-d%E1%BB%A5ng"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Tham số</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Lệnh áp dụng</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Chức năng tóm tắt</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`--force`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`init`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Ghi đè thư mục `.agent/` đã tồn tại</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`--path`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`init`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chỉ định thư mục cài đặt khác thay vì thư mục hiện tại</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`--branch`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`init`, `update`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chọn nhánh Git cụ thể để tải về</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`--quiet`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`init`, `update`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chạy im lặng, ẩn bớt output</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`--dry-run`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`init`, `update`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Xem trước các thao tác sẽ thực hiện mà không thực sự làm gì</td></tr></tbody></table>

</div>---

## 2. Tham số `--force`

### Chức năng

Cho phép ghi đè lên thư mục `.agent/` đã tồn tại. Mặc định, `ag-kit init` sẽ báo lỗi nếu thư mục này đã có.

### Cú pháp

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--1" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```bash
bash
ag-kit init --force
```

### Khi nào dùng

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-t%C3%ACnh-hu%E1%BB%91ng-d%C3%B9ng%C2%A0--fo"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Tình huống</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Dùng `--force` không?</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Cài đặt lần đầu</td><td class="px-3 py-2 leading-snug border border-gray-500/20">❌ Không cần</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Thư mục `.agent/` đã tồn tại, muốn cài lại</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Cần thiết</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Muốn xóa mọi tùy chỉnh và trở về mặc định</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Cần thiết</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Cần reset Kit sau khi thử nghiệm hỏng</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Cần thiết</td></tr></tbody></table>

</div>### Ví dụ

```bash
bash
# Thử cài đặt thông thường (sẽ báo lỗi nếu đã có .agent/)
ag-kit init
# Error: .agent/ already exists. Use --force to overwrite.


# Cài đặt lại với --force
ag-kit init --force
# ✅ Overwriting .agent/... Done!
```

<p class="callout warning">⚠️ **Cảnh báo:** `--force` sẽ **xóa toàn bộ** thư mục `.agent/` hiện tại trước khi cài lại. Mọi tùy chỉnh trong đó sẽ bị mất. Hãy sao lưu trước nếu cần.</p>

---

## 3. Tham số `--path`

### Chức năng

Chỉ định thư mục đích để cài đặt Kit thay vì thư mục hiện tại trong terminal.

### Cú pháp

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--3" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```bash
bash
ag-kit init --path <đường-dẫn-đến-thư-mục>
```

### Khi nào dùng

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-t%C3%ACnh-hu%E1%BB%91ng-v%C3%AD-d%E1%BB%A5-c%C3%A0i"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Tình huống</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Ví dụ</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Cài vào thư mục con cụ thể</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`ag-kit init --path ./apps/frontend`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Cài vào monorepo package</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`ag-kit init --path ./packages/web`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Cài vào đường dẫn tuyệt đối</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`ag-kit init --path /home/user/projects/myapp`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Không muốn phải `cd` vào thư mục</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`ag-kit init --path ./client`</td></tr></tbody></table>

</div>### Ví dụ thực tế

```bash
bash
# Cấu trúc monorepo:
my-monorepo/
├── apps/
│ ├── web/ ← muốn cài vào đây
│ └── mobile/ ← và cả đây
└── packages/


# Cài vào web app mà không cần cd
ag-kit init --path ./apps/web


# Cài vào mobile app
ag-kit init --path ./apps/mobile


# Kết hợp với --force nếu đã có .agent/ cũ
ag-kit init --path ./apps/web --force
```

---

## 4. Tham số `--branch`

### Chức năng

Chỉ định nhánh Git cụ thể trên repository để tải bộ kit. Mặc định sử dụng nhánh <span class="inline-flex break-all leading-tight">main</span> (phiên bản ổn định nhất).

### Cú pháp

```bash
bash
ag-kit init --branch <tên-nhánh>
ag-kit update --branch <tên-nhánh>
```

### Các nhánh phổ biến

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-nh%C3%A1nh-m%C3%B4-t%E1%BA%A3-n%C3%AAn-d%C3%B9ng"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Nhánh</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mô tả</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Nên dùng</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20"><div>  
</div><span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">main</span></span></span></td><td class="px-3 py-2 leading-snug border border-gray-500/20">Phiên bản ổn định chính thức</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Production, dự án thực tế</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`dev`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Phiên bản phát triển, có thể không ổn định</td><td class="px-3 py-2 leading-snug border border-gray-500/20">🧪 Thử nghiệm tính năng mới</td></tr></tbody></table>

</div>### Ví dụ

```bash
bash
# Cài từ nhánh chính thức (mặc định)
ag-kit init
# Tương đương với:
ag-kit init --branch main


# Thử nghiệm tính năng mới nhất (chưa phát hành)
ag-kit init --branch dev


# Cập nhật từ nhánh dev
ag-kit update --branch dev
```

<p class="callout warning">**Lưu ý:** Nhánh `dev` có thể chứa các tính năng chưa hoàn thiện. Chỉ dùng cho môi trường phát triển và thử nghiệm cá nhân.</p>

---

## 5. Tham số `--quiet`

### Chức năng

Chạy lệnh ở chế độ im lặng — ẩn bớt các thông báo thông thường, chỉ hiển thị lỗi nghiêm trọng (nếu có).

### Cú pháp

```bash
bash
ag-kit init --quiet
ag-kit update --quiet
```

### Khi nào dùng

- **CI/CD pipelines:** Khi bạn không muốn log quá dài làm rối output của build pipeline.
- **Script tự động:** Khi chạy trong script shell không cần đọc log chi tiết.
- **Chạy hàng loạt:** Khi cần cài/cập nhật Kit cho nhiều dự án cùng lúc.

### Ví dụ trong GitHub Actions

```yaml
yaml
name: Setup Antigravity Kit
on: [push]


jobs:
setup:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install Node.js
uses: actions/setup-node@v3
with:
node-version: '20'
- name: Install Antigravity Kit
run: |
npm install -g @vudovn/ag-kit
ag-kit init --quiet --force
```

---

## 6. Tham số `--dry-run`

### Chức năng

Thực hiện một lần chạy "giả định" — hiển thị tất cả những gì sẽ xảy ra nhưng **không thực sự làm gì** trên hệ thống. Không tạo, không xóa, không thay đổi file nào.

### Cú pháp

```bash
bash
ag-kit init --dry-run
ag-kit update --dry-run
```

### Khi nào dùng

- Trước khi cài đặt trên dự án quan trọng để xem trước thao tác.
- Kiểm tra xem lệnh có hoạt động đúng không mà không có rủi ro.
- Xem danh sách file sẽ được tạo ra.

### Ví dụ kết quả của `--dry-run`

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--7" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content">  
</div></div></div></div></div></div>```bash
bash
ag-kit init --dry-run
```

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--8" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"></div><div class="code-line" data-line-end="3" data-line-number="3" data-line-start="3">  
</div><div class="code-line" data-line-end="12" data-line-number="12" data-line-start="12"><div class="line-content"></div></div></div></div></div></div>```html
[DRY RUN] The following actions would be performed:
- Create directory: ./.agent/
- Create file: ./.agent/ARCHITECTURE.md
- Create file: ./.agent/AGENT_FLOW.md
- Create directory: ./.agent/agents/ (20 files)
- Create directory: ./.agent/skills/ (36 directories)
- Create directory: ./.agent/workflows/ (11 files)
- Create directory: ./.agent/rules/
- Create directory: ./.agent/scripts/
[DRY RUN] No changes were made.
```

---

## 7. Kết hợp nhiều tham số

Các tham số có thể kết hợp với nhau tùy ý:

```bash
bash
# Cài vào thư mục cụ thể, ghi đè nếu tồn tại, chạy im lặng
ag-kit init --path ./apps/web --force --quiet


# Xem trước thao tác cập nhật từ nhánh dev
ag-kit update --branch dev --dry-run


# Cài đặt vào thư mục cụ thể, xem trước (không thực sự làm)
ag-kit init --path ./packages/shared --dry-run
```

---

## 8. Bảng tham chiếu nhanh (Quick Reference)

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--11" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="29" data-line-number="29" data-line-start="29"><div class="line-content"></div></div></div></div></div></div>```bash
bash
# Cài đặt cơ bản
ag-kit init


# Cài đặt (ghi đè nếu đã có)
ag-kit init --force


# Cài vào thư mục khác
ag-kit init --path ./my-app


# Cài từ nhánh cụ thể
ag-kit init --branch dev


# Chạy im lặng (cho CI/CD)
ag-kit init --quiet --force


# Xem trước không làm gì
ag-kit init --dry-run


# Kết hợp: cài vào thư mục khác, ghi đè, im lặng
ag-kit init --path ./apps/web --force --quiet


# Cập nhật và xem trước
ag-kit update --dry-run


# Cập nhật im lặng (cho automation)
ag-kit update --quiet


# Kiểm tra trạng thái
ag-kit status
```

# Chương 5: Cẩm nang thực hành (Guides & Examples)

# Trang 5.1: Lên ý tưởng và so sánh giải pháp với /brainstorm.

## 1. Mục đích và triết lý

**`/brainstorm`** được thiết kế với triết lý rõ ràng: **"Suy nghĩ trước, code sau."**

Nhiều quyết định kiến trúc sai lầm bắt nguồn từ việc bắt tay vào code ngay mà không xem xét đủ các lựa chọn. Workflow này buộc AI phải trình bày **ít nhất 3 phương án khác nhau** với đầy đủ ưu/nhược điểm và mức độ nỗ lực, giúp bạn đưa ra lựa chọn sáng suốt.

> **Nguyên tắc vàng:** Luôn chạy `/brainstorm` trước khi bắt đầu bất kỳ tính năng phức tạp nào.

---

## 2. Khi nào nên dùng `/brainstorm`?

✅ **Nên dùng khi:**

- Bắt đầu một tính năng mới và chưa chắc về hướng triển khai.
- Cần so sánh các công nghệ, thư viện hoặc kiến trúc khác nhau.
- Muốn có cái nhìn khách quan về trade-off.
- Cần thuyết phục đội hoặc cấp trên về một lựa chọn kỹ thuật.

❌ **Không cần dùng khi:**

- Tác vụ đơn giản, rõ ràng (fix typo, thêm field đơn giản...).
- Đã có quyết định rõ ràng và chỉ cần triển khai.

---

## 3. Quy trình thực hiện

### Bước 1: Mô tả thách thức

```bash
bash
/brainstorm [mô tả vấn đề hoặc nhiệm vụ cần giải quyết]
```

*Lưu ý: Cung cấp càng nhiều ngữ cảnh (context) thì AI đưa ra phân tích càng chính xác.*

### Bước 2: Xem xét các phương án

AI sẽ trình bày **ít nhất 3 phương án** theo cấu trúc chuẩn:

```html
Phương án 1: [Tên phương án]
✅ Ưu điểm: ...
❌ Nhược điểm: ...
⏱️ Nỗ lực: Thấp / Trung bình / Cao
📌 Phù hợp khi: ...


Phương án 2: [Tên phương án]
...


Phương án 3: [Tên phương án]
...


👉 Khuyến nghị: Phương án X vì [lý do cụ thể dựa trên ngữ cảnh của bạn]
```

### Bước 3: Trao đổi và quyết định

- Hỏi thêm về phương án bạn quan tâm.
- Yêu cầu AI phân tích sâu hơn về một khía cạnh cụ thể.
- Xác nhận phương án để tiến hành bước tiếp theo (`/create` hoặc `/enhance`).

---

## 4. Ví dụ phiên làm việc thực tế

### Ví dụ 1: Chọn chiến lược quản lý state

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--3" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5"><div class="font-sans text-sm text-ide-text-color opacity-60">  
</div><div class="flex flex-row gap-2 justify-end">  
</div></div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1">  
</div><div class="code-line" data-line-end="32" data-line-number="32" data-line-start="32"><div class="line-content"></div></div></div></div></div></div>```html
👤 Bạn: /brainstorm chiến lược quản lý state cho ứng dụng React có
50+ màn hình và cần đồng bộ real-time


🤖 AI: Tôi sẽ phân tích 3 phương án quản lý state phù hợp với yêu cầu của bạn:


Phương án 1: Zustand + React Query
✅ Ưu điểm: Nhẹ (2KB), không boilerplate, tích hợp tốt với server state
❌ Nhược điểm: Cần học 2 thư viện riêng biệt
⏱️ Nỗ lực: Thấp
📌 Phù hợp: Dự án muốn linh hoạt, tránh over-engineering


Phương án 2: Redux Toolkit + RTK Query
✅ Ưu điểm: Chuẩn ngành, devtools mạnh, dễ debug
❌ Nhược điểm: Nhiều boilerplate hơn, bundle size lớn hơn
⏱️ Nỗ lực: Trung bình
📌 Phù hợp: Team đã quen Redux, dự án lớn cần chuẩn hóa


Phương án 3: Jotai + SWR
✅ Ưu điểm: Atomic state, cực kỳ linh hoạt, tránh re-render thừa
❌ Nhược điểm: Ít tài liệu hơn, cộng đồng nhỏ hơn
⏱️ Nỗ lực: Trung bình
📌 Phù hợp: Dự án phức tạp với nhiều state độc lập


👉 Khuyến nghị: Phương án 1 (Zustand + React Query) cho dự án mới,
vì cân bằng tốt giữa đơn giản và hiệu năng, đặc biệt phù hợp
với yêu cầu real-time của bạn.


Bạn muốn tôi phân tích sâu hơn về phương án nào?


👤 Bạn: Cho tôi biết thêm về Phương án 1, cách triển khai real-time như thế nào?


🤖 AI: [Phân tích chi tiết hơn về Zustand + React Query + WebSocket pattern...]
```

---

### Ví dụ 2: Chọn database cho hệ thống IoT

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--5" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1">  
</div><div class="code-line" data-line-end="13" data-line-number="13" data-line-start="13"><div class="line-content"></div></div></div></div></div></div>```html
👤 Bạn: /brainstorm lựa chọn database cho hệ thống IoT cần lưu
1 triệu sự kiện/ngày, query theo khoảng thời gian


🤖 AI: Phân tích 3 phương án phù hợp:


Phương án 1: TimescaleDB (PostgreSQL mở rộng)
Phương án 2: InfluxDB (Time-series database chuyên dụng)
Phương án 3: MongoDB với TTL collections


[Phân tích chi tiết từng phương án...]


👉 Khuyến nghị: TimescaleDB nếu đội quen SQL, InfluxDB nếu cần
hiệu năng cao nhất cho time-series.
```

---

## 5. Mẹo để brainstorm hiệu quả

### Cung cấp ngữ cảnh đầy đủ

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--7" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1">  
</div><div class="code-line" data-line-end="7" data-line-number="7" data-line-start="7"><div class="line-content"></div></div></div></div></div></div>```html
# Kém hiệu quả:
/brainstorm cách lưu dữ liệu


# Hiệu quả hơn:
/brainstorm cách lưu dữ liệu người dùng cho ứng dụng SaaS
B2B với 10,000 tenant, cần multi-tenancy, đang dùng PostgreSQL,
team 3 backend engineer
```

### Hỏi về trade-off cụ thể

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--8" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1">  
</div><div class="code-line" data-line-end="5" data-line-number="5" data-line-start="5"><div class="line-content"></div></div></div></div></div></div>```html
# Sau khi nhận phương án:
"Nếu dự án mở rộng lên 10 lần trong 1 năm, phương án nào
sẽ scale tốt hơn?"


"Chi phí vận hành của phương án 2 và 3 khác nhau thế nào?"
```

### Yêu cầu so sánh trực tiếp

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--9" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1">  
</div><div class="code-line" data-line-end="3" data-line-number="3" data-line-start="3"><div class="line-content"></div></div></div></div></div></div>```html
"Tôi đang phân vân giữa Phương án 1 và 3.
Hãy so sánh trực tiếp 2 phương án này theo
tiêu chí: hiệu năng, độ phức tạp, chi phí."
```

---

## 6. Bước tiếp theo sau khi có quyết định

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-quy%E1%BA%BFt-%C4%91%E1%BB%8Bnh-b%C6%B0%E1%BB%9Bc-ti%E1%BA%BFp"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Quyết định</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Bước tiếp theo</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Xây dựng tính năng từ đầu</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/create` với phương án đã chọn</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Cải tiến code đang có</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/enhance` với phương án đã chọn</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Cần kế hoạch chi tiết</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/plan` để phân rã công việc</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Muốn thử nghiệm nhanh trước</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tạo prototype rồi `/test`</td></tr></tbody></table>

</div>

# Trang 5.2: Lập kế hoạch dự án chi tiết (Blueprint) với /plan.

## 1. Mục đích và triết lý

**`/plan`** là lệnh kích hoạt chế độ **"Lập kế hoạch thuần túy"** — AI trở thành `project-planner` và nhiệm vụ duy nhất là tạo ra một kế hoạch chi tiết, không viết một dòng code nào.

> **Quy tắc sắt:** `/plan` kết thúc = Chỉ có file kế hoạch `PLAN.md`. Không có code, không có implementation. Đây là ranh giới nghiêm ngặt.

---

## 2. Khi nào nên dùng `/plan`?

✅ **Nên dùng khi:**

- Bắt đầu một dự án hoặc tính năng lớn (hơn 2-3 ngày công).
- Cần trình bày kế hoạch cho đội hoặc cấp trên phê duyệt.
- Muốn phân rã công việc thành các task nhỏ có thể giao cho thành viên.
- Cần ước tính thời gian và phụ thuộc giữa các tác vụ.

---

## 3. Quy trình thực hiện (4 bước)

### Bước 1: Khởi động lệnh

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--2" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```bash
bash
/plan [mô tả ngắn gọn về dự án hoặc tính năng]
```

*Ví dụ:*

```bash
bash
/plan hệ thống quản lý nhân sự với đăng nhập SSO,
phân quyền RBAC và báo cáo Excel
```

### Bước 2: Trả lời Câu hỏi Socratic

AI (`project-planner`) sẽ đặt một loạt câu hỏi làm rõ yêu cầu trước khi lên kế hoạch. Đây là **Cổng Socratic (Socratic Gate)** — bước bắt buộc để đảm bảo kế hoạch đúng ngay từ đầu.

Các câu hỏi thường xoay quanh:

- **Người dùng và quy mô:** Bao nhiêu người dùng? Loại người dùng nào?
- **Tech stack:** Đang dùng framework gì? Database nào?
- **Ràng buộc:** Deadline? Budget? Team size?
- **Tích hợp:** Có cần kết nối hệ thống nào khác không?
- **Ưu tiên:** MVP tối thiểu là gì? Tính năng nào có thể trì hoãn?

### Bước 3: AI lên kế hoạch

Sau khi bạn trả lời đủ câu hỏi, AI tổng hợp thông tin và tạo ra file kế hoạch.

### Bước 4: Xem xét và chỉnh sửa kế hoạch

File kế hoạch không phải là tài liệu cố định. Chỉnh sửa trực tiếp `PLAN.md` để:

- Điều chỉnh ưu tiên.
- Thêm/bớt tính năng.
- Phân công người phụ trách từng task.

---

## 4. Cấu trúc file kế hoạch đầu ra (`PLAN-{tên}.md`)

File kế hoạch thường được tạo tại `docs/PLAN-tên-dự-án.md` với nội dung đầy đủ:

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--4" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="44" data-line-number="44" data-line-start="44"><div class="line-content"></div></div></div></div></div></div>```markdown
markdown
# Kế hoạch: Hệ thống Quản lý Nhân sự


## Tổng quan
- Mô tả ngắn gọn về dự án
- Tech stack: Next.js 14, PostgreSQL, Prisma, NextAuth


## Phân tích yêu cầu
- Người dùng: HR Admin, Manager, Employee (3 vai trò)
- Quy mô: ~500 nhân viên, 50 manager
- ...


## Kiến trúc hệ thống
[Sơ đồ kiến trúc đơn giản]


## Phân rã tác vụ


### Giai đoạn 1: Nền tảng (Sprint 1-2)
- [ ] Thiết lập dự án Next.js
- [ ] Cấu hình database schema
- [ ] Triển khai SSO với NextAuth
- [ ] RBAC cơ bản (3 vai trò)


### Giai đoạn 2: Tính năng cốt lõi (Sprint 3-4)
- [ ] Module quản lý nhân viên (CRUD)
- [ ] Module chấm công
- [ ] Module nghỉ phép


### Giai đoạn 3: Báo cáo (Sprint 5)
- [ ] Dashboard tổng hợp
- [ ] Export Excel


## Phụ thuộc tác vụ
- RBAC cần hoàn thành trước các module nghiệp vụ
- Dashboard cần dữ liệu từ tất cả module khác


## Ước tính thời gian
- Tổng: ~5 sprint (10 tuần)
- MVP (Giai đoạn 1+2): 8 tuần


## Agent phụ trách
- database-architect: Schema thiết kế
- backend-specialist: API + Business logic
- frontend-specialist: UI/UX
- security-auditor: Review xác thực và phân quyền
```

---

## 5. Ví dụ phiên làm việc thực tế

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--6" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1">  
</div><div class="code-line" data-line-end="29" data-line-number="29" data-line-start="29"><div class="line-content"></div></div></div></div></div></div>```html
👤 Bạn: /plan tích hợp cổng thanh toán VNPAY vào ứng dụng Next.js
của tôi


🤖 AI (project-planner): Tôi cần làm rõ một số điểm để lên kế
hoạch chính xác:


1. Ứng dụng của bạn hiện đang ở giai đoạn nào?
(MVP mới, đang hoạt động, hay đang scale)
2. Bạn cần hỗ trợ những loại giao dịch nào?
(Thanh toán 1 lần, đăng ký định kỳ, hay cả hai)
3. Tech stack backend hiện tại là gì?
(Next.js API Routes, Express, hay gì khác)
4. Bạn cần xử lý hoàn tiền (refund) không?
5. Timeline mong muốn?


👤 Bạn:
1. Đang hoạt động, có ~500 đơn hàng/tháng
2. Thanh toán 1 lần cho đơn hàng
3. Next.js API Routes + PostgreSQL
4. Cần hoàn tiền một phần và toàn bộ
5. 2 tuần


🤖 AI: Tôi đã hiểu đủ thông tin. Đây là kế hoạch:


[Tạo file docs/PLAN-vnpay-integration.md với đầy đủ nội dung...]


✅ Đã tạo kế hoạch tại docs/PLAN-vnpay-integration.md
Kế hoạch bao gồm 3 giai đoạn, ước tính 8 ngày công.
Bạn có muốn điều chỉnh gì không?
```

---

## 6. Mẹo lập kế hoạch hiệu quả

### Trả lời đầy đủ câu hỏi Socratic

Câu hỏi càng chi tiết, kế hoạch càng chính xác. Đừng trả lời ngắn gọn như "bình thường" hay "tùy bạn".

### Định nghĩa MVP rõ ràng

```html
"MVP tối thiểu cho tôi là: có thể đăng nhập, xem danh sách
nhân viên và thêm mới. Các tính năng còn lại có thể phát hành sau."
```

### Chỉnh sửa kế hoạch ngay

Sau khi AI tạo kế hoạch:

- Mở file `PLAN.md` và đọc kỹ.
- Thêm người phụ trách (`@team-member`) vào từng task.
- Điều chỉnh độ ưu tiên nếu cần.

### Commit kế hoạch vào Git

```bash
bash
git add docs/PLAN-tên-dự-án.md
git commit -m "plan: add feature X implementation plan"
```

Điều này tạo lịch sử quyết định cho cả đội có thể tham khảo sau này.

---

## 7. Sau khi có kế hoạch: Bước tiếp theo

```html
Kế hoạch được phê duyệt ✅
│
▼
🔨 Triển khai:
/create [task đầu tiên trong kế hoạch]
hoặc
/enhance [tính năng cụ thể cần thêm vào]
```

# Trang 5.3: Xây dựng ứng dụng/tính năng mới từ đầu với /create.

## 1. Mục đích

**`/create`** đóng vai trò như một **trình thuật sĩ tạo ứng dụng (Application Creation Wizard)** — dẫn dắt bạn qua một cuộc hội thoại tương tác để hiểu yêu cầu, lên kế hoạch kiến trúc và điều phối các Agent chuyên gia cùng nhau xây dựng ứng dụng hoàn chỉnh.

> **Điểm khác biệt quan trọng:**
> 
> - `/create` = Xây dựng từ **trang giấy trắng (greenfield)**.
> - `/enhance` = Thêm vào hệ thống **đang hoạt động (brownfield)**.

---

## 2. Khi nào nên dùng `/create`?

✅ **Sử dụng `/create` khi:**

- Bắt đầu một dự án hoàn toàn mới.
- Tạo một module/service độc lập mới trong dự án lớn.
- Cần tạo nhanh một prototype để kiểm tra ý tưởng.
- Muốn triển khai một tính năng phức tạp từ đầu mà không lo ảnh hưởng code cũ.

---

## 3. Quy trình thực hiện (3 bước)

### Bước 1: Mô tả ứng dụng cần tạo

```bash
bash
/create [mô tả ứng dụng và các yêu cầu chính]
```

Cung cấp thông tin càng đầy đủ thì AI tạo ra code càng chính xác với nhu cầu của bạn.

### Bước 2: Xem xét và phê duyệt kế hoạch

Agent `app-builder` sẽ tổng hợp yêu cầu và đề xuất:

- **Tech stack:** Framework, database, thư viện chính.
- **Cấu trúc thư mục:** Cách tổ chức code.
- **Database schema:** Các bảng và quan hệ chính.
- **Danh sách tính năng:** Những gì sẽ được xây dựng.

Bạn cần phê duyệt (**Y**) hoặc yêu cầu điều chỉnh trước khi AI bắt đầu viết code.

### Bước 3: Các Agent cùng xây dựng

Sau khi phê duyệt, `orchestrator` sẽ điều phối các Agent chuyên gia:

```html
orchestrator điều phối:
├── database-architect → Tạo database schema và migrations
├── backend-specialist → Viết API endpoints và business logic
├── frontend-specialist → Xây dựng UI components và pages
└── test-engineer → Tạo bộ test cơ bản
```

---

## 4. Ví dụ phiên làm việc thực tế

### Ví dụ: Tạo ứng dụng quản lý công việc (Todo)

```html
👤 Bạn: /create ứng dụng todo có dark mode, xác thực người dùng,
phân loại task theo dự án, và có thể chia sẻ task với người khác


🤖 AI (app-builder):


📋 Kế hoạch xây dựng:


Tech Stack:
- Framework: Next.js 14 (App Router)
- Database: PostgreSQL + Prisma ORM
- Auth: NextAuth.js (Email + Google OAuth)
- UI: Tailwind CSS + shadcn/ui
- State: Zustand


Database Schema:
- User (id, email, name, avatar)
- Project (id, name, color, owner_id)
- Task (id, title, status, due_date, project_id, assignee_id)
- ProjectMember (project_id, user_id, role)


Tính năng sẽ tạo:
✅ Đăng ký/đăng nhập (Email + Google)
✅ Dark mode toggle
✅ CRUD Projects
✅ CRUD Tasks với drag-and-drop
✅ Chia sẻ project và gán task
✅ Bộ test cơ bản


Bạn có muốn tiến hành không? (Y/N)


👤 Bạn: Y (nhưng dùng MySQL thay vì PostgreSQL)


🤖 AI: Đã điều chỉnh sang MySQL. Đang bắt đầu xây dựng...


📦 database-architect: Đang tạo schema Prisma cho MySQL...
⚙️ backend-specialist: Đang tạo API routes...
🎨 frontend-specialist: Đang xây dựng components...
🧪 test-engineer: Đang viết test cases...


✅ Hoàn thành! Chạy lệnh sau để khởi động:
npm install && npx prisma migrate dev && npm run dev
```

---

## 5. Cấu trúc dự án được tạo ra (ví dụ Next.js)

```html
my-todo-app/
├── app/
│ ├── (auth)/
│ │ ├── login/page.tsx
│ │ └── register/page.tsx
│ ├── dashboard/
│ │ ├── layout.tsx
│ │ └── page.tsx
│ ├── projects/[id]/page.tsx
│ └── api/
│ ├── auth/[...nextauth]/route.ts
│ ├── projects/route.ts
│ └── tasks/route.ts
├── components/
│ ├── TaskCard.tsx
│ ├── ProjectList.tsx
│ └── ThemeToggle.tsx
├── lib/
│ ├── db.ts (Prisma client)
│ └── auth.ts (NextAuth config)
├── prisma/
│ └── schema.prisma
├── tests/
│ ├── api.test.ts
│ └── components.test.tsx
└── package.json
```

---

## 6. Mẹo để `/create` tạo ra kết quả tốt nhất

### Mô tả cụ thể và đầy đủ

```html
# Thiếu thông tin:
/create ứng dụng bán hàng


# Đầy đủ thông tin:
/create ứng dụng thương mại điện tử bán quần áo thời trang.
Người dùng có thể duyệt sản phẩm, thêm vào giỏ hàng,
thanh toán qua VNPay. Admin quản lý sản phẩm và đơn hàng.
Tech stack: Next.js + PostgreSQL + Stripe (nếu cần quốc tế).
MVP không cần: review, wishlist, loyalty points.
```

### Bắt đầu từ MVP

Tập trung vào tính năng cốt lõi. Sau khi có MVP chạy được, dùng `/enhance` để thêm dần.

```html
1. /create [core features only] → MVP
2. /enhance [feature A] → Version 1.1
3. /enhance [feature B] → Version 1.2
```

### Phê duyệt lần lượt từng thành phần

Nếu muốn kiểm soát chặt chẽ hơn, sau khi nhận kế hoạch:

```html
"Hãy tạo database schema trước để tôi review,
sau đó mới tiếp tục với backend."
```

---

## 7. Sau khi `/create` hoàn thành

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-b%C6%B0%E1%BB%9Bc-ti%E1%BA%BFp-theo-l%E1%BB%87nh-"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Bước tiếp theo</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Lệnh</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra ứng dụng</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/preview start`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Chạy tests</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/test`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Thêm tính năng mới</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/enhance [tính năng]`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra bảo mật</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Hỏi `@security-auditor review code này`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Triển khai</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/deploy`</td></tr></tbody></table>

</div>

# Trang 5.4: Nâng cấp và cải tiến mã nguồn hiện có với /enhance.

## 1. Mục đích và triết lý

**`/enhance`** là công cụ của vòng lặp phát triển hàng ngày — dùng để **thêm tính năng mới vào hệ thống đang chạy** mà không làm gián đoạn hoặc phá vỡ những gì đang hoạt động.

Triết lý cốt lõi của `/enhance` là **"phẫu thuật chính xác" (surgical precision)**: chỉ thay đổi đúng những gì cần thiết, không viết lại, không refactor không liên quan.

> **Khi nào `/enhance` vs `/create`?**
> 
> - **`/enhance`**: "Dự án đang chạy, tôi muốn thêm tính năng X" → ENHANCE
> - **`/create`**: "Tôi chưa có gì, tôi muốn xây dựng tính năng X từ đầu" → CREATE

---

## 2. Điều đặc biệt: Phân tích code trước khi thay đổi

Khác với `/create` (bắt đầu từ trang trắng), `/enhance` **bắt buộc phải đọc và hiểu codebase hiện tại** trước khi đề xuất bất kỳ thay đổi nào.

```html
/enhance [yêu cầu]
│
▼
📖 AI đọc cấu trúc dự án hiện tại
│
▼
🔍 Phân tích các file liên quan đến yêu cầu
│
▼
📋 Lập kế hoạch thay đổi tối thiểu cần thiết
│
▼
✅ Đề xuất plan → Bạn phê duyệt → AI triển khai
│
▼
🧪 Chạy kiểm tra để xác nhận không có regression
```

---

## 3. Phương pháp "Vertical Slice" (Lát cắt dọc)

Khi thêm tính năng mới, `/enhance` áp dụng phương pháp **Vertical Slice** — triển khai đầy đủ một tính năng theo chiều dọc từ database đến UI, thay vì làm từng lớp riêng lẻ.

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-v%C3%AD-d%E1%BB%A5%3A-th%C3%AAm-t%C3%ADnh-n%C4%83n" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5"><div class="font-sans text-sm text-ide-text-color opacity-60">  
</div><div class="flex flex-row gap-2 justify-end"></div></div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"><span class="mtk1">Ví dụ: Thêm tính năng "Bình luận bài viết"</span></div></div><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content">  
</div></div><div class="code-line" data-line-end="3" data-line-number="3" data-line-start="3"></div></div></div></div></div>```html
Vertical Slice (✅ cách /enhance làm):
├── Database: Bảng comments + migration
├── Backend: API /comments (GET, POST, DELETE)
├── Frontend: Component CommentSection + CommentItem
└── Testing: Unit test + Integration test


Thay vì (❌ cách dễ gây lỗi):
├── Tuần 1: Xong hết phần database
├── Tuần 2: Xong hết phần backend
└── Tuần 3: Xong hết phần frontend

Ưu điểm: Bạn có thể test và dùng tính năng ngay khi một Vertical Slice hoàn thành, không cần đợi toàn bộ.
```

---

## 4. Quy trình thực hiện

### Bước 1: Mô tả tính năng cần thêm

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--3" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```bash
bash
/enhance [mô tả tính năng + ràng buộc nếu có]
```

### Bước 2: AI phân tích codebase

AI sẽ đọc:

- <div>  
    </div><span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">package.json</span></span></span> để biết tech stack và thư viện.
- Cấu trúc thư mục `src/` để hiểu tổ chức code.
- Các file liên quan đến yêu cầu của bạn.

### Bước 3: AI đề xuất kế hoạch thay đổi

```html
📋 Kế hoạch thay đổi:


Tìm thấy:
- Framework: Next.js 14 với App Router
- Đang dùng Tailwind CSS
- Chưa có cấu hình dark mode


Thay đổi dự kiến:
1. Cập nhật tailwind.config.ts (thêm darkMode: 'class')
2. Tạo component ThemeProvider (dùng next-themes)
3. Tạo component ThemeToggle
4. Cập nhật app/layout.tsx để bọc trong ThemeProvider
5. Thêm class dark: vào các component chính


Thư viện cần cài: next-themes
Không ảnh hưởng đến: logic nghiệp vụ, database, API


Tiến hành? (Y/N)
```

### Bước 4: Phê duyệt và triển khai

Sau khi bạn xác nhận, AI triển khai từng thay đổi và chạy kiểm tra.

---

## 5. Ví dụ phiên làm việc thực tế

### Ví dụ 1: Thêm dark mode

```html
👤 Bạn: /enhance thêm dark mode toggle vào ứng dụng Next.js của tôi,
đảm bảo lưu lại tùy chọn của người dùng


🤖 AI: Đang phân tích codebase...


📊 Kết quả phân tích:
- Next.js 14 + App Router ✅
- Tailwind CSS ✅ (chưa có darkMode config)
- localStorage có thể dùng (không có SSR conflict nếu dùng next-themes)


📋 Kế hoạch (5 thay đổi):
1. npm install next-themes
2. Cập nhật tailwind.config.ts
3. Tạo ThemeProvider component
4. Tạo ThemeToggle button (sun/moon icon)
5. Cập nhật layout.tsx


Tiến hành? (Y/N)


👤 Bạn: Y


🤖 AI:
✅ Đã cài next-themes
✅ Đã cập nhật tailwind.config.ts
✅ Đã tạo components/ThemeProvider.tsx
✅ Đã tạo components/ThemeToggle.tsx
✅ Đã cập nhật app/layout.tsx


Chạy /preview start để xem kết quả.
Tùy chọn dark/light mode được lưu vào localStorage tự động.
```

### Ví dụ 2: Thêm tính năng dashboard analytics

```html
👤 Bạn: /enhance thêm dashboard analytics cho admin.
Cần: biểu đồ doanh thu 30 ngày, top 5 sản phẩm bán chạy,
số lượng đơn hàng theo trạng thái
Requirements:
- Dùng Recharts cho biểu đồ
- API endpoint riêng để aggregate data
- Chỉ admin mới xem được


🤖 AI: Đang phân tích codebase...


📊 Kết quả phân tích:
- Tìm thấy role-based auth trong middleware.ts
- Đang dùng Prisma + PostgreSQL
- Chưa có Recharts


📋 Kế hoạch (Vertical Slice):
Database: Không cần migration mới (aggregate từ bảng orders)
Backend: GET /api/admin/analytics (3 queries tổng hợp)
Frontend: Trang /admin/analytics với 3 chart components
Testing: Test API endpoint + mock data


Tiến hành? (Y/N)
```

---

## 6. Bảo vệ code hiện có — Các nguyên tắc an toàn

`/enhance` theo các nguyên tắc sau để không làm hỏng hệ thống:

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-nguy%C3%AAn-t%E1%BA%AFc-di%E1%BB%85n-gi%E1%BA%A3i"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Nguyên tắc</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Diễn giải</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Thay đổi tối thiểu**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chỉ tạo/sửa file thực sự cần thiết</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Cô lập tính năng**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tính năng mới trong thư mục/module riêng</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Không refactor ngoài phạm vi**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Không sửa những gì không liên quan đến yêu cầu</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Regression test**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chạy test hiện có sau mỗi thay đổi</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Phê duyệt trước khi làm**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Luôn trình bày kế hoạch để bạn xem xét trước</td></tr></tbody></table>

</div>---

## 7. Mẹo để `/enhance` hoạt động hiệu quả

### Kiểm tra dependencies trước

```html
"Trước khi thêm thư viện XYZ, hãy kiểm tra xem
nó có tương thích với phiên bản Node.js/React hiện tại không"
```

### Yêu cầu xem kế hoạch trước khi làm

Luôn đọc kỹ kế hoạch thay đổi trước khi gõ Y. Đặc biệt chú ý:

- Số lượng file bị thay đổi có hợp lý không?
- Có file nào "không liên quan" cũng bị sửa không?

### Yêu cầu test cụ thể

```html
/enhance thêm tính năng export CSV,
và viết test để đảm bảo CSV output đúng định dạng
```

### Dùng với `/test` sau mỗi lần enhance

```bash
bash
# Sau khi enhance xong
/test # Chạy toàn bộ test suite để kiểm tra regression
```

# Trang 5.5: Thiết kế giao diện Premium chuẩn UI-UX với /ui-ux-pro-max.

## 1. Mục đích

**`/ui-ux-pro-max`** là workflow chuyên biệt để tạo ra **giao diện web chất lượng cao, đẹp mắt và có tỉ lệ chuyển đổi cao** — đặc biệt là các trang Landing Page — trong thời gian tối thiểu.

Điểm khác biệt so với các cách thiết kế thông thường:

- Không phải output mẫu chung chung.
- AI áp dụng đúng **phong cách nghệ thuật** và **bảng màu** bạn chọn.
- Kết quả là code hoàn chỉnh: HTML semantic, components tái sử dụng, animations.

---

## 2. Thư viện phong cách NextLevelBuilder

Workflow này được tối ưu hóa để làm việc cùng với thư viện **50 phong cách thiết kế chuyên nghiệp** tại:

🔗 [nextlevelbuilder.io — Style Gallery](https://ui-ux-pro-max-skill.nextlevelbuilder.io/#styles)

Thư viện cung cấp:

- **50 Style Prompts** (Glassmorphism, Claymorphism, Neubrutalism, Modern SaaS, Minimalist...)
- **21 Bảng màu** đã được thiết kế và kiểm tra cẩn thận.
- **50 Font Combinations** phù hợp từng phong cách.

---

## 3. Quy trình thực hiện (3 bước)

### Bước 1: Chọn phong cách (tùy chọn nhưng khuyến nghị)

Truy cập [nextlevelbuilder.io](https://ui-ux-pro-max-skill.nextlevelbuilder.io/#styles), duyệt qua các phong cách và chọn một cái phù hợp với thương hiệu của bạn.

*Nếu không chọn cụ thể, AI sẽ tự đề xuất phong cách phù hợp dựa trên mô tả của bạn.*

### Bước 2: Chạy lệnh với mô tả đầy đủ

```bash
bash
/ui-ux-pro-max [mô tả trang + yêu cầu về phong cách, màu sắc, sections]
```

### Bước 3: AI xây dựng và bàn giao

AI tạo ra đầy đủ:

- **Cấu trúc HTML semantic** (chuẩn SEO, đúng heading hierarchy).
- **Các UI component** có thể tái sử dụng.
- **Micro-animations** và hiệu ứng hover.
- **Responsive design** hoạt động tốt trên mobile.

---

## 4. Ví dụ phiên làm việc

### Ví dụ 1: Landing page cho công ty dịch vụ thú cưng

```html
👤 Bạn: /ui-ux-pro-max tạo landing page cho dịch vụ chăm sóc thú cưng
cao cấp. Phong cách: Claymorphism với màu ấm áp và vui tươi.
Cần có: hero section, danh sách dịch vụ, gallery ảnh thú cưng,
bảng giá 3 gói, testimonials từ chủ thú cưng, và form đặt lịch.


🤖 AI:
📊 Phân tích phong cách:
Style: Claymorphism (3D soft shadows, rounded shapes)
Colors: Warm Amber #F59E0B + Rose #FB7185 + Cream #FEF3C7
Typography: Nunito (playful, rounded) + Inter (body)
Effects: Soft shadows, bouncy hover animations, gradient backgrounds


🏗️ Đang xây dựng...
✅ Tạo xong Hero Section với animated pet illustrations
✅ Tạo xong Services Grid (6 dịch vụ với icon claymorphism)
✅ Tạo xong Photo Gallery (masonry layout)
✅ Tạo xong Pricing Cards (3 gói với highlight card)
✅ Tạo xong Testimonial Carousel
✅ Tạo xong Booking Form với validation


📄 Tạo xong app/page.tsx
Chạy /preview start để xem kết quả.
```

### Ví dụ 2: Landing page SaaS fintech

```html
👤 Bạn: /ui-ux-pro-max landing page cho SaaS phân tích tài chính doanh nghiệp.
Phong cách: Glassmorphism dark mode với màu xanh navy và tím.
Sections: Hero với demo video, Features grid, Pricing 3 plans,
Dashboard preview screenshot, FAQ, CTA cuối trang.


🤖 AI:
📊 Phân tích phong cách:
Style: Glassmorphism + Dark Mode
Colors: Navy #0F172A bg + Blue #3B82F6 primary + Violet #8B5CF6 accent
Typography: Inter (clean, professional)
Effects: Glass cards với backdrop-blur, gradient glow effects,
subtle particle animations


[AI triển khai từng section...]


✅ Hoàn thành! High-conversion SaaS landing page ready.
```

---

## 5. Cách mô tả yêu cầu hiệu quả

### Mô tả theo 4 yếu tố

```html
/ui-ux-pro-max [Loại trang] cho [Đối tượng/Ngành]
                        [Phong cách + Màu sắc]
                        [Danh sách sections]
                        [Yêu cầu đặc biệt nếu có]
```

**Ví dụ hoàn chỉnh:**

```html
/ui-ux-pro-max Landing page cho startup EdTech dạy lập trình online.
                        Phong cách: Modern SaaS với gradient tím-xanh, clean và chuyên nghiệp.
                        Sections: Hero (headline + CTA), Course Preview (3 khóa học),
                       Instructor bio, Student results/stats, Pricing (monthly/yearly),
                       FAQ, và footer với newsletter signup.
                       Đặc biệt: Thêm countdown timer cho giá khuyến mãi.
```

### Các từ khóa phong cách phổ biến

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-t%E1%BB%AB-kh%C3%B3a-gi%E1%BA%A3i-th%C3%ADch-g"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Từ khóa</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Giải thích</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`Glassmorphism`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Card kính trong suốt, blur background, thường dùng với dark mode</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`Claymorphism`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Hình khối 3D mềm mại, màu ấm, bóng đổ dày</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`Neubrutalism`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Viền đen dày, màu sắc bold, không gradient, phong cách "thô"</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`Modern SaaS`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Sạch, tối giản, tập trung vào product screenshot</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`Minimalist`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Nhiều khoảng trống, typography nổi bật</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`Gradient mesh`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Màu gradient phức tạp, hiệu ứng ánh sáng</td></tr></tbody></table>

</div>---

## 6. Kết quả bàn giao

Sau khi `/ui-ux-pro-max` hoàn thành, bạn nhận được:

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-th%C3%A0nh-ph%E1%BA%A7n-m%C3%B4-t%E1%BA%A3-app"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Thành phần</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mô tả</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20"><div>  
</div>**<span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">app/page.tsx</span></span></span>**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Trang chính với tất cả sections</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**`components/`**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Các UI components tái sử dụng (Hero, Pricing, Testimonial...)</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**CSS/Tailwind**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Styles theo đúng phong cách đã chọn</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**SEO meta tags**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Title, description, OG tags</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Accessibility**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">ARIA labels, keyboard navigation</td></tr></tbody></table>

</div>---

## 7. Bước tiếp theo sau khi tạo giao diện

```bash
bash
/preview start # Xem kết quả ngay tại localhost:3000
/enhance [thay đổi cụ thể] # Điều chỉnh màu sắc, nội dung...
/deploy # Đưa lên production khi hài lòng
```

# Trang 5.6: Protocol 4 bước sửa lỗi có hệ thống với /debug.

## 1. Vấn đề với cách debug thông thường

Cách debug phổ biến nhất: **thấy lỗi → thử sửa ngay → không được → thử sửa khác → vẫn không được → frustration**.

Đây là cách tiếp cận theo kiểu "đoán mò" (guess-driven debugging). Nó tốn thời gian và dễ gây thêm lỗi mới.

**`/debug`** giải quyết vấn đề này bằng cách bắt buộc AI tuân thủ một **giao thức điều tra 4 giai đoạn dựa trên bằng chứng**. Không được phép sửa code cho đến khi có bằng chứng xác định nguyên nhân gốc rễ.

---

## 2. Giao thức 4 giai đoạn

### Giai đoạn 1: Discovery (Khám phá)

**Mục tiêu:** Thu thập toàn bộ sự kiện liên quan.

AI sẽ:

- Đọc error logs và stack trace (nếu bạn cung cấp).
- Xác định điều kiện tái hiện lỗi (repro steps).
- Đọc các file code liên quan đến khu vực bị lỗi.
- Thu thập thông tin môi trường (OS, version, config).

### Giai đoạn 2: Hypothesis (Giả thuyết)

**Mục tiêu:** Liệt kê các nguyên nhân tiềm năng theo thứ tự xác suất.

AI tạo danh sách giả thuyết, ví dụ:

```html
Giả thuyết 1 (Xác suất cao): emailRef.current là null khi submit
Giả thuyết 2 (Xác suất trung bình): Event handler bị bind sai context
Giả thuyết 3 (Xác suất thấp): Race condition trong async operation
```

### Giai đoạn 3: Verification (Xác minh)

**Mục tiêu:** Kiểm tra từng giả thuyết bằng bằng chứng cụ thể, **không suy đoán**.

AI kiểm tra bằng:

- Đọc code liên quan đến giả thuyết.
- Thêm logging tạm thời để quan sát giá trị.
- Tham chiếu đến tài liệu chính thức hoặc lịch sử thay đổi (git log).

### Giai đoạn 4: Resolution (Giải quyết)

**Mục tiêu:** Sửa đúng nguyên nhân gốc rễ + ngăn lỗi tái phát.

AI thực hiện:

1. Áp dụng bản sửa lỗi tối thiểu (minimal fix).
2. Giải thích tại sao cách sửa này đúng.
3. **Viết regression test** — test case để đảm bảo lỗi không quay lại.
4. Gợi ý cải thiện thêm nếu có.

---

## 3. Khi nào nên dùng `/debug`?

✅ **Lý tưởng cho:**

- "Nút submit không phản hồi gì, không có lỗi console."
- "API trả về 500 một cách ngẫu nhiên (intermittent)."
- "Ứng dụng crash chỉ trên một thiết bị/browser cụ thể."
- "Sau khi deploy, một tính năng vốn hoạt động tốt bỗng dưng hỏng."

❌ **Không cần dùng cho:**

- Lỗi typo rõ ràng, lỗi cú pháp đơn giản.
- Lỗi mà bạn đã biết nguyên nhân và chỉ cần sửa.

---

## 4. Ví dụ phiên làm việc thực tế

### Lỗi: Form submit im lặng

```html
👤 Bạn: /debug Form checkout của tôi bị lỗi. Khi click nút "Đặt hàng"
thì không có gì xảy ra cả, không có lỗi nào trong console.
Đây là stack trace khi tôi thêm try-catch:
TypeError: Cannot read properties of undefined (reading 'email')
at handleSubmit (CheckoutForm.tsx:47)


🤖 AI (debugger):
=== Phase 1: Discovery ===


Đang đọc CheckoutForm.tsx...


Tìm thấy hàm handleSubmit tại dòng 45-62.
Quan sát: formData.email được truy cập tại dòng 47,
nhưng formData được khởi tạo là undefined.


=== Phase 2: Hypothesis ===


GIẢ THUYẾT 1 (Xác suất 85%):
formData chưa được khởi tạo đúng — state ban đầu là undefined thay vì {}


GIẢ THUYẾT 2 (Xác suất 10%):
useForm() hook chưa hoàn tất khởi tạo khi component mount


GIẢ THUYẾT 3 (Xác suất 5%):
Event không được preventDefault(), gây page reload trước khi chạy code


=== Phase 3: Verification ===


Kiểm tra state khởi tạo tại dòng 12:
const [formData, setFormData] = useState(); ← LỖI!


✅ Xác nhận Giả thuyết 1: useState() không có giá trị mặc định


=== Phase 4: Resolution ===


Sửa dòng 12:
Cũ: const [formData, setFormData] = useState();
Mới: const [formData, setFormData] = useState({ email: '', name: '', address: '' });


✅ Đã áp dụng bản sửa lỗi
✅ Đã thêm regression test: "Form không submit khi formData undefined"


💡 Gợi ý thêm: Cân nhắc dùng TypeScript interface để
compiler phát hiện lỗi này sớm hơn.
```

### Lỗi: API 500 ngẫu nhiên

```html
👤 Bạn: /debug API /api/orders trả về 500 khoảng 1/5 lần gọi.
Không tái hiện được một cách nhất quán.
Server log:
Error: Connection terminated unexpectedly
at Connection.parseE (pg.js:234)


🤖 AI (debugger):
=== Phase 1: Discovery ===
Kiểm tra database connection pooling...
Tìm thấy: Pool size = 1, query timeout = 30s


=== Phase 2: Hypothesis ===
GIẢ THUYẾT 1: Connection pool cạn kiệt dưới tải cao
GIẢ THUYẾT 2: Database connection timeout không được xử lý
GIẢ THUYẾT 3: Race condition giữa các concurrent requests


=== Phase 3: Verification ===
Đọc db.ts: Pool maxConnections = 1 ← BẤT THƯỜNG
Error message "terminated unexpectedly" = timeout issue (không phải query lỗi)
✅ Xác nhận Giả thuyết 1: Pool size quá nhỏ cho concurrent requests


=== Phase 4: Resolution ===
[Gợi ý cấu hình pool size phù hợp + retry logic...]
```

---

## 5. Cách cung cấp thông tin để debug nhanh hơn

### Cung cấp đầy đủ context ngay từ đầu

```html
/debug [Mô tả lỗi]


Thông tin thêm:
- Stack trace: [paste toàn bộ error message]
- Bước tái hiện: [1. Làm A, 2. Làm B, 3. Lỗi xuất hiện]
- Môi trường: [Node 20, Next.js 14, macOS]
- Khi nào bắt đầu xảy ra: [Sau khi update thư viện X / deploy hôm qua]
```

### Yêu cầu xác nhận sau khi sửa

```html
"Sau khi sửa xong, hãy tạo test case để xác nhận lỗi không tái phát,
và chạy lại test suite để đảm bảo không có regression."
```

---

## 6. Điều Agent `debugger` tuyệt đối không làm

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-%E2%9D%8C-kh%C3%B4ng-%E2%9C%85-thay-v%C3%A0o-%C4%91"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">❌ Không</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">✅ Thay vào đó</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Đoán nguyên nhân và sửa ngay</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Thu thập bằng chứng trước</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Thay đổi nhiều thứ cùng lúc</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Thay đổi từng thứ một và verify</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">"Thử cái này xem sao"</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Giải thích tại sao cách sửa này đúng</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Bỏ qua viết regression test</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Luôn thêm test sau khi sửa</td></tr></tbody></table>

</div>

# Trang 5.7: Tự động hóa kiểm thử mã nguồn với /test.

## 1. Mục đích

**`/test`** là workflow để tự động hóa toàn bộ vòng đời kiểm thử — từ tạo test case, chạy bộ test hiện có, đến báo cáo độ bao phủ (coverage).

> **Triết lý:** Code không có test = code chưa hoàn chỉnh. `/test` giúp đội ngũ duy trì tiêu chuẩn kiểm thử mà không cần mất nhiều thời gian viết test thủ công.

---

## 2. Các chức năng của `/test`

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-c%C3%BA-ph%C3%A1p-ch%E1%BB%A9c-n%C4%83ng-%2Ft"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Cú pháp</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Chức năng</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/test`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chạy toàn bộ test suite hiện có</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/test [file hoặc thư mục]`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tạo test cases cho file cụ thể</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/test coverage`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Báo cáo tỉ lệ bao phủ (coverage report)</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/test --watch`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chế độ live — tự chạy lại khi code thay đổi</td></tr></tbody></table>

</div>---

## 3. Cách `/test` phân tích và tạo test

Khi nhận lệnh `/test [file]`, AI sẽ:

```html
1. Đọc toàn bộ nội dung file được chỉ định
│
▼
2. Xác định tất cả functions và classes cần test
│
▼
3. Phân tích input/output, edge cases, và error paths
│
▼
4. Tạo test file tương ứng với bộ test đầy đủ:
- Happy path (trường hợp bình thường)
- Error cases (xử lý lỗi)
- Edge cases (giá trị biên)
- Null/undefined inputs
│
▼
5. Chạy test vừa tạo và báo cáo kết quả
```

---

## 4. Ví dụ phiên làm việc thực tế

### Ví dụ 1: Tạo test cho authentication service

```html
👤 Bạn: /test src/services/auth.ts


🤖 AI:
📖 Đang phân tích auth.ts...


Tìm thấy 4 functions cần test:
- login(email, password): Promise<User>
- register(userData): Promise<User>
- verifyToken(token): boolean
- resetPassword(email): Promise<void>


🧪 Đang tạo test cases...


login():
✅ Trả về User khi credentials đúng
✅ Throw AuthError khi email không tồn tại
✅ Throw AuthError khi sai mật khẩu
✅ Throw ValidationError khi email không hợp lệ


register():
✅ Tạo User mới và trả về object
✅ Throw DuplicateError khi email đã tồn tại
✅ Hash password trước khi lưu (không lưu plaintext)
✅ Validate required fields


verifyToken():
✅ Trả về true với token hợp lệ
✅ Trả về false với token hết hạn
✅ Trả về false với token giả mạo
✅ Xử lý null/undefined input


resetPassword():
✅ Gửi email reset khi user tồn tại
✅ Không tiết lộ user không tồn tại (security)


📄 Đã tạo: tests/auth.test.ts (12 test cases)


🏃 Đang chạy tests...


✅ 12/12 PASSED
📊 Coverage: 95% (Statements), 91% (Branches)
```

### Ví dụ 2: Chạy toàn bộ test suite

```html
👤 Bạn: /test


🤖 AI:
🏃 Đang chạy toàn bộ test suite...


✅ auth.test.ts — 12/12 passed (0.8s)
✅ orders.test.ts — 8/8 passed (1.2s)
❌ products.test.ts — 5/7 passed (FAILED)
FAIL: "calculateDiscount returns 0 for expired coupons"
Expected: 0
Received: 10
✅ users.test.ts — 6/6 passed (0.5s)


📊 Summary:
Tests: 31 passed, 2 failed
Coverage: 78%


❌ 2 tests failed. Gợi ý: chạy /debug để điều tra calculateDiscount.
```

### Ví dụ 3: Xem coverage report

```html
👤 Bạn: /test coverage


🤖 AI:
📊 Coverage Report


File | Stmts | Branch | Funcs | Lines
------------------------|-------|--------|-------|------
src/services/auth.ts | 95% | 91% | 100% | 95%
src/services/orders.ts | 82% | 75% | 88% | 82%
src/utils/validators.ts | 60% | 45% | 70% | 60%


⚠️ validators.ts có coverage thấp (60%).
Gợi ý: chạy /test src/utils/validators.ts để bổ sung test.
```

---

## 5. Các nguyên lý kiểm thử được áp dụng

### AAA Pattern (Arrange-Act-Assert)

Mọi test case đều theo cấu trúc:

```typescript
typescript
it('login returns User khi credentials đúng', async () => {
// Arrange — Chuẩn bị dữ liệu test
const mockUser = { email: 'test@example.com', password: 'hashed' };
mockDB.findUser.mockResolvedValue(mockUser);


// Act — Thực hiện hành động cần test
const result = await login('test@example.com', 'correct-password');


// Assert — Kiểm tra kết quả
expect(result).toEqual(expect.objectContaining({ email: 'test@example.com' }));
expect(result.password).toBeUndefined(); // Không trả về password
});
```

### Test hành vi, không test implementation

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--4" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="5" data-line-number="5" data-line-start="5"><div class="line-content"></div></div></div></div></div></div>```typescript
typescript
// ❌ Test implementation (dễ vỡ khi refactor)
expect(service._privateMethod).toHaveBeenCalled();


// ✅ Test hành vi (bền vững)
expect(result.email).toBe('user@example.com');
```

### Kim tự tháp kiểm thử

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--5" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1">  
</div><div class="code-line" data-line-end="7" data-line-number="7" data-line-start="7"><div class="line-content"></div></div></div></div></div></div>```html
       /\
      /E2E\ (ít nhất, chậm nhất, tốn kém nhất)
     /------\
    /Integration\ (vừa phải)
   /------------\
  / Unit Tests \ (nhiều nhất, nhanh nhất, rẻ nhất)
/________________\
```

---

## 6. Mẹo kiểm thử hiệu quả

### Luôn kiểm tra edge cases

Sau khi AI tạo test, yêu cầu thêm:

```html
"Thêm test cases cho:
- Input rỗng (empty string, [], {})
- Giá trị giới hạn (0, -1, MAX_INT)
- Null và undefined
- Chuỗi unicode và ký tự đặc biệt"
```

### Tích hợp vào quy trình `/enhance`

```html
bash
# Sau mỗi lần thêm tính năng mới:
/test [file vừa tạo] # Tạo test cho code mới
/test # Chạy toàn bộ để kiểm tra regression
```

### Yêu cầu mock đúng cách

```html
"/test src/services/payment.ts
Lưu ý: mock VNPay API, không gọi endpoint thực.
Và mock database, không dùng test database."
```

---

## 7. Frameworks được hỗ trợ

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-framework-file-patte"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Framework</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">File pattern</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Ghi chú</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Jest**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`*.test.ts`, `*.spec.ts`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Phổ biến nhất với React/Node</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Vitest**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`*.test.ts`, `*.spec.ts`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Nhanh hơn Jest, dành cho Vite</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Playwright**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`e2e/*.spec.ts`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">E2E testing, browser automation</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**pytest**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`test_*.py`, `*_test.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Python projects</td></tr></tbody></table>

</div>AI tự phát hiện framework đang dùng từ <span class="inline-flex break-all leading-tight">package.json</span> và tạo test theo đúng syntax.

# Trang 5.8: Quản lý môi trường xem trước và theo dõi tiến độ (/preview & /status).

## 1. Tổng quan

Trang này hướng dẫn hai workflow đơn giản nhưng cực kỳ hữu ích trong công việc hàng ngày:

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-workflow-m%E1%BB%A5c-%C4%91%C3%ADch-%2Fp"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Workflow</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mục đích</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/preview`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Quản lý server phát triển cục bộ</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/status`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Xem tổng quan tiến độ và trạng thái dự án</td></tr></tbody></table>

</div>---

## Phần A: `/preview` — Quản lý server phát triển

### A.1. Các lệnh `/preview`

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-l%E1%BB%87nh-ch%E1%BB%A9c-n%C4%83ng-%2Fprev"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Lệnh</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Chức năng</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/preview start`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Khởi động server phát triển</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/preview stop`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Dừng server đang chạy</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/preview restart`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Khởi động lại server (áp dụng config mới)</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`/preview`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra trạng thái hiện tại</td></tr></tbody></table>

</div>### A.2. Tính năng tự động nhận diện framework

Workflow này đủ thông minh để **tự nhận diện** loại dự án và chạy đúng lệnh:

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-framework-l%E1%BB%87nh-%C4%91%C6%B0%E1%BB%A3c-"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Framework</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Lệnh được chạy tự động</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Next.js</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`npm run dev` (port 3000)</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Vite</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`npm run dev` (port 5173)</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Create React App</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`npm start` (port 3000)</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Express/Node.js</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`node server.js` hoặc `npm start`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">FastAPI (Python)</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`uvicorn main:app --reload`</td></tr></tbody></table>

</div>### A.3. Xử lý xung đột Port

Nếu port mặc định (3000) đã bị chiếm bởi ứng dụng khác:

```html
🤖 AI: Port 3000 đang bận.
Đề xuất alternatives:
- Port 3001 ✅ (available)
- Port 8080 ✅ (available)


Dùng port 3001? (Y/N)
```

### A.4. Ví dụ phiên làm việc

```html
👤 Bạn: /preview start


🤖 AI:
   🔍 Đang phát hiện framework...
   ✅ Tìm thấy: Next.js 14 (App Router)


   📦 Đang khởi động...
   Running: npm run dev


   ✅ Preview sẵn sàng!
   URL: http://localhost:3000


Server sẽ tiếp tục chạy. Dùng /preview stop để tắt.


👤 Bạn: /preview


🤖 AI:
   📊 Preview Status
   -----------------
   Status: 🟢 Running
   URL: http://localhost:3000
   Framework: Next.js 14
   Port: 3000
   Uptime: 12 phút


👤 Bạn: /preview stop


🤖 AI:
   ⏹️ Đã dừng server preview.
   Port 3000 đã được giải phóng.
```

### A.5. Khi nào dùng `/preview`

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-t%C3%ACnh-hu%E1%BB%91ng-l%E1%BB%87nh-sau-"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Tình huống</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Lệnh</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Sau khi `/create` hoặc `/enhance` xong</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/preview start`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Cần xem UI thay đổi trên trình duyệt</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/preview start`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Thay đổi cấu hình (next.config.js...)</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/preview restart`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Trước khi tắt máy</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/preview stop`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Không nhớ server có đang chạy không</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`/preview`</td></tr></tbody></table>

</div>---

## Phần B: `/status` — Bảng điều khiển tiến độ dự án

### B.1. Mục đích

Lệnh `/status` cung cấp **bảng điều khiển tổng thể** (dashboard) để bạn nắm bắt nhanh tình trạng hiện tại của dự án, bao gồm: thông tin kỹ thuật, tiến độ các Agent đang làm việc, và trạng thái server.

### B.2. Cú pháp

```bash
bash
/status
```

### B.3. Thông tin được hiển thị

```bash
=== Project Status ===


📁 Project Information
Name: my-ecommerce-app
Type: Next.js + PostgreSQL
Version: 1.2.0
Files: 147 total (73 created, 12 modified, 62 unchanged)


=== Agent Status ===


✅ database-architect → Completed (Schema + Migrations)
✅ backend-specialist → Completed (All API Endpoints)
🔄 frontend-specialist → In Progress (60% — Cart Page)
⏳ test-engineer → Waiting (Pending frontend completion)


=== Test Results ===


✅ Unit Tests: 45/45 passed
✅ Integration Tests: 12/12 passed
⚠️ E2E Tests: 8/10 passed (2 failing)


=== Preview ===


🌐 URL: http://localhost:3000
💚 Health: OK (responding in 124ms)
```

### B.4. Ví dụ phiên làm việc

```html
👤 Bạn: /status


🤖 AI:


=== 📊 PROJECT STATUS ===


📁 my-saas-app (Next.js + Prisma + PostgreSQL)
Files: 89 tổng (34 mới tạo hôm nay)
Branch: feature/payment-integration


=== 🤖 AGENT STATUS ===


✅ database-architect → DONE — Payment schema + Stripe webhook table
✅ backend-specialist → DONE — /api/payments (create, confirm, refund)
✅ security-auditor → DONE — Reviewed, không có high-severity issues
🔄 frontend-specialist → 70% — Đang tạo CheckoutPage...
⏳ test-engineer → Chưa bắt đầu


=== 🧪 TEST STATUS ===


✅ 38 tests passed | ❌ 0 failed | 📊 Coverage: 82%


=== 🌐 PREVIEW ===


Status: 🟢 Running — http://localhost:3000
Response time: 89ms


=== 💡 NEXT STEPS ===


1. Chờ frontend-specialist hoàn thành CheckoutPage (~30 phút)
2. Chạy /test để tạo test cho payment flow
3. Chạy /deploy khi tất cả test pass
```

### B.5. Khi nào dùng `/status`

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-t%C3%ACnh-hu%E1%BB%91ng-l%C3%BD-do-%C4%90%E1%BA%A7u"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Tình huống</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Lý do</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Đầu ngày làm việc</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Nhắc lại tiến độ từ hôm qua</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Sau khi `/orchestrate` phức tạp</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra tất cả Agent đã xong chưa</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Trước khi `/deploy`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Đảm bảo mọi thứ xanh trước khi đẩy lên production</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Khi bàn giao cho đồng đội</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chia sẻ trạng thái hiện tại nhanh chóng</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Khi không nhớ đang làm đến đâu</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Lấy lại ngữ cảnh công việc</td></tr></tbody></table>

</div>---

## Phần C: Vòng lặp phát triển kết hợp

Sử dụng `/preview` và `/status` trong quy trình hàng ngày:

```html
🌅 Bắt đầu ngày làm việc:
/status → Xem lại tiến độ hôm qua
/preview start → Khởi động server để làm việc


🔨 Trong giờ làm:
/enhance [feature] → Thêm tính năng
/preview start → Xem kết quả
/test → Kiểm tra không có regression


🌇 Cuối ngày:
/status → Tổng kết tiến độ hôm nay
/preview stop → Tắt server


🚀 Trước khi deploy:
/status → Xác nhận tất cả Agent xong việc
/test → Đảm bảo tất cả test pass
/deploy → Triển khai
```

# Chương 6: Quy tắc & Tiêu chuẩn phát triển (Rules & Masters)

# Trang 6.1: Tìm hiểu về file quy tắc GEMINI.md và cách tùy chỉnh hành vi AI.

## 1. `GEMINI.md` là gì?

**`GEMINI.md`** là file quan trọng nhất trong toàn bộ hệ thống Antigravity Kit. Nó nằm tại:

```html
.agent/rules/GEMINI.md
```

File này là **"hiến pháp"** định nghĩa cách AI phải hành xử trong **mọi** tình huống. Khi AI đọc file này, nó hiểu rõ:

- **Ưu tiên nào cao hơn** (quy tắc nào được áp dụng khi có xung đột).
- **Phân loại yêu cầu** như thế nào (câu hỏi, code đơn giản, task phức tạp).
- **Chọn Agent** nào cho từng loại yêu cầu.
- **Các quy tắc code toàn cục** phải tuân thủ.

---

## 2. Kiến trúc phân cấp ưu tiên

```html
P0: GEMINI.md ← Cao nhất — luôn có hiệu lực
P1: Agent .md ← Quy tắc riêng của từng Agent
P2: SKILL.md ← Kiến thức chuyên sâu từng lĩnh vực
```

Khi có xung đột giữa các cấp, cấp cao hơn luôn thắng.

---

## 3. Cấu trúc của `GEMINI.md`

File được tổ chức theo hệ thống **TIER** (Tầng):

### TIER 0 — Universal Rules (Luôn áp dụng)

Các quy tắc này hoạt động trong **mọi** yêu cầu, bất kể Agent nào được kích hoạt:

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-quy-t%E1%BA%AFc-n%E1%BB%99i-dung-lan"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Quy tắc</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Nội dung</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Language Handling**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Khi người dùng không dùng tiếng Anh, AI dịch nội bộ nhưng trả lời bằng ngôn ngữ của người dùng</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Clean Code**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Mọi code phải theo tiêu chuẩn `clean-code` — ngắn gọn, tự mô tả, không over-engineer</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**File Dependency Awareness**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Trước khi sửa file nào, kiểm tra file phụ thuộc và cập nhật đồng bộ</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**System Map Read**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Đọc <div>  
</div><span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">ARCHITECTURE.md</span></span></span> khi khởi động để hiểu hệ sinh thái</td></tr></tbody></table>

</div>### Request Classifier — Phân loại yêu cầu

Bảng phân loại tự động để AI biết cần làm gì:

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-lo%E1%BA%A1i-y%C3%AAu-c%E1%BA%A7u-t%E1%BB%AB-kh%C3%B3a"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Loại yêu cầu</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Từ khóa kích hoạt</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Kết quả</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**QUESTION**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">"là gì", "giải thích", "tại sao"</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chỉ trả lời văn bản</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**SURVEY**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">"phân tích", "liệt kê", "tổng quan"</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Phân tích, không tạo file</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**SIMPLE CODE**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">"sửa", "thêm", "đổi" (1 file)</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chỉnh sửa trực tiếp</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**COMPLEX CODE**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">"xây dựng", "tạo", "triển khai"</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tạo file kế hoạch <div>  
</div><span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">.md</span></span></span></td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**DESIGN/UI**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">"thiết kế", "UI", "giao diện"</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tạo file kế hoạch + components</td></tr></tbody></table>

</div>### Intelligent Routing Checklist

Checklist bắt buộc AI phải hoàn thành trước khi viết code:

```html
Bước 1: Đã xác định Agent phù hợp chưa?
Bước 2: Đã đọc file .md của Agent chưa?
Bước 3: Đã thông báo Agent cho người dùng chưa?
Bước 4: Đã tải Skills cần thiết chưa?
```

### TIER 1 — Code Rules (Khi viết code)

Chỉ áp dụng khi AI cần viết hoặc sửa code:

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-quy-t%E1%BA%AFc-n%E1%BB%99i-dung-pro"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Quy tắc</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Nội dung</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Project Type Routing**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Mobile → `mobile-developer`, Web → `frontend-specialist`, API → `backend-specialist`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Socratic Gate**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Với tác vụ phức tạp: bắt buộc hỏi ít nhất 3 câu làm rõ trước khi code</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Final Checklist Protocol**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Khi người dùng nói "final checks", chạy <div>  
</div><span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">checklist.py</span></span></span></td></tr></tbody></table>

</div>---

## 4. Tùy chỉnh `GEMINI.md` cho đội ngũ của bạn

### Nguyên tắc tùy chỉnh an toàn

**✅ Có thể sửa:**

- Thêm quy tắc mới vào cuối file.
- Thêm các ràng buộc về ngôn ngữ lập trình hoặc naming convention.
- Định nghĩa các pattern bị cấm trong dự án.

**⚠️ Cẩn thận khi sửa:**

- Bảng Request Classifier (có thể làm AI nhận diện sai loại yêu cầu).
- Agent Routing rules (có thể gây định tuyến sai Agent).

**❌ Không nên xóa:**

- Cấu trúc TIER 0 và TIER 1 cơ bản.
- Intelligent Routing Checklist.

### Ví dụ tùy chỉnh thực tế

**Thêm quy tắc ngôn ngữ:**

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--3" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5"></div></div>```markdown
markdown
## CUSTOM TEAM RULES


### Quy tắc ngôn ngữ
- Tất cả comment trong code phải bằng tiếng Anh
- Tên biến và hàm theo camelCase (không dùng snake_case trong JS/TS)
- Không dùng `any` trong TypeScript — phải có type cụ thể

Thêm pattern bị cấm:

markdown
### Các pattern bị cấm trong dự án này
- KHÔNG dùng `console.log` trong production code (dùng logger service)
- KHÔNG hard-code URL — phải dùng environment variables
- KHÔNG commit secret key hoặc password
- KHÔNG viết SQL raw — phải dùng Prisma ORM

Thêm convention đặt tên:

markdown
### Naming Convention
- Component: PascalCase (UserCard, ProductList)
- Hook: camelCase bắt đầu bằng "use" (useAuth, useCart)
- File component: PascalCase.tsx
- File util: camelCase.ts
- Test file: tên-file.test.ts

Thêm quy tắc về Tech Stack:

markdown
### Tech Stack bắt buộc cho dự án này
- Framework: Next.js 14 (App Router) — không dùng Pages Router
- Styling: Tailwind CSS — không dùng CSS Modules hay styled-components
- Database: Prisma + PostgreSQL — không dùng raw SQL
- Auth: NextAuth.js — không tự viết auth logic
```

---

## 5. Chia sẻ cấu hình với cả đội

Để toàn đội cùng dùng chung một bộ quy tắc:

```bash
bash
# Commit thư mục .agent/ vào Git
git add .agent/
git commit -m "chore: add/update Antigravity Kit team rules"
git push
```

Khi thành viên mới clone dự án, họ sẽ tự động có đầy đủ cấu hình đã được thống nhất.

---

## 6. Kiểm tra quy tắc có được áp dụng không

Sau khi sửa `GEMINI.md`, bạn có thể kiểm tra bằng cách:

```html
👤 Bạn: "Hãy kiểm tra và cho tôi biết các quy tắc nào bạn
đang áp dụng cho dự án này"


🤖 AI: Tôi đang áp dụng các quy tắc từ .agent/rules/GEMINI.md:
- TIER 0: Universal Rules (Language, Clean Code...)
- Custom Team Rules: No console.log, PascalCase components...
- Tech Stack: Next.js 14 App Router, Tailwind CSS...
```

# Trang 6.2: Sử dụng các script kiểm tra tổng thể (  checklist.py  &   verify_all.py ).

## 1. Tổng quan

Antigravity Kit cung cấp 2 script Python tổng thể (master scripts) trong thư mục `.agent/scripts/`. Chúng điều phối toàn bộ bộ script con từ các Skills để thực hiện kiểm tra chất lượng dự án một cách có hệ thống.

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-script-m%E1%BB%A5c-%C4%91%C3%ADch-khi-"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Script</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mục đích</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Khi nào dùng</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`checklist.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra nhanh theo thứ tự ưu tiên</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Hàng ngày, trước commit</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`verify_all.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra toàn diện bao gồm E2E và performance</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Trước khi release production</td></tr></tbody></table>

</div>---

## 2. `checklist.py` — Kiểm tra hàng ngày

### Cú pháp

```bash
bash
# Kiểm tra cơ bản
python .agent/scripts/checklist.py .


# Kiểm tra đầy đủ kèm performance (cần server đang chạy)
python .agent/scripts/checklist.py . --url http://localhost:3000
```

### Thứ tự ưu tiên kiểm tra (P0 → P6)

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-m%E1%BB%A9c-t%C3%AAn-c%C3%B4ng-c%E1%BB%A5-d%E1%BB%ABng"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mức</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Tên</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Công cụ</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Dừng nếu lỗi?</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**P0**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Security Scan</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`security_scan.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Có — Critical</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**P1**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Lint &amp; Type Check</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`lint_runner.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Có — Critical</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**P2**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Schema Validation</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`schema_validator.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">❌ Không</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**P3**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Test Runner</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`test_runner.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">❌ Không</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**P4**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">UX Audit</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`ux_audit.py` + `accessibility_checker.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">❌ Không</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**P5**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">SEO Check</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`seo_checker.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">❌ Không</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**P6**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Performance</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`lighthouse_audit.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">❌ Không (cần URL)</td></tr></tbody></table>

</div>> **Logic dừng sớm:** Nếu P0 (Security) hoặc P1 (Lint) thất bại, toàn bộ checklist dừng ngay và báo lỗi. Bạn phải sửa các vấn đề Critical trước khi các bước tiếp theo có ý nghĩa.

### Ví dụ kết quả

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--1" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="43" data-line-number="43" data-line-start="43"><div class="line-content">  
</div></div></div></div></div></div>```html
============================================================
🚀 ANTIGRAVITY KIT - MASTER CHECKLIST
============================================================
Project: /path/to/my-project


============================================================
📋 CORE CHECKS
============================================================


🔄 Running: Security Scan
✅ Security Scan: PASSED


🔄 Running: Lint Check
✅ Lint Check: PASSED


🔄 Running: Schema Validation
⏭️ Schema Validation: Script not found, skipping


🔄 Running: Test Runner
✅ Test Runner: PASSED


🔄 Running: UX Audit
✅ UX Audit: PASSED


🔄 Running: SEO Check
⚠️ SEO Check: FAILED
Error: Missing meta description on 3 pages


============================================================
📊 CHECKLIST SUMMARY
============================================================
Total Checks: 6
✅ Passed: 4
❌ Failed: 1
⏭️ Skipped: 1


❌ SEO Check
✅ Security Scan
✅ Lint Check
✅ Test Runner
✅ UX Audit


1 check(s) FAILED - Please fix before proceeding
```

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--2" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="43" data-line-number="43" data-line-start="43"><div class="line-content">  
</div></div></div></div></div></div>---

## 3. `verify_all.py` — Kiểm tra toàn diện trước production

### Cú pháp

```bash
bash


# Cần cung cấp URL của server đang chạy
python .agent/scripts/verify_all.py . --url http://localhost:3000
```

### Kiểm tra thêm so với `checklist.py`

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-ki%E1%BB%83m-tra-th%C3%AAm-c%C3%B4ng-c"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Kiểm tra thêm</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Công cụ</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Mục đích</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Lighthouse Audit**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`lighthouse_audit.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Score Core Web Vitals (LCP, CLS, INP)</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Playwright E2E**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`playwright_runner.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm thử end-to-end trên trình duyệt thật</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Bundle Analysis**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`bundle_analyzer.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Phân tích kích thước bundle JS/CSS</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Mobile Audit**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`mobile_audit.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra responsive + touch targets</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**i18n Check**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">(nếu có)</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Kiểm tra hardcoded strings</td></tr></tbody></table>

</div>### Yêu cầu trước khi chạy `verify_all.py`

- ✅ Server phải đang chạy (chạy `/preview start` trước).
- ✅ Playwright phải được cài: `npx playwright install`.
- ✅ Chromium hoặc Chrome phải có sẵn trên máy.

---

## 4. Khi nào dùng script nào?

```html
Đang phát triển hàng ngày:
→ python .agent/scripts/checklist.py .
→ Nhanh, dừng sớm khi có lỗi critical


Trước khi tạo Pull Request:
→ python .agent/scripts/checklist.py .
→ Đảm bảo không có Security/Lint issues


Trước khi merge vào main:
→ python .agent/scripts/checklist.py . --url http://localhost:3000
→ Bao gồm cả performance check


Trước khi release lên production:
→ python .agent/scripts/verify_all.py . --url http://localhost:3000
→ Kiểm tra toàn diện kể cả E2E và Lighthouse
```

---

## 5. Tích hợp vào CI/CD

### GitHub Actions

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--6" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="29" data-line-number="29" data-line-start="29"><div class="line-content"></div></div></div></div></div></div>```html
yaml


name: Quality Check
on: [push, pull_request]


jobs:
quality:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3


- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '20'


- name: Setup Python
uses: actions/setup-python@v4
with:
python-version: '3.11'


- name: Install dependencies
run: npm ci


- name: Run Antigravity Checklist
run: python .agent/scripts/checklist.py .


# Deploy chỉ chạy khi checklist pass
- name: Deploy
if: success() && github.ref == 'refs/heads/main'
run: npm run deploy
```

---

## 6. Chạy script con riêng lẻ

Ngoài 2 master scripts, bạn cũng có thể chạy từng script con riêng lẻ khi cần:

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--8" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="11" data-line-number="11" data-line-start="11"><div class="line-content"></div></div></div></div></div></div>```html
bash


# Chỉ quét bảo mật
python .agent/skills/vulnerability-scanner/scripts/security_scan.py .


# Chỉ kiểm tra UX
python .agent/skills/frontend-design/scripts/ux_audit.py .


# Chỉ chạy Lighthouse
python .agent/skills/performance-profiling/scripts/lighthouse_audit.py . http://localhost:3000


# Chỉ kiểm tra SEO
python .agent/skills/seo-fundamentals/scripts/seo_checker.py .
```

---

## 7. Kích hoạt từ lệnh chat

Bạn không cần nhớ đường dẫn script. Chỉ cần nói với AI:

```html
"final checks" → AI chạy checklist.py tự động
"son kontrolleri yap" → (Tiếng Thổ) Cũng kích hoạt checklist
"chạy tất cả test" → AI chạy checklist.py
"kiểm tra trước khi deploy" → AI chạy verify_all.py (với URL)

AI được cấu hình để nhận diện các từ khóa này và tự động chạy đúng script cho bạn.
```

---

## 8. Bảng tổng hợp toàn bộ 12 Scripts

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-script-skill-khi-n%C3%A0o"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Script</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Skill</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Khi nào dùng</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`security_scan.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">vulnerability-scanner</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Mỗi lần deploy</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`dependency_analyzer.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">vulnerability-scanner</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Hàng tuần / Mỗi lần deploy</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`lint_runner.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">lint-and-validate</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Mỗi lần thay đổi code</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`test_runner.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">testing-patterns</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Sau khi thay đổi logic</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`schema_validator.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">database-design</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Sau khi thay đổi DB schema</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`ux_audit.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">frontend-design</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Sau khi thay đổi UI</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`accessibility_checker.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">frontend-design</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Sau khi thay đổi UI</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`seo_checker.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">seo-fundamentals</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Sau khi thay đổi trang</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`bundle_analyzer.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">performance-profiling</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Trước khi deploy</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`mobile_audit.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">mobile-design</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Sau khi thay đổi mobile UI</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`lighthouse_audit.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">performance-profiling</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Trước khi deploy</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`playwright_runner.py`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">webapp-testing</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Trước khi deploy</td></tr></tbody></table>

</div>> **Ghi nhớ:** `checklist.py` và `verify_all.py` điều phối tất cả các scripts trên theo đúng thứ tự ưu tiên. Trong hầu hết các trường hợp, bạn chỉ cần gọi 2 master scripts và không cần chạy từng cái riêng lẻ.

# Phụ lục: Ví dụ xây dựng AI Skill cho WSO2 MI

# Toàn bộ quy trinh và cấu trúc để tạo bộ skill mới

## 1. Mục đích

Phần này minh họa cách xây dựng một **AI Skill chuyên biệt** để hỗ trợ phát triển và vận hành hệ thống **WSO2 Micro Integrator (WSO2 MI)**.

Skill này đóng vai trò như một **kho tri thức (Knowledge Base)** giúp AI Agent có thể:

- Hướng dẫn viết **Synapse XML**
- Áp dụng **best practices** khi xây dựng integration
- Phát hiện **anti-patterns**
- Hỗ trợ xử lý lỗi trong WSO2 MI

Toàn bộ tri thức được tổ chức trong thư mục:

```bash
.agent/skills/wso2-mi/
```

---

# 2. Cấu trúc Skill

Thư mục `wso2-mi` được tổ chức theo từng chủ đề của WSO2 MI.

```html
.agent/
├── skills/
│ └── wso2-mi/
│ ├── SKILL.md
│ ├── mediators.md
│ ├── sequences.md
│ ├── apis.md
│ ├── endpoints.md
│ ├── error-handling.md
│ ├── connectors.md
│ ├── data-services.md
│ └── references/
```

Ý nghĩa các file:

<div class="TyagGW_tableContainer" id="bkmrk-file-m%C3%B4-t%E1%BA%A3-skill.md-"><div class="group TyagGW_tableWrapper flex flex-col-reverse w-fit" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)" data-end="1687" data-start="1249"><thead data-end="1265" data-start="1249"><tr data-end="1265" data-start="1249"><th class="" data-col-size="sm" data-end="1256" data-start="1249">File</th><th class="" data-col-size="sm" data-end="1265" data-start="1256">Mô tả</th></tr></thead><tbody data-end="1687" data-start="1280"><tr data-end="1326" data-start="1280"><td data-col-size="sm" data-end="1291" data-start="1280">SKILL.md</td><td data-col-size="sm" data-end="1326" data-start="1291">File điều hướng tri thức cho AI</td></tr><tr data-end="1376" data-start="1327"><td data-col-size="sm" data-end="1342" data-start="1327">mediators.md</td><td data-col-size="sm" data-end="1376" data-start="1342">Hướng dẫn sử dụng các mediator</td></tr><tr data-end="1424" data-start="1377"><td data-col-size="sm" data-end="1392" data-start="1377">sequences.md</td><td data-col-size="sm" data-end="1424" data-start="1392">Thiết kế và sử dụng sequence</td></tr><tr data-end="1461" data-start="1425"><td data-col-size="sm" data-end="1435" data-start="1425">apis.md</td><td data-col-size="sm" data-end="1461" data-start="1435">Cách xây dựng REST API</td></tr><tr data-end="1498" data-start="1462"><td data-col-size="sm" data-end="1477" data-start="1462">endpoints.md</td><td data-col-size="sm" data-end="1498" data-start="1477">Cấu hình endpoint</td></tr><tr data-end="1539" data-start="1499"><td data-col-size="sm" data-end="1519" data-start="1499">error-handling.md</td><td data-col-size="sm" data-end="1539" data-start="1519">Cơ chế xử lý lỗi</td></tr><tr data-end="1587" data-start="1540"><td data-col-size="sm" data-end="1556" data-start="1540">connectors.md</td><td data-col-size="sm" data-end="1587" data-start="1556">Hướng dẫn sử dụng connector</td></tr><tr data-end="1640" data-start="1588"><td data-col-size="sm" data-end="1607" data-start="1588">data-services.md</td><td data-col-size="sm" data-end="1640" data-start="1607">Hướng dẫn Data Service (.dbs)</td></tr><tr data-end="1687" data-start="1641"><td data-col-size="sm" data-end="1654" data-start="1641">references</td><td data-col-size="sm" data-end="1687" data-start="1654">Chứa tài liệu nghiệp vụ riêng</td></tr></tbody></table>

</div></div>---

# 3. Agent chuyên biệt cho WSO2 MI

Một AI Agent chuyên biệt được tạo để xử lý các câu hỏi liên quan đến WSO2 MI.

Vị trí file:

```markdown
.agent/agents/wso2-mi-specialist.md
```

<div class="relative w-full my-4" id="bkmrk--2"><div class=""><div class="relative"><div class="h-full min-h-0 min-w-0"><div class="h-full min-h-0 min-w-0"><div class="border border-token-border-light border-radius-3xl corner-superellipse/1.1 rounded-3xl"><div class="h-full w-full border-radius-3xl bg-token-bg-elevated-secondary corner-superellipse/1.1 overflow-clip rounded-3xl lxnfua_clipPathFallback"><div class="pt-3"><div class="relative z-0 flex max-w-full"><div class="q9tKkq_viewer cm-editor z-10 light:cm-light dark:cm-light flex h-full w-full flex-col items-stretch ͼk ͼy" dir="ltr" id="bkmrk--3"><div class="cm-scroller"></div></div></div></div></div></div></div></div><div class=""><div class=""></div></div></div></div></div>Agent này có các đặc điểm:

- Ưu tiên sử dụng **skill `wso2-mi`**
- Tập trung hỗ trợ **WSO2 Micro Integrator**
- Áp dụng các quy tắc thiết kế integration

Ví dụ quy tắc của agent:

- Ưu tiên sử dụng **XML mediator chuẩn**
- Hạn chế viết **Script hoặc Java custom**
- Thiết kế integration theo hướng **dễ bảo trì và dễ mở rộng**

---

# 4. Tích hợp vào kiến trúc hệ thống AI

Để các Agent khác trong hệ thống có thể sử dụng skill này, cần đăng ký skill trong file kiến trúc chung:

```markdown
.agent/ARCHITECTURE.md
```

Skill `wso2-mi` được thêm vào phần:

```html
Backend & API
```

Việc này cho phép:

- Các agent khác nhận biết hệ thống đã có **chuyên gia WSO2**
- **Orchestrator Agent** có thể tự động gọi agent này khi cần hỗ trợ integration.

---

# 5. Cách sử dụng Agent

Trong quá trình làm việc, khi cần hỗ trợ về WSO2 MI, có thể gọi agent chuyên biệt:

```html
@wso2-mi-specialist
```

Khi được gọi, Agent sẽ:

1. Tự động truy cập thư mục:

```html
.agent/skills/wso2-mi/
```

<div class="relative w-full my-4" id="bkmrk--6"><div class=""><div class="relative"><div class="h-full min-h-0 min-w-0"><div class="h-full min-h-0 min-w-0"><div class="border border-token-border-light border-radius-3xl corner-superellipse/1.1 rounded-3xl"><div class="h-full w-full border-radius-3xl bg-token-bg-elevated-secondary corner-superellipse/1.1 overflow-clip rounded-3xl lxnfua_clipPathFallback"><div class="pt-3"><div class="relative z-0 flex max-w-full"><div class="q9tKkq_viewer cm-editor z-10 light:cm-light dark:cm-light flex h-full w-full flex-col items-stretch ͼk ͼy" dir="ltr" id="bkmrk--7"></div></div></div></div></div></div></div><div class=""><div class="">  
</div></div></div></div></div>2. Tìm kiếm thông tin trong các tài liệu liên quan
3. Trả lời và hướng dẫn viết **Synapse XML chuẩn** cho hệ thống.

Agent này được thiết kế để hỗ trợ phát triển các integration trong dự án **TTHC\_service**.

# Mẫu promt sử dụng skill mới của nền tảng wso2 mi

### 1. Cách Prompt đơn giản nhất (Chỉ định file UC)

Bạn gọi Agent chuyên gia và chỉ định file UC cụ thể trong thư mục `references`:

> **Prompt:** `@wso2-mi-specialist Hãy đọc file references/UC-83.md và triển khai API resources tương ứng trong WSO2 MI cho tôi.`

### 2. Prompt yêu cầu triển khai chi tiết

Nếu bạn muốn nó tạo cả logic xử lý lỗi và log theo chuẩn của dự án:

> **Prompt:** `@wso2-mi-specialist Dựa trên tài liệu nghiệp vụ nghiệp vụ tại references/UC-83.md, hãy:
> 
> 1. Tạo API mới với các resource đã định nghĩa.
> 2. Sử dụng PayloadFactory để transform request theo UC.
> 3. Cấu hình Fault Sequence để bắt các lỗi kết nối từ backend theo hướng dẫn trong skill wso2-mi.`

### 3. Prompt để cập nhật code hiện có

Nếu bạn đã có file XML và muốn sửa nó theo UC mới:

> **Prompt:** `@wso2-mi-specialist Hãy cập nhật file src/main/wso2mi/artifacts/apis/MessageAPI.xml của tôi để đáp ứng đúng luồng xử lý được mô tả trong file references/UC-85.md.`

---

### AI sẽ làm gì khi nhận được các Prompt này?

Khi bạn gọi `@wso2-mi-specialist`:

1. **Đọc Skill:** Nó sẽ tự động đọc các file trong `.agent/skills/wso2-mi/` để biết cách viết XML mediator (Property, Log, Call...) đúng chuẩn 2025.
2. **Đọc Reference:** Nó sẽ tìm đến thư mục `references/` để đọc file `.md` UC của bạn để hiểu logic nghiệp vụ (Ví dụ: bước nào cần ký số, bước nào cần gọi API Hải quan).
3. **Thực thi:** Nó sẽ đề xuất Code XML hoàn chỉnh hoặc trực tiếp tạo/sửa file trong thư mục `src/main/wso2mi/` của bạn.

**Mẹo:** Nếu bạn có nhiều file UC, hãy thử bắt đầu với một file nhỏ nhất (ví dụ: `UC-SignatureVerify.md`) để kiểm tra xem Agent có hiểu đúng ý bạn không nhé!

# Xử lý debugger khi agent ra bug

### 1. Sử dụng lệnh `/orchestrate` (Khuyến nghị cho lỗi phức tạp)

Lệnh này sẽ kích hoạt chế độ điều phối, giúp hai Agent thảo luận và bổ trợ cho nhau.

> **Prompt:** `/orchestrate @wso2-mi-specialist @debugger "API SyncUC83API.xml đang trả về lỗi 500 khi gọi backend. Hãy phân tra log MI, đối chiếu với references/UC-83.md để tìm nguyên nhân và sửa code."`

### 2. Prompt trực tiếp gọi cả hai Agent

Cách này nhanh gọn khi bạn đã biết lỗi nằm ở đâu.

> **Prompt:** `@wso2-mi-specialist @debugger Trong file SyncUC83API.xml, tôi thấy PayloadFactory đang map sai giá trị requestId từ request. Hãy kiểm tra lại logic và sửa dựa trên UC-83.md."`

### 3. Prompt khi lỗi không rõ ràng (Troubleshooting)

Khi bạn chỉ thấy lỗi mà không biết tại sao.

> **Prompt:** `@debugger @wso2-mi-specialist Tôi gửi request POST lên /api/v1/sync/uc-83 nhưng bị treo timeout. Hãy kiểm tra cấu hình Endpoint trong file XML và hướng dẫn tôi cách debug luồng này trong Micro Integrator."`

---

### Tại sao sự kết hợp này lại hiệu quả?

- **`@debugger`**: Sẽ sử dụng kỹ năng `systematic-debugging` để đi qua 4 bước: (1) Thu thập bằng chứng, (2) Đưa ra giả thuyết, (3) Thử nghiệm, (4) Xác minh. Nó sẽ yêu cầu xem log MI (`carbon.log`) hoặc chạy các lệnh kiểm tra kết nối.
- **`@wso2-mi-specialist`**: Sẽ đảm bảo các giải pháp sửa lỗi mà `@debugger` đưa ra là đúng cú pháp XML của WSO2, sử dụng đúng Mediator và Scope (default, transport, axis2...).

**Mẹo nhỏ:** Để việc debug hiệu quả nhất, bạn hãy copy một đoạn log lỗi từ MI vào chat cùng với Prompt.

---

NOTE

Tôi vẫn đang chờ bạn xác nhận **<span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><svg aria-hidden="true" class="lucide lucide-file-text h-3.5 w-3.5 stroke-1" fill="none" height="24" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" viewbox="0 0 24 24" width="24" xmlns="http://www.w3.org/2000/svg"><path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"></path><path d="M14 2v4a2 2 0 0 0 2 2h4"></path><path d="M10 9H8"></path><path d="M16 13H8"></path><path d="M16 17H8"></path></svg><span class="inline-flex break-all leading-tight">implementation\_plan.md</span></span></span>** cho `UC-83`. Nếu bạn thấy kế hoạch đã ổn, hãy phản hồi "Proceed" hoặc "Xác nhận" để tôi bắt đầu tạo code XML đầu tiên cho bạn nhé!

# Source và tài liệu liên quan

# Cách dùng skill spring-boot-api-flow và genarate code trong dự án spring boot

**<span style="font-size: 16.0pt; line-height: 107%; color: #1f3864;">1.<span style="mso-spacerun: yes;"> </span>Cài đặt ban đầu </span>**

Trước khi sử dụng skill, bạn cần clone repository cấu hình về thư mục gốc của project bằng lệnh sau:

<span style="font-size: 9.0pt; line-height: 107%; font-family: 'Courier New'; mso-bidi-font-family: 'Times New Roman'; color: #c0392b;">git clone -b be\_base http://192.168.0.95/minhnd/backend\_base\_angular</span>

Lệnh trên sẽ tải branch be\_base và đặt toàn bộ src spring boot.

<span style="font-size: 9.0pt; line-height: 107%; font-family: 'Courier New'; mso-bidi-font-family: 'Times New Roman'; color: #c0392b;">git clone -b master [http://192.168.0.95/minhnd/chat-gpt-agent.git](http://192.168.0.95/minhnd/chat-gpt-agent.git) .agent</span>

Lệnh trên sẽ tải thư mục .agent về.

**Lưu ý:<span style="mso-spacerun: yes;"> </span>**Chạy lệnh này tại thư mục gốc (root) của project, không phải bên trong thư mục con nào khác.

**<span style="font-size: 16.0pt; line-height: 107%; color: #1f3864;">2.<span style="mso-spacerun: yes;"> </span>Hướng dẫn cài đặt Google Antigravity</span>**

Truy cập link sau [https://antigravity.google](https://antigravity.google)<span style="color: #4472c4; mso-themecolor: accent1;">/download</span>

[![image.png](https://docs.lifetex.vn/uploads/images/gallery/2026-03/scaled-1680-/YBkimage.png)](https://docs.lifetex.vn/uploads/images/gallery/2026-03/YBkimage.png)

<span style="mso-no-proof: yes;">  
</span>

Sau đó cài đặt như bình thường.

**<span style="font-size: 16.0pt; line-height: 107%; color: #1f3864;">3.<span style="mso-spacerun: yes;"> Chuẩn bị file SRS, CSDL cho agent</span></span>**

Để AI Skill hiểu và sinh code chính xác, bắt buộc phải cung cấp **2 file đầu vào (Context)**:

**<span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">csdl.txt</span></span></span> (Database Schema):** Cung cấp cấu trúc bảng, kiểu dữ liệu và các mối quan hệ (Khóa chính/Khóa ngoại). 👉 *Giúp AI định nghĩa chính xác các Entity, cấu trúc Database.*

**<span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">srs.txt</span></span></span> (Đặc tả nghiệp vụ):** Chứa thông tin về các Endpoint API (Mã Use Case, Method, Payload Request/Response) và các quy tắc logic (Business rules, Validation). 👉 *Giúp AI hiểu "linh hồn" của chức năng để viết Controller và tầng Service chính xác.*

**Cách AI xử lý:** AI sẽ tham chiếu chéo (Cross-reference) cấu trúc dữ liệu từ c<span class="inline-flex break-all leading-tight">sdl.txt</span> sang các logic nghiệp vụ trong <span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">srs.txt</span></span></span> để tạo ra bộ mã nguồn hoàn chỉnh (từ DB lên API).

[![image.png](https://docs.lifetex.vn/uploads/images/gallery/2026-03/scaled-1680-/iEkimage.png)](https://docs.lifetex.vn/uploads/images/gallery/2026-03/iEkimage.png)

**<span style="font-size: 16.0pt; line-height: 107%; color: #1f3864;">4.<span style="mso-spacerun: yes;"> </span>Hướng dẫn promt cho AI để kích hoạt skill </span>**

Để kích hoạt skill *`spring-boot-api-flow`*, bạn có thể dùng một trong **3 cách** sau. Về cơ bản, AI được cấu hình hệ thống tự động nhận diện (Intelligent Routing), nhưng bạn vẫn có thể gọi thẳng nếu muốn chắc chắn.

**1. Kích hoạt tự động (Cách tự nhiên nhất)**

Bạn chỉ cần đưa ra một yêu cầu liên quan đến việc tạo hoặc xử lý Backend Java/Spring Boot. AI (agent `backend-specialist`) sẽ tự động phân tích ngữ cảnh và áp dụng skill này.

- **Ví dụ:** *"Căn cứ vào `srs.txt` và `csdl.txt`, hãy tạo các API Spring Boot CRUD."*

*\*hoặ*

**2. Kích hoạt tường minh (Nhắc tên)**

Nếu bạn muốn ép buộc 100% AI phải nhìn vào bộ luật đó để tránh sai sót, hãy nhắc trực tiếp tên skill trong câu lệnh của bạn.

- **Ví dụ:** *"`srs.txt` và `csdl.txt` Áp dụng chuẩn của skill `spring-boot-api-flow` để viết REST API."*
- **Ví dụ:** *"Hãy dùng `spring-boot-api-flow` refactor lại file `OrderService.java` này cho tôi, nhớ áp dụng luật chia nhỏ Rule 20 dòng."*

[![image.png](https://docs.lifetex.vn/uploads/images/gallery/2026-03/scaled-1680-/4jSimage.png)](https://docs.lifetex.vn/uploads/images/gallery/2026-03/4jSimage.png)

Skill sẽ tự động đọc *`srs.txt` và `csdl.txt`* để genarate code theo chuẩn cấu trúc *`spring-boot-api-flow`*