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

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ần	Phiên bản tối thiểu	Mục đích sử dụng
Node.js	16.0 hoặc mới hơn	Chạy công cụ CLI `ag-kit` và ứng dụng web
npm hoặc yarn	Đi kèm với Node.js	Quản lý gói phụ thuộc
Python	3.10 hoặc mới hơn	Chạy các script kiểm tra tự động của Kit
Git	Bất kỳ phiên bản nào	Cậ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
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:

Được cài đặt trên máy tính.
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)

Tải từ python.org.
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.
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)

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

Hệ điều hành	Trạng thái	Ghi 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
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:

Kết nối với GitHub để tải phiên bản mới nhất.
Tạo thư mục .agent/ trong dự án của bạn.
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

Vấn đề	Nguyên nhân	Giải pháp
`npx: command not found`	Node.js chưa được cài đặt	Cài đặt Node.js từ nodejs.org
`ag-kit: command not found`	Cài đặt toàn cục chưa thành công	Chạ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ạy	Python không có trong PATH	Cà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ông	Có
Phù hợp khi	Dùng thỉnh thoảng	Dùng thường xuyên, nhiều dự án
Cập nhật	Tự động lấy bản mới nhất	Cầ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
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:

Mở Settings → tìm kiếm "Environment Variables".
Nhấn "Edit the system environment variables".
Chọn biến Path trong phần "User variables" → nhấn Edit.
Nhấn New → dán đường dẫn từ Bước 1 vào.
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.

Mục	Nộ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ục	Nộ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
{
"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:

Skill	Scripts	Tá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

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

Phần	Nộ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

.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 commit	Trướ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 URL	Cần cung cấp URL để chạy Lighthouse & Playwright
Phạm vi kiểm tra	Security, Lint, Schema, Tests, UX, SEO	Tất cả của checklist + Lighthouse, Playwright, Bundle, Mobile, i18n

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

2. Node.js

Tại sao cần Node.js?

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

Cài đặt Node.js

3. Python

Tại sao cần Python?

Kiểm tra phiên bản Python

Cài đặt Python (Windows)

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

4. Git

Tại sao cần Git?

Kiểm tra phiên bản Git

Cài đặt Git

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

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

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

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

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

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

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

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

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

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

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

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

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

5. Quan trọng: Cấu hình .gitignore

Vấn đề

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

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

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

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

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

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

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

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

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

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

Kiểm tra PATH hiện tại

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

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

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

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

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

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

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

2. File ARCHITECTURE.md

3. File AGENT_FLOW.md

4. File mcp_config.json

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

Cấu trúc

Vai trò

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

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

Cấu trúc

Vai trò

Skills có script đặc biệt

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

Cấu trúc

Vai trò

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

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

Cấu trúc

Vai trò của GEMINI.md

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

Cấu trúc

So sánh hai main scripts

Cách chạy thủ công

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

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

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

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

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

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

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

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

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

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

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

Vai trò của `GEMINI.md`

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