# 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:
Thành phầnPhiên bản tối thiểuMục đích sử dụng
**Node.js**16.0 hoặc mới hơnChạy công cụ CLI `ag-kit` và ứng dụng web
**npm** hoặc **yarn**Đi kèm với Node.jsQuản lý gói phụ thuộc
**Python**3.10 hoặc mới hơnChạy các script kiểm tra tự động của Kit
**Git**Bất kỳ phiên bản nàoCập nhật Kit và quản lý phiên bản
--- ## 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 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](https://nodejs.org/) — Chọn phiên bản **LTS (Long Term Support)** để đảm bảo ổn định. > **Mẹo:** Nên cài đặt phiên bản Node.js LTS mới nhất (hiện tại là **Node.js 20.x LTS**) để có sự tương thích tốt nhất với tất cả các gói npm hiện đại. --- ## 3. Python ### Tại sao cần Python? Các script kiểm tra chất lượng tự động của Antigravity Kit (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 ```bash 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)
1. Tải từ [python.org](https://www.python.org/downloads/). 2. Trong quá trình cài đặt, **bắt buộc phải tích chọn** vào ô **"Add Python to PATH"** ở màn hình đầu tiên của trình cài đặt. 3. Sau khi cài xong, mở lại Terminal mới và chạy `python --version` để xác nhận.
>
**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) ```bash # macOS (dùng Homebrew) brew install python3 # Ubuntu / Debian sudo apt update && sudo apt install python3 python3-pip ``` ## 4. Git ### Tại sao cần Git? - Lệnh `ag-kit update` dùng Git để tải phiên bản mới nhất của bộ kit từ GitHub. - Cho phép bạn commit thư mục `.agent/` vào repository của dự án để chia sẻ cấu hình với cả đội. ### Kiểm tra phiên bản Git ```bash bash git --version ``` Kết quả hợp lệ ví dụ: `git version 2.43.0`. ### Cài đặt Git - **Windows:** Tải từ [git-scm.com](https://git-scm.com/). - **macOS:** Chạy `brew install git` hoặc cài Xcode Command Line Tools. - **Linux:** `sudo apt install git` (Ubuntu/Debian) hoặc `sudo dnf install git` (Fedora). --- ## 5. Kiểm tra nhanh toàn bộ hệ thống Chạy các lệnh sau để kiểm tra tất cả thành phần cùng lúc: ```bash node --version # Kiểm tra Node.js npm --version # Kiểm tra npm python --version # Kiểm tra Python git --version # Kiểm tra Git ``` Nếu tất cả đều trả về số phiên bản hợp lệ, hệ thống của bạn đã sẵn sàng để cài đặt Antigravity Kit. --- ## 6. Hệ điều hành được hỗ trợ Antigravity Kit tương thích với tất cả các hệ điều hành phổ biến:
Hệ điều hànhTrạng tháiGhi chú
**Windows 10/11**✅ Được hỗ trợ đầy đủCó thể dùng Command Prompt, PowerShell hoặc Windows Terminal
**macOS**✅ Được hỗ trợ đầy đủKhuyến nghị dùng iTerm2 hoặc Terminal tích hợp sẵn
**Linux (Ubuntu, Debian, Fedora...)**✅ Được hỗ trợ đầy đủDùng bất kỳ terminal chuẩn nào
--- > **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 bash cd đường/dẫn/đến/dự-án-của-bạn ``` **Ví dụ:**
```bash bash # Windows cd C:\Users\ten-ban\Projects\my-awesome-project # macOS / Linux cd ~/Projects/my-awesome-project ``` ### Bước 2: Chạy lệnh cài đặt
```bash bash npx @vudovn/ag-kit init ``` `npx` sẽ tự động tải công cụ `ag-kit` về (tạm thời) và chạy lệnh khởi tạo. Bạn **không cần** cài đặt gì trước đó. ### Bước 3: Chờ quá trình hoàn tất Quá trình cài đặt sẽ tự động: 1. Kết nối với GitHub để tải phiên bản mới nhất. 2. Tạo thư mục `.agent/` trong dự án của bạn. 3. Bơm toàn bộ 20 Agents, 36 Skills và 11 Workflows vào đó. Khi hiển thị thông báo thành công, quá trình cài đặt đã hoàn tất. --- ## 3. Phương pháp 2: Cài đặt toàn cục (`Global Install`) Phương pháp này phù hợp nếu bạn làm việc với **nhiều dự án khác nhau** và muốn dùng lệnh `ag-kit` từ bất kỳ đâu. ### Bước 1: Cài đặt `ag-kit` lên toàn bộ máy
```bash bash npm install -g @vudovn/ag-kit ``` Lệnh này chỉ cần chạy **một lần duy nhất** trên máy tính của bạn. ### Bước 2: Xác nhận cài đặt thành công
```bash bash ag-kit --version ``` Nếu hiển thị số phiên bản, cài đặt toàn cục đã thành công. ### Bước 3: Khởi tạo vào từng dự án Mỗi khi muốn tích hợp vào một dự án mới, di chuyển vào thư mục dự án đó và chạy:
```bash bash cd đường/dẫn/đến/dự-án ag-kit init ``` --- ## 4. Điều gì xảy ra sau khi cài đặt? Sau khi cài đặt thành công, một thư mục `.agent/` sẽ xuất hiện trong dự án của bạn với cấu trúc như sau:
```html your-project/ ├── src/ ├── package.json ├── ... └── .agent/ ← Thư mục mới được tạo ra ├── ARCHITECTURE.md # Tài liệu kiến trúc tổng thể của Kit ├── AGENT_FLOW.md # Sơ đồ luồng hoạt động của các Agent ├── agents/ # 20 file cấu hình Specialist Agent ├── skills/ # 36 thư mục Knowledge Module (Skills) ├── workflows/ # 11 file quy trình làm việc (Workflows) ├── rules/ # Quy tắc hành vi toàn cục (GEMINI.md) └── scripts/ # Script kiểm tra Python tổng thể ``` Từ thời điểm này, khi bạn mở dự án và bắt đầu trò chuyện với AI, nó sẽ tự động đọc các cấu hình trong thư mục `.agent/` và hoạt động như một đội chuyên gia. --- ## 5. Quan trọng: Cấu hình .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 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 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
Vấn đềNguyên nhânGiải pháp
`npx: command not found`Node.js chưa được cài đặtCài đặt Node.js từ nodejs.org
`ag-kit: command not found`Cài đặt toàn cục chưa thành côngChạy lại `npm install -g @vudovn/ag-kit`
Thư mục `.agent/` đã tồn tạiĐã cài đặt trước đóThêm tham số `--force`: `ag-kit init --force`
Script Python không chạyPython không có trong PATHCài lại Python với tùy chọn "Add to PATH"
Slash commands không hiện`.agent/` bị trong
.gitignore		Dùng
.git/info/exclude thay thế (xem Mục 5)
--- > **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.
Cài đặt nhanh (`npx`)Cài đặt toàn cục (`npm -g`)
**Tốc độ lần đầu**Chậm hơn (phải tải mỗi lần)Nhanh hơn (đã có sẵn)
**Cần cài trước**KhôngCó
**Phù hợp khi**Dùng thỉnh thoảngDùng thường xuyên, nhiều dự án
**Cập nhật**Tự động lấy bản mới nhấtCần chạy lại lệnh cài
--- ## 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 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 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 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 powershell $env:PATH -split ";" ``` **macOS / Linux:**
```bash bash echo $PATH ``` ### Kiểm tra `ag-kit` có trong PATH chưa
```bash bash # Tất cả hệ điều hành where ag-kit # Windows which ag-kit # macOS / Linux ``` Nếu lệnh trên trả về đường dẫn (ví dụ: `C:\Users\ten-ban\AppData\Roaming\npm\ag-kit`), bạn đã cấu hình đúng. ### Kiểm tra `python` có trong PATH chưa
```bash bash where python # Windows which python # macOS / Linux ``` --- ## 5. Cấu hình PATH thủ công (khi gặp lỗi) ### Windows — Thêm thư mục npm global vào PATH **B1:** Tìm thư mục npm global:
```powershell powershell npm config get prefix ``` Kết quả thường là: `C:\Users\ten-ban\AppData\Roaming\npm` **B2:** Thêm vào PATH: 1. Mở **Settings** → tìm kiếm "Environment Variables". 2. Nhấn "**Edit the system environment variables**". 3. Chọn biến **Path** trong phần "User variables" → nhấn **Edit**. 4. Nhấn **New** → dán đường dẫn từ Bước 1 vào. 5. Nhấn **OK** và **khởi động lại Terminal**. **B3:** Xác nhận lại:
```powershell powershell ag-kit --version ``` ### macOS / Linux — Thêm vào `.bashrc` hoặc `.zshrc`
```bash bash # Tìm thư mục npm global npm config get prefix # Thường là: /usr/local hoặc /home/ten-ban/.npm-global # Thêm vào file cấu hình shell echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc # Hoặc cho bash: echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc # Áp dụng thay đổi source ~/.zshrc # hoặc source ~/.bashrc ``` --- ## 6. Quy trình làm việc điển hình với nhiều dự án Đây là quy trình khuyến nghị khi bạn làm việc với nhiều dự án trên cùng một máy:
```html 1. Cài đặt một lần: npm install -g @vudovn/ag-kit 2. Cho mỗi dự án mới: cd my-new-project ag-kit init 3. Cập nhật định kỳ (không làm thường xuyên): ag-kit update ← chạy trong thư mục dự án ``` --- ## 7. Gỡ cài đặt toàn cục (khi cần) Nếu bạn muốn gỡ bỏ cài đặt toàn cục:
```html bash npm uninstall -g @vudovn/ag-kit ``` > **Lưu ý:** Gỡ cài đặt toàn cục không xóa bất kỳ thư mục `.agent/` nào đã được tạo trong các dự án. Để xóa khỏi một dự án cụ thể, hãy xóa thủ công thư mục `.agent/` đó. # Trang 2.4: Giải thích cấu trúc thư mục .agent/ (Agents, Skills, Workflows, Rules, Scripts). ## 1. Tổng quan cấu trúc Sau khi chạy lệnh `ag-kit init`, thư mục `.agent/` được tạo ra trong dự án của bạn với cấu trúc như sau:
```html .agent/ ├── ARCHITECTURE.md # Tài liệu kiến trúc tổng thể ├── AGENT_FLOW.md # Sơ đồ luồng hoạt động chi tiết ├── mcp_config.json # Cấu hình MCP servers (tích hợp bên thứ 3) ├── agents/ # 20 file cấu hình Specialist Agent ├── skills/ # 36 thư mục kiến thức chuyên sâu ├── workflows/ # 11 file quy trình làm việc ├── rules/ # Quy tắc hành vi toàn cục (GEMINI.md) └── scripts/ # Script kiểm tra tổng thể (Python) ``` Mỗi thư mục có một vai trò cụ thể và rõ ràng. Dưới đây là giải thích chi tiết từng thành phần. --- ## 2. File ARCHITECTURE.md **Đây là "bản đồ hệ thống"** dành cho AI.
MụcNội dung
**Mục đích**Cung cấp cái nhìn tổng thể về toàn bộ kiến trúc của Kit cho AI
**Nội dung**Danh sách đầy đủ 20 Agents (vai trò + Skills sử dụng), 36 Skills (phân loại theo nhóm), 11 Workflows (mô tả ngắn) và 2 master scripts
**Ai đọc**AI đọc file này đầu tiên khi khởi động để hiểu hệ sinh thái
> **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ử.
MụcNội dung
**Mục đích**Tài liệu hóa giao thức định tuyến Agent, bước kiểm tra bắt buộc và cổng Socratic
**Nội dung**Quy trình từng bước để AI chọn Agent, Checklist bắt buộc trước khi viết code, mô tả luồng làm việc từ yêu cầu đến kết quả
**Phiên bản**Được thêm vào từ phiên bản 2.0.1
--- ## 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 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
```html .agent/agents/ ├── orchestrator.md ├── frontend-specialist.md ├── backend-specialist.md ├── security-auditor.md ├── debugger.md └── ... (16 file khác) ``` ### Vai trò Mỗi file .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 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
```html .agent/skills/ ├── react-best-practices/ │ ├── SKILL.md # (Bắt buộc) Metadata và hướng dẫn chính │ ├── sections/ # Hướng dẫn chi tiết theo từng phần │ └── scripts/ # Script Python/Bash hỗ trợ (nếu có) ├── api-patterns/ │ └── SKILL.md ├── vulnerability-scanner/ │ ├── SKILL.md │ └── scripts/ │ ├── security_scan.py │ └── dependency_analyzer.py ├── frontend-design/ │ ├── SKILL.md │ └── scripts/ │ ├── ux_audit.py │ └── accessibility_checker.py └── ... (32 thư mục khác) ``` ### Vai trò - Mỗi thư mục là một **gói kiến thức độc lập** cho một lĩnh vực cụ thể. - File
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:
SkillScriptsTác dụng
`vulnerability-scanner``security_scan.py`, `dependency_analyzer.py`Quét lỗ hổng bảo mật
`lint-and-validate``lint_runner.py`Kiểm tra chất lượng code
`database-design``schema_validator.py`Kiểm tra tính nhất quán DB schema
`testing-patterns``test_runner.py`Chạy bộ test tự động
`frontend-design``ux_audit.py`, `accessibility_checker.py`Kiểm tra UX và Accessibility
`seo-fundamentals``seo_checker.py`Kiểm tra các yếu tố SEO
`performance-profiling``bundle_analyzer.py`, `lighthouse_audit.py`Đo lường hiệu năng
`webapp-testing``playwright_runner.py`Chạy E2E test
`mobile-design``mobile_audit.py`Kiểm tra giao diện mobile
--- ## 7. Thư mục `workflows/` — 11 Slash Commands ### Cấu trúc
```html .agent/workflows/ ├── brainstorm.md ├── create.md ├── debug.md ├── deploy.md ├── enhance.md ├── orchestrate.md ├── plan.md ├── preview.md ├── status.md ├── test.md └── ui-ux-pro-max.md ``` ### Vai trò Mỗi file .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: ```html .agent/workflows/my-custom-workflow.md ``` Sau đó gọi bằng lệnh `/my-custom-workflow` trong chat với AI. --- ## 8. Thư mục `rules/` — Quy tắc toàn cục ### Cấu trúc
```html .agent/rules/ └── GEMINI.md # File quy tắc chính, luôn được áp dụng ``` ### Vai trò của `GEMINI.md` Đây là file **quan trọng nhất** trong toàn bộ hệ thống. Nó chứa:
PhầnNội dung
**TIER 0 — Universal Rules**Quy tắc luôn áp dụng: Xử lý ngôn ngữ, code sạch, nhận thức phụ thuộc file
**Request Classifier**Bảng phân loại yêu cầu (Question, Survey, Simple Code, Complex Code, Design...)
**Intelligent Routing**Giao thức tự động chọn Agent phù hợp
**Agent Routing Checklist**Các bước bắt buộc AI phải làm trước khi viết code
**TIER 1 — Code Rules**Quy tắc khi viết code: Chọn project type, Socratic Gate
**Gemini Mode Mapping**Ánh xạ Plan/Ask/Edit mode sang Agent tương ứng
> **Tùy chỉnh:** `GEMINI.md` có thể được chỉnh sửa để thêm các quy tắc riêng của dự án hoặc tổ chức. Ví dụ: thêm quy tắc về naming convention, ngôn ngữ bình luận code, hay các pattern cấm dùng. --- ## 9. Thư mục `scripts/` — Master Validation Scripts ### Cấu trúc ```html .agent/scripts/ ├── checklist.py # Kiểm tra ưu tiên (P0→P6) ├── verify_all.py # Kiểm tra toàn diện (bao gồm Lighthouse, Playwright) ├── auto_preview.py # Tự động khởi chạy server xem trước └── session_manager.py # Quản lý trạng thái phiên làm việc AI ``` ### So sánh hai main scripts
Tiêu chí
checklist.py
verify\_all.py
**Khi nào dùng**Phát triển hàng ngày, trước commitTrước khi release production
**Tốc độ**Nhanh (dừng ngay khi có lỗi nghiêm trọng)Chậm hơn (chạy toàn bộ)
**Yêu cầu**Không cần URLCần cung cấp URL để chạy Lighthouse & Playwright
**Phạm vi kiểm tra**Security, Lint, Schema, Tests, UX, SEOTất cả của checklist + Lighthouse, Playwright, Bundle, Mobile, i18n
### Cách chạy thủ công
```bash bash # Kiểm tra cơ bản (từ thư mục gốc dự án) python .agent/scripts/checklist.py . # Kiểm tra toàn diện (cần server đang chạy) python .agent/scripts/verify_all.py . --url http://localhost:3000 ``` --- ## 10. Sơ đồ quan hệ giữa các thành phần ```html rules/GEMINI.md ← (1) AI đọc quy tắc đầu tiên │ ▼ ARCHITECTURE.md ← (2) AI hiểu toàn bộ hệ sinh thái │ ▼ agents/*.md ← (3) AI đóng vai Agent phù hợp │ ▼ skills/*/SKILL.md ← (4) Agent tải kiến thức cần thiết │ ▼ skills/*/scripts/*.py ← (5) Script chạy kiểm tra tự động │ ▼ scripts/checklist.py ← (6) Tổng hợp kết quả và báo cáo ``` > Hiểu rõ cấu trúc này giúp bạn dễ dàng **tùy chỉnh và mở rộng** bộ kit theo nhu cầu dự án của mình mà không làm ảnh hưởng đến phần còn lại của hệ thống.