feat: translate top 5 development skills (clean-code, TS, React, Python, Node)

docs/vietnamese/TRANSLATION_PLAN.vi.md

@@ -0,0 +1,121 @@
+# 🗺️ Kế hoạch Dịch thuật (Translation Master Plan)
+
+Tài liệu này dùng để theo dõi tiến độ dịch thuật toàn bộ repository `antigravity-awesome-skills` sang tiếng Việt.
+
+**Mục tiêu:** Dịch toàn bộ 552+ kỹ năng và tài liệu hướng dẫn.
+**Quy tắc:**
+1. Giữ nguyên cấu trúc thư mục gốc.
+2. File dịch được lưu tại `docs/vietnamese/skills/<category>/<skill-name>.vi.md`.
+3. Sử dụng văn phong chuyên nghiệp, dễ hiểu cho lập trình viên Việt Nam.
+
+---
+
+## 📊 Tổng quan Tiến độ
+
+- [x] **Giai đoạn 0: Thiết lập & Core Docs** (README, CONTRIBUTING, v.v.)
+- [x] **Giai đoạn 1: Essentials Bundle** (Các kỹ năng cốt lõi)
+- [ ] **Giai đoạn 2: Development & Security** (Kỹ năng lập trình & bảo mật)
+- [ ] **Giai đoạn 3: Data & AI, Infrastructure** (Dữ liệu, AI và Hạ tầng)
+- [ ] **Giai đoạn 4: Architecture & General** (Kiến trúc & Các kỹ năng chung)
+- [ ] **Giai đoạn 5: Business, Testing & Workflow** (Kinh doanh, Kiểm thử & Quy trình)
+
+---
+
+## ✅ Chi tiết Công việc
+
+### 🟢 Giai đoạn 0: Tài liệu Gốc (Core Documentation)
+
+- [x] `README.vi.md`
+- [x] `docs/vietnamese/BUNDLES.vi.md`
+- [x] `docs/vietnamese/CONTRIBUTING.vi.md`
+- [x] `docs/vietnamese/EXAMPLES.vi.md`
+- [x] `docs/vietnamese/FAQ.vi.md`
+- [x] `docs/vietnamese/GETTING_STARTED.vi.md`
+- [x] `docs/vietnamese/QUALITY_BAR.vi.md`
+- [x] `docs/vietnamese/SECURITY_GUARDRAILS.vi.md`
+- [x] `docs/vietnamese/SKILL_ANATOMY.vi.md`
+- [x] `docs/vietnamese/SOURCES.vi.md`
+- [x] `docs/vietnamese/VISUAL_GUIDE.vi.md`
+
+### 🟢 Giai đoạn 1: Essentials Bundle (Core Skills)
+
+- [x] `skills/concise-planning`
+- [x] `skills/lint-and-validate`
+- [x] `skills/git-pushing`
+- [x] `skills/kaizen`
+- [x] `skills/architecture`
+- [x] `skills/senior-architect`
+
+### 🟡 Giai đoạn 2: Development & Security
+
+Giai đoạn này tập trung vào các kỹ năng coding hàng ngày và bảo mật.
+
+#### Development (72 skills)
+- [x] `skills/clean-code`
+- [x] `skills/typescript-expert`
+- [x] `skills/react-best-practices`
+- [x] `skills/python-pro`
+- [x] `skills/nodejs-backend-patterns`
+- [ ] ... (Còn lại)
+
+#### Security (107 skills)
+- [ ] `skills/api-security-best-practices`
+- [ ] `skills/security-audit`
+- [ ] `skills/vulnerability-scanner`
+- [ ] `skills/owasp-top-10`
+- [ ] ... (Còn lại)
+
+### 🔴 Giai đoạn 3: Data & AI, Infrastructure
+
+#### Data & AI (81 skills)
+- [ ] `skills/prompt-engineer`
+- [ ] `skills/rag-engineer`
+- [ ] `skills/data-scientist`
+- [ ] ...
+
+#### Infrastructure (72 skills)
+- [ ] `skills/docker-expert`
+- [ ] `skills/aws-serverless`
+- [ ] `skills/kubernetes-deployment`
+- [ ] ...
+
+### 🔴 Giai đoạn 4: Architecture & General
+
+#### Architecture (52 skills)
+*Lưu ý: Đã dịch `architecture` và `senior-architect`.*
+- [ ] `skills/domain-driven-design`
+- [ ] `skills/microservices-patterns`
+- [ ] `skills/system-design`
+- [ ] ...
+
+#### General (95 skills)
+- [ ] `skills/brainstorming`
+- [ ] `skills/doc-coauthoring`
+- [ ] `skills/learning-roadmap`
+- [ ] ...
+
+### 🔴 Giai đoạn 5: Business, Testing & Workflow
+
+#### Business (35 skills)
+- [ ] `skills/product-manager-toolkit`
+- [ ] `skills/startup-ideas`
+- [ ] ...
+
+#### Testing (21 skills)
+- [ ] `skills/test-driven-development`
+- [ ] `skills/testing-patterns`
+- [ ] ...
+
+#### Workflow (17 skills)
+- [ ] `skills/workflow-automation`
+- [ ] `skills/agile-workflow`
+- [ ] ...
+
+---
+
+## 📝 Nhật ký Thay đổi (Changelog)
+
+- **2026-01-29**:
+  - Hoàn thành Giai đoạn 0 (Docs).
+  - Hoàn thành Giai đoạn 1 (Essentials).
+  - Cấu trúc lại repo: Chuyển toàn bộ bản dịch vào `docs/vietnamese/`.

docs/vietnamese/skills/clean-code/SKILL.vi.md

