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

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