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).
• Trang 1.2: Lộ trình phát triển và các thành phần chính (Agents, Skills, Workflows).
• 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).
• Trang 2.2: Hướng dẫn cài đặt nhanh (Sử dụng lệnh npx).
• Trang 2.3: Cài đặt toàn cục (Global Install) và cấu hình biến môi trường PATH.
• Trang 2.4: Giải thích cấu trúc thư mục .agent/ (Agents, Skills, Workflows, Rules, Scripts).
• 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).
• Trang 3.2: Skills - Hệ thống kỹ năng và kiến thức chuyên sâu cho AI.
• Trang 3.3: Workflows - Quy trình làm việc tự động thông qua các lệnh gạch chéo (/).
• 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).
• Trang 4.2: Cập nhật phiên bản và quản lý dữ liệu (ag-kit update).
• Trang 4.3: Các tham số nâng cao (Sử dụng --force, --path, --quiet).
• 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.
• Trang 5.2: Lập kế hoạch dự án chi tiết (Blueprint) với /plan.
• Trang 5.3: Xây dựng ứng dụng/tính năng mới từ đầu với /create.
• Trang 5.4: Nâng cấp và cải tiến mã nguồn hiện có với /enhance.
• Trang 5.5: Thiết kế giao diện Premium chuẩn UI-UX với /ui-ux-pro-max.
• Trang 5.6: Protocol 4 bước sửa lỗi có hệ thống với /debug.
• Trang 5.7: Tự động hóa kiểm thử mã nguồn với /test.
• Trang 5.8: Quản lý môi trường xem trước và theo dõi tiến độ (/preview & /status).
• 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.
• Trang 6.2: Sử dụng các script kiểm tra tổng thể ( checklist.py & verify_all.py ).
• 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
• Mẫu promt sử dụng skill mới của nền tảng wso2 mi
• Xử lý debugger khi agent ra bug
• 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

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:

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 & 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ự.

---

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 

ARCHITECTURE.md.

 

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.

 

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

 

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 
  
  
  AGENT_FLOW.md — 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):

[ 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 (.md) đượ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:

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

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

.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 & UI (5 Skills)

• react-best-practices — Tối ưu React & 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 & 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 & 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 & 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 & 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.

/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:

---
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/:

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.

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:

---

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:

bash
node --version

Kết quả hợp lệ phải hiển thị phiên bản >= 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 — 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 (checklist.py, verify_all.py) 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

python --version

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

Cài đặt Python (Windows)

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 đó.

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

# 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
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.
• 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:

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:

---

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 >= 16.0
• ✅ Python >= 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:

bash
cd đường/dẫn/đến/dự-án-của-bạn

Ví dụ:

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

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

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

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:

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:

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 .gitignore

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 

.gitignore 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 

.gitignore 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):

 

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 
  
  
  .gitignore 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
ag-kit update

⚠️ 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

---

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.

---

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

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

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:

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):

powershell
$env:PATH -split ";"

macOS / Linux:

bash
echo $PATH

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

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

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:

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:

powershell
ag-kit --version

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

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:

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:

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:

.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 ARCHITECTURE.md

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

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 AGENT_FLOW.md

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

---

4. File mcp_config.json

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).

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

.agent/agents/
├── orchestrator.md
├── frontend-specialist.md
├── backend-specialist.md
├── security-auditor.md
├── debugger.md
└── ... (16 file khác)

Vai trò

Mỗi file .md 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

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

.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 
  
  
  SKILL.md 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:

---

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

Cấu trúc

.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 .md 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:

.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

.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:

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

.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

Cách chạy thủ công

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

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.

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ế

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:

---

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:

---

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

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

Nhóm Phát triển

Nhóm Chất lượng & Bảo mật

Nhóm Chuyên biệt

---

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

---

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

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?

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.

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ế:

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

3. Cấu trúc một Skill

.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 

yaml
---
name: react-best-practices
description: React & Next.js performance optimization from Vercel Engineering.
allowed-tools: Read, Write, Edit, Bash
---

4. Danh sách đầy đủ 36 Skills theo nhóm

🎨 Frontend & UI (5 Skills)

⚙️ Backend & API (4 Skills)

🗄️ Database (2 Skills)

📝 TypeScript / JavaScript (1 Skill)

☁️ Cloud & Infrastructure (3 Skills)

🧪 Testing & Quality (5 Skills)

🔒 Security (2 Skills)

🏗️ Architecture & Planning (4 Skills)

📱 Mobile (1 Skill)

🎮 Game Development (1 Skill)

🔍 SEO & Growth (2 Skills)

💻 Shell / CLI (2 Skills)

🔧 Other (6 Skills)

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:

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

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

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

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

