# 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>