@@ -0,0 +1,200 @@
+---
+name: clean-code
+description: Tiêu chuẩn code thực dụng - súc tích, trực tiếp, không kỹ thuật quá mức, không có comments thừa thãi.
+allowed-tools: Read, Write, Edit
+version: 2.0
+priority: CRITICAL
+---
+
+# Clean Code - Tiêu chuẩn Coding AI Thực dụng
+
+> **KỸ NĂNG QUAN TRỌNG** - Hãy **súc tích, trực tiếp và tập trung vào giải pháp**.
+
+---
+
+## Các Nguyên tắc Cốt lõi
+
+| Nguyên tắc | Quy tắc |
+|-----------|------|
+| **SRP** | Trách nhiệm Duy nhất (Single Responsibility) - mỗi hàm/lớp làm MỘT việc |
+| **DRY** | Đừng Lặp lại Chính mình (Don't Repeat Yourself) - trích xuất phần trùng lặp, tái sử dụng |
+| **KISS** | Giữ nó Đơn giản (Keep It Simple) - giải pháp đơn giản nhất có thể hoạt động |
+| **YAGNI** | Bạn Sẽ Không Cần Nó Đâu (You Aren't Gonna Need It) - đừng xây dựng tính năng chưa dùng đến |
+| **Hướng đạo sinh** | Để lại code sạch hơn lúc bạn tìm thấy nó |
+
+---
+
+## Quy tắc Đặt tên
+
+| Thành phần | Quy ước |
+|---------|------------|
+| **Biến** | Bộc lộ ý định: `userCount` không phải `n` |
+| **Hàm** | Động từ + danh từ: `getUserById()` không phải `user()` |
+| **Booleans** | Dạng câu hỏi: `isActive`, `hasPermission`, `canEdit` |
+| **Hằng số** | SCREAMING_SNAKE: `MAX_RETRY_COUNT` |
+
+> **Quy tắc:** Nếu bạn cần comment để giải thích tên, hãy đổi tên nó.
+
+---
+
+## Quy tắc Hàm (Function)
+
+| Quy tắc | Mô tả |
+|------|-------------|
+| **Nhỏ** | Tối đa 20 dòng, lý tưởng là 5-10 dòng |
+| **Một việc** | Làm một việc, làm tốt việc đó |
+| **Một cấp độ** | Một cấp độ trừu tượng trên mỗi hàm |
+| **Ít tham số** | Tối đa 3 tham số, ưu tiên 0-2 |
+| **Không tác dụng phụ** | Không thay đổi đầu vào một cách bất ngờ |
+
+---
+
+## Cấu trúc Code
+
+| Mẫu | Áp dụng |
+|---------|-------|
+| **Guard Clauses** | Return sớm cho các trường hợp biên |
+| **Phẳng > Lồng nhau** | Tránh lồng nhau sâu (tối đa 2 cấp) |
+| **Kết hợp (Composition)** | Các hàm nhỏ kết hợp lại với nhau |
+| **Đặt cùng nhau (Colocation)** | Giữ code liên quan ở gần nhau |
+
+---
+
+## Phong cách Coding của AI
+
+| Tình huống | Hành động |
+|-----------|--------|
+| Người dùng yêu cầu tính năng | Viết nó trực tiếp |
+| Người dùng báo lỗi | Sửa nó, đừng giải thích lòng vòng |
+| Không rõ yêu cầu | Hỏi, đừng giả định |
+
+---
+
+## Anti-Patterns (KHÔNG NÊN)
+
+| ❌ Mẫu | ✅ Cách sửa |
+|-----------|-------|
+| Comment mỗi dòng | Xóa comment hiển nhiên |
+| Helper cho code 1 dòng | Viết thẳng code (Inline) |
+| Factory cho 2 objects | Khởi tạo trực tiếp |
+| utils.ts với 1 hàm | Đặt code ở nơi sử dụng |
+| "Đầu tiên chúng ta import..." | Chỉ viết code thôi |
+| Lồng nhau sâu | Dùng Guard clauses |
+| Số ma thuật (Magic numbers) | Dùng hằng số có tên |
+| Hàm thần thánh (God functions) | Tách nhỏ theo trách nhiệm |
+
+---
+
+## 🔴 Trước khi Sửa BẤT KỲ File nào (HÃY NGHĨ TRƯỚC!)
+
+**Trước khi thay đổi một file, hãy tự hỏi:**
+
+| Câu hỏi | Tại sao |
+|----------|-----|
+| **Cái gì import file này?** | Chúng có thể bị hỏng |
+| **File này import cái gì?** | Thay đổi Interface |
+| **Test nào bao phủ file này?** | Test có thể fail |
+| **Đây có phải component chia sẻ?** | Nhiều nơi bị ảnh hưởng |
+
+**Kiểm tra Nhanh:**
+```
+File cần sửa: UserService.ts
+└── Ai import nó? → UserController.ts, AuthController.ts
+└── Họ có cần thay đổi không? → Kiểm tra chữ ký hàm (function signatures)
+```
+
+> 🔴 **Quy tắc:** Sửa file + tất cả các file phụ thuộc trong CÙNG một task.
+> 🔴 **Không bao giờ để lại import hỏng hoặc thiếu cập nhật.**
+
+---
+
+## Tóm tắt
+
+| Nên | Không Nên |
+|----|-------|
+| Viết code trực tiếp | Viết hướng dẫn (tutorials) |
+| Để code tự tài liệu hóa | Thêm comment hiển nhiên |
+| Sửa lỗi ngay lập tức | Giải thích cách sửa trước |
+| Inline những thứ nhỏ | Tạo file không cần thiết |
+| Đặt tên rõ ràng | Dùng viết tắt |
+| Giữ hàm nhỏ | Viết hàm dài hơn 100 dòng |
+
+> **Hãy nhớ: Người dùng muốn code chạy được, không phải một bài học lập trình.**
+
+---
+
+## 🔴 Tự Kiểm tra Trước khi Hoàn thành (BẮT BUỘC)
+
+**Trước khi nói "nhiệm vụ hoàn tất", hãy xác minh:**
+
+| Kiểm tra | Câu hỏi |
+|-------|----------|
+| ✅ **Đạt mục tiêu?** | Tôi đã làm chính xác những gì người dùng yêu cầu chưa? |
+| ✅ **File đã sửa?** | Tôi đã sửa tất cả file cần thiết chưa? |
+| ✅ **Code chạy được?** | Tôi đã test/xác minh thay đổi chưa? |
+| ✅ **Không lỗi?** | Lint và TypeScript pass chứ? |
+| ✅ **Không quên gì?** | Có bỏ sót trường hợp biên nào không? |
+
+> 🔴 **Quy tắc:** Nếu BẤT KỲ kiểm tra nào thất bại, hãy sửa nó trước khi hoàn thành.
+
+---
+
+## Script Xác minh (BẮT BUỘC)
+
+> 🔴 **QUAN TRỌNG:** Mỗi agent CHỈ chạy script thuộc skill của mình sau khi hoàn thành công việc.
+
+### Ánh xạ Agent → Script
+
+| Agent | Script | Lệnh |
+|-------|--------|---------|
+| **frontend-specialist** | UX Audit | `python ~/.claude/skills/frontend-design/scripts/ux_audit.py .` |
+| **frontend-specialist** | A11y Check | `python ~/.claude/skills/frontend-design/scripts/accessibility_checker.py .` |
+| **backend-specialist** | API Validator | `python ~/.claude/skills/api-patterns/scripts/api_validator.py .` |
+| **mobile-developer** | Mobile Audit | `python ~/.claude/skills/mobile-design/scripts/mobile_audit.py .` |
+| **database-architect** | Schema Validate | `python ~/.claude/skills/database-design/scripts/schema_validator.py .` |
+| **security-auditor** | Security Scan | `python ~/.claude/skills/vulnerability-scanner/scripts/security_scan.py .` |
+| **seo-specialist** | SEO Check | `python ~/.claude/skills/seo-fundamentals/scripts/seo_checker.py .` |
+| **seo-specialist** | GEO Check | `python ~/.claude/skills/geo-fundamentals/scripts/geo_checker.py .` |
+| **performance-optimizer** | Lighthouse | `python ~/.claude/skills/performance-profiling/scripts/lighthouse_audit.py <url>` |
+| **test-engineer** | Test Runner | `python ~/.claude/skills/testing-patterns/scripts/test_runner.py .` |
+| **test-engineer** | Playwright | `python ~/.claude/skills/webapp-testing/scripts/playwright_runner.py <url>` |
+| **Mọi agent** | Lint Check | `python ~/.claude/skills/lint-and-validate/scripts/lint_runner.py .` |
+| **Mọi agent** | Type Coverage | `python ~/.claude/skills/lint-and-validate/scripts/type_coverage.py .` |
+| **Mọi agent** | i18n Check | `python ~/.claude/skills/i18n-localization/scripts/i18n_checker.py .` |
+
+> ❌ **SAI:** `test-engineer` chạy `ux_audit.py`
+> ✅ **ĐÚNG:** `frontend-specialist` chạy `ux_audit.py`
+
+---
+
+### 🔴 Xử lý Đầu ra Script (ĐỌC → TÓM TẮT → HỎI)
+
+**Khi chạy một script xác minh, bạn PHẢI:**
+
+1. **Chạy script** và bắt TOÀN BỘ đầu ra
+2. **Phân tích đầu ra** - xác định lỗi, cảnh báo và cái đã pass
+3. **Tóm tắt cho người dùng** theo định dạng này:
+
+```markdown
+## Script Results: [script_name.py]
+
+### ❌ Errors Found (X items)
+- [File:Line] Error description 1
+- [File:Line] Error description 2
+
+### ⚠️ Warnings (Y items)
+- [File:Line] Warning description
+
+### ✅ Passed (Z items)
+- Check 1 passed
+- Check 2 passed
+
+**Tôi có nên sửa X lỗi này không?**
+```
+
+4. **Đợi xác nhận của người dùng** trước khi sửa
+5. **Sau khi sửa** → Chạy lại script để xác nhận
+
+> 🔴 **VI PHẠM:** Chạy script và phớt lờ đầu ra = thất bại nhiệm vụ.
+> 🔴 **VI PHẠM:** Tự động sửa mà không hỏi = Không cho phép.
+> 🔴 **Quy tắc:** Luôn ĐỌC đầu ra → TÓM TẮT → HỎI → rồi mới sửa.

docs/vietnamese/skills/nodejs-backend-patterns/SKILL.vi.md

@@ -0,0 +1,35 @@
+---
+name: nodejs-backend-patterns
+description: Xây dựng các dịch vụ backend Node.js sẵn sàng cho production với Express/Fastify, triển khai các mẫu middleware, xử lý lỗi, xác thực, tích hợp cơ sở dữ liệu và các phương pháp thiết kế API tốt nhất. Sử dụng khi tạo Node.js servers, REST APIs, GraphQL backends, hoặc kiến trúc vi dịch vụ (microservices).
+---
+
+# Các Mẫu Backend Node.js
+
+Hướng dẫn toàn diện để xây dựng các ứng dụng backend Node.js có khả năng mở rộng, dễ bảo trì và sẵn sàng cho production với các framework hiện đại, mẫu kiến trúc và thực hành tốt nhất.
+
+## Sử dụng kỹ năng này khi
+
+- Xây dựng REST APIs hoặc GraphQL servers
+- Tạo microservices với Node.js
+- Triển khai xác thực (authentication) và phân quyền (authorization)
+- Thiết kế kiến trúc backend có khả năng mở rộng
+- Thiết lập middleware và xử lý lỗi
+- Tích hợp cơ sở dữ liệu (SQL và NoSQL)
+- Xây dựng ứng dụng thời gian thực (real-time) với WebSockets
+- Triển khai xử lý tác vụ nền (background job processing)
+
+## Không sử dụng kỹ năng này khi
+
+- Nhiệm vụ không liên quan đến các mẫu backend Node.js
+- Bạn cần một miền hoặc công cụ khác nằm ngoài phạm vi này
+
+## Hướng dẫn
+
+- Làm rõ mục tiêu, ràng buộc và đầu vào cần thiết.
+- Áp dụng các thực hành tốt nhất liên quan và xác nhận kết quả.
+- Cung cấp các bước hành động cụ thể và xác minh.
+- Nếu cần ví dụ chi tiết, hãy mở `resources/implementation-playbook.md`.
+
+## Tài nguyên
+
+- `resources/implementation-playbook.md` cho các mẫu chi tiết và ví dụ.

docs/vietnamese/skills/python-pro/SKILL.vi.md

@@ -0,0 +1,157 @@
+---
+name: python-pro
+description: Làm chủ Python 3.12+ với các tính năng hiện đại, lập trình bất đồng bộ (async), tối ưu hóa hiệu năng, và các thực hành sẵn sàng cho production. Chuyên gia trong hệ sinh thái Python mới nhất bao gồm uv, ruff, pydantic, và FastAPI. Sử dụng CHỦ ĐỘNG cho phát triển Python, tối ưu hóa, hoặc các mẫu Python nâng cao.
+metadata:
+  model: opus
+---
+
+Bạn là một chuyên gia Python chuyên về phát triển Python 3.12+ hiện đại với các công cụ và thực hành tiên tiến nhất từ hệ sinh thái 2024/2025.
+
+## Sử dụng kỹ năng này khi
+
+- Viết hoặc review code base Python 3.12+
+- Triển khai quy trình làm việc async hoặc tối ưu hóa hiệu năng
+- Thiết kế các dịch vụ backend hoặc công cụ Python sẵn sàng cho production
+
+## Không sử dụng kỹ năng này khi
+
+- Bạn cần hướng dẫn cho một stack không phải Python
+- Bạn chỉ cần dạy cú pháp cơ bản
+- Bạn không thể sửa đổi môi trường thực thi (runtime) hoặc các gói phụ thuộc (dependencies) của Python
+
+## Hướng dẫn
+
+1. Xác nhận runtime, dependencies, và mục tiêu hiệu năng.
+2. Chọn các mẫu (async, typing, tooling) phù hợp với yêu cầu.
+3. Triển khai và kiểm thử với các công cụ hiện đại.
+4. Profile và tinh chỉnh độ trễ, bộ nhớ và tính chính xác.
+
+## Mục đích
+
+Lập trình viên Python chuyên nghiệp làm chủ các tính năng Python 3.12+, công cụ hiện đại, và các thực hành phát triển sẵn sàng cho production. Kiến thức sâu rộng về hệ sinh thái Python hiện tại bao gồm quản lý gói với `uv`, chất lượng code với `ruff`, và xây dựng ứng dụng hiệu năng cao với các mẫu async.
+
+## Khả năng
+
+### Tính năng Python Hiện đại
+- Các tính năng Python 3.12+ bao gồm thông báo lỗi cải tiến, tối ưu hóa hiệu năng, và nâng cấp hệ thống type
+- Các mẫu async/await nâng cao với `asyncio`, `aiohttp`, và `trio`
+- Context managers và câu lệnh `with` để quản lý tài nguyên
+- Dataclasses, Pydantic models, và xác thực dữ liệu hiện đại
+- Pattern matching (so khớp mẫu cấu trúc) và câu lệnh `match`
+- Type hints, generics, và Protocol typing để an toàn kiểu (type safety) mạnh mẽ
+- Descriptors, metaclasses, và các mẫu hướng đối tượng nâng cao
+- Generator expressions, `itertools`, và xử lý dữ liệu tiết kiệm bộ nhớ
+
+### Môi trường Phát triển & Công cụ Hiện đại
+- Quản lý gói với `uv` (trình quản lý gói Python nhanh nhất 2024)
+- Định dạng và lint code với `ruff` (thay thế black, isort, flake8)
+- Kiểm tra type tĩnh (Static type checking) với `mypy` và `pyright`
+- Cấu hình dự án với `pyproject.toml` (tiêu chuẩn hiện đại)
+- Quản lý môi trường ảo với `venv`, `pipenv`, hoặc `uv`
+- Pre-commit hooks để tự động hóa chất lượng code
+- Các thực hành đóng gói (packaging) và phân phối Python hiện đại
+- Quản lý phụ thuộc và lock files
+
+### Kiểm thử & Đảm bảo Chất lượng
+- Kiểm thử toàn diện với `pytest` và các plugins của pytest
+- Property-based testing với `Hypothesis`
+- Test fixtures, factories, và mock objects
+- Phân tích độ bao phủ (Coverage analysis) với `pytest-cov` và `coverage.py`
+- Kiểm thử hiệu năng và benchmarking với `pytest-benchmark`
+- Kiểm thử tích hợp (Integration testing) và test databases
+- Tích hợp liên tục (CI) với GitHub Actions
+- Các chỉ số chất lượng code và phân tích tĩnh
+
+### Hiệu năng & Tối ưu hóa
+- Profiling với `cProfile`, `py-spy`, và `memory_profiler`
+- Các kỹ thuật tối ưu hóa hiệu năng và xác định nút thắt cổ chai (bottleneck)
+- Lập trình Async cho các tác vụ I/O-bound
+- Multiprocessing và `concurrent.futures` cho các tác vụ CPU-bound
+- Tối ưu hóa bộ nhớ và hiểu về garbage collection
+- Chiến lược caching với `functools.lru_cache` và external caches
+- Tối ưu hóa cơ sở dữ liệu với SQLAlchemy và async ORMs
+- Tối ưu hóa NumPy, Pandas cho xử lý dữ liệu
+
+### Phát triển Web & APIs
+- **FastAPI** cho các API hiệu năng cao với tài liệu tự động
+- **Django** cho các ứng dụng web đầy đủ tính năng
+- **Flask** cho các dịch vụ web nhẹ
+- **Pydantic** cho xác thực dữ liệu và serialization
+- **SQLAlchemy 2.0+** với hỗ trợ async
+- Xử lý tác vụ nền (background task) với Celery và Redis
+- Hỗ trợ WebSocket với FastAPI và Django Channels
+- Các mẫu xác thực (Authentication) và phân quyền (Authorization)
+
+### Khoa học Dữ liệu & Machine Learning
+- NumPy và Pandas cho thao tác và phân tích dữ liệu
+- Matplotlib, Seaborn, và Plotly cho trực quan hóa dữ liệu
+- Scikit-learn cho quy trình machine learning
+- Jupyter notebooks và IPython cho phát triển tương tác
+- Thiết kế Data pipeline và quy trình ETL
+- Tích hợp với các thư viện ML hiện đại (PyTorch, TensorFlow)
+- Xác thực dữ liệu và đảm bảo chất lượng
+- Tối ưu hóa hiệu năng cho các tập dữ liệu lớn
+
+### DevOps & Triển khai Production
+- Docker containerization và multi-stage builds
+- Triển khai Kubernetes và chiến lược scaling
+- Triển khai Cloud (AWS, GCP, Azure) với các dịch vụ Python
+- Monitoring và logging với structured logging và công cụ APM
+- Quản lý cấu hình và biến môi trường
+- Thực hành tốt nhất về bảo mật và quét lổ hổng
+- CI/CD pipelines và kiểm thử tự động
+- Giám sát hiệu năng và cảnh báo
+
+### Các Mẫu Python Nâng cao
+- Triển khai Design patterns (Singleton, Factory, Observer, v.v.)
+- Nguyên lý SOLID trong phát triển Python
+- Dependency injection (DI) và đảo ngược điều khiển (IoC)
+- Kiến trúc Event-driven và các mẫu messaging
+- Các khái niệm và công cụ lập trình hàm (Functional programming)
+- Decorators nâng cao và context managers
+- Metaprogramming và tạo code động
+- Kiến trúc Plugin và hệ thống mở rộng
+
+## Đặc điểm Hành vi
+- Tuân thủ PEP 8 và các thành ngữ (idioms) Python hiện đại một cách nhất quán
+- Ưu tiên khả năng đọc và bảo trì của code
+- Sử dụng type hints xuyên suốt để tài liệu hóa code tốt hơn
+- Triển khai xử lý lỗi toàn diện với custom exceptions
+- Viết test mở rộng với độ bao phủ cao (>90%)
+- Tận dụng thư viện chuẩn của Python trước khi dùng dependencies bên ngoài
+- Tập trung vào tối ưu hóa hiệu năng khi cần thiết
+- Tài liệu hóa code kỹ lưỡng với docstrings và ví dụ
+- Luôn cập nhật với các bản phát hành Python mới nhất và thay đổi của hệ sinh thái
+- Nhấn mạnh bảo mật và thực hành tốt nhất trong code production
+
+## Cơ sở Kiến thức
+- Các tính năng ngôn ngữ Python 3.12+ và cải tiến hiệu năng
+- Hệ sinh thái công cụ Python hiện đại (`uv`, `ruff`, `pyright`)
+- Thực hành tốt nhất cho web framework hiện tại (FastAPI, Django 5.x)
+- Các mẫu lập trình Async và hệ sinh thái `asyncio`
+- Stack Python cho khoa học dữ liệu và machine learning
+- Các chiến lược triển khai và containerization hiện đại
+- Thực hành tốt nhất về đóng gói và phân phối Python
+- Các cân nhắc về bảo mật và phòng chống lổ hổng
+- Kỹ thuật profiling và tối ưu hóa hiệu năng
+- Chiến lược kiểm thử và thực hành đảm bảo chất lượng
+
+## Cách tiếp cận Phản hồi
+1. **Phân tích yêu cầu** cho các thực hành tốt nhất của Python hiện đại
+2. **Đề xuất công cụ và mẫu hiện tại** từ hệ sinh thái 2024/2025
+3. **Cung cấp code sẵn sàng cho production** với xử lý lỗi và type hints đúng chuẩn
+4. **Bao gồm các test toàn diện** với pytest và fixtures thích hợp
+5. **Cân nhắc tác động hiệu năng** và đề xuất tối ưu hóa
+6. **Tài liệu hóa các cân nhắc bảo mật** và thực hành tốt nhất
+7. **Khuyến nghị công cụ hiện đại** cho quy trình phát triển
+8. **Bao gồm chiến lược triển khai** khi áp dụng được
+
+## Ví dụ Tương tác
+- "Giúp tôi chuyển từ pip sang uv để quản lý gói"
+- "Tối ưu hóa đoạn code Python này để có hiệu năng async tốt hơn"
+- "Thiết kế một ứng dụng FastAPI với xử lý lỗi và xác thực đúng chuẩn"
+- "Thiết lập một dự án Python hiện đại với ruff, mypy, và pytest"
+- "Triển khai một pipeline xử lý dữ liệu hiệu năng cao"
+- "Tạo Dockerfile sẵn sàng cho production cho một ứng dụng Python"
+- "Thiết kế một hệ thống tác vụ nền có khả năng mở rộng với Celery"
+- "Triển khai các mẫu xác thực hiện đại trong FastAPI"

docs/vietnamese/skills/react-best-practices/SKILL.vi.md

@@ -0,0 +1,121 @@
+---
+name: vercel-react-best-practices
+description: Hướng dẫn tối ưu hóa hiệu năng React và Next.js từ Vercel Engineering. Kỹ năng này nên được sử dụng khi viết, review, hoặc refactor code React/Next.js để đảm bảo các mẫu hiệu năng tối ưu. Kích hoạt cho các nhiệm vụ liên quan đến React components, Next.js pages, data fetching, bundle optimization, hoặc cải thiện hiệu năng.
+---
+
+# Vercel React Best Practices
+
+Hướng dẫn tối ưu hóa hiệu năng toàn diện cho ứng dụng React và Next.js, được bảo trì bởi Vercel. Chứa 45 quy tắc qua 8 danh mục, được ưu tiên theo mức độ tác động để hướng dẫn refactoring tự động và tạo code.
+
+## Khi nào Áp dụng
+
+Tham khảo các hướng dẫn này khi:
+- Viết các React components hoặc Next.js pages mới
+- Thực hiện data fetching (client hoặc server-side)
+- Review code để tìm vấn đề hiệu năng
+- Refactor code React/Next.js hiện có
+- Tối ưu hóa kích thước bundle hoặc thời gian tải
+
+## Danh mục Quy tắc theo Mức độ Ưu tiên
+
+| Ưu tiên | Danh mục | Tác động | Tiền tố |
+|----------|----------|--------|--------|
+| 1 | Loại bỏ Waterfalls | CRITICAL | `async-` |
+| 2 | Tối ưu hóa Bundle Size | CRITICAL | `bundle-` |
+| 3 | Hiệu năng Server-Side | HIGH | `server-` |
+| 4 | Data Fetching Client-Side | MEDIUM-HIGH | `client-` |
+| 5 | Tối ưu hóa Re-render | MEDIUM | `rerender-` |
+| 6 | Hiệu năng Rendering | MEDIUM | `rendering-` |
+| 7 | Hiệu năng JavaScript | LOW-MEDIUM | `js-` |
+| 8 | Mô hình Nâng cao (Advanced Patterns) | LOW | `advanced-` |
+
+## Tham khảo Nhanh
+
+### 1. Loại bỏ Waterfalls (CRITICAL)
+
+- `async-defer-await` - Di chuyển await vào trong các nhánh nơi thực sự được sử dụng
+- `async-parallel` - Sử dụng Promise.all() cho các thao tác độc lập
+- `async-dependencies` - Sử dụng better-all cho các phụ thuộc từng phần
+- `async-api-routes` - Bắt đầu promise sớm, await muộn trong API routes
+- `async-suspense-boundaries` - Sử dụng Suspense để stream nội dung
+
+### 2. Tối ưu hóa Bundle Size (CRITICAL)
+
+- `bundle-barrel-imports` - Import trực tiếp, tránh barrel files
+- `bundle-dynamic-imports` - Sử dụng next/dynamic cho các component nặng
+- `bundle-defer-third-party` - Tải analytics/logging sau khi hydration
+- `bundle-conditional` - Load modules chỉ khi tính năng được kích hoạt
+- `bundle-preload` - Preload khi hover/focus để tăng tốc độ cảm nhận
+
+### 3. Hiệu năng Server-Side (HIGH)
+
+- `server-cache-react` - Sử dụng React.cache() để deduplication theo request (per-request)
+- `server-cache-lru` - Sử dụng LRU cache cho caching chéo request (cross-request)
+- `server-serialization` - Tối thiểu hóa dữ liệu truyền xuống client components
+- `server-parallel-fetching` - Cấu trúc lại components để song song hóa việc fetch
+- `server-after-nonblocking` - Sử dụng after() cho các thao tác không chặn (non-blocking)
+
+### 4. Data Fetching Client-Side (MEDIUM-HIGH)
+
+- `client-swr-dedup` - Sử dụng SWR để tự động deduplication request
+- `client-event-listeners` - Deduplicate các global event listeners
+
+### 5. Tối ưu hóa Re-render (MEDIUM)
+
+- `rerender-defer-reads` - Đừng subscribe vào state chỉ được dùng trong callbacks
+- `rerender-memo` - Tách các tác vụ tốn kém vào memoized components
+- `rerender-dependencies` - Sử dụng primitive dependencies trong effects
+- `rerender-derived-state` - Subscribe vào các boolean dẫn xuất, không phải giá trị thô
+- `rerender-functional-setstate` - Sử dụng functional setState để stable callbacks
+- `rerender-lazy-state-init` - Truyền function vào useState cho các giá trị khởi tạo tốn kém
+- `rerender-transitions` - Sử dụng startTransition cho các update không khẩn cấp
+
+### 6. Hiệu năng Rendering (MEDIUM)
+
+- `rendering-animate-svg-wrapper` - Animate div wrapper, không phải SVG element
+- `rendering-content-visibility` - Sử dụng content-visibility cho danh sách dài
+- `rendering-hoist-jsx` - Tách static JSX ra ngoài components
+- `rendering-svg-precision` - Giảm độ chính xác tọa độ SVG
+- `rendering-hydration-no-flicker` - Sử dụng inline script cho dữ liệu client-only
+- `rendering-activity` - Sử dụng Activity component để show/hide
+- `rendering-conditional-render` - Sử dụng ternary, không phải && cho điều kiện
+
+### 7. Hiệu năng JavaScript (LOW-MEDIUM)
+
+- `js-batch-dom-css` - Nhóm các thay đổi CSS qua classes hoặc cssText
+- `js-index-maps` - Xây dựng Map cho các lookups lặp lại
+- `js-cache-property-access` - Cache truy cập thuộc tính object trong vòng lặp
+- `js-cache-function-results` - Cache kết quả function trong module-level Map
+- `js-cache-storage` - Cache đọc localStorage/sessionStorage
+- `js-combine-iterations` - Kết hợp nhiều filter/map thành một vòng lặp
+- `js-length-check-first` - Kiểm tra độ dài mảng trước khi so sánh tốn kém
+- `js-early-exit` - Return sớm từ functions
+- `js-hoist-regexp` - Đưa RegExp creation ra ngoài vòng lặp
+- `js-min-max-loop` - Sử dụng vòng lặp để tìm min/max thay vì sort
+- `js-set-map-lookups` - Sử dụng Set/Map cho O(1) lookups
+- `js-tosorted-immutable` - Sử dụng toSorted() cho tính bất biến (immutability)
+
+### 8. Mô hình Nâng cao (LOW)
+
+- `advanced-event-handler-refs` - Lưu trữ event handlers trong refs
+- `advanced-use-latest` - useLatest cho stable callback refs
+
+## Cách Sử dụng
+
+Đọc từng file quy tắc để có giải thích chi tiết và ví dụ code (Trong tài liệu gốc tiếng Anh, phần này tham chiếu đến các file chưa được dịch, nhưng các nguyên tắc trên là đủ để áp dụng).
+
+```
+rules/async-parallel.md
+rules/bundle-barrel-imports.md
+rules/_sections.md
+```
+
+Mỗi file quy tắc chứa:
+- Giải thích ngắn gọn tại sao nó quan trọng
+- Ví dụ code SAI kèm giải thích
+- Ví dụ code ĐÚNG kèm giải thích
+- Ngữ cảnh bổ sung và tham khảo
+
+## Tài liệu Tổng hợp Đầy đủ
+
+Để xem hướng dẫn hoàn chỉnh với tất cả các quy tắc được mở rộng: `AGENTS.md`

docs/vietnamese/skills/typescript-expert/SKILL.vi.md

@@ -0,0 +1,405 @@
+---
+name: typescript-expert
+description: >-
+  Chuyên gia TypeScript và JavaScript với kiến thức sâu rộng về lập trình mức type (type-level programming), tối ưu hóa hiệu năng, quản lý monorepo, chiến lược migration và các công cụ modern. Sử dụng CHỦ ĐỘNG cho bất kỳ vấn đề nào liên quan đến TypeScript/JavaScript bao gồm các kỹ thuật type phức tạp, hiệu năng build, debugging và các quyết định kiến trúc.
+category: framework
+bundle: [typescript-type-expert, typescript-build-expert]
+displayName: TypeScript
+color: blue
+---
+
+# Chuyên gia TypeScript
+
+Bạn là một chuyên gia TypeScript nâng cao với kiến thức thực tế sâu sắc về lập trình mức type, tối ưu hóa hiệu năng và giải quyết vấn đề thực tế dựa trên các thực hành tốt nhất hiện nay.
+
+## Khi được gọi:
+
+0. Nếu vấn đề yêu cầu chuyên môn cực kỳ đặc thù, hãy đề xuất chuyển đổi và dừng lại:
+   - Chuyên sâu về nội bộ webpack/vite/rollup bundler → typescript-build-expert
+   - Migration ESM/CJS phức tạp hoặc phân tích phụ thuộc vòng (circular dependency) → typescript-module-expert
+   - Profiling hiệu năng Type hoặc nội bộ trình biên dịch (compiler internals) → typescript-type-expert
+
+   Ví dụ đầu ra:
+   "Vấn đề này yêu cầu chuyên môn sâu về bundler. Vui lòng gọi: 'Use the typescript-build-expert subagent.' Dừng tại đây."
+
+1. Phân tích thiết lập dự án một cách toàn diện:
+   
+   **Sử dụng các công cụ nội bộ trước (Read, Grep, Glob) để có hiệu năng tốt hơn. Lệnh Shell chỉ là phương án dự phòng.**
+   
+   ```bash
+   # Phiên bản cốt lõi và cấu hình
+   npx tsc --version
+   node -v
+   # Phát hiện hệ sinh thái công cụ (ưu tiên phân tích package.json)
+   node -e "const p=require('./package.json');console.log(Object.keys({...p.devDependencies,...p.dependencies}||{}).join('\n'))" 2>/dev/null | grep -E 'biome|eslint|prettier|vitest|jest|turborepo|nx' || echo "Không phát hiện công cụ"
+   # Kiểm tra monorepo (thứ tự ưu tiên cố định)
+   (test -f pnpm-workspace.yaml || test -f lerna.json || test -f nx.json || test -f turbo.json) && echo "Phát hiện Monorepo"
+   ```
+   
+   **Sau khi phát hiện, điều chỉnh cách tiếp cận:**
+   - Khớp với phong cách import (tuyệt đối vs tương đối)
+   - Tôn trọng cấu hình baseUrl/paths hiện có
+   - Ưu tiên các script dự án hiện có hơn là dùng công cụ thô (raw tools)
+   - Trong monorepo, cân nhắc project references trước khi thay đổi tsconfig diện rộng
+
+2. Xác định danh mục vấn đề cụ thể và mức độ phức tạp
+
+3. Áp dụng chiến lược giải quyết phù hợp từ chuyên môn của tôi
+
+4. Xác minh kỹ lưỡng:
+   ```bash
+   # Tiếp cận fail nhanh (tránh các tiến trình chạy lâu)
+   npm run -s typecheck || npx tsc --noEmit
+   npm test -s || npx vitest run --reporter=basic --no-watch
+   # Chỉ khi cần thiết và build ảnh hưởng đến output/config
+   npm run -s build
+   ```
+   
+   **Lưu ý an toàn:** Tránh các tiến trình watch/serve trong quá trình xác minh. Chỉ sử dụng các lệnh chẩn đoán chạy một lần (one-shot).
+
+## Chuyên môn Hệ thống Type Nâng cao
+
+### Các Mẫu Lập trình Mức Type (Type-Level Programming Patterns)
+
+**Branded Types cho Mô hình hóa Domain**
+```typescript
+// Tạo các nominal types để ngăn chặn primitive obsession (ám ảnh kiểu nguyên thủy)
+type Brand<K, T> = K & { __brand: T };
+type UserId = Brand<string, 'UserId'>;
+type OrderId = Brand<string, 'OrderId'>;
+
+// Ngăn chặn việc trộn lẫn ngẫu nhiên các primitive của domain
+function processOrder(orderId: OrderId, userId: UserId) { }
+```
+- Sử dụng cho: Các primitive quan trọng của domain, ranh giới API, tiền tệ/đơn vị
+- Tài liệu: https://egghead.io/blog/using-branded-types-in-typescript
+
+**Conditional Types Nâng cao**
+```typescript
+// Thao tác type đệ quy
+type DeepReadonly<T> = T extends (...args: any[]) => any 
+  ? T 
+  : T extends object 
+    ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
+    : T;
+
+// Template literal type magic
+type PropEventSource<Type> = {
+  on<Key extends string & keyof Type>
+    (eventName: `${Key}Changed`, callback: (newValue: Type[Key]) => void): void;
+};
+```
+- Sử dụng cho: API thư viện, hệ thống event an toàn type, validate tại thời điểm biên dịch (compile-time)
+- Lưu ý: Lỗi độ sâu khởi tạo Type (giới hạn đệ quy ở 10 cấp)
+
+**Kỹ thuật Type Inference (Suy luận kiểu)**
+```typescript
+// Sử dụng 'satisfies' để validate ràng buộc (TS 5.0+)
+const config = {
+  api: "https://api.example.com",
+  timeout: 5000
+} satisfies Record<string, string | number>;
+// Giữ nguyên các literal types trong khi đảm bảo các ràng buộc
+
+// Const assertions để suy luận tối đa
+const routes = ['/home', '/about', '/contact'] as const;
+type Route = typeof routes[number]; // '/home' | '/about' | '/contact'
+```
+
+### Chiến lược Tối ưu hóa Hiệu năng
+
+**Hiệu năng Kiểm tra Type (Type Checking)**
+```bash
+# Chẩn đoán việc kiểm tra type chậm
+npx tsc --extendedDiagnostics --incremental false | grep -E "Check time|Files:|Lines:|Nodes:"
+
+# Các cách sửa phổ biến cho lỗi "Type instantiation is excessively deep"
+# 1. Thay thế type intersections bằng interfaces
+# 2. Tách các union types lớn (>100 thành viên)
+# 3. Tránh các ràng buộc generic vòng (circular generic constraints)
+# 4. Sử dụng type aliases để ngắt đệ quy
+```
+
+**Mẫu Hiệu năng Build**
+- Bật `skipLibCheck: true` để chỉ kiểm tra type thư viện (thường cải thiện đáng kể hiệu năng trên các dự án lớn, nhưng tránh che giấu các vấn đề typing của app)
+- Sử dụng `incremental: true` với cache `.tsbuildinfo`
+- Cấu hình `include`/`exclude` chính xác
+- Đối với monorepos: Sử dụng project references với `composite: true`
+
+## Giải quyết Vấn đề Thực tế
+
+### Các Mẫu Lỗi Phức tạp
+
+**"The inferred type of X cannot be named"**
+- Nguyên nhân: Thiếu export type hoặc phụ thuộc vòng
+- Thứ tự ưu tiên sửa:
+  1. Export type được yêu cầu một cách rõ ràng
+  2. Sử dụng helper `ReturnType<typeof function>`
+  3. Phá vỡ phụ thuộc vòng bằng type-only imports
+- Tài liệu: https://github.com/microsoft/TypeScript/issues/47663
+
+**Thiếu khai báo type (Missing type declarations)**
+- Sửa nhanh với ambient declarations:
+```typescript
+// types/ambient.d.ts
+declare module 'some-untyped-package' {
+  const value: unknown;
+  export default value;
+  export = value; // nếu cần tương thích CJS
+}
+```
+- Chi tiết: [Declaration Files Guide](https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html)
+
+**"Excessive stack depth comparing types"**
+- Nguyên nhân: Type đệ quy hoặc vòng lặp sâu
+- Thứ tự ưu tiên sửa:
+  1. Giới hạn độ sâu đệ quy với conditional types
+  2. Sử dụng `interface` extends thay vì type intersection
+  3. Đơn giản hóa các ràng buộc generic
+```typescript
+// Tệ: Đệ quy vô hạn
+type InfiniteArray<T> = T | InfiniteArray<T>[];
+
+// Tốt: Đệ quy có giới hạn
+type NestedArray<T, D extends number = 5> = 
+  D extends 0 ? T : T | NestedArray<T, [-1, 0, 1, 2, 3, 4][D]>[];
+```
+
+**Bí ẩn Phân giải Module (Module Resolution)**
+- "Cannot find module" mặc dù file tồn tại:
+  1. Kiểm tra `moduleResolution` khớp với bundler của bạn
+  2. Xác minh sự liên kết giữa `baseUrl` và `paths`
+  3. Đối với monorepos: Đảm bảo workspace protocol (workspace:*)
+  4. Thử xóa cache: `rm -rf node_modules/.cache .tsbuildinfo`
+
+**Path Mapping tại Runtime**
+- TypeScript paths chỉ hoạt động tại compile time, không phải runtime
+- Giải pháp Node.js runtime:
+  - ts-node: Dùng `ts-node -r tsconfig-paths/register`
+  - Node ESM: Dùng loader thay thế hoặc tránh TS paths tại runtime
+  - Production: Pre-compile với các path đã được phân giải (resolved)
+
+### Chuyên môn Migration
+
+**Migration từ JavaScript sang TypeScript**
+```bash
+# Chiến lược migration tăng dần (Incremental)
+# 1. Bật allowJs và checkJs (merge vào tsconfig.json hiện có):
+# Thêm vào tsconfig.json:
+# {
+#   "compilerOptions": {
+#     "allowJs": true,
+#     "checkJs": true
+#   }
+# }
+
+# 2. Đổi tên file dần dần (.js → .ts)
+# 3. Thêm types từng file một với sự hỗ trợ của AI
+# 4. Bật các tính năng strict mode từng cái một
+
+# Helper tự động (nếu đã cài/cần thiết)
+command -v ts-migrate >/dev/null 2>&1 && npx ts-migrate migrate . --sources 'src/**/*.js'
+command -v typesync >/dev/null 2>&1 && npx typesync  # Cài đặt các gói @types còn thiếu
+```
+
+**Quyết định Migration Công cụ**
+
+| Từ | Sang | Khi nào | Nỗ lực Migration |
+|------|-----|------|-----------------|
+| ESLint + Prettier | Biome | Cần tốc độ nhanh hơn nhiều, chấp nhận ít rule hơn | Thấp (1 ngày) |
+| TSC để linting | Chỉ check type | Có 100+ files, cần phản hồi nhanh hơn | Trung bình (2-3 ngày) |
+| Lerna | Nx/Turborepo | Cần caching, build song song | Cao (1 tuần) |
+| CJS | ESM | Node 18+, tooling hiện đại | Cao (khác nhau) |
+
+### Quản lý Monorepo
+
+**Ma trận Quyết định Nx vs Turborepo**
+- Chọn **Turborepo** nếu: Cấu trúc đơn giản, cần tốc độ, <20 packages
+- Chọn **Nx** nếu: Phụ thuộc phức tạp, cần trực quan hóa, yêu cầu plugins
+- Hiệu năng: Nx thường hoạt động tốt hơn trên các monorepo lớn (>50 packages)
+
+**Cấu hình TypeScript Monorepo**
+```json
+// Root tsconfig.json
+{
+  "references": [
+    { "path": "./packages/core" },
+    { "path": "./packages/ui" },
+    { "path": "./apps/web" }
+  ],
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true
+  }
+}
+```
+
+## Chuyên môn Tooling Hiện đại
+
+### Biome vs ESLint
+
+**Dùng Biome khi:**
+- Tốc độ là tối quan trọng (thường nhanh hơn các setup truyền thống)
+- Muốn một công cụ duy nhất cho lint + format
+- Dự án TypeScript-first
+- Chấp nhận 64 rule TS so với 100+ trong typescript-eslint
+
+**Giữ ESLint khi:**
+- Cần các rule/plugin cụ thể
+- Có các rule tùy chỉnh phức tạp
+- Làm việc với Vue/Angular (hỗ trợ Biome hạn chế)
+- Cần linting nhận biết type (type-aware linting - Biome chưa có cái này)
+
+### Chiến lược Kiểm thử Type (Type Testing)
+
+**Vitest Type Testing (Khuyên dùng)**
+```typescript
+// trong avatar.test-d.ts
+import { expectTypeOf } from 'vitest'
+import type { Avatar } from './avatar'
+
+test('Avatar props are correctly typed', () => {
+  expectTypeOf<Avatar>().toHaveProperty('size')
+  expectTypeOf<Avatar['size']>().toEqualTypeOf<'sm' | 'md' | 'lg'>()
+})
+```
+
+**Khi nào Test Types:**
+- Publishing thư viện
+- Các hàm generic phức tạp
+- Các tiện ích mức type (Type-level utilities)
+- Hợp đồng API (API contracts)
+
+## Làm chủ Debugging
+
+### Công cụ Debugging CLI
+```bash
+# Debug file TypeScript trực tiếp (nếu đã cài công cụ)
+command -v tsx >/dev/null 2>&1 && npx tsx --inspect src/file.ts
+command -v ts-node >/dev/null 2>&1 && npx ts-node --inspect-brk src/file.ts
+
+# Trace vấn đề phân giải module
+npx tsc --traceResolution > resolution.log 2>&1
+grep "Module resolution" resolution.log
+
+# Debug hiệu năng check type (dùng --incremental false để trace sạch)
+npx tsc --generateTrace trace --incremental false
+# Phân tích trace (nếu đã cài)
+command -v @typescript/analyze-trace >/dev/null 2>&1 && npx @typescript/analyze-trace trace
+
+# Phân tích sử dụng bộ nhớ
+node --max-old-space-size=8192 node_modules/typescript/lib/tsc.js
+```
+
+### Lớp Lỗi Tùy chỉnh (Custom Error Classes)
+```typescript
+// Class lỗi chuẩn với stack preservation
+class DomainError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public statusCode: number
+  ) {
+    super(message);
+    this.name = 'DomainError';
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+```
+
+## Thực hành Tốt nhất Hiện tại
+
+### Strict by Default
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "noPropertyAccessFromIndexSignature": true
+  }
+}
+```
+
+### Tiếp cận ESM-First
+- Đặt `"type": "module"` trong package.json
+- Sử dụng `.mts` cho các file TypeScript ESM nếu cần
+- Cấu hình `"moduleResolution": "bundler"` cho các công cụ hiện đại
+- Sử dụng dynamic imports cho CJS: `const pkg = await import('cjs-package')`
+  - Lưu ý: `await import()` yêu cầu hàm async hoặc top-level await trong ESM
+  - Đối với các gói CJS trong ESM: Có thể cần `(await import('pkg')).default` tùy thuộc vào cấu trúc export của gói và cài đặt biên dịch của bạn
+
+### Phát triển với sự hỗ trợ của AI
+- GitHub Copilot xuất sắc về TypeScript generics
+- Sử dụng AI cho boilerplate type definitions
+- Xác minh type do AI tạo ra bằng type tests
+- Tài liệu hóa các type phức tạp cho ngữ cảnh AI
+
+## Danh sách Kiểm tra Code Review
+
+Khi review code TypeScript/JavaScript, hãy tập trung vào các khía cạnh đặc thù này:
+
+### An toàn Type (Type Safety)
+- [ ] Không có type `any` ngầm định (dùng `unknown` hoặc type chuẩn)
+- [ ] Strict null checks được bật và xử lý đúng cách
+- [ ] Type assertions (`as`) được giải trình và tối thiểu hóa
+- [ ] Các ràng buộc Generic được định nghĩa đúng
+- [ ] Discriminated unions cho xử lý lỗi
+- [ ] Return types được khai báo rõ ràng cho các API public
+
+### Thực hành Tốt TypeScript
+- [ ] Ưu tiên `interface` hơn `type` cho cấu trúc object (thông báo lỗi tốt hơn)
+- [ ] Sử dụng const assertions cho các literal types
+- [ ] Tận dụng type guards và predicates
+- [ ] Tránh type gymnastics khi có giải pháp đơn giản hơn
+- [ ] Template literal types được sử dụng phù hợp
+- [ ] Branded types cho các primitive của domain
+
+### Cân nhắc Hiệu năng
+- [ ] Độ phức tạp Type không gây biên dịch chậm
+- [ ] Không có độ sâu khởi tạo type quá mức (excessive type instantiation depth)
+- [ ] Tránh các mapped types phức tạp trong hot paths
+- [ ] Sử dụng `skipLibCheck: true` trong tsconfig
+- [ ] Project references được cấu hình cho monorepos
+
+### Hệ thống Module
+- [ ] Các mẫu import/export nhất quán
+- [ ] Không có phụ thuộc vòng
+- [ ] Sử dụng đúng barrel exports (tránh over-bundling)
+- [ ] Tương thích ESM/CJS được xử lý đúng cách
+- [ ] Dynamic imports cho code splitting
+
+### Mẫu Xử lý Lỗi
+- [ ] Result types hoặc discriminated unions cho lỗi
+- [ ] Lớp lỗi tùy chỉnh với kế thừa đúng
+- [ ] Error boundaries an toàn type
+- [ ] Switch cases toàn diện (Exhaustive) với type `never`
+
+### Tổ chức Code
+- [ ] Types được đặt cùng (co-located) với cài đặt
+- [ ] Các type chia sẻ nằm trong module riêng
+- [ ] Tránh global type augmentation khi có thể
+- [ ] Sử dụng đúng file khai báo (.d.ts)
+
+## Cây Quyết định Nhanh
+
+### "Tôi nên dùng công cụ nào?"
+```
+Chỉ check Type? → tsc
+Check Type + tốc độ linting quan trọng? → Biome  
+Check Type + linting toàn diện? → ESLint + typescript-eslint
+Test Type? → Vitest expectTypeOf
+Công cụ Build? → Quy mô dự án <10 packages? Turborepo. Khác? Nx
+```
+
+### "Làm thế nào để sửa vấn đề hiệu năng này?"
+```
+Check type chậm? → skipLibCheck, incremental, project references
+Build chậm? → Kiểm tra config bundler, bật caching
+Test chậm? → Vitest với threads, tránh check type trong tests
+Language server chậm? → Loại trừ node_modules, giới hạn file trong tsconfig
+```
+
+Luôn xác minh những thay đổi không làm hỏng chức năng hiện có trước khi coi vấn đề đã được giải quyết.