Ví dụ thực tế

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ụ:

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ụ:

/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ụ:

/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ụ:

/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ụ:

/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
/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 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ụ:

/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ụ:

/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ộ.

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.

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ụ:

/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/:

.agent/workflows/code-review.md

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

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:

/code-review

---

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

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:

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
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 main.
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
# 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
# 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
# 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
ag-kit init --path ./packages/my-app

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
# Ghi đè lên .agent/ cũ
ag-kit init --force

---

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

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
ag-kit status

Thông tin hiển thị

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

Ví dụ kết quả

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
ls .agent/ # macOS / Linux
dir .agent\ # Windows

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

bash
ag-kit status

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

/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

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
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ự:

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

⚠️ 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.

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)

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

---

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

Trước khi chạy lệnh update, hãy đọc file CHANGELOG.md để biết những thay đổi trong phiên bản mới:

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

---

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

bash
ag-kit init --force

Khi nào dùng

Ví dụ

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!

⚠️ 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.

---

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

bash
ag-kit init --path <đường-dẫn-đến-thư-mục>

Khi nào dùng

Ví dụ thực tế

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 main (phiên bản ổn định nhất).

Cú pháp

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

Các nhánh phổ biến

Ví dụ

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

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.

---

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

bash
ag-kit init --dry-run

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

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
/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:

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

👤 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

👤 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 đủ

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

# 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

"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

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

bash
/plan [mô tả ngắn gọn về dự án hoặc tính năng]

Ví dụ:

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 đủ:

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ế

👤 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

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

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
/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:

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)

👤 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)

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 đủ

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

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:

"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

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.

/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ẻ.

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

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:

• 
  
  package.json để 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

📋 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

👤 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

👤 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:

---

7. Mẹo để /enhance hoạt động hiệu quả

Kiểm tra dependencies trước

"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ể

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

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, 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
/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

👤 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

👤 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ố

/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:

/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

---

6. Kết quả bàn giao

Sau khi /ui-ux-pro-max hoàn thành, bạn nhận được:

---

7. Bước tiếp theo sau khi tạo giao diện

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ụ:

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

👤 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

👤 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

/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

"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

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

---

3. Cách /test phân tích và tạo test

Khi nhận lệnh /test [file], AI sẽ:

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

👤 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

👤 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

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

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ử

       /\
      /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:

"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

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

"/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ợ

AI tự phát hiện framework đang dùng từ package.json 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:

---

Phần A: /preview — Quản lý server phát triển

A.1. Các lệnh /preview

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:

A.3. Xử lý xung đột Port

Nếu port mặc định (3000) đã bị chiếm bởi ứng dụng khác:

🤖 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

👤 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

---

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
/status

B.3. Thông tin được hiển thị

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

👤 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

---

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:

🌅 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:

.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

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:

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ì:

Intelligent Routing Checklist

Checklist bắt buộc AI phải hoàn thành trước khi viết code:

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:

---

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ữ:

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

👤 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.

---

2. checklist.py — Kiểm tra hàng ngày

Cú pháp

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)

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ả

============================================================
🚀 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

---

3. verify_all.py — Kiểm tra toàn diện trước production

Cú pháp

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

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?

Đ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

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:

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:

"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

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:

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

.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:

---

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:

.agent/agents/wso2-mi-specialist.md

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:

.agent/ARCHITECTURE.md

Skill wso2-mi được thêm vào phần:

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:

@wso2-mi-specialist

Khi được gọi, Agent sẽ:

1. Tự động truy cập thư mục:

.agent/skills/wso2-mi/

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 implementation_plan.md 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

1.  Cài đặt ban đầu 

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:

git clone -b be_base http://192.168.0.95/minhnd/backend_base_angular

Lệnh trên sẽ tải branch be_base  và đặt toàn bộ src spring boot.

git clone -b master http://192.168.0.95/minhnd/chat-gpt-agent.git .agent

Lệnh trên sẽ tải thư mục .agent về.

Lưu ý:  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.

2.  Hướng dẫn cài đặt Google Antigravity

Truy cập link sau https://antigravity.google/download

Sau đó cài đặt như bình thường.

3.  Chuẩn bị file SRS, CSDL cho agent

Để 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):

csdl.txt (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.

srs.txt (Đặ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ừ csdl.txt sang các logic nghiệp vụ trong srs.txt để tạo ra bộ mã nguồn hoàn chỉnh (từ DB lên API).

4.  Hướng dẫn promt cho AI để kích hoạt skill 

Để 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."

Skill sẽ tự động đọc srs.txt và csdl.txt để genarate code theo chuẩn cấu trúc spring-boot-api-flow