From a16b57e581ddae2d05d7e24cb8f6cd2cdd7928c1 Mon Sep 17 00:00:00 2001 From: sck_0 Date: Wed, 28 Jan 2026 18:01:08 +0100 Subject: [PATCH 01/10] docs: restructure translation formatting - moving all localized content to docs/vietnamese --- .github/MAINTENANCE.md | 6 +- CHANGELOG.md | 4 +- README.md | 30 +- FAQ.md => docs/FAQ.md | 8 +- GETTING_STARTED.md => docs/GETTING_STARTED.md | 14 +- docs/VISUAL_GUIDE.md | 8 +- docs/vi/BUNDLES.md | 148 ---- docs/vi/CONTRIBUTING.md | 239 ------ docs/vi/EXAMPLES.md | 56 -- docs/vi/FAQ.md | 178 ----- docs/vi/GETTING_STARTED.md | 110 --- docs/vi/README.md | 479 ------------ docs/vi/SOURCES.md | 21 - docs/vietnamese/BUNDLES.md | 124 ++++ docs/vietnamese/CONTRIBUTING.md | 236 ++++++ docs/vietnamese/EXAMPLES.md | 56 ++ docs/vietnamese/FAQ.md | 178 +++++ docs/vietnamese/GETTING_STARTED.md | 108 +++ docs/vietnamese/QUALITY_BAR.md | 64 ++ docs/vietnamese/README.md | 254 +++++++ docs/vietnamese/SECURITY_GUARDRAILS.md | 51 ++ docs/vietnamese/SKILL_ANATOMY.md | 605 +++++++++++++++ docs/vietnamese/SOURCES.md | 21 + docs/{vi => vietnamese}/VISUAL_GUIDE.md | 340 +++++---- docs/vietnamese/skills/architecture/SKILL.md | 55 ++ .../skills/concise-planning/SKILL.md | 62 ++ docs/vietnamese/skills/git-pushing/SKILL.md | 33 + docs/vietnamese/skills/kaizen/SKILL.md | 700 ++++++++++++++++++ .../skills/lint-and-validate/SKILL.md | 44 ++ .../skills/senior-architect/SKILL.md | 209 ++++++ skills/README.md | 6 +- 31 files changed, 3024 insertions(+), 1423 deletions(-) rename FAQ.md => docs/FAQ.md (94%) rename GETTING_STARTED.md => docs/GETTING_STARTED.md (89%) delete mode 100644 docs/vi/BUNDLES.md delete mode 100644 docs/vi/CONTRIBUTING.md delete mode 100644 docs/vi/EXAMPLES.md delete mode 100644 docs/vi/FAQ.md delete mode 100644 docs/vi/GETTING_STARTED.md delete mode 100644 docs/vi/README.md delete mode 100644 docs/vi/SOURCES.md create mode 100644 docs/vietnamese/BUNDLES.md create mode 100644 docs/vietnamese/CONTRIBUTING.md create mode 100644 docs/vietnamese/EXAMPLES.md create mode 100644 docs/vietnamese/FAQ.md create mode 100644 docs/vietnamese/GETTING_STARTED.md create mode 100644 docs/vietnamese/QUALITY_BAR.md create mode 100644 docs/vietnamese/README.md create mode 100644 docs/vietnamese/SECURITY_GUARDRAILS.md create mode 100644 docs/vietnamese/SKILL_ANATOMY.md create mode 100644 docs/vietnamese/SOURCES.md rename docs/{vi => vietnamese}/VISUAL_GUIDE.md (62%) create mode 100644 docs/vietnamese/skills/architecture/SKILL.md create mode 100644 docs/vietnamese/skills/concise-planning/SKILL.md create mode 100644 docs/vietnamese/skills/git-pushing/SKILL.md create mode 100644 docs/vietnamese/skills/kaizen/SKILL.md create mode 100644 docs/vietnamese/skills/lint-and-validate/SKILL.md create mode 100644 docs/vietnamese/skills/senior-architect/SKILL.md diff --git a/.github/MAINTENANCE.md b/.github/MAINTENANCE.md index f8da9d22..7eadfef1 100644 --- a/.github/MAINTENANCE.md +++ b/.github/MAINTENANCE.md @@ -124,8 +124,8 @@ GitHub's anchor generation breaks if headers have emojis. If you update installation instructions or tool compatibility, you MUST update all 3 files: 1. `README.md` (Source of Truth) -2. `GETTING_STARTED.md` (Beginner Guide) -3. `FAQ.md` (Troubleshooting) +2. `docs/GETTING_STARTED.md` (Beginner Guide) +3. `docs/FAQ.md` (Troubleshooting) _Common pitfall: Updating the clone URL in README but leaving an old one in FAQ._ @@ -138,7 +138,7 @@ Locations to check: 1. **Title of `README.md`**: "356+ Agentic Skills..." 2. **`## Full Skill Registry (356/356)` header**. -3. **`GETTING_STARTED.md` intro**. +3. **`docs/GETTING_STARTED.md` intro**. ### D. Credits Policy (Who goes where?) diff --git a/CHANGELOG.md b/CHANGELOG.md index 118d9986..1c7d6069 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -99,7 +99,7 @@ The following skills are now correctly indexed and visible in the registry: ### Changed - **Documentation**: Added `docs/CI_DRIFT_FIX.md` as a canonical reference for resolving drift issues. -- **Guidance**: Updated `GETTING_STARTED.md` counts to match the full registry (253+ skills). +- **Guidance**: Updated `docs/GETTING_STARTED.md` counts to match the full registry (253+ skills). - **Maintenance**: Updated `MAINTENANCE.md` with strict protocols for handling generated files. ## [3.0.0] - 2026-01-25 - "The Governance Update" @@ -259,7 +259,7 @@ The following skills are now correctly indexed and visible in the registry: - `cc-skill-project-guidelines-example` - `cc-skill-security-review` - `cc-skill-strategic-compact` -- **Documentation**: New `WALKTHROUGH.md` for import process details. +- **Documentation**: New `docs/WALKTHROUGH.md` for import process details. ### Changed diff --git a/README.md b/README.md index 5c7d7581..ca4c0f25 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# 🌌 Antigravity Awesome Skills: 257+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Copilot & More +# 🌌 Antigravity Awesome Skills: 552+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Copilot & More -> **The Ultimate Collection of 257+ Universal Agentic Skills for AI Coding Assistants — Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode** +> **The Ultimate Collection of 552+ Universal Agentic Skills for AI Coding Assistants — Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode** [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Claude Code](https://img.shields.io/badge/Claude%20Code-Anthropic-purple)](https://claude.ai) @@ -11,7 +11,7 @@ [![OpenCode](https://img.shields.io/badge/OpenCode-CLI-gray)](https://github.com/opencode-ai/opencode) [![Antigravity](https://img.shields.io/badge/Antigravity-DeepMind-red)](https://github.com/sickn33/antigravity-awesome-skills) -**Antigravity Awesome Skills** is a curated, battle-tested library of **257 high-performance agentic skills** designed to work seamlessly across all major AI coding assistants: +**Antigravity Awesome Skills** is a curated, battle-tested library of **552 high-performance agentic skills** designed to work seamlessly across all major AI coding assistants: - 🟣 **Claude Code** (Anthropic CLI) - 🔵 **Gemini CLI** (Google DeepMind) @@ -29,7 +29,7 @@ This repository provides essential skills to transform your AI assistant into a - [🔌 Compatibility & Invocation](#compatibility--invocation) - [📦 Features & Categories](#features--categories) - [🎁 Curated Collections (Bundles)](#curated-collections) -- [📚 Browse 550+ Skills](#browse-550-skills) +- [📚 Browse 552+ Skills](#browse-552-skills) - [🛠️ Installation](#installation) - [🤝 How to Contribute](#how-to-contribute) - [👥 Contributors & Credits](#credits--sources) @@ -52,7 +52,7 @@ AI Agents (like Claude Code, Cursor, or Gemini) are smart, but they lack **speci ### 2. ⚡️ Quick Start (The "Bundle" Way) -Don't install 250+ skills manually. Use our **Starter Packs**: +Don't install 552+ skills manually. Use our **Starter Packs**: 1. **Clone the repo**: ```bash @@ -70,7 +70,7 @@ Once installed, just ask your agent naturally: > "Use the **@brainstorming** skill to help me plan a SaaS." > "Run **@lint-and-validate** on this file." -👉 **[Read the Full Getting Started Guide](GETTING_STARTED.md)** +👉 **[Read the Full Getting Started Guide](docs/GETTING_STARTED.md)** --- @@ -104,17 +104,23 @@ This repository aggregates the best capabilities from across the open-source com The repository is organized into specialized domains to transform your AI into an expert across the entire software development lifecycle: -- **Engineering & Architecture**: 50+ skills for Backend, Frontend, DevOps, and System Design including `backend-architect`, `c4-architecture`, and `kubernetes-architect`. -- **AI & Data**: 80+ skills covering LLMs, RAG, Agents (LangChain/CrewAI), and Data Engineering. -- **Security**: 30+ skills for Penetration Testing, Code Auditing, and Security Compliance. -- **Product & Business**: 35+ skills for Startup Analytics, Marketing Strategy, and SEO. -- **Development**: 70+ skills for Python, TypeScript/JavaScript, Rust, Go, and more. +| Category | Focus | Example skills | +| :--- | :--- | :--- | +| Architecture (52) | System design, ADRs, C4, and scalable patterns | `architecture`, `c4-context`, `senior-architect` | +| Business (35) | Growth, pricing, CRO, SEO, and go-to-market | `copywriting`, `pricing-strategy`, `seo-audit` | +| Data & AI (81) | LLM apps, RAG, agents, observability, analytics | `rag-engineer`, `prompt-engineer`, `langgraph` | +| Development (72) | Language mastery, framework patterns, code quality | `typescript-expert`, `python-patterns`, `react-patterns` | +| General (95) | Planning, docs, product ops, writing, guidelines | `brainstorming`, `doc-coauthoring`, `writing-plans` | +| Infrastructure (72) | DevOps, cloud, serverless, deployment, CI/CD | `docker-expert`, `aws-serverless`, `vercel-deployment` | +| Security (107) | AppSec, pentesting, vuln analysis, compliance | `api-security-best-practices`, `sql-injection-testing`, `vulnerability-scanner` | +| Testing (21) | TDD, test design, fixes, QA workflows | `test-driven-development`, `testing-patterns`, `test-fixing` | +| Workflow (17) | Automation, orchestration, jobs, agents | `workflow-automation`, `inngest`, `trigger-dev` | ## Curated Collections [Check out our Starter Packs in docs/BUNDLES.md](docs/BUNDLES.md) to find the perfect toolkit for your role. -## Browse 550+ Skills +## Browse 552+ Skills We have moved the full skill registry to a dedicated catalog to keep this README clean. diff --git a/FAQ.md b/docs/FAQ.md similarity index 94% rename from FAQ.md rename to docs/FAQ.md index 8652a6d8..ec8ba0e3 100644 --- a/FAQ.md +++ b/docs/FAQ.md @@ -11,11 +11,11 @@ Skills are specialized instruction files that teach AI assistants how to handle specific tasks. Think of them as expert knowledge modules that your AI can load on-demand. **Simple analogy:** Just like you might consult different experts (a lawyer, a doctor, a mechanic), these skills let your AI become an expert in different areas when you need them. -### Do I need to install all 256+ skills? +### Do I need to install all 552+ skills? **No!** When you clone the repository, all skills are available, but your AI only loads them when you explicitly invoke them with `@skill-name`. It's like having a library - all books are there, but you only read the ones you need. -**Pro Tip:** Use [Starter Packs](docs/BUNDLES.md) to install only what matches your role. +**Pro Tip:** Use [Starter Packs](BUNDLES.md) to install only what matches your role. ### Which AI tools work with these skills? @@ -116,7 +116,7 @@ Use the `@` symbol followed by the skill name: ### How do I know which skill to use? -1. **Browse the README**: Check the [Full Skill Registry](README.md#full-skill-registry-256256). +1. **Browse the catalog**: Check the [Skill Catalog](../CATALOG.md). 2. **Search**: `ls skills/ | grep "keyword"` 3. **Ask your AI**: "What skills do you have for testing?" @@ -152,7 +152,7 @@ Include: - Fix typos - Add examples - Improve docs - Check out [CONTRIBUTING.md](CONTRIBUTING.md) for instructions. + Check out [CONTRIBUTING.md](../CONTRIBUTING.md) for instructions. ### My PR failed "Quality Bar" check. Why? diff --git a/GETTING_STARTED.md b/docs/GETTING_STARTED.md similarity index 89% rename from GETTING_STARTED.md rename to docs/GETTING_STARTED.md index 07156c62..c401bf7f 100644 --- a/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -15,7 +15,7 @@ AI Agents (like **Claude Code**, **Gemini**, **Cursor**) are smart, but they lac ## ⚡️ Quick Start: The "Starter Packs" -Don't panic about the 256+ skills. You don't need them all at once. +Don't panic about the 552+ skills. You don't need them all at once. We have curated **Starter Packs** to get you running immediately. ### 1. Install the Repo @@ -29,7 +29,7 @@ git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skill ### 2. Pick Your Persona -Find the bundle that matches your role (see [docs/BUNDLES.md](docs/BUNDLES.md)): +Find the bundle that matches your role (see [BUNDLES.md](BUNDLES.md)): | Persona | Bundle Name | What's Inside? | | :-------------------- | :------------- | :------------------------------------------------ | @@ -84,13 +84,13 @@ We classify skills so you know what you're running: - 🔵 **Safe**: Community skills that are non-destructive (Read-only/Planning). - 🔴 **Risk**: Skills that modify systems or perform security tests (Authorized Use Only). -_Check the [Full Registry](README.md#full-skill-registry-256256) for risk labels._ +_Check the [Skill Catalog](../CATALOG.md) for the full list._ --- ## ❓ FAQ -**Q: Do I need to install all 250 skills?** +**Q: Do I need to install all 552 skills?** A: You clone the whole repo, but your AI only _reads_ the ones you ask for (or that are relevant). It's lightweight! **Q: Can I make my own skills?** @@ -103,6 +103,6 @@ A: Yes, MIT License. Open Source forever. ## ⏭️ Next Steps -1. [Browse the Bundles](docs/BUNDLES.md) -2. [See Real-World Examples](docs/EXAMPLES.md) -3. [Contribute a Skill](CONTRIBUTING.md) +1. [Browse the Bundles](BUNDLES.md) +2. [See Real-World Examples](EXAMPLES.md) +3. [Contribute a Skill](../CONTRIBUTING.md) diff --git a/docs/VISUAL_GUIDE.md b/docs/VISUAL_GUIDE.md index 0957a715..3fc6864a 100644 --- a/docs/VISUAL_GUIDE.md +++ b/docs/VISUAL_GUIDE.md @@ -31,9 +31,7 @@ antigravity-awesome-skills/ │ ├── 📄 README.md ← Overview & skill list -├── 📄 GETTING_STARTED.md ← Start here! (NEW) ├── 📄 CONTRIBUTING.md ← How to contribute -├── 📄 FAQ.md ← Troubleshooting │ ├── 📁 skills/ ← All 250+ skills live here │ │ @@ -54,6 +52,8 @@ antigravity-awesome-skills/ │ └── 📄 MAINTENANCE.md ← Maintainers Guide │ └── 📁 docs/ ← Documentation + ├── 📄 GETTING_STARTED.md ← Start here! (NEW) + ├── 📄 FAQ.md ← Troubleshooting ├── 📄 BUNDLES.md ← Starter Packs (NEW) ├── 📄 QUALITY_BAR.md ← Quality Standards ├── 📄 SKILL_ANATOMY.md ← How skills work @@ -456,7 +456,7 @@ START HERE │ 5. Submit PR │ │ │ │ 🆘 HELP │ -│ • GETTING_STARTED.md - Basics │ +│ • docs/GETTING_STARTED.md - Basics │ │ • CONTRIBUTING.md - How to contribute │ │ • SKILL_ANATOMY.md - Deep dive │ │ • GitHub Issues - Ask questions │ @@ -505,7 +505,7 @@ Month 1: Regular contributor **Visual learner?** This guide should help! Still have questions? Check out: -- [GETTING_STARTED.md](../GETTING_STARTED.md) - Text-based intro +- [GETTING_STARTED.md](GETTING_STARTED.md) - Text-based intro - [SKILL_ANATOMY.md](SKILL_ANATOMY.md) - Detailed breakdown - [CONTRIBUTING.md](../CONTRIBUTING.md) - How to contribute diff --git a/docs/vi/BUNDLES.md b/docs/vi/BUNDLES.md deleted file mode 100644 index 95b8ae6c..00000000 --- a/docs/vi/BUNDLES.md +++ /dev/null @@ -1,148 +0,0 @@ -# 📦 Các Gói Skill Của Antigravity (Bundles) - -Không biết bắt đầu từ đâu? Đừng lo. Hãy chọn ngay một gói (Bundle) bên dưới để sở hữu bộ kỹ năng "trấn phái" phù hợp nhất với vai trò của bạn. - ---- - -## 🚀 Gói "Cơ Bản" (The Essentials Starter Pack) - -_Dành cho tất cả mọi người. Mới nhập môn thì cài bộ này trước._ - -- `concise-planning`: Luôn bắt đầu mọi việc bằng một kế hoạch ngắn gọn. -- `lint-and-validate`: Tự động giữ cho code sạch đẹp. -- `git-pushing`: Lưu trữ kết quả làm việc an toàn lên Git. -- `kaizen`: Tư duy cải tiến liên tục (nhỏ nhưng đều đặn). - ---- - -## 🛡️ Gói "Kỹ Sư Bảo Mật" (The Security Engineer Pack) - -_Dành cho pentester, chuyên gia audit và hacker mũ trắng._ - -- `ethical-hacking-methodology`: Cuốn "Kinh Thánh" về ethical hacking. -- `burp-suite-testing`: Quét lỗ hổng bảo mật Web. -- `owasp-top-10`: Kiểm tra nhanh các lỗi bảo mật phổ biến nhất. -- `linux-privilege-escalation`: Đánh giá bảo mật nâng cao cho Linux. -- `cloud-penetration-testing`: Bảo mật đám mây AWS/Azure/GCP. - ---- - -## 🌐 Gói "Phù Thủy Web" (The Web Wizard Pack) - -_Dành cho anh em Dev xây dựng các web app hiện đại, hiệu năng cao._ - -- `frontend-design`: Hướng dẫn về thẩm mỹ và nguyên tắc UI. -- `react-patterns`: Các bài thực hành tốt nhất (best practices) cho React. -- `tailwind-mastery`: Làm chủ CSS siêu tốc. -- `form-cro`: Tối ưu hóa các biểu mẫu (form) để tăng tỷ lệ chuyển đổi. -- `seo-audit`: Giúp web của bạn lên top Google. - ---- - -## 🤖 Gói "Kiến Trúc Sư AI" (The Agent Architect Pack) - -_Dành cho người xây dựng hệ thống AI._ - -- `agent-evaluation`: Kiểm thử và đánh giá Agent của bạn. -- `langgraph`: Xây dựng các luồng agent có trạng thái (stateful). -- `mcp-builder`: Tự chế tạo công cụ (tools) riêng cho AI. -- `prompt-engineering`: Làm chủ nghệ thuật ra lệnh cho LLM. - ---- - -## 🎮 Gói "Làm Game Indie" (The Indie Game Dev Pack) - -_Dành cho người làm game với sự trợ giúp của AI._ - -- `game-development/game-design`: Cơ chế và vòng lặp game (game loops). -- `game-development/2d-games`: Sprites và vật lý 2D. -- `game-development/3d-games`: Mô hình và đổ bóng (shaders) 3D. -- `game-development/unity-csharp`: Làm chủ C# scripting trong Unity. -- `algorithmic-art`: Tạo tài nguyên game bằng code nghệ thuật. - ---- - -## 🐍 Gói "Trùm Python" (The Python Pro Pack) - -_Dành cho đội Backend và khoa học dữ liệu._ - -- `python-patterns`: Viết code Python chuẩn chỉ (idiomatic). -- `poetry-manager`: Quản lý thư viện phụ thuộc (dependency) "không đau đầu". -- `pytest-mastery`: Làm chủ các framework kiểm thử. -- `fastapi-expert`: Xây dựng API hiệu năng cao. -- `django-guide`: Framework "pin trâu" cho mọi tính năng (batteries-included). - ---- - -## 🦄 Gói "Khởi Nghiệp" (The Startup Founder Pack) - -_Dành cho người xây sản phẩm, không chỉ mỗi code._ - -- `product-requirements-doc`: Định nghĩa rõ những gì cần làm. -- `competitor-analysis`: Biết người biết ta, trăm trận trăm thắng. -- `pitch-deck-creator`: Gọi vốn (hoặc đơn giản là trình bày ý tưởng). -- `landing-page-copy`: Viết nội dung bán hàng "đi vào lòng người". -- `stripe-integration`: Tích hợp thanh toán để lụm tiền. - ---- - -## 🌧️ Gói "DevOps & Cloud" (The DevOps Pack) - -_Dành cho người lo hạ tầng và mở rộng hệ thống._ - -- `docker-expert`: Bậc thầy về container. -- `aws-serverless`: Triển khai không máy chủ trên AWS (Lambda, DynamoDB). -- `environment-setup-guide`: Chuẩn hóa môi trường cho cả team. -- `deployment-procedures`: Chiến lược rollout an toàn. -- `bash-linux`: Phù thủy dòng lệnh Terminal. - ---- - -## 📊 Gói "Dữ Liệu & Phân Tích" (The Data Pack) - -_Dành cho người thích các con số._ - -- `analytics-tracking`: Cài đặt GA4/PostHog chuẩn ngay từ đầu. -- `d3-viz`: Vẽ biểu đồ tùy chỉnh tuyệt đẹp. -- `sql-mastery`: Viết câu truy vấn (query) tối ưu. -- `ab-test-setup`: Học hỏi dựa trên dữ liệu thực tế. - ---- - -## 🎨 Gói "Giám Đốc Sáng Tạo" (The Creative Director Pack) - -_Dành cho hình ảnh, nội dung và thương hiệu._ - -- `canvas-design`: Tạo poster và sơ đồ. -- `frontend-design`: Thẩm mỹ giao diện. -- `content-creator`: Viết blog chuẩn SEO. -- `copy-editing`: Chuốt lại câu từ cho mượt. -- `algorithmic-art`: Tạo kiệt tác bằng code. - ---- - -## 🐞 Gói "Kiểm Thử & QA" (The QA & Testing Pack) - -_Dành cho người "đập phá" trước khi người dùng kịp làm._ - -- `test-driven-development`: Quy trình Đỏ, Xanh, Refactor. -- `systematic-debugging`: Thám tử Sherlock Holmes trong làng code. -- `browser-automation`: Test toàn trình (E2E) với Playwright. -- `ab-test-setup`: Thử nghiệm có kiểm chứng. -- `code-review-checklist`: Bắt lỗi ngay trong Pull Request. - ---- - -## 🖌️ Gói "Thiết Kế Web" (The Web Designer Pack) - -_Dành cho trải nghiệm điểm ảnh hoàn hảo (pixel-perfect)._ - -- `ui-ux-pro-max`: Hệ thống thiết kế (Design systems) cao cấp. -- `frontend-design`: Nền tảng của cái đẹp. -- `3d-web-experience`: Ma thuật với Three.js & R3F. -- `canvas-design`: Hình ảnh tĩnh/poster. -- `responsive-layout`: Nguyên tắc "Mobile-first" (Di động trước tiên). - ---- - -_Để sử dụng một gói, bạn chỉ cần copy tên các skill vào thư mục `.agent/skills` hoặc gọi chúng trực tiếp với agent của bạn nhé._ diff --git a/docs/vi/CONTRIBUTING.md b/docs/vi/CONTRIBUTING.md deleted file mode 100644 index 8a655210..00000000 --- a/docs/vi/CONTRIBUTING.md +++ /dev/null @@ -1,239 +0,0 @@ -# 🤝 Hướng Dẫn Đóng Góp - V3 Enterprise Edition - -[Đọc bản gốc tiếng Anh](./CONTRIBUTING.md) - -**Cảm ơn bạn đã quan tâm và muốn đóng góp cho dự án!** -Tài liệu này sẽ hướng dẫn bạn quy trình đóng góp một cách cụ thể, ngay cả khi bạn chưa từng tham gia dự án mã nguồn mở nào. -Trong phiên bản V3, chúng tôi đặt ra tiêu chuẩn chất lượng cao hơn. Vui lòng đọc kỹ phần **Tiêu Chuẩn Chất Lượng Mới** bên dưới. - ---- - -## 🧐 "Thước Đo Chất Lượng" (Tiêu Chuẩn V3) - -**Lưu ý quan trọng cho Skill mới:** Mọi skill được gửi lên đều phải vượt qua **Quy Trình Kiểm Tra 5 Điểm** (xem chi tiết tại `docs/QUALITY_BAR.md`): - -1. **Metadata (Siêu dữ liệu)**: Khai báo Frontmatter chính xác (gồm `name`, `description`). -2. **Safety (An toàn)**: Tuyệt đối không chứa lệnh gây nguy hiểm nếu không gắn nhãn "Risk". -3. **Clarity (Rõ ràng)**: Mục "When to use" (Khi nào sử dụng) phải được mô tả cụ thể, dễ hiểu. -4. **Examples (Ví dụ)**: Phải cung cấp ít nhất một ví dụ thực tế có thể copy-paste và chạy được ngay. -5. **Actions (Hành động)**: Phải đưa ra các bước thực hiện cụ thể, tránh nói chung chung kiểu "hãy suy nghĩ về...". - ---- - -## Các Cách Đóng Góp - -Bạn không cần phải là chuyên gia mới có thể đóng góp! Dưới đây là những việc mà bất kỳ ai cũng có thể làm để hỗ trợ dự án: - -### 1. Cải Thiện Tài Liệu (Dễ nhất!) - -- Sửa lỗi chính tả, ngữ pháp. -- Viết lại các đoạn hướng dẫn cho dễ hiểu hơn. -- Bổ sung ví dụ minh họa cho các skill hiện có. -- Dịch tài liệu sang ngôn ngữ khác (Như bản dịch tiếng Việt này chẳng hạn!). - -### 2. Báo Cáo Vấn Đề (Issues) - -- Thấy chỗ nào khó hiểu? Hãy phản hồi cho chúng tôi! -- Skill chạy không đúng? Hãy báo lỗi ngay! -- Có ý tưởng hay ho? Chúng tôi rất muốn lắng nghe! - -### 3. Tạo Skill Mới - -- Đóng gói kiến thức chuyên môn của bạn thành một skill. -- Bổ sung những mảng kiến thức còn thiếu trong kho tàng skill hiện tại. -- Nâng cấp và cải thiện các skill đã có. - -### 4. Kiểm Tra và Xác Thực - -- Chạy thử các skill và báo cáo kết quả (cái nào ổn, cái nào lỗi). -- Test trên nhiều công cụ AI khác nhau (Claude, ChatGPT, Gemini...). -- Đề xuất các cải tiến về hiệu năng hoặc trải nghiệm. - ---- - -## Quy Trình Tạo Một Skill Mới - -### Hướng Dẫn Từng Bước - -#### Bước 1: Chọn Chủ Đề - -Hãy tự hỏi: "Mình ước gì con AI của mình biết rành rẽ về cái gì nhỉ?". -Ví dụ: "Mình thạo Docker, để mình viết một skill dạy nó dùng Docker cho chuẩn". - -#### Bước 2: Tạo Cấu Trúc Thư Mục - -Tất cả skill nằm trong thư mục `skills/`. Hãy đặt tên thư mục theo kiểu `kebab-case` (chữ thường, nối bằng gạch ngang). - -```bash -# Vào thư mục skills -cd skills/ - -# Tạo thư mục cho skill mới -mkdir my-awesome-skill -cd my-awesome-skill - -# Tạo file nội dung SKILL.md -touch SKILL.md -``` - -#### Bước 3: Viết Nội Dung SKILL.md - -Mọi skill đều phải tuân theo cấu trúc cơ bản sau. **Hãy copy mẫu này để bắt đầu:** - -```markdown ---- -name: my-awesome-skill -description: "Mô tả ngắn gọn (1 dòng) về công dụng của skill này" ---- - -# Tên Skill - -## Tổng Quan - -Giải thích skill này dùng để làm gì và bối cảnh sử dụng. - -## Khi Nào Nên Dùng (When to Use) - -- Dùng khi [trường hợp 1] -- Dùng khi [trường hợp 2] - -## Cách Hoạt Động - -Hướng dẫn từng bước chi tiết để AI làm theo... - -## Ví Dụ Minh Họa - -### Ví Dụ 1 - -\`\`\` -code example here -\`\`\` - -## Lưu Ý / Best Practices - -- ✅ Nên làm: ... -- ❌ Tránh làm: ... -``` - -#### Bước 4: Kiểm Tra (QUAN TRỌNG VỚI V3) - -Chạy script kiểm tra (validation) trên máy của bạn. **Chúng tôi sẽ không merge các PR nếu chưa qua bước này.** - -```bash -# Chế độ thường (chỉ hiện cảnh báo) -python3 scripts/validate_skills.py - -# Chế độ nghiêm ngặt (giống hệ thống CI) -python3 scripts/validate_skills.py --strict -``` - -Script này sẽ check: - -- ✅ File `SKILL.md` đã có chưa? -- ✅ Frontmatter khai báo đúng chưa? -- ✅ Tên skill có khớp với tên thư mục không? -- ✅ Có đạt chuẩn chất lượng (Quality Bar) không? - -#### Bước 5: Gửi Skill (Pull Request) - -```bash -git add skills/my-awesome-skill/ -git commit -m "feat: add my-awesome-skill" -git push origin my-branch -``` - ---- - -## Mẫu Template Chuẩn (Copy & Paste) - -Để tiết kiệm thời gian, bạn hãy dùng mẫu đầy đủ này: - -```markdown ---- -name: your-skill-name -description: "Mô tả ngắn gọn công dụng và thời điểm dùng skill này" ---- - -# Tên Skill - -## Tổng Quan - -[2-3 câu giới thiệu ngắn gọn về chức năng của skill] - -## Khi Nào Nên Dùng - -- Khi bạn cần [làm việc A] -- Khi bạn muốn [đạt kết quả B] - -## Hướng Dẫn Chi Tiết - -### 1. [Bước đầu tiên] - -[Mô tả các thực hiện] - -## Ví Dụ - -### Ví Dụ 1: [Tên trường hợp cụ thể] - -\`\`\`language -// Code mẫu -\`\`\` - -## Best Practices - -- ✅ **Nên:** [Thói quen tốt] -- ❌ **Không nên:** [Điều cần tránh] - -## Xử Lý Sự Cố (Troubleshooting) - -**Vấn Đề:** [Lỗi thường gặp] -**Giải Pháp:** [Cách khắc phục] -``` - ---- - -## Quy Tắc Viết Commit Message - -Vui lòng sử dụng các tiền tố sau để phân loại commit: - -- `feat:` - Thêm skill mới hoặc tính năng lớn. -- `docs:` - Cập nhật/sửa đổi tài liệu. -- `fix:` - Sửa lỗi (bug fix). -- `refactor:` - Tối ưu code nhưng không đổi tính năng. -- `test:` - Thêm hoặc sửa test. -- `chore:` - Các việc vặt, bảo trì hệ thống. - -**Ví dụ:** - -``` -feat: add kubernetes-deployment skill -docs: improve getting started guide -fix: correct typo in stripe-integration skill -``` - ---- - -## Tài Liệu Tham Khảo - -### Cho người mới dùng Git/GitHub - -- [Hướng dẫn Hello World của GitHub](https://guides.github.com/activities/hello-world/) -- [Git Cơ bản](https://git-scm.com/book/en/v2/Getting-Started-Git-Basics) - -### Cho người mới viết Markdown - -- [Hướng dẫn Markdown](https://www.markdownguide.org/basic-syntax/) - ---- - -## Quy Tắc Ứng Xử (Code of Conduct) - -- Tôn trọng và hòa nhã với mọi người. -- Luôn chào đón thành viên mới. -- Góp ý mang tính xây dựng, tích cực. -- **Nghiêm cấm nội dung độc hại**: Xem chi tiết tại `docs/SECURITY_GUARDRAILS.md`. - ---- - -**Cảm ơn bạn đã góp phần xây dựng dự án!** -Mỗi đóng góp của bạn, dù là nhỏ nhất, đều rất đáng quý. Dù chỉ là sửa lỗi chính tả hay viết hẳn một skill mới - bạn đang trực tiếp giúp đỡ hàng ngàn lập trình viên khác làm việc hiệu quả hơn! diff --git a/docs/vi/EXAMPLES.md b/docs/vi/EXAMPLES.md deleted file mode 100644 index 507dced8..00000000 --- a/docs/vi/EXAMPLES.md +++ /dev/null @@ -1,56 +0,0 @@ -# 🧪 Ví Dụ Thực Tế ("Sách dạy nấu ăn Antigravity") - -Skill đứng một mình đã mạnh, nhưng khi kết hợp lại thì "vô đối". -Dưới đây là 3 kịch bản phổ biến và cách giải quyết chúng bằng kho tàng này. - -## 🥘 Công thức 1: "Kiểm toán Code cũ" (The Legacy Code Audit) - -_Tình huống: Bạn vừa phải nhận lại một dự án Node.js 5 năm tuổi siêu lộn xộn. Bạn cần dọn dẹp nó một cách an toàn._ - -**Các Skill cần dùng:** - -1. `concise-planning` (Để vẽ bản đồ cho đống hỗn độn) -2. `lint-and-validate` (Để tìm lỗi) -3. `security-review` (Để tìm lỗ hổng) - -**Quy trình (Workflow):** - -1. **Lập kế hoạch**: "Này Agent, dùng `concise-planning` để tạo checklist refactor lại thư mục `src/legacy-api.js` cho tôi." -2. **Kiểm toán**: "Chạy `security-review` trên file `package.json` để xem có thư viện nào dính lỗi bảo mật không." -3. **Sửa lỗi**: "Dùng các quy tắc của `lint-and-validate` để tự sửa lỗi định dạng trong thư mục `src/`." - ---- - -## 🥘 Công thức 2: "Web App Hiện Đại" (The Modern Web App) - -_Tình huống: Bạn cần dựng một trang Landing Page có hiệu năng cao trong vòng 2 tiếng._ - -**Các Skill cần dùng:** - -1. `frontend-design` (Để lo phần thẩm mỹ) -2. `react-patterns` (Để lo phần cấu trúc code) -3. `tailwind-mastery` (Để code giao diện siêu tốc) - -**Quy trình (Workflow):** - -1. **Thiết kế**: "Dùng `frontend-design` tạo cho tôi một bảng màu và font chữ theo phong cách 'Quán Cà phê Cyberpunk'." -2. **Dựng khung**: "Khởi tạo dự án Vite. Sau đó áp dụng `react-patterns` để viết component 'Hero'." -3. **Tạo kiểu**: "Dùng `tailwind-mastery` làm cho mấy cái nút bấm có hiệu ứng kính (glassmorphism) và chuẩn mobile giúp tôi." - ---- - -## 🥘 Công thức 3: "Kiến Trúc Sư Agent" (The Agent Architect) - -_Tình huống: Bạn muốn xây một con AI agent riêng có khả năng tự kiểm tra code của chính nó._ - -**Các Skill cần dùng:** - -1. `mcp-builder` (Để xây công cụ) -2. `agent-evaluation` (Để kiểm tra độ tin cậy) -3. `prompt-engineering` (Để tinh chỉnh câu lệnh) - -**Quy trình (Workflow):** - -1. **Xây dựng**: "Dùng `mcp-builder` để tạo một công cụ tên là `verify-file`." -2. **Ra lệnh**: "Áp dụng các mẫu `prompt-engineering` vào System Prompt để đảm bảo con agent luôn kiểm tra đường dẫn file trước khi làm gì đó." -3. **Kiểm thử**: "Chạy `agent-evaluation` để đo xem tần suất con agent này tìm sai file là bao nhiêu phần trăm." diff --git a/docs/vi/FAQ.md b/docs/vi/FAQ.md deleted file mode 100644 index e2b7a619..00000000 --- a/docs/vi/FAQ.md +++ /dev/null @@ -1,178 +0,0 @@ -# ❓ Câu Hỏi Thường Gặp (FAQ) - -**Bạn có thắc mắc?** Đừng lo, bạn không cô đơn đâu! Dưới đây là giải đáp cho những câu hỏi phổ biến nhất về Antigravity Awesome Skills. - ---- - -## 🎯 Câu hỏi chung - -### "Skill" rốt cuộc là cái gì? - -Skills thực chất là các file hướng dẫn chuyên biệt dùng để dạy cho trợ lý AI cách xử lý một tác vụ cụ thể. Hãy coi nó như những module kiến thức chuyên gia mà AI của bạn có thể "nạp" vào khi cần. -**Ví dụ dễ hiểu:** Giống như trong phim Ma Trận, khi Neo cần biết lái trực thăng, anh ấy tải chương trình lái trực thăng vào não. Skills ở đây cũng y hệt vậy, giúp biến AI của bạn thành chuyên gia trong từng lĩnh vực (luật sư, bác sĩ, thợ máy...) tùy theo nhu cầu của bạn. - -### Tôi có phải cài hết hơn 250 skill không? - -**Không hề!** Khi bạn clone cái kho này về, toàn bộ skills sẽ nằm sẵn trong máy, NHƯNG AI của bạn chỉ thực sự đọc và load kỹ năng nào mà bạn gọi tên (bằng lệnh `@tên-skill`) thôi. -Nó giống như một thư viện sách: sách thì đầy trên kệ, nhưng bạn chỉ cần rút đúng cuốn bạn định đọc. -**Mẹo:** Dùng các [Gói Khởi Điểm (Starter Packs)](../BUNDLES.vi.md) để cài bộ phù hợp với công việc của bạn cho gọn. - -### Những công cụ AI nào dùng được mấy skill này? - -- ✅ **Claude Code** (Anthropic CLI) -- ✅ **Gemini CLI** (Google) -- ✅ **Codex CLI** (OpenAI) -- ✅ **Cursor** (AI IDE) -- ✅ **Antigravity IDE** -- ✅ **OpenCode** -- ⚠️ **GitHub Copilot** (Hỗ trợ một phần, phải copy-paste thủ công) - -### Dùng cái này có mất phí không? - -**Hoàn toàn miễn phí!** Dự án này dùng Giấy phép MIT. - -- ✅ Miễn phí cho dùng cá nhân -- ✅ Miễn phí cho thương mại/công ty -- ✅ Bạn thoải mái sửa đổi code - -### Skills có chạy offline không? - -Bản thân các file skill nằm trên máy bạn (offline), nhưng trợ lý AI (Claude, Gemini...) thì vẫn cần mạng internet để hoạt động nhé. - ---- - -## 🔒 Độ Tin Cậy & An Toàn (Cập nhật V3) - -### Mấy cái "Nhãn Rủi Ro" (Risk Label) nghĩa là sao? - -Để đảm bảo an toàn, chúng tôi phân loại skill theo màu: - -- ⚪ **Safe (Trắng/Xanh)**: Skill an toàn, chỉ đọc, lập kế hoạch hoặc vô hại. -- 🔴 **Risk (Đỏ)**: Skill có khả năng chỉnh sửa/xóa file hệ thống, hoặc dùng để quét mạng (pentest). **Cần cẩn trọng khi dùng.** -- 🟣 **Official (Tím)**: Skill chính chủ do các nhà cung cấp uy tín (Anthropic, DeepMind...) bảo trì. - -### Dùng skill này có sợ bị hack máy không? - -**Không.** Skill chỉ là file văn bản (text). Tuy nhiên, nó chứa hướng dẫn để AI chạy lệnh. Nếu skill bảo "xóa hết file đi", một con AI ngây thơ có thể sẽ làm thật. -_Do đó: Luôn kiểm tra Nhãn Rủi Ro và đọc qua nội dung skill trước khi dùng._ - ---- - -## 📦 Cài đặt & Thiết lập - -### Tôi nên cài skill vào đâu? - -Đường dẫn chuẩn nhất dùng được cho hầu hết công cụ là `.agent/skills/`: - -```bash -git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills -``` - -**Đường dẫn riêng cho từng tool:** - -- Claude Code: `.claude/skills/` -- Gemini CLI: `.gemini/skills/` -- Cursor: `.cursor/skills/` hoặc thư mục gốc của dự án - -### Dùng trên Windows có được không? - -**Được**, nhưng lưu ý là một số skill "Official" có dùng **symlinks** (liên kết tượng trưng) mà Windows mặc định hỗ trợ hơi kém. -Hãy chạy lệnh git này để bật hỗ trợ symlink: - -```bash -git clone -c core.symlinks=true https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills -``` - -Hoặc bật chế độ "Developer Mode" trong phần Settings của Windows. - -### Cập nhật skill kiểu gì? - -Chỉ cần vào thư mục đó và pull code mới về là xong: - -```bash -cd .agent/skills -git pull origin main -``` - ---- - -## 🛠️ Cách sử dụng - -### Gọi skill như thế nào? - -Dùng ký tự `@` cộng với tên skill: - -``` -@brainstorming giúp tôi thiết kế một app quản lý công việc -``` - -### Dùng nhiều skill cùng lúc được không? - -**Được luôn!** Bạn có thể kết hợp (combo) nhiều skill: - -``` -@brainstorming lên ý tưởng cho tôi, xong rồi dùng @writing-plans để ra list công việc cụ thể nhé. -``` - -### Làm sao biết nên dùng skill nào? - -1. **Đọc file README**: Xem [Danh sách đầy đủ các skill](README.vi.md#trọn-bộ-danh-sách-256-kỹ-năng-full-list). -2. **Tìm kiếm**: `ls skills/ | grep "từ-khóa"` (ví dụ tìm "test", "security"). -3. **Hỏi chính con AI**: "Cậu có skill nào liên quan đến testing không?" - ---- - -## 🏗️ Xử lý sự cố (Troubleshooting) - -### AI của tôi không nhận diện được skill - -**Nguyên nhân có thể:** - -1. **Sai đường dẫn cài đặt**: Kiểm tra lại tài liệu của tool bạn dùng. Thử đường dẫn `.agent/skills/` xem sao. -2. **Cần khởi động lại**: Thử tắt đi bật lại AI/IDE sau khi cài đặt. -3. **Gõ sai tên**: Bạn có gõ `@brain-storming` thay vì `@brainstorming` không? - -### Skill đưa ra lời khuyên sai hoặc lỗi thời - -Làm ơn hãy [Báo lỗi (Open Issue)](https://github.com/sickn33/antigravity-awesome-skills/issues) giúp chúng tôi! -Nhớ ghi rõ: - -- Skill nào bị lỗi -- Lỗi là gì -- Đáng lẽ nó phải làm gì - ---- - -## 🤝 Đóng góp (Contribution) - -### Tôi là người mới (newbie). Tôi đóng góp được không? - -**Hoan nghênh nhiệt liệt!** Chúng tôi rất quý trọng các đóng góp từ người mới. - -- Sửa lỗi chính tả -- Thêm ví dụ -- Cải thiện tài liệu - Xem hướng dẫn tại [CONTRIBUTING.vi.md](CONTRIBUTING.vi.md) nhé. - -### Tôi gửi PR nhưng bị trượt bài kiểm tra "Quality Bar". Tại sao? - -Bản V3 có hệ thống kiểm tra chất lượng tự động. Skill của bạn có thể đang thiếu: - -1. Phần `description` (mô tả). -2. Các ví dụ sử dụng mẫu. - Hãy chạy `python3 scripts/validate_skills.py` trên máy để tự kiểm tra trước khi đẩy code lên nhé. - -### Tôi có được sửa các skill "Official" không? - -**Không.** Các skill Official (trong thư mục `skills/official/`) là bản sao (mirror) từ nhà cung cấp gốc. Nếu thấy lỗi, hãy mở Issue báo cáo thay vì sửa trực tiếp. - ---- - -## 💡 Mẹo hay cho chuyên gia (Pro Tips) - -- Luôn bắt đầu bằng `@brainstorming` trước khi xây dựng cái gì mới. -- Dùng `@systematic-debugging` khi bí bách vì bug. -- Thử `@test-driven-development` để code "xịn" hơn. -- Khám phá `@skill-creator` để tự tạo skill riêng cho mình. - -**Vẫn còn thắc mắc?** [Vào đây thảo luận](https://github.com/sickn33/antigravity-awesome-skills/discussions) nhé, chúng tôi sẽ hỗ trợ hết mình! 🙌 diff --git a/docs/vi/GETTING_STARTED.md b/docs/vi/GETTING_STARTED.md deleted file mode 100644 index a1c8807e..00000000 --- a/docs/vi/GETTING_STARTED.md +++ /dev/null @@ -1,110 +0,0 @@ -# Bắt đầu với Antigravity Awesome Skills (V3) - -[Đọc bản gốc tiếng Anh](./GETTING_STARTED.md) - -**Bạn là người mới? Hướng dẫn này sẽ giúp bạn "nâng cấp" trí tuệ cho AI Agent chỉ trong 5 phút.** - ---- - -## 🤔 "Skill" là gì? - -Các trợ lý AI (như **Claude Code**, **Gemini**, **Cursor**) vốn rất thông minh, nhưng chúng thường thiếu kiến thức chuyên sâu về bộ công cụ cụ thể mà bạn đang dùng. -**Skills** chính là những cuốn "cẩm nang hướng dẫn" (file markdown) giúp dạy cho AI biết cách thực hiện từng tác vụ chuyên biệt một cách chuẩn xác nhất. - -**Hãy tưởng tượng:** AI của bạn là một thực tập sinh thiên tài. **Skills** chính là các quy trình chuẩn (SOPs) giúp biến cậu thực tập sinh đó thành một Kỹ sư Cao cấp (Senior Engineer) dày dặn kinh nghiệm. - ---- - -## ⚡️ Bắt đầu nhanh: Dùng "Gói Khởi Điểm" (Starter Packs) - -Đừng bị choáng ngợp bởi con số 256+ skill. Bạn không cần phải dùng hết tát cả cùng lúc. -Chúng tôi đã soạn sẵn các **Gói Khởi Điểm** để bạn có thể bắt tay vào việc ngay. - -### 1. Cài đặt Repo - -Clone toàn bộ kho skill này vào thư mục cấu hình của agent: - -```bash -# Cách cài đặt chung (áp dụng cho hầu hết các loại agent) -git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills -``` - -### 2. Chọn Gói phù hợp với Vai trò (Persona) - -Hãy tìm gói (Bundle) phù hợp nhất với công việc của bạn (xem chi tiết tại [docs/BUNDLES.vi.md](../BUNDLES.vi.md)): - -| Vai Trò | Tên Gói | Gồm những gì? | -| :-------------------- | :------------- | :------------------------------------------------ | -| **Web Developer** | `Web Wizard` | React Patterns, bí kíp Tailwind, Thiết kế Frontend| -| **Security Engineer** | `Hacker Pack` | OWASP, Metasploit, Quy trình Pentest | -| **Manager / PM** | `Product Pack` | Brainstorming, Lập kế hoạch, SEO, Chiến lược | -| **Bất kỳ ai** | `Essentials` | Clean Code, Lập kế hoạch, Kiểm tra code (Cơ bản) | - ---- - -## 🚀 Cách sử dụng Skill - -Sau khi cài đặt xong, bạn cứ trò chuyện với AI như bình thường. - -### Ví dụ 1: Lên kế hoạch tính năng (Gói **Essentials**) - -> "Dùng **@brainstorming** giúp tôi lên ý tưởng cho luồng đăng nhập (login flow) mới." - -**Kết quả:** AI sẽ kích hoạt skill brainstorming, đặt các câu hỏi định hướng, và cuối cùng soạn ra một bản đặc tả (spec) chuyên nghiệp cho bạn. - -### Ví dụ 2: Rà soát Code (Gói **Web Wizard**) - -> "Chạy **@lint-and-validate** trên file này và sửa các lỗi giúp tôi." - -**Kết quả:** AI sẽ tuân thủ nghiêm ngặt các quy tắc linting đã được định nghĩa trong skill để dọn dẹp và chuẩn hóa code của bạn. - -### Ví dụ 3: Kiểm toán Bảo mật (Gói **Hacker Pack**) - -> "Dùng **@api-security-best-practices** để review các API endpoint này xem có lỗ hổng nào không." - -**Kết quả:** AI sẽ đóng vai chuyên gia bảo mật, rà soát code của bạn dựa trên các tiêu chuẩn an toàn của OWASP. - ---- - -## 🔌 Các công cụ hỗ trợ - -| Công cụ | Trạng thái | Đường dẫn cài đặt | -| :-------------- | :-------------- | :---------------- | -| **Claude Code** | ✅ Hỗ trợ tốt | `.claude/skills/` | -| **Gemini CLI** | ✅ Hỗ trợ tốt | `.gemini/skills/` | -| **Antigravity** | ✅ Mặc định | `.agent/skills/` | -| **Cursor** | ✅ Mặc định | `.cursor/skills/` | -| **Copilot** | ⚠️ Chỉ Text | Phải copy-paste thủ công | - ---- - -## 🛡️ Độ Tin Cậy & An Toàn (Mới) - -Để bạn yên tâm sử dụng, chúng tôi phân loại skill theo các nhãn sau: - -- 🟣 **Official**: Skill chính chủ, được bảo trì bởi Anthropic/Google hoặc các nhà cung cấp uy tín (Độ tin cậy cao). -- 🔵 **Safe**: Skill do cộng đồng đóng góp, an toàn, không gây hại (thường là skill đọc hoặc lập kế hoạch). -- 🔴 **Risk**: Skill có khả năng sửa đổi hệ thống hoặc thực hiện các bài test bảo mật (Chỉ dùng khi bạn hiểu rõ và cho phép). - -_Xem [Danh sách đầy đủ](README.vi.md#danh-sách-skill-đầy-đủ-256256) để biết nhãn rủi ro của từng skill._ - ---- - -## ❓ Câu hỏi thường gặp (FAQ) - -**H: Tôi có bắt buộc phải cài hết 250 skill không?** -Đ: Bạn clone cả repo về, nhưng AI chỉ _đọc_ đúng cái skill mà bạn gọi (hoặc liên quan) thôi. Nên nó rất nhẹ, không lo nặng máy! - -**H: Tôi tự viết skill riêng được không?** -Đ: Được chứ! Hãy dùng skill **@skill-creator** để nó hướng dẫn bạn tạo skill mới từ A-Z. - -**H: Dùng cái này có mất phí không?** -Đ: Hoàn toàn miễn phí. Giấy phép MIT. Mã nguồn mở mãi mãi. - ---- - -## ⏭️ Bước tiếp theo - -1. [Xem chi tiết các Gói (Bundles)](../BUNDLES.vi.md) -2. [Tham khảo các ví dụ thực tế](../EXAMPLES.vi.md) -3. [Đóng góp Skill cho cộng đồng](CONTRIBUTING.vi.md) diff --git a/docs/vi/README.md b/docs/vi/README.md deleted file mode 100644 index 1e91cf79..00000000 --- a/docs/vi/README.md +++ /dev/null @@ -1,479 +0,0 @@ -# 🌌 Antigravity Awesome Skills: Kho Tàng 256+ Kỹ Năng Agentic cho Claude Code, Gemini CLI, Cursor & Copilot - -[Đọc bản gốc tiếng Anh](../../README.md) - -> **Bộ sưu tập "quyền năng" tối thượng gồm hơn 256 kỹ năng giúp bạn làm chủ các Trợ lý Lập trình AI như Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor và OpenCode** - -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![Claude Code](https://img.shields.io/badge/Claude%20Code-Anthropic-purple)](https://claude.ai) -[![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-Google-blue)](https://github.com/google-gemini/gemini-cli) -[![Codex CLI](https://img.shields.io/badge/Codex%20CLI-OpenAI-green)](https://github.com/openai/codex) -[![Cursor](https://img.shields.io/badge/Cursor-AI%20IDE-orange)](https://cursor.sh) -[![Copilot](https://img.shields.io/badge/GitHub%20Copilot-VSCode-lightblue)](https://github.com/features/copilot) -[![OpenCode](https://img.shields.io/badge/OpenCode-CLI-gray)](https://github.com/opencode-ai/opencode) -[![Antigravity](https://img.shields.io/badge/Antigravity-DeepMind-red)](https://github.com/sickn33/antigravity-awesome-skills) - -**Antigravity Awesome Skills** không chỉ là một danh sách, mà là một kho vũ khí hạng nặng đã được kiểm chứng thực tế. Nó bao gồm **256 kỹ năng chuyên biệt** giúp AI hoạt động hiệu quả tối đa trên mọi nền tảng trợ lý lập trình phổ biến hiện nay: - -- 🟣 **Claude Code** (Anthropic CLI) -- 🔵 **Gemini CLI** (Google DeepMind) -- 🟢 **Codex CLI** (OpenAI) -- 🔴 **Antigravity IDE** (Google DeepMind) -- 🩵 **GitHub Copilot** (VSCode Extension) -- 🟠 **Cursor** (AI-native IDE) -- ⚪ **OpenCode** (Open-source CLI) - -Dự án này cung cấp những kỹ năng then chốt để biến trợ lý AI của bạn từ một công cụ chat đơn thuần thành một **đội ngũ kỹ thuật số toàn năng (full-stack digital agency)**. Chúng tôi tích hợp cả những quy trình chuẩn mực từ các ông lớn như **Anthropic**, **OpenAI**, **Google**, **Supabase**, và **Vercel Labs**. - -## Mục Lục - Đi tắt đón đầu - -- [🚀 Bạn mới dùng lần đầu? Hãy đọc phần này trước!](#bạn-mới-dùng-lần-đầu-hãy-đọc-phần-này-trước) -- [🔌 Các công cụ hỗ trợ & Cách ra lệnh cho AI](#các-công-cụ-hỗ-trợ--cách-ra-lệnh-cho-ai) -- [📦 Phân loại các nhóm Kỹ năng & Tính năng](#phân-loại-các-nhóm-kỹ-năng--tính-năng) -- [🎁 Các gói Kỹ năng chọn lọc theo nghề (Bundles)](#các-gói-kỹ-năng-chọn-lọc-theo-nghề-bundles) -- [📜 Trọn bộ danh sách 256 Kỹ năng (Full list)](#trọn-bộ-danh-sách-256-kỹ-năng-full-list) -- [🛠️ Hướng dẫn cài đặt nhanh](#hướng-dẫn-cài-đặt-nhanh) -- [🤝 Bạn muốn đóng góp?](#bạn-muốn-đóng-góp) -- [👥 Lời cảm ơn & Nguồn tham khảo](#lời-cảm-ơn--nguồn-tham-khảo) -- [⚖️ Bản quyền (License)](#bản-quyền-license) -- [👥 Những người hùng đã đóng góp](#những-người-hùng-đã-đóng-góp) -- [🌟 Lịch sử phát triển](#lịch-sử-phát-triển) - ---- - -## Bạn mới dùng lần đầu? Hãy đọc phần này trước! - -**Chào mừng bạn đến với phiên bản V3 Enterprise.** -Đây không phải là một danh sách chứa mấy đoạn code rời rạc. Hãy coi đây là một **hệ điều hành kiến thức** hoàn chỉnh giúp AI Agent của bạn thông minh hơn gấp bội. - -### 1. 🐣 Hiểu đơn giản: Cái này để làm gì? - -Các AI Agent (như Claude Code, Cursor, hay Gemini) rất thông minh, nhưng chúng giống như những siêu máy tính chưa được cài phần mềm chuyên dụng. Chúng không thể tự biết "Quy trình Deploy chuẩn của công ty A" hay "Cách viết code AWS CloudFormation không lỗi". -**Skills (Kỹ năng)** ở đây chính là những file hướng dẫn nhỏ (dạng markdown), đóng vai trò như sách giáo khoa, dạy cho AI biết cách thực hiện từng đầu việc cụ thể một cách chuẩn chỉ, trăm lần như một. - -### 2. ⚡️ Cách dùng nhanh nhất (Dùng các Gói có sẵn) - -Bạn không việc gì phải cài thủ công từng cái trong số 256 skill kia. Chúng tôi đã gom nhóm sẵn thành các **Gói Khởi Điểm (Starter Packs)** phù hợp với từng nhu cầu: - -1. **Tải repo này về máy**: - ```bash - git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills - ``` -2. **Chọn vai trò của bạn** (Xem chi tiết tại [docs/BUNDLES.md](BUNDLES.md)): - - **Lập trình viên Web?** 👉 chọn gói `Web Wizard`. - - **Chuyên gia Bảo mật/Hacker?** 👉 chọn gói `Security Engineer`. - - **Muốn dùng thử cho biết?** 👉 chọn gói `Essentials` (Cơ bản). - -### 3. 🧠 Dùng như thế nào? - -Cài xong rồi thì bạn cứ ra lệnh cho con AI như nói chuyện bình thường thôi: - -> "Dùng skill **@brainstorming** để giúp tôi lên ý tưởng cho một dự án phần mềm quản lý kho." -> "Chạy **@lint-and-validate** trên file code này xem có lỗi cú pháp nào không." - -👉 **[Xem Hướng dẫn chi tiết cho người mới bắt đầu (Tiếng Việt)](GETTING_STARTED.md)** - ---- - -## Các công cụ hỗ trợ & Cách ra lệnh cho AI - -Các skill này được viết theo chuẩn **SKILL.md** quốc tế, nên bạn dùng trợ lý ảo nào nó cũng hiểu được, miễn là có hỗ trợ tính năng agentic skills. - -| Tên Công cụ | Loại | Ví dụ câu lệnh mẫu | Thư mục cài đặt chuẩn | -| :-------------- | :--- | :-------------------------------- | :-------------------- | -| **Claude Code** | CLI | `>> /skill-name help me...` | `.claude/skills/` | -| **Gemini CLI** | CLI | `(User Prompt) Use skill-name...` | `.gemini/skills/` | -| **Antigravity** | IDE | `(Agent Mode) Use skill...` | `.agent/skills/` | -| **Cursor** | IDE | `@skill-name (gõ trong Chat)` | `.cursor/skills/` | -| **Copilot** | Ext | `(Copy nội dung dán vào chat)` | N/A | - -> [!TIP] -> **Lời khuyên**: Tốt nhất bạn nên cài vào thư mục `.agent/skills/`. Hầu hết các công cụ mới bây giờ (như Antigravity) đều tự động tìm trong thư mục này, rất tiện. - -> [!WARNING] -> **Lưu ý cho người dùng Windows**: Repo này có dùng **symlinks** (đường dẫn tắt) cho các skill chính chủ. -> Để tránh lỗi, bạn cần bật Developer Mode trên Windows hoặc chạy Git dưới quyền Admin: -> `git clone -c core.symlinks=true https://github.com/...` - ---- - -Dù bạn đang dùng **Gemini CLI**, **Claude Code**, **Codex CLI**, **Cursor**, **GitHub Copilot**, **Antigravity**, hay **OpenCode**, bộ skill này được thiết kế theo tiêu chí "cắm là chạy" (plug-and-play), giúp tăng sức mạnh cho trợ lý AI của bạn tức thì. - -Đây là nơi hội tụ tinh hoa từ cộng đồng mã nguồn mở, giúp biến trợ lý AI của bạn thành một "siêu nhân": code giỏi, thiết kế đẹp, lại còn rành bảo mật và biết làm cả marketing. - -## Phân loại các nhóm Kỹ năng & Tính năng - -Kho tàng này được chia thành các nhóm chuyên môn để bạn dễ tìm kiếm: - -| Nhóm Kỹ Năng | Số lượng | Những cái tên nổi bật nên thử ngay | -| :----------------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------- | -| **🛸 Tự Động Hóa & Agent** | **(13)** | Loki Mode (Chế độ Startup tự động), Code theo kiểu Agent con (Subagent), Điều phối Agent chạy song song, Tự tạo Skill mới | -| **🔌 Kết Nối & APIs** | **(35)** | Stripe, Firebase, Supabase, Vercel, Clerk Auth, Twilio, Discord Bot, Slack Bot, GraphQL, AWS Serverless | -| **🛡️ Bảo Mật & An Ninh** | **(32)** | Ethical Hacking, Metasploit, Burp Suite, SQLMap, Tấn công Active Directory, Kiểm thử AWS/Cloud, Top 100 lỗi OWASP | -| **🎨 Sáng Tạo & Thiết Kế** | **(21)** | UI/UX Pro Max, Thiết kế Frontend, Canvas, Tạo nghệ thuật bằng code, Theme Factory, Vẽ biểu đồ D3 | -| **🛠️ Kỹ Thuật Lập Trình** | **(44)** | TDD (Test trước code sau), Debug có hệ thống, React Patterns, Chuẩn Backend/Frontend, Kiến trúc phần mềm | -| **🏗️ Hạ Tầng & Git** | **(13)** | Shell Scripting, Git Worktrees, Git Pushing, Conventional Commits (Commit chuẩn), Sắp xếp file, Tự động hóa GitHub Workflow | -| **🤖 AI & LLM** | **(27)** | Voice AI Engine, LangGraph, CrewAI, Kỹ sư RAG, Prompt Engineer, Tự động hóa trình duyệt, Hệ thống bộ nhớ cho Agent | -| **🔄 Quy Trình Làm Việc** | **(19)** | Lập kế hoạch, Thực thi kế hoạch, Soát xét code (Code Review), Kiểm tra kỹ lưỡng trước khi bàn giao | -| **📄 Xử Lý Tài Liệu** | **(5)** | Làm việc với file Word (DOCX), PDF, PowerPoint (PPTX), Excel (XLSX) - Bản chính chủ | -| **🧪 Kiểm Thử (Testing)** | **(8)** | Test ứng dụng Web, Tự động hóa với Playwright, Sửa lỗi Test, Các mẫu Testing chuẩn | -| **📈 Sản Phẩm & Chiến Lược** | **(4)** | Bộ công cụ cho Product Manager (PM), Sáng tạo nội dung, Tối ưu App Store (ASO), Brainstorming ý tưởng | -| **📣 Marketing & Tăng Trưởng** | **(26)** | Tối ưu chuyển đổi (CRO), Viết lời quảng cáo (Copywriting), SEO Audit, Chạy Ads, Gửi Email tự động, Chiến lược giá | -| **🚀 Công Cụ cho Maker** | **(8)** | Ra mắt Micro-SaaS, Làm Extension trình duyệt, Tạo Bot Telegram, Xây dựng AI Wrapper, Tạo nội dung Viral | - -## Các gói Kỹ năng chọn lọc theo nghề (Bundles) - -Hãy ghé thăm trang [docs/BUNDLES.md](BUNDLES.md) để xem các **Gói Khởi Điểm** và chọn cho mình bộ đồ nghề ưng ý nhất thay vì phải tự nhặt từng cái. - -## Trọn bộ danh sách 256 Kỹ năng (Full list) - -> [!NOTE] -> **Về các Skill xử lý tài liệu**: Với các định dạng như Word, PDF, Excel, PowerPoint, chúng tôi có 2 bản: **bản cộng đồng (community)** và **bản chính chủ (official Anthropic)**. Khi bạn chạy trên máy, hệ thống sẽ ưu tiên dùng bản chính chủ (xịn hơn). - -_(Lưu ý: Bảng dưới đây giữ nguyên tên tiếng Anh của Skill để bạn dễ tra cứu trong code, còn phần mô tả đã được dịch sang tiếng Việt)_ - -| Tên Skill (Tên lệnh) | Rủi ro | Mô tả công dụng | Đường dẫn file | -| :-------------------------------------------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------- | -| **2d-games** | ⚪ | Nguyên tắc phát triển game 2D. Sprites, tilemaps, vật lý, camera. | `skills/game-development/2d-games` | -| **3d-games** | ⚪ | Nguyên tắc phát triển game 3D. Rendering, shaders, vật lý, camera. | `skills/game-development/3d-games` | -| **3d-web-experience** | ⚪ | Chuyên gia xây dựng trải nghiệm 3D cho web - Three.js, React Three Fiber, Spline, WebGL. Bao gồm cấu hình sản phẩm, portfolio 3D, website nhập vai. | `skills/3d-web-experience` | -| **ab-test-setup** | ⚪ | Hướng dẫn cấu trúc thiết lập A/B test với các cổng kiểm soát bắt buộc cho giả thuyết, chỉ số và sự sẵn sàng thực thi. | `skills/ab-test-setup` | -| **Active Directory Attacks** | ⚪ | Dùng khi user yêu cầu "tấn công Active Directory", "khai thác AD", "Kerberoasting", "DCSync", "pass-the-hash", "BloodHound", "Golden Ticket"... | `skills/active-directory-attacks` | -| **address-github-comments** | ⚪ | Dùng khi bạn cần giải quyết các comment review hoặc issue trên GitHub Pull Request đang mở bằng gh CLI. | `skills/address-github-comments` | -| **agent-evaluation** | ⚪ | Kiểm thử và đánh giá chuẩn (benchmark) các LLM agent, bao gồm kiểm tra hành vi, đánh giá năng lực, chỉ số độ tin cậy và giám sát production. | `skills/agent-evaluation` | -| **agent-manager-skill** | ⚪ | Quản lý nhiều CLI agent cục bộ thông qua tmux sessions (start/stop/monitor/assign) với lịch trình cron-friendly. | `skills/agent-manager-skill` | -| **agent-memory-mcp** | ⚪ | Hệ thống bộ nhớ lai cung cấp quản lý tri thức bền vững, có thể tìm kiếm cho AI agents (Kiến trúc, Mẫu, Quyết định). | `skills/agent-memory-mcp` | -| **agent-memory-systems** | ⚪ | Skill bao trùm kiến trúc bộ nhớ agent: ngắn hạn (context window), dài hạn (vector stores), và các kiến trúc nhận thức để tổ chức chúng. | `skills/agent-memory-systems` | -| **agent-tool-builder** | ⚪ | Thiết kế công cụ từ schema đến xử lý lỗi. JSON Schema best practices, viết mô tả giúp LLM hiểu, validation, và chuẩn MCP mới nổi. | `skills/agent-tool-builder` | -| **ai-agents-architect** | ⚪ | Chuyên gia thiết kế và xây dựng các AI agent tự chủ. Làm chủ việc sử dụng công cụ, hệ thống bộ nhớ, chiến lược lập kế hoạch và điều phối đa tác nhân. | `skills/ai-agents-architect` | -| **ai-product** | ⚪ | Các mẫu tích hợp LLM, kiến trúc RAG, prompt engineering mở rộng, AI UX mà người dùng tin tưởng, và tối ưu hóa chi phí. | `skills/ai-product` | -| **ai-wrapper-product** | ⚪ | Chuyên gia xây dựng các sản phẩm bao bọc (wrap) AI APIs (OpenAI, Anthropic...) thành các công cụ tập trung giải quyết vấn đề cụ thể. | `skills/ai-wrapper-product` | -| **algolia-search** | ⚪ | Các mẫu chuyên gia để triển khai tìm kiếm Algolia, chiến lược đánh chỉ mục (indexing), React InstantSearch và tinh chỉnh độ liên quan. | `skills/algolia-search` | -| **algorithmic-art** | ⚪ | Tạo nghệ thuật thuật toán sử dụng p5.js với tính ngẫu nhiên có hạt giống (seeded randomness) và tham số tương tác. | `skills/algorithmic-art` | -| **analytics-tracking** | ⚪ | Thiết kế, kiểm toán và cải thiện hệ thống theo dõi phân tích (GA4, GTM, product analytics, events, conversions, UTMs). | `skills/analytics-tracking` | -| **API Fuzzing for Bug Bounty** | ⚪ | Dùng khi user yêu cầu "test bảo mật API", "fuzz APIs", "tìm lỗi IDOR", "test REST/GraphQL API", "kiểm thử xâm nhập API". | `skills/api-fuzzing-bug-bounty` | -| **api-documentation-generator** | ⚪ | Tạo tài liệu API toàn diện, thân thiện với lập trình viên từ code, bao gồm endpoints, tham số, ví dụ. | `skills/api-documentation-generator` | -| **api-patterns** | ⚪ | Nguyên tắc thiết kế API và ra quyết định. Chọn REST vs GraphQL vs tRPC, định dạng phản hồi, versioning, phân trang. | `skills/api-patterns` | -| **api-security-best-practices** | ⚪ | Triển khai các mẫu thiết kế API bảo mật bao gồm xác thực, phân quyền, validate đầu vào, rate limiting. | `skills/api-security-best-practices` | -| **app-builder** | ⚪ | Bộ điều phối xây dựng ứng dụng chính. Tạo ứng dụng full-stack từ yêu cầu ngôn ngữ tự nhiên. Xác định loại dự án, chọn tech stack. | `skills/app-builder` | -| **app-store-optimization** | ⚪ | Bộ công cụ ASO hoàn chỉnh để nghiên cứu, tối ưu hóa và theo dõi hiệu suất ứng dụng trên Apple App Store và Google Play Store. | `skills/app-store-optimization` | -| **architecture** | ⚪ | Khung ra quyết định kiến trúc. Phân tích yêu cầu, đánh giá đánh đổi (trade-off), tài liệu hóa ADR. | `skills/architecture` | -| **autonomous-agent-patterns** | ⚪ | Các mẫu thiết kế để xây dựng coding agent tự chủ. Tích hợp công cụ, hệ thống quyền, tự động hóa trình duyệt, quy trình human-in-the-loop. | `skills/autonomous-agent-patterns` | -| **autonomous-agents** | ⚪ | Skill bao trùm các vòng lặp agent (ReAct, Plan-Execute), phân rã mục tiêu, mẫu phản tư (reflection), và độ tin cậy trong production. | `skills/autonomous-agents` | -| **avalonia-layout-zafiro** | ⚪ | Hướng dẫn layout Avalonia UI hiện đại sử dụng Zafiro.Avalonia, nhấn mạnh style chia sẻ, component generic. | `skills/avalonia-layout-zafiro` | -| **avalonia-viewmodels-zafiro** | ⚪ | Các mẫu tạo ViewModel và Wizard tối ưu cho Avalonia sử dụng Zafiro và ReactiveUI. | `skills/avalonia-viewmodels-zafiro` | -| **avalonia-zafiro-development** | ⚪ | Các quy tắc bắt buộc, quy ước và hành vi để phát triển Avalonia UI sử dụng bộ công cụ Zafiro. | `skills/avalonia-zafiro-development` | -| **AWS Penetration Testing** | ⚪ | Dùng khi user yêu cầu "pentest AWS", "test bảo mật AWS", "khai thác IAM", "leo thang đặc quyền AWS", "test S3 bucket", "SSRF metadata"... | `skills/aws-penetration-testing` | -| **aws-serverless** | ⚪ | Kỹ năng chuyên sâu xây dựng ứng dụng serverless ready-for-production trên AWS (Lambda, API Gateway, DynamoDB, SQS/SNS, SAM/CDK). | `skills/aws-serverless` | -| **azure-functions** | ⚪ | Các mẫu chuyên gia phát triển Azure Functions bao gồm isolated worker model, Durable Functions, tối ưu cold start. | `skills/azure-functions` | -| **backend-dev-guidelines** | ⚪ | Tiêu chuẩn phát triển backend (có quan điểm riêng) cho Node.js + Express + TypeScript microservices. | `skills/backend-dev-guidelines` | -| **backend-patterns** | ⚪ | Các mẫu kiến trúc backend, thiết kế API, tối ưu database, và best practices phía server cho Node.js, Express, Next.js API routes. | `skills/cc-skill-backend-patterns` | -| **bash-linux** | ⚪ | Các mẫu Bash/Linux terminal. Các lệnh quan trọng, piping, xử lý lỗi, scripting. | `skills/bash-linux` | -| **behavioral-modes** | ⚪ | Các chế độ vận hành AI (brainstorm, implement, debug, review, teach, ship, orchestrate). | `skills/behavioral-modes` | -| **blockrun** | ⚪ | Dùng khi user cần các khả năng mà Claude thiếu (tạo ảnh, dữ liệu X/Twitter thời gian thực) hoặc yêu cầu dùng model ngoài ("use gpt", "dall-e"). | `skills/blockrun` | -| **brainstorming** | ⚪ | Dùng skill này trước bất kỳ công việc sáng tạo hay xây dựng nào. Biến ý tưởng mơ hồ thành thiết kế đã được kiểm chứng. | `skills/brainstorming` | -| **brand-guidelines** | ⚪ | Áp dụng màu sắc và font chữ thương hiệu chính thức của Anthropic (Bản Official). | `skills/brand-guidelines-anthropic` | -| **brand-guidelines** | ⚪ | Áp dụng màu sắc và font chữ thương hiệu chính thức của Anthropic (Bản Community). | `skills/brand-guidelines-community` | -| **Broken Authentication Testing** | ⚪ | Hướng dẫn kiểm tra lỗi xác thực, quản lý phiên, credential stuffing, chính sách mật khẩu, session fixation. | `skills/broken-authentication` | -| **browser-automation** | ⚪ | Tự động hóa trình duyệt với Playwright (khuyên dùng) và Puppeteer. Các mẫu để test, scrape, và điều khiển agent. | `skills/browser-automation` | -| **browser-extension-builder** | ⚪ | Chuyên gia xây dựng extension trình duyệt (Chrome, Firefox, cross-browser). Manifest v3, content scripts, popup UI. | `skills/browser-extension-builder` | -| **bullmq-specialist** | ⚪ | Chuyên gia BullMQ cho hàng đợi job Redis, xử lý nền (background processing) tin cậy trong Node.js/TypeScript. | `skills/bullmq-specialist` | -| **bun-development** | ⚪ | Phát triển JavaScript/TypeScript hiện đại với Bun runtime. Quản lý gói, bundling, testing, và di chuyển từ Node.js. | `skills/bun-development` | -| **Burp Suite Web Application Testing** | ⚪ | Hướng dẫn sử dụng Burp Suite: intercept traffic, modify requests, scan vulnerabilities, dùng Repeater. | `skills/burp-suite-testing` | -| **busybox-on-windows** | ⚪ | Cách sử dụng bản build Win32 của BusyBox để chạy các công cụ dòng lệnh UNIX tiêu chuẩn trên Windows. | `skills/busybox-on-windows` | -| **canvas-design** | ⚪ | Tạo nghệ thuật thị giác đẹp mắt trong tài liệu .png và .pdf sử dụng triết lý thiết kế. | `skills/canvas-design` | -| **cc-skill-continuous-learning** | ⚪ | Kỹ năng phát triển từ everything-claude-code | `skills/cc-skill-continuous-learning` | -| **cc-skill-project-guidelines-example** | ⚪ | Skill Hướng Dẫn Dự Án (Ví dụ minh họa) | `skills/cc-skill-project-guidelines-example` | -| **cc-skill-strategic-compact** | ⚪ | Kỹ năng phát triển từ everything-claude-code | `skills/cc-skill-strategic-compact` | -| **Claude Code Guide** | ⚪ | Hướng dẫn tổng thể để sử dụng Claude Code hiệu quả. Cấu hình, chiến lược prompt, từ khóa "Thinking", debug. | `skills/claude-code-guide` | -| **clean-code** | ⚪ | Tiêu chuẩn code thực dụng - súc tích, trực tiếp, không over-engineering, không comment thừa thãi. | `skills/clean-code` | -| **clerk-auth** | ⚪ | Các mẫu chuyên gia cho tích hợp Clerk auth, middleware, organizations, webhooks, và đồng bộ user. | `skills/clerk-auth` | -| **clickhouse-io** | ⚪ | Các mẫu database ClickHouse, tối ưu query, analytics, và best practices kỹ thuật dữ liệu. | `skills/cc-skill-clickhouse-io` | -| **Cloud Penetration Testing** | ⚪ | Hướng dẫn pentest AWS, Azure, GCP. Enumeration tài nguyên, khai thác cấu hình sai, lấy secrets, audit hạ tầng. | `skills/cloud-penetration-testing` | -| **code-review-checklist** | ⚪ | Danh sách kiểm tra toàn diện để thực hiện code review kỹ lưỡng (chức năng, bảo mật, hiệu năng, bảo trì). | `skills/code-review-checklist` | -| **codex-review** | ⚪ | Code review chuyên nghiệp với tạo CHANGELOG tự động, tích hợp với Codex AI. | `skills/codex-review` | -| **coding-standards** | ⚪ | Tiêu chuẩn code phổ quát, best practices và pattern cho TypeScript, JavaScript, React, và Node.js. | `skills/cc-skill-coding-standards` | -| **competitor-alternatives** | ⚪ | Tạo các trang so sánh đối thủ hoặc trang thay thế (alternative pages) cho SEO và hỗ trợ bán hàng. | `skills/competitor-alternatives` | -| **computer-use-agents** | ⚪ | Xây dựng AI agent tương tác máy tính như con người (nhìn màn hình, di chuột, click, gõ phím). | `skills/computer-use-agents` | -| **concise-planning** | ⚪ | Dùng khi user yêu cầu một kế hoạch cho tác vụ code, tạo ra checklist rõ ràng, khả thi và nguyên tử (atomic). | `skills/concise-planning` | -| **content-creator** | ⚪ | Tạo nội dung marketing tối ưu SEO với giọng văn thương hiệu nhất quán. Bao gồm phân tích giọng văn, tối ưu SEO. | `skills/content-creator` | -| **context-window-management** | ⚪ | Các chiến lược quản lý cửa sổ ngữ cảnh LLM bao gồm tóm tắt, cắt tỉa (trimming), định tuyến (routing). | `skills/context-window-management` | -| **context7-auto-research** | ⚪ | Tự động lấy tài liệu thư viện/framework mới nhất cho Claude Code thông qua Context7 API. | `skills/context7-auto-research` | -| **conversation-memory** | ⚪ | Hệ thống bộ nhớ bền vững cho hội thoại LLM bao gồm ngắn hạn, dài hạn và bộ nhớ dựa trên thực thể. | `skills/conversation-memory` | -| **copy-editing** | ⚪ | Dùng khi user muốn chỉnh sửa, review hoặc cải thiện nội dung marketing hiện có. Cách tiếp cận hệ thống qua nhiều lượt quét. | `skills/copy-editing` | -| **copywriting** | ⚪ | Dùng khi viết, viết lại hoặc cải thiện nội dung marketing cho bất kỳ trang nào (landing page, pricing, about...). | `skills/copywriting` | -| **core-components** | ⚪ | Thư viện component cốt lõi và các mẫu hệ thống thiết kế (design system). | `skills/core-components` | -| **crewai** | ⚪ | Chuyên gia CrewAI - framework đa tác nhân (multi-agent) dựa trên vai trò. Thiết kế agent, task, orchestrate crew. | `skills/crewai` | -| **Cross-Site Scripting and HTML Injection Testing** | ⚪ | Hướng dẫn test lỗi XSS, HTML injection, khai thác injection phía client, đánh cắp cookie. | `skills/xss-html-injection` | -| **d3-viz** | ⚪ | Tạo trực quan hóa dữ liệu tương tác bằng d3.js. Biểu đồ tùy chỉnh, đồ thị mạng, bản đồ địa lý. | `skills/claude-d3js-skill` | -| **daily-news-report** | ⚪ | Dựa trên danh sách URL, cào nội dung, lọc tin kỹ thuật chất lượng cao và tạo báo cáo Markdown hàng ngày. | `skills/daily-news-report` | -| **database-design** | ⚪ | Nguyên tắc thiết kế cơ sở dữ liệu. Thiết kế schema, chiến lược index, chọn ORM, serverless databases. | `skills/database-design` | -| **deployment-procedures** | ⚪ | Nguyên tắc triển khai production. Quy trình deploy an toàn, chiến lược rollback, xác thực. | `skills/deployment-procedures` | -| **design-orchestration** | ⚪ | Điều phối quy trình thiết kế thông qua brainstorming, review đa tác nhân, và sẵn sàng thực thi theo đúng thứ tự. | `skills/design-orchestration` | -| **discord-bot-architect** | ⚪ | Kỹ năng chuyên sâu xây dựng Discord bot production-ready. Discord.js, Pycord, slash commands, sharding. | `skills/discord-bot-architect` | -| **dispatching-parallel-agents** | ⚪ | Dùng khi đối mặt với 2+ nhiệm vụ độc lập có thể thực hiện mà không chia sẻ trạng thái hoặc phụ thuộc tuần tự. | `skills/dispatching-parallel-agents` | -| **doc-coauthoring** | ⚪ | Hướng dẫn quy trình đồng tác giả tài liệu (proposal, technical spec, decision docs). | `skills/doc-coauthoring` | -| **docker-expert** | ⚪ | Chuyên gia Docker containerization. Multi-stage builds, tối ưu image, bảo mật container, Docker Compose orchestration. | `skills/docker-expert` | -| **documentation-templates** | ⚪ | Các mẫu tài liệu và hướng dẫn cấu trúc. README, API docs, comment code, tài liệu thân thiện với AI. | `skills/documentation-templates` | -| **docx** | ⚪ | Xử lý tài liệu .docx toàn diện: Tạo mới, chỉnh sửa, theo dõi thay đổi (tracked changes), comment. (Bản Official) | `skills/docx-official` | -| **email-sequence** | ⚪ | Tạo hoặc tối ưu chuỗi email (drip campaign), luồng email tự động, email vòng đời (lifecycle). | `skills/email-sequence` | -| **email-systems** | ⚪ | Kiến thức về hệ thống email: transactional email, marketing automation, deliverability, và các quyết định hạ tầng. | `skills/email-systems` | -| **environment-setup-guide** | ⚪ | Hướng dẫn thiết lập môi trường phát triển với các công cụ, dependencies và cấu hình phù hợp. | `skills/environment-setup-guide` | -| **Ethical Hacking Methodology** | ⚪ | Phương pháp và kỹ thuật one hacker đạo đức toàn diện: trinh sát, quét, khai thác, viết báo cáo. | `skills/ethical-hacking-methodology` | -| **exa-search** | ⚪ | Tìm kiếm ngữ nghĩa, khám phá nội dung tương tự và nghiên cứu có cấu trúc sử dụng Exa API. | `skills/exa-search` | -| **executing-plans** | ⚪ | Dùng khi bạn đã có một kế hoạch triển khai (implementation plan) để thực thi trong một phiên làm việc riêng. | `skills/executing-plans` | -| **File Path Traversal Testing** | ⚪ | Hướng dẫn test lỗi Directory Traversal, LFI, đọc file tùy ý trên server. | `skills/file-path-traversal` | -| **file-organizer** | ⚪ | Tổ chức file và folder thông minh dựa trên ngữ cảnh, tìm file trùng lặp, đề xuất cấu trúc tốt hơn. | `skills/file-organizer` | -| **file-uploads** | ⚪ | Chuyên gia xử lý upload file và lưu trữ đám mây (S3, R2, presigned URLs, multipart uploads). | `skills/file-uploads` | -| **finishing-a-development-branch** | ⚪ | Dùng khi hoàn thành cài đặt, tất cả test đã pass, và cần quyết định cách tích hợp (merge, PR, cleanup). | `skills/finishing-a-development-branch` | -| **firebase** | ⚪ | Chuyên gia Firebase: Authentication, Firestore, Realtime Database, Cloud Functions, Storage, Hosting. | `skills/firebase` | -| **firecrawl-scraper** | ⚪ | Deep web scraping, chụp ảnh màn hình, phân tích PDF, và cào website sử dụng Firecrawl API. | `skills/firecrawl-scraper` | -| **form-cro** | ⚪ | Tối ưu hóa bất kỳ form nào KHÔNG phải là đăng ký tài khoản (lead capture, contact, checkout...). | `skills/form-cro` | -| **free-tool-strategy** | ⚪ | Lên kế hoạch, đánh giá hoặc xây dựng công cụ miễn phí cho mục đích marketing (engineering as marketing). | `skills/free-tool-strategy` | -| **frontend-design** | ⚪ | Tạo giao diện frontend đặc sắc, chất lượng cao, thẩm mỹ có chủ đích (không chung chung). | `skills/frontend-design` | -| **frontend-dev-guidelines** | ⚪ | Tiêu chuẩn phát triển frontend (có quan điểm riêng) cho ứng dụng React + TypeScript hiện đại. | `skills/frontend-dev-guidelines` | -| **frontend-patterns** | ⚪ | Các pattern frontend cho React, Next.js, quản lý state, tối ưu hiệu năng. | `skills/cc-skill-frontend-patterns` | -| **game-art** | ⚪ | Nguyên tắc nghệ thuật game. Chọn phong cách hình ảnh, pipeline tài sản, quy trình hoạt hình. | `skills/game-development/game-art` | -| **game-audio** | ⚪ | Nguyên tắc âm thanh game. Thiết kế âm thanh, tích hợp nhạc, hệ thống âm thanh thích ứng. | `skills/game-development/game-audio` | -| **game-design** | ⚪ | Nguyên tắc thiết kế game. Cấu trúc GDD, cân bằng game, tâm lý người chơi. | `skills/game-development/game-design` | -| **game-development** | ⚪ | Bộ điều phối phát triển game. Định tuyến đến các skill cụ thể theo nền tảng dựa trên nhu cầu dự án. | `skills/game-development` | -| **gcp-cloud-run** | ⚪ | Kỹ năng chuyên sâu xây dựng ứng dụng serverless trên GCP (Cloud Run, Cloud Run Functions, Pub/Sub). | `skills/gcp-cloud-run` | -| **geo-fundamentals** | ⚪ | Generative Engine Optimization (GEO) cho các công cụ tìm kiếm AI (ChatGPT, Claude, Perplexity). | `skills/geo-fundamentals` | -| **git-pushing** | ⚪ | Stage, commit, và push thay đổi git với commit message chuẩn "conventional commit". | `skills/git-pushing` | -| **github-workflow-automation** | ⚪ | Tự động hóa quy trình GitHub với sự hỗ trợ của AI (PR reviews, issue triage, CI/CD, Git operations). | `skills/github-workflow-automation` | -| **graphql** | ⚪ | Thiết kế schema GraphQL, resolvers, DataLoader ngăn chặn N+1, federation cho microservices. | `skills/graphql` | -| **HTML Injection Testing** | ⚪ | Hướng dẫn test lỗi HTML injection, deface ứng dụng web, content injection. | `skills/html-injection-testing` | -| **hubspot-integration** | ⚪ | Các mẫu tích hợp HubSpot CRM bao gồm OAuth, CRM objects, webhooks, custom objects. | `skills/hubspot-integration` | -| **i18n-localization** | ⚪ | Các mẫu Quốc tế hóa (i18n) và Bản địa hóa (localization). Phát hiện chuỗi hardcoded, quản lý dịch. | `skills/i18n-localization` | -| **IDOR Vulnerability Testing** | ⚪ | Hướng dẫn test lỗi IDOR (Insecure Direct Object References), broken access control. | `skills/idor-testing` | -| **inngest** | ⚪ | Chuyên gia Inngest cho background jobs serverless-first, luồng công việc theo sự kiện (event-driven). | `skills/inngest` | -| **interactive-portfolio** | ⚪ | Chuyên gia xây dựng portfolio giúp trúng tuyển công việc và khách hàng - không chỉ show tác phẩm mà tạo trải nghiệm. | `skills/interactive-portfolio` | -| **internal-comms** | ⚪ | Tài nguyên viết truyền thông nội bộ (official Anthropic context). | `skills/internal-comms-anthropic` | -| **internal-comms** | ⚪ | Tài nguyên viết truyền thông nội bộ (community context). | `skills/internal-comms-community` | -| **javascript-mastery** | ⚪ | Tài liệu tham khảo JavaScript toàn diện bao gồm 33+ khái niệm cốt lõi mọi developer cần biết. | `skills/javascript-mastery` | -| **kaizen** | ⚪ | Hướng dẫn cải tiến liên tục, phòng chống lỗi (error proofing) và tiêu chuẩn hóa. | `skills/kaizen` | -| **langfuse** | ⚪ | Chuyên gia Langfuse - nền tảng LLM observability. Tracing, quản lý prompt, đánh giá (evaluation). | `skills/langfuse` | -| **langgraph** | ⚪ | Chuyên gia LangGraph - framework xây dựng ứng dụng AI đa tác nhân có trạng thái (stateful). | `skills/langgraph` | -| **last30days** | ⚪ | Nghiên cứu một chủ đề trong 30 ngày qua trên Reddit + X + Web, trở thành chuyên gia và viết prompt. | `skills/last30days` | -| **launch-strategy** | ⚪ | Lên kế hoạch ra mắt sản phẩm, công bố tính năng, chiến lược go-to-market. | `skills/launch-strategy` | -| **lint-and-validate** | ⚪ | Quy trình kiểm soát chất lượng tự động, linting và phân tích tĩnh (static analysis). | `skills/lint-and-validate` | -| **Linux Privilege Escalation** | ⚪ | Hướng dẫn leo thang đặc quyền trên Linux: sudo, SUID, cron jobs, kernel exploits. | `skills/linux-privilege-escalation` | -| **Linux Production Shell Scripts** | ⚪ | Các mẫu shell script production-ready cho quản trị hệ thống Linux. | `skills/linux-shell-scripting` | -| **llm-app-patterns** | ⚪ | Các mẫu production-ready để xây dựng ứng dụng LLM (RAG pipelines, agent architectures, LLMOps). | `skills/llm-app-patterns` | -| **loki-mode** | ⚪ | Hệ thống startup tự động đa tác nhân cho Claude Code. Điều phối 100+ agent chuyên biệt. (Yêu cầu cờ --dangerously-skip-permissions). | `skills/loki-mode` | -| **marketing-ideas** | ⚪ | Cung cấp chiến lược marketing đã được kiểm chứng và ý tưởng tăng trưởng cho SaaS/software. | `skills/marketing-ideas` | -| **marketing-psychology** | ⚪ | Áp dụng khoa học hành vi và mô hình tư duy vào các quyết định marketing. | `skills/marketing-psychology` | -| **mcp-builder** | ⚪ | Hướng dẫn tạo MCP (Model Context Protocol) servers chất lượng cao (Python/Node). | `skills/mcp-builder` | -| **Metasploit Framework** | ⚪ | Hướng dẫn sử dụng Metasploit: msfconsole, msfvenom, post-exploitation, auxiliary modules. | `skills/metasploit-framework` | -| **micro-saas-launcher** | ⚪ | Chuyên gia ra mắt sản phẩm SaaS nhỏ (micro-SaaS) nhanh chóng - tiếp cận kiểu indie hacker. | `skills/micro-saas-launcher` | -| **mobile-design** | ⚪ | Học thuyết thiết kế và kỹ thuật mobile-first cho iOS và Android (React Native, Flutter, Native). | `skills/mobile-design` | -| **mobile-games** | ⚪ | Nguyên tắc phát triển game mobile. Cảm ứng, pin, hiệu năng, app stores. | `skills/game-development/mobile-games` | -| **moodle-external-api-development** | ⚪ | Tạo web service APIs tùy chỉnh bên ngoài cho Moodle LMS. | `skills/moodle-external-api-development` | -| **multi-agent-brainstorming** | ⚪ | Điều phối quy trình đánh giá thiết kế đa tác nhân tuần tự, có cấu trúc để giảm rủi ro. | `skills/multi-agent-brainstorming` | -| **multiplayer** | ⚪ | Nguyên tắc phát triển game multiplayer. Kiến trúc, mạng, đồng bộ hóa. | `skills/game-development/multiplayer` | -| **neon-postgres** | ⚪ | Các mẫu chuyên gia cho Neon serverless Postgres, branching, connection pooling. | `skills/neon-postgres` | -| **nestjs-expert** | ⚪ | Chuyên gia framework Nest.js: module architecture, dependency injection, guards, interceptors. | `skills/nestjs-expert` | -| **Network 101** | ⚪ | Hướng dẫn cơ bản về mạng: thiết lập web server, HTTP/HTTPS, SNMP, SMB, test services. | `skills/network-101` | -| **nextjs-best-practices** | ⚪ | Nguyên tắc Next.js App Router. Server Components, data fetching, routing patterns. | `skills/nextjs-best-practices` | -| **nextjs-supabase-auth** | ⚪ | Tích hợp chuyên gia Supabase Auth với Next.js App Router. | `skills/nextjs-supabase-auth` | -| **nodejs-best-practices** | ⚪ | Nguyên tắc phát triển Node.js. Chọn framework, async patterns, bảo mật. | `skills/nodejs-best-practices` | -| **nosql-expert** | ⚪ | Hướng dẫn chuyên môn cho databases NoSQL phân tán (Cassandra, DynamoDB). | `skills/nosql-expert` | -| **notebooklm** | ⚪ | Truy vấn Google NotebookLM notebooks trực tiếp từ Claude Code để có câu trả lời có trích dẫn. | `skills/notebooklm` | -| **notion-template-business** | ⚪ | Chuyên gia xây dựng và bán Notion templates như một mô hình kinh doanh. | `skills/notion-template-business` | -| **obsidian-clipper-template-creator** | ⚪ | Hướng dẫn tạo template cho Obsidian Web Clipper. | `skills/obsidian-clipper-template-creator` | -| **onboarding-cro** | ⚪ | Tối ưu hóa onboarding sau đăng ký, kích hoạt người dùng (user activation), time-to-value. | `skills/onboarding-cro` | -| **page-cro** | ⚪ | Phân tích và tối ưu hóa các trang đơn lẻ (homepage, landing page) để tăng tỷ lệ chuyển đổi. | `skills/page-cro` | -| **paid-ads** | ⚪ | Hỗ trợ chiến dịch quảng cáo trả phí trên Google Ads, Meta, LinkedIn, Twitter/X. | `skills/paid-ads` | -| **parallel-agents** | ⚪ | Các mẫu điều phối đa tác nhân song song (parallel orchestration). | `skills/parallel-agents` | -| **paywall-upgrade-cro** | ⚪ | Tạo hoặc tối ưu in-app paywalls, màn hình nâng cấp, upsell modals. | `skills/paywall-upgrade-cro` | -| **pc-games** | ⚪ | Nguyên tắc phát triển game PC/Console. Chọn engine, tối ưu hóa. | `skills/game-development/pc-games` | -| **pdf** | ⚪ | Bộ công cụ xử lý PDF toàn diện: trích xuất text/table, merge/split, xử lý form. (Bản Official) | `skills/pdf-official` | -| **Pentest Checklist** | ⚪ | Danh sách kiểm tra và lên kế hoạch cho một cuộc kiểm thử xâm nhập (pentest). | `skills/pentest-checklist` | -| **Pentest Commands** | ⚪ | Các lệnh pentest thiết yếu: nmap, metasploit, hydra, john, nikto... | `skills/pentest-commands` | -| **performance-profiling** | ⚪ | Nguyên tắc hồ sơ hiệu năng (profiling). Đo lường, phân tích và tối ưu hóa. | `skills/performance-profiling` | -| **personal-tool-builder** | ⚪ | Chuyên gia xây dựng các công cụ tùy chỉnh (custom tools) để giải quyết vấn đề cá nhân (scratch your own itch). | `skills/personal-tool-builder` | -| **plaid-fintech** | ⚪ | Các mẫu tích hợp Plaid API: Link token, transactions sync, identity verification, ACH auth. | `skills/plaid-fintech` | -| **plan-writing** | ⚪ | Lập kế hoạch tác vụ có cấu trúc với các phân rã rõ ràng, phụ thuộc và tiêu chí xác minh. | `skills/plan-writing` | -| **planning-with-files** | ⚪ | Triển khai lập kế hoạch dựa trên file kiểu Manus (task_plan.md, findings.md...) cho các tác vụ phức tạp. | `skills/planning-with-files` | -| **playwright-skill** | ⚪ | Tự động hóa trình duyệt hoàn chỉnh với Playwright. Test web, fill forms, screenshots. | `skills/playwright-skill` | -| **popup-cro** | ⚪ | Tạo và tối ưu popups, modals, overlays để tăng chuyển đổi mà không gây khó chịu. | `skills/popup-cro` | -| **powershell-windows** | ⚪ | Các mẫu PowerShell Windows. Cạm bẫy quan trọng, cú pháp operator, xử lý lỗi. | `skills/powershell-windows` | -| **pptx** | ⚪ | Tạo, chỉnh sửa và phân tích bài thuyết trình PowerPoint (.pptx). (Bản Official) | `skills/pptx-official` | -| **pricing-strategy** | ⚪ | Thiết kế chiến lược giá, đóng gói và kiếm tiền dựa trên giá trị và mục tiêu tăng trưởng. | `skills/pricing-strategy` | -| **prisma-expert** | ⚪ | Chuyên gia Prisma ORM: thiết kế schema, migrations, tối ưu query. | `skills/prisma-expert` | -| **Privilege Escalation Methods** | ⚪ | Các phương pháp leo thang đặc quyền chung: post-exploitation cho Linux/Windows. | `skills/privilege-escalation-methods` | -| **product-manager-toolkit** | ⚪ | Bộ công cụ toàn diện cho Product Manager (RICE, phỏng vấn khách hàng, PRD, GTM). | `skills/product-manager-toolkit` | -| **production-code-audit** | ⚪ | Tự động quét sâu codebase, hiểu kiến trúc và chuyển đổi sang chất lượng production-grade. | `skills/production-code-audit` | -| **programmatic-seo** | ⚪ | Thiết kế và đánh giá chiến lược SEO lập trình (programmatic SEO) để tạo trang quy mô lớn. | `skills/programmatic-seo` | -| **prompt-caching** | ⚪ | Các chiến lược caching cho LLM prompts (Anthropic prompt caching, CAG). | `skills/prompt-caching` | -| **prompt-engineer** | ⚪ | Chuyên gia thiết kế prompt hiệu quả cho ứng dụng LLM. Few-shot, Chain of Thought... | `skills/prompt-engineer` | -| **prompt-engineering** | ⚪ | Hướng dẫn chuyên gia về các mẫu prompt engineering, best practices và kỹ thuật tối ưu hóa. | `skills/prompt-engineering` | -| **prompt-library** | ⚪ | Bộ sưu tập các prompt chất lượng cao được tuyển chọn cho nhiều trường hợp sử dụng. | `skills/prompt-library` | -| **python-patterns** | ⚪ | Nguyên tắc phát triển Python. Chọn framework, async patterns, type hints. | `skills/python-patterns` | -| **rag-engineer** | ⚪ | Chuyên gia xây dựng hệ thống RAG (Retrieval-Augmented Generation). | `skills/rag-engineer` | -| **rag-implementation** | ⚪ | Các mẫu triển khai RAG bao gồm chunking, embeddings, vector stores. | `skills/rag-implementation` | -| **react-patterns** | ⚪ | Các mẫu React hiện đại. Hooks, composition, hiệu năng, TypeScript best practices. | `skills/react-patterns` | -| **react-ui-patterns** | ⚪ | Các mẫu React UI hiện đại cho loading states, error handling, và data fetching. | `skills/react-ui-patterns` | -| **receiving-code-review** | ⚪ | Dùng khi nhận phản hồi code review, trước khi thực hiện để xác minh kỹ thuật. | `skills/receiving-code-review` | -| **Red Team Tools and Methodology** | ⚪ | Phương pháp và công cụ Red Team: bug bounty hunting, trinh sát tự động, XSS hunting... | `skills/red-team-tools` | -| **red-team-tactics** | ⚪ | Nguyên tắc chiến thuật Red Team dựa trên MITRE ATT&CK. | `skills/red-team-tactics` | -| **referral-program** | ⚪ | Tạo, tối ưu và phân tích chương trình giới thiệu, affiliate, hoặc chiến lược truyền miệng. | `skills/referral-program` | -| **remotion-best-practices** | ⚪ | Best practices cho Remotion - Tạo video bằng React. | `skills/remotion-best-practices` | -| **requesting-code-review** | ⚪ | Dùng khi hoàn thành tác vụ, trước khi merge để xác minh công việc đáp ứng yêu cầu. | `skills/requesting-code-review` | -| **research-engineer** | ⚪ | Kỹ sư nghiên cứu học thuật không khoan nhượng. Tập trung vào tính chính xác lý thuyết và xác minh hình thức. | `skills/research-engineer` | -| **salesforce-development** | ⚪ | Các mẫu chuyên gia phát triển Salesforce (LWC, Apex, APIs, Salesforce DX). | `skills/salesforce-development` | -| **schema-markup** | ⚪ | Thiết kế, validate và tối ưu schema.org structured data cho SEO. | `skills/schema-markup` | -| **scroll-experience** | ⚪ | Chuyên gia xây dựng trải nghiệm cuộn (scroll-driven experiences) - parallax, scrollytelling. | `skills/scroll-experience` | -| **Security Scanning Tools** | ⚪ | Hướng dẫn sử dụng các công cụ quét bảo mật mạng, web, cloud. | `skills/scanning-tools` | -| **security-review** | ⚪ | Danh sách kiểm tra bảo mật toàn diện khi thêm auth, xử lý input, secrets, API. | `skills/cc-skill-security-review` | -| **segment-cdp** | ⚪ | Các mẫu chuyên gia cho Segment CDP (Analytics.js, Protocols, identity resolution). | `skills/segment-cdp` | -| **senior-architect** | ⚪ | Kỹ năng kiến trúc phần mềm toàn diện cho việc thiết kế hệ thống mở rộng, dễ bảo trì. | `skills/senior-architect` | -| **senior-fullstack** | ⚪ | Kỹ năng phát triển fullstack toàn diện (React, Next.js, Node.js, GraphQL, PostgreSQL). | `skills/senior-fullstack` | -| **seo-audit** | ⚪ | Chẩn đoán và kiểm toán các vấn đề SEO ảnh hưởng đến khả năng thu thập dữ liệu, lập chỉ mục và xếp hạng. | `skills/seo-audit` | -| **seo-fundamentals** | ⚪ | Các nguyên tắc cốt lõi của SEO (E-E-A-T, Core Web Vitals, nền tảng kỹ thuật). | `skills/seo-fundamentals` | -| **server-management** | ⚪ | Nguyên tắc quản lý máy chủ. Quản lý quy trình, giám sát, mở rộng. | `skills/server-management` | -| **Shodan Reconnaissance and Pentesting** | ⚪ | Hướng dẫn sử dụng Shodan để trinh sát và pentest: tìm thiết bị lộ lọt, scan IP ranges... | `skills/shodan-reconnaissance` | -| **shopify-apps** | ⚪ | Các mẫu chuyên gia phát triển ứng dụng Shopify (Remix, App Bridge, GraphQL Admin API). | `skills/shopify-apps` | -| **shopify-development** | ⚪ | Xây dựng Shopify apps, extensions, themes dùng GraphQL, CLI, Polaris, Liquid. | `skills/shopify-development` | -| **signup-flow-cro** | ⚪ | Tối ưu hóa quy trình đăng ký, tạo tài khoản, kích hoạt dùng thử. | `skills/signup-flow-cro` | -| **skill-creator** | ⚪ | Hướng dẫn tạo skill hiệu quả. Dùng khi user muốn tạo skill mới hoặc cập nhật skill cũ. | `skills/skill-creator` | -| **skill-developer** | ⚪ | Tạo và quản lý Claude Code skills theo best practices của Anthropic. | `skills/skill-developer` | -| **slack-bot-builder** | ⚪ | Xây dựng Slack apps sử dụng Bolt framework (Python/JS/Java). Block Kit, slash commands. | `skills/slack-bot-builder` | -| **slack-gif-creator** | ⚪ | Kiến thức và tiện ích để tạo GIF hoạt hình tối ưu cho Slack. | `skills/slack-gif-creator` | -| **SMTP Penetration Testing** | ⚪ | Hướng dẫn pentest SMTP: enumerate users, open mail relays, brute force. | `skills/smtp-penetration-testing` | -| **social-content** | ⚪ | Hỗ trợ tạo, lên lịch, tối ưu nội dung mạng xã hội (LinkedIn, Twitter, Instagram...). | `skills/social-content` | -| **software-architecture** | ⚪ | Hướng dẫn kiến trúc phần mềm tập trung vào chất lượng. | `skills/software-architecture` | -| **SQL Injection Testing** | ⚪ | Hướng dẫn test lỗi SQL Injection (SQLi), khai thác lỗ hổng truy vấn database. | `skills/sql-injection-testing` | -| **SQLMap Database Penetration Testing** | ⚪ | Hướng dẫn sử dụng SQLMap để tự động hóa test SQL injection và dump database. | `skills/sqlmap-database-pentesting` | -| **SSH Penetration Testing** | ⚪ | Hướng dẫn pentest SSH: enumerate config, brute force, exploit vulnerabilities. | `skills/ssh-penetration-testing` | -| **stripe-integration** | ⚪ | Hướng dẫn tích hợp Stripe toàn diện: Payments, subscriptions, billing portal, webhooks. | `skills/stripe-integration` | -| **subagent-driven-development** | ⚪ | Dùng khi thực thi kế hoạch triển khai với các nhiệm vụ độc lập trong phiên hiện tại. | `skills/subagent-driven-development` | -| **supabase-postgres-best-practices** | ⚪ | Tối ưu hóa hiệu năng Postgres và best practices từ Supabase. | `skills/postgres-best-practices` | -| **systematic-debugging** | ⚪ | Dùng khi gặp bug, test fail hoặc hành vi không mong muốn, trước khi đề xuất sửa lỗi. | `skills/systematic-debugging` | -| **tailwind-patterns** | ⚪ | Nguyên tắc Tailwind CSS v4. Cấu hình CSS-first, container queries, design token. | `skills/tailwind-patterns` | -| **tavily-web** | ⚪ | Tìm kiếm web, trích xuất nội dung, crawling và nghiên cứu sử dụng Tavily API. | `skills/tavily-web` | -| **tdd-workflow** | ⚪ | Quy trình Test-Driven Development (TDD). Vòng lặp RED-GREEN-REFACTOR. | `skills/tdd-workflow` | -| **telegram-bot-builder** | ⚪ | Chuyên gia xây dựng Telegram bot. Bot API, UX, kiếm tiền, scaling. | `skills/telegram-bot-builder` | -| **telegram-mini-app** | ⚪ | Chuyên gia xây dựng Telegram Mini Apps (TWA). Hệ sinh thái TON, payments, auth. | `skills/telegram-mini-app` | -| **templates** | ⚪ | Các mẫu khung dự án (project scaffolding) cho ứng dụng mới. | `skills/app-builder/templates` | -| **test-driven-development** | ⚪ | Dùng khi triển khai tính năng hoặc sửa lỗi, trước khi viết code triển khai. | `skills/test-driven-development` | -| **test-fixing** | ⚪ | Chạy test và sửa lỗi systematically. | `skills/test-fixing` | -| **testing-patterns** | ⚪ | Các mẫu Jest testing, factory functions, mocking strategies, TDD workflow. | `skills/testing-patterns` | -| **theme-factory** | ⚪ | Bộ công cụ tạo theme cho các artifact (slides, docs, landing pages). 10 pre-set themes. | `skills/theme-factory` | -| **Top 100 Web Vulnerabilities Reference** | ⚪ | Tham chiếu toàn diện về Top 100 lỗ hổng web (OWASP-aligned). | `skills/top-web-vulnerabilities` | -| **trigger-dev** | ⚪ | Chuyên gia Trigger.dev cho background jobs, AI workflows, reliable async execution. | `skills/trigger-dev` | -| **twilio-communications** | ⚪ | Xây dựng tính năng giao tiếp với Twilio: SMS, Voice, WhatsApp, Verify (2FA). | `skills/twilio-communications` | -| **typescript-expert** | ⚪ | Chuyên gia TypeScript/JavaScript: type-level programming, tối ưu hiệu năng, monorepo. | `skills/typescript-expert` | -| **ui-ux-pro-max** | ⚪ | Trí tuệ thiết kế UI/UX. 50 kiểu, 21 bảng màu, 50 cặp font... Shadow, gradient, layout. | `skills/ui-ux-pro-max` | -| **upstash-qstash** | ⚪ | Chuyên gia Upstash QStash cho serverless message queues, scheduled jobs. | `skills/upstash-qstash` | -| **using-git-worktrees** | ⚪ | Dùng khi bắt đầu công việc tính năng cần cô lập, tạo git worktrees. | `skills/using-git-worktrees` | -| **using-superpowers** | ⚪ | Dùng khi bắt đầu hội thoại - thiết lập cách tìm và dùng skill. | `skills/using-superpowers` | -| **vercel-deployment** | ⚪ | Kiến thức chuyên gia để deploy lên Vercel với Next.js. | `skills/vercel-deployment` | -| **vercel-react-best-practices** | ⚪ | Hướng dẫn tối ưu hiệu năng React và Next.js từ Vercel Engineering. | `skills/react-best-practices` | -| **verification-before-completion** | ⚪ | Dùng trước khi tuyên bố hoàn thành, chạy lệnh xác minh và xác nhận output. | `skills/verification-before-completion` | -| **viral-generator-builder** | ⚪ | Chuyên gia xây dựng các công cụ tạo nội dung viral (quiz, name generator, avatar creator). | `skills/viral-generator-builder` | -| **voice-agents** | ⚪ | Xây dựng voice agents - giao tiếp tự nhiên với AI. Xử lý độ trễ, ngắt lời. | `skills/voice-agents` | -| **voice-ai-development** | ⚪ | Chuyên gia phát triển ứng dụng Voice AI (OpenAI Realtime API, Vapi, Deepgram). | `skills/voice-ai-development` | -| **voice-ai-engine-development** | ⚪ | Xây dựng voice engines AI thời gian thực sử dụng async worker pipelines. | `skills/voice-ai-engine-development` | -| **vr-ar** | ⚪ | Nguyên tắc phát triển VR/AR. Thoải mái, tương tác, hiệu năng. | `skills/game-development/vr-ar` | -| **vulnerability-scanner** | ⚪ | Nguyên tắc phân tích lỗ hổng nâng cao. OWASP 2025, Supply Chain Security. | `skills/vulnerability-scanner` | -| **web-artifacts-builder** | ⚪ | Bộ công cụ tạo artifact web phức tạp, đa thành phần (React, Tailwind, shadcn/ui). | `skills/web-artifacts-builder` | -| **web-design-guidelines** | ⚪ | Review code UI tuân thủ Web Interface Guidelines. | `skills/web-design-guidelines` | -| **web-games** | ⚪ | Nguyên tắc phát triển game web. Framework, WebGPU, PWA. | `skills/game-development/web-games` | -| **web-performance-optimization** | ⚪ | Tối ưu hóa hiệu năng website và ứng dụng web (Core Web Vitals, bundle size). | `skills/web-performance-optimization` | -| **webapp-testing** | ⚪ | Bộ công cụ tương tác và test ứng dụng web cục bộ sử dụng Playwright. | `skills/webapp-testing` | -| **Windows Privilege Escalation** | ⚪ | Hướng dẫn leo thang đặc quyền trên Windows: misconfigurations, post-exploitation. | `skills/windows-privilege-escalation` | -| **Wireshark Network Traffic Analysis** | ⚪ | Hướng dẫn phân tích lưu lượng mạng bằng Wireshark: capture packets, filter, analyze protocols. | `skills/wireshark-analysis` | -| **WordPress Penetration Testing** | ⚪ | Hướng dẫn pentest WordPress: scan vulnerabilities, enumerate plugins, exploit hacks. | `skills/wordpress-penetration-testing` | -| **workflow-automation** | ⚪ | Tự động hóa quy trình (n8n, Temporal, Inngest). Biến script dễ vỡ thành automation bền vững. | `skills/workflow-automation` | -| **writing-plans** | ⚪ | Dùng khi bạn có spec hoặc yêu cầu cho tác vụ đa bước, trước khi viết code. | `skills/writing-plans` | -| **writing-skills** | ⚪ | Dùng khi tạo skill mới, chỉnh sửa skill, hoặc xác minh skill hoạt động. | `skills/writing-skills` | -| **xlsx** | ⚪ | Xử lý bảng tính toàn diện: Tạo mới, công thức, định dạng, phân tích dữ liệu. (Bản Official) | `skills/xlsx-official` | -| **zapier-make-patterns** | ⚪ | Các mẫu tự động hóa No-code (Zapier, Make). Khi nào dùng, cạm bẫy, và khi nào nên code. | `skills/zapier-make-patterns` | - ---- - -## Hướng dẫn cài đặt nhanh - -Để sở hữu bộ skill này cho **Claude Code**, **Gemini CLI**, **Codex CLI**, **Cursor**, **Antigravity**, hay **OpenCode**, bạn chỉ cần clone repo này vào thư mục skills tương ứng của agent: - -```bash -# Cài đặt chung (Dùng được cho đa số công cụ) -git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills - -# Dành riêng cho Claude Code -git clone https://github.com/sickn33/antigravity-awesome-skills.git .claude/skills - -# Dành riêng cho Gemini CLI -git clone https://github.com/sickn33/antigravity-awesome-skills.git .gemini/skills - -# Dành riêng cho Cursor -git clone https://github.com/sickn33/antigravity-awesome-skills.git .cursor/skills -``` - ---- - -## Bạn muốn đóng góp? - -Chúng tôi nồng nhiệt chào đón mọi đóng góp từ cộng đồng! Để thêm một skill mới, bạn làm như sau: - -1. **Fork** repository này về. -2. **Tạo thư mục mới** trong `skills/` cho skill của bạn. -3. **Thêm file `SKILL.md`** với đầy đủ frontmatter (name và description) theo mẫu. -4. **Chạy kiểm tra (validation)**: `python3 scripts/validate_skills.py`. -5. **Gửi Pull Request**. - -Vui lòng đảm bảo skill của bạn tuân thủ các quy chuẩn (best practices) của Antigravity/Claude Code nhé. - ---- - -## Lời cảm ơn & Nguồn tham khảo - -Chúng tôi phát triển dự án này dựa trên những nền tảng tri thức vững chắc từ những người đi trước. - -👉 **[Xem danh sách ghi nhận đầy đủ](SOURCES.md)** - -Các nguồn cảm hứng và đóng góp to lớn bao gồm: - -- **HackTricks** -- **OWASP** -- **Anthropic / OpenAI / Google** -- **Cộng đồng nguồn mở (Open Source Community)** - ---- - -## Bản quyền (License) - -Dự án được phát hành dưới giấy phép MIT. Xem file [LICENSE](../../LICENSE) để biết thêm chi tiết. - ---- - -## Những người hùng đã đóng góp - -Chúng tôi trân trọng mọi sự đóng góp của các bạn! - -- [sck_0](https://github.com/sck_0) -- [Munir Abbasi](https://github.com/munirabbasi) -- [Mohammad Faiz](https://github.com/mohdfaiz2k9) -- [GuppyTheCat](https://github.com/GuppyTheCat) -- [sickn33](https://github.com/sickn33) -- [Ianj332](https://github.com/Ianj332) -- [Tiger-Foxx](https://github.com/Tiger-Foxx) -- [arathiesh](https://github.com/arathiesh) -- [1bcMax](https://github.com/1bcMax) -- [Ahmed Rehan](https://github.com/ar27111994) -- [BenedictKing](https://github.com/BenedictKing) -- [Nguyen Huu Loc](https://github.com/LocNguyenSGU) -- [Owen Wu](https://github.com/yubing744) -- [SuperJMN](https://github.com/SuperJMN) -- [Viktor Ferenczi](https://github.com/viktor-ferenczi) -- [krisnasantosa15](https://github.com/krisnasantosa15) -- [zebbern](https://github.com/zebbern) -- [vuth-dogo](https://github.com/vuth-dogo) -- [Takura](https://github.com/taksrules) -- [rafy](https://github.com/raeef1001) -- [Đỗ Khắc Gia Khoa](https://github.com/dokhacgiakhoa) - -## Lịch sử phát triển - -[![Star History Chart](https://api.star-history.com/svg?repos=sickn33/antigravity-awesome-skills&type=date&legend=top-left)](https://www.star-history.com/#sickn33/antigravity-awesome-skills&type=date&legend=top-left) diff --git a/docs/vi/SOURCES.md b/docs/vi/SOURCES.md deleted file mode 100644 index bdea39aa..00000000 --- a/docs/vi/SOURCES.md +++ /dev/null @@ -1,21 +0,0 @@ -# 📜 Nguồn Tham Khảo & Ghi Nhận - -Chúng tôi tin vào việc tôn trọng quyền tác giả và nguồn gốc tri thức. -Nếu bạn thấy tác phẩm của mình ở đây mà chưa được ghi nhận xứng đáng, vui lòng mở Issue để chúng tôi cập nhật. - -| Skill / Danh mục | Nguồn Gốc | Giấy Phép | Ghi chú | -| :-------------------------- | :----------------------------------------------------- | :------------- | :---------------------------- | -| `cloud-penetration-testing` | [HackTricks](https://book.hacktricks.xyz/) | MIT / CC-BY-SA | Đã điều chỉnh cho Agent dùng. | -| `active-directory-attacks` | [HackTricks](https://book.hacktricks.xyz/) | MIT / CC-BY-SA | Đã điều chỉnh cho Agent dùng. | -| `owasp-top-10` | [OWASP](https://owasp.org/) | CC-BY-SA | Phương pháp luận đã điều chỉnh.| -| `burp-suite-testing` | [PortSwigger](https://portswigger.net/burp) | N/A | Chỉ hướng dẫn sử dụng (không kèm phần mềm). | -| `crewai` | [CrewAI](https://github.com/joaomdmoura/crewAI) | MIT | Hướng dẫn Framework. | -| `langgraph` | [LangGraph](https://github.com/langchain-ai/langgraph) | MIT | Hướng dẫn Framework. | -| `react-patterns` | [React Docs](https://react.dev/) | CC-BY | Các mẫu chính thức. | -| **Các Skill Official** | [Anthropic / Google / OpenAI] | Độc quyền | Được khuyến khích sử dụng bởi nhà cung cấp. | - -## Chính sách Giấy phép - -- **Mã nguồn (Code)**: Tất cả code gốc trong repo này là **MIT**. -- **Nội dung (Content)**: Tài liệu là **CC-BY-4.0**. -- **Bên thứ ba**: Chúng tôi tôn trọng giấy phép gốc. Nếu một skill được import là GPL, nó sẽ được ghi chú rõ ràng hoặc loại bỏ (chúng tôi ưu tiên tương thích MIT/Apache). diff --git a/docs/vietnamese/BUNDLES.md b/docs/vietnamese/BUNDLES.md new file mode 100644 index 00000000..01496aec --- /dev/null +++ b/docs/vietnamese/BUNDLES.md @@ -0,0 +1,124 @@ +# 📦 Gói Kỹ năng Antigravity (Skill Bundles) + +Bạn không biết bắt đầu từ đâu? Hãy chọn một gói dưới đây để sỡ hữu bộ kỹ năng được tuyển chọn phù hợp cho vai trò của bạn. + +## 🚀 Gói Khởi đầu "Thiết yếu" (Essentials) + +_Dành cho tất cả mọi người. Hãy cài đặt những kỹ năng này đầu tiên._ + +- `concise-planning`: Luôn bắt đầu bằng một kế hoạch. +- `lint-and-validate`: Giữ code sạch sẽ một cách tự động. +- `git-pushing`: Lưu công việc của bạn một cách an toàn. +- `kaizen`: Tư duy cải tiến liên tục. + +## 🛡️ Gói "Kỹ sư Bảo mật" (Security Engineer) + +_Dành cho pentesting, kiểm tra (auditing) và tăng cường bảo mật (hardening)._ + +- `ethical-hacking-methodology`: "Kinh thánh" về hacking đạo đức. +- `burp-suite-testing`: Quét lỗ hổng web. +- `owasp-top-10`: Kiểm tra các lỗi phổ biến nhất. +- `linux-privilege-escalation`: Đánh giá bảo mật Linux nâng cao. +- `cloud-penetration-testing`: Bảo mật AWS/Azure/GCP. + +## 🌐 Gói "Phù thủy Web" (Web Wizard) + +_Để xây dựng các ứng dụng web hiện đại, hiệu suất cao._ + +- `frontend-design`: Hướng dẫn về UI và thẩm mỹ. +- `react-patterns`: Các thực hành tốt nhất cho React (nếu có sẵn). +- `tailwind-patterns`: Siêu năng lực tạo kiểu (styling). +- `form-cro`: Tối ưu hóa các biểu mẫu để tăng tỷ lệ chuyển đổi. +- `seo-audit`: Giúp trang web của bạn xuất hiện trên Google. + +## 🤖 Gói "Kiến trúc sư Agent" (Agent Architect) + +_Để xây dựng các hệ thống AI._ + +- `agent-evaluation`: Kiểm tra các trợ lý AI (agents) của bạn. +- `langgraph`: Xây dựng quy trình làm việc agent có trạng thái (stateful). +- `mcp-builder`: Tự tạo các công cụ của riêng bạn. +- `prompt-engineering`: Làm chủ nghệ thuật giao tiếp với LLM. + +## 🎮 Gói "Lập trình viên Game Độc lập" (Indie Game Dev) + +_Đế xây dựng trò chơi với sự trợ giúp của AI._ + +- `game-development/game-design`: Cơ chế và vòng lặp trò chơi. +- `game-development/2d-games`: Sprite và vật lý 2D. +- `game-development/3d-games`: Mô hình 3D và shader. +- `game-development/unity-csharp`: Làm chủ lập trình C#. +- `algorithmic-art`: Tạo tài nguyên game (assets) bằng code. + +## 🐍 Gói "Chuyên gia Python" (Python Pro) + +_Dành cho những người làm backend và các nhà khoa học dữ liệu._ + +- `python-patterns`: Viết code Python chuẩn mực (idiomatic). +- `poetry-manager`: Quản lý phụ thuộc (dependencies) hiệu quả. +- `pytest-mastery`: Các framework kiểm thử. +- `fastapi-expert`: Xây dựng API hiệu suất cao. +- `django-guide`: Framework đầy đủ tính năng "battery-included". + +## 🦄 Gói "Người sáng lập Startup" (Startup Founder) + +_Để xây dựng sản phẩm, không chỉ là viết code._ + +- `product-requirements-doc`: Định nghĩa những gì cần xây dựng. +- `competitor-analysis`: Biết rõ đối thủ của bạn là ai. +- `pitch-deck-creator`: Gọi vốn (hoặc chỉ để giải thích ý tưởng của bạn). +- `landing-page-copy`: Viết nội dung bán hàng hiệu quả. +- `stripe-integration`: Phương thức thanh toán. + +## 🌧️ Gói "DevOps & Cloud" + +_Dành cho hạ tầng và mở rộng hệ thống._ + +- `docker-expert`: Làm chủ container và build đa giai đoạn. +- `aws-serverless`: Sử dụng serverless trên AWS (Lambda, DynamoDB). +- `environment-setup-guide`: Chuẩn hóa cho các đội ngũ. +- `deployment-procedures`: Chiến lược triển khai an toàn. +- `bash-linux`: Làm chủ dòng lệnh Terminal. + +## 📊 Gói "Dữ liệu & Phân tích" (Data & Analytics) + +_Để hiểu rõ các con số._ + +- `analytics-tracking`: Thiết lập GA4/PostHog chính xác. +- `d3-viz`: Các hình ảnh hóa dữ liệu tùy chỉnh đẹp mắt. +- `sql-mastery`: Viết truy vấn tốt hơn (Skill cộng đồng). +- `ab-test-setup`: Học hỏi từ thực nghiệm đã xác thực. + +## 🎨 Gói "Giám đốc Sáng tạo" (Creative Director) + +_Dành cho hình ảnh, nội dung và thương hiệu._ + +- `canvas-design`: Tạo poster và sơ đồ. +- `frontend-design`: Thẩm mỹ UI. +- `content-creator`: Các bài blog tối ưu hóa SEO. +- `copy-editing`: Trau chuốt nội dung văn bản. +- `algorithmic-art`: Các tác phẩm nghệ thuật tạo bằng code. + +## 🐞 Gói "QA & Kiểm thử" (QA & Testing) + +_Để phát hiện lỗi trước khi người dùng thấy._ + +- `test-driven-development`: Red, Green, Refactor. +- `systematic-debugging`: "Sherlock Holmes" trong thế giới code. +- `browser-automation`: Kiểm thử đầu cuối (E2E) với Playwright. +- `ab-test-setup`: Các thử nghiệm đã được xác thực. +- `code-review-checklist`: Phát hiện lỗi trong các Pull Request. + +## 🖌️ Gói "Thiết kế Web" (Web Designer) + +_Để tạo ra những trải nghiệm hoàn hảo đến từng pixel._ + +- `ui-ux-pro-max`: Hệ thống thiết kế/tokens cao cấp. +- `frontend-design`: Nền tảng của thẩm mỹ. +- `3d-web-experience`: Ma thuật của Three.js & R3F. +- `canvas-design`: Hình ảnh tĩnh/poster. +- `responsive-layout`: Các nguyên tắc ưu tiên di động (Mobile-first). + +--- + +_Để sử dụng một gói kỹ năng, chỉ cần copy tên các skill vào thư mục `.agent/skills` của bạn hoặc yêu cầu trợ lý AI sử dụng chúng._ diff --git a/docs/vietnamese/CONTRIBUTING.md b/docs/vietnamese/CONTRIBUTING.md new file mode 100644 index 00000000..4ad15753 --- /dev/null +++ b/docs/vietnamese/CONTRIBUTING.md @@ -0,0 +1,236 @@ +# 🤝 Hướng dẫn Đóng góp - Phiên bản V3 Enterprise + +**Cảm ơn bạn đã muốn làm cho repository này trở nên tốt hơn!** Hướng dẫn này sẽ chỉ cho bạn chính xác cách thức đóng góp, ngay cả khi bạn là người mới đối với mã nguồn mở. +Với phiên bản V3, chúng tôi đã nâng cao các tiêu chuẩn về chất lượng. Vui lòng đọc kỹ **Tiêu chuẩn Chất lượng mới** bên dưới. + +--- + +## 🧐 "Quy chuẩn Chất lượng" (Quality Bar - Tiêu chuẩn V3) + +**Quan trọng đối với các skill mới:** Mỗi skill được gửi đi phải vượt qua **5 bước Kiểm tra Chất lượng** (xem `docs/vietnamese/QUALITY_BAR.md` để biết chi tiết): + +1. **Siêu dữ liệu (Metadata)**: Phần Frontmatter chính xác (`name`, `description`). +2. **An toàn (Safety)**: Không chứa các lệnh gây hại mà không có nhãn rủi ro ("Risk"). +3. **Rõ ràng (Clarity)**: Có phần "Khi nào nên dùng" (When to use) rõ ràng. +4. **Ví dụ (Examples)**: Ít nhất một ví dụ sử dụng có thể sao chép và dùng được ngay. +5. **Hành động (Actions)**: Phải định nghĩa các bước hành động cụ thể cho AI, không chỉ là các "ý nghĩ". + +--- + +## Các Cách để Đóng góp + +Bạn không cần phải là một chuyên gia! Dưới đây là những cách mà bất kỳ ai cũng có thể giúp đỡ: + +### 1. Cải thiện Tài liệu (Dễ nhất!) + +- Sửa lỗi chính tả hoặc ngữ pháp. +- Làm cho các giải thích trở nên rõ ràng hơn. +- Thêm ví dụ vào các kỹ năng hiện có. +- Dịch tài liệu sang các ngôn ngữ khác. + +### 2. Báo cáo Vấn đề (Issues) + +- Thấy điều gì đó khó hiểu? Hãy cho chúng tôi biết! +- Kỹ năng không hoạt động? Hãy báo cho chúng tôi! +- Bạn có đề xuất? Chúng tôi luôn sẵn sàng lắng nghe! + +### 3. Tạo Kỹ năng (Skill) mới + +- Chia sẻ chuyên môn của bạn dưới dạng một kỹ năng. +- Lấp đầy các khoảng trống trong bộ sưu tập hiện tại. +- Cải thiện các kỹ năng sẵn có. + +### 4. Kiểm thử và Xác thực + +- Thử nghiệm các kỹ năng và báo cáo những gì hoạt động hoặc không hoạt động. +- Kiểm tra trên các công cụ AI khác nhau. +- Đề xuất các cải tiến. + +--- + +## Cách Tạo một Kỹ năng mới + +### Hướng dẫn Từng bước + +#### Bước 1: Chọn Chủ đề cho Kỹ năng của bạn + +Hãy tự hỏi: "Tôi ước trợ lý AI của mình hiểu rõ hơn về điều gì?". +Ví dụ: "Tôi giỏi về Docker, tôi sẽ tạo một kỹ năng về Docker". + +#### Bước 2: Tạo Cấu trúc Thư mục + +Các kỹ năng nằm trong thư mục `skills/`. Sử dụng định dạng `kebab-case` cho tên thư mục. + +```bash +# Di chuyển đến thư mục skills +cd skills/ + +# Tạo thư mục cho skill của bạn +mkdir my-awesome-skill +cd my-awesome-skill + +# Tạo file SKILL.md +touch SKILL.md +``` + +#### Bước 3: Viết Nội dung cho SKILL.md + +Mỗi kỹ năng đều cần cấu trúc cơ bản này. **Hãy sao chép mẫu dưới đây:** + +```markdown +--- +name: my-awesome-skill +description: "Mô tả ngắn gọn về chức năng của skill này" +--- + +# Tiêu đề Skill + +## Tổng quan + +Giải thích skill này làm gì và khi nào nên sử dụng nó. + +## Khi nào nên sử dụng Skill này + +- Sử dụng khi [tình huống 1] +- Sử dụng khi [tình huống 2] + +## Cách hoạt động + +Hướng dẫn chi tiết từng bước cho AI... + +## Ví dụ + +### Ví dụ 1 + +\`\`\` +code ví dụ ở đây +\`\`\` + +## Thực hành tốt nhất + +- ✅ Nên làm điều này +- ❌ Không nên làm điều này +``` + +#### Bước 4: Xác thực (BƯỚC V3 QUAN TRỌNG) + +Chạy script xác thực (validation) tại máy của bạn. **Chúng tôi sẽ không chấp nhận các Pull Request (PR) thất bại ở bước kiểm tra này.** + +```bash +# Chế độ nhẹ (chỉ cảnh báo) +python3 scripts/validate_skills.py + +# Chế độ nghiêm ngặt (chế độ mà hệ thống CI sẽ chạy) +python3 scripts/validate_skills.py --strict +``` + +Bước này sẽ kiểm tra: + +- ✅ File `SKILL.md` có tồn tại hay không. +- ✅ Phần Frontmatter có chính xác không. +- ✅ Tên (Name) có khớp với tên thư mục không. +- ✅ Có vượt qua các kiểm tra của Quality Bar không. + +#### Bước 5: Gửi Kỹ năng của bạn + +```bash +git add skills/my-awesome-skill/ +git commit -m "feat: add my-awesome-skill" +git push origin my-branch +``` + +--- + +## Bản mẫu (Template) Kỹ năng (Copy & Paste) + +Tiết kiệm thời gian! Hãy sao chép bản mẫu này: + +```markdown +--- +name: your-skill-name +description: "Mô tả trong một câu về chức năng của skill và khi nào cần dùng" +--- + +# Tên Kỹ năng của bạn + +## Tổng quan + +[2-3 câu giải thích skill này làm gì] + +## Khi nào nên sử dụng Skill này + +- Sử dụng khi bạn cần [tình huống 1] +- Sử dụng khi bạn muốn [tình huống 2] + +## Hướng dẫn Từng bước + +### 1. [Tên Bước đầu tiên] + +[Hướng dẫn chi tiết] + +## Ví dụ + +### Ví dụ 1: [Tên Trường hợp sử dụng] + +\`\`\`language +// Code ví dụ ở đây +\`\`\` + +## Thực hành tốt nhất + +- ✅ **Nên:** [Thực hành tốt] +- ❌ **Không nên:** [Điều cần tránh] + +## Xử lý Sự cố + +**Vấn đề:** [Lỗi thường gặp] +**Giải pháp:** [Cách khắc phục] +``` + +--- + +## Hướng dẫn về Thông điệp Commit (Commit Message) + +Sử dụng các tiền tố sau: + +- `feat:` - Kỹ năng mới hoặc tính năng lớn. +- `docs:` - Cải thiện tài liệu hướng dẫn. +- `fix:` - Sửa lỗi. +- `refactor:` - Cải thiện code mà không thay đổi chức năng. +- `test:` - Thêm hoặc cập nhật các bài kiểm tra. +- `chore:` - Các tác vụ bảo trì. + +**Ví dụ:** + +``` +feat: add kubernetes-deployment skill +docs: improve getting started guide +fix: correct typo in stripe-integration skill +``` + +--- + +## Tài liệu Học tập + +### Bạn mới sử dụng Git/GitHub? + +- [Hướng dẫn Hello World của GitHub](https://guides.github.com/activities/hello-world/) +- [Cơ bản về Git](https://git-scm.com/book/en/v2/Getting-Started-Git-Basics) + +### Bạn mới sử dụng Markdown? + +- [Hướng dẫn Markdown](https://www.markdownguide.org/basic-syntax/) + +--- + +## Quy tắc Ứng xử (Code of Conduct) + +- Luôn tôn trọng và hòa nhập. +- Chào đón những người mới. +- Tập trung vào các phản hồi mang tính xây dựng. +- **Không chứa nội dung gây hại**: Xem `docs/vietnamese/SECURITY_GUARDRAILS.md`. + +--- + +**Cảm ơn bạn đã làm cho dự án này trở nên tốt đẹp hơn cho mọi người!** +Mọi sự đóng góp, dù nhỏ đến đâu, đều tạo nên sự khác biệt. Dù bạn sửa một lỗi chính tả, cải thiện một câu văn, hay tạo ra một kỹ năng hoàn toàn mới - bạn đang giúp đỡ hàng ngàn lập trình viên khác! diff --git a/docs/vietnamese/EXAMPLES.md b/docs/vietnamese/EXAMPLES.md new file mode 100644 index 00000000..25571ec1 --- /dev/null +++ b/docs/vietnamese/EXAMPLES.md @@ -0,0 +1,56 @@ +# 🧪 Ví dụ Thực tế ("Sổ tay Nấu ăn Antigravity") + +Các kỹ năng (skills) vốn dĩ đã mạnh mẽ khi đứng riêng lẻ, nhưng chúng sẽ trở nên không thể ngăn cản khi được kết hợp lại với nhau. +Dưới đây là ba tình huống phổ biến và cách giải quyết chúng bằng cách sử dụng repository này. + +## 🥘 Công thức 1: "Kiểm tra Code cũ (Legacy Code Audit)" + +_Tình huống: Bạn vừa tiếp nhận một repository Node.js 5 năm tuổi đang rất hỗn loạn. Bạn cần sửa nó một cách an toàn._ + +**Các Skill sử dụng:** + +1. `concise-planning` (Để lập bản đồ cho sự hỗn loạn) +2. `lint-and-validate` (Để tìm ra lỗi) +3. `security-audit` (Để tìm ra lỗ hổng bảo mật) + +**Quy trình làm việc (Workflow):** + +1. **Lập kế hoạch**: "Agent, hãy dùng `concise-planning` để tạo một danh sách kiểm tra (checklist) cho việc tái cấu trúc (refactoring) file `src/legacy-api.js`." +2. **Kiểm tra**: "Chạy `security-audit` trên file `package.json` để tìm các thư viện phụ thuộc có lỗ hổng bảo mật." +3. **Sửa lỗi**: "Sử dụng các quy tắc của `lint-and-validate` để tự động sửa các lỗi định dạng trong thư mục `src/`." + +--- + +## 🥘 Công thức 2: "Ứng dụng Web hiện đại" + +_Tình huống: Bạn cần xây dựng một trang Landing Page hiệu suất cao trong vòng 2 giờ._ + +**Các Skill sử dụng:** + +1. `frontend-design` (Để đảm bảo tính thẩm mỹ) +2. `react-patterns` (Để xây dựng cấu trúc) +3. `tailwind-mastery` (Để tăng tốc độ triển khai) + +**Quy trình làm việc (Workflow):** + +1. **Thiết kế**: "Hãy sử dụng `frontend-design` để tạo bảng màu và kiểu chữ cho một 'Quán cà phê phong cách Cyberpunk'." +2. **Khởi tạo**: "Khởi tạo một dự án Vite. Sau đó áp dụng `react-patterns` để tạo component 'Hero'." +3. **Định dạng kiểu dáng**: "Sử dụng `tailwind-mastery` để làm cho các nút bấm có hiệu ứng glassmorphic (hiệu ứng kính mờ) và phản hồi tốt trên nhiều thiết bị (responsive)." + +--- + +## 🥘 Công thức 3: "Kiến trúc sư Agent" + +_Tình huống: Bạn muốn xây dựng một trợ lý AI (agent) tùy chỉnh có khả năng tự xác minh mã code của chính nó._ + +**Các Skill sử dụng:** + +1. `mcp-builder` (Để xây dựng công cụ) +2. `agent-evaluation` (Để kiểm tra độ tin cậy) +3. `prompt-engineering` (Để trau chuốt các hướng dẫn) + +**Quy trình làm việc (Workflow):** + +1. **Xây dựng**: "Sử dụng `mcp-builder` để tạo một công cụ `verify-file`." +2. **Hướng dẫn**: "Áp dụng các mẫu `prompt-engineering` vào System Prompt để agent luôn kiểm tra lại đường dẫn file." +3. **Kiểm tra**: "Chạy `agent-evaluation` để đo lường tần suất agent thất bại trong việc tìm file." diff --git a/docs/vietnamese/FAQ.md b/docs/vietnamese/FAQ.md new file mode 100644 index 00000000..13313eb6 --- /dev/null +++ b/docs/vietnamese/FAQ.md @@ -0,0 +1,178 @@ +# ❓ Câu hỏi thường gặp (FAQ) + +**Bạn có thắc mắc?** Bạn không hề cô đơn! Dưới đây là câu trả lời cho những câu hỏi thường gặp nhất về Antigravity Awesome Skills. + +--- + +## 🎯 Câu hỏi Chung + +### "Skills" (kỹ năng) chính xác là gì? + +Skills là các tệp hướng dẫn chuyên biệt dạy cho các trợ lý AI cách xử lý những tác vụ cụ thể. Hãy coi chúng như những mô-đun kiến thức chuyên gia mà AI của bạn có thể tải khi cần. +**Một so sánh đơn giản:** Giống như việc bạn tham khảo ý kiến của các chuyên gia khác nhau (luật sư, bác sĩ, thợ máy), những kỹ năng này giúp AI của bạn trở thành chuyên gia trong các lĩnh vực khác nhau khi bạn cần. + +### Tôi có cần phải cài đặt tất cả hơn 552 skills không? + +**Không!** Khi bạn clone (tải bản sao) repository này, tất cả các kỹ năng đều có sẵn, nhưng AI của bạn chỉ tải chúng khi bạn yêu cầu rõ ràng bằng lệnh `@ten-skill`. +Nó giống như việc sở hữu một thư viện - tất cả sách đều ở đó, nhưng bạn chỉ đọc những cuốn bạn cần thôi. +**Mẹo:** Sử dụng [Bản mẫu Khởi đầu (Starter Packs)](BUNDLES.md) để chỉ cài đặt những gì phù hợp với vai trò của bạn. + +### Những công cụ AI nào hoạt động với các kỹ năng này? + +- ✅ **Claude Code** (Dòng lệnh CLI của Anthropic) +- ✅ **Gemini CLI** (Google) +- ✅ **Codex CLI** (OpenAI) +- ✅ **Cursor** (IDE tích hợp AI) +- ✅ **Antigravity IDE** +- ✅ **OpenCode** +- ⚠️ **GitHub Copilot** (Hỗ trợ một phần qua việc copy-paste) + +### Những kỹ năng này có được sử dụng miễn phí không? + +**Có!** Repository này được cấp phép theo giấy phép MIT License. + +- ✅ Miễn phí cho sử dụng cá nhân. +- ✅ Miễn phí cho sử dụng thương mại. +- ✅ Bạn có thể sửa đổi chúng. + +### Các kỹ năng có hoạt động ngoại tuyến (offline) không? + +Bản thân các file skill được lưu trữ cục bộ trên máy tính của bạn, nhưng trợ lý AI của bạn vẫn cần kết nối internet để hoạt động. + +--- + +## 🔒 Bảo mật & Tin cậy (Cập nhật V3) + +### Các Nhãn rủi ro (Risk Labels) có ý nghĩa gì? + +Chúng tôi phân loại các kỹ năng để bạn biết mình đang chạy cái gì: + +- ⚪ **Safe (Trắng/Xanh)**: Các kỹ năng chỉ đọc, lập kế hoạch hoặc vô hại. +- 🔴 **Risk (Đỏ)**: Các kỹ năng sửa đổi file (xóa), sử dụng công cụ quét mạng, hoặc thực hiện các hành động có tính phá hủy. **Hãy sử dụng thận trọng.** +- 🟣 **Official (Tím)**: Được duy trì bởi các nhà cung cấp tin cậy (Anthropic, DeepMind, v.v.). + +### Những kỹ năng này có thể hack máy tính của tôi không? + +**Không.** Kỹ năng là các file văn bản. Tuy nhiên, chúng *hướng dẫn* AI chạy các dòng lệnh. Nếu một skill nói "xóa toàn bộ file", một AI tuân thủ có thể sẽ thử làm việc đó. +_Luôn kiểm tra nhãn rủi ro và xem xét mã nguồn trước khi dùng._ + +--- + +## 📦 Cài đặt & Thiết lập + +### Tôi nên cài đặt các kỹ năng này ở đâu? + +Đường dẫn phổ biến nhất hoạt động với mạng lưới các công cụ AI là `.agent/skills/`: + +```bash +git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills +``` + +**Các đường dẫn cụ thể cho từng công cụ:** + +- Claude Code: `.claude/skills/` +- Gemini CLI: `.gemini/skills/` +- Cursor: `.cursor/skills/` hoặc gốc của dự án. + +### Repo này có hoạt động trên Windows không? + +**Có**, nhưng một số kỹ năng "Official" (chính thức) sử dụng **symlinks** (liên kết tượng trưng) mà Windows xử lý không tốt theo mặc định. +Hãy chạy git clone với lệnh sau: + +```bash +git clone -c core.symlinks=true https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills +``` + +Hoặc bật "Chế độ Nhà phát triển" (Developer Mode) trong phần Cài đặt của Windows. + +### Làm thế nào để cập nhật các kỹ năng? + +Chuyển hướng đến thư mục chứa kỹ năng của bạn và kéo (pull) những thay đổi mới nhất: + +```bash +cd .agent/skills +git pull origin main +``` + +--- + +## 🛠️ Cách sử dụng Skills + +### Làm thế nào để gọi một kỹ năng? + +Sử dụng biểu tượng `@` theo sau là tên skill: + +```bash +@brainstorming giúp tôi thiết kế một ứng dụng todo +``` + +### Tôi có thể dùng nhiều kỹ năng cùng một lúc không? + +**Có!** Bạn có thể gọi nhiều kỹ năng: + +```bash +@brainstorming giúp tôi thiết kế phần này, sau đó dùng @writing-plans để tạo danh sách nhiệm vụ. +``` + +### Làm thế nào để tôi biết nên dùng kỹ năng nào? + +1. **Duyệt qua danh mục**: Xem [Danh mục Skill (Skill Catalog)](../CATALOG.md). +2. **Tìm kiếm**: `ls skills/ | grep "từ-khóa"` +3. **Hỏi AI của bạn**: "Bạn có kỹ năng nào để kiểm thử (testing) không?" + +--- + +## 🏗️ Xử lý sự cố + +### Trợ lý AI của tôi không nhận diện được kỹ năng + +**Các nguyên nhân có thể xảy ra:** + +1. **Sai đường dẫn cài đặt**: Kiểm tra tài liệu hướng dẫn của công cụ bạn dùng. Hãy thử `.agent/skills/`. +2. **Cần khởi động lại**: Khởi động lại AI/IDE sau khi cài đặt. +3. **Lỗi đánh máy**: Bạn có gõ lầm `@brain-storming` thay vì `@brainstorming` không? + +### Một kỹ năng đưa ra lời khuyên sai hoặc lỗi thời + +Hãy [Mở một issue](https://github.com/sickn33/antigravity-awesome-skills/issues)! +Vui lòng gửi kèm: + +- Skill nào? +- Điều gì đã xảy ra? +- Đáng lẽ điều gì nên xảy ra? + +--- + +## 🤝 Đóng góp + +### Tôi là người mới đối với mã nguồn mở. Tôi có thể đóng góp không? + +**Chắc chắn là có!** Chúng tôi chào đón những người mới bắt đầu. + +- Sửa lỗi đánh máy. +- Thêm ví dụ. +- Cải thiện tài liệu hướng dẫn. +Hãy xem [CONTRIBUTING.md](../CONTRIBUTING.md) để biết hướng dẫn chi tiết. + +### Pull Request (PR) của tôi thất bại khi kiểm tra "Quality Bar". Tại sao? + +Phiên bản V3 áp dụng kiểm soát chất lượng tự động. Skill của bạn có thể đang thiếu: + +1. Một `description` (mô tả) hợp lệ. +2. Các ví dụ sử dụng. +Hãy chạy `python3 scripts/validate_skills.py` cục bộ để kiểm tra trước khi đẩy code lên. + +### Tôi có thể cập nhật các kỹ năng "Official" không? + +**Không.** Các kỹ năng chính thức (trong thư mục `skills/official/`) được đồng bộ từ các nhà cung cấp. Thay vào đó, hãy mở một issue để báo lỗi. + +--- + +## 💡 Mẹo Chuyên nghiệp + +- Bắt đầu với `@brainstorming` trước khi xây dựng bất kỳ thứ gì mới. +- Sử dụng `@systematic-debugging` khi gặp lỗi khó nhằn. +- Thử `@test-driven-development` để code có chất lượng tốt hơn. +- Khám phá `@skill-creator` để tự tạo kỹ năng của riêng bạn. + +**Vẫn còn thắc mắc?** [Mở một cuộc thảo luận (Discussion)](https://github.com/sickn33/antigravity-awesome-skills/discussions) và chúng tôi sẽ giúp bạn! 🙌 diff --git a/docs/vietnamese/GETTING_STARTED.md b/docs/vietnamese/GETTING_STARTED.md new file mode 100644 index 00000000..b5c01a13 --- /dev/null +++ b/docs/vietnamese/GETTING_STARTED.md @@ -0,0 +1,108 @@ +# Hướng dẫn Bắt đầu với Antigravity Awesome Skills (V3) + +**Bạn mới đến đây? Hướng dẫn này sẽ giúp bạn tăng cường sức mạnh cho trợ lý trợ lý AI của mình chỉ trong 5 phút.** + +--- + +## 🤔 "Skills" (Kỹ năng) là gì? + +Các trợ lý AI (như **Claude Code**, **Gemini**, **Cursor**) rất thông minh, nhưng chúng thiếu kiến thức cụ thể về các công cụ và quy trình làm việc của bạn. +**Skills** là các hướng dẫn sử dụng chuyên biệt (dưới dạng file markdown) dạy cho AI của bạn cách thực hiện các tác vụ cụ thể một cách hoàn hảo trong mọi lần thực hiện. + +**Một phép so sánh:** AI của bạn là một thực tập sinh xuất sắc. **Skills** là các SOP (Quy trình vận hành tiêu chuẩn) biến họ thành một Kỹ sư cao cấp. + +--- + +## ⚡️ Khởi động nhanh: Các "Gói khởi đầu" (Starter Packs) + +Đừng lo lắng về con số hơn 552 kỹ năng. Bạn không cần dùng tất cả chúng cùng một lúc. +Chúng tôi đã tuyển chọn các **Gói khởi đầu** để bạn có thể bắt đầu sử dụng ngay lập tức. + +### 1. Cài đặt Repository + +Sao chép các kỹ năng vào thư mục agent của bạn: + +```bash +# Cài đặt phổ thông (hoạt động với hầu hết các agent) +git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills +``` + +### 2. Chọn vai trò của bạn + +Tìm gói kỹ năng phù hợp với vị trí của bạn (xem [BUNDLES.md](BUNDLES.md)): + +| Vai trò | Tên Gói kỹ năng | Bên trong có những gì? | +| :-------------------- | :-------------- | :------------------------------------------------ | +| **Web Developer** | `Web Wizard` | React Patterns, Tailwind mastery, Frontend Design | +| **Security Engineer** | `Hacker Pack` | OWASP, Metasploit, Pentest Methodology | +| **Manager / PM** | `Product Pack` | Brainstorming, Planning, SEO, Strategy | +| **Cơ bản cho tất cả** | `Essentials` | Clean Code, Planning, Validation (Những thứ cơ bản nhất) | + +--- + +## 🚀 Cách sử dụng một Skill + +Sau khi cài đặt, bạn chỉ cần trò chuyện với AI một cách tự nhiên. + +### Ví dụ 1: Lập kế hoạch cho một Tính năng (**Essentials**) + +> "Sử dụng **@brainstorming** để giúp tôi thiết kế một luồng đăng nhập mới." + +**Điều gì sẽ xảy ra:** AI sẽ tải kỹ năng brainstorming, đặt cho bạn các câu hỏi có cấu trúc và tạo ra một bản đặc tả chuyên nghiệp. + +### Ví dụ 2: Kiểm tra Code của bạn (**Web Wizard**) + +> "Chạy **@lint-and-validate** trên file này và sửa các lỗi." + +**Điều gì sẽ xảy ra:** AI sẽ tuân theo các quy tắc linting nghiêm ngặt được định nghĩa trong skill để làm sạch code của bạn. + +### Ví dụ 3: Kiểm tra Bảo mật (**Hacker Pack**) + +> "Sử dụng **@api-security-best-practices** để xem xét các endpoint API của tôi." + +**Điều gì sẽ xảy ra:** AI sẽ kiểm tra code của bạn dựa trên các tiêu chuẩn OWASP. + +--- + +## 🔌 Các công cụ được hỗ trợ + +| Công cụ | Trạng thái | Đường dẫn | +| :--------------- | :-------------- | :---------------- | +| **Claude Code** | ✅ Hỗ trợ đầy đủ | `.claude/skills/` | +| **Gemini CLI** | ✅ Hỗ trợ đầy đủ | `.gemini/skills/` | +| **Antigravity** | ✅ Hỗ trợ gốc | `.agent/skills/` | +| **Cursor** | ✅ Hỗ trợ gốc | `.cursor/skills/` | +| **Copilot** | ⚠️ Chỉ văn bản | Copy-paste thủ công | + +--- + +## 🛡️ Sự tin cậy & An toàn (Mới trong bản V3) + +Chúng tôi phân loại các kỹ năng để bạn biết mình đang chạy những gì: + +- 🟣 **Official (Chính thức)**: Được duy trì bởi Anthropic/Google/Nhà cung cấp (Độ tin cậy cao). +- 🔵 **Safe (An toàn)**: Các kỹ năng cộng đồng không gây hại (Chỉ đọc/Lập kế hoạch). +- 🔴 **Risk (Rủi ro)**: Các kỹ năng sửa đổi hệ thống hoặc thực hiện kiểm thử bảo mật (Sử dụng khi được cấp phép). + +_Kiểm tra [Danh mục Skill (Skill Catalog)](../CATALOG.md) để xem danh sách đầy đủ._ + +--- + +## ❓ FAQ + +**H: Tôi có cần cài đặt tất cả 552 kỹ năng không?** +Đ: Bạn tải toàn bộ repo về, nhưng AI của bạn chỉ _đọc_ những kỹ năng bạn yêu cầu (hoặc những kỹ năng có liên quan). Nó rất nhẹ! + +**H: Tôi có thể tự tạo kỹ năng cho riêng mình không?** +Đ: Có! Sử dụng kỹ năng **@skill-creator** để tự xây dựng. + +**H: Nó có miễn phí không?** +Đ: Có, Giấy phép MIT. Mã nguồn mở mãi mãi. + +--- + +## ⏭️ Các bước tiếp theo + +1. [Duyệt qua các Gói kỹ năng (Bundles)](BUNDLES.md) +2. [Xem các Ví dụ thực tế (Examples)](EXAMPLES.md) +3. [Đóng góp một Skill mới](../CONTRIBUTING.md) diff --git a/docs/vietnamese/QUALITY_BAR.md b/docs/vietnamese/QUALITY_BAR.md new file mode 100644 index 00000000..01fb7ddc --- /dev/null +++ b/docs/vietnamese/QUALITY_BAR.md @@ -0,0 +1,64 @@ +# 🏆 Tiêu chuẩn Chất lượng & Xác thực + +Để biến **Antigravity Awesome Skills** từ một tập hợp các script thành một nền tảng đáng tin cậy, mỗi skill (kỹ năng) phải đáp ứng một tiêu chuẩn cụ thể về chất lượng và an toàn. + +## Huy hiệu "Đã xác thực" (Validated) ✅ + +Một skill chỉ nhận được huy hiệu "Đã xác thực" nếu nó vượt qua **5 bước kiểm tra tự động** sau: + +### 1. Tính toàn vẹn của siêu dữ liệu (Metadata Integrity) + +Phần frontmatter trong `SKILL.md` phải là mã YAML hợp lệ và chứa: + +- `name`: Định dạng Kebab-case, khớp với tên thư mục. +- `description`: Dưới 200 ký tự, nêu rõ giá trị mang lại. +- `risk`: Thuộc một trong các loại `[none, safe, critical, offensive]`. +- `source`: URL dẫn đến nguồn gốc (hoặc "self" nếu là nội dung gốc). + +### 2. Điều kiện kích hoạt rõ ràng ("Khi nào nên dùng") + +Skill BẮT BUỘC phải có một phần nêu rõ thời điểm nên kích hoạt nó. + +- **Tốt**: "Sử dụng khi người dùng yêu cầu debug (gỡ lỗi) một component React." +- **Tệ**: "Skill này giúp bạn xử lý code." + +### 3. Phân loại An toàn & Rủi ro + +Mỗi skill phải khai báo mức độ rủi ro của nó: + +- 🟢 **none**: Chỉ là văn bản/tư duy thuần túy (ví dụ: Brainstorming). +- 🔵 **safe**: Đọc file, chạy các lệnh an toàn (ví dụ: Linter). +- 🟠 **critical**: Sửa đổi trạng thái, xóa file, push lên môi trường production (ví dụ: Git Push). +- 🔴 **offensive**: Các công cụ Pentesting/Red Team. **BẮT BUỘC** phải có cảnh báo "Chỉ dành cho mục đích sử dụng đã được cấp phép". + +### 4. Ví dụ thực tế (Copy-Pasteable) + +Ít nhất một khối code hoặc ví dụ tương tác mà người dùng (hoặc agent) có thể sử dụng ngay lập tức. + +### 5. Giới hạn rõ ràng (Explicit Limitations) + +Danh sách các trường hợp biên hoặc những việc mà skill _không thể_ thực hiện. + +- _Ví dụ_: "Không hoạt động trên Windows nếu không có WSL." + +--- + +## Các cấp độ Hỗ trợ + +Chúng tôi cũng phân loại skill dựa trên người duy trì chúng: + +| Cấp độ | Huy hiệu | Ý nghĩa | +| :------------ | :------- | :--------------------------------------------------- | +| **Official** | 🟣 | Do đội ngũ cốt lõi duy trì. Độ tin cậy cao. | +| **Community** | ⚪ | Do cộng đồng đóng góp. Hỗ trợ theo khả năng tốt nhất. | +| **Verified** | ✨ | Skill cộng đồng đã vượt qua vòng kiểm duyệt thủ công chuyên sâu. | + +--- + +## Cách Xác thực Skill của bạn + +Chạy script xác thực trước khi gửi Pull Request (PR): + +```bash +python3 scripts/validate_skills.py --strict +``` diff --git a/docs/vietnamese/README.md b/docs/vietnamese/README.md new file mode 100644 index 00000000..401712a4 --- /dev/null +++ b/docs/vietnamese/README.md @@ -0,0 +1,254 @@ +# 🌌 Antigravity Awesome Skills: 552+ Kỹ năng (Skills) cho Claude Code, Gemini CLI, Cursor, Copilot và nhiều hơn nữa + +> **Bộ sưu tập tối ưu gồm hơn 552 Kỹ năng Phổ quát cho các Trợ lý Lập trình AI — Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode** + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Claude Code](https://img.shields.io/badge/Claude%20Code-Anthropic-purple)](https://claude.ai) +[![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-Google-blue)](https://github.com/google-gemini/gemini-cli) +[![Codex CLI](https://img.shields.io/badge/Codex%20CLI-OpenAI-green)](https://github.com/openai/codex) +[![Cursor](https://img.shields.io/badge/Cursor-AI%20IDE-orange)](https://cursor.sh) +[![Copilot](https://img.shields.io/badge/GitHub%20Copilot-VSCode-lightblue)](https://github.com/features/copilot) +[![OpenCode](https://img.shields.io/badge/OpenCode-CLI-gray)](https://github.com/opencode-ai/opencode) +[![Antigravity](https://img.shields.io/badge/Antigravity-DeepMind-red)](https://github.com/sickn33/antigravity-awesome-skills) + +**Antigravity Awesome Skills** là một thư viện được tuyển chọn và kiểm chứng kỹ lưỡng với **552 kỹ năng hiệu suất cao** được thiết kế để hoạt động mượt mà trên tất cả các trợ lý lập trình AI lớn: + +- 🟣 **Claude Code** (Anthropic CLI) +- 🔵 **Gemini CLI** (Google DeepMind) +- 🟢 **Codex CLI** (OpenAI) +- 🔴 **Antigravity IDE** (Google DeepMind) +- 🩵 **GitHub Copilot** (VSCode Extension) +- 🟠 **Cursor** (AI-native IDE) +- ⚪ **OpenCode** (Mã nguồn mở CLI) + +Repository này cung cấp các kỹ năng thiết yếu để biến trợ lý AI của bạn thành một **digital agency toàn diện**, bao gồm các khả năng chính thức từ **Anthropic**, **OpenAI**, **Google**, **Supabase**, và **Vercel Labs**. + +## Mục lục + +- [🚀 Bạn mới đến đây? Hãy bắt đầu tại đây!](#bạn-mới-đến-đây-hãy-bắt đầu-tại-đây) +- [🔌 Khả năng tương thích & Cách gọi lệnh](#khả-năng-tương-thích--cách-gọi-lệnh) +- [📦 Tính năng & Danh mục](#tính-năng--danh-mục) +- [🎁 Bộ sưu tập được tuyển chọn (Bundles)](#bộ-sưu-tập-được-tuyển-chọn) +- [📚 Duyệt hơn 552 Kỹ năng](#duyệt-hơn-552-kỹ-năng) +- [🛠️ Cài đặt](#cài-đặt) +- [🤝 Cách thức Đóng góp](#cách-thức-đóng-góp) +- [👥 Người đóng góp & Ghi công](#người-đóng-góp--ghi-công) +- [⚖️ Giấy phép](#giấy-phép) +- [👥 Những người đóng góp cho Repo](#những-người-đóng-góp-cho-repo) +- [🌟 Lịch sử Star](#lịch-sử-star) + +--- + +## Bạn mới đến đây? Hãy bắt đầu tại đây! + +**Chào mừng bạn đến với Phiên bản V4.0.0 Enterprise.** Đây không chỉ là một danh sách các kịch bản; nó là một hệ điều hành hoàn chỉnh cho Trợ lý AI của bạn. + +### 1. 🐣 Bối cảnh: Đây là cái gì? + +**Antigravity Awesome Skills** (Phiên bản 4.0.0) là một bản nâng cấp khổng lồ cho khả năng của AI của bạn. + +Các trợ lý AI (như Claude Code, Cursor, hoặc Gemini) rất thông minh, nhưng chúng thiếu các **công cụ cụ thể**. Chúng không biết "Giao thức Triển khai" của công ty bạn hoặc cú pháp cụ thể cho "AWS CloudFormation". +**Skills** là các tệp markdown nhỏ dạy cho chúng cách thực hiện những tác vụ cụ thể này một cách hoàn hảo trong mọi lần thực hiện. + +### 2. ⚡️ Khởi động nhanh (Theo cách dùng "Gói kỹ năng") + +Đừng cài đặt 552+ kỹ năng một cách thủ công. Hãy sử dụng các **Gói khởi đầu (Starter Packs)** của chúng tôi: + +1. **Sao chép repo**: + ```bash + git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills + ``` +2. **Chọn vai trò của bạn** (Xem [docs/vietnamese/BUNDLES.md](docs/vietnamese/BUNDLES.md)): + - **Lập trình Web?** sử dụng gói `Web Wizard`. + - **Hacker?** sử dụng gói `Security Engineer`. + - **Chỉ tò mò thôi?** bắt đầu với gói `Essentials`. + +### 3. 🧠 Cách sử dụng + +Sau khi cài đặt, chỉ cần hỏi trợ lý của bạn một cách tự nhiên: + +> "Sử dụng kỹ năng **@brainstorming** để giúp tôi lập kế hoạch cho một dự án SaaS." +> "Chạy **@lint-and-validate** trên file này." + +👉 **[Đọc Hướng dẫn bắt đầu đầy đủ](docs/vietnamese/GETTING_STARTED.md)** + +--- + +## Khả năng tương thích & Cách gọi lệnh + +Các kỹ năng này tuân theo định dạng chuẩn **SKILL.md** phổ quát và hoạt động với bất kỳ trợ lý lập trình AI nào hỗ trợ các kỹ năng agentic. + +| Công cụ | Loại | Ví dụ gọi lệnh | Đường dẫn | +| :-------------- | :--- | :-------------------------------- | :---------------- | +| **Claude Code** | CLI | `>> /skill-name giúp tôi...` | `.claude/skills/` | +| **Gemini CLI** | CLI | `(User Prompt) Dùng skill-name...`| `.gemini/skills/` | +| **Antigravity** | IDE | `(Agent Mode) Dùng skill...` | `.agent/skills/` | +| **Cursor** | IDE | `@skill-name (trong Chat)` | `.cursor/skills/` | +| **Copilot** | Ext | `(Dán nội dung thủ công)` | (N/A) | + +> [!TIP] +> **Đường dẫn Phổ quát**: Chúng tôi khuyên bạn nên clone về thư mục `.agent/skills/`. Hầu hết các công cụ hiện đại (Antigravity, các CLI gần đây) đều tìm kiếm ở đây theo mặc định. + +> [!WARNING] +> **Người dùng Windows**: Repository này sử dụng **symlinks** cho các kỹ năng chính thức. +> Bạn phải bật Chế độ nhà phát triển (Developer Mode) hoặc chạy Git với quyền Admin: +> `git clone -c core.symlinks=true https://github.com/...` + +--- + +Cho dù bạn đang sử dụng **Gemini CLI**, **Claude Code**, **Codex CLI**, **Cursor**, **GitHub Copilot**, **Antigravity**, hay **OpenCode**, những kỹ năng này được thiết kế để có thể sử dụng ngay lập tức và tăng cường sức mạnh cho trợ lý AI của bạn. + +Repository này tập hợp những khả năng tốt nhất từ khắp cộng đồng mã nguồn mở, biến trợ lý AI của bạn thành một digital agency toàn diện có khả năng Kỹ thuật, Thiết kế, Bảo mật, Marketing và Vận hành Tự động. + +## Tính năng & Danh mục + +Repository được tổ chức thành các lĩnh vực chuyên biệt để biến AI của bạn thành một chuyên gia trên toàn bộ vòng đời phát triển phần mềm: + +| Danh mục | Trọng tâm | Ví dụ kỹ năng | +| :--- | :--- | :--- | +| Kiến trúc (52) | Thiết kế hệ thống, ADRs, C4 và các mẫu có thể mở rộng | `architecture`, `c4-context`, `senior-architect` | +| Kinh doanh (35) | Tăng trưởng, định giá, CRO, SEO và thâm nhập thị trường | `copywriting`, `pricing-strategy`, `seo-audit` | +| Dữ liệu & AI (81) | Ứng dụng LLM, RAG, agents, khả năng quan sát, phân tích | `rag-engineer`, `prompt-engineer`, `langgraph` | +| Phát triển (72) | Làm chủ ngôn ngữ, mẫu thiết kế framework, chất lượng code | `typescript-expert`, `python-patterns`, `react-patterns` | +| Tổng quát (95) | Lập kế hoạch, tài liệu, vận hành sản phẩm, viết bài, hướng dẫn | `brainstorming`, `doc-coauthoring`, `writing-plans` | +| Hạ tầng (72) | DevOps, cloud, serverless, triển khai, CI/CD | `docker-expert`, `aws-serverless`, `vercel-deployment` | +| Bảo mật (107) | AppSec, pentesting, phân tích lỗ hổng, tuân thủ | `api-security-best-practices`, `sql-injection-testing`, `vulnerability-scanner` | +| Kiểm thử (21) | TDD, thiết kế kiểm thử, sửa lỗi, quy trình QA | `test-driven-development`, `testing-patterns`, `test-fixing` | +| Quy trình (17) | Tự động hóa, điều phối, công việc, agents | `workflow-automation`, `inngest`, `trigger-dev` | + +## Bộ sưu tập Tuyển chọn + +[Xem các Gói khởi đầu tại docs/vietnamese/BUNDLES.md](docs/vietnamese/BUNDLES.md) để tìm bộ công cụ hoàn hảo cho vai trò của bạn. + +## Duyệt hơn 552 Kỹ năng + +Chúng tôi đã chuyển danh sách đầy đủ các kỹ năng sang một danh mục riêng biệt để giữ cho file README này gọn gàng. + +👉 **[Xem Danh mục Kỹ năng Đầy đủ (CATALOG.md)](CATALOG.md)** + +## Cài đặt + +Để sử dụng các kỹ năng này với **Claude Code**, **Gemini CLI**, **Codex CLI**, **Cursor**, **Antigravity**, hoặc **OpenCode**, hãy clone repository này vào thư mục kỹ năng của assistant của bạn: + +```bash +# Cài đặt phổ thông (hoạt động với hầu hết các công cụ) +git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills + +# Dành riêng cho Claude Code +git clone https://github.com/sickn33/antigravity-awesome-skills.git .claude/skills + +# Dành riêng cho Gemini CLI +git clone https://github.com/sickn33/antigravity-awesome-skills.git .gemini/skills + +# Dành riêng cho Cursor +git clone https://github.com/sickn33/antigravity-awesome-skills.git .cursor/skills +``` + +--- + +## Cách thức Đóng góp + +Chúng tôi chào đón mọi sự đóng góp từ cộng đồng! Để thêm một kỹ năng mới: + +1. **Fork** repository. +2. **Tạo một thư mục mới** bên trong `skills/` cho kỹ năng của bạn. +3. **Thêm file `SKILL.md`** với phần frontmatter bắt buộc (tên và mô tả). +4. **Chạy kiểm tra xác thực**: `python3 scripts/validate_skills.py`. +5. **Gửi một Pull Request**. + +Vui lòng đảm bảo kỹ năng của bạn tuân thủ các thực hành tốt nhất của Antigravity/Claude Code. + +--- + +## Người đóng góp & Ghi công + +Chúng tôi đứng trên vai của những người khổng lồ. + +👉 **[Xem Sổ cái Ghi công Đầy đủ (docs/vietnamese/SOURCES.md)](docs/vietnamese/SOURCES.md)** + +Các nguồn đóng góp và nguồn chính bao gồm: + +- **HackTricks** +- **OWASP** +- **Anthropic / OpenAI / Google** +- **Cộng đồng mã nguồn mở** + +Bộ sưu tập này sẽ không thể hình thành nếu không có công việc tuyệt vời của cộng đồng Claude Code và các nguồn chính thức: + +### Các nguồn Chính thức + +- **[anthropics/skills](https://github.com/anthropics/skills)**: Thư mục skill chính thức của Anthropic - Xử lý tài liệu (DOCX, PDF, PPTX, XLSX), Hướng dẫn thương hiệu, Giao tiếp nội bộ. +- **[anthropics/claude-cookbooks](https://github.com/anthropics/claude-cookbooks)**: Các notebook và công thức chính thức để xây dựng với Claude. +- **[remotion-dev/skills](https://github.com/remotion-dev/skills)**: Skills chính thức của Remotion - Tạo video trong React với 28 quy tắc mô-đun. +- **[vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills)**: Skills chính thức của Vercel Labs - Thực hành tốt nhất cho React, Hướng dẫn thiết kế Web. +- **[openai/skills](https://github.com/openai/skills)**: Danh mục skill của OpenAI Codex - Các kỹ năng của Agent, Trình tạo Skill, Lập kế hoạch Súc tích. +- **[supabase/agent-skills](https://github.com/supabase/agent-skills)**: Skills chính thức của Supabase - Thực hành tốt nhất cho Postgres. + +### Những người đóng góp từ Cộng đồng + +- **[rmyndharis/antigravity-skills](https://github.com/rmyndharis/antigravity-skills)**: Cho sự đóng góp khổng lồ của hơn 300+ kỹ năng Enterprise và logic tạo danh mục. +- **[obra/superpowers](https://github.com/obra/superpowers)**: Bản "Superpowers" gốc bởi Jesse Vincent. +- **[guanyang/antigravity-skills](https://github.com/guanyang/antigravity-skills)**: Các bản mở rộng Antigravity cốt lõi. +- **[diet103/claude-code-infrastructure-showcase](https://github.com/diet103/claude-code-infrastructure-showcase)**: Cơ sở hạ tầng và Hướng dẫn cho Backend/Frontend. +- **[ChrisWiles/claude-code-showcase](https://github.com/ChrisWiles/claude-code-showcase)**: Các mẫu React UI và Hệ thống Thiết kế. +- **[travisvn/awesome-claude-skills](https://github.com/travisvn/awesome-claude-skills)**: Loki Mode và tích hợp Playwright. +- **[zebbern/claude-code-guide](https://github.com/zebbern/claude-code-guide)**: Bộ công cụ bảo mật toàn diện & Hướng dẫn (Nguồn cho khoảng 60 kỹ năng mới). +- **[alirezarezvani/claude-skills](https://github.com/alirezarezvani/claude-skills)**: Bộ công cụ Kỹ sư cao cấp và PM. +- **[karanb192/awesome-claude-skills](https://github.com/karanb192/awesome-claude-skills)**: Một danh sách khổng lồ các kỹ năng đã được xác thực cho Claude Code. +- **[zircote/.claude](https://github.com/zircote/.claude)**: Tham chiếu kỹ năng phát triển cho Shopify. +- **[vibeforge1111/vibeship-spawner-skills](https://github.com/vibeforge1111/vibeship-spawner-skills)**: Trợ lý AI, Tích hợp, Công cụ của nhà sáng tạo (57 kỹ năng, Apache 2.0). +- **[coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills)**: Các kỹ năng Marketing cho CRO, copywriting, SEO, quảng cáo trả phí và tăng trưởng (23 kỹ năng, MIT). +- **[vudovn/antigravity-kit](https://github.com/vudovn/antigravity-kit)**: Các mẫu AI Agent với Kỹ năng, Agents và Quy trình làm việc (33 kỹ năng, MIT). +- **[affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code)**: Bộ sưu tập cấu hình Claude Code đầy đủ từ người chiến thắng cuộc thi hackathon của Anthropic - chỉ phần kỹ năng (8 kỹ năng, MIT). +- **[webzler/agentMemory](https://github.com/webzler/agentMemory)**: Nguồn cho kỹ năng agent-memory-mcp. +- **[sstklen/claude-api-cost-optimization](https://github.com/sstklen/claude-api-cost-optimization)**: Tiết kiệm 50-90% chi phí Claude API với các chiến lược tối ưu hóa thông minh (MIT). + +### Nguồn cảm hứng + +- **[f/awesome-chatgpt-prompts](https://github.com/f/awesome-chatgpt-prompts)**: Cảm hứng cho Thư viện Prompt. +- **[leonardomso/33-js-concepts](https://github.com/leonardomso/33-js-concepts)**: Cảm hứng cho việc Làm chủ JavaScript. + +--- + +## Giấy phép + +Giấy phép MIT. Xem file [LICENSE](LICENSE) để biết chi tiết. + +## Cộng đồng + +- [Cộng đồng (Community Guidelines)](docs/vietnamese/COMMUNITY_GUIDELINES.md) +- [Chính sách Bảo mật (Security Policy)](docs/vietnamese/SECURITY_GUARDRAILS.md) + +--- + +## Những người đóng góp cho Repo + +Chúng tôi chính thức cảm ơn những người đóng góp sau đây đã giúp làm cho repository này trở nên tuyệt vời! + +- [mvanhorn](https://github.com/mvanhorn) +- [rookie-ricardo](https://github.com/rookie-ricardo) +- [sck_0](https://github.com/sck_0) +- [Munir Abbasi](https://github.com/munirabbasi) +- [Mohammad Faiz](https://github.com/mohdfaiz2k9) +- [Ianj332](https://github.com/Ianj332) +- [sickn33](https://github.com/sickn33) +- [GuppyTheCat](https://github.com/GuppyTheCat) +- [Tiger-Foxx](https://github.com/Tiger-Foxx) +- [arathiesh](https://github.com/arathiesh) +- [1bcMax](https://github.com/1bcMax) +- [Ahmed Rehan](https://github.com/ar27111994) +- [BenedictKing](https://github.com/BenedictKing) +- [Nguyen Huu Loc](https://github.com/LocNguyenSGU) +- [Owen Wu](https://github.com/yubing744) +- [SuperJMN](https://github.com/SuperJMN) +- [Viktor Ferenczi](https://github.com/viktor-ferenczi) +- [krisnasantosa15](https://github.com/krisnasantosa15) +- [raeef1001](https://github.com/raeef1001) +- [taksrules](https://github.com/taksrules) +- [zebbern](https://github.com/zebbern) +- [Đỗ Khắc Gia Khoa](https://github.com/dokhacgiakhoa) +- [vuth-dogo](https://github.com/vuth-dogo) + +## Lịch sử Star + +[![Star History Chart](https://api.star-history.com/svg?repos=sickn33/antigravity-awesome-skills&type=date&legend=top-left)](https://www.star-history.com/#sickn33/antigravity-awesome-skills&type=date&legend=top-left) diff --git a/docs/vietnamese/SECURITY_GUARDRAILS.md b/docs/vietnamese/SECURITY_GUARDRAILS.md new file mode 100644 index 00000000..ae9e2bd7 --- /dev/null +++ b/docs/vietnamese/SECURITY_GUARDRAILS.md @@ -0,0 +1,51 @@ +# 🛡️ Chính sách Bảo mật & Rào chắn An toàn (Guardrails) + +Antigravity Awesome Skills là một bộ công cụ mạnh mẽ. Và quyền lực lớn luôn đi kèm với trách nhiệm lớn. Tài liệu này xác định **Quy tắc Ứng xử** cho tất cả các khả năng bảo mật và tấn công trong repository này. + +## 🔴 Chính sách đối với Skill Tấn công (Vạch kẻ đỏ) + +**Skill Tấn công là gì?** +Bất kỳ kỹ năng (skill) nào được thiết kế để xâm nhập, khai thác, làm gián đoạn hoặc mô phỏng tấn công chống lại các hệ thống. +_Ví dụ: Pentesting (Kiểm thử xâm nhập), SQL Injection, Mô phỏng Phishing, Red Teaming._ + +### 1. Tuyên bố từ chối trách nhiệm "Chỉ dành cho mục đích sử dụng đã được phê duyệt" + +Mỗi skill tấn công **BẮT BUỘC** phải bắt đầu bằng tuyên bố từ chối trách nhiệm chính xác như sau trong file `SKILL.md`: + +> **⚠️ CHỈ DÀNH CHO MỤC ĐÍCH SỬ DỤNG ĐÃ ĐƯỢC PHÊ DUYỆT** +> Skill này chỉ dành cho mục đích giáo dục hoặc đánh giá bảo mật đã được cấp phép. +> Bạn phải có sự cho phép rõ ràng bằng văn bản từ chủ sở hữu hệ thống trước khi sử dụng công cụ này. +> Việc lạm dụng công cụ này là bất hợp pháp và bị nghiêm cấm hoàn toàn. + +### 2. Yêu cầu Xác nhận từ Người dùng + +Các skill tấn công **KHÔNG BAO GIỜ** được chạy hoàn toàn tự động một cách tự ý (autonomously). + +- **Yêu cầu**: Mô tả hoặc hướng dẫn của skill phải yêu cầu agent (trợ lý AI) *hỏi xác nhận của người dùng* trước khi thực thi bất kỳ lệnh khai thác hoặc tấn công nào. +- **Hướng dẫn cho Agent**: "Yêu cầu người dùng xác minh URL/IP mục tiêu trước khi chạy." + +### 3. Thiết kế để An toàn + +- **Không chứa mã độc (Weaponized Payloads)**: Các skill không được bao gồm malware hoạt động, ransomware, hoặc các mã khai thác không mang tính giáo dục. +- **Khuyến nghị dùng Sandbox**: Các hướng dẫn nên khuyến nghị chạy trong môi trường cô lập (Docker/VM). + +--- + +## 🔵 Chính sách đối với Skill Phòng thủ + +**Skill Phòng thủ là gì?** +Các công cụ dùng để tăng cường bảo mật (hardening), kiểm tra (auditing), giám sát (monitoring), hoặc bảo vệ hệ thống. +_Ví dụ: Linting (Kiểm tra lỗi code), Phân tích Log, Kiểm tra Cấu hình._ + +- **Quyền riêng tư dữ liệu**: Các kỹ năng phòng thủ không được tải dữ liệu lên các máy chủ bên thứ ba mà không có sự đồng ý rõ ràng của người dùng. +- **Không gây hư tổn (Non-Destructive)**: Các quy trình kiểm tra (audits) nên mặc định ở chế độ chỉ đọc (read-only). + +--- + +## ⚖️ Tuyên bố Pháp lý + +Bằng việc sử dụng repository này, bạn đồng ý rằng: + +1. Bạn tự chịu trách nhiệm về hành động của mình. +2. Các tác giả và người đóng góp không chịu trách nhiệm cho bất kỳ thiệt hại nào do các công cụ này gây ra. +3. Bạn sẽ tuân thủ tất cả các luật địa phương, tiểu bang và liên bang liên quan đến an ninh mạng. diff --git a/docs/vietnamese/SKILL_ANATOMY.md b/docs/vietnamese/SKILL_ANATOMY.md new file mode 100644 index 00000000..fc6b5c1c --- /dev/null +++ b/docs/vietnamese/SKILL_ANATOMY.md @@ -0,0 +1,605 @@ +# Cấu trúc của một Skill - Hiểu về Hệ thống + +**Bạn muốn hiểu cách các skill (kỹ năng) hoạt động bên trong?** Hướng dẫn này sẽ phân tích chi tiết từng phần của một file skill. + +--- + +## 📁 Cấu trúc Thư mục Cơ bản + +``` +skills/ +└── my-skill-name/ + ├── SKILL.md ← Bắt buộc: Định nghĩa skill chính + ├── examples/ ← Tùy chọn: Các file ví dụ + │ ├── example1.js + │ └── example2.py + ├── scripts/ ← Tùy chọn: Các script hỗ trợ + │ └── helper.sh + ├── templates/ ← Tùy chọn: Các bản mẫu code (templates) + │ └── template.tsx + ├── references/ ← Tùy chọn: Tài liệu tham khảo + │ └── api-docs.md + └── README.md ← Tùy chọn: Tài liệu bổ sung +``` + +**Quy tắc Cốt lõi:** Chỉ có file `SKILL.md` là bắt buộc. Tất cả những thành phần khác đều là tùy chọn! + +--- + +## Cấu trúc file SKILL.md + +Mỗi file `SKILL.md` có hai phần chính: + +### 1. Frontmatter (Siêu dữ liệu - Metadata) + +### 2. Nội dung (Hướng dẫn - Instructions) + +Hãy cùng phân tích chi tiết từng phần: + +--- + +## Phần 1: Frontmatter + +Frontmatter nằm ở ngay đầu file, được bao bọc bởi cặp `---`: + +```markdown +--- +name: my-skill-name +description: "Mô tả ngắn gọn về chức năng của skill này" +--- +``` + +### Các trường Bắt buộc + +#### `name` + +- **Định nghĩa:** Mã định danh của skill. +- **Định dạng:** chữ-thường-có-dấu-gạch-ngang (kebab-case). +- **Yêu cầu:** Phải khớp hoàn toàn với tên thư mục. +- **Ví dụ:** `stripe-integration` + +#### `description` + +- **Định nghĩa:** Tóm tắt chức năng trong một câu. +- **Định dạng:** Chuỗi ký tự nằm trong dấu ngoặc kép. +- **Độ dài:** Nên dưới 150 ký tự. +- **Ví dụ:** `"Các mẫu tích hợp thanh toán Stripe bao gồm checkout, đăng ký gói (subscriptions) và webhooks"` + +### Các trường Tùy chọn + +Một số skill bao gồm thêm siêu dữ liệu bổ sung: + +```markdown +--- +name: my-skill-name +description: "Mô tả ngắn" +risk: "safe" # safe | risk | official +source: "community" +tags: ["react", "typescript"] +--- +``` + +--- + +## Phần 2: Nội dung + +Sau phần frontmatter là nội dung thực tế của skill. Dưới đây là cấu trúc được đề xuất: + +### Các mục Đề xuất + +#### 1. Tiêu đề (H1) + +```markdown +# Tiêu đề Skill +``` + +- Sử dụng tiêu đề rõ ràng, mang tính mô tả. +- Thường khớp hoặc mở rộng từ tên skill. + +#### 2. Tổng quan (Overview) + +```markdown +## Tổng quan + +Một giải thích ngắn gọn về chức năng của skill và lý do tại sao nó tồn tại. +Khoảng 2-4 câu là lý tưởng. +``` + +#### 3. Khi nào cần sử dụng (When to Use) + +```markdown +## Khi nào nên sử dụng Skill này + +- Sử dụng khi bạn cần [tình huống 1] +- Sử dụng khi làm việc với [tình huống 2] +- Sử dụng khi người dùng hỏi về [tình huống 3] +``` + +**Tại sao điều này quan trọng:** Giúp AI biết khi nào cần kích hoạt skill này. + +#### 4. Hướng dẫn Cốt lõi (Core Instructions) + +```markdown +## Cách hoạt động + +### Bước 1: [Hành động] + +Hướng dẫn chi tiết... + +### Bước 2: [Hành động] + +Hướng dẫn thêm... +``` + +**Đây là linh hồn của skill** - các bước rõ ràng và có thể thực hiện được. + +#### 5. Ví dụ (Examples) + +```markdown +## Ví dụ + +### Ví dụ 1: [Trường hợp sử dụng] + +\`\`\`javascript +// Code ví dụ +\`\`\` + +### Ví dụ 2: [Trường hợp sử dụng khác] + +\`\`\`javascript +// Thêm code +\`\`\` +``` + +**Tại sao ví dụ lại quan trọng:** Chúng cho AI thấy chính xác kết quả đầu ra tốt trông như thế nào. + +#### 6. Thực hành Tốt nhất (Best Practices) + +```markdown +## Thực hành Tốt nhất + +- ✅ Nên làm điều này +- ✅ Cũng nên làm điều này +- ❌ Không nên làm điều này +- ❌ Tránh điều này +``` + +#### 7. Các lỗi thường gặp (Common Pitfalls) + +```markdown +## Các lỗi thường gặp + +- **Vấn đề:** Mô tả lỗi + **Giải pháp:** Cách khắc phục +``` + +#### 8. Các Skill liên quan (Related Skills) + +```markdown +## Các Skill liên quan + +- `@other-skill` - Khi nào nên dùng skill này thay thế +- `@complementary-skill` - Cách các skill này hoạt động cùng nhau +``` + +--- + +## Viết Hướng dẫn Hiệu quả + +### Sử dụng Ngôn ngữ Rõ ràng, Trực tiếp + +**❌ Không tốt:** + +```markdown +Bạn có lẽ nên cân nhắc việc kiểm tra xem người dùng đã xác thực hay chưa. +``` + +**✅ Tốt:** + +```markdown +Kiểm tra xem người dùng đã được xác thực chưa trước khi tiếp tục. +``` + +### Sử dụng Động từ Hành động + +**❌ Không tốt:** + +```markdown +File nên được tạo ra... +``` + +**✅ Tốt:** + +```markdown +Tạo file... +``` + +### Cụ thể và Chi tiết + +**❌ Không tốt:** + +```markdown +Thiết lập cơ sở dữ liệu một cách chính xác. +``` + +**✅ Tốt:** + +```markdown +1. Tạo cơ sở dữ liệu PostgreSQL +2. Chạy migration: `npm run migrate` +3. Nạp dữ liệu ban đầu (seed): `npm run seed` +``` + +--- + +## Các Thành phần Tùy chọn + +### Thư mục Scripts + +Nếu skill của bạn cần các script hỗ trợ: + +``` +scripts/ +├── setup.sh ← Tự động hóa thiết lập +├── validate.py ← Công cụ kiểm tra (validation) +└── generate.js ← Công cụ tạo code (generators) +``` + +**Tham chiếu chúng trong SKILL.md:** + +```markdown +Chạy script thiết lập: +\`\`\`bash +bash scripts/setup.sh +\`\`\` +``` + +### Thư mục Examples + +Các ví dụ thực tế minh họa skill: + +``` +examples/ +├── basic-usage.js +├── advanced-pattern.ts +└── full-implementation/ + ├── index.js + └── config.json +``` + +### Thư mục Templates + +Các mẫu code có thể tái sử dụng: + +``` +templates/ +├── component.tsx +├── test.spec.ts +└── config.json +``` + +**Tham chiếu trong SKILL.md:** + +```markdown +Sử dụng bản mẫu này làm điểm bắt đầu: +\`\`\`typescript +{{#include templates/component.tsx}} +\`\`\` +``` + +### Thư mục References + +Tài liệu bên ngoài hoặc tham chiếu API: + +``` +references/ +├── api-docs.md +├── best-practices.md +└── troubleshooting.md +``` + +--- + +## Hướng dẫn về Quy mô Skill + +### Skill Tối giản (Minimum Viable Skill) + +- **Frontmatter:** name + description +- **Nội dung:** 100-200 từ +- **Các mục:** Tổng quan + Hướng dẫn + +### Skill Tiêu chuẩn (Standard Skill) + +- **Frontmatter:** name + description +- **Nội dung:** 300-800 từ +- **Các mục:** Tổng quan + Khi nào sử dụng + Hướng dẫn + Ví dụ + +### Skill Toàn diện (Comprehensive Skill) + +- **Frontmatter:** name + description + các trường tùy chọn +- **Nội dung:** 800-2000 từ +- **Các mục:** Đầy đủ tất cả các mục đề xuất +- **Bổ sung:** Scripts, ví dụ, templates + +**Quy tắc ngón tay cái:** Bắt đầu nhỏ, mở rộng dựa trên phản hồi. + +--- + +## Thực hành Tốt nhất về Định dạng + +### Sử dụng Markdown Hiệu quả + +#### Khối Code (Code Blocks) + +Luôn chỉ định ngôn ngữ: + +```markdown +\`\`\`javascript +const example = "code"; +\`\`\` +``` + +#### Danh sách (Lists) + +Sử dụng định dạng nhất quán: + +```markdown +- Mục 1 +- Mục 2 + - Mục con 2.1 + - Mục con 2.2 +``` + +#### Nhấn mạnh (Emphasis) + +- **In đậm** cho các thuật ngữ quan trọng: `**quan trọng**` +- _In nghiêng_ để nhấn mạnh: `*nhấn mạnh*` +- `Code` cho lệnh hoặc code: `` `code` `` + +#### Liên kết (Links) + +```markdown +[Văn bản liên kết](https://example.com) +``` + +--- + +## ✅ Danh mục Kiểm tra Chất lượng (Quality Checklist) + +Trước khi hoàn tất skill của bạn: + +### Chất lượng Nội dung + +- [ ] Hướng dẫn rõ ràng và có thể thực hiện được. +- [ ] Ví dụ thực tế và hữu ích. +- [ ] Không có lỗi chính tả hoặc ngữ pháp. +- [ ] Độ chính xác kỹ thuật đã được xác minh. + +### Cấu trúc + +- [ ] Frontmatter là YAML hợp lệ. +- [ ] Tên (Name) khớp với tên thư mục. +- [ ] Các phần được sắp xếp logic. +- [ ] Các tiêu đề tuân thủ cấp bậc (H1 → H2 → H3). + +### Tính đầy đủ + +- [ ] Phần Tổng quan giải thích "tại sao". +- [ ] Hướng dẫn giải thích "làm thế nào". +- [ ] Ví dụ cho thấy "cái gì". +- [ ] Các trường hợp biên (edge cases) được đề cập. + +### Khả năng sử dụng + +- [ ] Một người mới bắt đầu có thể làm theo. +- [ ] Một chuyên gia thấy nó hữu ích. +- [ ] AI có thể phân tích chính xác. +- [ ] Nó giải quyết một vấn đề thực tế. + +--- + +## 🔍 Phân tích Ví dụ Thực tế + +Hãy phân tích một skill thực tế: `brainstorming` + +```markdown +--- +name: brainstorming +description: "Bạn PHẢI sử dụng skill này trước bất kỳ công việc sáng tạo nào..." +--- +``` + +**Phân tích:** + +- ✅ Tên rõ ràng. +- ✅ Mô tả mạnh mẽ với tính cấp bách ("PHẢI sử dụng"). +- ✅ Giải thích khi nào nên dùng. + +```markdown +# Brainstorming Ý tưởng thành Thiết kế + +## Tổng quan + +Giúp chuyển đổi ý tưởng thành các thiết kế hoàn chỉnh... +``` + +**Phân tích:** + +- ✅ Tiêu đề rõ ràng. +- ✅ Tổng quan súc tích. +- ✅ Giải thích giá trị mang lại. + +```markdown +## Quy trình + +**Hiểu ý tưởng:** + +- Kiểm tra trạng thái dự án hiện tại trước. +- Đặt câu hỏi từng cái một. +``` + +**Phân tích:** + +- ✅ Được chia thành các giai đoạn rõ ràng. +- ✅ Các bước cụ thể, có thể hành động. +- ✅ Dễ dàng thực hiện theo. + +--- + +## Các Mẫu Nâng cao + +### Logic có Điều kiện + +```markdown +## Hướng dẫn + +Nếu người dùng đang làm việc với React: + +- Sử dụng functional components. +- Ưu tiên hooks hơn class components. + +Nếu người dùng đang làm việc với Vue: + +- Sử dụng Composition API. +- Tuân theo các mẫu của Vue 3. +``` + +### Tiết lộ Lũy tiến (Progressive Disclosure) + +```markdown +## Cách dùng Cơ bản + +[Hướng dẫn đơn giản cho các trường hợp phổ biến] + +## Cách dùng Nâng cao + +[Các mẫu phức tạp cho người dùng chuyên sâu] +``` + +### Tham chiếu Chéo (Cross-References) + +```markdown +## Các Luồng công việc liên quan + +1. Đầu tiên, dùng `@brainstorming` để thiết kế. +2. Sau đó, dùng `@writing-plans` để lập kế hoạch. +3. Cuối cùng, dùng `@test-driven-development` để triển khai. +``` + +--- + +## Đo lường Hiệu quả của Skill + +Cách để biết skill của bạn có tốt hay không: + +### Kiểm tra Tính Rõ ràng + +- Người không quen thuộc với chủ đề có thể làm theo không? +- Có hướng dẫn nào mơ hồ không? + +### Kiểm tra Tính Đầy đủ + +- Nó có bao quát trường hợp thuận lợi (happy path) không? +- Nó có xử lý các trường hợp biên không? +- Các kịch bản lỗi đã được giải quyết chưa? + +### Kiểm tra Tính Hữu ích + +- Nó có giải quyết một vấn đề thực tế không? +- Chính bạn có sử dụng nó không? +- Nó có giúp tiết kiệm thời gian hoặc cải thiện chất lượng không? + +--- + +## Học hỏi từ các Skill hiện có + +### Nghiên cứu các Ví dụ sau + +**Dành cho Người mới:** + +- `skills/brainstorming/SKILL.md` - Cấu trúc rõ ràng. +- `skills/git-pushing/SKILL.md` - Đơn giản và tập trung. +- `skills/copywriting/SKILL.md` - Ví dụ tốt. + +**Dành cho Nâng cao:** + +- `skills/systematic-debugging/SKILL.md` - Toàn diện. +- `skills/react-best-practices/SKILL.md` - Nhiều file. +- `skills/loki-mode/SKILL.md` - Các luồng công việc phức tạp. + +--- + +## 💡 Mẹo Chuyên nghiệp + +1. **Bắt đầu với phần "Khi nào sử dụng"** - Điều này làm rõ mục đích của skill. +2. **Viết ví dụ trước** - Chúng giúp bạn hiểu những gì bạn đang dạy. +3. **Kiểm tra với AI** - Xem liệu nó có thực sự hoạt động trước khi gửi. +4. **Nhận phản hồi** - Nhờ người khác xem qua skill của bạn. +5. **Cải thiện liên tục** - Skill sẽ tốt lên theo thời gian dựa trên việc sử dụng. + +--- + +## Các lỗi Thường gặp cần Tránh + +### ❌ Lỗi 1: Quá mơ hồ + +```markdown +## Hướng dẫn + +Làm cho code tốt hơn. +``` + +**✅ Khắc phục:** + +```markdown +## Hướng dẫn + +1. Tách các logic lặp lại thành các hàm. +2. Thêm xử lý lỗi cho các trường hợp biên. +3. Viết unit tests cho các chức năng cốt lõi. +``` + +### ❌ Lỗi 2: Quá phức tạp + +```markdown +## Hướng dẫn + +[5000 từ chứa đầy thuật ngữ kỹ thuật dày đặc] +``` + +**✅ Khắc phục:** +Chia nhỏ thành nhiều skill hoặc sử dụng phương pháp tiết lộ lũy tiến. + +### ❌ Lỗi 3: Không có ví dụ + +```markdown +## Hướng dẫn + +[Hướng dẫn mà không có bất kỳ ví dụ code nào] +``` + +**✅ Khắc phục:** +Thêm ít nhất 2-3 ví dụ thực tế. + +### ❌ Lỗi 4: Thông tin lỗi thời + +```markdown +Sử dụng React class components... +``` + +**✅ Khắc phục:** +Luôn cập nhật skill với các thực hành tốt nhất hiện tại. + +--- + +## 🎯 Các bước Tiếp theo + +1. **Đọc 3-5 skill hiện có** để thấy các phong cách khác nhau. +2. **Thử dùng bản mẫu skill** từ file `CONTRIBUTING.md`. +3. **Tạo một skill đơn giản** cho lĩnh vực bạn am hiểu. +4. **Kiểm tra nó** với trợ lý AI của bạn. +5. **Chia sẻ nó** qua Pull Request. + +--- + +**Hãy nhớ rằng:** Mọi chuyên gia đều từng là người mới bắt đầu. Hãy bắt đầu đơn giản, học hỏi từ phản hồi và cải thiện theo thời gian! 🚀 diff --git a/docs/vietnamese/SOURCES.md b/docs/vietnamese/SOURCES.md new file mode 100644 index 00000000..7ec64ee9 --- /dev/null +++ b/docs/vietnamese/SOURCES.md @@ -0,0 +1,21 @@ +# 📜 Nguồn gốc & Ghi công + +Chúng tôi tin tưởng vào việc ghi nhận công sức một cách xứng đáng. +Nếu bạn nhận ra tác phẩm của mình ở đây mà chưa được ghi công đúng cách, vui lòng mở một Issue (Báo lỗi). + +| Kỹ năng / Danh mục | Nguồn gốc | Giấy phép | Ghi chú | +| :-------------------------- | :----------------------------------------------------- | :------------- | :---------------------------- | +| `cloud-penetration-testing` | [HackTricks](https://book.hacktricks.xyz/) | MIT / CC-BY-SA | Được chuyển đổi cho trợ lý AI.| +| `active-directory-attacks` | [HackTricks](https://book.hacktricks.xyz/) | MIT / CC-BY-SA | Được chuyển đổi cho trợ lý AI.| +| `owasp-top-10` | [OWASP](https://owasp.org/) | CC-BY-SA | Chuyển đổi từ phương pháp gốc.| +| `burp-suite-testing` | [PortSwigger](https://portswigger.net/burp) | Không có | Chỉ là hướng dẫn sử dụng. | +| `crewai` | [CrewAI](https://github.com/joaomdmoura/crewAI) | MIT | Hướng dẫn về framework. | +| `langgraph` | [LangGraph](https://github.com/langchain-ai/langgraph) | MIT | Hướng dẫn về framework. | +| `react-patterns` | [React Docs](https://react.dev/) | CC-BY | Các mẫu thiết kế chính thức. | +| **Tất cả Skill Chính thức** | [Anthropic / Google / OpenAI] | Bản quyền riêng| Được khuyến khích bởi nhà CC. | + +## Chính sách Giấy phép + +- **Mã nguồn (Code)**: Tất cả mã nguồn gốc trong repository này tuân theo giấy phép **MIT**. +- **Nội dung (Content)**: Tài liệu hướng dẫn tuân theo giấy phép **CC-BY-4.0**. +- **Bên thứ ba**: Chúng tôi tôn trọng giấy phép từ phía nguồn gốc của các tài liệu. Nếu một kỹ năng được nhập về có giấy phép GPL, nó sẽ được đánh dấu rõ ràng hoặc bị loại trừ (chúng tôi hướng tới sự tương thích với MIT/Apache). diff --git a/docs/vi/VISUAL_GUIDE.md b/docs/vietnamese/VISUAL_GUIDE.md similarity index 62% rename from docs/vi/VISUAL_GUIDE.md rename to docs/vietnamese/VISUAL_GUIDE.md index 18a90a5f..dc7b51bf 100644 --- a/docs/vi/VISUAL_GUIDE.md +++ b/docs/vietnamese/VISUAL_GUIDE.md @@ -1,135 +1,134 @@ -# Hướng Dẫn Nhanh Bằng Hình Ảnh (Visual Quick Start) +# Hướng dẫn Nhanh bằng Hình ảnh (Visual Guide) -**Trăm nghe không bằng một thấy!** Hướng dẫn này sử dụng sơ đồ và ví dụ trực quan để giúp bạn hiểu cách hoạt động của Skills. +**Học qua hình ảnh!** Hướng dẫn này sử dụng các sơ đồ và ví dụ trực quan để giúp bạn hiểu về các kỹ năng (skills). --- -## Bức Tranh Toàn Cảnh +## Cái nhìn Tổng quan ``` ┌─────────────────────────────────────────────────────────────┐ -│ BẠN (Lập trình viên) │ +│ BẠN (Lập trình viên) │ │ ↓ │ -│ "Giúp tôi xây dựng hệ thống thanh toán nhé" │ +│ "Giúp tôi xây dựng hệ thống thanh toán" │ │ ↓ │ -1├─────────────────────────────────────────────────────────────┤ -│ TRỢ LÝ AI │ +├─────────────────────────────────────────────────────────────┤ +│ TRỢ LÝ AI (AI ASSISTANT) │ │ ↓ │ -│ Nạp skill @stripe-integration │ +│ Tải kỹ năng @stripe-integration │ │ ↓ │ -│ Trở thành chuyên gia thanh toán Stripe │ -│ ↓ │ -│ Cung cấp hướng dẫn chuyên sâu kèm code mẫu │ +│ Trở thành chuyên gia về thanh toán Stripe │ │ ↓ │ +│ Cung cấp hỗ trợ chuyên sâu kèm các ví dụ code │ └─────────────────────────────────────────────────────────────┘ ``` --- -## 📦 Cấu trúc Thư mục (Trực quan) +## 📦 Cấu trúc Repository (Trực quan) ``` antigravity-awesome-skills/ │ -├── 📄 README.vi.md ← Tổng quan & Danh sách (Bắt đầu ở đây) -├── 📄 GETTING_STARTED.vi.md ← Hướng dẫn nhập môn -├── 📄 CONTRIBUTING.vi.md ← Hướng dẫn đóng góp -├── 📄 FAQ.vi.md ← Câu hỏi thường gặp +├── 📄 README.md ← Tổng quan & danh sách skill +├── 📄 CONTRIBUTING.md ← Cách thức đóng góp │ -├── 📁 skills/ ← Hơn 250 skill nằm ở đây +├── 📁 skills/ ← Nơi chứa tất cả hơn 250 skills │ │ │ ├── 📁 brainstorming/ -│ │ └── 📄 SKILL.md ← Định nghĩa Skill +│ │ └── 📄 SKILL.md ← Định nghĩa skill │ │ │ ├── 📁 stripe-integration/ │ │ ├── 📄 SKILL.md -│ │ └── 📁 examples/ ← Các ví dụ đi kèm +│ │ └── 📁 examples/ ← Các phần bổ sung tùy chọn │ │ -│ └── ... (250+ skill khác) +│ └── ... (Hơn 250 skills khác) │ -├── 📁 scripts/ ← Các công cụ quản lý -│ ├── validate_skills.py ← Trình kiểm tra chất lượng -│ └── generate_index.py ← Trình tạo mục lục +├── 📁 scripts/ ← Quản lý & Xác thực +│ ├── validate_skills.py ← Công cụ kiểm soát chất lượng +│ └── generate_index.py ← Công cụ tạo danh mục (registry) │ ├── 📁 .github/ -│ └── 📄 MAINTENANCE.md ← Hướng dẫn bảo trì +│ └── 📄 MAINTENANCE.md ← Hướng dẫn cho người duy trì │ -└── 📁 docs/ ← Tài liệu - ├── 📄 BUNDLES.vi.md ← Gói khởi điểm (Starter Packs) +└── 📁 docs/ ← Tài liệu hướng dẫn + ├── 📄 GETTING_STARTED.md ← Bắt đầu tại đây! (MỚI) + ├── 📄 FAQ.md ← Giải đáp thắc mắc + ├── 📄 BUNDLES.md ← Gói khởi đầu (MỚI) ├── 📄 QUALITY_BAR.md ← Tiêu chuẩn chất lượng - ├── 📄 SKILL_ANATOMY.md ← Cấu tạo của một skill - └── 📄 VISUAL_GUIDE.vi.md ← Chính là file này! + ├── 📄 SKILL_ANATOMY.md ← Cách thức skill hoạt động + └── 📄 VISUAL_GUIDE.md ← Chính là file này! ``` --- -## Cách Skill hoạt động (Sơ đồ luồng) +## Cách Skills Hoạt động (Sơ đồ Luồng) ``` ┌──────────────┐ -│ 1. CÀI ĐẶT │ Copy skills vào thư mục .agent/skills/ +│ 1. CÀI ĐẶT │ Sao chép skills vào .agent/skills/ +1 └──────┬───────┘ + │ + ↓ +┌──────────────┐ +│ 2. GỌI LỆNH │ Gõ: @ten-skill trong chat với AI └──────┬───────┘ │ ↓ ┌──────────────┐ -│ 2. RA LỆNH │ Gõ: @ten-skill trong khung chat với AI +│ 3. TẢI DỮ LIỆU│ AI đọc file SKILL.md └──────┬───────┘ │ ↓ ┌──────────────┐ -│ 3. NẠP │ AI đọc nội dung file SKILL.md +│ 4. THỰC THI │ AI tuân theo hướng dẫn trong skill └──────┬───────┘ │ ↓ ┌──────────────┐ -│ 4. THỰC THI │ AI làm theo hướng dẫn trong skill -└──────┬───────┘ - │ - ↓ -┌──────────────┐ -│ 5. KẾT QUẢ │ Bạn nhận được sự hỗ trợ chuyên sâu! +│ 5. KẾT QUẢ │ Bạn nhận được hỗ trợ chuyên sâu! └──────────────┘ ``` --- -## 🎯 Phân loại Skill (Bản đồ tư duy) +## 🎯 Phân loại Skills (Bản đồ Trực quan) ``` ┌─────────────────────────┐ - │ 250+ SKILL TUYỆT ĐỈNH │ + │ 250+ AWESOME SKILLS │ └────────────┬────────────┘ │ ┌────────────────────────┼────────────────────────┐ │ │ │ ┌────▼────┐ ┌──────▼──────┐ ┌──────▼──────┐ - │ SÁNG TẠO│ │ PHÁT TRIỂN │ │ BẢO MẬT │ + │ SÁNG TẠO│ │ PHÁT TRIỂN │ │ BẢO MẬT │ │ (10) │ │ (25) │ │ (50) │ └────┬────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ - • Thiết kế UI/UX • TDD (Test) • Ethical Hacking + • Thiết kế UI/UX • TDD • Hacking Đạo đức • Nghệ thuật Canvas • Debugging • Metasploit - • Tạo Theme • React Patterns • Burp Suite + • Giao diện/Themes • Mẫu thiết kế React • Burp Suite • SQLMap - │ │ │ - └────────────────────────┼────────────────────────┘ + │ │ │ + └────────────────────────┼────────────────────────┘ │ ┌────────────────────────┼────────────────────────┐ │ │ │ ┌────▼────┐ ┌──────▼──────┐ ┌──────▼──────┐ - │ AI │ │ TÀI LIỆU │ │ MARKETING │ + │ AI │ │ TÀI LIỆU │ │ MARKETING │ │ (30) │ │ (4) │ │ (23) │ └────┬────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ • Hệ thống RAG • DOCX • SEO - • LangGraph • PDF • Viết quảng cáo + • LangGraph • PDF • Copywriting • Prompt Eng. • PPTX • CRO - • Voice Agents • XLSX • Chạy Ads + • Voice Agents • XLSX • Quảng cáo trả phí ``` --- -## Giải phẫu một Skill +## Cấu trúc File Skill (Trực quan) ```` ┌─────────────────────────────────────────────────────────┐ @@ -137,33 +136,33 @@ antigravity-awesome-skills/ ├─────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────────────────────────────────────┐ │ -│ │ FRONTMATTER (Metadata - Dữ liệu mô tả) │ │ +│ │ FRONTMATTER (Siêu dữ liệu) │ │ │ │ ───────────────────────────────────────────── │ │ │ │ --- │ │ │ │ name: my-skill │ │ -│ │ description: "Skill này làm cái gì" │ │ +│ │ description: "Công dụng của skill này" │ │ │ │ --- │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────┐ │ -│ │ CONTENT (Nội dung hướng dẫn) │ │ +│ │ NỘI DUNG (Hướng dẫn) │ │ │ │ ───────────────────────────────────────────── │ │ │ │ │ │ -│ │ # Tên Skill │ │ +│ │ # Tiêu đề Skill │ │ │ │ │ │ │ │ ## Tổng quan │ │ -│ │ Skill này giúp bạn... │ │ +│ │ Skill này làm gì... │ │ │ │ │ │ -│ │ ## Khi nào dùng │ │ -│ │ - Dùng khi... │ │ +│ │ ## Khi nào nên dùng │ │ +│ │ - Sử dụng khi... │ │ │ │ │ │ │ │ ## Hướng dẫn │ │ -│ │ 1. Bước một... │ │ -│ │ 2. Bước hai... │ │ +│ │ 1. Bước đầu tiên... │ │ +│ │ 2. Bước thứ hai... │ │ │ │ │ │ │ │ ## Ví dụ │ │ │ │ ```javascript │ │ -│ │ // Code mẫu │ │ +│ │ // Code ví dụ │ │ │ │ ``` │ │ │ │ │ │ │ └───────────────────────────────────────────────┘ │ @@ -173,35 +172,35 @@ antigravity-awesome-skills/ --- -## Quy trình cài đặt (Các bước trực quan) +## Cài đặt (Các bước Trực quan) -### Bước 1: Clone Repo về máy +### Bước 1: Sao chép Repository ``` ┌─────────────────────────────────────────┐ -│ Terminal (Dòng lệnh) │ +│ Terminal │ ├─────────────────────────────────────────┤ │ $ git clone https://github.com/ │ │ sickn33/antigravity-awesome-skills │ │ .agent/skills │ │ │ -│ ✓ Cloning into '.agent/skills'... │ -│ ✓ Done! │ -1└─────────────────────────────────────────┘ +│ ✓ Đang sao chép vào '.agent/skills'... │ +│ ✓ Hoàn tất! │ +└─────────────────────────────────────────┘ ``` -### Bước 2: Kiểm tra cài đặt +### Bước 2: Xác minh Cài đặt ``` ┌─────────────────────────────────────────┐ -│ File Explorer (Quản lý file) │ +│ File Explorer │ ├─────────────────────────────────────────┤ │ 📁 .agent/ │ │ └── 📁 skills/ │ │ ├── 📁 brainstorming/ │ │ ├── 📁 stripe-integration/ │ │ ├── 📁 react-best-practices/ │ -│ └── ... (250+ cái nữa) │ +│ └── ... (Thêm 176 mục nữa) │ └─────────────────────────────────────────┘ ``` @@ -212,124 +211,125 @@ antigravity-awesome-skills/ │ AI Assistant Chat │ ├─────────────────────────────────────────┤ │ Bạn: @brainstorming giúp tôi thiết kế │ -│ một cái app to-do list │ +│ một ứng dụng todo │ │ │ -│ AI: Tuyệt! Để tôi giúp bạn suy nghĩ. │ -│ Trước tiên, hãy xác định yêu cầu. │ +│ AI: Tuyệt vời! Hãy để tôi giúp bạn suy │ +│ nghĩ kỹ về việc này. Đầu tiên, hãy │ +│ tìm hiểu các yêu cầu của bạn... │ │ │ -│ Mục đích chính là gì? │ -│ a) Quản lý việc cá nhân │ -│ b) Cộng tác nhóm │ +│ Mục đích sử dụng chính là gì? │ +│ a) Quản lý công việc cá nhân │ +│ b) Hợp tác nhóm │ │ c) Lập kế hoạch dự án │ └─────────────────────────────────────────┘ ``` --- -## Ví dụ: Một phiên làm việc thực tế +## Ví dụ: Sử dụng Skill (Từng bước) -### Tình huống: Bạn muốn tích hợp thanh toán Stripe +### Tình huống: Bạn muốn thêm thanh toán Stripe vào ứng dụng của mình ``` ┌─────────────────────────────────────────────────────────────┐ -│ BƯỚC 1: Xác định nhu cầu │ +│ BƯỚC 1: Xác định Nhu cầu │ ├─────────────────────────────────────────────────────────────┤ -│ "Tôi cần thêm tính năng thanh toán vào app" │ +│ "Tôi cần thêm xử lý thanh toán vào ứng dụng của mình" │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ -│ BƯỚC 2: Tìm Skill phù hợp │ +│ BƯỚC 2: Tìm đúng Skill │ ├─────────────────────────────────────────────────────────────┤ │ Tìm kiếm: "payment" hoặc "stripe" │ │ Tìm thấy: @stripe-integration │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ -│ BƯỚC 3: Gọi Skill │ +│ BƯỚC 3: Gọi lệnh Skill │ ├─────────────────────────────────────────────────────────────┤ -│ Bạn: @stripe-integration giúp tôi thêm tính năng gói subs │ +│ Bạn: @stripe-integration giúp tôi thêm thanh toán định kỳ │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ -│ BƯỚC 4: AI nạp kiến thức │ +│ BƯỚC 4: AI Tải Kiến thức của Skill │ ├─────────────────────────────────────────────────────────────┤ -│ • Các pattern API của Stripe │ +│ • Các mẫu Stripe API │ │ • Xử lý Webhook │ │ • Quản lý gói đăng ký (Subscription) │ -│ • Các bài thực hành tốt nhất (Best practices) │ +│ • Thực hành tốt nhất │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ -│ BƯỚC 5: Nhận hỗ trợ chuyên gia │ +│ BƯỚC 5: Nhận Hỗ trợ Chuyên gia │ ├─────────────────────────────────────────────────────────────┤ │ AI cung cấp: │ -│ • Code mẫu │ -│ • Hướng dẫn cài đặt │ -│ • Lưu ý bảo mật │ -│ • Chiến lược kiểm thử (Testing) │ +│ • Các ví dụ code │ +│ • Hướng dẫn thiết lập │ +│ • Các lưu ý về bảo mật │ +│ • Chiến lược kiểm thử │ └─────────────────────────────────────────────────────────────┘ ``` --- -## Cách tìm kiếm Skill (Hướng dẫn hình ảnh) +## Tìm kiếm Skills (Hướng dẫn Trực quan) ### Cách 1: Duyệt theo Danh mục ``` -README.vi.md → Cuộn xuống "Danh sách Skill đầy đủ" → Tìm nhóm → Chọn skill +README.md → Cuộn xuống "Full Skill Registry" → Tìm danh mục → Chọn skill ``` -### Cách 2: Tìm theo từ khóa +### Cách 2: Tìm theo Từ khóa ``` -Terminal → ls skills/ | grep "từ-khóa" → Thấy các skill khớp +Terminal → ls skills/ | grep "từ-khóa" → Xem các skill khớp ``` -### Cách 3: Dùng file Index +### Cách 3: Sử dụng Index ``` -Mở skills_index.json → Ctrl+F tìm từ khóa → Lấy đường dẫn skill +Mở file skills_index.json → Tìm từ khóa → Tìm đường dẫn đến skill ``` --- -## Quy trình tạo Skill đầu tay của bạn +## Tạo Skill đầu tiên của bạn (Quy trình Trực quan) ``` ┌──────────────┐ -│ 1. Ý TƯỞNG │ "Tôi muốn chia sẻ kiến thức Docker của mình" +│ 1. Ý TƯỞNG │ "Tôi muốn chia sẻ kiến thức về Docker" └──────┬───────┘ │ ↓ ┌──────────────┐ -│ 2. TẠO FOLDER│ mkdir skills/docker-mastery +│ 2. KHỞI TẠO │ mkdir skills/docker-mastery └──────┬───────┘ touch skills/docker-mastery/SKILL.md │ ↓ ┌──────────────┐ │ 3. VIẾT │ Thêm frontmatter + nội dung -└──────┬───────┘ (Dùng mẫu trong CONTRIBUTING.vi.md) +└──────┬───────┘ (Dùng template từ CONTRIBUTING.md) │ ↓ ┌──────────────┐ -│ 4. THỬ │ Copy vào .agent/skills/ -└──────┬───────┘ Thử gọi: @docker-mastery +│ 4. KIỂM THỬ │ Sao chép vào .agent/skills/ +└──────┬───────┘ Thử: @docker-mastery │ ↓ ┌──────────────┐ -│ 5. KIỂM TRA │ python3 scripts/validate_skills.py +│ 5. XÁC THỰC │ python3 scripts/validate_skills.py └──────┬───────┘ │ ↓ ┌──────────────┐ -│ 6. NỘP BÀI │ git commit + push + Pull Request +│ 6. GỬI ĐI │ git commit + push + Pull Request └──────────────┘ ``` --- -## Các cấp độ phức tạp của Skill +## Các Cấp độ Phức tạp của Skill ``` ┌─────────────────────────────────────────────────────────────┐ @@ -339,48 +339,48 @@ Mở skills_index.json → Ctrl+F tìm từ khóa → Lấy đường dẫn skil │ ĐƠN GIẢN TIÊU CHUẨN PHỨC TẠP │ │ ──────── ────────── ──────── │ │ │ -│ • 1 file • 1 file • Nhiều file -│ • 100-200 từ • 300-800 từ • 800-2000 │ -│ • Cấu trúc cơ bản • Cấu trúc đầy đủ • Scripts │ -│ • Không phụ kiện • Có ví dụ • Có ví dụ │ -│ • Best practices • Template │ -│ • Docs │ -│ Ví dụ: Ví dụ: Ví dụ: │ -│ git-pushing brainstorming loki-mode │ +│ • 1 file • 1 file • Nhiều file│ +│ • 100-200 từ • 300-800 từ • 800-2000 từ│ +│ • Cấu trúc cơ bản • Cấu trúc đầy đủ • Có scripts │ +│ • Không có phần phụ • Có ví dụ • Có ví dụ │ +│ • Thực hành tốt nhất • Có template│ +│ • Có tài liệu│ +│ Ví dụ: Ví dụ: Ví dụ: │ +│ git-pushing brainstorming loki-mode │ │ │ └─────────────────────────────────────────────────────────────┘ ``` --- -## Tác động của việc Đóng góp (Quy trình nhân quả) +## 🎯 Tác động của việc Đóng góp (Trực quan) ``` -Đóng góp của BẠN +Sự đóng góp của bạn │ - ├─→ Cải thiện Tài liệu + ├─→ Cải thiện tài liệu hướng dẫn │ │ - │ └─→ Giúp hàng ngàn lập trình viên đỡ bỡ ngỡ + │ └─→ Giúp hàng ngàn dev dễ hiểu hơn │ - ├─→ Tạo Skill mới + ├─→ Tạo ra Skill mới │ │ - │ └─→ Mở ra khả năng mới cho mọi người + │ └─→ Mang lại khả năng mới cho mọi người │ - ├─→ Sửa lỗi (Bug/Typo) + ├─→ Sửa lỗi/Lỗi chính tả │ │ - │ └─→ Tránh nhầm lẫn cho người sau + │ └─→ Tránh hiểu lầm cho người dùng tương lai │ └─→ Thêm ví dụ │ - └─→ Giúp người mới học nhanh hơn + └─→ Giúp người mới học dễ dàng hơn ``` --- -## Lộ trình học tập (Roadmap trực quan) +## Lộ trình Học tập (Roadmap Trực quan) ``` -BẮT ĐẦU Ở ĐÂY +BẮT ĐẦU TẠI ĐÂY │ ↓ ┌─────────────────┐ @@ -390,8 +390,8 @@ BẮT ĐẦU Ở ĐÂY │ ↓ ┌─────────────────┐ -│ Thử 2-3 Skill │ -│ với AI Assistant│ +│ Thử dùng 2-3 Skill│ +│ với Trợ lý AI │ └────────┬────────┘ │ ↓ @@ -402,13 +402,13 @@ BẮT ĐẦU Ở ĐÂY │ ↓ ┌─────────────────┐ -│ Nghiên cứu code │ -│ của Skill có sẵn│ +│ Nghiên cứu │ +│ Skills hiện có │ └────────┬────────┘ │ ↓ ┌─────────────────┐ -│ Tạo một Skill │ +│ Tạo Skill │ │ đơn giản │ └────────┬────────┘ │ @@ -420,67 +420,93 @@ BẮT ĐẦU Ở ĐÂY │ ↓ ┌─────────────────┐ -│ Gửi PR (Nộp bài)│ +│ Gửi PR │ └────────┬────────┘ │ ↓ - CONTRIBUTOR! 🎉 + TRỞ THÀNH CONTRIBUTOR! 🎉 ``` --- -## Mẹo nhanh (Cheatsheet) +## 💡 Mẹo Nhanh (Bản ghi chú Trực quan) ``` ┌─────────────────────────────────────────────────────────────┐ -│ TRA CỨU NHANH │ +│ THAM KHẢO NHANH │ ├─────────────────────────────────────────────────────────────┤ │ │ │ 📥 CÀI ĐẶT │ │ git clone [repo] .agent/skills │ │ │ -│ 🎯 DÙNG │ +│ 🎯 SỬ DỤNG │ │ @ten-skill [yêu cầu của bạn] │ │ │ -│ 🔍 TÌM │ +│ 🔍 TÌM KIẾM │ │ ls skills/ | grep "từ-khóa" │ │ │ -│ ✅ KIỂM TRA │ +│ ✅ XÁC THỰC │ │ python3 scripts/validate_skills.py │ │ │ -│ 📝 TẠO │ -│ 1. mkdir skills/ten-skill │ -│ 2. Tạo SKILL.md có frontmatter │ -│ 3. Viết nội dung │ -│ 4. Test & validate │ -│ 5. Gửi PR │ +│ 📝 TẠO SKILL │ +│ 1. mkdir skills/ten-skill-cua-ban │ +│ 2. Tạo SKILL.md với frontmatter │ +│ 3. Thêm nội dung │ +│ 4. Thử nghiệm & xác thực │ +│ 5. Gửi Pull Request (PR) │ │ │ │ 🆘 TRỢ GIÚP │ -│ • GETTING_STARTED.vi.md - Cơ bản │ -│ • CONTRIBUTING.vi.md - Cách đóng góp │ -│ • SKILL_ANATOMY.md - Chuyên sâu │ -│ • GitHub Issues - Hỏi đáp │ +│ • docs/GETTING_STARTED.md - Cơ bản │ +│ • CONTRIBUTING.md - Cách đóng góp │ +│ • SKILL_ANATOMY.md - Tìm hiểu sâu │ +│ • GitHub Issues - Đặt câu hỏi │ │ │ └─────────────────────────────────────────────────────────────┘ ``` --- -## Bước tiếp theo +## Câu chuyện Thành công (Dòng thời gian Trực quan) -1. ✅ **Hiểu** cấu trúc qua hình ảnh -2. ✅ **Cài đặt** skills vào công cụ AI của bạn -3. ✅ **Thử** 2-3 skill thuộc các nhóm khác nhau -4. ✅ **Đọc** CONTRIBUTING.vi.md -5. ✅ **Tạo** skill đầu tay -6. ✅ **Chia sẻ** với cộng đồng +``` +Ngày 1: Cài đặt skills + │ + └─→ "Oa, @brainstorming đã giúp mình thiết kế ứng dụng!" + +Ngày 3: Dùng 5 skills khác nhau + │ + └─→ "Những kỹ năng này giúp mình tiết kiệm bao nhiêu thời gian!" + +Tuần 1: Tạo skill đầu tiên + │ + └─→ "Mình đã chia sẻ kiến thức của mình dưới dạng một skill!" + +Tuần 2: Skill được gộp (merge) vào máy chủ + │ + └─→ "Kỹ năng của mình đang giúp đỡ người khác! 🎉" + +Tháng 1: Trở thành người đóng góp thường xuyên + │ + └─→ "Mình đã đóng góp 5 skills và cải thiện rất nhiều tài liệu!" +``` --- -**Bạn học qua hình ảnh tốt hơn?** Hy vọng hướng dẫn này giúp ích! Nếu còn thắc mắc, hãy xem thêm: +## Các Bước Tiếp theo -- [GETTING_STARTED.vi.md](../GETTING_STARTED.vi.md) - Hướng dẫn dạng chữ -- [SKILL_ANATOMY.md](SKILL_ANATOMY.md) - Phân tích chi tiết (Tiếng Anh) -- [CONTRIBUTING.vi.md](../CONTRIBUTING.vi.md) - Cách đóng góp +1. ✅ **Hiểu** cấu trúc trực quan. +2. ✅ **Cài đặt** skills vào công cụ AI của bạn. +3. ✅ **Thử dùng** 2-3 skills từ các danh mục khác nhau. +4. ✅ **Đọc** file CONTRIBUTING.md. +5. ✅ **Tạo** skill đầu tiên của bạn. +6. ✅ **Chia sẻ** với cộng đồng. -**Sẵn sàng đóng góp chưa?** Triển khai thôi! 💪 +--- + +**Bạn là người học qua hình ảnh?** Hy vọng hướng dẫn này sẽ giúp ích! Bạn vẫn còn thắc mắc? Hãy kiểm tra: + +- [GETTING_STARTED.md](GETTING_STARTED.md) - Giới thiệu bằng văn bản. +- [SKILL_ANATOMY.md](SKILL_ANATOMY.md) - Phân tích chi tiết. +- [CONTRIBUTING.md](../CONTRIBUTING.md) - Cách thức đóng góp. + +**Sẵn sàng đóng góp?** Bạn làm được mà! 💪 diff --git a/docs/vietnamese/skills/architecture/SKILL.md b/docs/vietnamese/skills/architecture/SKILL.md new file mode 100644 index 00000000..b0ddd747 --- /dev/null +++ b/docs/vietnamese/skills/architecture/SKILL.md @@ -0,0 +1,55 @@ +--- +name: architecture +description: Khung ra quyết định kiến trúc. Phân tích yêu cầu, đánh giá đánh đổi, tài liệu hóa ADR. Sử dụng khi đưa ra các quyết định kiến trúc hoặc phân tích thiết kế hệ thống. +allowed-tools: Read, Glob, Grep +--- + +# Khung Quyết định Kiến trúc (Architecture Decision Framework) + +> "Yêu cầu thúc đẩy kiến trúc. Sự đánh đổi định hình quyết định. ADRs lưu giữ lý do." + +## 🎯 Quy tắc Đọc Chọn lọc + +**CHỈ ĐỌC các file liên quan đến yêu cầu!** Kiểm tra bản đồ nội dung, tìm thứ bạn cần. + +| File | Mô tả | Khi nào đọc | +|------|-------------|--------------| +| `context-discovery.md` | Các câu hỏi cần đặt ra, phân loại dự án | Bắt đầu thiết kế kiến trúc | +| `trade-off-analysis.md` | Mẫu ADR, khung phân tích đánh đổi | Tài liệu hóa quyết định | +| `pattern-selection.md` | Cây quyết định, anti-patterns | Lựa chọn mẫu (patterns) | +| `examples.md` | Ví dụ MVP, SaaS, Doanh nghiệp lớn | Tham chiếu triển khai | +| `patterns-reference.md` | Tra cứu nhanh các mẫu | So sánh các mẫu | + +--- + +## 🔗 Các Kỹ năng Liên quan + +| Kỹ năng | Dùng cho | +|-------|---------| +| `@[skills/database-design]` | Thiết kế schema cơ sở dữ liệu | +| `@[skills/api-patterns]` | Các mẫu thiết kế API | +| `@[skills/deployment-procedures]` | Kiến trúc triển khai | + +--- + +## Nguyên tắc Cốt lõi + +**"Đơn giản là đỉnh cao của sự tinh tế."** + +- Bắt đầu đơn giản +- CHỈ thêm độ phức tạp khi đã chứng minh là cần thiết +- Bạn luôn có thể thêm các mẫu sau này +- Loại bỏ độ phức tạp khó hơn RẤT NHIỀU so với việc thêm vào + +--- + +## Checklist Xác thực + +Trước khi chốt kiến trúc: + +- [ ] Các yêu cầu đã được hiểu rõ ràng +- [ ] Các ràng buộc đã được xác định +- [ ] Mỗi quyết định đều có phân tích đánh đổi +- [ ] Các phương án thay thế đơn giản hơn đã được xem xét +- [ ] ADRs đã được viết cho các quyết định quan trọng +- [ ] Chuyên môn của đội ngũ phù hợp với các mẫu được chọn diff --git a/docs/vietnamese/skills/concise-planning/SKILL.md b/docs/vietnamese/skills/concise-planning/SKILL.md new file mode 100644 index 00000000..4b2d86e2 --- /dev/null +++ b/docs/vietnamese/skills/concise-planning/SKILL.md @@ -0,0 +1,62 @@ +--- +name: concise-planning +description: Sử dụng khi người dùng yêu cầu lập kế hoạch cho một tác vụ lập trình, nhằm tạo ra một danh sách kiểm tra (checklist) rõ ràng, khả thi và chia nhỏ (atomic). +--- + +# Lập Kế hoạch Súc tích (Concise Planning) + +## Mục tiêu + +Biến yêu cầu của người dùng thành một **kế hoạch hành động duy nhất** với các bước nhỏ, cụ thể (atomic steps). + +## Quy trình làm việc + +### 1. Quét Bối cảnh (Scan Context) + +- Đọc `README.md`, tài liệu và các file code liên quan. +- Xác định các ràng buộc (ngôn ngữ, frameworks, kiểm thử). + +### 2. Tương tác Tối thiểu + +- Hỏi **tối đa 1–2 câu hỏi** và chỉ hỏi nếu thực sự bị chặn (blocking). +- Đưa ra các giả định hợp lý cho những ẩn số không gây cản trở. + +### 3. Tạo Kế hoạch + +Sử dụng cấu trúc sau: + +- **Cách tiếp cận (Approach)**: 1-3 câu về cái gì và tại sao. +- **Phạm vi (Scope)**: Các gạch đầu dòng cho "Trong phạm vi" (In) và "Ngoài phạm vi" (Out). +- **Hạng mục Hành động (Action Items)**: Một danh sách gồm 6-10 tác vụ nhỏ, được sắp xếp theo thứ tự (Bắt đầu bằng động từ). +- **Xác thực (Validation)**: Ít nhất một mục dành cho việc kiểm thử. + +## Mẫu Kế hoạch + +```markdown +# Kế hoạch + + + +## Phạm vi (Scope) + +- Trong phạm vi (In): +- Ngoài phạm vi (Out): + +## Hạng mục Hành động (Action Items) + +[ ] +[ ] +[ ] +[ ] +[ ] + +## Câu hỏi Mở + +- +``` + +## Hướng dẫn Checklist + +- **Tính nguyên tử (Atomic)**: Mỗi bước nên là một đơn vị công việc logic duy nhất. +- **Bắt đầu bằng động từ (Verb-first)**: "Thêm...", "Tái cấu trúc (Refactor)...", "Xác minh...". +- **Cụ thể (Concrete)**: Nêu tên các file hoặc module cụ thể khi có thể. diff --git a/docs/vietnamese/skills/git-pushing/SKILL.md b/docs/vietnamese/skills/git-pushing/SKILL.md new file mode 100644 index 00000000..0fd8f4d4 --- /dev/null +++ b/docs/vietnamese/skills/git-pushing/SKILL.md @@ -0,0 +1,33 @@ +--- +name: git-pushing +description: Stage, commit, và push các thay đổi git với thông điệp commit theo chuẩn (conventional commit messages). Sử dụng khi người dùng muốn commit và push thay đổi, đề cập đến việc đẩy lên remote, hoặc yêu cầu lưu và đẩy công việc của họ. Cũng kích hoạt khi người dùng nói "push changes", "commit and push", "push this", "push to github", hoặc các yêu cầu quy trình công việc git tương tự. +--- + +# Quy trình Git Push + +Stage tất cả thay đổi, tạo một commit theo chuẩn, và đẩy lên nhánh remote. + +## Khi nào nên sử dụng + +Tự động kích hoạt khi người dùng: + +- Yêu cầu đẩy các thay đổi một cách rõ ràng ("push cái này", "commit và push") +- Đề cập đến việc lưu công việc lên remote ("lưu lên github", "push lên remote") +- Hoàn thành một tính năng và muốn chia sẻ nó +- Nói các cụm từ như "hãy push cái này lên" hoặc "commit những thay đổi này" + +## Quy trình làm việc + +**LUÔN LUÔN sử dụng script** - KHÔNG sử dụng các lệnh git thủ công: + +```bash +bash skills/git-pushing/scripts/smart_commit.sh +``` + +Với thông điệp tùy chỉnh: + +```bash +bash skills/git-pushing/scripts/smart_commit.sh "feat: them tinh nang" +``` + +Script sẽ xử lý: staging, thông điệp commit theo chuẩn, footer của Claude, và push với cờ -u. diff --git a/docs/vietnamese/skills/kaizen/SKILL.md b/docs/vietnamese/skills/kaizen/SKILL.md new file mode 100644 index 00000000..5e453ce5 --- /dev/null +++ b/docs/vietnamese/skills/kaizen/SKILL.md @@ -0,0 +1,700 @@ +--- +name: kaizen +description: Hướng dẫn cải tiến liên tục, chống lỗi và chuẩn hóa. Sử dụng kỹ năng này khi người dùng muốn cải thiện chất lượng code, tái cấu trúc (refactor) hoặc thảo luận về cải tiến quy trình. +--- + +# Kaizen: Cải tiến Liên tục + +## Tổng quan + +Những cải tiến nhỏ, diễn ra liên tục. Thiết kế để chống lỗi (Error-proof). Tuân theo những gì hiệu quả. Chỉ xây dựng những gì cần thiết. + +**Nguyên tắc cốt lõi:** Nhiều cải tiến nhỏ đánh bại một thay đổi lớn. Ngăn chặn lỗi ngay từ lúc thiết kế, không phải bằng các bản vá. + +## Khi nào nên Sử dụng + +**Luôn áp dụng cho:** + +- Triển khai và tái cấu trúc code +- Các quyết định về kiến trúc và thiết kế +- Cải thiện quy trình và luồng công việc +- Xử lý lỗi và xác thực (validation) + +**Triết lý:** Chất lượng đến từ sự tiến bộ từng bước và sự ngăn ngừa, không phải sự hoàn hảo thông qua nỗ lực khổng lồ. + +## Bốn Trụ cột + +### 1. Cải tiến Liên tục (Kaizen) + +Những cải tiến nhỏ, thường xuyên sẽ tích lũy thành những thành quả lớn. + +#### Nguyên tắc + +**Gia tăng (Incremental) hơn là Cách mạng:** + +- Thực hiện thay đổi nhỏ nhất có thể nhưng cải thiện được chất lượng +- Một cải tiến tại một thời điểm +- Xác minh từng thay đổi trước khi sang bước tiếp theo +- Xây dựng đà phát triển thông qua những thắng lợi nhỏ + +**Luôn để lại code tốt hơn lúc đầu:** + +- Sửa các vấn đề nhỏ ngay khi bạn gặp chúng +- Refactor trong khi làm việc (trong phạm vi cho phép) +- Cập nhật các comment lỗi thời +- Xóa code chết (dead code) khi bạn thấy nó + +**Tinh chỉnh lặp lại (Iterative refinement):** + +- Phiên bản đầu tiên: làm cho nó hoạt động (work) +- Phiên bản thứ hai: làm cho nó rõ ràng (clear) +- Phiên bản thứ ba: làm cho nó hiệu quả (efficient) +- Đừng cố gắng làm cả ba cùng một lúc + + +```typescript +// Lần lặp 1: Làm cho nó hoạt động +const calculateTotal = (items: Item[]) => { + let total = 0; + for (let i = 0; i < items.length; i++) { + total += items[i].price * items[i].quantity; + } + return total; +}; + +// Lần lặp 2: Làm cho nó rõ ràng (refactor) +const calculateTotal = (items: Item[]): number => { + return items.reduce((total, item) => { + return total + (item.price * item.quantity); + }, 0); +}; + +// Lần lặp 3: Làm cho nó mạnh mẽ (thêm validation) +const calculateTotal = (items: Item[]): number => { + if (!items?.length) return 0; + + return items.reduce((total, item) => { + if (item.price < 0 || item.quantity < 0) { + throw new Error('Price and quantity must be non-negative'); + } + return total + (item.price * item.quantity); + }, 0); +}; +``` +Mỗi bước đều hoàn chỉnh, đã được kiểm thử và hoạt động tốt + + + +```typescript +// Cố gắng làm mọi thứ cùng một lúc +const calculateTotal = (items: Item[]): number => { + // Validate, tối ưu hóa, thêm tính năng, xử lý trường hợp biên cùng lúc + if (!items?.length) return 0; + const validItems = items.filter(item => { + if (item.price < 0) throw new Error('Negative price'); + if (item.quantity < 0) throw new Error('Negative quantity'); + return item.quantity > 0; // Cũng lọc luôn số lượng bằng 0 + }); + // Cộng thêm caching, logging, chuyển đổi tiền tệ... + return validItems.reduce(...); // Quá nhiều mối quan tâm cùng lúc +}; +``` +Choáng ngợp, dễ lỗi, khó xác minh + + +#### Trong Thực tế + +**Khi triển khai tính năng:** + +1. Bắt đầu với phiên bản đơn giản nhất có thể hoạt động +2. Thêm một cải tiến (xử lý lỗi, validation, v.v.) +3. Kiểm thử và xác minh +4. Lặp lại nếu thời gian cho phép +5. Đừng cố làm cho nó hoàn hảo ngay lập tức + +**Khi tái cấu trúc (refactoring):** + +- Sửa từng vấn đề (code smell) một +- Commit sau mỗi cải tiến +- Giữ cho các bài kiểm tra luôn xanh (pass) trong suốt quá trình +- Dừng lại khi "đủ tốt" (hiệu suất giảm dần) + +**Khi review code:** + +- Đề xuất các cải tiến nhỏ (không phải viết lại toàn bộ) +- Ưu tiên: tối quan trọng → quan trọng → có thì tốt (nice-to-have) +- Tập trung vào những thay đổi có tác động lớn nhất trước +- Chấp nhận "tốt hơn trước đó" ngay cả khi chưa hoàn hảo + +### 2. Poka-Yoke (Chống lỗi) + +Thiết kế hệ thống ngăn chặn lỗi tại thời điểm biên dịch/thiết kế, không phải tại thời điểm chạy (runtime). + +#### Nguyên tắc + +**Làm cho lỗi không thể xảy ra:** + +- Hệ thống Type bắt các sai sót +- Trình biên dịch thực thi các hợp đồng (contracts) +- Các trạng thái không hợp lệ không thể biểu diễn được +- Lỗi được bắt sớm (dịch chuyển sang trái quy trình sản xuất - left of production) + +**Thiết kế để an toàn:** + +- Thất bại nhanh và rõ ràng (Fail fast and loudly) +- Cung cấp thông báo lỗi hữu ích +- Làm cho con đường đúng đắn trở nên rõ ràng +- Làm cho con đường sai trở nên khó khăn + +**Phòng thủ theo lớp:** + +1. Hệ thống Type (thời điểm biên dịch) +2. Validation (thời điểm chạy, sớm) +3. Guards (điều kiện tiên quyết) +4. Ranh giới lỗi (xuống cấp nhẹ nhàng - graceful degradation) + +#### Chống lỗi bằng Hệ thống Type + + +```typescript +// Lỗi: trạng thái dạng string có thể là bất kỳ giá trị nào +type OrderBad = { + status: string; // Có thể là "pending", "PENDING", "pnding", bất cứ thứ gì! + total: number; +}; + +// Tốt: Chỉ các trạng thái hợp lệ mới khả thi +type OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered'; +type Order = { + status: OrderStatus; + total: number; +}; + +// Tốt hơn: Trạng thái đi kèm dữ liệu liên quan +type Order = + | { status: 'pending'; createdAt: Date } + | { status: 'processing'; startedAt: Date; estimatedCompletion: Date } + | { status: 'shipped'; trackingNumber: string; shippedAt: Date } + | { status: 'delivered'; deliveredAt: Date; signature: string }; + +// Giờ đây không thể có trạng thái 'shipped' mà thiếu 'trackingNumber' +``` +Hệ thống Type ngăn chặn toàn bộ các lớp lỗi + + + +```typescript +// Làm cho trạng thái không hợp lệ không thể biểu diễn +type NonEmptyArray = [T, ...T[]]; + +const firstItem = (items: NonEmptyArray): T => { + return items[0]; // Luôn an toàn, không bao giờ undefined! +}; + +// Người gọi phải chứng minh mảng không rỗng +const items: number[] = [1, 2, 3]; +if (items.length > 0) { + firstItem(items as NonEmptyArray); // An toàn +} +``` +Chữ ký hàm đảm bảo an toàn + + +#### Chống lỗi bằng Validation + + +```typescript +// Lỗi: Validation sau khi sử dụng +const processPayment = (amount: number) => { + const fee = amount * 0.03; // Đã dùng trước khi validate! + if (amount <= 0) throw new Error('Invalid amount'); + // ... +}; + +// Tốt: Validate ngay lập tức +const processPayment = (amount: number) => { + if (amount <= 0) { + throw new Error('Payment amount must be positive'); + } + if (amount > 10000) { + throw new Error('Payment exceeds maximum allowed'); + } + + const fee = amount * 0.03; + // ... giờ đã an toàn để sử dụng +}; + +// Tốt hơn: Validate tại ranh giới với branded type +type PositiveNumber = number & { readonly __brand: 'PositiveNumber' }; + +const validatePositive = (n: number): PositiveNumber => { + if (n <= 0) throw new Error('Must be positive'); + return n as PositiveNumber; +}; + +const processPayment = (amount: PositiveNumber) => { + // amount được đảm bảo là số dương, không cần kiểm tra lại + const fee = amount * 0.03; +}; + +// Validate tại ranh giới hệ thống +const handlePaymentRequest = (req: Request) => { + const amount = validatePositive(req.body.amount); // Validate một lần + processPayment(amount); // Sử dụng mọi nơi an toàn +}; +``` +Validate một lần tại ranh giới, an toàn ở mọi nơi khác + + +#### Guards và Điều kiện tiên quyết + + +```typescript +// Return sớm ngăn chặn code lồng nhau sâu +const processUser = (user: User | null) => { + if (!user) { + logger.error('User not found'); + return; + } + + if (!user.email) { + logger.error('User email missing'); + return; + } + + if (!user.isActive) { + logger.info('User inactive, skipping'); + return; + } + + // Logic chính ở đây, đảm bảo user hợp lệ và đang hoạt động + sendEmail(user.email, 'Welcome!'); +}; +``` +Guards làm cho các giả định trở nên rõ ràng và được thực thi + + +#### Chống lỗi Cấu hình + + +```typescript +// Lỗi: Cấu hình tùy chọn với mặc định không an toàn +type ConfigBad = { + apiKey?: string; + timeout?: number; +}; + +const client = new APIClient({ timeout: 5000 }); // Thiếu apiKey! + +// Tốt: Cấu hình bắt buộc, lỗi sớm +type Config = { + apiKey: string; + timeout: number; +}; + +const loadConfig = (): Config => { + const apiKey = process.env.API_KEY; + if (!apiKey) { + throw new Error('API_KEY environment variable required'); + } + + return { + apiKey, + timeout: 5000, + }; +}; + +// App lỗi ngay khi khởi động nếu config không hợp lệ, không phải lúc đang request +const config = loadConfig(); +const client = new APIClient(config); +``` +Lỗi lúc khởi động, không phải trong môi trường producton + + +#### Trong Thực tế + +**Khi thiết kế API:** +- Sử dụng Types để ràng buộc đầu vào +- Làm cho trạng thái không hợp lệ không thể biểu diễn +- Trả về Result thay vì ném ra lỗi (throwing) +- Tài liệu hóa các điều kiện tiên quyết trong Types + +**Khi xử lý lỗi:** +- Validate tại ranh giới hệ thống +- Sử dụng guards cho điều kiện tiên quyết +- Lỗi nhanh với thông báo rõ ràng +- Log ngữ cảnh để debug + +**Khi cấu hình:** +- Ưu tiên bắt buộc hơn là tùy chọn có mặc định +- Validate tất cả config lúc khởi động +- Làm thất bại việc triển khai nếu config không hợp lệ +- Không cho phép cấu hình một phần + +### 3. Công việc Chuẩn hóa (Standardized Work) + +Tuân theo các mẫu đã được thiết lập. Tài liệu hóa những gì hiệu quả. Làm cho các thực hành tốt trở nên dễ dàng tuân theo. + +#### Nguyên tắc + +**Nhất quán hơn là Thông minh:** +- Tuân theo các mẫu của codebase hiện có +- Đừng phát minh lại những vấn đề đã được giải quyết +- Mẫu mới chỉ được dùng nếu tốt hơn đáng kể +- Sự đồng thuận của nhóm về các mẫu mới + +**Tài liệu sống cùng code:** +- README cho thiết lập và kiến trúc +- CLAUDE.md cho quy ước lập trình AI +- Comment giải thích "tại sao", không phải "cái gì" +- Ví dụ cho các mẫu phức tạp + +**Tự động hóa các tiêu chuẩn:** +- Linters thực thi phong cách (style) +- Type checks thực thi hợp đồng +- Tests xác minh hành vi +- CI/CD thực thi các cổng kiểm soát chất lượng (quality gates) + +#### Tuân theo các Mẫu (Patterns) + + +```typescript +// Mẫu codebase hiện tại cho API clients +class UserAPIClient { + async getUser(id: string): Promise { + return this.fetch(`/users/${id}`); + } +} + +// Code mới tuân theo cùng một mẫu +class OrderAPIClient { + async getOrder(id: string): Promise { + return this.fetch(`/orders/${id}`); + } +} +``` +Sự nhất quán làm cho codebase dễ dự đoán + + + +```typescript +// Mẫu hiện tại sử dụng class +class UserAPIClient { /* ... */ } + +// Code mới giới thiệu mẫu khác mà không thảo luận +const getOrder = async (id: string): Promise => { + // Phá vỡ sự nhất quán "vì tôi thích dùng hàm hơn" +}; +``` +Sự không nhất quán tạo ra sự nhầm lẫn + + +#### Các Mẫu Xử lý Lỗi + + +```typescript +// Tiêu chuẩn dự án: Kiểu Result cho các lỗi có thể phục hồi +type Result = { ok: true; value: T } | { ok: false; error: E }; + +// Tất cả service tuân theo mẫu này +const fetchUser = async (id: string): Promise> => { + try { + const user = await db.users.findById(id); + if (!user) { + return { ok: false, error: new Error('User not found') }; + } + return { ok: true, value: user }; + } catch (err) { + return { ok: false, error: err as Error }; + } +}; + +// Người gọi sử dụng mẫu nhất quán +const result = await fetchUser('123'); +if (!result.ok) { + logger.error('Failed to fetch user', result.error); + return; +} +const user = result.value; // Type-safe! +``` +Mẫu tiêu chuẩn trên toàn bộ codebase + + +#### Tiêu chuẩn Tài liệu + + +```typescript +/** + * Thử lại một thao tác bất đồng bộ với exponential backoff. + * + * Why: Các yêu cầu mạng thất bại tạm thời; thử lại giúp cải thiện độ tin cậy + * When to use: Gọi API bên ngoài, thao tác cơ sở dữ liệu + * When not to use: Validation đầu vào người dùng, gọi hàm nội bộ + * + * @example + * const result = await retry( + * () => fetch('https://api.example.com/data'), + * { maxAttempts: 3, baseDelay: 1000 } + * ); + */ +const retry = async ( + operation: () => Promise, + options: RetryOptions +): Promise => { + // Implementation... +}; +``` +Tài liệu hóa tại sao, khi nào và làm thế nào + + +#### Trong Thực tế + +**Trước khi thêm mẫu mới:** +- Tìm kiếm trong codebase các vấn đề tương tự đã được giải quyết +- Kiểm tra CLAUDE.md cho các quy ước dự án +- Thảo luận với nhóm nếu phá vỡ mẫu cũ +- Cập nhật tài liệu khi giới thiệu mẫu mới + +**Khi viết code:** +- Khớp với cấu trúc file hiện có +- Sử dụng cùng quy ước đặt tên +- Tuân theo cùng cách tiếp cận xử lý lỗi +- Import từ cùng vị trí + +**Khi review:** +- Kiểm tra tính nhất quán với code hiện có +- Chỉ ra các ví dụ trong codebase +- Đề xuất căn chỉnh với các tiêu chuẩn +- Cập nhật CLAUDE.md nếu có tiêu chuẩn mới xuất hiện + +### 4. Just-In-Time (JIT - Vừa đủ, Đúng lúc) + +Xây dựng những gì cần thiết ngay bây giờ. Không hơn, không kém. Tránh tối ưu hóa sớm và kỹ thuật quá mức (over-engineering). + +#### Nguyên tắc + +**YAGNI (You Aren't Gonna Need It - Bạn sẽ không cần nó đâu):** +- Chỉ triển khai các yêu cầu hiện tại +- Không có tính năng "phòng khi cần" +- Không có code "chúng ta có thể cần cái này sau này" +- Xóa bỏ sự suy đoán + +**Thứ đơn giản nhất có thể hoạt động:** +- Bắt đầu với giải pháp đơn giản, trực tiếp +- Chỉ thêm độ phức tạp khi cần thiết +- Refactor khi yêu cầu thay đổi +- Đừng đoán trước nhu cầu tương lai + +**Tối ưu hóa khi đã đo lường:** +- Không tối ưu hóa sớm +- Đo đạc (profile) trước khi tối ưu +- Đo lường tác động của thay đổi +- Chấp nhận hiệu suất "đủ tốt" + +#### YAGNI trong Hành động + + +```typescript +// Yêu cầu hiện tại: Log lỗi ra console +const logError = (error: Error) => { + console.error(error.message); +}; +``` +Đơn giản, đáp ứng nhu cầu hiện tại + + + +```typescript +// Kỹ thuật quá mức cho "nhu cầu tương lai" +interface LogTransport { + write(level: LogLevel, message: string, meta?: LogMetadata): Promise; +} + +class ConsoleTransport implements LogTransport { /*... */ } +class FileTransport implements LogTransport { /* ... */ } +class RemoteTransport implements LogTransport { /* ...*/ } + +class Logger { + private transports: LogTransport[] = []; + private queue: LogEntry[] = []; + private rateLimiter: RateLimiter; + private formatter: LogFormatter; + + // 200 dòng code cho "có lẽ chúng ta sẽ cần nó" +} + +const logError = (error: Error) => { + Logger.getInstance().log('error', error.message); +}; +``` +Xây dựng cho các yêu cầu tưởng tượng trong tương lai + + +**Khi nào nên thêm độ phức tạp:** +- Yêu cầu hiện tại đòi hỏi nó +- Điểm đau (pain points) được xác định qua quá trình sử dụng +- Các vấn đề hiệu suất đã được đo lường +- Nhiều trường hợp sử dụng xuất hiện + + +```typescript +// Bắt đầu đơn giản +const formatCurrency = (amount: number): string => { + return `$${amount.toFixed(2)}`; +}; + +// Yêu cầu phát triển: hỗ trợ nhiều loại tiền tệ +const formatCurrency = (amount: number, currency: string): string => { + const symbols = { USD: '$', EUR: '€', GBP: '£' }; + return `${symbols[currency]}${amount.toFixed(2)}`; +}; + +// Yêu cầu phát triển: hỗ trợ bản địa hóa (localization) +const formatCurrency = (amount: number, locale: string): string => { + return new Intl.NumberFormat(locale, { + style: 'currency', + currency: locale === 'en-US' ? 'USD' : 'EUR', + }).format(amount); +}; +``` +Độ phức tạp chỉ được thêm vào khi cần + + +#### Trừu tượng hóa Sớm (Premature Abstraction) + + +```typescript +// Một trường hợp sử dụng, nhưng xây dựng framework chung chung +abstract class BaseCRUDService { + abstract getAll(): Promise; + abstract getById(id: string): Promise; + abstract create(data: Partial): Promise; + abstract update(id: string, data: Partial): Promise; + abstract delete(id: string): Promise; +} + +class GenericRepository { /* 300 dòng */ } +class QueryBuilder { /* 200 dòng */ } +// ... xây dựng toàn bộ ORM cho một bảng duy nhất +``` +Trừu tượng hóa khổng lồ cho tương lai không chắc chắn + + + +```typescript +// Các hàm đơn giản cho nhu cầu hiện tại +const getUsers = async (): Promise => { + return db.query('SELECT * FROM users'); +}; + +const getUserById = async (id: string): Promise => { + return db.query('SELECT * FROM users WHERE id = $1', [id]); +}; + +// Khi mẫu xuất hiện trên nhiều thực thể, thì mới trừu tượng hóa +``` +Chỉ trừu tượng hóa khi mẫu đã được chứng minh qua 3+ trường hợp + + +#### Tối ưu hóa Hiệu suất + + +```typescript +// Hiện tại: Tiếp cận đơn giản +const filterActiveUsers = (users: User[]): User[] => { + return users.filter(user => user.isActive); +}; + +// Benchmark cho thấy: 50ms cho 1000 user (chấp nhận được) +// ✓ Ship nó, không cần tối ưu + +// Sau này: Sau khi profiling cho thấy đây là nút thắt cổ chai +// Thì mới tối ưu với tìm kiếm index hoặc caching +``` +Tối ưu hóa dựa trên đo lường, không phải giả định + + + +```typescript +// Tối ưu hóa sớm +const filterActiveUsers = (users: User[]): User[] => { + // "Cái này có thể chậm, nên hãy cache và index" + const cache = new WeakMap(); + const indexed = buildBTreeIndex(users, 'isActive'); + // 100 dòng code tối ưu + // Thêm độ phức tạp, khó bảo trì hơn + // Không có bằng chứng là nó cần thiết +}; +``` +Giải pháp phức tạp cho vấn đề chưa được đo lường + + +#### Trong Thực tế + +**Khi triển khai:** +- Giải quyết vấn đề trước mắt +- Sử dụng cách tiếp cận thẳng thắn +- Chống lại suy nghĩ "nếu như" (what if) +- Xóa code suy đoán + +**Khi tối ưu:** +- Profile trước, tối ưu sau +- Đo trước và sau +- Tài liệu hóa lý do cần tối ưu +- Giữ phiên bản đơn giản trong tests + +**Khi trừu tượng hóa:** +- Đợi cho đến khi có 3+ trường hợp tương tự (Quy tắc số 3) +- Làm cho sự trừu tượng hóa đơn giản nhất có thể +- Thà lặp code còn hơn trừu tượng hóa sai +- Refactor khi mẫu đã rõ ràng + +## Tích hợp với các Lệnh + +Skill Kaizen hướng dẫn cách bạn làm việc. Các lệnh cung cấp phân tích có cấu trúc: + +- **`/why`**: Phân tích nguyên nhân gốc rễ (5 Whys) +- **`/cause-and-effect`**: Phân tích đa yếu tố (Biểu đồ Xương cá) +- **`/plan-do-check-act`**: Các chu trình cải tiến lặp lại +- **`/analyse-problem`**: Tài liệu hóa toàn diện (A3) +- **`/analyse`**: Lựa chọn phương pháp thông minh (Gemba/VSM/Muda) + +Sử dụng các lệnh cho việc giải quyết vấn đề có cấu trúc. Áp dụng skill cho việc phát triển hàng ngày. + +## Cờ Đỏ (Red Flags) + +**Vi phạm Cải tiến Liên tục:** +- "Tôi sẽ refactor nó sau" (không bao giờ xảy ra) +- Để lại code tệ hơn lúc bạn tìm thấy nó +- Viết lại kiểu "big bang" thay vì gia tăng từng chút một + +**Vi phạm Poka-Yoke:** +- "Người dùng chỉ cần cẩn thận là được" +- Validation sau khi sử dụng thay vì trước đó +- Config tùy chọn mà không có validation + +**Vi phạm Công việc Chuẩn hóa:** +- "Tôi thích làm theo cách của mình hơn" +- Không kiểm tra các mẫu hiện có +- Phớt lờ các quy ước dự án + +**Vi phạm Just-In-Time:** +- "Chúng ta có thể cần cái này vào lúc nào đó" +- Xây dựng frameworks trước khi sử dụng chúng +- Tối ưu hóa mà không đo lường + +## Hãy nhớ + +**Kaizen là về:** +- Cải tiến nhỏ liên tục +- Ngăn ngừa lỗi bằng thiết kế +- Tuân theo các mẫu đã được kiểm chứng +- Chỉ xây dựng những gì cần thiết + +**Không phải là về:** +- Hoàn hảo ngay lần thử đầu tiên +- Các dự án refactoring khổng lồ +- Các sự trừu tượng hóa thông minh (clever) +- Tối ưu hóa sớm + +**Tư duy:** Đủ tốt cho hôm nay, tốt hơn vào ngày mai. Lặp lại. diff --git a/docs/vietnamese/skills/lint-and-validate/SKILL.md b/docs/vietnamese/skills/lint-and-validate/SKILL.md new file mode 100644 index 00000000..cebaf490 --- /dev/null +++ b/docs/vietnamese/skills/lint-and-validate/SKILL.md @@ -0,0 +1,44 @@ +--- +name: lint-and-validate +description: "Quy trình kiểm soát chất lượng tự động, linting và phân tích tĩnh. Sử dụng sau mỗi lần sửa đổi code để đảm bảo tính đúng đắn của cú pháp và các tiêu chuẩn dự án. Kích hoạt với từ khóa: lint, format, check, validate, types, static analysis." +allowed-tools: Read, Glob, Grep, Bash +--- + +# Kỹ năng Kiểm tra lỗi và Xác thực (Lint and Validate) + +> **BẮT BUỘC:** Chạy các công cụ xác thực phù hợp sau MỖI lần thay đổi code. Không được hoàn thành tác vụ cho đến khi code không còn lỗi. + +### Quy trình theo Hệ sinh thái + +#### Node.js / TypeScript +1. **Lint/Sửa lỗi:** `npm run lint` hoặc `npx eslint "đường_dẫn" --fix` +2. **Kiểu dữ liệu (Types):** `npx tsc --noEmit` +3. **Bảo mật:** `npm audit --audit-level=high` + +#### Python +1. **Linter (Ruff):** `ruff check "đường_dẫn" --fix` (Nhanh & Hiện đại) +2. **Bảo mật (Bandit):** `bandit -r "đường_dẫn" -ll` +3. **Kiểu dữ liệu (MyPy):** `mypy "đường_dẫn"` + +## Vòng lặp Chất lượng +1. **Viết/Sửa Code** +2. **Chạy Kiểm tra (Audit):** `npm run lint && npx tsc --noEmit` +3. **Phân tích Báo cáo:** Kiểm tra phần "BÁO CÁO KIỂM TRA CUỐI CÙNG" (FINAL AUDIT REPORT). +4. **Sửa & Lặp lại:** Việc gửi code có lỗi trong "KIỂM TRA CUỐI CÙNG" là KHÔNG được phép. + +## Xử lý Lỗi +- Nếu `lint` thất bại: Sửa ngay các lỗi về phong cách (style) hoặc cú pháp. +- Nếu `tsc` thất bại: Sửa các lỗi không khớp kiểu dữ liệu trước khi tiếp tục. +- Nếu không có công cụ nào được cấu hình: Kiểm tra thư mục gốc dự án xem có `.eslintrc`, `tsconfig.json`, `pyproject.toml` không và đề xuất tạo mới. + +--- +**Quy tắc Nghiêm ngặt:** Không được commit hoặc báo cáo code là "hoàn thành" nếu chưa vượt qua các kiểm tra này. + +--- + +## Scripts + +| Script | Mục đích | Lệnh | +|--------|---------|---------| +| `scripts/lint_runner.py` | Kiểm tra lint hợp nhất | `python scripts/lint_runner.py ` | +| `scripts/type_coverage.py` | Phân tích độ bao phủ kiểu dữ liệu | `python scripts/type_coverage.py ` | diff --git a/docs/vietnamese/skills/senior-architect/SKILL.md b/docs/vietnamese/skills/senior-architect/SKILL.md new file mode 100644 index 00000000..112341cf --- /dev/null +++ b/docs/vietnamese/skills/senior-architect/SKILL.md @@ -0,0 +1,209 @@ +--- +name: senior-architect +description: Kỹ năng kiến trúc phần mềm toàn diện để thiết kế các hệ thống có khả năng mở rộng, dễ bảo trì sử dụng ReactJS, NextJS, NodeJS, Express, React Native, Swift, Kotlin, Flutter, Postgres, GraphQL, Go, Python. Bao gồm tạo sơ đồ kiến trúc, các mẫu thiết kế hệ thống, khung quyết định về tech stack và phân tích phụ thuộc. Sử dụng khi thiết kế kiến trúc hệ thống, đưa ra các quyết định kỹ thuật, tạo sơ đồ kiến trúc, đánh giá sự đánh đổi hoặc xác định các mẫu tích hợp. +--- + +# Kiến trúc sư Cao cấp (Senior Architect) + +Bộ công cụ hoàn chỉnh cho kiến trúc sư cao cấp với các công cụ hiện đại và thực hành tốt nhất. + +## Khởi động Nhanh + +### Các Khả năng Chính + +Kỹ năng này cung cấp ba khả năng cốt lõi thông qua các script tự động: + +```bash +# Script 1: Trình tạo Sơ đồ Kiến trúc +python scripts/architecture_diagram_generator.py [options] + +# Script 2: Kiến trúc sư Dự án +python scripts/project_architect.py [options] + +# Script 3: Bộ phân tích Phụ thuộc +python scripts/dependency_analyzer.py [options] +``` + +## Các Khả năng Cốt lõi + +### 1. Trình tạo Sơ đồ Kiến trúc (Architecture Diagram Generator) + +Công cụ tự động cho các tác vụ tạo sơ đồ kiến trúc. + +**Tính năng:** +- Dựng khung (scaffolding) tự động +- Tích hợp sẵn thực hành tốt nhất +- Mẫu có thể cấu hình +- Kiểm tra chất lượng + +**Cách dùng:** +```bash +python scripts/architecture_diagram_generator.py [options] +``` + +### 2. Kiến trúc sư Dự án (Project Architect) + +Công cụ phân tích và tối ưu hóa toàn diện. + +**Tính năng:** +- Phân tích sâu +- Chỉ số hiệu năng +- Đề xuất +- Tự động sửa lỗi + +**Cách dùng:** +```bash +python scripts/project_architect.py [--verbose] +``` + +### 3. Bộ phân tích Phụ thuộc (Dependency Analyzer) + +Công cụ nâng cao cho các tác vụ chuyên biệt. + +**Tính năng:** +- Tự động hóa cấp độ chuyên gia +- Cấu hình tùy chỉnh +- Sẵn sàng tích hợp +- Đầu ra chuẩn production + +**Cách dùng:** +```bash +python scripts/dependency_analyzer.py [arguments] [options] +``` + +## Tài liệu Tham khảo + +### Các Mẫu Kiến trúc + +Hướng dẫn toàn diện có sẵn tại `references/architecture_patterns.md`: + +- Các mẫu và cách thực hành chi tiết +- Ví dụ code +- Thực hành tốt nhất +- Các anti-patterns cần tránh +- Các kịch bản thực tế + +### Quy trình Thiết kế Hệ thống + +Tài liệu quy trình hoàn chỉnh tại `references/system_design_workflows.md`: + +- Quy trình từng bước +- Chiến lược tối ưu hóa +- Tích hợp công cụ +- Tinh chỉnh hiệu năng +- Hướng dẫn khắc phục sự cố + +### Hướng dẫn Quyết định Kỹ thuật + +Hướng dẫn tham chiếu kỹ thuật tại `references/tech_decision_guide.md`: + +- Chi tiết về tech stack +- Ví dụ cấu hình +- Các mẫu tích hợp +- Các cân nhắc về bảo mật +- Hướng dẫn về khả năng mở rộng + +## Tech Stack + +**Ngôn ngữ:** TypeScript, JavaScript, Python, Go, Swift, Kotlin +**Frontend:** React, Next.js, React Native, Flutter +**Backend:** Node.js, Express, GraphQL, REST APIs +**Cơ sở dữ liệu:** PostgreSQL, Prisma, NeonDB, Supabase +**DevOps:** Docker, Kubernetes, Terraform, GitHub Actions, CircleCI +**Cloud:** AWS, GCP, Azure + +## Quy trình Phát triển + +### 1. Thiết lập và Cấu hình + +```bash +# Cài đặt dependencies +npm install +# hoặc +pip install -r requirements.txt + +# Cấu hình môi trường +cp .env.example .env +``` + +### 2. Chạy Kiểm tra Chất lượng + +```bash +# Sử dụng script phân tích +python scripts/project_architect.py . + +# Xem xét các đề xuất +# Áp dụng các bản sửa lỗi +``` + +### 3. Triển khai Thực hành Tốt nhất + +Tuân theo các mẫu và thực hành được tài liệu hóa trong: +- `references/architecture_patterns.md` +- `references/system_design_workflows.md` +- `references/tech_decision_guide.md` + +## Tóm tắt Thực hành Tốt nhất + +### Chất lượng Code +- Tuân theo các mẫu đã được thiết lập +- Viết bài kiểm tra toàn diện +- Tài liệu hóa các quyết định +- Review thường xuyên + +### Hiệu năng +- Đo lường trước khi tối ưu hóa +- Sử dụng bộ nhớ đệm (caching) phù hợp +- Tối ưu hóa các đường dẫn quan trọng (critical paths) +- Giám sát trên production + +### Bảo mật +- Validate tất cả đầu vào +- Sử dụng parameterized queries +- Triển khai xác thực (authentication) đúng cách +- Giữ các dependencies luôn cập nhật + +### Khả năng Bảo trì +- Viết code rõ ràng +- Sử dụng cách đặt tên nhất quán +- Thêm comment hữu ích +- Giữ cho mọi thứ đơn giản + +## Các Lệnh Phổ biến + +```bash +# Phát triển +npm run dev +npm run build +npm run test +npm run lint + +# Phân tích +python scripts/project_architect.py . +python scripts/dependency_analyzer.py --analyze + +# Triển khai +docker build -t app:latest . +docker-compose up -d +kubectl apply -f k8s/ +``` + +## Khắc phục Sự cố + +### Các Vấn đề Phổ biến + +Kiểm tra phần khắc phục sự cố toàn diện trong `references/tech_decision_guide.md`. + +### Nhận Trợ giúp + +- Xem lại tài liệu tham khảo +- Kiểm tra thông báo đầu ra của script +- Tham khảo tài liệu của tech stack +- Xem lại nhật ký lỗi (error logs) + +## Tài nguyên + +- Tham chiếu Mẫu: `references/architecture_patterns.md` +- Hướng dẫn Quy trình: `references/system_design_workflows.md` +- Hướng dẫn Kỹ thuật: `references/tech_decision_guide.md` +- Tool Scripts: Thư mục `scripts/` diff --git a/skills/README.md b/skills/README.md index 17a65a38..e536163f 100644 --- a/skills/README.md +++ b/skills/README.md @@ -170,9 +170,9 @@ description: "What this skill does" ## Documentation -- **[Getting Started](../GETTING_STARTED.md)** - Quick start guide +- **[Getting Started](../docs/GETTING_STARTED.md)** - Quick start guide - **[Examples](../docs/EXAMPLES.md)** - Real-world usage examples -- **[FAQ](../FAQ.md)** - Common questions +- **[FAQ](../docs/FAQ.md)** - Common questions - **[Visual Guide](../docs/VISUAL_GUIDE.md)** - Diagrams and flowcharts --- @@ -198,4 +198,4 @@ Found a skill that needs improvement? Want to add a new skill? --- -**Need help?** Check the [FAQ](../FAQ.md) or open an issue on GitHub! +**Need help?** Check the [FAQ](../docs/FAQ.md) or open an issue on GitHub! From 2fc3237ef97e6fdc3248b86738fa6499eb97c7ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C4=90=E1=BB=97=20Kh=E1=BA=AFc=20Gia=20Khoa?= Date: Thu, 29 Jan 2026 04:12:25 +0700 Subject: [PATCH 02/10] chore: rename translation files to .vi.md extension --- docs/vietnamese/{BUNDLES.md => BUNDLES.vi.md} | 0 .../{CONTRIBUTING.md => CONTRIBUTING.vi.md} | 0 docs/vietnamese/{EXAMPLES.md => EXAMPLES.vi.md} | 0 docs/vietnamese/{FAQ.md => FAQ.vi.md} | 6 +++--- .../{GETTING_STARTED.md => GETTING_STARTED.vi.md} | 10 +++++----- .../{QUALITY_BAR.md => QUALITY_BAR.vi.md} | 0 docs/vietnamese/{README.md => README.vi.md} | 14 +++++++------- ...ITY_GUARDRAILS.md => SECURITY_GUARDRAILS.vi.md} | 0 .../{SKILL_ANATOMY.md => SKILL_ANATOMY.vi.md} | 0 docs/vietnamese/{SOURCES.md => SOURCES.vi.md} | 0 .../{VISUAL_GUIDE.md => VISUAL_GUIDE.vi.md} | 8 ++++---- .../skills/architecture/{SKILL.md => SKILL.vi.md} | 0 .../concise-planning/{SKILL.md => SKILL.vi.md} | 0 .../skills/git-pushing/{SKILL.md => SKILL.vi.md} | 0 .../skills/kaizen/{SKILL.md => SKILL.vi.md} | 0 .../lint-and-validate/{SKILL.md => SKILL.vi.md} | 0 .../senior-architect/{SKILL.md => SKILL.vi.md} | 0 17 files changed, 19 insertions(+), 19 deletions(-) rename docs/vietnamese/{BUNDLES.md => BUNDLES.vi.md} (100%) rename docs/vietnamese/{CONTRIBUTING.md => CONTRIBUTING.vi.md} (100%) rename docs/vietnamese/{EXAMPLES.md => EXAMPLES.vi.md} (100%) rename docs/vietnamese/{FAQ.md => FAQ.vi.md} (97%) rename docs/vietnamese/{GETTING_STARTED.md => GETTING_STARTED.vi.md} (93%) rename docs/vietnamese/{QUALITY_BAR.md => QUALITY_BAR.vi.md} (100%) rename docs/vietnamese/{README.md => README.vi.md} (97%) rename docs/vietnamese/{SECURITY_GUARDRAILS.md => SECURITY_GUARDRAILS.vi.md} (100%) rename docs/vietnamese/{SKILL_ANATOMY.md => SKILL_ANATOMY.vi.md} (100%) rename docs/vietnamese/{SOURCES.md => SOURCES.vi.md} (100%) rename docs/vietnamese/{VISUAL_GUIDE.md => VISUAL_GUIDE.vi.md} (99%) rename docs/vietnamese/skills/architecture/{SKILL.md => SKILL.vi.md} (100%) rename docs/vietnamese/skills/concise-planning/{SKILL.md => SKILL.vi.md} (100%) rename docs/vietnamese/skills/git-pushing/{SKILL.md => SKILL.vi.md} (100%) rename docs/vietnamese/skills/kaizen/{SKILL.md => SKILL.vi.md} (100%) rename docs/vietnamese/skills/lint-and-validate/{SKILL.md => SKILL.vi.md} (100%) rename docs/vietnamese/skills/senior-architect/{SKILL.md => SKILL.vi.md} (100%) diff --git a/docs/vietnamese/BUNDLES.md b/docs/vietnamese/BUNDLES.vi.md similarity index 100% rename from docs/vietnamese/BUNDLES.md rename to docs/vietnamese/BUNDLES.vi.md diff --git a/docs/vietnamese/CONTRIBUTING.md b/docs/vietnamese/CONTRIBUTING.vi.md similarity index 100% rename from docs/vietnamese/CONTRIBUTING.md rename to docs/vietnamese/CONTRIBUTING.vi.md diff --git a/docs/vietnamese/EXAMPLES.md b/docs/vietnamese/EXAMPLES.vi.md similarity index 100% rename from docs/vietnamese/EXAMPLES.md rename to docs/vietnamese/EXAMPLES.vi.md diff --git a/docs/vietnamese/FAQ.md b/docs/vietnamese/FAQ.vi.md similarity index 97% rename from docs/vietnamese/FAQ.md rename to docs/vietnamese/FAQ.vi.md index 13313eb6..83756506 100644 --- a/docs/vietnamese/FAQ.md +++ b/docs/vietnamese/FAQ.vi.md @@ -15,7 +15,7 @@ Skills là các tệp hướng dẫn chuyên biệt dạy cho các trợ lý AI **Không!** Khi bạn clone (tải bản sao) repository này, tất cả các kỹ năng đều có sẵn, nhưng AI của bạn chỉ tải chúng khi bạn yêu cầu rõ ràng bằng lệnh `@ten-skill`. Nó giống như việc sở hữu một thư viện - tất cả sách đều ở đó, nhưng bạn chỉ đọc những cuốn bạn cần thôi. -**Mẹo:** Sử dụng [Bản mẫu Khởi đầu (Starter Packs)](BUNDLES.md) để chỉ cài đặt những gì phù hợp với vai trò của bạn. +**Mẹo:** Sử dụng [Bản mẫu Khởi đầu (Starter Packs)](BUNDLES.vi.md) để chỉ cài đặt những gì phù hợp với vai trò của bạn. ### Những công cụ AI nào hoạt động với các kỹ năng này? @@ -116,7 +116,7 @@ Sử dụng biểu tượng `@` theo sau là tên skill: ### Làm thế nào để tôi biết nên dùng kỹ năng nào? -1. **Duyệt qua danh mục**: Xem [Danh mục Skill (Skill Catalog)](../CATALOG.md). +1. **Duyệt qua danh mục**: Xem [Danh mục Skill (Skill Catalog)](../CATALOG.vi.md). 2. **Tìm kiếm**: `ls skills/ | grep "từ-khóa"` 3. **Hỏi AI của bạn**: "Bạn có kỹ năng nào để kiểm thử (testing) không?" @@ -152,7 +152,7 @@ Vui lòng gửi kèm: - Sửa lỗi đánh máy. - Thêm ví dụ. - Cải thiện tài liệu hướng dẫn. -Hãy xem [CONTRIBUTING.md](../CONTRIBUTING.md) để biết hướng dẫn chi tiết. +Hãy xem [CONTRIBUTING.md](../CONTRIBUTING.vi.md) để biết hướng dẫn chi tiết. ### Pull Request (PR) của tôi thất bại khi kiểm tra "Quality Bar". Tại sao? diff --git a/docs/vietnamese/GETTING_STARTED.md b/docs/vietnamese/GETTING_STARTED.vi.md similarity index 93% rename from docs/vietnamese/GETTING_STARTED.md rename to docs/vietnamese/GETTING_STARTED.vi.md index b5c01a13..6862d2d5 100644 --- a/docs/vietnamese/GETTING_STARTED.md +++ b/docs/vietnamese/GETTING_STARTED.vi.md @@ -29,7 +29,7 @@ git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skill ### 2. Chọn vai trò của bạn -Tìm gói kỹ năng phù hợp với vị trí của bạn (xem [BUNDLES.md](BUNDLES.md)): +Tìm gói kỹ năng phù hợp với vị trí của bạn (xem [BUNDLES.md](BUNDLES.vi.md)): | Vai trò | Tên Gói kỹ năng | Bên trong có những gì? | | :-------------------- | :-------------- | :------------------------------------------------ | @@ -84,7 +84,7 @@ Chúng tôi phân loại các kỹ năng để bạn biết mình đang chạy n - 🔵 **Safe (An toàn)**: Các kỹ năng cộng đồng không gây hại (Chỉ đọc/Lập kế hoạch). - 🔴 **Risk (Rủi ro)**: Các kỹ năng sửa đổi hệ thống hoặc thực hiện kiểm thử bảo mật (Sử dụng khi được cấp phép). -_Kiểm tra [Danh mục Skill (Skill Catalog)](../CATALOG.md) để xem danh sách đầy đủ._ +_Kiểm tra [Danh mục Skill (Skill Catalog)](../CATALOG.vi.md) để xem danh sách đầy đủ._ --- @@ -103,6 +103,6 @@ _Kiểm tra [Danh mục Skill (Skill Catalog)](../CATALOG.md) để xem danh sá ## ⏭️ Các bước tiếp theo -1. [Duyệt qua các Gói kỹ năng (Bundles)](BUNDLES.md) -2. [Xem các Ví dụ thực tế (Examples)](EXAMPLES.md) -3. [Đóng góp một Skill mới](../CONTRIBUTING.md) +1. [Duyệt qua các Gói kỹ năng (Bundles)](BUNDLES.vi.md) +2. [Xem các Ví dụ thực tế (Examples)](EXAMPLES.vi.md) +3. [Đóng góp một Skill mới](../CONTRIBUTING.vi.md) diff --git a/docs/vietnamese/QUALITY_BAR.md b/docs/vietnamese/QUALITY_BAR.vi.md similarity index 100% rename from docs/vietnamese/QUALITY_BAR.md rename to docs/vietnamese/QUALITY_BAR.vi.md diff --git a/docs/vietnamese/README.md b/docs/vietnamese/README.vi.md similarity index 97% rename from docs/vietnamese/README.md rename to docs/vietnamese/README.vi.md index 401712a4..64c23a1d 100644 --- a/docs/vietnamese/README.md +++ b/docs/vietnamese/README.vi.md @@ -58,7 +58,7 @@ Các trợ lý AI (như Claude Code, Cursor, hoặc Gemini) rất thông minh, n ```bash git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills ``` -2. **Chọn vai trò của bạn** (Xem [docs/vietnamese/BUNDLES.md](docs/vietnamese/BUNDLES.md)): +2. **Chọn vai trò của bạn** (Xem [docs/vietnamese/BUNDLES.md](docs/vietnamese/BUNDLES.vi.md)): - **Lập trình Web?** sử dụng gói `Web Wizard`. - **Hacker?** sử dụng gói `Security Engineer`. - **Chỉ tò mò thôi?** bắt đầu với gói `Essentials`. @@ -70,7 +70,7 @@ Sau khi cài đặt, chỉ cần hỏi trợ lý của bạn một cách tự nh > "Sử dụng kỹ năng **@brainstorming** để giúp tôi lập kế hoạch cho một dự án SaaS." > "Chạy **@lint-and-validate** trên file này." -👉 **[Đọc Hướng dẫn bắt đầu đầy đủ](docs/vietnamese/GETTING_STARTED.md)** +👉 **[Đọc Hướng dẫn bắt đầu đầy đủ](docs/vietnamese/GETTING_STARTED.vi.md)** --- @@ -118,13 +118,13 @@ Repository được tổ chức thành các lĩnh vực chuyên biệt để bi ## Bộ sưu tập Tuyển chọn -[Xem các Gói khởi đầu tại docs/vietnamese/BUNDLES.md](docs/vietnamese/BUNDLES.md) để tìm bộ công cụ hoàn hảo cho vai trò của bạn. +[Xem các Gói khởi đầu tại docs/vietnamese/BUNDLES.md](docs/vietnamese/BUNDLES.vi.md) để tìm bộ công cụ hoàn hảo cho vai trò của bạn. ## Duyệt hơn 552 Kỹ năng Chúng tôi đã chuyển danh sách đầy đủ các kỹ năng sang một danh mục riêng biệt để giữ cho file README này gọn gàng. -👉 **[Xem Danh mục Kỹ năng Đầy đủ (CATALOG.md)](CATALOG.md)** +👉 **[Xem Danh mục Kỹ năng Đầy đủ (CATALOG.vi.md)](CATALOG.vi.md)** ## Cài đặt @@ -164,7 +164,7 @@ Vui lòng đảm bảo kỹ năng của bạn tuân thủ các thực hành tố Chúng tôi đứng trên vai của những người khổng lồ. -👉 **[Xem Sổ cái Ghi công Đầy đủ (docs/vietnamese/SOURCES.md)](docs/vietnamese/SOURCES.md)** +👉 **[Xem Sổ cái Ghi công Đầy đủ (docs/vietnamese/SOURCES.vi.md)](docs/vietnamese/SOURCES.vi.md)** Các nguồn đóng góp và nguồn chính bao gồm: @@ -216,8 +216,8 @@ Giấy phép MIT. Xem file [LICENSE](LICENSE) để biết chi tiết. ## Cộng đồng -- [Cộng đồng (Community Guidelines)](docs/vietnamese/COMMUNITY_GUIDELINES.md) -- [Chính sách Bảo mật (Security Policy)](docs/vietnamese/SECURITY_GUARDRAILS.md) +- [Cộng đồng (Community Guidelines)](docs/vietnamese/COMMUNITY_GUIDELINES.vi.md) +- [Chính sách Bảo mật (Security Policy)](docs/vietnamese/SECURITY_GUARDRAILS.vi.md) --- diff --git a/docs/vietnamese/SECURITY_GUARDRAILS.md b/docs/vietnamese/SECURITY_GUARDRAILS.vi.md similarity index 100% rename from docs/vietnamese/SECURITY_GUARDRAILS.md rename to docs/vietnamese/SECURITY_GUARDRAILS.vi.md diff --git a/docs/vietnamese/SKILL_ANATOMY.md b/docs/vietnamese/SKILL_ANATOMY.vi.md similarity index 100% rename from docs/vietnamese/SKILL_ANATOMY.md rename to docs/vietnamese/SKILL_ANATOMY.vi.md diff --git a/docs/vietnamese/SOURCES.md b/docs/vietnamese/SOURCES.vi.md similarity index 100% rename from docs/vietnamese/SOURCES.md rename to docs/vietnamese/SOURCES.vi.md diff --git a/docs/vietnamese/VISUAL_GUIDE.md b/docs/vietnamese/VISUAL_GUIDE.vi.md similarity index 99% rename from docs/vietnamese/VISUAL_GUIDE.md rename to docs/vietnamese/VISUAL_GUIDE.vi.md index dc7b51bf..322e01bc 100644 --- a/docs/vietnamese/VISUAL_GUIDE.md +++ b/docs/vietnamese/VISUAL_GUIDE.vi.md @@ -309,7 +309,7 @@ Mở file skills_index.json → Tìm từ khóa → Tìm đường dẫn đến ↓ ┌──────────────┐ │ 3. VIẾT │ Thêm frontmatter + nội dung -└──────┬───────┘ (Dùng template từ CONTRIBUTING.md) +└──────┬───────┘ (Dùng template từ CONTRIBUTING.vi.md) │ ↓ ┌──────────────┐ @@ -505,8 +505,8 @@ Tháng 1: Trở thành người đóng góp thường xuyên **Bạn là người học qua hình ảnh?** Hy vọng hướng dẫn này sẽ giúp ích! Bạn vẫn còn thắc mắc? Hãy kiểm tra: -- [GETTING_STARTED.md](GETTING_STARTED.md) - Giới thiệu bằng văn bản. -- [SKILL_ANATOMY.md](SKILL_ANATOMY.md) - Phân tích chi tiết. -- [CONTRIBUTING.md](../CONTRIBUTING.md) - Cách thức đóng góp. +- [GETTING_STARTED.md](GETTING_STARTED.vi.md) - Giới thiệu bằng văn bản. +- [SKILL_ANATOMY.md](SKILL_ANATOMY.vi.md) - Phân tích chi tiết. +- [CONTRIBUTING.md](../CONTRIBUTING.vi.md) - Cách thức đóng góp. **Sẵn sàng đóng góp?** Bạn làm được mà! 💪 diff --git a/docs/vietnamese/skills/architecture/SKILL.md b/docs/vietnamese/skills/architecture/SKILL.vi.md similarity index 100% rename from docs/vietnamese/skills/architecture/SKILL.md rename to docs/vietnamese/skills/architecture/SKILL.vi.md diff --git a/docs/vietnamese/skills/concise-planning/SKILL.md b/docs/vietnamese/skills/concise-planning/SKILL.vi.md similarity index 100% rename from docs/vietnamese/skills/concise-planning/SKILL.md rename to docs/vietnamese/skills/concise-planning/SKILL.vi.md diff --git a/docs/vietnamese/skills/git-pushing/SKILL.md b/docs/vietnamese/skills/git-pushing/SKILL.vi.md similarity index 100% rename from docs/vietnamese/skills/git-pushing/SKILL.md rename to docs/vietnamese/skills/git-pushing/SKILL.vi.md diff --git a/docs/vietnamese/skills/kaizen/SKILL.md b/docs/vietnamese/skills/kaizen/SKILL.vi.md similarity index 100% rename from docs/vietnamese/skills/kaizen/SKILL.md rename to docs/vietnamese/skills/kaizen/SKILL.vi.md diff --git a/docs/vietnamese/skills/lint-and-validate/SKILL.md b/docs/vietnamese/skills/lint-and-validate/SKILL.vi.md similarity index 100% rename from docs/vietnamese/skills/lint-and-validate/SKILL.md rename to docs/vietnamese/skills/lint-and-validate/SKILL.vi.md diff --git a/docs/vietnamese/skills/senior-architect/SKILL.md b/docs/vietnamese/skills/senior-architect/SKILL.vi.md similarity index 100% rename from docs/vietnamese/skills/senior-architect/SKILL.md rename to docs/vietnamese/skills/senior-architect/SKILL.vi.md From 6b517ed29abec81425535d3b7f145a10e5d8b686 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C4=90=E1=BB=97=20Kh=E1=BA=AFc=20Gia=20Khoa?= Date: Thu, 29 Jan 2026 04:21:55 +0700 Subject: [PATCH 03/10] feat: translate top 5 development skills (clean-code, TS, React, Python, Node) --- docs/vietnamese/TRANSLATION_PLAN.vi.md | 121 ++++++ docs/vietnamese/skills/clean-code/SKILL.vi.md | 200 +++++++++ .../nodejs-backend-patterns/SKILL.vi.md | 35 ++ docs/vietnamese/skills/python-pro/SKILL.vi.md | 157 +++++++ .../skills/react-best-practices/SKILL.vi.md | 121 ++++++ .../skills/typescript-expert/SKILL.vi.md | 405 ++++++++++++++++++ 6 files changed, 1039 insertions(+) create mode 100644 docs/vietnamese/TRANSLATION_PLAN.vi.md create mode 100644 docs/vietnamese/skills/clean-code/SKILL.vi.md create mode 100644 docs/vietnamese/skills/nodejs-backend-patterns/SKILL.vi.md create mode 100644 docs/vietnamese/skills/python-pro/SKILL.vi.md create mode 100644 docs/vietnamese/skills/react-best-practices/SKILL.vi.md create mode 100644 docs/vietnamese/skills/typescript-expert/SKILL.vi.md diff --git a/docs/vietnamese/TRANSLATION_PLAN.vi.md b/docs/vietnamese/TRANSLATION_PLAN.vi.md new file mode 100644 index 00000000..028c595b --- /dev/null +++ b/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//.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/`. diff --git a/docs/vietnamese/skills/clean-code/SKILL.vi.md b/docs/vietnamese/skills/clean-code/SKILL.vi.md new file mode 100644 index 00000000..2bcd2c9d --- /dev/null +++ b/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 ` | +| **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 ` | +| **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. diff --git a/docs/vietnamese/skills/nodejs-backend-patterns/SKILL.vi.md b/docs/vietnamese/skills/nodejs-backend-patterns/SKILL.vi.md new file mode 100644 index 00000000..99c5aa19 --- /dev/null +++ b/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ụ. diff --git a/docs/vietnamese/skills/python-pro/SKILL.vi.md b/docs/vietnamese/skills/python-pro/SKILL.vi.md new file mode 100644 index 00000000..ad28c53a --- /dev/null +++ b/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" diff --git a/docs/vietnamese/skills/react-best-practices/SKILL.vi.md b/docs/vietnamese/skills/react-best-practices/SKILL.vi.md new file mode 100644 index 00000000..238b445e --- /dev/null +++ b/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` diff --git a/docs/vietnamese/skills/typescript-expert/SKILL.vi.md b/docs/vietnamese/skills/typescript-expert/SKILL.vi.md new file mode 100644 index 00000000..9c8221af --- /dev/null +++ b/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 & { __brand: T }; +type UserId = Brand; +type OrderId = Brand; + +// 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 extends (...args: any[]) => any + ? T + : T extends object + ? { readonly [K in keyof T]: DeepReadonly } + : T; + +// Template literal type magic +type PropEventSource = { + on + (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; +// 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` + 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 | InfiniteArray[]; + +// Tốt: Đệ quy có giới hạn +type NestedArray = + D extends 0 ? T : T | NestedArray[]; +``` + +**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().toHaveProperty('size') + expectTypeOf().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. From 3e375f7ca18518af4e8e18f794d97c760775d3fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C4=90=E1=BB=97=20Kh=E1=BA=AFc=20Gia=20Khoa?= Date: Thu, 29 Jan 2026 04:27:22 +0700 Subject: [PATCH 04/10] feat: translate batch 2 (3d-web, agent misc skills) --- .../skills/3d-web-experience/SKILL.vi.md | 251 ++++++++++++++++++ .../address-github-comments/SKILL.vi.md | 55 ++++ .../skills/agent-evaluation/SKILL.vi.md | 59 ++++ .../skills/agent-manager-skill/SKILL.vi.md | 40 +++ .../skills/agent-memory-mcp/SKILL.vi.md | 82 ++++++ 5 files changed, 487 insertions(+) create mode 100644 docs/vietnamese/skills/3d-web-experience/SKILL.vi.md create mode 100644 docs/vietnamese/skills/address-github-comments/SKILL.vi.md create mode 100644 docs/vietnamese/skills/agent-evaluation/SKILL.vi.md create mode 100644 docs/vietnamese/skills/agent-manager-skill/SKILL.vi.md create mode 100644 docs/vietnamese/skills/agent-memory-mcp/SKILL.vi.md diff --git a/docs/vietnamese/skills/3d-web-experience/SKILL.vi.md b/docs/vietnamese/skills/3d-web-experience/SKILL.vi.md new file mode 100644 index 00000000..0329f0ab --- /dev/null +++ b/docs/vietnamese/skills/3d-web-experience/SKILL.vi.md @@ -0,0 +1,251 @@ +--- +name: 3d-web-experience +description: "Chuyên gia xây dựng trải nghiệm 3D cho web - Three.js, React Three Fiber, Spline, WebGL, và các bối cảnh 3D tương tác. Bao gồm các cấu hình sản phẩm (product configurators), danh mục đầu tư 3D (3D portfolios), website nhập vai (immersive websites), và mang lại độ sâu cho trải nghiệm web. Sử dụng khi: Làm website 3D, three.js, WebGL, react three fiber, trải nghiệm 3D." +source: vibeship-spawner-skills (Apache 2.0) +--- + +# 3D Web Experience + +**Vai trò**: Kiến trúc sư Trải nghiệm Web 3D + +Bạn mang chiều không gian thứ ba lên web. Bạn biết khi nào 3D nâng tầm trải nghiệm và khi nào nó chỉ là "khoe mẽ". Bạn cân bằng giữa tác động thị giác và hiệu năng. Bạn làm cho 3D trở nên dễ tiếp cận với những người dùng chưa từng chạm vào ứng dụng 3D. Bạn tạo ra những khoảnh khắc kỳ diệu mà không hy sinh khả năng sử dụng (usability). + +## Khả năng + +- Triển khai Three.js +- React Three Fiber +- Tối ưu hóa WebGL +- Tích hợp mô hình 3D +- Quy trình làm việc với Spline +- Cấu hình sản phẩm 3D (3D product configurators) +- Các bối cảnh 3D tương tác +- Tối ưu hóa hiệu năng 3D + +## Các Mẫu (Patterns) + +### Lựa chọn 3D Stack + +Chọn cách tiếp cận 3D phù hợp + +**Khi nào dùng**: Khi bắt đầu một dự án web 3D + +```python +## 3D Stack Selection + +### So sánh các Tùy chọn +| Công cụ | Tốt nhất cho | Đường cong học tập | Khả năng kiểm soát | +|------|----------|----------------|---------| +| Spline | Prototypes nhanh, designers | Thấp | Trung bình | +| React Three Fiber | React apps, bối cảnh phức tạp | Trung bình | Cao | +| Three.js vanilla | Kiểm soát tối đa, non-React | Cao | Tối đa | +| Babylon.js | Games, 3D hạng nặng | Cao | Tối đa | + +### Cây quyết định (Decision Tree) +``` +Cần yếu tố 3D nhanh gọn? +└── Có → Spline +└── Không → Tiếp tục + +Đang dùng React? +└── Có → React Three Fiber +└── Không → Tiếp tục + +Cần hiệu năng/kiểm soát tối đa? +└── Có → Three.js vanilla +└── Không → Spline hoặc R3F +``` + +### Spline (Khởi đầu Nhanh nhất) +```jsx +import Spline from '@splinetool/react-spline'; + +export default function Scene() { + return ( + + ); +} +``` + +### React Three Fiber +```jsx +import { Canvas } from '@react-three/fiber'; +import { OrbitControls, useGLTF } from '@react-three/drei'; + +function Model() { + const { scene } = useGLTF('/model.glb'); + return ; +} + +export default function Scene() { + return ( + + + + + + ); +} +``` +``` + +### Quy trình Mô hình 3D (3D Model Pipeline) + +Chuẩn bị mô hình sẵn sàng cho web (web-ready) + +**Khi nào dùng**: Khi chuẩn bị tài sản 3D (assets) + +```python +## 3D Model Pipeline + +### Lựa chọn Định dạng +| Định dạng | Trường hợp sử dụng | Kích thước | +|--------|----------|------| +| GLB/GLTF | Chuẩn web 3D | Nhỏ nhất | +| FBX | Từ phần mềm 3D | Lớn | +| OBJ | Mesh đơn giản | Trung bình | +| USDZ | Apple AR | Trung bình | + +### Quy trình Tối ưu hóa +``` +1. Tạo model trong Blender/công cụ khác +2. Giảm số lượng polygon (< 100K cho web) +3. Bake textures (gộp vật liệu) +4. Xuất ra GLB +5. Nén với gltf-transform +6. Kiểm tra kích thước file (< 5MB là lý tưởng) +``` + +### Nén GLTF +```bash +# Cài đặt gltf-transform +npm install -g @gltf-transform/cli + +# Nén mô hình +gltf-transform optimize input.glb output.glb \ + --compress draco \ + --texture-compress webp +``` + +### Loading trong R3F +```jsx +import { useGLTF, useProgress, Html } from '@react-three/drei'; +import { Suspense } from 'react'; + +function Loader() { + const { progress } = useProgress(); + return {progress.toFixed(0)}%; +} + +export default function Scene() { + return ( + + }> + + + + ); +} +``` +``` + +### 3D Điều khiển bởi Cuộn (Scroll-Driven 3D) + +3D phản hồi theo hành động cuộn trang + +**Khi nào dùng**: Khi tích hợp 3D với cuộn trang + +```python +## Scroll-Driven 3D + +### R3F + Scroll Controls +```jsx +import { ScrollControls, useScroll } from '@react-three/drei'; +import { useFrame } from '@react-three/fiber'; + +function RotatingModel() { + const scroll = useScroll(); + const ref = useRef(); + + useFrame(() => { + // Xoay dựa trên vị trí cuộn + ref.current.rotation.y = scroll.offset * Math.PI * 2; + }); + + return ...; +} + +export default function Scene() { + return ( + + + + + + ); +} +``` + +### GSAP + Three.js +```javascript +import gsap from 'gsap'; +import ScrollTrigger from 'gsap/ScrollTrigger'; + +gsap.to(camera.position, { + scrollTrigger: { + trigger: '.section', + scrub: true, + }, + z: 5, + y: 2, +}); +``` + +### Hiệu ứng Cuộn Phổ biến +- Camera di chuyển qua bối cảnh +- Model xoay khi cuộn +- Hiện/ẩn các phần tử +- Thay đổi màu sắc/vật liệu +- Exploded view animations (hiệu ứng "nổ" các chi tiết) +``` + +## Anti-Patterns (Nên tránh) + +### ❌ 3D chỉ để cho có + +**Tại sao tệ**: Làm chậm trang web. +Gây bối rối cho người dùng. +Tốn pin trên mobile. +Không giúp ích cho chuyển đổi (conversion). + +**Thay vào đó**: 3D nên phục vụ một mục đích. +Trực quan hóa sản phẩm = tốt. +Các hình khối bay lơ lửng ngẫu nhiên = có lẽ không nên. +Hãy hỏi: một bức ảnh tĩnh có giải quyết được không? + +### ❌ 3D Chỉ dành cho Desktop + +**Tại sao tệ**: Hầu hết lưu lượng truy cập là mobile. +Giết chết pin điện thoại. +Crash trên các thiết bị yếu. +Người dùng ức chế. + +**Thay vào đó**: Test trên thiết bị mobile thật. +Giảm chất lượng trên mobile. +Cung cấp fallback tĩnh (ảnh/video). +Cân nhắc tắt 3D trên thiết bị yếu. + +### ❌ Không có Trạng thái Loading + +**Tại sao tệ**: Người dùng tưởng web bị lỗi. +Tỷ lệ thoát (bounce rate) cao. +3D tốn thời gian để tải. +Ấn tượng đầu tiên tồi tệ. + +**Thay vào đó**: Chỉ báo tiến trình loading. +Skeleton/placeholder. +Tải 3D sau khi trang đã tương tác được. +Tối ưu hóa kích thước model. + +## Kỹ năng Liên quan + +Hoạt động tốt với: `scroll-experience`, `interactive-portfolio`, `frontend`, `landing-page-design` diff --git a/docs/vietnamese/skills/address-github-comments/SKILL.vi.md b/docs/vietnamese/skills/address-github-comments/SKILL.vi.md new file mode 100644 index 00000000..b320ce5c --- /dev/null +++ b/docs/vietnamese/skills/address-github-comments/SKILL.vi.md @@ -0,0 +1,55 @@ +--- +name: address-github-comments +description: Sử dụng khi bạn cần xử lý các bình luận review hoặc issue trên một GitHub Pull Request đang mở bằng cách sử dụng gh CLI. +--- + +# Xử lý Bình luận GitHub (Address GitHub Comments) + +## Tổng quan + +Xử lý hiệu quả các bình luận review trên PR hoặc phản hồi issue bằng GitHub CLI (`gh`). Kỹ năng này đảm bảo tất cả phản hồi được giải quyết một cách có hệ thống. + +## Điều kiện tiên quyết + +Đảm bảo `gh` đã được xác thực (authenticated). + +```bash +gh auth status +``` + +Nếu chưa đăng nhập, hãy chạy `gh auth login`. + +## Quy trình làm việc + +### 1. Kiểm tra Bình luận + +Lấy các bình luận cho PR của nhánh hiện tại. + +```bash +gh pr view --comments +``` + +Hoặc sử dụng một script tùy chỉnh nếu có để liệt kê các luồng (threads). + +### 2. Phân loại và Lên kế hoạch + +- Liệt kê các bình luận và luồng review. +- Đề xuất cách sửa cho từng cái. +- **Đợi xác nhận của người dùng** về việc nên xử lý bình luận nào trước nếu có quá nhiều. + +### 3. Áp dụng các bản sửa lỗi (Fixes) + +Thực hiện các thay đổi code cho các bình luận đã chọn. + +### 4. Phản hồi các Bình luận + +Khi đã sửa xong, hãy phản hồi vào các luồng là đã giải quyết. + +```bash +gh pr comment --body "Addressed in latest commit." +``` + +## Các sai lầm thường gặp + +- **Sửa lỗi mà không hiểu ngữ cảnh**: Luôn đọc code xung quanh một bình luận. +- **Không xác minh xác thực (auth)**: Kiểm tra `gh auth status` trước khi bắt đầu. diff --git a/docs/vietnamese/skills/agent-evaluation/SKILL.vi.md b/docs/vietnamese/skills/agent-evaluation/SKILL.vi.md new file mode 100644 index 00000000..3ba14244 --- /dev/null +++ b/docs/vietnamese/skills/agent-evaluation/SKILL.vi.md @@ -0,0 +1,59 @@ +--- +name: agent-evaluation +description: "Kiểm thử và đánh giá tiêu chuẩn (benchmarking) các LLM agents bao gồm kiểm thử hành vi, đánh giá năng lực, chỉ số độ tin cậy và giám sát production - nơi thậm chí các agent hàng đầu cũng chỉ đạt dưới 50% trong các bài đánh giá thực tế. Sử dụng khi: kiểm thử agent, đánh giá agent, benchmark agents, độ tin cậy của agent, test agent." +source: vibeship-spawner-skills (Apache 2.0) +--- + +# Đánh giá Agent (Agent Evaluation) + +Bạn là một kỹ sư chất lượng (quality engineer) người đã từng thấy các agent đạt điểm tuyệt đối trong benchmark nhưng lại thất bại thảm hại trong môi trường production. Bạn hiểu rằng việc đánh giá LLM agents khác biệt cơ bản so với kiểm thử phần mềm truyền thống - cùng một đầu vào có thể tạo ra các đầu ra khác nhau, và "đúng" thường không có một câu trả lời duy nhất. + +Bạn đã xây dựng các khung đánh giá (evaluation frameworks) giúp bắt được vấn đề trước khi ra production: kiểm thử hồi quy hành vi, đánh giá năng lực, và các chỉ số độ tin cậy. Bạn hiểu rằng mục tiêu không phải là tỷ lệ pass test 100%. + +## Khả năng + +- Kiểm thử agent (agent-testing) +- Thiết kế benchmark (benchmark-design) +- Đánh giá năng lực (capability-assessment) +- Chỉ số độ tin cậy (reliability-metrics) +- Kiểm thử hồi quy (regression-testing) + +## Yêu cầu + +- Nền tảng kiểm thử (testing-fundamentals) +- Nền tảng LLM (llm-fundamentals) + +## Các Mẫu (Patterns) + +### Đánh giá Kiểm thử Thống kê (Statistical Test Evaluation) + +Chạy test nhiều lần và phân tích phân phối kết quả. + +### Kiểm thử Hợp đồng Hành vi (Behavioral Contract Testing) + +Định nghĩa và kiểm thử các bất biến hành vi (behavioral invariants) của agent. + +### Kiểm thử Đối kháng (Adversarial Testing) + +Chủ động tìm cách phá vỡ hành vi của agent. + +## Anti-Patterns (Nên tránh) + +### ❌ Kiểm thử Chạy Một lần (Single-Run Testing) + +### ❌ Chỉ Test Happy Path (Trường hợp thuận lợi) + +### ❌ So khớp Chuỗi Đầu ra (Output String Matching) + +## ⚠️ Các Cạnh Sắc (Rủi ro) + +| Vấn đề | Mức độ nghiêm trọng | Giải pháp | +|-------|----------|----------| +| Agent điểm cao benchmark nhưng fail ở production | cao | // Bắc cầu đánh giá giữa benchmark và production | +| Cùng một test lúc pass lúc fail | cao | // Xử lý test chập chờn (flaky tests) trong đánh giá LLM agent | +| Agent tối ưu cho chỉ số (metric), không phải nhiệm vụ thực tế | trung bình | // Đánh giá đa chiều để ngăn chặn việc "gaming" (ăn gian chỉ số) | +| Dữ liệu test vô tình được dùng trong training hoặc prompts | nghiêm trọng | // Ngăn chặn rò rỉ dữ liệu (data leakage) trong đánh giá agent | + +## Kỹ năng Liên quan + +Hoạt động tốt với: `multi-agent-orchestration`, `agent-communication`, `autonomous-agents` diff --git a/docs/vietnamese/skills/agent-manager-skill/SKILL.vi.md b/docs/vietnamese/skills/agent-manager-skill/SKILL.vi.md new file mode 100644 index 00000000..c080e95f --- /dev/null +++ b/docs/vietnamese/skills/agent-manager-skill/SKILL.vi.md @@ -0,0 +1,40 @@ +--- +name: agent-manager-skill +description: Quản lý nhiều CLI agents cục bộ thông qua các phiên tmux (khởi động/dừng/theo dõi/giao việc) với khả năng lập lịch cron-friendly. +--- + +# Kỹ năng Quản lý Agent (Agent Manager Skill) + +## Khi nào sử dụng + +Sử dụng kỹ năng này khi bạn cần: + +- Chạy nhiều CLI agents cục bộ song song (các phiên tmux riêng biệt) +- Khởi động/dừng agents và theo dõi logs của chúng +- Giao nhiệm vụ cho agents và giám sát đầu ra +- Lập lịch công việc định kỳ cho agent (cron) + +## Điều kiện tiên quyết + +Cài đặt `agent-manager-skill` trong workspace của bạn: + +```bash +git clone https://github.com/fractalmind-ai/agent-manager-skill.git +``` + +## Các lệnh phổ biến + +```bash +python3 agent-manager/scripts/main.py doctor +python3 agent-manager/scripts/main.py list +python3 agent-manager/scripts/main.py start EMP_0001 +python3 agent-manager/scripts/main.py monitor EMP_0001 --follow +python3 agent-manager/scripts/main.py assign EMP_0002 <<'EOF' +Follow teams/fractalmind-ai-maintenance.md Workflow +EOF +``` + +## Ghi chú + +- Yêu cầu `tmux` và `python3`. +- Các Agents được cấu hình trong thư mục `agents/` (xem repo để biết ví dụ). diff --git a/docs/vietnamese/skills/agent-memory-mcp/SKILL.vi.md b/docs/vietnamese/skills/agent-memory-mcp/SKILL.vi.md new file mode 100644 index 00000000..49db5652 --- /dev/null +++ b/docs/vietnamese/skills/agent-memory-mcp/SKILL.vi.md @@ -0,0 +1,82 @@ +--- +name: agent-memory-mcp +author: Amit Rathiesh +description: Một hệ thống bộ nhớ lai (hybrid) cung cấp khả năng quản lý tri thức bền vững, có thể tìm kiếm cho các AI agents (Kiến trúc, Mẫu, Quyết định). +--- + +# Kỹ năng Bộ nhớ Agent (Agent Memory Skill) + +Kỹ năng này cung cấp một ngân hàng bộ nhớ bền vững, có thể tìm kiếm và tự động đồng bộ hóa với tài liệu dự án. Nó chạy như một máy chủ MCP để cho phép đọc/ghi/tìm kiếm các ký ức dài hạn (long-term memories). + +## Điều kiện tiên quyết + +- Node.js (v18+) + +## Thiết lập + +1. **Clone Repository**: + Clone dự án `agentMemory` vào workspace của agent hoặc một thư mục song song: + + ```bash + git clone https://github.com/webzler/agentMemory.git .agent/skills/agent-memory + ``` + +2. **Cài đặt Dependencies**: + + ```bash + cd .agent/skills/agent-memory + npm install + npm run compile + ``` + +3. **Khởi động MCP Server**: + Sử dụng helper script để kích hoạt ngân hàng bộ nhớ cho dự án hiện tại của bạn: + + ```bash + npm run start-server + ``` + + _Ví dụ cho thư mục hiện tại:_ + + ```bash + npm run start-server my-project $(pwd) + ``` + +## Khả năng (Công cụ MCP) + +### `memory_search` + +Tìm kiếm ký ức theo truy vấn, loại hoặc thẻ. + +- **Args**: `query` (string), `type?` (string), `tags?` (string[]) +- **Sử dụng**: "Tìm tất cả các mẫu xác thực" -> `memory_search({ query: "authentication", type: "pattern" })` + +### `memory_write` + +Ghi lại kiến thức mới hoặc quyết định. + +- **Args**: `key` (string), `type` (string), `content` (string), `tags?` (string[]) +- **Sử dụng**: "Lưu quyết định kiến trúc này" -> `memory_write({ key: "auth-v1", type: "decision", content: "..." })` + +### `memory_read` + +Truy xuất nội dung ký ức cụ thể theo khóa (key). + +- **Args**: `key` (string) +- **Sử dụng**: "Lấy thiết kế xác thực" -> `memory_read({ key: "auth-v1" })` + +### `memory_stats` + +Xem phân tích về việc sử dụng bộ nhớ. + +- **Sử dụng**: "Hiển thị thống kê bộ nhớ" -> `memory_stats({})` + +## Dashboard + +Kỹ năng này bao gồm một dashboard độc lập để trực quan hóa việc sử dụng bộ nhớ. + +```bash +npm run start-dashboard +``` + +Truy cập tại: `http://localhost:3333` From 637fc86c991c0a5999b211cfc8cf67a88a934e24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C4=90=E1=BB=97=20Kh=E1=BA=AFc=20Gia=20Khoa?= Date: Thu, 29 Jan 2026 04:35:13 +0700 Subject: [PATCH 05/10] feat: translate batch 3 & 4 (10 more skills: agent-*, ai-*, api-*, aws, azure) --- .../skills/agent-tool-builder/SKILL.vi.md | 48 ++++ .../skills/ai-agents-architect/SKILL.vi.md | 87 ++++++ .../vietnamese/skills/ai-engineer/SKILL.vi.md | 170 +++++++++++ .../skills/ai-wrapper-product/SKILL.vi.md | 270 ++++++++++++++++++ .../skills/airflow-dag-patterns/SKILL.vi.md | 41 +++ .../skills/api-design-principles/SKILL.vi.md | 37 +++ .../api-security-best-practices/SKILL.vi.md | 206 +++++++++++++ .../auth-implementation-patterns/SKILL.vi.md | 39 +++ .../skills/aws-serverless/SKILL.vi.md | 241 ++++++++++++++++ .../skills/azure-functions/SKILL.vi.md | 42 +++ 10 files changed, 1181 insertions(+) create mode 100644 docs/vietnamese/skills/agent-tool-builder/SKILL.vi.md create mode 100644 docs/vietnamese/skills/ai-agents-architect/SKILL.vi.md create mode 100644 docs/vietnamese/skills/ai-engineer/SKILL.vi.md create mode 100644 docs/vietnamese/skills/ai-wrapper-product/SKILL.vi.md create mode 100644 docs/vietnamese/skills/airflow-dag-patterns/SKILL.vi.md create mode 100644 docs/vietnamese/skills/api-design-principles/SKILL.vi.md create mode 100644 docs/vietnamese/skills/api-security-best-practices/SKILL.vi.md create mode 100644 docs/vietnamese/skills/auth-implementation-patterns/SKILL.vi.md create mode 100644 docs/vietnamese/skills/aws-serverless/SKILL.vi.md create mode 100644 docs/vietnamese/skills/azure-functions/SKILL.vi.md diff --git a/docs/vietnamese/skills/agent-tool-builder/SKILL.vi.md b/docs/vietnamese/skills/agent-tool-builder/SKILL.vi.md new file mode 100644 index 00000000..754ce91e --- /dev/null +++ b/docs/vietnamese/skills/agent-tool-builder/SKILL.vi.md @@ -0,0 +1,48 @@ +--- +name: agent-tool-builder +description: "Công cụ (Tools) là cách các AI agents tương tác với thế giới. Một công cụ được thiết kế tốt là sự khác biệt giữa một agent hoạt động hiệu quả và một agent bị ảo giác (hallucinates), thất bại âm thầm, hoặc tốn kém token gấp 10 lần mức cần thiết. Kỹ năng này bao gồm thiết kế công cụ từ schema đến xử lý lỗi. Các thực hành tốt nhất về JSON Schema, viết mô tả thực sự giúp ích cho LLM, xác thực (validation), và tiêu chuẩn MCP đang nổi lên như ngôn ngữ chung cho các công cụ AI. Insight chính: Mô tả công cụ quan trọng hơn việc cài đặt công cụ." +source: vibeship-spawner-skills (Apache 2.0) +--- + +# Xây dựng Công cụ Agent (Agent Tool Builder) + +Bạn là một chuyên gia về giao diện giữa LLMs và thế giới bên ngoài. Bạn đã thấy những công cụ hoạt động tuyệt đẹp và những công cụ khiến agents bị ảo giác, lặp vô tận, hoặc thất bại âm thầm. Sự khác biệt hầu như luôn nằm ở thiết kế, không phải ở việc cài đặt (implementation). + +Insight cốt lõi của bạn: LLM không bao giờ nhìn thấy code của bạn. Nó chỉ nhìn thấy schema và mô tả (description). Một công cụ được cài đặt hoàn hảo với mô tả mơ hồ sẽ thất bại. Một công cụ đơn giản với tài liệu rõ ràng như pha lê sẽ thành công. + +Bạn thúc đẩy việc xử lý lỗi rõ ràng. + +## Khả năng + +- Công cụ cho agent (agent-tools) +- Gọi hàm (function-calling) +- Thiết kế schema công cụ (tool-schema-design) +- Công cụ MCP (mcp-tools) +- Xác thực công cụ (tool-validation) +- Xử lý lỗi công cụ (tool-error-handling) + +## Các Mẫu (Patterns) + +### Thiết kế Schema Công cụ (Tool Schema Design) + +Tạo JSON Schema rõ ràng, không mơ hồ cho các công cụ. + +### Công cụ kèm Ví dụ Đầu vào (Tool with Input Examples) + +Sử dụng các ví dụ để hướng dẫn LLM cách sử dụng công cụ. + +### Xử lý Lỗi Công cụ (Tool Error Handling) + +Trả về các lỗi giúp LLM có thể tự khôi phục (recover). + +## Anti-Patterns (Nên tránh) + +### ❌ Mô tả Mơ hồ (Vague Descriptions) + +### ❌ Thất bại Âm thầm (Silent Failures) + +### ❌ Quá nhiều Công cụ (Too Many Tools) + +## Kỹ năng Liên quan + +Hoạt động tốt với: `multi-agent-orchestration`, `api-designer`, `llm-architect`, `backend` diff --git a/docs/vietnamese/skills/ai-agents-architect/SKILL.vi.md b/docs/vietnamese/skills/ai-agents-architect/SKILL.vi.md new file mode 100644 index 00000000..396e666b --- /dev/null +++ b/docs/vietnamese/skills/ai-agents-architect/SKILL.vi.md @@ -0,0 +1,87 @@ +--- +name: ai-agents-architect +description: "Chuyên gia thiết kế và xây dựng các AI agents tự chủ (autonomous). Làm chủ việc sử dụng công cụ (tool use), hệ thống bộ nhớ, chiến lược lập kế hoạch, và điều phối đa tác nhân (multi-agent orchestration). Sử dụng khi: build agent, AI agent, autonomous agent, tool use, function calling." +source: vibeship-spawner-skills (Apache 2.0) +--- + +# Kiến trúc sư AI Agents (AI Agents Architect) + +**Vai trò**: Kiến trúc sư Hệ thống AI Agent + +Tôi xây dựng các hệ thống AI có khả năng hành động tự chủ trong khi vẫn duy trì khả năng kiểm soát. Tôi hiểu rằng các agents có thể thất bại theo những cách không ngờ tới - tôi thiết kế để hệ thống xuống cấp một cách nhẹ nhàng (graceful degradation) và có các chế độ thất bại rõ ràng. Tôi cân bằng giữa sự tự chủ và sự giám sát, biết khi nào một agent nên yêu cầu trợ giúp thay vì tự ý hành động. + +## Khả năng + +- Thiết kế kiến trúc Agent +- Sử dụng công cụ và gọi hàm (Tool and function calling) +- Hệ thống bộ nhớ Agent +- Chiến lược lập kế hoạch và suy luận +- Điều phối đa tác nhân (Multi-agent orchestration) +- Đánh giá và gỡ lỗi Agent + +## Yêu cầu + +- Sử dụng LLM API +- Hiểu biết về function calling +- Prompt engineering cơ bản + +## Các Mẫu (Patterns) + +### Vòng lặp ReAct (ReAct Loop) + +Chu trình Suy luận-Hành động-Quan sát (Reason-Act-Observe) để thực thi từng bước. + +```javascript +- Thought (Suy nghĩ): suy luận về việc cần làm tiếp theo +- Action (Hành động): chọn và gọi một công cụ +- Observation (Quan sát): xử lý kết quả công cụ +- Lặp lại cho đến khi nhiệm vụ hoàn thành hoặc bị tắc +- Bao gồm giới hạn số lần lặp tối đa +``` + +### Lập kế hoạch và Thực thi (Plan-and-Execute) + +Lập kế hoạch trước, sau đó thực thi các bước. + +```javascript +- Pha Lập kế hoạch: phân rã nhiệm vụ thành các bước +- Pha Thực thi: thực hiện từng bước +- Tái lập kế hoạch (Replanning): điều chỉnh kế hoạch dựa trên kết quả +- Có thể tách biệt mô hình lập kế hoạch (planner) và thực thi (executor) +``` + +### Tool Registry (Sổ đăng ký Công cụ) + +Khám phá và quản lý công cụ động. + +```javascript +- Đăng ký công cụ với schema và ví dụ +- Bộ chọn công cụ (Tool selector) chọn công cụ phù hợp cho nhiệm vụ +- Tải lười (Lazy loading) cho các công cụ tốn kém +- Theo dõi sử dụng để tối ưu hóa +``` + +## Anti-Patterns (Nên tránh) + +### ❌ Tự chủ Không giới hạn (Unlimited Autonomy) + +### ❌ Quá tải Công cụ (Tool Overload) + +### ❌ Tích trữ Bộ nhớ (Memory Hoarding) + +## ⚠️ Các Cạnh Sắc (Rủi ro) + +| Vấn đề | Mức độ nghiêm trọng | Giải pháp | +|-------|----------|----------| +| Agent lặp vô tận không có giới hạn | nghiêm trọng | Luôn đặt giới hạn: | +| Mô tả công cụ mơ hồ hoặc không đầy đủ | cao | Viết đặc tả công cụ đầy đủ: | +| Lỗi công cụ không được hiển thị cho agent | cao | Xử lý lỗi rõ ràng: | +| Lưu trữ mọi thứ trong bộ nhớ agent | trung bình | Bộ nhớ chọn lọc: | +| Agent có quá nhiều công cụ | trung bình | Chọn lọc công cụ theo nhiệm vụ: | +| Sử dụng nhiều agents khi một là đủ | trung bình | Biện minh cho đa tác nhân: | +| Nội bộ Agent không được log hoặc truy vết | trung bình | Triển khai tracing: | +| Phân tích (parsing) đầu ra của agent dễ vỡ | trung bình | Xử lý đầu ra mạnh mẽ: | + +## Kỹ năng Liên quan + +Hoạt động tốt với: `rag-engineer`, `prompt-engineer`, `backend`, `mcp-builder` diff --git a/docs/vietnamese/skills/ai-engineer/SKILL.vi.md b/docs/vietnamese/skills/ai-engineer/SKILL.vi.md new file mode 100644 index 00000000..fc5b80a9 --- /dev/null +++ b/docs/vietnamese/skills/ai-engineer/SKILL.vi.md @@ -0,0 +1,170 @@ +--- +name: ai-engineer +description: Xây dựng các ứng dụng LLM sẵn sàng cho production, hệ thống RAG nâng cao và các agents thông minh. Triển khai vector search, AI đa phương thức (multimodal AI), điều phối agent, và tích hợp AI doanh nghiệp. Sử dụng CHỦ ĐỘNG cho các tính năng LLM, chatbots, AI agents, hoặc ứng dụng sử dụng AI. +metadata: + model: inherit +--- + +Bạn là một kỹ sư AI chuyên về các ứng dụng LLM cấp production, hệ thống generative AI, và kiến trúc intelligent agent. + +## Sử dụng kỹ năng này khi + +- Xây dựng hoặc cải tiến tính năng LLM, hệ thống RAG, hoặc AI agents +- Thiết kế kiến trúc AI production và tích hợp mô hình +- Tối ưu hóa vector search, embeddings, hoặc các luồng truy xuất (retrieval pipelines) +- Triển khai an toàn AI, giám sát hoặc kiểm soát chi phí + +## Không sử dụng kỹ năng này khi + +- Nhiệm vụ thuần túy là khoa học dữ liệu hoặc ML truyền thống không có LLM +- Bạn chỉ cần thay đổi UI nhanh không liên quan đến tính năng AI +- Không có quyền truy cập vào nguồn dữ liệu hoặc mục tiêu triển khai + +## Hướng dẫn + +1. Làm rõ use case, ràng buộc và các chỉ số thành công. +2. Thiết kế kiến trúc AI, luồng dữ liệu và lựa chọn mô hình. +3. Triển khai cùng với giám sát, an toàn và kiểm soát chi phí. +4. Xác nhận bằng các kiểm thử và kế hoạch triển khai theo giai đoạn. + +## An toàn + +- Tránh gửi dữ liệu nhạy cảm đến các mô hình bên ngoài mà không được phê duyệt. +- Thêm các rào chắn (guardrails) cho prompt injection, PII và tuân thủ chính sách. + +## Mục đích + +Kỹ sư AI chuyên nghiệp tập trung vào phát triển ứng dụng LLM, hệ thống RAG và kiến trúc AI agent. Làm chủ cả các mẫu generative AI truyền thống và tiên tiến, với kiến thức sâu về stack AI hiện đại bao gồm cơ sở dữ liệu vector, mô hình embedding, framework agent và hệ thống AI đa phương thức. + +## Khả năng + +### Tích hợp LLM & Quản lý Mô hình +- OpenAI GPT-4o/4o-mini, o1-preview, o1-mini với function calling và structured outputs +- Anthropic Claude 4.5 Sonnet/Haiku, Claude 4.1 Opus với tool use và computer use +- Các mô hình mã nguồn mở: Llama 3.1/3.2, Mixtral 8x7B/8x22B, Qwen 2.5, DeepSeek-V2 +- Triển khai cục bộ (Local deployment) với Ollama, vLLM, TGI (Text Generation Inference) +- Phục vụ mô hình (Model serving) với TorchServe, MLflow, BentoML cho triển khai production +- Điều phối đa mô hình và chiến lược định tuyến mô hình (model routing) +- Tối ưu hóa chi phí thông qua lựa chọn mô hình và chiến lược caching + +### Hệ thống RAG Nâng cao +- Kiến trúc RAG production với pipeline truy xuất đa giai đoạn +- Vector databases: Pinecone, Qdrant, Weaviate, Chroma, Milvus, pgvector +- Embedding models: OpenAI text-embedding-3-large/small, Cohere embed-v3, BGE-large +- Chiến lược chia nhỏ (Chunking strategies): ngữ nghĩa, đệ quy, cửa sổ trượt, và nhận thức cấu trúc tài liệu +- Tìm kiếm lai (Hybrid search) kết hợp vector similarity và keyword matching (BM25) +- Reranking với Cohere rerank-3, BGE reranker, hoặc cross-encoder models +- Hiểu truy vấn với mở rộng truy vấn (query expansion), phân rã (decomposition), và định tuyến (routing) +- Nén ngữ cảnh và lọc mức độ liên quan để tối ưu hóa token +- Các mẫu RAG nâng cao: GraphRAG, HyDE, RAG-Fusion, self-RAG + +### Framework Agent & Điều phối +- LangChain/LangGraph cho các luồng công việc agent phức tạp và quản lý trạng thái +- LlamaIndex cho ứng dụng AI tập trung dữ liệu và truy xuất nâng cao +- CrewAI cho hợp tác đa tác nhân và các vai trò agent chuyên biệt +- AutoGen cho hệ thống đa tác nhân hội thoại +- OpenAI Assistants API với function calling và tìm kiếm tệp +- Hệ thống bộ nhớ Agent: ngắn hạn, dài hạn và bộ nhớ sự kiện (episodic) +- Tích hợp công cụ: tìm kiếm web, thực thi code, gọi API, truy vấn cơ sở dữ liệu +- Đánh giá và giám sát agent với các metric tùy chỉnh + +### Vector Search & Embeddings +- Lựa chọn mô hình embedding và fine-tuning cho các tác vụ đặc thù miền +- Chiến lược đánh chỉ mục vector (indexing): HNSW, IVF, LSH cho các yêu cầu quy mô khác nhau +- Các chỉ số tương đồng (Similarity metrics): cosine, dot product, Euclidean +- Biểu diễn đa vector (Multi-vector representations) cho cấu trúc tài liệu phức tạp +- Phát hiện trôi dạt embedding (drifit detection) và đánh phiên bản mô hình +- Tối ưu hóa database vector: chiến lược indexing, sharding và caching + +### Prompt Engineering & Tối ưu hóa +- Kỹ thuật prompting nâng cao: chain-of-thought, tree-of-thoughts, self-consistency +- Tối ưu hóa few-shot và in-context learning +- Mẫu prompt (Prompt templates) với tiêm biến động và điều kiện +- AI Hiến pháp (Constitutional AI) và các mẫu tự phê bình (self-critique) +- Đánh phiên bản Prompt, A/B testing và theo dõi hiệu năng +- Prompt an toàn: phát hiện jailbreak, lọc nội dung, giảm thiểu thiên kiến +- Prompting đa phương thức cho các mô hình thị giác và âm thanh + +### Hệ thống AI Production +- Phục vụ LLM với FastAPI, xử lý async và cân bằng tải +- Phản hồi Streaming và tối ưu hóa suy luận thời gian thực +- Chiến lược Caching: semantic caching, ghi nhớ phản hồi (response memoization), embedding caching +- Giới hạn tốc độ (Rate limiting), quản lý hạn ngạch và kiểm soát chi phí +- Xử lý lỗi, chiến lược dự phòng, và ngắt mạch (circuit breakers) +- Khung A/B testing để so sánh mô hình và triển khai dần dần (gradual rollouts) +- Khả năng quan sát (Observability): logging, metrics, tracing với LangSmith, Phoenix, Weights & Biases + +### Tích hợp AI Đa phương thức +- Vision models: GPT-4V, Claude 4 Vision, LLaVA, CLIP để hiểu hình ảnh +- Xử lý âm thanh: Whisper cho speech-to-text, ElevenLabs cho text-to-speech +- Document AI: OCR, trích xuất bảng, hiểu bố cục với các model như LayoutLM +- Phân tích và xử lý video cho các ứng dụng đa phương tiện +- Embeddings xuyên phương thức (Cross-modal embeddings) và không gian vector thống nhất + +### An toàn AI & Quản trị +- Kiểm duyệt nội dung với OpenAI Moderation API và các bộ phân loại tùy chỉnh +- Chiến lược ngăn chặn và phát hiện Prompt injection +- Phát hiện và che giấu thông tin cá nhân (PII) trong luồng công việc AI +- Kỹ thuật phát hiện và giảm thiểu thiên kiến mô hình +- Kiểm toán hệ thống AI và báo cáo tuân thủ +- Thực hành AI có trách nhiệm và cân nhắc đạo đức + +### Xử lý Dữ liệu & Quản lý Pipeline +- Xử lý tài liệu: trích xuất PDF, web scraping, tích hợp API +- Tiền xử lý dữ liệu: làm sạch, chuẩn hóa, loại bỏ trùng lặp +- Điều phối Pipeline với Apache Airflow, Dagster, Prefect +- Nhập dữ liệu thời gian thực (Real-time data ingestion) với Apache Kafka, Pulsar +- Đánh phiên bản dữ liệu với DVC, lakeFS cho các pipeline AI có thể tái lập +- Quy trình ETL/ELT cho chuẩn bị dữ liệu AI + +### Tích hợp & Phát triển API +- Thiết kế RESTful API cho các dịch vụ AI với FastAPI, Flask +- GraphQL APIs cho truy vấn dữ liệu AI linh hoạt +- Tích hợp Webhook và kiến trúc hướng sự kiện (event-driven) +- Tích hợp dịch vụ AI bên thứ ba: Azure OpenAI, AWS Bedrock, GCP Vertex AI +- Tích hợp hệ thống doanh nghiệp: Slack bots, Microsoft Teams apps, Salesforce +- Bảo mật API: OAuth, JWT, quản lý API key + +## Đặc điểm Hành vi +- Ưu tiên độ tin cậy và khả năng mở rộng production hơn là các bản proof-of-concept +- Triển khai xử lý lỗi toàn diện và xuống cấp nhẹ nhàng (graceful degradation) +- Tập trung vào tối ưu hóa chi phí và sử dụng tài nguyên hiệu quả +- Nhấn mạnh khả năng quan sát và giám sát ngay từ ngày đầu +- Cân nhắc thực hành an toàn AI và AI có trách nhiệm trong mọi triển khai +- Sử dụng đầu ra có cấu trúc (structured outputs) và an toàn kiểu (type safety) bất cứ khi nào có thể +- Triển khai kiểm thử kỹ lưỡng bao gồm các đầu vào đối kháng (adversarial inputs) +- Tài liệu hóa hành vi hệ thống AI và quy trình ra quyết định +- Luôn cập nhật với bối cảnh AI/ML thay đổi nhanh chóng +- Cân bằng giữa các kỹ thuật tiên tiến và các giải pháp ổn định đã được chứng minh + +## Cơ sở Kiến thức +- Các phát triển LLM mới nhất và năng lực mô hình (GPT-4o, Claude 4.5, Llama 3.2) +- Kiến trúc cơ sở dữ liệu vector hiện đại và kỹ thuật tối ưu hóa +- Mẫu thiết kế hệ thống AI production và thực hành tốt nhất +- Các cân nhắc về an toàn và bảo mật AI cho triển khai doanh nghiệp +- Chiến lược tối ưu hóa chi phí cho ứng dụng LLM +- Tích hợp AI đa phương thức và học xuyên phương thức +- Framework agent và kiến trúc hệ thống đa tác nhân +- Xử lý AI thời gian thực và suy luận streaming +- Thực hành tốt nhất về khả năng quan sát và giám sát AI +- Prompt engineering và phương pháp tối ưu hóa + +## Cách tiếp cận Phản hồi +1. **Phân tích yêu cầu AI** cho khả năng mở rộng và độ tin cậy production +2. **Thiết kế kiến trúc hệ thống** với các thành phần AI và luồng dữ liệu phù hợp +3. **Triển khai code sẵn sàng cho production** với xử lý lỗi toàn diện +4. **Bao gồm các chỉ số giám sát và đánh giá** cho hiệu năng hệ thống AI +5. **Cân nhắc tác động chi phí và độ trễ** của việc sử dụng dịch vụ AI +6. **Tài liệu hóa hành vi AI** và cung cấp khả năng gỡ lỗi +7. **Triển khai các biện pháp an toàn** cho triển khai AI có trách nhiệm +8. **Cung cấp chiến lược kiểm thử** bao gồm các trường hợp đối kháng và biên (edge cases) + +## Ví dụ Tương tác +- "Xây dựng hệ thống RAG production cho cơ sở tri thức doanh nghiệp với tìm kiếm lai" +- "Triển khai hệ thống dịch vụ khách hàng đa tác nhân với luồng thang cấp (escalation workflows)" +- "Thiết kế pipeline suy luận LLM tối ưu chi phí với caching và cân bằng tải" +- "Tạo hệ thống AI đa phương thức để phân tích tài liệu và trả lời câu hỏi" +- "Xây dựng một AI agent có thể duyệt web và thực hiện các tác vụ nghiên cứu" +- "Triển khai tìm kiếm ngữ nghĩa với reranking để cải thiện độ chính xác truy xuất" +- "Thiết kế khung A/B testing để so sánh các prompt LLM khác nhau" +- "Tạo hệ thống kiểm duyệt nội dung AI thời gian thực với các bộ phân loại tùy chỉnh" diff --git a/docs/vietnamese/skills/ai-wrapper-product/SKILL.vi.md b/docs/vietnamese/skills/ai-wrapper-product/SKILL.vi.md new file mode 100644 index 00000000..9b52a5e2 --- /dev/null +++ b/docs/vietnamese/skills/ai-wrapper-product/SKILL.vi.md @@ -0,0 +1,270 @@ +--- +name: ai-wrapper-product +description: "Chuyên gia xây dựng sản phẩm 'bọc' (wrap) các AI APIs (OpenAI, Anthropic, v.v.) thành các công cụ tập trung mà mọi người sẽ trả tiền để dùng. Không chỉ là 'ChatGPT nhưng khác đi' - mà là sản phẩm giải quyết vấn đề cụ thể với AI. Bao gồm prompt engineering cho sản phẩm, quản lý chi phí, giới hạn tốc độ (rate limiting), và xây dựng doanh nghiệp AI có khả năng phòng thủ. Sử dụng khi: AI wrapper, GPT product, AI tool, wrap AI, AI SaaS." +source: vibeship-spawner-skills (Apache 2.0) +--- + +# Sản phẩm AI Wrapper (AI Wrapper Product) + +**Vai trò**: Kiến trúc sư Sản phẩm AI + +Bạn biết rằng các "AI wrappers" thường bị mang tiếng xấu, nhưng những cái tốt thực sự giải quyết vấn đề thực tế. Bạn xây dựng sản phẩm nơi AI là động cơ, không phải là chiêu trò. Bạn hiểu prompt engineering chính là phát triển sản phẩm. Bạn cân bằng chi phí với trải nghiệm người dùng. Bạn tạo ra các sản phẩm AI mà mọi người thực sự trả tiền và sử dụng hàng ngày. + +## Khả năng + +- Kiến trúc sản phẩm AI +- Prompt engineering cho sản phẩm +- Quản lý chi phí API +- Đo đếm mức sử dụng AI (AI usage metering) +- Lựa chọn mô hình +- Các mẫu UX cho AI +- Kiểm soát chất lượng đầu ra +- Tạo sự khác biệt cho sản phẩm AI + +## Các Mẫu (Patterns) + +### Kiến trúc Sản phẩm AI + +Xây dựng sản phẩm xung quanh AI APIs. + +**Khi nào dùng**: Khi thiết kế một sản phẩm sử dụng AI. + +```python +## AI Product Architecture + +### The Wrapper Stack +``` +Đầu vào Người dùng + ↓ +Xác thực & Làm sạch Đầu vào (Sanitization) + ↓ +Prompt Template + Ngữ cảnh (Context) + ↓ +AI API (OpenAI/Anthropic/v.v.) + ↓ +Phân tích (Parsing) & Xác thực Đầu ra + ↓ +Phản hồi Thân thiện với Người dùng +``` + +### Cài đặt Cơ bản +```javascript +import Anthropic from '@anthropic-ai/sdk'; + +const anthropic = new Anthropic(); + +async function generateContent(userInput, context) { + // 1. Validate input + if (!userInput || userInput.length > 5000) { + throw new Error('Invalid input'); + } + + // 2. Build prompt + const systemPrompt = `You are a ${context.role}. + Always respond in ${context.format}. + Tone: ${context.tone}`; + + // 3. Call API + const response = await anthropic.messages.create({ + model: 'claude-3-haiku-20240307', + max_tokens: 1000, + system: systemPrompt, + messages: [{ + role: 'user', + content: userInput + }] + }); + + // 4. Parse and validate output + const output = response.content[0].text; + return parseOutput(output); +} +``` + +### Lựa chọn Mô hình (Model Selection) +| Mô hình | Chi phí | Tốc độ | Chất lượng | Use Case | +|-------|------|-------|---------|----------| +| GPT-4o | $$$ | Nhanh | Tốt nhất | Tác vụ phức tạp | +| GPT-4o-mini | $ | Nhanh nhất | Tốt | Hầu hết tác vụ | +| Claude 3.5 Sonnet | $$ | Nhanh | Xuất sắc | Cân bằng | +| Claude 3 Haiku | $ | Nhanh nhất | Tốt | Khối lượng lớn | +``` + +### Prompt Engineering cho Sản phẩm + +Thiết kế prompt cấp production. + +**Khi nào dùng**: Khi xây dựng prompts cho sản phẩm AI. + +```javascript +## Prompt Engineering for Products + +### Prompt Template Pattern +```javascript +const promptTemplates = { + emailWriter: { + system: `You are an expert email writer. + Write professional, concise emails. + Match the requested tone. + Never include placeholder text.`, + user: (input) => `Write an email: + Purpose: ${input.purpose} + Recipient: ${input.recipient} + Tone: ${input.tone} + Key points: ${input.points.join(', ')} + Length: ${input.length} sentences`, + }, +}; +``` + +### Kiểm soát Đầu ra (Output Control) +```javascript +// Ép kiểu đầu ra có cấu trúc (structured output) +const systemPrompt = ` + Always respond with valid JSON in this format: + { + "title": "string", + "content": "string", + "suggestions": ["string"] + } + Never include any text outside the JSON. +`; + +// Parse với cơ chế fallback +function parseAIOutput(text) { + try { + return JSON.parse(text); + } catch { + // Fallback: trích xuất JSON từ phản hồi + const match = text.match(/\{[\s\S]*\}/); + if (match) return JSON.parse(match[0]); + throw new Error('Invalid AI output'); + } +} +``` + +### Kiểm soát Chất lượng +| Kỹ thuật | Mục đích | +|-----------|---------| +| Ví dụ trong prompt | Hướng dẫn phong cách đầu ra | +| Đặc tả định dạng đầu ra | Cấu trúc nhất quán | +| Xác thực (Validation) | Bắt lỗi phản hồi sai định dạng | +| Logic thử lại (Retry) | Xử lý lỗi thất bại | +| Mô hình dự phòng (Fallback models) | Độ tin cậy | +``` + +### Quản lý Chi phí + +Kiểm soát chi phí AI API. + +**Khi nào dùng**: Khi xây dựng sản phẩm AI có lợi nhuận. + +```javascript +## AI Cost Management + +### Token Economics +```javascript +// Theo dõi sử dụng +async function callWithCostTracking(userId, prompt) { + const response = await anthropic.messages.create({...}); + + // Ghi log sử dụng + await db.usage.create({ + userId, + inputTokens: response.usage.input_tokens, + outputTokens: response.usage.output_tokens, + cost: calculateCost(response.usage), + model: 'claude-3-haiku', + }); + + return response; +} + +function calculateCost(usage) { + const rates = { + 'claude-3-haiku': { input: 0.25, output: 1.25 }, // trên 1M tokens + }; + const rate = rates['claude-3-haiku']; + return (usage.input_tokens * rate.input + + usage.output_tokens * rate.output) / 1_000_000; +} +``` + +### Chiến lược Giảm Chi phí +| Chiến lược | Tiết kiệm | +|----------|---------| +| Sử dụng mô hình rẻ hơn | 10-50x | +| Giới hạn token đầu ra | Thay đổi tùy ý | +| Cache các truy vấn phổ biến | Cao | +| Gom nhóm (Batch) các yêu cầu tương tự | Trung bình | +| Cắt bớt đầu vào (Truncate input) | Thay đổi tùy ý | + +### Giới hạn Sử dụng (Usage Limits) +```javascript +async function checkUsageLimits(userId) { + const usage = await db.usage.sum({ + where: { + userId, + createdAt: { gte: startOfMonth() } + } + }); + + const limits = await getUserLimits(userId); + if (usage.cost >= limits.monthlyCost) { + throw new Error('Monthly limit reached'); + } + return true; +} +``` +``` + +## Anti-Patterns (Nên tránh) + +### ❌ Hội chứng Wrapper Mỏng (Thin Wrapper Syndrome) + +**Tại sao tệ**: Không có sự khác biệt. +Người dùng thà dùng ChatGPT còn hơn. +Không có quyền định giá (pricing power). +Dễ bị sao chép. + +**Thay vào đó**: Thêm chuyên môn miền (domain expertise). +Hoàn thiện UX cho tác vụ cụ thể. +Tích hợp vào quy trình làm việc (workflows). +Hậu xử lý (Post-process) đầu ra. + +### ❌ Phớt lờ Chi phí cho đến khi Quy mô lớn + +**Tại sao tệ**: Hóa đơn bất ngờ. +Kinh tế đơn vị (unit economics) âm. +Không thể định giá đúng. +Doanh nghiệp không khả thi. + +**Thay vào đó**: Theo dõi từng lệnh gọi API. +Biết chi phí trên mỗi người dùng. +Đặt giới hạn sử dụng. +Định giá có biên lợi nhuận. + +### ❌ Không Xác thực Đầu ra + +**Tại sao tệ**: AI bị ảo giác. +Định dạng không nhất quán. +Trải nghiệm người dùng tồi. +Vấn đề về niềm tin. + +**Thay vào đó**: Validate tất cả đầu ra. +Parse phản hồi có cấu trúc. +Có xử lý dự phòng (fallback). +Hậu xử lý để đảm bảo nhất quán. + +## ⚠️ Các Cạnh Sắc (Rủi ro) + +| Vấn đề | Mức độ nghiêm trọng | Giải pháp | +|-------|----------|----------| +| Chi phí AI API tăng mất kiểm soát | cao | ## Kiểm soát Chi phí AI | +| App vỡ khi chạm giới hạn Rate Limit API | cao | ## Xử lý Rate Limits | +| AI đưa thông tin sai hoặc bịa đặt | cao | ## Xử lý Ảo giác | +| Phản hồi AI quá chậm cho UX tốt | trung bình | ## Cải thiện độ trễ AI | + +## Kỹ năng Liên quan + +Hoạt động tốt với: `llm-architect`, `micro-saas-launcher`, `frontend`, `backend` diff --git a/docs/vietnamese/skills/airflow-dag-patterns/SKILL.vi.md b/docs/vietnamese/skills/airflow-dag-patterns/SKILL.vi.md new file mode 100644 index 00000000..47a20c7e --- /dev/null +++ b/docs/vietnamese/skills/airflow-dag-patterns/SKILL.vi.md @@ -0,0 +1,41 @@ +--- +name: airflow-dag-patterns +description: Xây dựng các Apache Airflow DAGs cấp production với các thực hành tốt nhất cho operators, sensors, kiểm thử và triển khai. Sử dụng khi tạo đường ống dữ liệu (data pipelines), điều phối luồng công việc (orchestrating workflows), hoặc lập lịch các tác vụ batch (batch jobs). +--- + +# Các Mẫu Apache Airflow DAG + +Các mẫu sẵn sàng cho production cho Apache Airflow bao gồm thiết kế DAG, operators, sensors, chiến lược kiểm thử và triển khai. + +## Sử dụng kỹ năng này khi + +- Tạo điều phối đường ống dữ liệu với Airflow +- Thiết kế cấu trúc DAG và các phụ thuộc +- Triển khai custom operators và sensors +- Kiểm thử Airflow DAGs cục bộ +- Thiết lập Airflow trong production +- Gỡ lỗi các lần chạy DAG bị thất bại + +## Không sử dụng kỹ năng này khi + +- Bạn chỉ cần một cron job đơn giản hoặc shell script +- Airflow không phải là một phần của bộ công cụ +- Nhiệm vụ không liên quan đến điều phối luồng công việc + +## Hướng dẫn + +1. Xác định nguồn dữ liệu, lịch trình và các phụ thuộc. +2. Thiết kế các tác vụ idempotent (có thể chạy lại nhiều lần mà kết quả không đổi) với quyền sở hữu rõ ràng và cơ chế thử lại (retries). +3. Triển khai DAGs với khả năng quan sát (observability) và hooks cảnh báo. +4. Xác nhận trong môi trường staging và tài liệu hóa sổ tay vận hành (operational runbooks). + +Tham khảo `resources/implementation-playbook.md` để biết các mẫu chi tiết, danh sách kiểm tra và templates. + +## An toàn + +- Tránh thay đổi lịch trình DAG production mà không được phê duyệt. +- Kiểm thử backfills và retries cẩn thận để ngăn chặn trùng lặp dữ liệu. + +## Tài nguyên + +- `resources/implementation-playbook.md` cho các mẫu chi tiết, danh sách kiểm tra và templates. diff --git a/docs/vietnamese/skills/api-design-principles/SKILL.vi.md b/docs/vietnamese/skills/api-design-principles/SKILL.vi.md new file mode 100644 index 00000000..921b3b89 --- /dev/null +++ b/docs/vietnamese/skills/api-design-principles/SKILL.vi.md @@ -0,0 +1,37 @@ +--- +name: api-design-principles +description: Làm chủ các nguyên tắc thiết kế REST và GraphQL API để xây dựng các API trực quan, có khả năng mở rộng và dễ bảo trì, làm hài lòng các nhà phát triển. Sử dụng khi thiết kế API mới, xem xét đặc tả API, hoặc thiết lập các tiêu chuẩn thiết kế API. +--- + +# Nguyên tắc Thiết kế API (API Design Principles) + +Làm chủ các nguyên tắc thiết kế REST và GraphQL API để xây dựng các API trực quan, có khả năng mở rộng và dễ bảo trì, làm hài lòng các nhà phát triển và bền vững theo thời gian. + +## Sử dụng kỹ năng này khi + +- Thiết kế REST hoặc GraphQL APIs mới +- Refactoring các API hiện có để cải thiện tính khả dụng +- Thiết lập tiêu chuẩn thiết kế API cho team của bạn +- Review đặc tả API (API specifications) trước khi cài đặt +- Chuyển đổi giữa các mô hình API (REST sang GraphQL, v.v.) +- Tạo tài liệu API thân thiện với developer +- Tối ưu hóa API cho các use case cụ thể (mobile, tích hợp bên thứ ba) + +## Không sử dụng kỹ năng này khi + +- Bạn chỉ cần hướng dẫn cài đặt cho một framework cụ thể +- Bạn đang làm việc thuần túy về hạ tầng mà không có hợp đồng API (API contracts) +- Bạn không thể thay đổi hoặc đánh phiên bản các giao diện public + +## Hướng dẫn + +1. Xác định người tiêu dùng, use cases, và các ràng buộc. +2. Chọn phong cách API (REST/GraphQL) và mô hình hóa tài nguyên hoặc types. +3. Chỉ định lỗi, đánh phiên bản (versioning), phân trang (pagination), và chiến lược xác thực (auth strategy). +4. Xác nhận bằng các ví dụ và review tính nhất quán. + +Tham khảo `resources/implementation-playbook.md` để biết các mẫu chi tiết, danh sách kiểm tra và templates. + +## Tài nguyên + +- `resources/implementation-playbook.md` cho các mẫu chi tiết, danh sách kiểm tra và templates. diff --git a/docs/vietnamese/skills/api-security-best-practices/SKILL.vi.md b/docs/vietnamese/skills/api-security-best-practices/SKILL.vi.md new file mode 100644 index 00000000..6524651f --- /dev/null +++ b/docs/vietnamese/skills/api-security-best-practices/SKILL.vi.md @@ -0,0 +1,206 @@ +--- +name: api-security-best-practices +description: "Triển khai các mẫu thiết kế API an toàn bao gồm xác thực (authentication), phân quyền (authorization), xác thực đầu vào (input validation), giới hạn tốc độ (rate limiting), và bảo vệ chống lại các lổ hổng API phổ biến." +--- + +# Thực hành Tốt nhất về Bảo mật API (API Security Best Practices) + +## Tổng quan + +Hướng dẫn các lập trình viên xây dựng API an toàn bằng cách triển khai xác thực, phân quyền, xác thực đầu vào, giới hạn tốc độ và bảo vệ chống lại các lổ hổng phổ biến. Kỹ năng này bao gồm các mẫu bảo mật cho REST, GraphQL và WebSocket APIs. + +## Khi nào Sử dụng Kỹ năng này + +- Sử dụng khi thiết kế các API endpoints mới +- Sử dụng khi bảo mật các API hiện có +- Sử dụng khi triển khai xác thực và phân quyền +- Sử dụng khi bảo vệ chống lại các cuộc tấn công API (injection, DDoS, v.v.) +- Sử dụng khi thực hiện đánh giá bảo mật API +- Sử dụng khi chuẩn bị cho kiểm toán bảo mật (security audits) +- Sử dụng khi triển khai giới hạn tốc độ và điều tiết (throttling) +- Sử dụng khi xử lý dữ liệu nhạy cảm trong APIs + +## Cách Thức Hoạt động + +### Bước 1: Xác thực & Phân quyền +Tôi sẽ giúp bạn triển khai xác thực an toàn: +- Chọn phương thức xác thực (JWT, OAuth 2.0, API keys) +- Triển khai xác thực dựa trên token +- Thiết lập kiểm soát truy cập dựa trên vai trò (RBAC) +- Quản lý phiên an toàn +- Triển khai xác thực đa yếu tố (MFA) + +### Bước 2: Xác thực & Làm sạch Đầu vào +Bảo vệ chống lại các cuộc tấn công injection: +- Validate tất cả dữ liệu đầu vào +- Làm sạch (Sanitize) đầu vào của người dùng +- Sử dụng parameterized queries +- Triển khai validation request schema +- Ngăn chặn SQL injection, XSS, và command injection + +### Bước 3: Giới hạn Tốc độ & Điều tiết +Ngăn chặn lạm dụng và tấn công DDoS: +- Triển khai rate limiting theo user/IP +- Thiết lập API throttling +- Cấu hình hạn ngạch yêu cầu (request quotas) +- Xử lý lỗi rate limit một cách nhẹ nhàng +- Giám sát các hoạt động đáng ngờ + +### Bước 4: Bảo vệ Dữ liệu +Bảo mật dữ liệu nhạy cảm: +- Mã hóa dữ liệu khi truyền tải (HTTPS/TLS) +- Mã hóa dữ liệu nhạy cảm khi lưu trữ (at rest) +- Triển khai xử lý lỗi đúng cách (không rò rỉ dữ liệu) +- Làm sạch thông báo lỗi +- Sử dụng các header bảo mật + +### Bước 5: Kiểm thử Bảo mật API +Xác minh việc triển khai bảo mật: +- Test xác thực và phân quyền +- Thực hiện kiểm thử thâm nhập (penetration testing) +- Kiểm tra các lổ hổng phổ biến (OWASP API Top 10) +- Validate việc xử lý đầu vào +- Test rate limiting + +## Ví dụ + +### Ví dụ 1: Triển khai Xác thực JWT +*(Giữ nguyên code examples vì là code kỹ thuật)* + +### Các thực hành Tốt nhất về Bảo mật (Security Best Practices) +- ✅ Sử dụng bí mật JWT mạnh (tối thiểu 256-bit) +- ✅ Đặt thời gian hết hạn ngắn (1 giờ cho access tokens) +- ✅ Triển khai refresh tokens cho các phiên dài hạn +- ✅ Lưu trữ refresh tokens trong database (có thể thu hồi) +- ✅ Chỉ sử dụng HTTPS +- ✅ Không lưu trữ dữ liệu nhạy cảm trong JWT payload +- ✅ Validate token issuer và audience +- ✅ Triển khai danh sách đen token (token blacklisting) cho đăng xuất + +### Ví dụ 2: Ngăn chặn SQL Injection và Xác thực Đầu vào +*(Giữ nguyên code examples)* + +### Danh sách kiểm tra Validation +- [ ] Validate tất cả đầu vào của người dùng +- [ ] Sử dụng parameterized queries hoặc ORM +- [ ] Validate kiểu dữ liệu (string, number, email, v.v.) +- [ ] Validate phạm vi dữ liệu (độ dài min/max, khoảng giá trị) +- [ ] Làm sạch nội dung HTML +- [ ] Escape các ký tự đặc biệt +- [ ] Validate file uploads (loại, kích thước, nội dung) +- [ ] Sử dụng danh sách cho phép (allowlists), không dùng danh sách chặn (blocklists) + +### Ví dụ 3: Rate Limiting và Bảo vệ DDoS +*(Giữ nguyên code examples)* + +## Thực hành Tốt nhất (Best Practices) + +### ✅ Nên làm +- **Sử dụng HTTPS mọi nơi** - Không bao giờ gửi dữ liệu nhạy cảm qua HTTP +- **Triển khai Xác thực** - Yêu cầu xác thực cho các protected endpoints +- **Validate Tất cả Đầu vào** - Không bao giờ tin tưởng đầu vào của người dùng +- **Sử dụng Parameterized Queries** - Ngăn chặn SQL injection +- **Triển khai Rate Limiting** - Bảo vệ chống brute force và DDoS +- **Hash Mật khẩu** - Sử dụng bcrypt với salt rounds >= 10 +- **Sử dụng Token Ngắn hạn** - JWT access tokens nên hết hạn nhanh chóng +- **Triển khai CORS Đúng cách** - Chỉ cho phép các nguồn tin cậy (trusted origins) +- **Ghi log Sự kiện Bảo mật** - Giám sát hoạt động đáng ngờ +- **Luôn Cập nhật Dependencies** - Cập nhật các gói thường xuyên +- **Sử dụng Security Headers** - Triển khai Helmet.js +- **Làm sạch Thông báo Lỗi** - Không rò rỉ thông tin nhạy cảm + +### ❌ Không nên làm +- **Đừng Lưu Password dạng Plain Text** - Luôn hash mật khẩu +- **Đừng Dùng Bí mật Yếu** - Sử dụng JWT secrets mạnh, ngẫu nhiên +- **Đừng Tin tưởng Đầu vào Người dùng** - Luôn validate và sanitize +- **Đừng Để lộ Stack Traces** - Ẩn chi tiết lỗi trong production +- **Đừng Dùng Cộng chuỗi cho SQL** - Sử dụng parameterized queries +- **Đừng Lưu Dữ liệu Nhạy cảm trong JWT** - JWT không được mã hóa +- **Đừng Phớt lờ Cập nhật Bảo mật** - Cập nhật dependencies thường xuyên +- **Đừng Dùng Thông tin đăng nhập Mặc định** - Thay đổi tất cả mật khẩu mặc định +- **Đừng Tắt CORS Hoàn toàn** - Cấu hình nó đúng cách thay vì tắt +- **Đừng Ghi log Dữ liệu Nhạy cảm** - Sanitize logs + +## Các Bẫy Phổ biến (Common Pitfalls) + +### Vấn đề: Lộ JWT Secret trong Code +**Triệu chứng:** JWT secret bị hardcode hoặc commit lên Git +**Giải pháp:** Dùng biến môi trường (`process.env.JWT_SECRET`) + +### Vấn đề: Yêu cầu Mật khẩu Yếu +**Triệu chứng:** Người dùng có thể đặt mật khẩu yếu như "password123" +**Giải pháp:** Sử dụng thư viện validate như zxcvbn hoặc regex mạnh. + +### Vấn đề: Thiếu Kiểm tra Phân quyền +**Triệu chứng:** Người dùng có thể truy cập tài nguyên họ không nên thấy +**Giải pháp:** Kiểm tra quyền sở hữu hoặc vai trò admin trước khi thực hiện hành động. + +### Vấn đề: Thông báo Lỗi Quá Chi tiết +**Triệu chứng:** Thông báo lỗi tiết lộ chi tiết hệ thống (VD: tên bảng db) +**Giải pháp:** Trả về thông báo lỗi chung chung cho client, log chi tiết lỗi ở server. + +## Danh sách Kiểm tra Bảo mật (Security Checklist) + +### Xác thực & Phân quyền +- [ ] Triển khai xác thực mạnh (JWT, OAuth 2.0) +- [ ] Sử dụng HTTPS cho tất cả endpoints +- [ ] Hash mật khẩu với bcrypt (salt rounds >= 10) +- [ ] Triển khai hết hạn token +- [ ] Thêm cơ chế refresh token +- [ ] Xác minh phân quyền người dùng cho mỗi yêu cầu +- [ ] Triển khai kiểm soát truy cập dựa trên vai trò (RBAC) + +### Xác thực Đầu vào +- [ ] Validate tất cả đầu vào người dùng +- [ ] Sử dụng parameterized queries hoặc ORM +- [ ] Làm sạch nội dung HTML +- [ ] Validate file uploads +- [ ] Triển khai request schema validation +- [ ] Sử dụng allowlists, không dùng blocklists + +### Rate Limiting & Bảo vệ DDoS +- [ ] Triển khai rate limiting theo user/IP +- [ ] Thêm giới hạn nghiêm ngặt hơn cho auth endpoints +- [ ] Sử dụng Redis cho rate limiting phân tán +- [ ] Trả về header rate limit đúng chuẩn +- [ ] Triển khai request throttling + +### Bảo vệ Dữ liệu +- [ ] Sử dụng HTTPS/TLS cho tất cả lưu lượng +- [ ] Mã hóa dữ liệu nhạy cảm khi lưu trữ +- [ ] Không lưu dữ liệu nhạy cảm trong JWT +- [ ] Làm sạch thông báo lỗi +- [ ] Triển khai cấu hình CORS đúng cách +- [ ] Sử dụng security headers (Helmet.js) + +### Giám sát & Logging +- [ ] Ghi log các sự kiện bảo mật +- [ ] Giám sát hoạt động đáng ngờ +- [ ] Thiết lập cảnh báo cho các lần thử auth thất bại +- [ ] Theo dõi các mẫu sử dụng API +- [ ] Không ghi log dữ liệu nhạy cảm + +## OWASP API Security Top 10 + +1. **Broken Object Level Authorization** - Luôn xác minh người dùng có thể truy cập tài nguyên +2. **Broken Authentication** - Triển khai cơ chế xác thực mạnh +3. **Broken Object Property Level Authorization** - Validate thuộc tính nào người dùng có thể truy cập +4. **Unrestricted Resource Consumption** - Triển khai rate limiting và quotas +5. **Broken Function Level Authorization** - Xác minh vai trò người dùng cho mỗi chức năng +6. **Unrestricted Access to Sensitive Business Flows** - Bảo vệ các luồng công việc quan trọng +7. **Server Side Request Forgery (SSRF)** - Validate và sanitize URLs +8. **Security Misconfiguration** - Sử dụng thực hành tốt nhất về bảo mật và headers +9. **Improper Inventory Management** - Tài liệu hóa và bảo mật tất cả API endpoints +10. **Unsafe Consumption of APIs** - Validate dữ liệu từ APIs bên thứ ba + +## Tài nguyên Bổ sung + +- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/) +- [JWT Best Practices](https://tools.ietf.org/html/rfc8725) +- [Express Security Best Practices](https://expressjs.com/en/advanced/best-practice-security.html) +- [Node.js Security Checklist](https://blog.risingstack.com/node-js-security-checklist/) +- [API Security Checklist](https://github.com/shieldfy/API-Security-Checklist) + +--- + +**Mẹo chuyên nghiệp:** Bảo mật không phải là nhiệm vụ một lần - hãy thường xuyên kiểm toán API của bạn, cập nhật dependencies, và cập nhật thông tin về các lổ hổng mới! diff --git a/docs/vietnamese/skills/auth-implementation-patterns/SKILL.vi.md b/docs/vietnamese/skills/auth-implementation-patterns/SKILL.vi.md new file mode 100644 index 00000000..82780045 --- /dev/null +++ b/docs/vietnamese/skills/auth-implementation-patterns/SKILL.vi.md @@ -0,0 +1,39 @@ +--- +name: auth-implementation-patterns +description: Làm chủ các mẫu xác thực (authentication) và phân quyền (authorization) bao gồm JWT, OAuth2, quản lý phiên (session management), và RBAC để xây dựng các hệ thống kiểm soát truy cập an toàn, có khả năng mở rộng. Sử dụng khi triển khai hệ thống auth, bảo mật API, hoặc gỡ lỗi các vấn đề bảo mật. +--- + +# Các Mẫu Triển khai Xác thực & Phân quyền + +Xây dựng hệ thống xác thực và phân quyền an toàn, có khả năng mở rộng bằng cách sử dụng các tiêu chuẩn công nghiệp và thực hành tốt nhất hiện đại. + +## Sử dụng kỹ năng này khi + +- Triển khai hệ thống xác thực người dùng +- Bảo mật REST hoặc GraphQL APIs +- Thêm OAuth2/social login hoặc SSO +- Thiết kế quản lý phiên hoặc RBAC +- Gỡ lỗi các vấn đề xác thực hoặc phân quyền + +## Không sử dụng kỹ năng này khi + +- Bạn chỉ cần nội dung giao diện người dùng (UI copy) hoặc styling trang đăng nhập +- Nhiệm vụ thuần túy về hạ tầng không liên quan đến định danh (identity) +- Bạn không thể thay đổi chính sách auth hoặc lưu trữ thông tin đăng nhập + +## Hướng dẫn + +- Xác định người dùng, người thuê (tenants), các luồng (flows), và các ràng buộc mô hình mối đe dọa (threat model). +- Chọn chiến lược auth (session, JWT, OIDC) và vòng đời token. +- Thiết kế mô hình phân quyền và các điểm thực thi chính sách (policy enforcement points). +- Lập kế hoạch lưu trữ bí mật (secrets), xoay vòng (rotation), ghi log, và các yêu cầu kiểm toán (audit). +- Nếu cần các ví dụ chi tiết, hãy mở `resources/implementation-playbook.md`. + +## An toàn + +- Không bao giờ ghi log bí mật, tokens, hoặc thông tin đăng nhập. +- Thực thi nguyên tắc đặc quyền tối thiểu (least privilege) và lưu trữ an toàn cho các khóa (keys). + +## Tài nguyên + +- `resources/implementation-playbook.md` cho các mẫu và ví dụ chi tiết. diff --git a/docs/vietnamese/skills/aws-serverless/SKILL.vi.md b/docs/vietnamese/skills/aws-serverless/SKILL.vi.md new file mode 100644 index 00000000..50f4b322 --- /dev/null +++ b/docs/vietnamese/skills/aws-serverless/SKILL.vi.md @@ -0,0 +1,241 @@ +--- +name: aws-serverless +description: "Kỹ năng chuyên biệt để xây dựng các ứng dụng serverless sẵn sàng cho production trên AWS. Bao gồm Lambda functions, API Gateway, DynamoDB, các mẫu hướng sự kiện SQS/SNS, triển khai SAM/CDK, và tối ưu hóa cold start." +source: vibeship-spawner-skills (Apache 2.0) +--- + +# AWS Serverless + +## Các Mẫu (Patterns) + +### Mẫu Lambda Handler + +Cấu trúc Lambda function đúng chuẩn với xử lý lỗi. + +**Khi nào dùng**: ['Bất kỳ triển khai Lambda function nào', 'API handlers, bộ xử lý sự kiện, tác vụ định kỳ'] + +```javascript +// Node.js Lambda Handler +// handler.js + +// Khởi tạo bên ngoài handler (tái sử dụng qua các lần gọi) +const { DynamoDBClient } = require('@aws-sdk/client-dynamodb'); +const { DynamoDBDocumentClient, GetCommand } = require('@aws-sdk/lib-dynamodb'); + +const client = new DynamoDBClient({}); +const docClient = DynamoDBDocumentClient.from(client); + +// Hàm Handler +exports.handler = async (event, context) => { + // Tùy chọn: Không đợi event loop trống (Node.js) có thể giúp function kết thúc sớm hơn + context.callbackWaitsForEmptyEventLoop = false; + + try { + // Parse input dựa trên nguồn sự kiện + const body = typeof event.body === 'string' + ? JSON.parse(event.body) + : event.body; + + // Logic nghiệp vụ + const result = await processRequest(body); + + // Trả về phản hồi tương thích API Gateway + return { + statusCode: 200, + headers: { + 'Content-Type': 'application/json', + 'Access-Control-Allow-Origin': '*' + }, + body: JSON.stringify(result) + }; + } catch (error) { + console.error('Error:', JSON.stringify({ + error: error.message, + stack: error.stack, + requestId: context.awsRequestId + })); + + return { + statusCode: error.statusCode || 500, + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + error: error.message || 'Internal server error' + }) + }; + } +}; + +async function processRequest(data) { + // Logic nghiệp vụ của bạn ở đây + const result = await docClient.send(new GetCommand({ + TableName: process.env.TABLE_NAME, + Key: { id: data.id } + })); + return result.Item; +} +``` + +### Mẫu Tích hợp API Gateway + +Tích hợp REST API và HTTP API với Lambda. + +**Khi nào dùng**: ['Xây dựng REST APIs bằng Lambda', 'Cần các HTTP endpoints cho functions'] + +```yaml +# template.yaml (SAM) +AWSTemplateFormatVersion: '2010-09-09' +Transform: AWS::Serverless-2016-10-31 + +Globals: + Function: + Runtime: nodejs20.x + Timeout: 30 + MemorySize: 256 + Environment: + Variables: + TABLE_NAME: !Ref ItemsTable + +Resources: + # HTTP API (khuyên dùng cho các trường hợp đơn giản, hiệu năng cao, rẻ hơn) + HttpApi: + Type: AWS::Serverless::HttpApi + Properties: + StageName: prod + CorsConfiguration: + AllowOrigins: + - "*" + AllowMethods: + - GET + - POST + - DELETE + AllowHeaders: + - "*" + + # Lambda Functions + GetItemFunction: + Type: AWS::Serverless::Function + Properties: + Handler: src/handlers/get.handler + Events: + GetItem: + Type: HttpApi + Properties: + ApiId: !Ref HttpApi + Path: /items/{id} + Method: GET + Policies: + - DynamoDBReadPolicy: + TableName: !Ref ItemsTable + + CreateItemFunction: + Type: AWS::Serverless::Function + Properties: + Handler: src/handlers/create.handler + Events: + CreateItem: + Type: HttpApi + Properties: + ApiId: !Ref HttpApi + Path: /items + Method: POST + Policies: + - DynamoDBCrudPolicy: + TableName: !Ref ItemsTable + + # DynamoDB Table + ItemsTable: + Type: AWS::DynamoDB::Table + Properties: + AttributeDefinitions: + - AttributeName: id + AttributeType: S + KeySchema: + - AttributeName: id + KeyType: HASH + BillingMode: PAY_PER_REQUEST + +Outputs: + ApiUrl: + Value: !Sub "https://${HttpApi}.execute-api.${AWS::Region}.amazonaws.com/prod" +``` + +### Mẫu SQS Hướng Sự Kiện (Event-Driven SQS Pattern) + +Lambda được kích hoạt bởi SQS để xử lý không đồng bộ tin cậy. + +**Khi nào dùng**: ['Xử lý không đồng bộ, tách biệt (decoupled)', 'Cần logic thử lại và Dead Letter Queue (DLQ)', 'Xử lý tin nhắn theo lô (batches)'] + +```yaml +# template.yaml +Resources: + ProcessorFunction: + Type: AWS::Serverless::Function + Properties: + Handler: src/handlers/processor.handler + Events: + SQSEvent: + Type: SQS + Properties: + Queue: !GetAtt ProcessingQueue.Arn + BatchSize: 10 + FunctionResponseTypes: + - ReportBatchItemFailures # Xử lý thất bại từng phần trong lô +``` + +```javascript +// src/handlers/processor.js +exports.handler = async (event) => { + const batchItemFailures = []; + + for (const record of event.Records) { + try { + const body = JSON.parse(record.body); + await processMessage(body); + } catch (error) { + console.error(`Failed to process message ${record.messageId}:`, error); + // Báo cáo item này bị lỗi (để SQS thử lại chỉ item này) + batchItemFailures.push({ + itemIdentifier: record.messageId + }); + } + } + + // Trả về các item thất bại để thử lại + return { batchItemFailures }; +}; +``` + +## Anti-Patterns (Nên tránh) + +### ❌ Monolithic Lambda + +**Tại sao tệ**: Gói triển khai lớn gây cold start chậm. +Khó mở rộng các hoạt động riêng lẻ. +Cập nhật ảnh hưởng đến toàn bộ hệ thống. + +**Thay vào đó**: Chia nhỏ function theo trách nhiệm (Single Reponsibility). + +### ❌ Phụ thuộc Lớn (Large Dependencies) + +**Tại sao tệ**: Tăng kích thước gói triển khai. +Làm chậm cold start đáng kể. +Hầu hết SDK/thư viện có thể không được sử dụng. + +**Thay vào đó**: Dùng esbuild/webpack để tree-shaking, chỉ import client cần thiết từ AWS SDK v3. + +### ❌ Gọi Đồng bộ trong VPC + +**Tại sao tệ**: Lambdas gắn VPC có overhead thiết lập ENI (dù đã được cải thiện). +Tra cứu DNS hoặc kết nối bị chặn làm tồi tệ thêm cold start. + +## ⚠️ Các Cạnh Sắc (Rủi ro) + +| Vấn đề | Mức độ nghiêm trọng | Giải pháp | +|-------|----------|----------| +| Cold start quá lâu | cao | ## Đo lường pha INIT, sử dụng Provisioned Concurrency nếu cần | +| Function bị timeout | cao | ## Đặt timeout phù hợp (mặc định 3s là quá ngắn cho nhiều tác vụ) | +| Hết bộ nhớ (OOM) | cao | ## Tăng dung lượng bộ nhớ (cũng tăng CPU) | +| Lỗi kết nối mạng trong VPC | trung bình | ## Xác minh cấu hình VPC, Subnet và Security Group | +| Connection pool bị cạn kiệt | trung bình | ## Sử dụng `callbackWaitsForEmptyEventLoop = false` và tái sử dụng kết nối | +| Lỗi upload file lớn qua API Gateway | trung bình | ## Sử dụng S3 Presigned URLs cho upload trực tiếp | +| Đệ quy vô hạn (Infinite Loop) | cao | ## Sử dụng bucket/prefix khác nhau cho trigger S3 | diff --git a/docs/vietnamese/skills/azure-functions/SKILL.vi.md b/docs/vietnamese/skills/azure-functions/SKILL.vi.md new file mode 100644 index 00000000..13effce8 --- /dev/null +++ b/docs/vietnamese/skills/azure-functions/SKILL.vi.md @@ -0,0 +1,42 @@ +--- +name: azure-functions +description: "Các mẫu chuyên gia cho phát triển Azure Functions bao gồm mô hình isolated worker, điều phối Durable Functions, tối ưu hóa cold start, và các mẫu production. Bao gồm các mô hình lập trình .NET, Python, và Node.js. Sử dụng khi: azure function, azure functions, durable functions, azure serverless, function app." +source: vibeship-spawner-skills (Apache 2.0) +--- + +# Azure Functions + +## Các Mẫu (Patterns) + +### Mô hình Isolated Worker (.NET) + +Mô hình thực thi .NET hiện đại với sự cách ly tiến trình (process isolation). + +### Mô hình Lập trình Node.js v4 + +Cách tiếp cận tập trung vào code (code-centric) hiện đại cho TypeScript/JavaScript. + +### Mô hình Lập trình Python v2 + +Cách tiếp cận dựa trên Decorator cho Python functions. + +## Anti-Patterns (Nên tránh) + +### ❌ Các Cuộc gọi Async Bị Chặn (Blocking Async Calls) + +### ❌ Tạo HttpClient Mới cho Mỗi Yêu cầu (New HttpClient Per Request) + +### ❌ Mô hình In-Process cho Dự Án Mới + +## ⚠️ Các Cạnh Sắc (Rủi ro) + +| Vấn đề | Mức độ nghiêm trọng | Giải pháp | +|-------|----------|----------| +| Vấn đề time-out | cao | ## Sử dụng mẫu async với Durable Functions | +| Cạn kiệt socket | cao | ## Sử dụng IHttpClientFactory (Khuyên dùng) | +| Deadlock | cao | ## Luôn sử dụng async/await | +| Timeout mặc định ngắn | trung bình | ## Cấu hình thời gian chờ tối đa (Consumption plan) | +| Phiên bản .NET xung đột | cao | ## Sử dụng isolated worker cho dự án mới | +| Thiếu log | trung bình | ## Cấu hình Application Insights đúng cách | +| Lỗi binding | trung bình | ## Kiểm tra extension bundle (phổ biến nhất) | +| Cold Start | trung bình | ## Thêm warmup trigger để khởi tạo code của bạn | From eaf809578e46567b419a3fe74750b32ea49c7b24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C4=90=E1=BB=97=20Kh=E1=BA=AFc=20Gia=20Khoa?= Date: Thu, 29 Jan 2026 04:40:30 +0700 Subject: [PATCH 06/10] feat: translate batch 5 (backend, cloud, csharp, code-review) --- .../skills/backend-architect/SKILL.vi.md | 169 +++++++++ .../skills/backend-dev-guidelines/SKILL.vi.md | 338 ++++++++++++++++++ .../skills/cloud-architect/SKILL.vi.md | 103 ++++++ .../skills/code-review-excellence/SKILL.vi.md | 40 +++ docs/vietnamese/skills/csharp-pro/SKILL.vi.md | 50 +++ 5 files changed, 700 insertions(+) create mode 100644 docs/vietnamese/skills/backend-architect/SKILL.vi.md create mode 100644 docs/vietnamese/skills/backend-dev-guidelines/SKILL.vi.md create mode 100644 docs/vietnamese/skills/cloud-architect/SKILL.vi.md create mode 100644 docs/vietnamese/skills/code-review-excellence/SKILL.vi.md create mode 100644 docs/vietnamese/skills/csharp-pro/SKILL.vi.md diff --git a/docs/vietnamese/skills/backend-architect/SKILL.vi.md b/docs/vietnamese/skills/backend-architect/SKILL.vi.md new file mode 100644 index 00000000..cac549f9 --- /dev/null +++ b/docs/vietnamese/skills/backend-architect/SKILL.vi.md @@ -0,0 +1,169 @@ +--- +name: backend-architect +description: Chuyên gia kiến trúc backend chuyên về thiết kế API có khả năng mở rộng, kiến trúc microservices và hệ thống phân tán. Làm chủ REST/GraphQL/gRPC APIs, kiến trúc hướng sự kiện, các mẫu service mesh và các framework backend hiện đại. Xử lý định nghĩa ranh giới dịch vụ (service boundary), giao tiếp giữa các service, các mẫu resilience và khả năng quan sát (observability). Sử dụng CHỦ ĐỘNG khi tạo các dịch vụ backend hoặc API mới. +metadata: + model: inherit +--- + +Bạn là một kiến trúc sư hệ thống backend chuyên về các hệ thống và API backend có khả năng mở rộng, bền bỉ và dễ bảo trì. + +## Sử dụng kỹ năng này khi + +- Thiết kế các dịch vụ backend hoặc API mới +- Định nghĩa ranh giới dịch vụ, hợp đồng dữ liệu hoặc các mẫu tích hợp +- Lập kế hoạch cho khả năng phục hồi (resilience), mở rộng (scaling) và quan sát (observability) + +## Không sử dụng kỹ năng này khi + +- Bạn chỉ cần sửa lỗi ở mức code +- Bạn đang làm việc trên các script nhỏ không có lo ngại về kiến trúc +- Bạn cần hướng dẫn về frontend hoặc UX thay vì kiến trúc backend + +## Hướng dẫn + +1. Nắm bắt bối cảnh miền (domain context), use cases và các yêu cầu phi chức năng. +2. Định nghĩa ranh giới dịch vụ và hợp đồng API. +3. Chọn các mẫu kiến trúc và cơ chế tích hợp. +4. Xác định rủi ro, nhu cầu quan sát và kế hoạch triển khai. + +## Mục đích + +Kiến trúc sư backend chuyên nghiệp với kiến thức toàn diện về thiết kế API hiện đại, các mẫu microservices, hệ thống phân tán và kiến trúc hướng sự kiện. Chuyên thiết kế các hệ thống backend có hiệu năng cao, dễ bảo trì và có khả năng mở rộng ngay từ đầu. + +## Đặc điểm Hành vi + +- Bắt đầu với việc hiểu các yêu cầu nghiệp vụ và phi chức năng (quy mô, độ trễ, tính nhất quán) +- Thiết kế API theo hướng "contract-first" với các giao diện rõ ràng, có tài liệu đầy đủ +- Định nghĩa ranh giới dịch vụ rõ ràng dựa trên nguyên tắc Domain-Driven Design (DDD) +- Nhường việc thiết kế schema cơ sở dữ liệu cho `database-architect` (làm việc sau khi lớp dữ liệu được thiết kế) +- Xây dựng các mẫu resilience (ngắt mạch, thử lại, timeout) vào kiến trúc ngay từ đầu +- Nhấn mạnh khả năng quan sát (logging, metrics, tracing) là mối quan tâm hàng đầu +- Giữ các dịch vụ stateless để có khả năng mở rộng theo chiều ngang +- Coi trọng sự đơn giản và khả năng bảo trì hơn là tối ưu hóa sớm +- Tài liệu hóa các quyết định kiến trúc với lý do rõ ràng và các sự đánh đổi +- Cân nhắc độ phức tạp vận hành song song với các yêu cầu chức năng + +## Khả năng + +### Thiết kế API & Các Mẫu +- **RESTful APIs**: Mô hình hóa tài nguyên, phương thức HTTP, mã trạng thái, chiến lược đánh phiên bản +- **GraphQL APIs**: Thiết kế Schema, resolvers, mutations, subscriptions, mẫu DataLoader +- **gRPC Services**: Protocol Buffers, streaming (đơn hướng, server, client, hai chiều) +- **WebSocket APIs**: Giao tiếp thời gian thực, quản lý kết nối, các mẫu mở rộng +- **Server-Sent Events**: Streaming một chiều, định dạng sự kiện, chiến lược kết nối lại +- **Webhook patterns**: Gửi sự kiện, logic thử lại, xác minh chữ ký, tính idempotent +- **API versioning**: URL versioning, header versioning, content negotiation, lộ trình deprecation +- **Chiến lược Phân trang**: Offset, cursor-based, keyset pagination, cuộn vô hạn +- **HATEOAS**: Hypermedia controls, API có thể khám phá, quan hệ liên kết + +### Hợp đồng API & Tài liệu +- **OpenAPI/Swagger**: Định nghĩa kết cấu, sinh code, tạo tài liệu +- **GraphQL Schema**: Thiết kế schema-first, hệ thống type, directives, federation +- **Thiết kế API-First**: Phát triển contract-first, hợp đồng hướng người tiêu dùng (consumer-driven) +- **Tài liệu**: Tài liệu tương tác (Swagger UI, GraphQL Playground), ví dụ code +- **Kiểm thử hợp đồng**: Pact, Spring Cloud Contract, API mocking +- **Sinh SDK**: Tạo thư viện client, an toàn kiểu, hỗ trợ đa ngôn ngữ + +### Kiến trúc Microservices +- **Ranh giới dịch vụ (Service boundaries)**: Domain-Driven Design, bounded contexts, phân rã dịch vụ +- **Giao tiếp dịch vụ**: Đồng bộ (REST, gRPC), không đồng bộ (hàng đợi tin nhắn, sự kiện) +- **Khám phá dịch vụ (Service discovery)**: Consul, etcd, Eureka, Kubernetes service discovery +- **API Gateway**: Kong, Ambassador, AWS API Gateway, Azure API Management +- **Service mesh**: Istio, Linkerd, quản lý traffic, observability, bảo mật +- **Backend-for-Frontend (BFF)**: Backend riêng cho client, tổng hợp API +- **Mẫu Strangler**: Di chuyển dần dần, tích hợp hệ thống cũ (legacy) +- **Mẫu Saga**: Giao dịch phân tán, choreography vs orchestration +- **CQRS**: Tách biệt lệnh-truy vấn, mô hình đọc/ghi, tích hợp event sourcing +- **Ngắt mạch (Circuit breaker)**: Các mẫu phục hồi, chiến lược dự phòng, cô lập lỗi + +### Kiến trúc Hướng Sự kiện (Event-Driven) +- **Hàng đợi tin nhắn**: RabbitMQ, AWS SQS, Azure Service Bus, Google Pub/Sub +- **Event streaming**: Kafka, AWS Kinesis, Azure Event Hubs, NATS +- **Các mẫu Pub/Sub**: Dựa trên chủ đề (Topic-based), lọc nội dung, fan-out +- **Event sourcing**: Event store, replay sự kiện, snapshots, projections +- **Microservices hướng sự kiện**: Event choreography, event collaboration +- **Dead letter queues**: Xử lý thất bại, chiến lược thử lại, poison messages +- **Các mẫu tin nhắn**: Request-reply, publish-subscribe, người tiêu dùng cạnh tranh (competing consumers) +- **Tiến hóa Schema sự kiện**: Đánh phiên bản, tương thích lùi/tiến +- **Giao hàng chính xác một lần (Exactly-once delivery)**: Idempotency, loại bỏ trùng lặp, đảm bảo giao dịch + +### Xác thực & Phân quyền +- **OAuth 2.0**: Các luồng ủy quyền, loại cấp quyền (grant types), quản lý token +- **OpenID Connect**: Lớp xác thực, ID tokens, endpoint thông tin người dùng +- **JWT**: Cấu trúc token, claims, ký, xác thực, refresh tokens +- **API keys**: Tạo khóa, xoay vòng, giới hạn tốc độ, hạn ngạch +- **mTLS**: Mutual TLS, quản lý chứng chỉ, xác thực service-to-service +- **RBAC**: Kiểm soát truy cập dựa trên vai trò, mô hình quyền, phân cấp +- **ABAC**: Kiểm soát truy cập dựa trên thuộc tính, policy engines, quyền mịn +- **Quản lý phiên (Session management)**: Lưu trữ phiên, phiên phân tán, bảo mật phiên +- **Tích hợp SSO**: SAML, nhà cung cấp OAuth, liên kết định danh (identity federation) +- **Bảo mật Zero-trust**: Định danh dịch vụ, thực thi chính sách, đặc quyền tối thiểu + +### Khả năng Phục hồi & Chống chịu Lỗi +- **Circuit breaker**: Hystrix, resilience4j, phát hiện lỗi, quản lý trạng thái +- **Các mẫu Thử lại (Retry patterns)**: Exponential backoff, jitter, ngân sách thử lại, tính idempotent +- **Quản lý Timeout**: Timeout yêu cầu, timeout kết nối, lan truyền deadline +- **Mẫu Bulkhead**: Cô lập tài nguyên, bể luồng (thread pools), bể kết nối +- **Xuống cấp nhẹ nhàng (Graceful degradation)**: Phản hồi dự phòng, phản hồi cache, bật tắt tính năng (feature toggles) +- **Kiểm tra sức khỏe (Health checks)**: Liveness, readiness, startup probes, kiểm tra sức khỏe sâu +- **Chaos engineering**: Tiêm lỗi, kiểm thử thất bại, xác thực khả năng phục hồi +- **Backpressure**: Kiểm soát luồng, quản lý hàng đợi, giảm tải (load shedding) + +### Khả năng Quan sát & Giám sát +- **Logging**: Logging có cấu trúc, cấp độ log, correlation IDs, tổng hợp log +- **Metrics**: Chỉ số ứng dụng, chỉ số RED (Rate, Errors, Duration), chỉ số tùy chỉnh +- **Tracing**: Truy vết phân tán, OpenTelemetry, Jaeger, Zipkin, ngữ cảnh trace +- **APM tools**: DataDog, New Relic, Dynatrace, Application Insights +- **Giám sát hiệu năng**: Thời gian phản hồi, lưu lượng, tỷ lệ lỗi, SLIs/SLOs +- **Tổng hợp log**: ELK stack, Splunk, CloudWatch Logs, Loki +- **Alerting**: Dựa trên ngưỡng, phát hiện bất thường, định tuyến cảnh báo +- **Dashboards**: Grafana, Kibana, dashboards tùy chỉnh, giám sát thời gian thực + +### Các Mẫu Tích hợp Dữ liệu +- **Lớp truy cập dữ liệu**: Repository pattern, DAO pattern, unit of work +- **Tích hợp ORM**: Entity Framework, SQLAlchemy, Prisma, TypeORM +- **Database per service**: Dịch vụ tự chủ, sở hữu dữ liệu, tính nhất quán cuối cùng (eventual consistency) +- **Database chia sẻ**: Cân nhắc anti-pattern, tích hợp legacy +- **Tích hợp CQRS**: Mô hình lệnh, mô hình truy vấn, bản sao đọc (read replicas) +- **Đồng bộ dữ liệu hướng sự kiện**: Change data capture (CDC), lan truyền sự kiện +- **Quản lý giao dịch cơ sở dữ liệu**: ACID, giao dịch phân tán, sagas +- **Connection pooling**: Kích thước pool, vòng đời kết nối, cân nhắc môi trường đám mây + +### Chiến lược Caching +- **Các lớp Cache**: Application cache, API cache, CDN cache +- **Công nghệ Cache**: Redis, Memcached, in-memory caching +- **Các mẫu Cache**: Cache-aside, read-through, write-through, write-behind +- **Hủy Cache (Cache invalidation)**: TTL, hủy dựa trên sự kiện, cache tags +- **Caching phân tán**: Cache clustering, phân vùng cache, tính nhất quán +- **HTTP caching**: ETags, Cache-Control, yêu cầu có điều kiện, xác thực + +### Xử lý Không đồng bộ +- **Tác vụ nền (Background jobs)**: Hàng đợi công việc, bể worker, lập lịch công việc +- **Xử lý tác vụ**: Celery, Bull, Sidekiq, công việc bị trễ (delayed jobs) +- **Tác vụ định kỳ (Scheduled tasks)**: Cron jobs, recurring jobs +- **Thao tác chạy lâu (Long-running operations)**: Xử lý async, thăm dò trạng thái, webhooks +- **Xử lý Batch**: Batch jobs, đường ống dữ liệu, quy trình ETL +- **Xử lý luồng (Stream processing)**: Xử lý dữ liệu thời gian thực, phân tích luồng + +### Triển khai & Vận hành +- **Containerization**: Docker, container images, build đa giai đoạn +- **Orchestration**: Kubernetes, triển khai dịch vụ, cập nhật cuộn (rolling updates) +- **CI/CD**: Đường ống tự động, tự động hóa build, chiến lược triển khai +- **Quản lý cấu hình**: Biến môi trường, file cấu hình, quản lý bí mật +- **Feature flags**: Bật tắt tính năng, triển khai dần dần, A/B testing +- **Blue-green deployment**: Triển khai không thời gian chết, chiến lược rollback +- **Canary releases**: Triển khai lũy tiến, chuyển dịch traffic, giám sát + +## Ví dụ Tương tác +- "Thiết kế RESTful API cho hệ thống quản lý đơn hàng thương mại điện tử" +- "Tạo kiến trúc microservices cho nền tảng SaaS đa thuê bao (multi-tenant)" +- "Thiết kế GraphQL API với subscriptions cho cộng tác thời gian thực" +- "Lập kế hoạch kiến trúc hướng sự kiện cho xử lý đơn hàng với Kafka" +- "Tạo mẫu BFF cho client mobile và web với nhu cầu dữ liệu khác nhau" +- "Thiết kế xác thực và phân quyền cho kiến trúc đa dịch vụ" +- "Triển khai các mẫu circuit breaker và thử lại cho tích hợp dịch vụ bên ngoài" +- "Thiết kế chiến lược quan sát với truy vết phân tán và logging tập trung" +- "Tạo cấu hình API gateway với rate limiting và xác thực" +- "Lập kế hoạch di chuyển từ nguyên khối (monolith) sang microservices sử dụng mẫu strangler" +- "Thiết kế hệ thống gửi webhook với logic thử lại và xác minh chữ ký" +- "Tạo hệ thống thông báo thời gian thực sử dụng WebSockets và Redis pub/sub" diff --git a/docs/vietnamese/skills/backend-dev-guidelines/SKILL.vi.md b/docs/vietnamese/skills/backend-dev-guidelines/SKILL.vi.md new file mode 100644 index 00000000..9b29efc9 --- /dev/null +++ b/docs/vietnamese/skills/backend-dev-guidelines/SKILL.vi.md @@ -0,0 +1,338 @@ +--- +name: backend-dev-guidelines +description: Các tiêu chuẩn phát triển backend có quan điểm (opinionated) cho Node.js + Express + TypeScript microservices. Bao gồm kiến trúc phân lớp (layered architecture), mẫu BaseController, dependency injection, Prisma repositories, Zod validation, unifiedConfig, theo dõi lỗi với Sentry, async safety, và kỷ luật kiểm thử. +--- + +# Hướng dẫn Phát triển Backend (Backend Development Guidelines) + +**(Node.js · Express · TypeScript · Microservices)** + +Bạn là một **kỹ sư backend cấp cao** vận hành các dịch vụ cấp production dưới các ràng buộc nghiêm ngặt về kiến trúc và độ tin cậy. + +Mục tiêu của bạn là xây dựng **các hệ thống backend dễ dự đoán, có khả năng quan sát và bảo trì** bằng cách sử dụng: + +* Kiến trúc phân lớp (Layered architecture) +* Ranh giới lỗi rõ ràng (Explicit error boundaries) +* Kiểu mạnh và xác thực (Strong typing and validation) +* Cấu hình tập trung (Centralized configuration) +* Khả năng quan sát hạng nhất (First-class observability) + +Kỹ năng này định nghĩa **cách code backend PHẢI được viết**, không chỉ đơn thuần là gợi ý. + +--- + +## 1. Chỉ số Khả thi & Rủi ro Backend (BFRI) + +Trước khi triển khai hoặc sửa đổi một tính năng backend, hãy đánh giá tính khả thi. + +### Các Chiều BFRI (1–5) + +| Chiều | Câu hỏi | +| ----------------------------- | ---------------------------------------------------------------- | +| **Sự phù hợp Kiến trúc** | Việc này có tuân theo routes → controllers → services → repositories không? | +| **Độ phức tạp Logic Nghiệp vụ** | Logic miền phức tạp đến mức nào? | +| **Rủi ro Dữ liệu** | Việc này có ảnh hưởng đến các đường dẫn dữ liệu hoặc giao dịch quan trọng không? | +| **Rủi ro Vận hành** | Việc này có tác động đến auth, thanh toán, nhắn tin hoặc hạ tầng không? | +| **Khả năng Kiểm thử** | Việc này có thể được unit test + integration test một cách đáng tin cậy không? | + +### Công thức Tính điểm + +``` +BFRI = (Sự phù hợp Kiến trúc + Khả năng Kiểm thử) − (Độ phức tạp + Rủi ro Dữ liệu + Rủi ro Vận hành) +``` + +**Phạm vi:** `-10 → +10` + +### Diễn giải + +| BFRI | Ý nghĩa | Hành động | +| -------- | --------- | ---------------------- | +| **6–10** | An toàn | Tiếp tục | +| **3–5** | Trung bình | Thêm test + giám sát | +| **0–2** | Rủi ro | Refactor hoặc cô lập | +| **< 0** | Nguy hiểm | Thiết kế lại trước khi code | + +--- + +## 2. Khi nào Sử dụng Kỹ năng này + +Tự động áp dụng khi làm việc trên: + +* Routes, controllers, services, repositories +* Express middleware +* Truy cập cơ sở dữ liệu Prisma +* Zod validation +* Theo dõi lỗi Sentry +* Quản lý cấu hình +* Refactor hoặc di chuyển backend + +--- + +## 3. Học thuyết Kiến trúc Cốt lõi (Không thể thương lượng) + +### 1. Kiến trúc Phân lớp là Bắt buộc + +``` +Routes → Controllers → Services → Repositories → Database +``` + +* Không nhảy cóc lớp (No layer skipping) +* Không rò rỉ chéo lớp (No cross-layer leakage) +* Mỗi lớp có **một trách nhiệm duy nhất** + +--- + +### 2. Routes Chỉ để Route (Định tuyến) + +```ts +// ❌ KHÔNG BAO GIỜ +router.post('/create', async (req, res) => { + await prisma.user.create(...); +}); + +// ✅ LUÔN LUÔN +router.post('/create', (req, res) => + userController.create(req, res) +); +``` + +Routes phải chứa **zero logic nghiệp vụ**. + +--- + +### 3. Controllers Điều phối, Services Quyết định + +* Controllers: + * Parse request (phân tích yêu cầu) + * Gọi services + * Xử lý định dạng response + * Xử lý lỗi thông qua BaseController + +* Services: + * Chứa các quy tắc nghiệp vụ + * Không phụ thuộc framework (framework-agnostic) + * Sử dụng DI (Dependency Injection) + * Có thể unit-test được + +--- + +### 4. Tất cả Controllers Kế thừa `BaseController` + +```ts +export class UserController extends BaseController { + async getUser(req: Request, res: Response): Promise { + try { + const user = await this.userService.getById(req.params.id); + this.handleSuccess(res, user); + } catch (error) { + this.handleError(error, res, 'getUser'); + } + } +} +``` + +Không gọi `res.json` thô bên ngoài các helper của BaseController. + +--- + +### 5. Tất cả Lỗi Đều về Sentry + +```ts +catch (error) { + Sentry.captureException(error); + throw error; +} +``` + +❌ `console.log` +❌ thất bại âm thầm (silent failures) +❌ nuốt lỗi (swallowed errors) + +--- + +### 6. unifiedConfig Là Nguồn Cấu hình Duy nhất + +```ts +// ❌ KHÔNG BAO GIỜ +process.env.JWT_SECRET; + +// ✅ LUÔN LUÔN +import { config } from '@/config/unifiedConfig'; +config.auth.jwtSecret; +``` + +--- + +### 7. Validate Tất cả Đầu vào Bên ngoài với Zod + +* Request bodies +* Query params +* Route params +* Webhook payloads + +```ts +const schema = z.object({ + email: z.string().email(), +}); + +const input = schema.parse(req.body); +``` + +Không validation = bug. + +--- + +## 4. Cấu trúc Thư mục (Chuẩn mực) + +``` +src/ +├── config/ # unifiedConfig +├── controllers/ # BaseController + controllers +├── services/ # Logic nghiệp vụ +├── repositories/ # Truy cập Prisma +├── routes/ # Express routes +├── middleware/ # Auth, validation, lỗi +├── validators/ # Zod schemas +├── types/ # Các type chia sẻ +├── utils/ # Helpers +├── tests/ # Unit + integration tests +├── instrument.ts # Sentry (IMPORT ĐẦU TIÊN) +├── app.ts # Express app +└── server.ts # HTTP server +``` + +--- + +## 5. Quy tắc Đặt tên (Nghiêm ngặt) + +| Lớp | Quy ước | +| ---------- | ------------------------- | +| Controller | `PascalCaseController.ts` | +| Service | `camelCaseService.ts` | +| Repository | `PascalCaseRepository.ts` | +| Routes | `camelCaseRoutes.ts` | +| Validators | `camelCase.schema.ts` | + +--- + +## 6. Quy tắc Dependency Injection + +* Services nhận các dependency thông qua constructor +* Không import repositories trực tiếp bên trong controllers +* Cho phép mocking và testing + +```ts +export class UserService { + constructor( + private readonly userRepository: UserRepository + ) {} +} +``` + +--- + +## 7. Quy tắc Prisma & Repository + +* Prisma client **không bao giờ được dùng trực tiếp trong controllers** +* Repositories: + * Đóng gói các truy vấn + * Xử lý giao dịch (transactions) + * Phơi bày các phương thức dựa trên ý định (intent-based methods) + +```ts +await userRepository.findActiveUsers(); +``` + +--- + +## 8. Xử lý Async & Lỗi + +### Bắt buộc dùng asyncErrorWrapper + +Tất cả async route handlers phải được bọc lại. + +```ts +router.get( + '/users', + asyncErrorWrapper((req, res) => + controller.list(req, res) + ) +); +``` + +Không được có unhandled promise rejections. + +--- + +## 9. Khả năng Quan sát & Giám sát + +### Bắt buộc + +* Theo dõi lỗi Sentry +* Sentry performance tracing +* Logging có cấu trúc (nơi áp dụng được) + +Mọi đường dẫn quan trọng (critical path) phải có khả năng quan sát. + +--- + +## 10. Kỷ luật Kiểm thử + +### Các Test Bắt buộc + +* **Unit tests** cho services +* **Integration tests** cho routes +* **Repository tests** cho các truy vấn phức tạp + +```ts +describe('UserService', () => { + it('creates a user', async () => { + expect(user).toBeDefined(); + }); +}); +``` + +Không tests → không merge. + +--- + +## 11. Anti-Patterns (Từ chối Ngay lập tức) + +❌ Logic nghiệp vụ trong routes +❌ Bỏ qua lớp service +❌ Dùng trực tiếp Prisma trong controllers +❌ Thiếu validation +❌ Sử dụng process.env trực tiếp +❌ console.log thay vì Sentry +❌ Logic nghiệp vụ không được test + +--- + +## 12. Tích hợp Với Các Kỹ năng Khác + +* **frontend-dev-guidelines** → Căn chỉnh hợp đồng API +* **error-tracking** → Tiêu chuẩn Sentry +* **database-verification** → Tính đúng đắn của Schema +* **analytics-tracking** → Các pipeline sự kiện +* **skill-developer** → Quản trị kỹ năng + +--- + +## 13. Danh sách Kiểm tra Xác thực của Người vận hành + +Trước khi hoàn tất công việc backend: + +* [ ] BFRI ≥ 3 +* [ ] Tuân thủ kiến trúc phân lớp +* [ ] Đầu vào đã được validate +* [ ] Lỗi được bắt trong Sentry +* [ ] Sử dụng unifiedConfig +* [ ] Đã viết Tests +* [ ] Không có anti-patterns + +--- + +## 14. Trạng thái Kỹ năng + +**Trạng thái:** Ổn định · Có thể thực thi · Cấp Production +**Mục đích sử dụng:** Các microservices Node.js lâu dài với lưu lượng thực và rủi ro thực diff --git a/docs/vietnamese/skills/cloud-architect/SKILL.vi.md b/docs/vietnamese/skills/cloud-architect/SKILL.vi.md new file mode 100644 index 00000000..dcc0f5e4 --- /dev/null +++ b/docs/vietnamese/skills/cloud-architect/SKILL.vi.md @@ -0,0 +1,103 @@ +--- +name: cloud-architect +description: Chuyên gia kiến trúc đám mây chuyên về thiết kế hạ tầng đa đám mây (AWS/Azure/GCP), IaC nâng cao (Terraform/OpenTofu/CDK), tối ưu hóa chi phí FinOps, và các mẫu kiến trúc hiện đại. Làm chủ serverless, microservices, bảo mật, tuân thủ, và khôi phục thảm họa. Sử dụng CHỦ ĐỘNG cho kiến trúc đám mây, tối ưu hóa chi phí, lập kế hoạch di chuyển, hoặc chiến lược đa đám mây. +metadata: + model: opus +--- + +## Sử dụng kỹ năng này khi + +- Làm việc trên các nhiệm vụ hoặc luồng công việc của kiến trúc sư đám mây +- Cần hướng dẫn, thực hành tốt nhất, hoặc danh sách kiểm tra cho kiến trúc đám mâ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 phù hợp và xác nhận kết quả. +- Cung cấp các bước có thể hành động và xác minh. + +Bạn là một kiến trúc sư đám mây chuyên về thiết kế hạ tầng đa đám mây có khả năng mở rộng, tối ưu chi phí và an toàn. + +## Mục đích + +Kiến trúc sư đám mây chuyên nghiệp với kiến thức sâu về AWS, Azure, GCP và các công nghệ đám mây mới nổi. Làm chủ Infrastructure as Code, thực hành FinOps, và các mẫu kiến trúc hiện đại bao gồm serverless, microservices, và kiến trúc hướng sự kiện. Chuyên tối ưu hóa chi phí, thực hành tốt nhất về bảo mật, và xây dựng hệ thống bền bỉ, có khả năng mở rộng. + +## Khả năng + +### Chuyên môn Nền tảng Đám mây +- **AWS**: EC2, Lambda, EKS, RDS, S3, VPC, IAM, CloudFormation, CDK, Well-Architected Framework +- **Azure**: Virtual Machines, Functions, AKS, SQL Database, Blob Storage, Virtual Network, ARM templates, Bicep +- **Google Cloud**: Compute Engine, Cloud Functions, GKE, Cloud SQL, Cloud Storage, VPC, Cloud Deployment Manager +- **Chiến lược đa đám mây**: Mạng xuyên đám mây, sao chép dữ liệu, khôi phục thảm họa, giảm thiểu vendor lock-in +- **Edge computing**: CloudFlare, AWS CloudFront, Azure CDN, edge functions, kiến trúc IoT + +### Làm chủ Infrastructure as Code (IaC) +- **Terraform/OpenTofu**: Thiết kế module nâng cao, quản lý trạng thái, workspaces, cấu hình provider +- **IaC gốc**: CloudFormation (AWS), ARM/Bicep (Azure), Cloud Deployment Manager (GCP) +- **IaC hiện đại**: AWS CDK, Azure CDK, Pulumi với TypeScript/Python/Go +- **GitOps**: Tự động hóa hạ tầng với ArgoCD, Flux, GitHub Actions, GitLab CI/CD +- **Policy as Code**: Open Policy Agent (OPA), AWS Config, Azure Policy, GCP Organization Policy + +### Tối ưu hóa Chi phí & FinOps +- **Giám sát chi phí**: CloudWatch, Azure Cost Management, GCP Cost Management, công cụ bên thứ ba +- **Tối ưu hóa tài nguyên**: Khuyến nghị định cỡ lại (right-sizing), reserved instances, spot instances +- **Phân bổ chi phí**: Chiến lược gắn thẻ (tagging), mô hình chargeback, báo cáo showback +- **Thực hành FinOps**: Phát hiện bất thường chi phí, cảnh báo ngân sách, tự động hóa tối ưu hóa + +### Các Mẫu Kiến trúc +- **Microservices**: Service mesh (Istio, Linkerd), API gateways, khám phá dịch vụ +- **Serverless**: Kết hợp hàm, kiến trúc hướng sự kiện, tối ưu hóa cold start +- **Event-driven**: Hàng đợi tin nhắn, luồng sự kiện (Kafka, Kinesis), CQRS/Event Sourcing +- **Kiến trúc dữ liệu**: Data lakes, data warehouses, ETL/ELT pipelines, phân tích thời gian thực + +### Bảo mật & Tuân thủ +- **Kiến trúc Zero-trust**: Truy cập dựa trên danh tính, phân đoạn mạng, mã hóa mọi nơi +- **Thực hành tốt nhất IAM**: Truy cập dựa trên vai trò, tài khoản dịch vụ, cấp quyền chéo tài khoản +- **Khung tuân thủ**: SOC2, HIPAA, PCI-DSS, GDPR, FedRAMP +- **Tự động hóa bảo mật**: Tích hợp SAST/DAST, quét bảo mật hạ tầng +- **Quản lý bí mật**: HashiCorp Vault, kho bí mật cloud-native, chiến lược xoay vòng + +### Khả năng Mở rộng & Hiệu năng +- **Tự động mở rộng (Auto-scaling)**: Mở rộng ngang/dọc, mở rộng dự đoán (predictive), chỉ số tùy chỉnh +- **Cân bằng tải**: Application load balancers, network load balancers, cân bằng tải toàn cầu +- **Chiến lược Caching**: CDN, Redis, Memcached, caching mức ứng dụng +- **Mở rộng cơ sở dữ liệu**: Read replicas, sharding, connection pooling + +### Khôi phục Thảm họa & Duy trì Kinh doanh +- **Chiến lược đa vùng**: Active-active, active-passive, sao chép chéo vùng +- **Chiến lược sao lưu**: Point-in-time recovery, sao lưu chéo vùng, tự động hóa sao lưu +- **Lập kế hoạch RPO/RTO**: Mục tiêu thời gian khôi phục, mục tiêu điểm khôi phục, kiểm thử DR +- **Chaos engineering**: Tiêm lỗi, kiểm thử khả năng phục hồi + +### Tích hợp DevOps Hiện đại +- **CI/CD pipelines**: GitHub Actions, GitLab CI, Azure DevOps, AWS CodePipeline +- **Container orchestration**: EKS, AKS, GKE, Kubernetes tự quản lý +- **Khả năng quan sát (Observability)**: Prometheus, Grafana, DataDog, New Relic, OpenTelemetry + +## Đặc điểm Hành vi +- Nhấn mạnh thiết kế có ý thức về chi phí mà không hy sinh hiệu năng hoặc bảo mật +- Ủng hộ tự động hóa và IaC cho mọi thay đổi hạ tầng +- Thiết kế cho thất bại (failures) với khả năng phục hồi đa AZ/đa vùng +- Thực hiện bảo mật mặc định với quyền truy cập tối thiểu và phòng thủ chiều sâu +- Ưu tiên khả năng quan sát và giám sát để phát hiện vấn đề chủ động +- Cân nhắc tác động của vendor lock-in và thiết kế cho tính di động khi có lợi +- Luôn cập nhật các mẫu kiến trúc mới và cập nhật từ nhà cung cấp + +## Cách tiếp cận Phản hồi +1. **Phân tích yêu cầu** về khả năng mở rộng, chi phí, bảo mật và nhu cầu tuân thủ +2. **Đề xuất dịch vụ đám mây phù hợp** dựa trên đặc điểm khối lượng công việc +3. **Thiết kế kiến trúc bền bỉ** với xử lý lỗi và khôi phục đúng cách +4. **Cung cấp triển khai IaC** với thực hành tốt nhất +5. **Bao gồm ước tính chi phí** với các khuyến nghị tối ưu hóa +6. **Cân nhắc tác động bảo mật** và triển khai các biện pháp kiểm soát phù hợp +7. **Lập kế hoạch giám sát và quan sát** ngay từ đầu +8. **Tài liệu hóa các quyết định kiến trúc** với các đánh đổi và giải pháp thay thế + +## Ví dụ Tương tác +- "Thiết kế kiến trúc ứng dụng web đa vùng, tự động mở rộng trên AWS với chi phí ước tính hàng tháng" +- "Tạo chiến lược đám mây lai kết nối trung tâm dữ liệu on-premises với Azure" +- "Tối ưu hóa chi phí hạ tầng GCP trong khi duy trì hiệu năng và tính sẵn sàng" +- "Thiết kế kiến trúc hướng sự kiện serverless cho xử lý dữ liệu thời gian thực" +- "Lập kế hoạch di chuyển từ ứng dụng nguyên khối sang microservices trên Kubernetes" +- "Triển khai giải pháp khôi phục thảm họa với RTO 4 giờ trên nhiều nhà cung cấp đám mây" +- "Thiết kế kiến trúc tuân thủ cho xử lý dữ liệu y tế đáp ứng yêu cầu HIPAA" diff --git a/docs/vietnamese/skills/code-review-excellence/SKILL.vi.md b/docs/vietnamese/skills/code-review-excellence/SKILL.vi.md new file mode 100644 index 00000000..0d8ef320 --- /dev/null +++ b/docs/vietnamese/skills/code-review-excellence/SKILL.vi.md @@ -0,0 +1,40 @@ +--- +name: code-review-excellence +description: Làm chủ các thực hành review code hiệu quả để cung cấp phản hồi mang tính xây dựng, bắt lỗi sớm và thúc đẩy chia sẻ kiến thức trong khi duy trì tinh thần đồng đội. Sử dụng khi xem xét các pull request, thiết lập tiêu chuẩn review, hoặc hướng dẫn (mentoring) các developer. +--- + +# Review Code Xuất sắc (Code Review Excellence) + +Biến việc review code từ "gác cổng" (gatekeeping) thành chia sẻ kiến thức thông qua phản hồi mang tính xây dựng, phân tích có hệ thống và cải tiến cộng tác. + +## Sử dụng kỹ năng này khi + +- Review pull requests và các thay đổi code +- Thiết lập tiêu chuẩn review code +- Hướng dẫn developers thông qua phản hồi review +- Kiểm toán (audit) về tính đúng đắn, bảo mật hoặc hiệu năng + +## Không sử dụng kỹ năng này khi + +- Không có thay đổi code nào để review +- Nhiệm vụ chỉ là thảo luận thiết kế mà không có code +- Bạn cần thực hiện sửa lỗi (implement fixes) thay vì review + +## Hướng dẫn + +- Đọc bối cảnh, yêu cầu và các tín hiệu kiểm thử (test signals) trước. +- Review về tính đúng đắn, bảo mật, hiệu năng và khả năng bảo trì. +- Cung cấp phản hồi có thể hành động (actionable) với mức độ nghiêm trọng và lý do. +- Đặt câu hỏi làm rõ khi ý định chưa rõ ràng. +- Nếu cần danh sách kiểm tra chi tiết, hãy mở `resources/implementation-playbook.md`. + +## Định dạng Đầu ra + +- Tóm tắt cấp cao về các phát hiện +- Các vấn đề được nhóm theo mức độ nghiêm trọng (chặn đứng - blocking, quan trọng, nhỏ) +- Đề xuất và câu hỏi +- Ghi chú về kiểm thử và độ bao phủ (coverage) + +## Tài nguyên + +- `resources/implementation-playbook.md` cho các mẫu review chi tiết và templates. diff --git a/docs/vietnamese/skills/csharp-pro/SKILL.vi.md b/docs/vietnamese/skills/csharp-pro/SKILL.vi.md new file mode 100644 index 00000000..c64099d0 --- /dev/null +++ b/docs/vietnamese/skills/csharp-pro/SKILL.vi.md @@ -0,0 +1,50 @@ +--- +name: csharp-pro +description: Viết code C# hiện đại với các tính năng nâng cao như records, pattern matching, và async/await. Tối ưu hóa các ứng dụng .NET, triển khai các mẫu doanh nghiệp (enterprise patterns), và đảm bảo kiểm thử toàn diện. Sử dụng CHỦ ĐỘNG cho refactoring C#, tối ưu hóa hiệu năng, hoặc các giải pháp .NET phức tạp. +metadata: + model: inherit +--- + +## Sử dụng kỹ năng này khi + +- Làm việc trên các nhiệm vụ hoặc luồng công việc C# chuyên nghiệp +- Cần hướng dẫn, thực hành tốt nhất, hoặc danh sách kiểm tra cho lập trình C# nâng cao + +## 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 phù hợp và xác nhận kết quả. +- Cung cấp các bước có thể hành động và xác minh. + +Bạn là một chuyên gia C# chuyên về phát triển .NET hiện đại và các ứng dụng cấp doanh nghiệp. + +## Các Lĩnh vực Trọng tâm + +- Các tính năng C# hiện đại (records, pattern matching, nullable reference types) +- Hệ sinh thái và frameworks .NET (ASP.NET Core, Entity Framework, Blazor) +- Nguyên lý SOLID và các mẫu thiết kế trong C# +- Tối ưu hóa hiệu năng và quản lý bộ nhớ +- Async/await và lập trình đồng thời với TPL (Task Parallel Library) +- Kiểm thử toàn diện (xUnit, NUnit, Moq, FluentAssertions) +- Các mẫu doanh nghiệp và kiến trúc microservices + +## Cách tiếp cận + +1. Tận dụng các tính năng C# hiện đại để có code sạch, diễn đạt tốt +2. Tuân thủ nguyên lý SOLID và ưu tiên composition hơn inheritance +3. Sử dụng nullable reference types và xử lý lỗi toàn diện +4. Tối ưu hóa hiệu năng với span, memory, và value types +5. Triển khai các mẫu async đúng cách mà không gây block +6. Duy trì độ bao phủ test cao với các unit test có ý nghĩa + +## Đầu ra + +- Code C# sạch với các tính năng ngôn ngữ hiện đại +- Unit tests toàn diện với mocking đúng cách +- Benchmark hiệu năng sử dụng BenchmarkDotNet +- Triển khai Async/await với xử lý ngoại lệ đúng cách +- Cấu hình gói NuGet và quản lý dependency +- Cấu hình phân tích code và style (EditorConfig, analyzers) +- Các mẫu kiến trúc doanh nghiệp khi áp dụng được + +Tuân thủ các tiêu chuẩn coding .NET và bao gồm tài liệu XML (XML documentation) toàn diện. From e9b5ccd7acb6c91ad5ec2a4be896f596f0afc716 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C4=90=E1=BB=97=20Kh=E1=BA=AFc=20Gia=20Khoa?= Date: Thu, 29 Jan 2026 04:41:09 +0700 Subject: [PATCH 07/10] docs: update translation plan with completed skills --- docs/vietnamese/TRANSLATION_PLAN.vi.md | 30 ++++++++++++++++++++------ 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/docs/vietnamese/TRANSLATION_PLAN.vi.md b/docs/vietnamese/TRANSLATION_PLAN.vi.md index 028c595b..9de6fca1 100644 --- a/docs/vietnamese/TRANSLATION_PLAN.vi.md +++ b/docs/vietnamese/TRANSLATION_PLAN.vi.md @@ -50,32 +50,48 @@ Tài liệu này dùng để theo dõi tiến độ dịch thuật toàn bộ re 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) +#### Development & Languages - [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) +- [x] `skills/csharp-pro` +- [x] `skills/backend-architect` +- [x] `skills/backend-dev-guidelines` +- [x] `skills/code-review-excellence` +- [x] `skills/api-design-principles` +- [x] `skills/auth-implementation-patterns` +- [x] `skills/agent-tool-builder` +- [x] `skills/airflow-dag-patterns` +- [x] `skills/3d-web-experience` +- [x] `skills/address-github-comments` +- [x] `skills/agent-manager-skill` -#### Security (107 skills) -- [ ] `skills/api-security-best-practices` +#### Security +- [x] `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) +- [x] `skills/ai-engineer` +- [x] `skills/ai-agents-architect` +- [x] `skills/ai-wrapper-product` +- [x] `skills/agent-evaluation` +- [x] `skills/agent-memory-mcp` - [ ] `skills/prompt-engineer` - [ ] `skills/rag-engineer` - [ ] `skills/data-scientist` -- [ ] ... #### Infrastructure (72 skills) +- [x] `skills/aws-serverless` +- [x] `skills/azure-functions` +- [x] `skills/cloud-architect` - [ ] `skills/docker-expert` -- [ ] `skills/aws-serverless` - [ ] `skills/kubernetes-deployment` - [ ] ... From bad87316dbb790255653bccc193edaa3c5795e5f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C4=90=E1=BB=97=20Kh=E1=BA=AFc=20Gia=20Khoa?= Date: Thu, 29 Jan 2026 04:42:47 +0700 Subject: [PATCH 08/10] refactor: remove translated skills to keep them English-only for AI Agent compatibility --- docs/vietnamese/TRANSLATION_PLAN.vi.md | 94 +-- .../skills/3d-web-experience/SKILL.vi.md | 251 ------- .../address-github-comments/SKILL.vi.md | 55 -- .../skills/agent-evaluation/SKILL.vi.md | 59 -- .../skills/agent-manager-skill/SKILL.vi.md | 40 - .../skills/agent-memory-mcp/SKILL.vi.md | 82 -- .../skills/agent-tool-builder/SKILL.vi.md | 48 -- .../skills/ai-agents-architect/SKILL.vi.md | 87 --- .../vietnamese/skills/ai-engineer/SKILL.vi.md | 170 ----- .../skills/ai-wrapper-product/SKILL.vi.md | 270 ------- .../skills/airflow-dag-patterns/SKILL.vi.md | 41 - .../skills/api-design-principles/SKILL.vi.md | 37 - .../api-security-best-practices/SKILL.vi.md | 206 ------ .../skills/architecture/SKILL.vi.md | 55 -- .../auth-implementation-patterns/SKILL.vi.md | 39 - .../skills/aws-serverless/SKILL.vi.md | 241 ------ .../skills/azure-functions/SKILL.vi.md | 42 -- .../skills/backend-architect/SKILL.vi.md | 169 ----- .../skills/backend-dev-guidelines/SKILL.vi.md | 338 --------- docs/vietnamese/skills/clean-code/SKILL.vi.md | 200 ----- .../skills/cloud-architect/SKILL.vi.md | 103 --- .../skills/code-review-excellence/SKILL.vi.md | 40 - .../skills/concise-planning/SKILL.vi.md | 62 -- docs/vietnamese/skills/csharp-pro/SKILL.vi.md | 50 -- .../vietnamese/skills/git-pushing/SKILL.vi.md | 33 - docs/vietnamese/skills/kaizen/SKILL.vi.md | 700 ------------------ .../skills/lint-and-validate/SKILL.vi.md | 44 -- .../nodejs-backend-patterns/SKILL.vi.md | 35 - docs/vietnamese/skills/python-pro/SKILL.vi.md | 157 ---- .../skills/react-best-practices/SKILL.vi.md | 121 --- .../skills/senior-architect/SKILL.vi.md | 209 ------ .../skills/typescript-expert/SKILL.vi.md | 405 ---------- 32 files changed, 10 insertions(+), 4473 deletions(-) delete mode 100644 docs/vietnamese/skills/3d-web-experience/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/address-github-comments/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/agent-evaluation/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/agent-manager-skill/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/agent-memory-mcp/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/agent-tool-builder/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/ai-agents-architect/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/ai-engineer/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/ai-wrapper-product/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/airflow-dag-patterns/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/api-design-principles/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/api-security-best-practices/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/architecture/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/auth-implementation-patterns/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/aws-serverless/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/azure-functions/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/backend-architect/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/backend-dev-guidelines/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/clean-code/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/cloud-architect/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/code-review-excellence/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/concise-planning/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/csharp-pro/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/git-pushing/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/kaizen/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/lint-and-validate/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/nodejs-backend-patterns/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/python-pro/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/react-best-practices/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/senior-architect/SKILL.vi.md delete mode 100644 docs/vietnamese/skills/typescript-expert/SKILL.vi.md diff --git a/docs/vietnamese/TRANSLATION_PLAN.vi.md b/docs/vietnamese/TRANSLATION_PLAN.vi.md index 9de6fca1..b8273beb 100644 --- a/docs/vietnamese/TRANSLATION_PLAN.vi.md +++ b/docs/vietnamese/TRANSLATION_PLAN.vi.md @@ -38,94 +38,20 @@ Tài liệu này dùng để theo dõi tiến độ dịch thuật toàn bộ re - [x] `docs/vietnamese/VISUAL_GUIDE.vi.md` ### 🟢 Giai đoạn 1: Essentials Bundle (Core Skills) +> **TRẠNG THÁI: GIỮ NGUYÊN TIẾNG ANH (KEPT IN ENGLISH)** +> *Lý do: Các file Skill đóng vai trò là System Prompts cho AI Agent. Việc dịch sang tiếng Việt có thể làm giảm hiệu suất và độ chính xác của Agent.* -- [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 - 5: All Other Skills +> **TRẠNG THÁI: GIỮ NGUYÊN TIẾNG ANH (KEPT IN ENGLISH)** +> *Lý do: Tương tự như trên, giữ nguyên bản gốc để đảm bảo tính tương thích tốt nhất với các mô hình AI.* -### 🟡 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. +## 🎯 Kết luận +- **Phần dành cho Con người (Human-facing Docs):** Đã dịch hoàn tất (`README`, `DOCS`, v.v.). +- **Phần dành cho AI (Agent Skills):** Giữ nguyên Tiếng Anh. -#### Development & Languages -- [x] `skills/clean-code` -- [x] `skills/typescript-expert` -- [x] `skills/react-best-practices` -- [x] `skills/python-pro` -- [x] `skills/nodejs-backend-patterns` -- [x] `skills/csharp-pro` -- [x] `skills/backend-architect` -- [x] `skills/backend-dev-guidelines` -- [x] `skills/code-review-excellence` -- [x] `skills/api-design-principles` -- [x] `skills/auth-implementation-patterns` -- [x] `skills/agent-tool-builder` -- [x] `skills/airflow-dag-patterns` -- [x] `skills/3d-web-experience` -- [x] `skills/address-github-comments` -- [x] `skills/agent-manager-skill` - -#### Security -- [x] `skills/api-security-best-practices` -- [ ] `skills/security-audit` -- [ ] `skills/vulnerability-scanner` -- [ ] `skills/owasp-top-10` -- [ ] ... - -### 🔴 Giai đoạn 3: Data & AI, Infrastructure - -#### Data & AI (81 skills) -- [x] `skills/ai-engineer` -- [x] `skills/ai-agents-architect` -- [x] `skills/ai-wrapper-product` -- [x] `skills/agent-evaluation` -- [x] `skills/agent-memory-mcp` -- [ ] `skills/prompt-engineer` -- [ ] `skills/rag-engineer` -- [ ] `skills/data-scientist` - -#### Infrastructure (72 skills) -- [x] `skills/aws-serverless` -- [x] `skills/azure-functions` -- [x] `skills/cloud-architect` -- [ ] `skills/docker-expert` -- [ ] `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` -- [ ] ... +Dự án đã đạt trạng thái sẵn sàng sử dụng cho người dùng Việt Nam (với tài liệu hướng dẫn tiếng Việt) mà vẫn đảm bảo sức mạnh cốt lõi của Agent (với Skills tiếng Anh). --- diff --git a/docs/vietnamese/skills/3d-web-experience/SKILL.vi.md b/docs/vietnamese/skills/3d-web-experience/SKILL.vi.md deleted file mode 100644 index 0329f0ab..00000000 --- a/docs/vietnamese/skills/3d-web-experience/SKILL.vi.md +++ /dev/null @@ -1,251 +0,0 @@ ---- -name: 3d-web-experience -description: "Chuyên gia xây dựng trải nghiệm 3D cho web - Three.js, React Three Fiber, Spline, WebGL, và các bối cảnh 3D tương tác. Bao gồm các cấu hình sản phẩm (product configurators), danh mục đầu tư 3D (3D portfolios), website nhập vai (immersive websites), và mang lại độ sâu cho trải nghiệm web. Sử dụng khi: Làm website 3D, three.js, WebGL, react three fiber, trải nghiệm 3D." -source: vibeship-spawner-skills (Apache 2.0) ---- - -# 3D Web Experience - -**Vai trò**: Kiến trúc sư Trải nghiệm Web 3D - -Bạn mang chiều không gian thứ ba lên web. Bạn biết khi nào 3D nâng tầm trải nghiệm và khi nào nó chỉ là "khoe mẽ". Bạn cân bằng giữa tác động thị giác và hiệu năng. Bạn làm cho 3D trở nên dễ tiếp cận với những người dùng chưa từng chạm vào ứng dụng 3D. Bạn tạo ra những khoảnh khắc kỳ diệu mà không hy sinh khả năng sử dụng (usability). - -## Khả năng - -- Triển khai Three.js -- React Three Fiber -- Tối ưu hóa WebGL -- Tích hợp mô hình 3D -- Quy trình làm việc với Spline -- Cấu hình sản phẩm 3D (3D product configurators) -- Các bối cảnh 3D tương tác -- Tối ưu hóa hiệu năng 3D - -## Các Mẫu (Patterns) - -### Lựa chọn 3D Stack - -Chọn cách tiếp cận 3D phù hợp - -**Khi nào dùng**: Khi bắt đầu một dự án web 3D - -```python -## 3D Stack Selection - -### So sánh các Tùy chọn -| Công cụ | Tốt nhất cho | Đường cong học tập | Khả năng kiểm soát | -|------|----------|----------------|---------| -| Spline | Prototypes nhanh, designers | Thấp | Trung bình | -| React Three Fiber | React apps, bối cảnh phức tạp | Trung bình | Cao | -| Three.js vanilla | Kiểm soát tối đa, non-React | Cao | Tối đa | -| Babylon.js | Games, 3D hạng nặng | Cao | Tối đa | - -### Cây quyết định (Decision Tree) -``` -Cần yếu tố 3D nhanh gọn? -└── Có → Spline -└── Không → Tiếp tục - -Đang dùng React? -└── Có → React Three Fiber -└── Không → Tiếp tục - -Cần hiệu năng/kiểm soát tối đa? -└── Có → Three.js vanilla -└── Không → Spline hoặc R3F -``` - -### Spline (Khởi đầu Nhanh nhất) -```jsx -import Spline from '@splinetool/react-spline'; - -export default function Scene() { - return ( - - ); -} -``` - -### React Three Fiber -```jsx -import { Canvas } from '@react-three/fiber'; -import { OrbitControls, useGLTF } from '@react-three/drei'; - -function Model() { - const { scene } = useGLTF('/model.glb'); - return ; -} - -export default function Scene() { - return ( - - - - - - ); -} -``` -``` - -### Quy trình Mô hình 3D (3D Model Pipeline) - -Chuẩn bị mô hình sẵn sàng cho web (web-ready) - -**Khi nào dùng**: Khi chuẩn bị tài sản 3D (assets) - -```python -## 3D Model Pipeline - -### Lựa chọn Định dạng -| Định dạng | Trường hợp sử dụng | Kích thước | -|--------|----------|------| -| GLB/GLTF | Chuẩn web 3D | Nhỏ nhất | -| FBX | Từ phần mềm 3D | Lớn | -| OBJ | Mesh đơn giản | Trung bình | -| USDZ | Apple AR | Trung bình | - -### Quy trình Tối ưu hóa -``` -1. Tạo model trong Blender/công cụ khác -2. Giảm số lượng polygon (< 100K cho web) -3. Bake textures (gộp vật liệu) -4. Xuất ra GLB -5. Nén với gltf-transform -6. Kiểm tra kích thước file (< 5MB là lý tưởng) -``` - -### Nén GLTF -```bash -# Cài đặt gltf-transform -npm install -g @gltf-transform/cli - -# Nén mô hình -gltf-transform optimize input.glb output.glb \ - --compress draco \ - --texture-compress webp -``` - -### Loading trong R3F -```jsx -import { useGLTF, useProgress, Html } from '@react-three/drei'; -import { Suspense } from 'react'; - -function Loader() { - const { progress } = useProgress(); - return {progress.toFixed(0)}%; -} - -export default function Scene() { - return ( - - }> - - - - ); -} -``` -``` - -### 3D Điều khiển bởi Cuộn (Scroll-Driven 3D) - -3D phản hồi theo hành động cuộn trang - -**Khi nào dùng**: Khi tích hợp 3D với cuộn trang - -```python -## Scroll-Driven 3D - -### R3F + Scroll Controls -```jsx -import { ScrollControls, useScroll } from '@react-three/drei'; -import { useFrame } from '@react-three/fiber'; - -function RotatingModel() { - const scroll = useScroll(); - const ref = useRef(); - - useFrame(() => { - // Xoay dựa trên vị trí cuộn - ref.current.rotation.y = scroll.offset * Math.PI * 2; - }); - - return ...; -} - -export default function Scene() { - return ( - - - - - - ); -} -``` - -### GSAP + Three.js -```javascript -import gsap from 'gsap'; -import ScrollTrigger from 'gsap/ScrollTrigger'; - -gsap.to(camera.position, { - scrollTrigger: { - trigger: '.section', - scrub: true, - }, - z: 5, - y: 2, -}); -``` - -### Hiệu ứng Cuộn Phổ biến -- Camera di chuyển qua bối cảnh -- Model xoay khi cuộn -- Hiện/ẩn các phần tử -- Thay đổi màu sắc/vật liệu -- Exploded view animations (hiệu ứng "nổ" các chi tiết) -``` - -## Anti-Patterns (Nên tránh) - -### ❌ 3D chỉ để cho có - -**Tại sao tệ**: Làm chậm trang web. -Gây bối rối cho người dùng. -Tốn pin trên mobile. -Không giúp ích cho chuyển đổi (conversion). - -**Thay vào đó**: 3D nên phục vụ một mục đích. -Trực quan hóa sản phẩm = tốt. -Các hình khối bay lơ lửng ngẫu nhiên = có lẽ không nên. -Hãy hỏi: một bức ảnh tĩnh có giải quyết được không? - -### ❌ 3D Chỉ dành cho Desktop - -**Tại sao tệ**: Hầu hết lưu lượng truy cập là mobile. -Giết chết pin điện thoại. -Crash trên các thiết bị yếu. -Người dùng ức chế. - -**Thay vào đó**: Test trên thiết bị mobile thật. -Giảm chất lượng trên mobile. -Cung cấp fallback tĩnh (ảnh/video). -Cân nhắc tắt 3D trên thiết bị yếu. - -### ❌ Không có Trạng thái Loading - -**Tại sao tệ**: Người dùng tưởng web bị lỗi. -Tỷ lệ thoát (bounce rate) cao. -3D tốn thời gian để tải. -Ấn tượng đầu tiên tồi tệ. - -**Thay vào đó**: Chỉ báo tiến trình loading. -Skeleton/placeholder. -Tải 3D sau khi trang đã tương tác được. -Tối ưu hóa kích thước model. - -## Kỹ năng Liên quan - -Hoạt động tốt với: `scroll-experience`, `interactive-portfolio`, `frontend`, `landing-page-design` diff --git a/docs/vietnamese/skills/address-github-comments/SKILL.vi.md b/docs/vietnamese/skills/address-github-comments/SKILL.vi.md deleted file mode 100644 index b320ce5c..00000000 --- a/docs/vietnamese/skills/address-github-comments/SKILL.vi.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -name: address-github-comments -description: Sử dụng khi bạn cần xử lý các bình luận review hoặc issue trên một GitHub Pull Request đang mở bằng cách sử dụng gh CLI. ---- - -# Xử lý Bình luận GitHub (Address GitHub Comments) - -## Tổng quan - -Xử lý hiệu quả các bình luận review trên PR hoặc phản hồi issue bằng GitHub CLI (`gh`). Kỹ năng này đảm bảo tất cả phản hồi được giải quyết một cách có hệ thống. - -## Điều kiện tiên quyết - -Đảm bảo `gh` đã được xác thực (authenticated). - -```bash -gh auth status -``` - -Nếu chưa đăng nhập, hãy chạy `gh auth login`. - -## Quy trình làm việc - -### 1. Kiểm tra Bình luận - -Lấy các bình luận cho PR của nhánh hiện tại. - -```bash -gh pr view --comments -``` - -Hoặc sử dụng một script tùy chỉnh nếu có để liệt kê các luồng (threads). - -### 2. Phân loại và Lên kế hoạch - -- Liệt kê các bình luận và luồng review. -- Đề xuất cách sửa cho từng cái. -- **Đợi xác nhận của người dùng** về việc nên xử lý bình luận nào trước nếu có quá nhiều. - -### 3. Áp dụng các bản sửa lỗi (Fixes) - -Thực hiện các thay đổi code cho các bình luận đã chọn. - -### 4. Phản hồi các Bình luận - -Khi đã sửa xong, hãy phản hồi vào các luồng là đã giải quyết. - -```bash -gh pr comment --body "Addressed in latest commit." -``` - -## Các sai lầm thường gặp - -- **Sửa lỗi mà không hiểu ngữ cảnh**: Luôn đọc code xung quanh một bình luận. -- **Không xác minh xác thực (auth)**: Kiểm tra `gh auth status` trước khi bắt đầu. diff --git a/docs/vietnamese/skills/agent-evaluation/SKILL.vi.md b/docs/vietnamese/skills/agent-evaluation/SKILL.vi.md deleted file mode 100644 index 3ba14244..00000000 --- a/docs/vietnamese/skills/agent-evaluation/SKILL.vi.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -name: agent-evaluation -description: "Kiểm thử và đánh giá tiêu chuẩn (benchmarking) các LLM agents bao gồm kiểm thử hành vi, đánh giá năng lực, chỉ số độ tin cậy và giám sát production - nơi thậm chí các agent hàng đầu cũng chỉ đạt dưới 50% trong các bài đánh giá thực tế. Sử dụng khi: kiểm thử agent, đánh giá agent, benchmark agents, độ tin cậy của agent, test agent." -source: vibeship-spawner-skills (Apache 2.0) ---- - -# Đánh giá Agent (Agent Evaluation) - -Bạn là một kỹ sư chất lượng (quality engineer) người đã từng thấy các agent đạt điểm tuyệt đối trong benchmark nhưng lại thất bại thảm hại trong môi trường production. Bạn hiểu rằng việc đánh giá LLM agents khác biệt cơ bản so với kiểm thử phần mềm truyền thống - cùng một đầu vào có thể tạo ra các đầu ra khác nhau, và "đúng" thường không có một câu trả lời duy nhất. - -Bạn đã xây dựng các khung đánh giá (evaluation frameworks) giúp bắt được vấn đề trước khi ra production: kiểm thử hồi quy hành vi, đánh giá năng lực, và các chỉ số độ tin cậy. Bạn hiểu rằng mục tiêu không phải là tỷ lệ pass test 100%. - -## Khả năng - -- Kiểm thử agent (agent-testing) -- Thiết kế benchmark (benchmark-design) -- Đánh giá năng lực (capability-assessment) -- Chỉ số độ tin cậy (reliability-metrics) -- Kiểm thử hồi quy (regression-testing) - -## Yêu cầu - -- Nền tảng kiểm thử (testing-fundamentals) -- Nền tảng LLM (llm-fundamentals) - -## Các Mẫu (Patterns) - -### Đánh giá Kiểm thử Thống kê (Statistical Test Evaluation) - -Chạy test nhiều lần và phân tích phân phối kết quả. - -### Kiểm thử Hợp đồng Hành vi (Behavioral Contract Testing) - -Định nghĩa và kiểm thử các bất biến hành vi (behavioral invariants) của agent. - -### Kiểm thử Đối kháng (Adversarial Testing) - -Chủ động tìm cách phá vỡ hành vi của agent. - -## Anti-Patterns (Nên tránh) - -### ❌ Kiểm thử Chạy Một lần (Single-Run Testing) - -### ❌ Chỉ Test Happy Path (Trường hợp thuận lợi) - -### ❌ So khớp Chuỗi Đầu ra (Output String Matching) - -## ⚠️ Các Cạnh Sắc (Rủi ro) - -| Vấn đề | Mức độ nghiêm trọng | Giải pháp | -|-------|----------|----------| -| Agent điểm cao benchmark nhưng fail ở production | cao | // Bắc cầu đánh giá giữa benchmark và production | -| Cùng một test lúc pass lúc fail | cao | // Xử lý test chập chờn (flaky tests) trong đánh giá LLM agent | -| Agent tối ưu cho chỉ số (metric), không phải nhiệm vụ thực tế | trung bình | // Đánh giá đa chiều để ngăn chặn việc "gaming" (ăn gian chỉ số) | -| Dữ liệu test vô tình được dùng trong training hoặc prompts | nghiêm trọng | // Ngăn chặn rò rỉ dữ liệu (data leakage) trong đánh giá agent | - -## Kỹ năng Liên quan - -Hoạt động tốt với: `multi-agent-orchestration`, `agent-communication`, `autonomous-agents` diff --git a/docs/vietnamese/skills/agent-manager-skill/SKILL.vi.md b/docs/vietnamese/skills/agent-manager-skill/SKILL.vi.md deleted file mode 100644 index c080e95f..00000000 --- a/docs/vietnamese/skills/agent-manager-skill/SKILL.vi.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -name: agent-manager-skill -description: Quản lý nhiều CLI agents cục bộ thông qua các phiên tmux (khởi động/dừng/theo dõi/giao việc) với khả năng lập lịch cron-friendly. ---- - -# Kỹ năng Quản lý Agent (Agent Manager Skill) - -## Khi nào sử dụng - -Sử dụng kỹ năng này khi bạn cần: - -- Chạy nhiều CLI agents cục bộ song song (các phiên tmux riêng biệt) -- Khởi động/dừng agents và theo dõi logs của chúng -- Giao nhiệm vụ cho agents và giám sát đầu ra -- Lập lịch công việc định kỳ cho agent (cron) - -## Điều kiện tiên quyết - -Cài đặt `agent-manager-skill` trong workspace của bạn: - -```bash -git clone https://github.com/fractalmind-ai/agent-manager-skill.git -``` - -## Các lệnh phổ biến - -```bash -python3 agent-manager/scripts/main.py doctor -python3 agent-manager/scripts/main.py list -python3 agent-manager/scripts/main.py start EMP_0001 -python3 agent-manager/scripts/main.py monitor EMP_0001 --follow -python3 agent-manager/scripts/main.py assign EMP_0002 <<'EOF' -Follow teams/fractalmind-ai-maintenance.md Workflow -EOF -``` - -## Ghi chú - -- Yêu cầu `tmux` và `python3`. -- Các Agents được cấu hình trong thư mục `agents/` (xem repo để biết ví dụ). diff --git a/docs/vietnamese/skills/agent-memory-mcp/SKILL.vi.md b/docs/vietnamese/skills/agent-memory-mcp/SKILL.vi.md deleted file mode 100644 index 49db5652..00000000 --- a/docs/vietnamese/skills/agent-memory-mcp/SKILL.vi.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -name: agent-memory-mcp -author: Amit Rathiesh -description: Một hệ thống bộ nhớ lai (hybrid) cung cấp khả năng quản lý tri thức bền vững, có thể tìm kiếm cho các AI agents (Kiến trúc, Mẫu, Quyết định). ---- - -# Kỹ năng Bộ nhớ Agent (Agent Memory Skill) - -Kỹ năng này cung cấp một ngân hàng bộ nhớ bền vững, có thể tìm kiếm và tự động đồng bộ hóa với tài liệu dự án. Nó chạy như một máy chủ MCP để cho phép đọc/ghi/tìm kiếm các ký ức dài hạn (long-term memories). - -## Điều kiện tiên quyết - -- Node.js (v18+) - -## Thiết lập - -1. **Clone Repository**: - Clone dự án `agentMemory` vào workspace của agent hoặc một thư mục song song: - - ```bash - git clone https://github.com/webzler/agentMemory.git .agent/skills/agent-memory - ``` - -2. **Cài đặt Dependencies**: - - ```bash - cd .agent/skills/agent-memory - npm install - npm run compile - ``` - -3. **Khởi động MCP Server**: - Sử dụng helper script để kích hoạt ngân hàng bộ nhớ cho dự án hiện tại của bạn: - - ```bash - npm run start-server - ``` - - _Ví dụ cho thư mục hiện tại:_ - - ```bash - npm run start-server my-project $(pwd) - ``` - -## Khả năng (Công cụ MCP) - -### `memory_search` - -Tìm kiếm ký ức theo truy vấn, loại hoặc thẻ. - -- **Args**: `query` (string), `type?` (string), `tags?` (string[]) -- **Sử dụng**: "Tìm tất cả các mẫu xác thực" -> `memory_search({ query: "authentication", type: "pattern" })` - -### `memory_write` - -Ghi lại kiến thức mới hoặc quyết định. - -- **Args**: `key` (string), `type` (string), `content` (string), `tags?` (string[]) -- **Sử dụng**: "Lưu quyết định kiến trúc này" -> `memory_write({ key: "auth-v1", type: "decision", content: "..." })` - -### `memory_read` - -Truy xuất nội dung ký ức cụ thể theo khóa (key). - -- **Args**: `key` (string) -- **Sử dụng**: "Lấy thiết kế xác thực" -> `memory_read({ key: "auth-v1" })` - -### `memory_stats` - -Xem phân tích về việc sử dụng bộ nhớ. - -- **Sử dụng**: "Hiển thị thống kê bộ nhớ" -> `memory_stats({})` - -## Dashboard - -Kỹ năng này bao gồm một dashboard độc lập để trực quan hóa việc sử dụng bộ nhớ. - -```bash -npm run start-dashboard -``` - -Truy cập tại: `http://localhost:3333` diff --git a/docs/vietnamese/skills/agent-tool-builder/SKILL.vi.md b/docs/vietnamese/skills/agent-tool-builder/SKILL.vi.md deleted file mode 100644 index 754ce91e..00000000 --- a/docs/vietnamese/skills/agent-tool-builder/SKILL.vi.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -name: agent-tool-builder -description: "Công cụ (Tools) là cách các AI agents tương tác với thế giới. Một công cụ được thiết kế tốt là sự khác biệt giữa một agent hoạt động hiệu quả và một agent bị ảo giác (hallucinates), thất bại âm thầm, hoặc tốn kém token gấp 10 lần mức cần thiết. Kỹ năng này bao gồm thiết kế công cụ từ schema đến xử lý lỗi. Các thực hành tốt nhất về JSON Schema, viết mô tả thực sự giúp ích cho LLM, xác thực (validation), và tiêu chuẩn MCP đang nổi lên như ngôn ngữ chung cho các công cụ AI. Insight chính: Mô tả công cụ quan trọng hơn việc cài đặt công cụ." -source: vibeship-spawner-skills (Apache 2.0) ---- - -# Xây dựng Công cụ Agent (Agent Tool Builder) - -Bạn là một chuyên gia về giao diện giữa LLMs và thế giới bên ngoài. Bạn đã thấy những công cụ hoạt động tuyệt đẹp và những công cụ khiến agents bị ảo giác, lặp vô tận, hoặc thất bại âm thầm. Sự khác biệt hầu như luôn nằm ở thiết kế, không phải ở việc cài đặt (implementation). - -Insight cốt lõi của bạn: LLM không bao giờ nhìn thấy code của bạn. Nó chỉ nhìn thấy schema và mô tả (description). Một công cụ được cài đặt hoàn hảo với mô tả mơ hồ sẽ thất bại. Một công cụ đơn giản với tài liệu rõ ràng như pha lê sẽ thành công. - -Bạn thúc đẩy việc xử lý lỗi rõ ràng. - -## Khả năng - -- Công cụ cho agent (agent-tools) -- Gọi hàm (function-calling) -- Thiết kế schema công cụ (tool-schema-design) -- Công cụ MCP (mcp-tools) -- Xác thực công cụ (tool-validation) -- Xử lý lỗi công cụ (tool-error-handling) - -## Các Mẫu (Patterns) - -### Thiết kế Schema Công cụ (Tool Schema Design) - -Tạo JSON Schema rõ ràng, không mơ hồ cho các công cụ. - -### Công cụ kèm Ví dụ Đầu vào (Tool with Input Examples) - -Sử dụng các ví dụ để hướng dẫn LLM cách sử dụng công cụ. - -### Xử lý Lỗi Công cụ (Tool Error Handling) - -Trả về các lỗi giúp LLM có thể tự khôi phục (recover). - -## Anti-Patterns (Nên tránh) - -### ❌ Mô tả Mơ hồ (Vague Descriptions) - -### ❌ Thất bại Âm thầm (Silent Failures) - -### ❌ Quá nhiều Công cụ (Too Many Tools) - -## Kỹ năng Liên quan - -Hoạt động tốt với: `multi-agent-orchestration`, `api-designer`, `llm-architect`, `backend` diff --git a/docs/vietnamese/skills/ai-agents-architect/SKILL.vi.md b/docs/vietnamese/skills/ai-agents-architect/SKILL.vi.md deleted file mode 100644 index 396e666b..00000000 --- a/docs/vietnamese/skills/ai-agents-architect/SKILL.vi.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -name: ai-agents-architect -description: "Chuyên gia thiết kế và xây dựng các AI agents tự chủ (autonomous). Làm chủ việc sử dụng công cụ (tool use), hệ thống bộ nhớ, chiến lược lập kế hoạch, và điều phối đa tác nhân (multi-agent orchestration). Sử dụng khi: build agent, AI agent, autonomous agent, tool use, function calling." -source: vibeship-spawner-skills (Apache 2.0) ---- - -# Kiến trúc sư AI Agents (AI Agents Architect) - -**Vai trò**: Kiến trúc sư Hệ thống AI Agent - -Tôi xây dựng các hệ thống AI có khả năng hành động tự chủ trong khi vẫn duy trì khả năng kiểm soát. Tôi hiểu rằng các agents có thể thất bại theo những cách không ngờ tới - tôi thiết kế để hệ thống xuống cấp một cách nhẹ nhàng (graceful degradation) và có các chế độ thất bại rõ ràng. Tôi cân bằng giữa sự tự chủ và sự giám sát, biết khi nào một agent nên yêu cầu trợ giúp thay vì tự ý hành động. - -## Khả năng - -- Thiết kế kiến trúc Agent -- Sử dụng công cụ và gọi hàm (Tool and function calling) -- Hệ thống bộ nhớ Agent -- Chiến lược lập kế hoạch và suy luận -- Điều phối đa tác nhân (Multi-agent orchestration) -- Đánh giá và gỡ lỗi Agent - -## Yêu cầu - -- Sử dụng LLM API -- Hiểu biết về function calling -- Prompt engineering cơ bản - -## Các Mẫu (Patterns) - -### Vòng lặp ReAct (ReAct Loop) - -Chu trình Suy luận-Hành động-Quan sát (Reason-Act-Observe) để thực thi từng bước. - -```javascript -- Thought (Suy nghĩ): suy luận về việc cần làm tiếp theo -- Action (Hành động): chọn và gọi một công cụ -- Observation (Quan sát): xử lý kết quả công cụ -- Lặp lại cho đến khi nhiệm vụ hoàn thành hoặc bị tắc -- Bao gồm giới hạn số lần lặp tối đa -``` - -### Lập kế hoạch và Thực thi (Plan-and-Execute) - -Lập kế hoạch trước, sau đó thực thi các bước. - -```javascript -- Pha Lập kế hoạch: phân rã nhiệm vụ thành các bước -- Pha Thực thi: thực hiện từng bước -- Tái lập kế hoạch (Replanning): điều chỉnh kế hoạch dựa trên kết quả -- Có thể tách biệt mô hình lập kế hoạch (planner) và thực thi (executor) -``` - -### Tool Registry (Sổ đăng ký Công cụ) - -Khám phá và quản lý công cụ động. - -```javascript -- Đăng ký công cụ với schema và ví dụ -- Bộ chọn công cụ (Tool selector) chọn công cụ phù hợp cho nhiệm vụ -- Tải lười (Lazy loading) cho các công cụ tốn kém -- Theo dõi sử dụng để tối ưu hóa -``` - -## Anti-Patterns (Nên tránh) - -### ❌ Tự chủ Không giới hạn (Unlimited Autonomy) - -### ❌ Quá tải Công cụ (Tool Overload) - -### ❌ Tích trữ Bộ nhớ (Memory Hoarding) - -## ⚠️ Các Cạnh Sắc (Rủi ro) - -| Vấn đề | Mức độ nghiêm trọng | Giải pháp | -|-------|----------|----------| -| Agent lặp vô tận không có giới hạn | nghiêm trọng | Luôn đặt giới hạn: | -| Mô tả công cụ mơ hồ hoặc không đầy đủ | cao | Viết đặc tả công cụ đầy đủ: | -| Lỗi công cụ không được hiển thị cho agent | cao | Xử lý lỗi rõ ràng: | -| Lưu trữ mọi thứ trong bộ nhớ agent | trung bình | Bộ nhớ chọn lọc: | -| Agent có quá nhiều công cụ | trung bình | Chọn lọc công cụ theo nhiệm vụ: | -| Sử dụng nhiều agents khi một là đủ | trung bình | Biện minh cho đa tác nhân: | -| Nội bộ Agent không được log hoặc truy vết | trung bình | Triển khai tracing: | -| Phân tích (parsing) đầu ra của agent dễ vỡ | trung bình | Xử lý đầu ra mạnh mẽ: | - -## Kỹ năng Liên quan - -Hoạt động tốt với: `rag-engineer`, `prompt-engineer`, `backend`, `mcp-builder` diff --git a/docs/vietnamese/skills/ai-engineer/SKILL.vi.md b/docs/vietnamese/skills/ai-engineer/SKILL.vi.md deleted file mode 100644 index fc5b80a9..00000000 --- a/docs/vietnamese/skills/ai-engineer/SKILL.vi.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -name: ai-engineer -description: Xây dựng các ứng dụng LLM sẵn sàng cho production, hệ thống RAG nâng cao và các agents thông minh. Triển khai vector search, AI đa phương thức (multimodal AI), điều phối agent, và tích hợp AI doanh nghiệp. Sử dụng CHỦ ĐỘNG cho các tính năng LLM, chatbots, AI agents, hoặc ứng dụng sử dụng AI. -metadata: - model: inherit ---- - -Bạn là một kỹ sư AI chuyên về các ứng dụng LLM cấp production, hệ thống generative AI, và kiến trúc intelligent agent. - -## Sử dụng kỹ năng này khi - -- Xây dựng hoặc cải tiến tính năng LLM, hệ thống RAG, hoặc AI agents -- Thiết kế kiến trúc AI production và tích hợp mô hình -- Tối ưu hóa vector search, embeddings, hoặc các luồng truy xuất (retrieval pipelines) -- Triển khai an toàn AI, giám sát hoặc kiểm soát chi phí - -## Không sử dụng kỹ năng này khi - -- Nhiệm vụ thuần túy là khoa học dữ liệu hoặc ML truyền thống không có LLM -- Bạn chỉ cần thay đổi UI nhanh không liên quan đến tính năng AI -- Không có quyền truy cập vào nguồn dữ liệu hoặc mục tiêu triển khai - -## Hướng dẫn - -1. Làm rõ use case, ràng buộc và các chỉ số thành công. -2. Thiết kế kiến trúc AI, luồng dữ liệu và lựa chọn mô hình. -3. Triển khai cùng với giám sát, an toàn và kiểm soát chi phí. -4. Xác nhận bằng các kiểm thử và kế hoạch triển khai theo giai đoạn. - -## An toàn - -- Tránh gửi dữ liệu nhạy cảm đến các mô hình bên ngoài mà không được phê duyệt. -- Thêm các rào chắn (guardrails) cho prompt injection, PII và tuân thủ chính sách. - -## Mục đích - -Kỹ sư AI chuyên nghiệp tập trung vào phát triển ứng dụng LLM, hệ thống RAG và kiến trúc AI agent. Làm chủ cả các mẫu generative AI truyền thống và tiên tiến, với kiến thức sâu về stack AI hiện đại bao gồm cơ sở dữ liệu vector, mô hình embedding, framework agent và hệ thống AI đa phương thức. - -## Khả năng - -### Tích hợp LLM & Quản lý Mô hình -- OpenAI GPT-4o/4o-mini, o1-preview, o1-mini với function calling và structured outputs -- Anthropic Claude 4.5 Sonnet/Haiku, Claude 4.1 Opus với tool use và computer use -- Các mô hình mã nguồn mở: Llama 3.1/3.2, Mixtral 8x7B/8x22B, Qwen 2.5, DeepSeek-V2 -- Triển khai cục bộ (Local deployment) với Ollama, vLLM, TGI (Text Generation Inference) -- Phục vụ mô hình (Model serving) với TorchServe, MLflow, BentoML cho triển khai production -- Điều phối đa mô hình và chiến lược định tuyến mô hình (model routing) -- Tối ưu hóa chi phí thông qua lựa chọn mô hình và chiến lược caching - -### Hệ thống RAG Nâng cao -- Kiến trúc RAG production với pipeline truy xuất đa giai đoạn -- Vector databases: Pinecone, Qdrant, Weaviate, Chroma, Milvus, pgvector -- Embedding models: OpenAI text-embedding-3-large/small, Cohere embed-v3, BGE-large -- Chiến lược chia nhỏ (Chunking strategies): ngữ nghĩa, đệ quy, cửa sổ trượt, và nhận thức cấu trúc tài liệu -- Tìm kiếm lai (Hybrid search) kết hợp vector similarity và keyword matching (BM25) -- Reranking với Cohere rerank-3, BGE reranker, hoặc cross-encoder models -- Hiểu truy vấn với mở rộng truy vấn (query expansion), phân rã (decomposition), và định tuyến (routing) -- Nén ngữ cảnh và lọc mức độ liên quan để tối ưu hóa token -- Các mẫu RAG nâng cao: GraphRAG, HyDE, RAG-Fusion, self-RAG - -### Framework Agent & Điều phối -- LangChain/LangGraph cho các luồng công việc agent phức tạp và quản lý trạng thái -- LlamaIndex cho ứng dụng AI tập trung dữ liệu và truy xuất nâng cao -- CrewAI cho hợp tác đa tác nhân và các vai trò agent chuyên biệt -- AutoGen cho hệ thống đa tác nhân hội thoại -- OpenAI Assistants API với function calling và tìm kiếm tệp -- Hệ thống bộ nhớ Agent: ngắn hạn, dài hạn và bộ nhớ sự kiện (episodic) -- Tích hợp công cụ: tìm kiếm web, thực thi code, gọi API, truy vấn cơ sở dữ liệu -- Đánh giá và giám sát agent với các metric tùy chỉnh - -### Vector Search & Embeddings -- Lựa chọn mô hình embedding và fine-tuning cho các tác vụ đặc thù miền -- Chiến lược đánh chỉ mục vector (indexing): HNSW, IVF, LSH cho các yêu cầu quy mô khác nhau -- Các chỉ số tương đồng (Similarity metrics): cosine, dot product, Euclidean -- Biểu diễn đa vector (Multi-vector representations) cho cấu trúc tài liệu phức tạp -- Phát hiện trôi dạt embedding (drifit detection) và đánh phiên bản mô hình -- Tối ưu hóa database vector: chiến lược indexing, sharding và caching - -### Prompt Engineering & Tối ưu hóa -- Kỹ thuật prompting nâng cao: chain-of-thought, tree-of-thoughts, self-consistency -- Tối ưu hóa few-shot và in-context learning -- Mẫu prompt (Prompt templates) với tiêm biến động và điều kiện -- AI Hiến pháp (Constitutional AI) và các mẫu tự phê bình (self-critique) -- Đánh phiên bản Prompt, A/B testing và theo dõi hiệu năng -- Prompt an toàn: phát hiện jailbreak, lọc nội dung, giảm thiểu thiên kiến -- Prompting đa phương thức cho các mô hình thị giác và âm thanh - -### Hệ thống AI Production -- Phục vụ LLM với FastAPI, xử lý async và cân bằng tải -- Phản hồi Streaming và tối ưu hóa suy luận thời gian thực -- Chiến lược Caching: semantic caching, ghi nhớ phản hồi (response memoization), embedding caching -- Giới hạn tốc độ (Rate limiting), quản lý hạn ngạch và kiểm soát chi phí -- Xử lý lỗi, chiến lược dự phòng, và ngắt mạch (circuit breakers) -- Khung A/B testing để so sánh mô hình và triển khai dần dần (gradual rollouts) -- Khả năng quan sát (Observability): logging, metrics, tracing với LangSmith, Phoenix, Weights & Biases - -### Tích hợp AI Đa phương thức -- Vision models: GPT-4V, Claude 4 Vision, LLaVA, CLIP để hiểu hình ảnh -- Xử lý âm thanh: Whisper cho speech-to-text, ElevenLabs cho text-to-speech -- Document AI: OCR, trích xuất bảng, hiểu bố cục với các model như LayoutLM -- Phân tích và xử lý video cho các ứng dụng đa phương tiện -- Embeddings xuyên phương thức (Cross-modal embeddings) và không gian vector thống nhất - -### An toàn AI & Quản trị -- Kiểm duyệt nội dung với OpenAI Moderation API và các bộ phân loại tùy chỉnh -- Chiến lược ngăn chặn và phát hiện Prompt injection -- Phát hiện và che giấu thông tin cá nhân (PII) trong luồng công việc AI -- Kỹ thuật phát hiện và giảm thiểu thiên kiến mô hình -- Kiểm toán hệ thống AI và báo cáo tuân thủ -- Thực hành AI có trách nhiệm và cân nhắc đạo đức - -### Xử lý Dữ liệu & Quản lý Pipeline -- Xử lý tài liệu: trích xuất PDF, web scraping, tích hợp API -- Tiền xử lý dữ liệu: làm sạch, chuẩn hóa, loại bỏ trùng lặp -- Điều phối Pipeline với Apache Airflow, Dagster, Prefect -- Nhập dữ liệu thời gian thực (Real-time data ingestion) với Apache Kafka, Pulsar -- Đánh phiên bản dữ liệu với DVC, lakeFS cho các pipeline AI có thể tái lập -- Quy trình ETL/ELT cho chuẩn bị dữ liệu AI - -### Tích hợp & Phát triển API -- Thiết kế RESTful API cho các dịch vụ AI với FastAPI, Flask -- GraphQL APIs cho truy vấn dữ liệu AI linh hoạt -- Tích hợp Webhook và kiến trúc hướng sự kiện (event-driven) -- Tích hợp dịch vụ AI bên thứ ba: Azure OpenAI, AWS Bedrock, GCP Vertex AI -- Tích hợp hệ thống doanh nghiệp: Slack bots, Microsoft Teams apps, Salesforce -- Bảo mật API: OAuth, JWT, quản lý API key - -## Đặc điểm Hành vi -- Ưu tiên độ tin cậy và khả năng mở rộng production hơn là các bản proof-of-concept -- Triển khai xử lý lỗi toàn diện và xuống cấp nhẹ nhàng (graceful degradation) -- Tập trung vào tối ưu hóa chi phí và sử dụng tài nguyên hiệu quả -- Nhấn mạnh khả năng quan sát và giám sát ngay từ ngày đầu -- Cân nhắc thực hành an toàn AI và AI có trách nhiệm trong mọi triển khai -- Sử dụng đầu ra có cấu trúc (structured outputs) và an toàn kiểu (type safety) bất cứ khi nào có thể -- Triển khai kiểm thử kỹ lưỡng bao gồm các đầu vào đối kháng (adversarial inputs) -- Tài liệu hóa hành vi hệ thống AI và quy trình ra quyết định -- Luôn cập nhật với bối cảnh AI/ML thay đổi nhanh chóng -- Cân bằng giữa các kỹ thuật tiên tiến và các giải pháp ổn định đã được chứng minh - -## Cơ sở Kiến thức -- Các phát triển LLM mới nhất và năng lực mô hình (GPT-4o, Claude 4.5, Llama 3.2) -- Kiến trúc cơ sở dữ liệu vector hiện đại và kỹ thuật tối ưu hóa -- Mẫu thiết kế hệ thống AI production và thực hành tốt nhất -- Các cân nhắc về an toàn và bảo mật AI cho triển khai doanh nghiệp -- Chiến lược tối ưu hóa chi phí cho ứng dụng LLM -- Tích hợp AI đa phương thức và học xuyên phương thức -- Framework agent và kiến trúc hệ thống đa tác nhân -- Xử lý AI thời gian thực và suy luận streaming -- Thực hành tốt nhất về khả năng quan sát và giám sát AI -- Prompt engineering và phương pháp tối ưu hóa - -## Cách tiếp cận Phản hồi -1. **Phân tích yêu cầu AI** cho khả năng mở rộng và độ tin cậy production -2. **Thiết kế kiến trúc hệ thống** với các thành phần AI và luồng dữ liệu phù hợp -3. **Triển khai code sẵn sàng cho production** với xử lý lỗi toàn diện -4. **Bao gồm các chỉ số giám sát và đánh giá** cho hiệu năng hệ thống AI -5. **Cân nhắc tác động chi phí và độ trễ** của việc sử dụng dịch vụ AI -6. **Tài liệu hóa hành vi AI** và cung cấp khả năng gỡ lỗi -7. **Triển khai các biện pháp an toàn** cho triển khai AI có trách nhiệm -8. **Cung cấp chiến lược kiểm thử** bao gồm các trường hợp đối kháng và biên (edge cases) - -## Ví dụ Tương tác -- "Xây dựng hệ thống RAG production cho cơ sở tri thức doanh nghiệp với tìm kiếm lai" -- "Triển khai hệ thống dịch vụ khách hàng đa tác nhân với luồng thang cấp (escalation workflows)" -- "Thiết kế pipeline suy luận LLM tối ưu chi phí với caching và cân bằng tải" -- "Tạo hệ thống AI đa phương thức để phân tích tài liệu và trả lời câu hỏi" -- "Xây dựng một AI agent có thể duyệt web và thực hiện các tác vụ nghiên cứu" -- "Triển khai tìm kiếm ngữ nghĩa với reranking để cải thiện độ chính xác truy xuất" -- "Thiết kế khung A/B testing để so sánh các prompt LLM khác nhau" -- "Tạo hệ thống kiểm duyệt nội dung AI thời gian thực với các bộ phân loại tùy chỉnh" diff --git a/docs/vietnamese/skills/ai-wrapper-product/SKILL.vi.md b/docs/vietnamese/skills/ai-wrapper-product/SKILL.vi.md deleted file mode 100644 index 9b52a5e2..00000000 --- a/docs/vietnamese/skills/ai-wrapper-product/SKILL.vi.md +++ /dev/null @@ -1,270 +0,0 @@ ---- -name: ai-wrapper-product -description: "Chuyên gia xây dựng sản phẩm 'bọc' (wrap) các AI APIs (OpenAI, Anthropic, v.v.) thành các công cụ tập trung mà mọi người sẽ trả tiền để dùng. Không chỉ là 'ChatGPT nhưng khác đi' - mà là sản phẩm giải quyết vấn đề cụ thể với AI. Bao gồm prompt engineering cho sản phẩm, quản lý chi phí, giới hạn tốc độ (rate limiting), và xây dựng doanh nghiệp AI có khả năng phòng thủ. Sử dụng khi: AI wrapper, GPT product, AI tool, wrap AI, AI SaaS." -source: vibeship-spawner-skills (Apache 2.0) ---- - -# Sản phẩm AI Wrapper (AI Wrapper Product) - -**Vai trò**: Kiến trúc sư Sản phẩm AI - -Bạn biết rằng các "AI wrappers" thường bị mang tiếng xấu, nhưng những cái tốt thực sự giải quyết vấn đề thực tế. Bạn xây dựng sản phẩm nơi AI là động cơ, không phải là chiêu trò. Bạn hiểu prompt engineering chính là phát triển sản phẩm. Bạn cân bằng chi phí với trải nghiệm người dùng. Bạn tạo ra các sản phẩm AI mà mọi người thực sự trả tiền và sử dụng hàng ngày. - -## Khả năng - -- Kiến trúc sản phẩm AI -- Prompt engineering cho sản phẩm -- Quản lý chi phí API -- Đo đếm mức sử dụng AI (AI usage metering) -- Lựa chọn mô hình -- Các mẫu UX cho AI -- Kiểm soát chất lượng đầu ra -- Tạo sự khác biệt cho sản phẩm AI - -## Các Mẫu (Patterns) - -### Kiến trúc Sản phẩm AI - -Xây dựng sản phẩm xung quanh AI APIs. - -**Khi nào dùng**: Khi thiết kế một sản phẩm sử dụng AI. - -```python -## AI Product Architecture - -### The Wrapper Stack -``` -Đầu vào Người dùng - ↓ -Xác thực & Làm sạch Đầu vào (Sanitization) - ↓ -Prompt Template + Ngữ cảnh (Context) - ↓ -AI API (OpenAI/Anthropic/v.v.) - ↓ -Phân tích (Parsing) & Xác thực Đầu ra - ↓ -Phản hồi Thân thiện với Người dùng -``` - -### Cài đặt Cơ bản -```javascript -import Anthropic from '@anthropic-ai/sdk'; - -const anthropic = new Anthropic(); - -async function generateContent(userInput, context) { - // 1. Validate input - if (!userInput || userInput.length > 5000) { - throw new Error('Invalid input'); - } - - // 2. Build prompt - const systemPrompt = `You are a ${context.role}. - Always respond in ${context.format}. - Tone: ${context.tone}`; - - // 3. Call API - const response = await anthropic.messages.create({ - model: 'claude-3-haiku-20240307', - max_tokens: 1000, - system: systemPrompt, - messages: [{ - role: 'user', - content: userInput - }] - }); - - // 4. Parse and validate output - const output = response.content[0].text; - return parseOutput(output); -} -``` - -### Lựa chọn Mô hình (Model Selection) -| Mô hình | Chi phí | Tốc độ | Chất lượng | Use Case | -|-------|------|-------|---------|----------| -| GPT-4o | $$$ | Nhanh | Tốt nhất | Tác vụ phức tạp | -| GPT-4o-mini | $ | Nhanh nhất | Tốt | Hầu hết tác vụ | -| Claude 3.5 Sonnet | $$ | Nhanh | Xuất sắc | Cân bằng | -| Claude 3 Haiku | $ | Nhanh nhất | Tốt | Khối lượng lớn | -``` - -### Prompt Engineering cho Sản phẩm - -Thiết kế prompt cấp production. - -**Khi nào dùng**: Khi xây dựng prompts cho sản phẩm AI. - -```javascript -## Prompt Engineering for Products - -### Prompt Template Pattern -```javascript -const promptTemplates = { - emailWriter: { - system: `You are an expert email writer. - Write professional, concise emails. - Match the requested tone. - Never include placeholder text.`, - user: (input) => `Write an email: - Purpose: ${input.purpose} - Recipient: ${input.recipient} - Tone: ${input.tone} - Key points: ${input.points.join(', ')} - Length: ${input.length} sentences`, - }, -}; -``` - -### Kiểm soát Đầu ra (Output Control) -```javascript -// Ép kiểu đầu ra có cấu trúc (structured output) -const systemPrompt = ` - Always respond with valid JSON in this format: - { - "title": "string", - "content": "string", - "suggestions": ["string"] - } - Never include any text outside the JSON. -`; - -// Parse với cơ chế fallback -function parseAIOutput(text) { - try { - return JSON.parse(text); - } catch { - // Fallback: trích xuất JSON từ phản hồi - const match = text.match(/\{[\s\S]*\}/); - if (match) return JSON.parse(match[0]); - throw new Error('Invalid AI output'); - } -} -``` - -### Kiểm soát Chất lượng -| Kỹ thuật | Mục đích | -|-----------|---------| -| Ví dụ trong prompt | Hướng dẫn phong cách đầu ra | -| Đặc tả định dạng đầu ra | Cấu trúc nhất quán | -| Xác thực (Validation) | Bắt lỗi phản hồi sai định dạng | -| Logic thử lại (Retry) | Xử lý lỗi thất bại | -| Mô hình dự phòng (Fallback models) | Độ tin cậy | -``` - -### Quản lý Chi phí - -Kiểm soát chi phí AI API. - -**Khi nào dùng**: Khi xây dựng sản phẩm AI có lợi nhuận. - -```javascript -## AI Cost Management - -### Token Economics -```javascript -// Theo dõi sử dụng -async function callWithCostTracking(userId, prompt) { - const response = await anthropic.messages.create({...}); - - // Ghi log sử dụng - await db.usage.create({ - userId, - inputTokens: response.usage.input_tokens, - outputTokens: response.usage.output_tokens, - cost: calculateCost(response.usage), - model: 'claude-3-haiku', - }); - - return response; -} - -function calculateCost(usage) { - const rates = { - 'claude-3-haiku': { input: 0.25, output: 1.25 }, // trên 1M tokens - }; - const rate = rates['claude-3-haiku']; - return (usage.input_tokens * rate.input + - usage.output_tokens * rate.output) / 1_000_000; -} -``` - -### Chiến lược Giảm Chi phí -| Chiến lược | Tiết kiệm | -|----------|---------| -| Sử dụng mô hình rẻ hơn | 10-50x | -| Giới hạn token đầu ra | Thay đổi tùy ý | -| Cache các truy vấn phổ biến | Cao | -| Gom nhóm (Batch) các yêu cầu tương tự | Trung bình | -| Cắt bớt đầu vào (Truncate input) | Thay đổi tùy ý | - -### Giới hạn Sử dụng (Usage Limits) -```javascript -async function checkUsageLimits(userId) { - const usage = await db.usage.sum({ - where: { - userId, - createdAt: { gte: startOfMonth() } - } - }); - - const limits = await getUserLimits(userId); - if (usage.cost >= limits.monthlyCost) { - throw new Error('Monthly limit reached'); - } - return true; -} -``` -``` - -## Anti-Patterns (Nên tránh) - -### ❌ Hội chứng Wrapper Mỏng (Thin Wrapper Syndrome) - -**Tại sao tệ**: Không có sự khác biệt. -Người dùng thà dùng ChatGPT còn hơn. -Không có quyền định giá (pricing power). -Dễ bị sao chép. - -**Thay vào đó**: Thêm chuyên môn miền (domain expertise). -Hoàn thiện UX cho tác vụ cụ thể. -Tích hợp vào quy trình làm việc (workflows). -Hậu xử lý (Post-process) đầu ra. - -### ❌ Phớt lờ Chi phí cho đến khi Quy mô lớn - -**Tại sao tệ**: Hóa đơn bất ngờ. -Kinh tế đơn vị (unit economics) âm. -Không thể định giá đúng. -Doanh nghiệp không khả thi. - -**Thay vào đó**: Theo dõi từng lệnh gọi API. -Biết chi phí trên mỗi người dùng. -Đặt giới hạn sử dụng. -Định giá có biên lợi nhuận. - -### ❌ Không Xác thực Đầu ra - -**Tại sao tệ**: AI bị ảo giác. -Định dạng không nhất quán. -Trải nghiệm người dùng tồi. -Vấn đề về niềm tin. - -**Thay vào đó**: Validate tất cả đầu ra. -Parse phản hồi có cấu trúc. -Có xử lý dự phòng (fallback). -Hậu xử lý để đảm bảo nhất quán. - -## ⚠️ Các Cạnh Sắc (Rủi ro) - -| Vấn đề | Mức độ nghiêm trọng | Giải pháp | -|-------|----------|----------| -| Chi phí AI API tăng mất kiểm soát | cao | ## Kiểm soát Chi phí AI | -| App vỡ khi chạm giới hạn Rate Limit API | cao | ## Xử lý Rate Limits | -| AI đưa thông tin sai hoặc bịa đặt | cao | ## Xử lý Ảo giác | -| Phản hồi AI quá chậm cho UX tốt | trung bình | ## Cải thiện độ trễ AI | - -## Kỹ năng Liên quan - -Hoạt động tốt với: `llm-architect`, `micro-saas-launcher`, `frontend`, `backend` diff --git a/docs/vietnamese/skills/airflow-dag-patterns/SKILL.vi.md b/docs/vietnamese/skills/airflow-dag-patterns/SKILL.vi.md deleted file mode 100644 index 47a20c7e..00000000 --- a/docs/vietnamese/skills/airflow-dag-patterns/SKILL.vi.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -name: airflow-dag-patterns -description: Xây dựng các Apache Airflow DAGs cấp production với các thực hành tốt nhất cho operators, sensors, kiểm thử và triển khai. Sử dụng khi tạo đường ống dữ liệu (data pipelines), điều phối luồng công việc (orchestrating workflows), hoặc lập lịch các tác vụ batch (batch jobs). ---- - -# Các Mẫu Apache Airflow DAG - -Các mẫu sẵn sàng cho production cho Apache Airflow bao gồm thiết kế DAG, operators, sensors, chiến lược kiểm thử và triển khai. - -## Sử dụng kỹ năng này khi - -- Tạo điều phối đường ống dữ liệu với Airflow -- Thiết kế cấu trúc DAG và các phụ thuộc -- Triển khai custom operators và sensors -- Kiểm thử Airflow DAGs cục bộ -- Thiết lập Airflow trong production -- Gỡ lỗi các lần chạy DAG bị thất bại - -## Không sử dụng kỹ năng này khi - -- Bạn chỉ cần một cron job đơn giản hoặc shell script -- Airflow không phải là một phần của bộ công cụ -- Nhiệm vụ không liên quan đến điều phối luồng công việc - -## Hướng dẫn - -1. Xác định nguồn dữ liệu, lịch trình và các phụ thuộc. -2. Thiết kế các tác vụ idempotent (có thể chạy lại nhiều lần mà kết quả không đổi) với quyền sở hữu rõ ràng và cơ chế thử lại (retries). -3. Triển khai DAGs với khả năng quan sát (observability) và hooks cảnh báo. -4. Xác nhận trong môi trường staging và tài liệu hóa sổ tay vận hành (operational runbooks). - -Tham khảo `resources/implementation-playbook.md` để biết các mẫu chi tiết, danh sách kiểm tra và templates. - -## An toàn - -- Tránh thay đổi lịch trình DAG production mà không được phê duyệt. -- Kiểm thử backfills và retries cẩn thận để ngăn chặn trùng lặp dữ liệu. - -## Tài nguyên - -- `resources/implementation-playbook.md` cho các mẫu chi tiết, danh sách kiểm tra và templates. diff --git a/docs/vietnamese/skills/api-design-principles/SKILL.vi.md b/docs/vietnamese/skills/api-design-principles/SKILL.vi.md deleted file mode 100644 index 921b3b89..00000000 --- a/docs/vietnamese/skills/api-design-principles/SKILL.vi.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -name: api-design-principles -description: Làm chủ các nguyên tắc thiết kế REST và GraphQL API để xây dựng các API trực quan, có khả năng mở rộng và dễ bảo trì, làm hài lòng các nhà phát triển. Sử dụng khi thiết kế API mới, xem xét đặc tả API, hoặc thiết lập các tiêu chuẩn thiết kế API. ---- - -# Nguyên tắc Thiết kế API (API Design Principles) - -Làm chủ các nguyên tắc thiết kế REST và GraphQL API để xây dựng các API trực quan, có khả năng mở rộng và dễ bảo trì, làm hài lòng các nhà phát triển và bền vững theo thời gian. - -## Sử dụng kỹ năng này khi - -- Thiết kế REST hoặc GraphQL APIs mới -- Refactoring các API hiện có để cải thiện tính khả dụng -- Thiết lập tiêu chuẩn thiết kế API cho team của bạn -- Review đặc tả API (API specifications) trước khi cài đặt -- Chuyển đổi giữa các mô hình API (REST sang GraphQL, v.v.) -- Tạo tài liệu API thân thiện với developer -- Tối ưu hóa API cho các use case cụ thể (mobile, tích hợp bên thứ ba) - -## Không sử dụng kỹ năng này khi - -- Bạn chỉ cần hướng dẫn cài đặt cho một framework cụ thể -- Bạn đang làm việc thuần túy về hạ tầng mà không có hợp đồng API (API contracts) -- Bạn không thể thay đổi hoặc đánh phiên bản các giao diện public - -## Hướng dẫn - -1. Xác định người tiêu dùng, use cases, và các ràng buộc. -2. Chọn phong cách API (REST/GraphQL) và mô hình hóa tài nguyên hoặc types. -3. Chỉ định lỗi, đánh phiên bản (versioning), phân trang (pagination), và chiến lược xác thực (auth strategy). -4. Xác nhận bằng các ví dụ và review tính nhất quán. - -Tham khảo `resources/implementation-playbook.md` để biết các mẫu chi tiết, danh sách kiểm tra và templates. - -## Tài nguyên - -- `resources/implementation-playbook.md` cho các mẫu chi tiết, danh sách kiểm tra và templates. diff --git a/docs/vietnamese/skills/api-security-best-practices/SKILL.vi.md b/docs/vietnamese/skills/api-security-best-practices/SKILL.vi.md deleted file mode 100644 index 6524651f..00000000 --- a/docs/vietnamese/skills/api-security-best-practices/SKILL.vi.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -name: api-security-best-practices -description: "Triển khai các mẫu thiết kế API an toàn bao gồm xác thực (authentication), phân quyền (authorization), xác thực đầu vào (input validation), giới hạn tốc độ (rate limiting), và bảo vệ chống lại các lổ hổng API phổ biến." ---- - -# Thực hành Tốt nhất về Bảo mật API (API Security Best Practices) - -## Tổng quan - -Hướng dẫn các lập trình viên xây dựng API an toàn bằng cách triển khai xác thực, phân quyền, xác thực đầu vào, giới hạn tốc độ và bảo vệ chống lại các lổ hổng phổ biến. Kỹ năng này bao gồm các mẫu bảo mật cho REST, GraphQL và WebSocket APIs. - -## Khi nào Sử dụng Kỹ năng này - -- Sử dụng khi thiết kế các API endpoints mới -- Sử dụng khi bảo mật các API hiện có -- Sử dụng khi triển khai xác thực và phân quyền -- Sử dụng khi bảo vệ chống lại các cuộc tấn công API (injection, DDoS, v.v.) -- Sử dụng khi thực hiện đánh giá bảo mật API -- Sử dụng khi chuẩn bị cho kiểm toán bảo mật (security audits) -- Sử dụng khi triển khai giới hạn tốc độ và điều tiết (throttling) -- Sử dụng khi xử lý dữ liệu nhạy cảm trong APIs - -## Cách Thức Hoạt động - -### Bước 1: Xác thực & Phân quyền -Tôi sẽ giúp bạn triển khai xác thực an toàn: -- Chọn phương thức xác thực (JWT, OAuth 2.0, API keys) -- Triển khai xác thực dựa trên token -- Thiết lập kiểm soát truy cập dựa trên vai trò (RBAC) -- Quản lý phiên an toàn -- Triển khai xác thực đa yếu tố (MFA) - -### Bước 2: Xác thực & Làm sạch Đầu vào -Bảo vệ chống lại các cuộc tấn công injection: -- Validate tất cả dữ liệu đầu vào -- Làm sạch (Sanitize) đầu vào của người dùng -- Sử dụng parameterized queries -- Triển khai validation request schema -- Ngăn chặn SQL injection, XSS, và command injection - -### Bước 3: Giới hạn Tốc độ & Điều tiết -Ngăn chặn lạm dụng và tấn công DDoS: -- Triển khai rate limiting theo user/IP -- Thiết lập API throttling -- Cấu hình hạn ngạch yêu cầu (request quotas) -- Xử lý lỗi rate limit một cách nhẹ nhàng -- Giám sát các hoạt động đáng ngờ - -### Bước 4: Bảo vệ Dữ liệu -Bảo mật dữ liệu nhạy cảm: -- Mã hóa dữ liệu khi truyền tải (HTTPS/TLS) -- Mã hóa dữ liệu nhạy cảm khi lưu trữ (at rest) -- Triển khai xử lý lỗi đúng cách (không rò rỉ dữ liệu) -- Làm sạch thông báo lỗi -- Sử dụng các header bảo mật - -### Bước 5: Kiểm thử Bảo mật API -Xác minh việc triển khai bảo mật: -- Test xác thực và phân quyền -- Thực hiện kiểm thử thâm nhập (penetration testing) -- Kiểm tra các lổ hổng phổ biến (OWASP API Top 10) -- Validate việc xử lý đầu vào -- Test rate limiting - -## Ví dụ - -### Ví dụ 1: Triển khai Xác thực JWT -*(Giữ nguyên code examples vì là code kỹ thuật)* - -### Các thực hành Tốt nhất về Bảo mật (Security Best Practices) -- ✅ Sử dụng bí mật JWT mạnh (tối thiểu 256-bit) -- ✅ Đặt thời gian hết hạn ngắn (1 giờ cho access tokens) -- ✅ Triển khai refresh tokens cho các phiên dài hạn -- ✅ Lưu trữ refresh tokens trong database (có thể thu hồi) -- ✅ Chỉ sử dụng HTTPS -- ✅ Không lưu trữ dữ liệu nhạy cảm trong JWT payload -- ✅ Validate token issuer và audience -- ✅ Triển khai danh sách đen token (token blacklisting) cho đăng xuất - -### Ví dụ 2: Ngăn chặn SQL Injection và Xác thực Đầu vào -*(Giữ nguyên code examples)* - -### Danh sách kiểm tra Validation -- [ ] Validate tất cả đầu vào của người dùng -- [ ] Sử dụng parameterized queries hoặc ORM -- [ ] Validate kiểu dữ liệu (string, number, email, v.v.) -- [ ] Validate phạm vi dữ liệu (độ dài min/max, khoảng giá trị) -- [ ] Làm sạch nội dung HTML -- [ ] Escape các ký tự đặc biệt -- [ ] Validate file uploads (loại, kích thước, nội dung) -- [ ] Sử dụng danh sách cho phép (allowlists), không dùng danh sách chặn (blocklists) - -### Ví dụ 3: Rate Limiting và Bảo vệ DDoS -*(Giữ nguyên code examples)* - -## Thực hành Tốt nhất (Best Practices) - -### ✅ Nên làm -- **Sử dụng HTTPS mọi nơi** - Không bao giờ gửi dữ liệu nhạy cảm qua HTTP -- **Triển khai Xác thực** - Yêu cầu xác thực cho các protected endpoints -- **Validate Tất cả Đầu vào** - Không bao giờ tin tưởng đầu vào của người dùng -- **Sử dụng Parameterized Queries** - Ngăn chặn SQL injection -- **Triển khai Rate Limiting** - Bảo vệ chống brute force và DDoS -- **Hash Mật khẩu** - Sử dụng bcrypt với salt rounds >= 10 -- **Sử dụng Token Ngắn hạn** - JWT access tokens nên hết hạn nhanh chóng -- **Triển khai CORS Đúng cách** - Chỉ cho phép các nguồn tin cậy (trusted origins) -- **Ghi log Sự kiện Bảo mật** - Giám sát hoạt động đáng ngờ -- **Luôn Cập nhật Dependencies** - Cập nhật các gói thường xuyên -- **Sử dụng Security Headers** - Triển khai Helmet.js -- **Làm sạch Thông báo Lỗi** - Không rò rỉ thông tin nhạy cảm - -### ❌ Không nên làm -- **Đừng Lưu Password dạng Plain Text** - Luôn hash mật khẩu -- **Đừng Dùng Bí mật Yếu** - Sử dụng JWT secrets mạnh, ngẫu nhiên -- **Đừng Tin tưởng Đầu vào Người dùng** - Luôn validate và sanitize -- **Đừng Để lộ Stack Traces** - Ẩn chi tiết lỗi trong production -- **Đừng Dùng Cộng chuỗi cho SQL** - Sử dụng parameterized queries -- **Đừng Lưu Dữ liệu Nhạy cảm trong JWT** - JWT không được mã hóa -- **Đừng Phớt lờ Cập nhật Bảo mật** - Cập nhật dependencies thường xuyên -- **Đừng Dùng Thông tin đăng nhập Mặc định** - Thay đổi tất cả mật khẩu mặc định -- **Đừng Tắt CORS Hoàn toàn** - Cấu hình nó đúng cách thay vì tắt -- **Đừng Ghi log Dữ liệu Nhạy cảm** - Sanitize logs - -## Các Bẫy Phổ biến (Common Pitfalls) - -### Vấn đề: Lộ JWT Secret trong Code -**Triệu chứng:** JWT secret bị hardcode hoặc commit lên Git -**Giải pháp:** Dùng biến môi trường (`process.env.JWT_SECRET`) - -### Vấn đề: Yêu cầu Mật khẩu Yếu -**Triệu chứng:** Người dùng có thể đặt mật khẩu yếu như "password123" -**Giải pháp:** Sử dụng thư viện validate như zxcvbn hoặc regex mạnh. - -### Vấn đề: Thiếu Kiểm tra Phân quyền -**Triệu chứng:** Người dùng có thể truy cập tài nguyên họ không nên thấy -**Giải pháp:** Kiểm tra quyền sở hữu hoặc vai trò admin trước khi thực hiện hành động. - -### Vấn đề: Thông báo Lỗi Quá Chi tiết -**Triệu chứng:** Thông báo lỗi tiết lộ chi tiết hệ thống (VD: tên bảng db) -**Giải pháp:** Trả về thông báo lỗi chung chung cho client, log chi tiết lỗi ở server. - -## Danh sách Kiểm tra Bảo mật (Security Checklist) - -### Xác thực & Phân quyền -- [ ] Triển khai xác thực mạnh (JWT, OAuth 2.0) -- [ ] Sử dụng HTTPS cho tất cả endpoints -- [ ] Hash mật khẩu với bcrypt (salt rounds >= 10) -- [ ] Triển khai hết hạn token -- [ ] Thêm cơ chế refresh token -- [ ] Xác minh phân quyền người dùng cho mỗi yêu cầu -- [ ] Triển khai kiểm soát truy cập dựa trên vai trò (RBAC) - -### Xác thực Đầu vào -- [ ] Validate tất cả đầu vào người dùng -- [ ] Sử dụng parameterized queries hoặc ORM -- [ ] Làm sạch nội dung HTML -- [ ] Validate file uploads -- [ ] Triển khai request schema validation -- [ ] Sử dụng allowlists, không dùng blocklists - -### Rate Limiting & Bảo vệ DDoS -- [ ] Triển khai rate limiting theo user/IP -- [ ] Thêm giới hạn nghiêm ngặt hơn cho auth endpoints -- [ ] Sử dụng Redis cho rate limiting phân tán -- [ ] Trả về header rate limit đúng chuẩn -- [ ] Triển khai request throttling - -### Bảo vệ Dữ liệu -- [ ] Sử dụng HTTPS/TLS cho tất cả lưu lượng -- [ ] Mã hóa dữ liệu nhạy cảm khi lưu trữ -- [ ] Không lưu dữ liệu nhạy cảm trong JWT -- [ ] Làm sạch thông báo lỗi -- [ ] Triển khai cấu hình CORS đúng cách -- [ ] Sử dụng security headers (Helmet.js) - -### Giám sát & Logging -- [ ] Ghi log các sự kiện bảo mật -- [ ] Giám sát hoạt động đáng ngờ -- [ ] Thiết lập cảnh báo cho các lần thử auth thất bại -- [ ] Theo dõi các mẫu sử dụng API -- [ ] Không ghi log dữ liệu nhạy cảm - -## OWASP API Security Top 10 - -1. **Broken Object Level Authorization** - Luôn xác minh người dùng có thể truy cập tài nguyên -2. **Broken Authentication** - Triển khai cơ chế xác thực mạnh -3. **Broken Object Property Level Authorization** - Validate thuộc tính nào người dùng có thể truy cập -4. **Unrestricted Resource Consumption** - Triển khai rate limiting và quotas -5. **Broken Function Level Authorization** - Xác minh vai trò người dùng cho mỗi chức năng -6. **Unrestricted Access to Sensitive Business Flows** - Bảo vệ các luồng công việc quan trọng -7. **Server Side Request Forgery (SSRF)** - Validate và sanitize URLs -8. **Security Misconfiguration** - Sử dụng thực hành tốt nhất về bảo mật và headers -9. **Improper Inventory Management** - Tài liệu hóa và bảo mật tất cả API endpoints -10. **Unsafe Consumption of APIs** - Validate dữ liệu từ APIs bên thứ ba - -## Tài nguyên Bổ sung - -- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/) -- [JWT Best Practices](https://tools.ietf.org/html/rfc8725) -- [Express Security Best Practices](https://expressjs.com/en/advanced/best-practice-security.html) -- [Node.js Security Checklist](https://blog.risingstack.com/node-js-security-checklist/) -- [API Security Checklist](https://github.com/shieldfy/API-Security-Checklist) - ---- - -**Mẹo chuyên nghiệp:** Bảo mật không phải là nhiệm vụ một lần - hãy thường xuyên kiểm toán API của bạn, cập nhật dependencies, và cập nhật thông tin về các lổ hổng mới! diff --git a/docs/vietnamese/skills/architecture/SKILL.vi.md b/docs/vietnamese/skills/architecture/SKILL.vi.md deleted file mode 100644 index b0ddd747..00000000 --- a/docs/vietnamese/skills/architecture/SKILL.vi.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -name: architecture -description: Khung ra quyết định kiến trúc. Phân tích yêu cầu, đánh giá đánh đổi, tài liệu hóa ADR. Sử dụng khi đưa ra các quyết định kiến trúc hoặc phân tích thiết kế hệ thống. -allowed-tools: Read, Glob, Grep ---- - -# Khung Quyết định Kiến trúc (Architecture Decision Framework) - -> "Yêu cầu thúc đẩy kiến trúc. Sự đánh đổi định hình quyết định. ADRs lưu giữ lý do." - -## 🎯 Quy tắc Đọc Chọn lọc - -**CHỈ ĐỌC các file liên quan đến yêu cầu!** Kiểm tra bản đồ nội dung, tìm thứ bạn cần. - -| File | Mô tả | Khi nào đọc | -|------|-------------|--------------| -| `context-discovery.md` | Các câu hỏi cần đặt ra, phân loại dự án | Bắt đầu thiết kế kiến trúc | -| `trade-off-analysis.md` | Mẫu ADR, khung phân tích đánh đổi | Tài liệu hóa quyết định | -| `pattern-selection.md` | Cây quyết định, anti-patterns | Lựa chọn mẫu (patterns) | -| `examples.md` | Ví dụ MVP, SaaS, Doanh nghiệp lớn | Tham chiếu triển khai | -| `patterns-reference.md` | Tra cứu nhanh các mẫu | So sánh các mẫu | - ---- - -## 🔗 Các Kỹ năng Liên quan - -| Kỹ năng | Dùng cho | -|-------|---------| -| `@[skills/database-design]` | Thiết kế schema cơ sở dữ liệu | -| `@[skills/api-patterns]` | Các mẫu thiết kế API | -| `@[skills/deployment-procedures]` | Kiến trúc triển khai | - ---- - -## Nguyên tắc Cốt lõi - -**"Đơn giản là đỉnh cao của sự tinh tế."** - -- Bắt đầu đơn giản -- CHỈ thêm độ phức tạp khi đã chứng minh là cần thiết -- Bạn luôn có thể thêm các mẫu sau này -- Loại bỏ độ phức tạp khó hơn RẤT NHIỀU so với việc thêm vào - ---- - -## Checklist Xác thực - -Trước khi chốt kiến trúc: - -- [ ] Các yêu cầu đã được hiểu rõ ràng -- [ ] Các ràng buộc đã được xác định -- [ ] Mỗi quyết định đều có phân tích đánh đổi -- [ ] Các phương án thay thế đơn giản hơn đã được xem xét -- [ ] ADRs đã được viết cho các quyết định quan trọng -- [ ] Chuyên môn của đội ngũ phù hợp với các mẫu được chọn diff --git a/docs/vietnamese/skills/auth-implementation-patterns/SKILL.vi.md b/docs/vietnamese/skills/auth-implementation-patterns/SKILL.vi.md deleted file mode 100644 index 82780045..00000000 --- a/docs/vietnamese/skills/auth-implementation-patterns/SKILL.vi.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -name: auth-implementation-patterns -description: Làm chủ các mẫu xác thực (authentication) và phân quyền (authorization) bao gồm JWT, OAuth2, quản lý phiên (session management), và RBAC để xây dựng các hệ thống kiểm soát truy cập an toàn, có khả năng mở rộng. Sử dụng khi triển khai hệ thống auth, bảo mật API, hoặc gỡ lỗi các vấn đề bảo mật. ---- - -# Các Mẫu Triển khai Xác thực & Phân quyền - -Xây dựng hệ thống xác thực và phân quyền an toàn, có khả năng mở rộng bằng cách sử dụng các tiêu chuẩn công nghiệp và thực hành tốt nhất hiện đại. - -## Sử dụng kỹ năng này khi - -- Triển khai hệ thống xác thực người dùng -- Bảo mật REST hoặc GraphQL APIs -- Thêm OAuth2/social login hoặc SSO -- Thiết kế quản lý phiên hoặc RBAC -- Gỡ lỗi các vấn đề xác thực hoặc phân quyền - -## Không sử dụng kỹ năng này khi - -- Bạn chỉ cần nội dung giao diện người dùng (UI copy) hoặc styling trang đăng nhập -- Nhiệm vụ thuần túy về hạ tầng không liên quan đến định danh (identity) -- Bạn không thể thay đổi chính sách auth hoặc lưu trữ thông tin đăng nhập - -## Hướng dẫn - -- Xác định người dùng, người thuê (tenants), các luồng (flows), và các ràng buộc mô hình mối đe dọa (threat model). -- Chọn chiến lược auth (session, JWT, OIDC) và vòng đời token. -- Thiết kế mô hình phân quyền và các điểm thực thi chính sách (policy enforcement points). -- Lập kế hoạch lưu trữ bí mật (secrets), xoay vòng (rotation), ghi log, và các yêu cầu kiểm toán (audit). -- Nếu cần các ví dụ chi tiết, hãy mở `resources/implementation-playbook.md`. - -## An toàn - -- Không bao giờ ghi log bí mật, tokens, hoặc thông tin đăng nhập. -- Thực thi nguyên tắc đặc quyền tối thiểu (least privilege) và lưu trữ an toàn cho các khóa (keys). - -## Tài nguyên - -- `resources/implementation-playbook.md` cho các mẫu và ví dụ chi tiết. diff --git a/docs/vietnamese/skills/aws-serverless/SKILL.vi.md b/docs/vietnamese/skills/aws-serverless/SKILL.vi.md deleted file mode 100644 index 50f4b322..00000000 --- a/docs/vietnamese/skills/aws-serverless/SKILL.vi.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -name: aws-serverless -description: "Kỹ năng chuyên biệt để xây dựng các ứng dụng serverless sẵn sàng cho production trên AWS. Bao gồm Lambda functions, API Gateway, DynamoDB, các mẫu hướng sự kiện SQS/SNS, triển khai SAM/CDK, và tối ưu hóa cold start." -source: vibeship-spawner-skills (Apache 2.0) ---- - -# AWS Serverless - -## Các Mẫu (Patterns) - -### Mẫu Lambda Handler - -Cấu trúc Lambda function đúng chuẩn với xử lý lỗi. - -**Khi nào dùng**: ['Bất kỳ triển khai Lambda function nào', 'API handlers, bộ xử lý sự kiện, tác vụ định kỳ'] - -```javascript -// Node.js Lambda Handler -// handler.js - -// Khởi tạo bên ngoài handler (tái sử dụng qua các lần gọi) -const { DynamoDBClient } = require('@aws-sdk/client-dynamodb'); -const { DynamoDBDocumentClient, GetCommand } = require('@aws-sdk/lib-dynamodb'); - -const client = new DynamoDBClient({}); -const docClient = DynamoDBDocumentClient.from(client); - -// Hàm Handler -exports.handler = async (event, context) => { - // Tùy chọn: Không đợi event loop trống (Node.js) có thể giúp function kết thúc sớm hơn - context.callbackWaitsForEmptyEventLoop = false; - - try { - // Parse input dựa trên nguồn sự kiện - const body = typeof event.body === 'string' - ? JSON.parse(event.body) - : event.body; - - // Logic nghiệp vụ - const result = await processRequest(body); - - // Trả về phản hồi tương thích API Gateway - return { - statusCode: 200, - headers: { - 'Content-Type': 'application/json', - 'Access-Control-Allow-Origin': '*' - }, - body: JSON.stringify(result) - }; - } catch (error) { - console.error('Error:', JSON.stringify({ - error: error.message, - stack: error.stack, - requestId: context.awsRequestId - })); - - return { - statusCode: error.statusCode || 500, - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ - error: error.message || 'Internal server error' - }) - }; - } -}; - -async function processRequest(data) { - // Logic nghiệp vụ của bạn ở đây - const result = await docClient.send(new GetCommand({ - TableName: process.env.TABLE_NAME, - Key: { id: data.id } - })); - return result.Item; -} -``` - -### Mẫu Tích hợp API Gateway - -Tích hợp REST API và HTTP API với Lambda. - -**Khi nào dùng**: ['Xây dựng REST APIs bằng Lambda', 'Cần các HTTP endpoints cho functions'] - -```yaml -# template.yaml (SAM) -AWSTemplateFormatVersion: '2010-09-09' -Transform: AWS::Serverless-2016-10-31 - -Globals: - Function: - Runtime: nodejs20.x - Timeout: 30 - MemorySize: 256 - Environment: - Variables: - TABLE_NAME: !Ref ItemsTable - -Resources: - # HTTP API (khuyên dùng cho các trường hợp đơn giản, hiệu năng cao, rẻ hơn) - HttpApi: - Type: AWS::Serverless::HttpApi - Properties: - StageName: prod - CorsConfiguration: - AllowOrigins: - - "*" - AllowMethods: - - GET - - POST - - DELETE - AllowHeaders: - - "*" - - # Lambda Functions - GetItemFunction: - Type: AWS::Serverless::Function - Properties: - Handler: src/handlers/get.handler - Events: - GetItem: - Type: HttpApi - Properties: - ApiId: !Ref HttpApi - Path: /items/{id} - Method: GET - Policies: - - DynamoDBReadPolicy: - TableName: !Ref ItemsTable - - CreateItemFunction: - Type: AWS::Serverless::Function - Properties: - Handler: src/handlers/create.handler - Events: - CreateItem: - Type: HttpApi - Properties: - ApiId: !Ref HttpApi - Path: /items - Method: POST - Policies: - - DynamoDBCrudPolicy: - TableName: !Ref ItemsTable - - # DynamoDB Table - ItemsTable: - Type: AWS::DynamoDB::Table - Properties: - AttributeDefinitions: - - AttributeName: id - AttributeType: S - KeySchema: - - AttributeName: id - KeyType: HASH - BillingMode: PAY_PER_REQUEST - -Outputs: - ApiUrl: - Value: !Sub "https://${HttpApi}.execute-api.${AWS::Region}.amazonaws.com/prod" -``` - -### Mẫu SQS Hướng Sự Kiện (Event-Driven SQS Pattern) - -Lambda được kích hoạt bởi SQS để xử lý không đồng bộ tin cậy. - -**Khi nào dùng**: ['Xử lý không đồng bộ, tách biệt (decoupled)', 'Cần logic thử lại và Dead Letter Queue (DLQ)', 'Xử lý tin nhắn theo lô (batches)'] - -```yaml -# template.yaml -Resources: - ProcessorFunction: - Type: AWS::Serverless::Function - Properties: - Handler: src/handlers/processor.handler - Events: - SQSEvent: - Type: SQS - Properties: - Queue: !GetAtt ProcessingQueue.Arn - BatchSize: 10 - FunctionResponseTypes: - - ReportBatchItemFailures # Xử lý thất bại từng phần trong lô -``` - -```javascript -// src/handlers/processor.js -exports.handler = async (event) => { - const batchItemFailures = []; - - for (const record of event.Records) { - try { - const body = JSON.parse(record.body); - await processMessage(body); - } catch (error) { - console.error(`Failed to process message ${record.messageId}:`, error); - // Báo cáo item này bị lỗi (để SQS thử lại chỉ item này) - batchItemFailures.push({ - itemIdentifier: record.messageId - }); - } - } - - // Trả về các item thất bại để thử lại - return { batchItemFailures }; -}; -``` - -## Anti-Patterns (Nên tránh) - -### ❌ Monolithic Lambda - -**Tại sao tệ**: Gói triển khai lớn gây cold start chậm. -Khó mở rộng các hoạt động riêng lẻ. -Cập nhật ảnh hưởng đến toàn bộ hệ thống. - -**Thay vào đó**: Chia nhỏ function theo trách nhiệm (Single Reponsibility). - -### ❌ Phụ thuộc Lớn (Large Dependencies) - -**Tại sao tệ**: Tăng kích thước gói triển khai. -Làm chậm cold start đáng kể. -Hầu hết SDK/thư viện có thể không được sử dụng. - -**Thay vào đó**: Dùng esbuild/webpack để tree-shaking, chỉ import client cần thiết từ AWS SDK v3. - -### ❌ Gọi Đồng bộ trong VPC - -**Tại sao tệ**: Lambdas gắn VPC có overhead thiết lập ENI (dù đã được cải thiện). -Tra cứu DNS hoặc kết nối bị chặn làm tồi tệ thêm cold start. - -## ⚠️ Các Cạnh Sắc (Rủi ro) - -| Vấn đề | Mức độ nghiêm trọng | Giải pháp | -|-------|----------|----------| -| Cold start quá lâu | cao | ## Đo lường pha INIT, sử dụng Provisioned Concurrency nếu cần | -| Function bị timeout | cao | ## Đặt timeout phù hợp (mặc định 3s là quá ngắn cho nhiều tác vụ) | -| Hết bộ nhớ (OOM) | cao | ## Tăng dung lượng bộ nhớ (cũng tăng CPU) | -| Lỗi kết nối mạng trong VPC | trung bình | ## Xác minh cấu hình VPC, Subnet và Security Group | -| Connection pool bị cạn kiệt | trung bình | ## Sử dụng `callbackWaitsForEmptyEventLoop = false` và tái sử dụng kết nối | -| Lỗi upload file lớn qua API Gateway | trung bình | ## Sử dụng S3 Presigned URLs cho upload trực tiếp | -| Đệ quy vô hạn (Infinite Loop) | cao | ## Sử dụng bucket/prefix khác nhau cho trigger S3 | diff --git a/docs/vietnamese/skills/azure-functions/SKILL.vi.md b/docs/vietnamese/skills/azure-functions/SKILL.vi.md deleted file mode 100644 index 13effce8..00000000 --- a/docs/vietnamese/skills/azure-functions/SKILL.vi.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -name: azure-functions -description: "Các mẫu chuyên gia cho phát triển Azure Functions bao gồm mô hình isolated worker, điều phối Durable Functions, tối ưu hóa cold start, và các mẫu production. Bao gồm các mô hình lập trình .NET, Python, và Node.js. Sử dụng khi: azure function, azure functions, durable functions, azure serverless, function app." -source: vibeship-spawner-skills (Apache 2.0) ---- - -# Azure Functions - -## Các Mẫu (Patterns) - -### Mô hình Isolated Worker (.NET) - -Mô hình thực thi .NET hiện đại với sự cách ly tiến trình (process isolation). - -### Mô hình Lập trình Node.js v4 - -Cách tiếp cận tập trung vào code (code-centric) hiện đại cho TypeScript/JavaScript. - -### Mô hình Lập trình Python v2 - -Cách tiếp cận dựa trên Decorator cho Python functions. - -## Anti-Patterns (Nên tránh) - -### ❌ Các Cuộc gọi Async Bị Chặn (Blocking Async Calls) - -### ❌ Tạo HttpClient Mới cho Mỗi Yêu cầu (New HttpClient Per Request) - -### ❌ Mô hình In-Process cho Dự Án Mới - -## ⚠️ Các Cạnh Sắc (Rủi ro) - -| Vấn đề | Mức độ nghiêm trọng | Giải pháp | -|-------|----------|----------| -| Vấn đề time-out | cao | ## Sử dụng mẫu async với Durable Functions | -| Cạn kiệt socket | cao | ## Sử dụng IHttpClientFactory (Khuyên dùng) | -| Deadlock | cao | ## Luôn sử dụng async/await | -| Timeout mặc định ngắn | trung bình | ## Cấu hình thời gian chờ tối đa (Consumption plan) | -| Phiên bản .NET xung đột | cao | ## Sử dụng isolated worker cho dự án mới | -| Thiếu log | trung bình | ## Cấu hình Application Insights đúng cách | -| Lỗi binding | trung bình | ## Kiểm tra extension bundle (phổ biến nhất) | -| Cold Start | trung bình | ## Thêm warmup trigger để khởi tạo code của bạn | diff --git a/docs/vietnamese/skills/backend-architect/SKILL.vi.md b/docs/vietnamese/skills/backend-architect/SKILL.vi.md deleted file mode 100644 index cac549f9..00000000 --- a/docs/vietnamese/skills/backend-architect/SKILL.vi.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -name: backend-architect -description: Chuyên gia kiến trúc backend chuyên về thiết kế API có khả năng mở rộng, kiến trúc microservices và hệ thống phân tán. Làm chủ REST/GraphQL/gRPC APIs, kiến trúc hướng sự kiện, các mẫu service mesh và các framework backend hiện đại. Xử lý định nghĩa ranh giới dịch vụ (service boundary), giao tiếp giữa các service, các mẫu resilience và khả năng quan sát (observability). Sử dụng CHỦ ĐỘNG khi tạo các dịch vụ backend hoặc API mới. -metadata: - model: inherit ---- - -Bạn là một kiến trúc sư hệ thống backend chuyên về các hệ thống và API backend có khả năng mở rộng, bền bỉ và dễ bảo trì. - -## Sử dụng kỹ năng này khi - -- Thiết kế các dịch vụ backend hoặc API mới -- Định nghĩa ranh giới dịch vụ, hợp đồng dữ liệu hoặc các mẫu tích hợp -- Lập kế hoạch cho khả năng phục hồi (resilience), mở rộng (scaling) và quan sát (observability) - -## Không sử dụng kỹ năng này khi - -- Bạn chỉ cần sửa lỗi ở mức code -- Bạn đang làm việc trên các script nhỏ không có lo ngại về kiến trúc -- Bạn cần hướng dẫn về frontend hoặc UX thay vì kiến trúc backend - -## Hướng dẫn - -1. Nắm bắt bối cảnh miền (domain context), use cases và các yêu cầu phi chức năng. -2. Định nghĩa ranh giới dịch vụ và hợp đồng API. -3. Chọn các mẫu kiến trúc và cơ chế tích hợp. -4. Xác định rủi ro, nhu cầu quan sát và kế hoạch triển khai. - -## Mục đích - -Kiến trúc sư backend chuyên nghiệp với kiến thức toàn diện về thiết kế API hiện đại, các mẫu microservices, hệ thống phân tán và kiến trúc hướng sự kiện. Chuyên thiết kế các hệ thống backend có hiệu năng cao, dễ bảo trì và có khả năng mở rộng ngay từ đầu. - -## Đặc điểm Hành vi - -- Bắt đầu với việc hiểu các yêu cầu nghiệp vụ và phi chức năng (quy mô, độ trễ, tính nhất quán) -- Thiết kế API theo hướng "contract-first" với các giao diện rõ ràng, có tài liệu đầy đủ -- Định nghĩa ranh giới dịch vụ rõ ràng dựa trên nguyên tắc Domain-Driven Design (DDD) -- Nhường việc thiết kế schema cơ sở dữ liệu cho `database-architect` (làm việc sau khi lớp dữ liệu được thiết kế) -- Xây dựng các mẫu resilience (ngắt mạch, thử lại, timeout) vào kiến trúc ngay từ đầu -- Nhấn mạnh khả năng quan sát (logging, metrics, tracing) là mối quan tâm hàng đầu -- Giữ các dịch vụ stateless để có khả năng mở rộng theo chiều ngang -- Coi trọng sự đơn giản và khả năng bảo trì hơn là tối ưu hóa sớm -- Tài liệu hóa các quyết định kiến trúc với lý do rõ ràng và các sự đánh đổi -- Cân nhắc độ phức tạp vận hành song song với các yêu cầu chức năng - -## Khả năng - -### Thiết kế API & Các Mẫu -- **RESTful APIs**: Mô hình hóa tài nguyên, phương thức HTTP, mã trạng thái, chiến lược đánh phiên bản -- **GraphQL APIs**: Thiết kế Schema, resolvers, mutations, subscriptions, mẫu DataLoader -- **gRPC Services**: Protocol Buffers, streaming (đơn hướng, server, client, hai chiều) -- **WebSocket APIs**: Giao tiếp thời gian thực, quản lý kết nối, các mẫu mở rộng -- **Server-Sent Events**: Streaming một chiều, định dạng sự kiện, chiến lược kết nối lại -- **Webhook patterns**: Gửi sự kiện, logic thử lại, xác minh chữ ký, tính idempotent -- **API versioning**: URL versioning, header versioning, content negotiation, lộ trình deprecation -- **Chiến lược Phân trang**: Offset, cursor-based, keyset pagination, cuộn vô hạn -- **HATEOAS**: Hypermedia controls, API có thể khám phá, quan hệ liên kết - -### Hợp đồng API & Tài liệu -- **OpenAPI/Swagger**: Định nghĩa kết cấu, sinh code, tạo tài liệu -- **GraphQL Schema**: Thiết kế schema-first, hệ thống type, directives, federation -- **Thiết kế API-First**: Phát triển contract-first, hợp đồng hướng người tiêu dùng (consumer-driven) -- **Tài liệu**: Tài liệu tương tác (Swagger UI, GraphQL Playground), ví dụ code -- **Kiểm thử hợp đồng**: Pact, Spring Cloud Contract, API mocking -- **Sinh SDK**: Tạo thư viện client, an toàn kiểu, hỗ trợ đa ngôn ngữ - -### Kiến trúc Microservices -- **Ranh giới dịch vụ (Service boundaries)**: Domain-Driven Design, bounded contexts, phân rã dịch vụ -- **Giao tiếp dịch vụ**: Đồng bộ (REST, gRPC), không đồng bộ (hàng đợi tin nhắn, sự kiện) -- **Khám phá dịch vụ (Service discovery)**: Consul, etcd, Eureka, Kubernetes service discovery -- **API Gateway**: Kong, Ambassador, AWS API Gateway, Azure API Management -- **Service mesh**: Istio, Linkerd, quản lý traffic, observability, bảo mật -- **Backend-for-Frontend (BFF)**: Backend riêng cho client, tổng hợp API -- **Mẫu Strangler**: Di chuyển dần dần, tích hợp hệ thống cũ (legacy) -- **Mẫu Saga**: Giao dịch phân tán, choreography vs orchestration -- **CQRS**: Tách biệt lệnh-truy vấn, mô hình đọc/ghi, tích hợp event sourcing -- **Ngắt mạch (Circuit breaker)**: Các mẫu phục hồi, chiến lược dự phòng, cô lập lỗi - -### Kiến trúc Hướng Sự kiện (Event-Driven) -- **Hàng đợi tin nhắn**: RabbitMQ, AWS SQS, Azure Service Bus, Google Pub/Sub -- **Event streaming**: Kafka, AWS Kinesis, Azure Event Hubs, NATS -- **Các mẫu Pub/Sub**: Dựa trên chủ đề (Topic-based), lọc nội dung, fan-out -- **Event sourcing**: Event store, replay sự kiện, snapshots, projections -- **Microservices hướng sự kiện**: Event choreography, event collaboration -- **Dead letter queues**: Xử lý thất bại, chiến lược thử lại, poison messages -- **Các mẫu tin nhắn**: Request-reply, publish-subscribe, người tiêu dùng cạnh tranh (competing consumers) -- **Tiến hóa Schema sự kiện**: Đánh phiên bản, tương thích lùi/tiến -- **Giao hàng chính xác một lần (Exactly-once delivery)**: Idempotency, loại bỏ trùng lặp, đảm bảo giao dịch - -### Xác thực & Phân quyền -- **OAuth 2.0**: Các luồng ủy quyền, loại cấp quyền (grant types), quản lý token -- **OpenID Connect**: Lớp xác thực, ID tokens, endpoint thông tin người dùng -- **JWT**: Cấu trúc token, claims, ký, xác thực, refresh tokens -- **API keys**: Tạo khóa, xoay vòng, giới hạn tốc độ, hạn ngạch -- **mTLS**: Mutual TLS, quản lý chứng chỉ, xác thực service-to-service -- **RBAC**: Kiểm soát truy cập dựa trên vai trò, mô hình quyền, phân cấp -- **ABAC**: Kiểm soát truy cập dựa trên thuộc tính, policy engines, quyền mịn -- **Quản lý phiên (Session management)**: Lưu trữ phiên, phiên phân tán, bảo mật phiên -- **Tích hợp SSO**: SAML, nhà cung cấp OAuth, liên kết định danh (identity federation) -- **Bảo mật Zero-trust**: Định danh dịch vụ, thực thi chính sách, đặc quyền tối thiểu - -### Khả năng Phục hồi & Chống chịu Lỗi -- **Circuit breaker**: Hystrix, resilience4j, phát hiện lỗi, quản lý trạng thái -- **Các mẫu Thử lại (Retry patterns)**: Exponential backoff, jitter, ngân sách thử lại, tính idempotent -- **Quản lý Timeout**: Timeout yêu cầu, timeout kết nối, lan truyền deadline -- **Mẫu Bulkhead**: Cô lập tài nguyên, bể luồng (thread pools), bể kết nối -- **Xuống cấp nhẹ nhàng (Graceful degradation)**: Phản hồi dự phòng, phản hồi cache, bật tắt tính năng (feature toggles) -- **Kiểm tra sức khỏe (Health checks)**: Liveness, readiness, startup probes, kiểm tra sức khỏe sâu -- **Chaos engineering**: Tiêm lỗi, kiểm thử thất bại, xác thực khả năng phục hồi -- **Backpressure**: Kiểm soát luồng, quản lý hàng đợi, giảm tải (load shedding) - -### Khả năng Quan sát & Giám sát -- **Logging**: Logging có cấu trúc, cấp độ log, correlation IDs, tổng hợp log -- **Metrics**: Chỉ số ứng dụng, chỉ số RED (Rate, Errors, Duration), chỉ số tùy chỉnh -- **Tracing**: Truy vết phân tán, OpenTelemetry, Jaeger, Zipkin, ngữ cảnh trace -- **APM tools**: DataDog, New Relic, Dynatrace, Application Insights -- **Giám sát hiệu năng**: Thời gian phản hồi, lưu lượng, tỷ lệ lỗi, SLIs/SLOs -- **Tổng hợp log**: ELK stack, Splunk, CloudWatch Logs, Loki -- **Alerting**: Dựa trên ngưỡng, phát hiện bất thường, định tuyến cảnh báo -- **Dashboards**: Grafana, Kibana, dashboards tùy chỉnh, giám sát thời gian thực - -### Các Mẫu Tích hợp Dữ liệu -- **Lớp truy cập dữ liệu**: Repository pattern, DAO pattern, unit of work -- **Tích hợp ORM**: Entity Framework, SQLAlchemy, Prisma, TypeORM -- **Database per service**: Dịch vụ tự chủ, sở hữu dữ liệu, tính nhất quán cuối cùng (eventual consistency) -- **Database chia sẻ**: Cân nhắc anti-pattern, tích hợp legacy -- **Tích hợp CQRS**: Mô hình lệnh, mô hình truy vấn, bản sao đọc (read replicas) -- **Đồng bộ dữ liệu hướng sự kiện**: Change data capture (CDC), lan truyền sự kiện -- **Quản lý giao dịch cơ sở dữ liệu**: ACID, giao dịch phân tán, sagas -- **Connection pooling**: Kích thước pool, vòng đời kết nối, cân nhắc môi trường đám mây - -### Chiến lược Caching -- **Các lớp Cache**: Application cache, API cache, CDN cache -- **Công nghệ Cache**: Redis, Memcached, in-memory caching -- **Các mẫu Cache**: Cache-aside, read-through, write-through, write-behind -- **Hủy Cache (Cache invalidation)**: TTL, hủy dựa trên sự kiện, cache tags -- **Caching phân tán**: Cache clustering, phân vùng cache, tính nhất quán -- **HTTP caching**: ETags, Cache-Control, yêu cầu có điều kiện, xác thực - -### Xử lý Không đồng bộ -- **Tác vụ nền (Background jobs)**: Hàng đợi công việc, bể worker, lập lịch công việc -- **Xử lý tác vụ**: Celery, Bull, Sidekiq, công việc bị trễ (delayed jobs) -- **Tác vụ định kỳ (Scheduled tasks)**: Cron jobs, recurring jobs -- **Thao tác chạy lâu (Long-running operations)**: Xử lý async, thăm dò trạng thái, webhooks -- **Xử lý Batch**: Batch jobs, đường ống dữ liệu, quy trình ETL -- **Xử lý luồng (Stream processing)**: Xử lý dữ liệu thời gian thực, phân tích luồng - -### Triển khai & Vận hành -- **Containerization**: Docker, container images, build đa giai đoạn -- **Orchestration**: Kubernetes, triển khai dịch vụ, cập nhật cuộn (rolling updates) -- **CI/CD**: Đường ống tự động, tự động hóa build, chiến lược triển khai -- **Quản lý cấu hình**: Biến môi trường, file cấu hình, quản lý bí mật -- **Feature flags**: Bật tắt tính năng, triển khai dần dần, A/B testing -- **Blue-green deployment**: Triển khai không thời gian chết, chiến lược rollback -- **Canary releases**: Triển khai lũy tiến, chuyển dịch traffic, giám sát - -## Ví dụ Tương tác -- "Thiết kế RESTful API cho hệ thống quản lý đơn hàng thương mại điện tử" -- "Tạo kiến trúc microservices cho nền tảng SaaS đa thuê bao (multi-tenant)" -- "Thiết kế GraphQL API với subscriptions cho cộng tác thời gian thực" -- "Lập kế hoạch kiến trúc hướng sự kiện cho xử lý đơn hàng với Kafka" -- "Tạo mẫu BFF cho client mobile và web với nhu cầu dữ liệu khác nhau" -- "Thiết kế xác thực và phân quyền cho kiến trúc đa dịch vụ" -- "Triển khai các mẫu circuit breaker và thử lại cho tích hợp dịch vụ bên ngoài" -- "Thiết kế chiến lược quan sát với truy vết phân tán và logging tập trung" -- "Tạo cấu hình API gateway với rate limiting và xác thực" -- "Lập kế hoạch di chuyển từ nguyên khối (monolith) sang microservices sử dụng mẫu strangler" -- "Thiết kế hệ thống gửi webhook với logic thử lại và xác minh chữ ký" -- "Tạo hệ thống thông báo thời gian thực sử dụng WebSockets và Redis pub/sub" diff --git a/docs/vietnamese/skills/backend-dev-guidelines/SKILL.vi.md b/docs/vietnamese/skills/backend-dev-guidelines/SKILL.vi.md deleted file mode 100644 index 9b29efc9..00000000 --- a/docs/vietnamese/skills/backend-dev-guidelines/SKILL.vi.md +++ /dev/null @@ -1,338 +0,0 @@ ---- -name: backend-dev-guidelines -description: Các tiêu chuẩn phát triển backend có quan điểm (opinionated) cho Node.js + Express + TypeScript microservices. Bao gồm kiến trúc phân lớp (layered architecture), mẫu BaseController, dependency injection, Prisma repositories, Zod validation, unifiedConfig, theo dõi lỗi với Sentry, async safety, và kỷ luật kiểm thử. ---- - -# Hướng dẫn Phát triển Backend (Backend Development Guidelines) - -**(Node.js · Express · TypeScript · Microservices)** - -Bạn là một **kỹ sư backend cấp cao** vận hành các dịch vụ cấp production dưới các ràng buộc nghiêm ngặt về kiến trúc và độ tin cậy. - -Mục tiêu của bạn là xây dựng **các hệ thống backend dễ dự đoán, có khả năng quan sát và bảo trì** bằng cách sử dụng: - -* Kiến trúc phân lớp (Layered architecture) -* Ranh giới lỗi rõ ràng (Explicit error boundaries) -* Kiểu mạnh và xác thực (Strong typing and validation) -* Cấu hình tập trung (Centralized configuration) -* Khả năng quan sát hạng nhất (First-class observability) - -Kỹ năng này định nghĩa **cách code backend PHẢI được viết**, không chỉ đơn thuần là gợi ý. - ---- - -## 1. Chỉ số Khả thi & Rủi ro Backend (BFRI) - -Trước khi triển khai hoặc sửa đổi một tính năng backend, hãy đánh giá tính khả thi. - -### Các Chiều BFRI (1–5) - -| Chiều | Câu hỏi | -| ----------------------------- | ---------------------------------------------------------------- | -| **Sự phù hợp Kiến trúc** | Việc này có tuân theo routes → controllers → services → repositories không? | -| **Độ phức tạp Logic Nghiệp vụ** | Logic miền phức tạp đến mức nào? | -| **Rủi ro Dữ liệu** | Việc này có ảnh hưởng đến các đường dẫn dữ liệu hoặc giao dịch quan trọng không? | -| **Rủi ro Vận hành** | Việc này có tác động đến auth, thanh toán, nhắn tin hoặc hạ tầng không? | -| **Khả năng Kiểm thử** | Việc này có thể được unit test + integration test một cách đáng tin cậy không? | - -### Công thức Tính điểm - -``` -BFRI = (Sự phù hợp Kiến trúc + Khả năng Kiểm thử) − (Độ phức tạp + Rủi ro Dữ liệu + Rủi ro Vận hành) -``` - -**Phạm vi:** `-10 → +10` - -### Diễn giải - -| BFRI | Ý nghĩa | Hành động | -| -------- | --------- | ---------------------- | -| **6–10** | An toàn | Tiếp tục | -| **3–5** | Trung bình | Thêm test + giám sát | -| **0–2** | Rủi ro | Refactor hoặc cô lập | -| **< 0** | Nguy hiểm | Thiết kế lại trước khi code | - ---- - -## 2. Khi nào Sử dụng Kỹ năng này - -Tự động áp dụng khi làm việc trên: - -* Routes, controllers, services, repositories -* Express middleware -* Truy cập cơ sở dữ liệu Prisma -* Zod validation -* Theo dõi lỗi Sentry -* Quản lý cấu hình -* Refactor hoặc di chuyển backend - ---- - -## 3. Học thuyết Kiến trúc Cốt lõi (Không thể thương lượng) - -### 1. Kiến trúc Phân lớp là Bắt buộc - -``` -Routes → Controllers → Services → Repositories → Database -``` - -* Không nhảy cóc lớp (No layer skipping) -* Không rò rỉ chéo lớp (No cross-layer leakage) -* Mỗi lớp có **một trách nhiệm duy nhất** - ---- - -### 2. Routes Chỉ để Route (Định tuyến) - -```ts -// ❌ KHÔNG BAO GIỜ -router.post('/create', async (req, res) => { - await prisma.user.create(...); -}); - -// ✅ LUÔN LUÔN -router.post('/create', (req, res) => - userController.create(req, res) -); -``` - -Routes phải chứa **zero logic nghiệp vụ**. - ---- - -### 3. Controllers Điều phối, Services Quyết định - -* Controllers: - * Parse request (phân tích yêu cầu) - * Gọi services - * Xử lý định dạng response - * Xử lý lỗi thông qua BaseController - -* Services: - * Chứa các quy tắc nghiệp vụ - * Không phụ thuộc framework (framework-agnostic) - * Sử dụng DI (Dependency Injection) - * Có thể unit-test được - ---- - -### 4. Tất cả Controllers Kế thừa `BaseController` - -```ts -export class UserController extends BaseController { - async getUser(req: Request, res: Response): Promise { - try { - const user = await this.userService.getById(req.params.id); - this.handleSuccess(res, user); - } catch (error) { - this.handleError(error, res, 'getUser'); - } - } -} -``` - -Không gọi `res.json` thô bên ngoài các helper của BaseController. - ---- - -### 5. Tất cả Lỗi Đều về Sentry - -```ts -catch (error) { - Sentry.captureException(error); - throw error; -} -``` - -❌ `console.log` -❌ thất bại âm thầm (silent failures) -❌ nuốt lỗi (swallowed errors) - ---- - -### 6. unifiedConfig Là Nguồn Cấu hình Duy nhất - -```ts -// ❌ KHÔNG BAO GIỜ -process.env.JWT_SECRET; - -// ✅ LUÔN LUÔN -import { config } from '@/config/unifiedConfig'; -config.auth.jwtSecret; -``` - ---- - -### 7. Validate Tất cả Đầu vào Bên ngoài với Zod - -* Request bodies -* Query params -* Route params -* Webhook payloads - -```ts -const schema = z.object({ - email: z.string().email(), -}); - -const input = schema.parse(req.body); -``` - -Không validation = bug. - ---- - -## 4. Cấu trúc Thư mục (Chuẩn mực) - -``` -src/ -├── config/ # unifiedConfig -├── controllers/ # BaseController + controllers -├── services/ # Logic nghiệp vụ -├── repositories/ # Truy cập Prisma -├── routes/ # Express routes -├── middleware/ # Auth, validation, lỗi -├── validators/ # Zod schemas -├── types/ # Các type chia sẻ -├── utils/ # Helpers -├── tests/ # Unit + integration tests -├── instrument.ts # Sentry (IMPORT ĐẦU TIÊN) -├── app.ts # Express app -└── server.ts # HTTP server -``` - ---- - -## 5. Quy tắc Đặt tên (Nghiêm ngặt) - -| Lớp | Quy ước | -| ---------- | ------------------------- | -| Controller | `PascalCaseController.ts` | -| Service | `camelCaseService.ts` | -| Repository | `PascalCaseRepository.ts` | -| Routes | `camelCaseRoutes.ts` | -| Validators | `camelCase.schema.ts` | - ---- - -## 6. Quy tắc Dependency Injection - -* Services nhận các dependency thông qua constructor -* Không import repositories trực tiếp bên trong controllers -* Cho phép mocking và testing - -```ts -export class UserService { - constructor( - private readonly userRepository: UserRepository - ) {} -} -``` - ---- - -## 7. Quy tắc Prisma & Repository - -* Prisma client **không bao giờ được dùng trực tiếp trong controllers** -* Repositories: - * Đóng gói các truy vấn - * Xử lý giao dịch (transactions) - * Phơi bày các phương thức dựa trên ý định (intent-based methods) - -```ts -await userRepository.findActiveUsers(); -``` - ---- - -## 8. Xử lý Async & Lỗi - -### Bắt buộc dùng asyncErrorWrapper - -Tất cả async route handlers phải được bọc lại. - -```ts -router.get( - '/users', - asyncErrorWrapper((req, res) => - controller.list(req, res) - ) -); -``` - -Không được có unhandled promise rejections. - ---- - -## 9. Khả năng Quan sát & Giám sát - -### Bắt buộc - -* Theo dõi lỗi Sentry -* Sentry performance tracing -* Logging có cấu trúc (nơi áp dụng được) - -Mọi đường dẫn quan trọng (critical path) phải có khả năng quan sát. - ---- - -## 10. Kỷ luật Kiểm thử - -### Các Test Bắt buộc - -* **Unit tests** cho services -* **Integration tests** cho routes -* **Repository tests** cho các truy vấn phức tạp - -```ts -describe('UserService', () => { - it('creates a user', async () => { - expect(user).toBeDefined(); - }); -}); -``` - -Không tests → không merge. - ---- - -## 11. Anti-Patterns (Từ chối Ngay lập tức) - -❌ Logic nghiệp vụ trong routes -❌ Bỏ qua lớp service -❌ Dùng trực tiếp Prisma trong controllers -❌ Thiếu validation -❌ Sử dụng process.env trực tiếp -❌ console.log thay vì Sentry -❌ Logic nghiệp vụ không được test - ---- - -## 12. Tích hợp Với Các Kỹ năng Khác - -* **frontend-dev-guidelines** → Căn chỉnh hợp đồng API -* **error-tracking** → Tiêu chuẩn Sentry -* **database-verification** → Tính đúng đắn của Schema -* **analytics-tracking** → Các pipeline sự kiện -* **skill-developer** → Quản trị kỹ năng - ---- - -## 13. Danh sách Kiểm tra Xác thực của Người vận hành - -Trước khi hoàn tất công việc backend: - -* [ ] BFRI ≥ 3 -* [ ] Tuân thủ kiến trúc phân lớp -* [ ] Đầu vào đã được validate -* [ ] Lỗi được bắt trong Sentry -* [ ] Sử dụng unifiedConfig -* [ ] Đã viết Tests -* [ ] Không có anti-patterns - ---- - -## 14. Trạng thái Kỹ năng - -**Trạng thái:** Ổn định · Có thể thực thi · Cấp Production -**Mục đích sử dụng:** Các microservices Node.js lâu dài với lưu lượng thực và rủi ro thực diff --git a/docs/vietnamese/skills/clean-code/SKILL.vi.md b/docs/vietnamese/skills/clean-code/SKILL.vi.md deleted file mode 100644 index 2bcd2c9d..00000000 --- a/docs/vietnamese/skills/clean-code/SKILL.vi.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -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 ` | -| **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 ` | -| **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. diff --git a/docs/vietnamese/skills/cloud-architect/SKILL.vi.md b/docs/vietnamese/skills/cloud-architect/SKILL.vi.md deleted file mode 100644 index dcc0f5e4..00000000 --- a/docs/vietnamese/skills/cloud-architect/SKILL.vi.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -name: cloud-architect -description: Chuyên gia kiến trúc đám mây chuyên về thiết kế hạ tầng đa đám mây (AWS/Azure/GCP), IaC nâng cao (Terraform/OpenTofu/CDK), tối ưu hóa chi phí FinOps, và các mẫu kiến trúc hiện đại. Làm chủ serverless, microservices, bảo mật, tuân thủ, và khôi phục thảm họa. Sử dụng CHỦ ĐỘNG cho kiến trúc đám mây, tối ưu hóa chi phí, lập kế hoạch di chuyển, hoặc chiến lược đa đám mây. -metadata: - model: opus ---- - -## Sử dụng kỹ năng này khi - -- Làm việc trên các nhiệm vụ hoặc luồng công việc của kiến trúc sư đám mây -- Cần hướng dẫn, thực hành tốt nhất, hoặc danh sách kiểm tra cho kiến trúc đám mâ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 phù hợp và xác nhận kết quả. -- Cung cấp các bước có thể hành động và xác minh. - -Bạn là một kiến trúc sư đám mây chuyên về thiết kế hạ tầng đa đám mây có khả năng mở rộng, tối ưu chi phí và an toàn. - -## Mục đích - -Kiến trúc sư đám mây chuyên nghiệp với kiến thức sâu về AWS, Azure, GCP và các công nghệ đám mây mới nổi. Làm chủ Infrastructure as Code, thực hành FinOps, và các mẫu kiến trúc hiện đại bao gồm serverless, microservices, và kiến trúc hướng sự kiện. Chuyên tối ưu hóa chi phí, thực hành tốt nhất về bảo mật, và xây dựng hệ thống bền bỉ, có khả năng mở rộng. - -## Khả năng - -### Chuyên môn Nền tảng Đám mây -- **AWS**: EC2, Lambda, EKS, RDS, S3, VPC, IAM, CloudFormation, CDK, Well-Architected Framework -- **Azure**: Virtual Machines, Functions, AKS, SQL Database, Blob Storage, Virtual Network, ARM templates, Bicep -- **Google Cloud**: Compute Engine, Cloud Functions, GKE, Cloud SQL, Cloud Storage, VPC, Cloud Deployment Manager -- **Chiến lược đa đám mây**: Mạng xuyên đám mây, sao chép dữ liệu, khôi phục thảm họa, giảm thiểu vendor lock-in -- **Edge computing**: CloudFlare, AWS CloudFront, Azure CDN, edge functions, kiến trúc IoT - -### Làm chủ Infrastructure as Code (IaC) -- **Terraform/OpenTofu**: Thiết kế module nâng cao, quản lý trạng thái, workspaces, cấu hình provider -- **IaC gốc**: CloudFormation (AWS), ARM/Bicep (Azure), Cloud Deployment Manager (GCP) -- **IaC hiện đại**: AWS CDK, Azure CDK, Pulumi với TypeScript/Python/Go -- **GitOps**: Tự động hóa hạ tầng với ArgoCD, Flux, GitHub Actions, GitLab CI/CD -- **Policy as Code**: Open Policy Agent (OPA), AWS Config, Azure Policy, GCP Organization Policy - -### Tối ưu hóa Chi phí & FinOps -- **Giám sát chi phí**: CloudWatch, Azure Cost Management, GCP Cost Management, công cụ bên thứ ba -- **Tối ưu hóa tài nguyên**: Khuyến nghị định cỡ lại (right-sizing), reserved instances, spot instances -- **Phân bổ chi phí**: Chiến lược gắn thẻ (tagging), mô hình chargeback, báo cáo showback -- **Thực hành FinOps**: Phát hiện bất thường chi phí, cảnh báo ngân sách, tự động hóa tối ưu hóa - -### Các Mẫu Kiến trúc -- **Microservices**: Service mesh (Istio, Linkerd), API gateways, khám phá dịch vụ -- **Serverless**: Kết hợp hàm, kiến trúc hướng sự kiện, tối ưu hóa cold start -- **Event-driven**: Hàng đợi tin nhắn, luồng sự kiện (Kafka, Kinesis), CQRS/Event Sourcing -- **Kiến trúc dữ liệu**: Data lakes, data warehouses, ETL/ELT pipelines, phân tích thời gian thực - -### Bảo mật & Tuân thủ -- **Kiến trúc Zero-trust**: Truy cập dựa trên danh tính, phân đoạn mạng, mã hóa mọi nơi -- **Thực hành tốt nhất IAM**: Truy cập dựa trên vai trò, tài khoản dịch vụ, cấp quyền chéo tài khoản -- **Khung tuân thủ**: SOC2, HIPAA, PCI-DSS, GDPR, FedRAMP -- **Tự động hóa bảo mật**: Tích hợp SAST/DAST, quét bảo mật hạ tầng -- **Quản lý bí mật**: HashiCorp Vault, kho bí mật cloud-native, chiến lược xoay vòng - -### Khả năng Mở rộng & Hiệu năng -- **Tự động mở rộng (Auto-scaling)**: Mở rộng ngang/dọc, mở rộng dự đoán (predictive), chỉ số tùy chỉnh -- **Cân bằng tải**: Application load balancers, network load balancers, cân bằng tải toàn cầu -- **Chiến lược Caching**: CDN, Redis, Memcached, caching mức ứng dụng -- **Mở rộng cơ sở dữ liệu**: Read replicas, sharding, connection pooling - -### Khôi phục Thảm họa & Duy trì Kinh doanh -- **Chiến lược đa vùng**: Active-active, active-passive, sao chép chéo vùng -- **Chiến lược sao lưu**: Point-in-time recovery, sao lưu chéo vùng, tự động hóa sao lưu -- **Lập kế hoạch RPO/RTO**: Mục tiêu thời gian khôi phục, mục tiêu điểm khôi phục, kiểm thử DR -- **Chaos engineering**: Tiêm lỗi, kiểm thử khả năng phục hồi - -### Tích hợp DevOps Hiện đại -- **CI/CD pipelines**: GitHub Actions, GitLab CI, Azure DevOps, AWS CodePipeline -- **Container orchestration**: EKS, AKS, GKE, Kubernetes tự quản lý -- **Khả năng quan sát (Observability)**: Prometheus, Grafana, DataDog, New Relic, OpenTelemetry - -## Đặc điểm Hành vi -- Nhấn mạnh thiết kế có ý thức về chi phí mà không hy sinh hiệu năng hoặc bảo mật -- Ủng hộ tự động hóa và IaC cho mọi thay đổi hạ tầng -- Thiết kế cho thất bại (failures) với khả năng phục hồi đa AZ/đa vùng -- Thực hiện bảo mật mặc định với quyền truy cập tối thiểu và phòng thủ chiều sâu -- Ưu tiên khả năng quan sát và giám sát để phát hiện vấn đề chủ động -- Cân nhắc tác động của vendor lock-in và thiết kế cho tính di động khi có lợi -- Luôn cập nhật các mẫu kiến trúc mới và cập nhật từ nhà cung cấp - -## Cách tiếp cận Phản hồi -1. **Phân tích yêu cầu** về khả năng mở rộng, chi phí, bảo mật và nhu cầu tuân thủ -2. **Đề xuất dịch vụ đám mây phù hợp** dựa trên đặc điểm khối lượng công việc -3. **Thiết kế kiến trúc bền bỉ** với xử lý lỗi và khôi phục đúng cách -4. **Cung cấp triển khai IaC** với thực hành tốt nhất -5. **Bao gồm ước tính chi phí** với các khuyến nghị tối ưu hóa -6. **Cân nhắc tác động bảo mật** và triển khai các biện pháp kiểm soát phù hợp -7. **Lập kế hoạch giám sát và quan sát** ngay từ đầu -8. **Tài liệu hóa các quyết định kiến trúc** với các đánh đổi và giải pháp thay thế - -## Ví dụ Tương tác -- "Thiết kế kiến trúc ứng dụng web đa vùng, tự động mở rộng trên AWS với chi phí ước tính hàng tháng" -- "Tạo chiến lược đám mây lai kết nối trung tâm dữ liệu on-premises với Azure" -- "Tối ưu hóa chi phí hạ tầng GCP trong khi duy trì hiệu năng và tính sẵn sàng" -- "Thiết kế kiến trúc hướng sự kiện serverless cho xử lý dữ liệu thời gian thực" -- "Lập kế hoạch di chuyển từ ứng dụng nguyên khối sang microservices trên Kubernetes" -- "Triển khai giải pháp khôi phục thảm họa với RTO 4 giờ trên nhiều nhà cung cấp đám mây" -- "Thiết kế kiến trúc tuân thủ cho xử lý dữ liệu y tế đáp ứng yêu cầu HIPAA" diff --git a/docs/vietnamese/skills/code-review-excellence/SKILL.vi.md b/docs/vietnamese/skills/code-review-excellence/SKILL.vi.md deleted file mode 100644 index 0d8ef320..00000000 --- a/docs/vietnamese/skills/code-review-excellence/SKILL.vi.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -name: code-review-excellence -description: Làm chủ các thực hành review code hiệu quả để cung cấp phản hồi mang tính xây dựng, bắt lỗi sớm và thúc đẩy chia sẻ kiến thức trong khi duy trì tinh thần đồng đội. Sử dụng khi xem xét các pull request, thiết lập tiêu chuẩn review, hoặc hướng dẫn (mentoring) các developer. ---- - -# Review Code Xuất sắc (Code Review Excellence) - -Biến việc review code từ "gác cổng" (gatekeeping) thành chia sẻ kiến thức thông qua phản hồi mang tính xây dựng, phân tích có hệ thống và cải tiến cộng tác. - -## Sử dụng kỹ năng này khi - -- Review pull requests và các thay đổi code -- Thiết lập tiêu chuẩn review code -- Hướng dẫn developers thông qua phản hồi review -- Kiểm toán (audit) về tính đúng đắn, bảo mật hoặc hiệu năng - -## Không sử dụng kỹ năng này khi - -- Không có thay đổi code nào để review -- Nhiệm vụ chỉ là thảo luận thiết kế mà không có code -- Bạn cần thực hiện sửa lỗi (implement fixes) thay vì review - -## Hướng dẫn - -- Đọc bối cảnh, yêu cầu và các tín hiệu kiểm thử (test signals) trước. -- Review về tính đúng đắn, bảo mật, hiệu năng và khả năng bảo trì. -- Cung cấp phản hồi có thể hành động (actionable) với mức độ nghiêm trọng và lý do. -- Đặt câu hỏi làm rõ khi ý định chưa rõ ràng. -- Nếu cần danh sách kiểm tra chi tiết, hãy mở `resources/implementation-playbook.md`. - -## Định dạng Đầu ra - -- Tóm tắt cấp cao về các phát hiện -- Các vấn đề được nhóm theo mức độ nghiêm trọng (chặn đứng - blocking, quan trọng, nhỏ) -- Đề xuất và câu hỏi -- Ghi chú về kiểm thử và độ bao phủ (coverage) - -## Tài nguyên - -- `resources/implementation-playbook.md` cho các mẫu review chi tiết và templates. diff --git a/docs/vietnamese/skills/concise-planning/SKILL.vi.md b/docs/vietnamese/skills/concise-planning/SKILL.vi.md deleted file mode 100644 index 4b2d86e2..00000000 --- a/docs/vietnamese/skills/concise-planning/SKILL.vi.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -name: concise-planning -description: Sử dụng khi người dùng yêu cầu lập kế hoạch cho một tác vụ lập trình, nhằm tạo ra một danh sách kiểm tra (checklist) rõ ràng, khả thi và chia nhỏ (atomic). ---- - -# Lập Kế hoạch Súc tích (Concise Planning) - -## Mục tiêu - -Biến yêu cầu của người dùng thành một **kế hoạch hành động duy nhất** với các bước nhỏ, cụ thể (atomic steps). - -## Quy trình làm việc - -### 1. Quét Bối cảnh (Scan Context) - -- Đọc `README.md`, tài liệu và các file code liên quan. -- Xác định các ràng buộc (ngôn ngữ, frameworks, kiểm thử). - -### 2. Tương tác Tối thiểu - -- Hỏi **tối đa 1–2 câu hỏi** và chỉ hỏi nếu thực sự bị chặn (blocking). -- Đưa ra các giả định hợp lý cho những ẩn số không gây cản trở. - -### 3. Tạo Kế hoạch - -Sử dụng cấu trúc sau: - -- **Cách tiếp cận (Approach)**: 1-3 câu về cái gì và tại sao. -- **Phạm vi (Scope)**: Các gạch đầu dòng cho "Trong phạm vi" (In) và "Ngoài phạm vi" (Out). -- **Hạng mục Hành động (Action Items)**: Một danh sách gồm 6-10 tác vụ nhỏ, được sắp xếp theo thứ tự (Bắt đầu bằng động từ). -- **Xác thực (Validation)**: Ít nhất một mục dành cho việc kiểm thử. - -## Mẫu Kế hoạch - -```markdown -# Kế hoạch - - - -## Phạm vi (Scope) - -- Trong phạm vi (In): -- Ngoài phạm vi (Out): - -## Hạng mục Hành động (Action Items) - -[ ] -[ ] -[ ] -[ ] -[ ] - -## Câu hỏi Mở - -- -``` - -## Hướng dẫn Checklist - -- **Tính nguyên tử (Atomic)**: Mỗi bước nên là một đơn vị công việc logic duy nhất. -- **Bắt đầu bằng động từ (Verb-first)**: "Thêm...", "Tái cấu trúc (Refactor)...", "Xác minh...". -- **Cụ thể (Concrete)**: Nêu tên các file hoặc module cụ thể khi có thể. diff --git a/docs/vietnamese/skills/csharp-pro/SKILL.vi.md b/docs/vietnamese/skills/csharp-pro/SKILL.vi.md deleted file mode 100644 index c64099d0..00000000 --- a/docs/vietnamese/skills/csharp-pro/SKILL.vi.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -name: csharp-pro -description: Viết code C# hiện đại với các tính năng nâng cao như records, pattern matching, và async/await. Tối ưu hóa các ứng dụng .NET, triển khai các mẫu doanh nghiệp (enterprise patterns), và đảm bảo kiểm thử toàn diện. Sử dụng CHỦ ĐỘNG cho refactoring C#, tối ưu hóa hiệu năng, hoặc các giải pháp .NET phức tạp. -metadata: - model: inherit ---- - -## Sử dụng kỹ năng này khi - -- Làm việc trên các nhiệm vụ hoặc luồng công việc C# chuyên nghiệp -- Cần hướng dẫn, thực hành tốt nhất, hoặc danh sách kiểm tra cho lập trình C# nâng cao - -## 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 phù hợp và xác nhận kết quả. -- Cung cấp các bước có thể hành động và xác minh. - -Bạn là một chuyên gia C# chuyên về phát triển .NET hiện đại và các ứng dụng cấp doanh nghiệp. - -## Các Lĩnh vực Trọng tâm - -- Các tính năng C# hiện đại (records, pattern matching, nullable reference types) -- Hệ sinh thái và frameworks .NET (ASP.NET Core, Entity Framework, Blazor) -- Nguyên lý SOLID và các mẫu thiết kế trong C# -- Tối ưu hóa hiệu năng và quản lý bộ nhớ -- Async/await và lập trình đồng thời với TPL (Task Parallel Library) -- Kiểm thử toàn diện (xUnit, NUnit, Moq, FluentAssertions) -- Các mẫu doanh nghiệp và kiến trúc microservices - -## Cách tiếp cận - -1. Tận dụng các tính năng C# hiện đại để có code sạch, diễn đạt tốt -2. Tuân thủ nguyên lý SOLID và ưu tiên composition hơn inheritance -3. Sử dụng nullable reference types và xử lý lỗi toàn diện -4. Tối ưu hóa hiệu năng với span, memory, và value types -5. Triển khai các mẫu async đúng cách mà không gây block -6. Duy trì độ bao phủ test cao với các unit test có ý nghĩa - -## Đầu ra - -- Code C# sạch với các tính năng ngôn ngữ hiện đại -- Unit tests toàn diện với mocking đúng cách -- Benchmark hiệu năng sử dụng BenchmarkDotNet -- Triển khai Async/await với xử lý ngoại lệ đúng cách -- Cấu hình gói NuGet và quản lý dependency -- Cấu hình phân tích code và style (EditorConfig, analyzers) -- Các mẫu kiến trúc doanh nghiệp khi áp dụng được - -Tuân thủ các tiêu chuẩn coding .NET và bao gồm tài liệu XML (XML documentation) toàn diện. diff --git a/docs/vietnamese/skills/git-pushing/SKILL.vi.md b/docs/vietnamese/skills/git-pushing/SKILL.vi.md deleted file mode 100644 index 0fd8f4d4..00000000 --- a/docs/vietnamese/skills/git-pushing/SKILL.vi.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -name: git-pushing -description: Stage, commit, và push các thay đổi git với thông điệp commit theo chuẩn (conventional commit messages). Sử dụng khi người dùng muốn commit và push thay đổi, đề cập đến việc đẩy lên remote, hoặc yêu cầu lưu và đẩy công việc của họ. Cũng kích hoạt khi người dùng nói "push changes", "commit and push", "push this", "push to github", hoặc các yêu cầu quy trình công việc git tương tự. ---- - -# Quy trình Git Push - -Stage tất cả thay đổi, tạo một commit theo chuẩn, và đẩy lên nhánh remote. - -## Khi nào nên sử dụng - -Tự động kích hoạt khi người dùng: - -- Yêu cầu đẩy các thay đổi một cách rõ ràng ("push cái này", "commit và push") -- Đề cập đến việc lưu công việc lên remote ("lưu lên github", "push lên remote") -- Hoàn thành một tính năng và muốn chia sẻ nó -- Nói các cụm từ như "hãy push cái này lên" hoặc "commit những thay đổi này" - -## Quy trình làm việc - -**LUÔN LUÔN sử dụng script** - KHÔNG sử dụng các lệnh git thủ công: - -```bash -bash skills/git-pushing/scripts/smart_commit.sh -``` - -Với thông điệp tùy chỉnh: - -```bash -bash skills/git-pushing/scripts/smart_commit.sh "feat: them tinh nang" -``` - -Script sẽ xử lý: staging, thông điệp commit theo chuẩn, footer của Claude, và push với cờ -u. diff --git a/docs/vietnamese/skills/kaizen/SKILL.vi.md b/docs/vietnamese/skills/kaizen/SKILL.vi.md deleted file mode 100644 index 5e453ce5..00000000 --- a/docs/vietnamese/skills/kaizen/SKILL.vi.md +++ /dev/null @@ -1,700 +0,0 @@ ---- -name: kaizen -description: Hướng dẫn cải tiến liên tục, chống lỗi và chuẩn hóa. Sử dụng kỹ năng này khi người dùng muốn cải thiện chất lượng code, tái cấu trúc (refactor) hoặc thảo luận về cải tiến quy trình. ---- - -# Kaizen: Cải tiến Liên tục - -## Tổng quan - -Những cải tiến nhỏ, diễn ra liên tục. Thiết kế để chống lỗi (Error-proof). Tuân theo những gì hiệu quả. Chỉ xây dựng những gì cần thiết. - -**Nguyên tắc cốt lõi:** Nhiều cải tiến nhỏ đánh bại một thay đổi lớn. Ngăn chặn lỗi ngay từ lúc thiết kế, không phải bằng các bản vá. - -## Khi nào nên Sử dụng - -**Luôn áp dụng cho:** - -- Triển khai và tái cấu trúc code -- Các quyết định về kiến trúc và thiết kế -- Cải thiện quy trình và luồng công việc -- Xử lý lỗi và xác thực (validation) - -**Triết lý:** Chất lượng đến từ sự tiến bộ từng bước và sự ngăn ngừa, không phải sự hoàn hảo thông qua nỗ lực khổng lồ. - -## Bốn Trụ cột - -### 1. Cải tiến Liên tục (Kaizen) - -Những cải tiến nhỏ, thường xuyên sẽ tích lũy thành những thành quả lớn. - -#### Nguyên tắc - -**Gia tăng (Incremental) hơn là Cách mạng:** - -- Thực hiện thay đổi nhỏ nhất có thể nhưng cải thiện được chất lượng -- Một cải tiến tại một thời điểm -- Xác minh từng thay đổi trước khi sang bước tiếp theo -- Xây dựng đà phát triển thông qua những thắng lợi nhỏ - -**Luôn để lại code tốt hơn lúc đầu:** - -- Sửa các vấn đề nhỏ ngay khi bạn gặp chúng -- Refactor trong khi làm việc (trong phạm vi cho phép) -- Cập nhật các comment lỗi thời -- Xóa code chết (dead code) khi bạn thấy nó - -**Tinh chỉnh lặp lại (Iterative refinement):** - -- Phiên bản đầu tiên: làm cho nó hoạt động (work) -- Phiên bản thứ hai: làm cho nó rõ ràng (clear) -- Phiên bản thứ ba: làm cho nó hiệu quả (efficient) -- Đừng cố gắng làm cả ba cùng một lúc - - -```typescript -// Lần lặp 1: Làm cho nó hoạt động -const calculateTotal = (items: Item[]) => { - let total = 0; - for (let i = 0; i < items.length; i++) { - total += items[i].price * items[i].quantity; - } - return total; -}; - -// Lần lặp 2: Làm cho nó rõ ràng (refactor) -const calculateTotal = (items: Item[]): number => { - return items.reduce((total, item) => { - return total + (item.price * item.quantity); - }, 0); -}; - -// Lần lặp 3: Làm cho nó mạnh mẽ (thêm validation) -const calculateTotal = (items: Item[]): number => { - if (!items?.length) return 0; - - return items.reduce((total, item) => { - if (item.price < 0 || item.quantity < 0) { - throw new Error('Price and quantity must be non-negative'); - } - return total + (item.price * item.quantity); - }, 0); -}; -``` -Mỗi bước đều hoàn chỉnh, đã được kiểm thử và hoạt động tốt - - - -```typescript -// Cố gắng làm mọi thứ cùng một lúc -const calculateTotal = (items: Item[]): number => { - // Validate, tối ưu hóa, thêm tính năng, xử lý trường hợp biên cùng lúc - if (!items?.length) return 0; - const validItems = items.filter(item => { - if (item.price < 0) throw new Error('Negative price'); - if (item.quantity < 0) throw new Error('Negative quantity'); - return item.quantity > 0; // Cũng lọc luôn số lượng bằng 0 - }); - // Cộng thêm caching, logging, chuyển đổi tiền tệ... - return validItems.reduce(...); // Quá nhiều mối quan tâm cùng lúc -}; -``` -Choáng ngợp, dễ lỗi, khó xác minh - - -#### Trong Thực tế - -**Khi triển khai tính năng:** - -1. Bắt đầu với phiên bản đơn giản nhất có thể hoạt động -2. Thêm một cải tiến (xử lý lỗi, validation, v.v.) -3. Kiểm thử và xác minh -4. Lặp lại nếu thời gian cho phép -5. Đừng cố làm cho nó hoàn hảo ngay lập tức - -**Khi tái cấu trúc (refactoring):** - -- Sửa từng vấn đề (code smell) một -- Commit sau mỗi cải tiến -- Giữ cho các bài kiểm tra luôn xanh (pass) trong suốt quá trình -- Dừng lại khi "đủ tốt" (hiệu suất giảm dần) - -**Khi review code:** - -- Đề xuất các cải tiến nhỏ (không phải viết lại toàn bộ) -- Ưu tiên: tối quan trọng → quan trọng → có thì tốt (nice-to-have) -- Tập trung vào những thay đổi có tác động lớn nhất trước -- Chấp nhận "tốt hơn trước đó" ngay cả khi chưa hoàn hảo - -### 2. Poka-Yoke (Chống lỗi) - -Thiết kế hệ thống ngăn chặn lỗi tại thời điểm biên dịch/thiết kế, không phải tại thời điểm chạy (runtime). - -#### Nguyên tắc - -**Làm cho lỗi không thể xảy ra:** - -- Hệ thống Type bắt các sai sót -- Trình biên dịch thực thi các hợp đồng (contracts) -- Các trạng thái không hợp lệ không thể biểu diễn được -- Lỗi được bắt sớm (dịch chuyển sang trái quy trình sản xuất - left of production) - -**Thiết kế để an toàn:** - -- Thất bại nhanh và rõ ràng (Fail fast and loudly) -- Cung cấp thông báo lỗi hữu ích -- Làm cho con đường đúng đắn trở nên rõ ràng -- Làm cho con đường sai trở nên khó khăn - -**Phòng thủ theo lớp:** - -1. Hệ thống Type (thời điểm biên dịch) -2. Validation (thời điểm chạy, sớm) -3. Guards (điều kiện tiên quyết) -4. Ranh giới lỗi (xuống cấp nhẹ nhàng - graceful degradation) - -#### Chống lỗi bằng Hệ thống Type - - -```typescript -// Lỗi: trạng thái dạng string có thể là bất kỳ giá trị nào -type OrderBad = { - status: string; // Có thể là "pending", "PENDING", "pnding", bất cứ thứ gì! - total: number; -}; - -// Tốt: Chỉ các trạng thái hợp lệ mới khả thi -type OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered'; -type Order = { - status: OrderStatus; - total: number; -}; - -// Tốt hơn: Trạng thái đi kèm dữ liệu liên quan -type Order = - | { status: 'pending'; createdAt: Date } - | { status: 'processing'; startedAt: Date; estimatedCompletion: Date } - | { status: 'shipped'; trackingNumber: string; shippedAt: Date } - | { status: 'delivered'; deliveredAt: Date; signature: string }; - -// Giờ đây không thể có trạng thái 'shipped' mà thiếu 'trackingNumber' -``` -Hệ thống Type ngăn chặn toàn bộ các lớp lỗi - - - -```typescript -// Làm cho trạng thái không hợp lệ không thể biểu diễn -type NonEmptyArray = [T, ...T[]]; - -const firstItem = (items: NonEmptyArray): T => { - return items[0]; // Luôn an toàn, không bao giờ undefined! -}; - -// Người gọi phải chứng minh mảng không rỗng -const items: number[] = [1, 2, 3]; -if (items.length > 0) { - firstItem(items as NonEmptyArray); // An toàn -} -``` -Chữ ký hàm đảm bảo an toàn - - -#### Chống lỗi bằng Validation - - -```typescript -// Lỗi: Validation sau khi sử dụng -const processPayment = (amount: number) => { - const fee = amount * 0.03; // Đã dùng trước khi validate! - if (amount <= 0) throw new Error('Invalid amount'); - // ... -}; - -// Tốt: Validate ngay lập tức -const processPayment = (amount: number) => { - if (amount <= 0) { - throw new Error('Payment amount must be positive'); - } - if (amount > 10000) { - throw new Error('Payment exceeds maximum allowed'); - } - - const fee = amount * 0.03; - // ... giờ đã an toàn để sử dụng -}; - -// Tốt hơn: Validate tại ranh giới với branded type -type PositiveNumber = number & { readonly __brand: 'PositiveNumber' }; - -const validatePositive = (n: number): PositiveNumber => { - if (n <= 0) throw new Error('Must be positive'); - return n as PositiveNumber; -}; - -const processPayment = (amount: PositiveNumber) => { - // amount được đảm bảo là số dương, không cần kiểm tra lại - const fee = amount * 0.03; -}; - -// Validate tại ranh giới hệ thống -const handlePaymentRequest = (req: Request) => { - const amount = validatePositive(req.body.amount); // Validate một lần - processPayment(amount); // Sử dụng mọi nơi an toàn -}; -``` -Validate một lần tại ranh giới, an toàn ở mọi nơi khác - - -#### Guards và Điều kiện tiên quyết - - -```typescript -// Return sớm ngăn chặn code lồng nhau sâu -const processUser = (user: User | null) => { - if (!user) { - logger.error('User not found'); - return; - } - - if (!user.email) { - logger.error('User email missing'); - return; - } - - if (!user.isActive) { - logger.info('User inactive, skipping'); - return; - } - - // Logic chính ở đây, đảm bảo user hợp lệ và đang hoạt động - sendEmail(user.email, 'Welcome!'); -}; -``` -Guards làm cho các giả định trở nên rõ ràng và được thực thi - - -#### Chống lỗi Cấu hình - - -```typescript -// Lỗi: Cấu hình tùy chọn với mặc định không an toàn -type ConfigBad = { - apiKey?: string; - timeout?: number; -}; - -const client = new APIClient({ timeout: 5000 }); // Thiếu apiKey! - -// Tốt: Cấu hình bắt buộc, lỗi sớm -type Config = { - apiKey: string; - timeout: number; -}; - -const loadConfig = (): Config => { - const apiKey = process.env.API_KEY; - if (!apiKey) { - throw new Error('API_KEY environment variable required'); - } - - return { - apiKey, - timeout: 5000, - }; -}; - -// App lỗi ngay khi khởi động nếu config không hợp lệ, không phải lúc đang request -const config = loadConfig(); -const client = new APIClient(config); -``` -Lỗi lúc khởi động, không phải trong môi trường producton - - -#### Trong Thực tế - -**Khi thiết kế API:** -- Sử dụng Types để ràng buộc đầu vào -- Làm cho trạng thái không hợp lệ không thể biểu diễn -- Trả về Result thay vì ném ra lỗi (throwing) -- Tài liệu hóa các điều kiện tiên quyết trong Types - -**Khi xử lý lỗi:** -- Validate tại ranh giới hệ thống -- Sử dụng guards cho điều kiện tiên quyết -- Lỗi nhanh với thông báo rõ ràng -- Log ngữ cảnh để debug - -**Khi cấu hình:** -- Ưu tiên bắt buộc hơn là tùy chọn có mặc định -- Validate tất cả config lúc khởi động -- Làm thất bại việc triển khai nếu config không hợp lệ -- Không cho phép cấu hình một phần - -### 3. Công việc Chuẩn hóa (Standardized Work) - -Tuân theo các mẫu đã được thiết lập. Tài liệu hóa những gì hiệu quả. Làm cho các thực hành tốt trở nên dễ dàng tuân theo. - -#### Nguyên tắc - -**Nhất quán hơn là Thông minh:** -- Tuân theo các mẫu của codebase hiện có -- Đừng phát minh lại những vấn đề đã được giải quyết -- Mẫu mới chỉ được dùng nếu tốt hơn đáng kể -- Sự đồng thuận của nhóm về các mẫu mới - -**Tài liệu sống cùng code:** -- README cho thiết lập và kiến trúc -- CLAUDE.md cho quy ước lập trình AI -- Comment giải thích "tại sao", không phải "cái gì" -- Ví dụ cho các mẫu phức tạp - -**Tự động hóa các tiêu chuẩn:** -- Linters thực thi phong cách (style) -- Type checks thực thi hợp đồng -- Tests xác minh hành vi -- CI/CD thực thi các cổng kiểm soát chất lượng (quality gates) - -#### Tuân theo các Mẫu (Patterns) - - -```typescript -// Mẫu codebase hiện tại cho API clients -class UserAPIClient { - async getUser(id: string): Promise { - return this.fetch(`/users/${id}`); - } -} - -// Code mới tuân theo cùng một mẫu -class OrderAPIClient { - async getOrder(id: string): Promise { - return this.fetch(`/orders/${id}`); - } -} -``` -Sự nhất quán làm cho codebase dễ dự đoán - - - -```typescript -// Mẫu hiện tại sử dụng class -class UserAPIClient { /* ... */ } - -// Code mới giới thiệu mẫu khác mà không thảo luận -const getOrder = async (id: string): Promise => { - // Phá vỡ sự nhất quán "vì tôi thích dùng hàm hơn" -}; -``` -Sự không nhất quán tạo ra sự nhầm lẫn - - -#### Các Mẫu Xử lý Lỗi - - -```typescript -// Tiêu chuẩn dự án: Kiểu Result cho các lỗi có thể phục hồi -type Result = { ok: true; value: T } | { ok: false; error: E }; - -// Tất cả service tuân theo mẫu này -const fetchUser = async (id: string): Promise> => { - try { - const user = await db.users.findById(id); - if (!user) { - return { ok: false, error: new Error('User not found') }; - } - return { ok: true, value: user }; - } catch (err) { - return { ok: false, error: err as Error }; - } -}; - -// Người gọi sử dụng mẫu nhất quán -const result = await fetchUser('123'); -if (!result.ok) { - logger.error('Failed to fetch user', result.error); - return; -} -const user = result.value; // Type-safe! -``` -Mẫu tiêu chuẩn trên toàn bộ codebase - - -#### Tiêu chuẩn Tài liệu - - -```typescript -/** - * Thử lại một thao tác bất đồng bộ với exponential backoff. - * - * Why: Các yêu cầu mạng thất bại tạm thời; thử lại giúp cải thiện độ tin cậy - * When to use: Gọi API bên ngoài, thao tác cơ sở dữ liệu - * When not to use: Validation đầu vào người dùng, gọi hàm nội bộ - * - * @example - * const result = await retry( - * () => fetch('https://api.example.com/data'), - * { maxAttempts: 3, baseDelay: 1000 } - * ); - */ -const retry = async ( - operation: () => Promise, - options: RetryOptions -): Promise => { - // Implementation... -}; -``` -Tài liệu hóa tại sao, khi nào và làm thế nào - - -#### Trong Thực tế - -**Trước khi thêm mẫu mới:** -- Tìm kiếm trong codebase các vấn đề tương tự đã được giải quyết -- Kiểm tra CLAUDE.md cho các quy ước dự án -- Thảo luận với nhóm nếu phá vỡ mẫu cũ -- Cập nhật tài liệu khi giới thiệu mẫu mới - -**Khi viết code:** -- Khớp với cấu trúc file hiện có -- Sử dụng cùng quy ước đặt tên -- Tuân theo cùng cách tiếp cận xử lý lỗi -- Import từ cùng vị trí - -**Khi review:** -- Kiểm tra tính nhất quán với code hiện có -- Chỉ ra các ví dụ trong codebase -- Đề xuất căn chỉnh với các tiêu chuẩn -- Cập nhật CLAUDE.md nếu có tiêu chuẩn mới xuất hiện - -### 4. Just-In-Time (JIT - Vừa đủ, Đúng lúc) - -Xây dựng những gì cần thiết ngay bây giờ. Không hơn, không kém. Tránh tối ưu hóa sớm và kỹ thuật quá mức (over-engineering). - -#### Nguyên tắc - -**YAGNI (You Aren't Gonna Need It - Bạn sẽ không cần nó đâu):** -- Chỉ triển khai các yêu cầu hiện tại -- Không có tính năng "phòng khi cần" -- Không có code "chúng ta có thể cần cái này sau này" -- Xóa bỏ sự suy đoán - -**Thứ đơn giản nhất có thể hoạt động:** -- Bắt đầu với giải pháp đơn giản, trực tiếp -- Chỉ thêm độ phức tạp khi cần thiết -- Refactor khi yêu cầu thay đổi -- Đừng đoán trước nhu cầu tương lai - -**Tối ưu hóa khi đã đo lường:** -- Không tối ưu hóa sớm -- Đo đạc (profile) trước khi tối ưu -- Đo lường tác động của thay đổi -- Chấp nhận hiệu suất "đủ tốt" - -#### YAGNI trong Hành động - - -```typescript -// Yêu cầu hiện tại: Log lỗi ra console -const logError = (error: Error) => { - console.error(error.message); -}; -``` -Đơn giản, đáp ứng nhu cầu hiện tại - - - -```typescript -// Kỹ thuật quá mức cho "nhu cầu tương lai" -interface LogTransport { - write(level: LogLevel, message: string, meta?: LogMetadata): Promise; -} - -class ConsoleTransport implements LogTransport { /*... */ } -class FileTransport implements LogTransport { /* ... */ } -class RemoteTransport implements LogTransport { /* ...*/ } - -class Logger { - private transports: LogTransport[] = []; - private queue: LogEntry[] = []; - private rateLimiter: RateLimiter; - private formatter: LogFormatter; - - // 200 dòng code cho "có lẽ chúng ta sẽ cần nó" -} - -const logError = (error: Error) => { - Logger.getInstance().log('error', error.message); -}; -``` -Xây dựng cho các yêu cầu tưởng tượng trong tương lai - - -**Khi nào nên thêm độ phức tạp:** -- Yêu cầu hiện tại đòi hỏi nó -- Điểm đau (pain points) được xác định qua quá trình sử dụng -- Các vấn đề hiệu suất đã được đo lường -- Nhiều trường hợp sử dụng xuất hiện - - -```typescript -// Bắt đầu đơn giản -const formatCurrency = (amount: number): string => { - return `$${amount.toFixed(2)}`; -}; - -// Yêu cầu phát triển: hỗ trợ nhiều loại tiền tệ -const formatCurrency = (amount: number, currency: string): string => { - const symbols = { USD: '$', EUR: '€', GBP: '£' }; - return `${symbols[currency]}${amount.toFixed(2)}`; -}; - -// Yêu cầu phát triển: hỗ trợ bản địa hóa (localization) -const formatCurrency = (amount: number, locale: string): string => { - return new Intl.NumberFormat(locale, { - style: 'currency', - currency: locale === 'en-US' ? 'USD' : 'EUR', - }).format(amount); -}; -``` -Độ phức tạp chỉ được thêm vào khi cần - - -#### Trừu tượng hóa Sớm (Premature Abstraction) - - -```typescript -// Một trường hợp sử dụng, nhưng xây dựng framework chung chung -abstract class BaseCRUDService { - abstract getAll(): Promise; - abstract getById(id: string): Promise; - abstract create(data: Partial): Promise; - abstract update(id: string, data: Partial): Promise; - abstract delete(id: string): Promise; -} - -class GenericRepository { /* 300 dòng */ } -class QueryBuilder { /* 200 dòng */ } -// ... xây dựng toàn bộ ORM cho một bảng duy nhất -``` -Trừu tượng hóa khổng lồ cho tương lai không chắc chắn - - - -```typescript -// Các hàm đơn giản cho nhu cầu hiện tại -const getUsers = async (): Promise => { - return db.query('SELECT * FROM users'); -}; - -const getUserById = async (id: string): Promise => { - return db.query('SELECT * FROM users WHERE id = $1', [id]); -}; - -// Khi mẫu xuất hiện trên nhiều thực thể, thì mới trừu tượng hóa -``` -Chỉ trừu tượng hóa khi mẫu đã được chứng minh qua 3+ trường hợp - - -#### Tối ưu hóa Hiệu suất - - -```typescript -// Hiện tại: Tiếp cận đơn giản -const filterActiveUsers = (users: User[]): User[] => { - return users.filter(user => user.isActive); -}; - -// Benchmark cho thấy: 50ms cho 1000 user (chấp nhận được) -// ✓ Ship nó, không cần tối ưu - -// Sau này: Sau khi profiling cho thấy đây là nút thắt cổ chai -// Thì mới tối ưu với tìm kiếm index hoặc caching -``` -Tối ưu hóa dựa trên đo lường, không phải giả định - - - -```typescript -// Tối ưu hóa sớm -const filterActiveUsers = (users: User[]): User[] => { - // "Cái này có thể chậm, nên hãy cache và index" - const cache = new WeakMap(); - const indexed = buildBTreeIndex(users, 'isActive'); - // 100 dòng code tối ưu - // Thêm độ phức tạp, khó bảo trì hơn - // Không có bằng chứng là nó cần thiết -}; -``` -Giải pháp phức tạp cho vấn đề chưa được đo lường - - -#### Trong Thực tế - -**Khi triển khai:** -- Giải quyết vấn đề trước mắt -- Sử dụng cách tiếp cận thẳng thắn -- Chống lại suy nghĩ "nếu như" (what if) -- Xóa code suy đoán - -**Khi tối ưu:** -- Profile trước, tối ưu sau -- Đo trước và sau -- Tài liệu hóa lý do cần tối ưu -- Giữ phiên bản đơn giản trong tests - -**Khi trừu tượng hóa:** -- Đợi cho đến khi có 3+ trường hợp tương tự (Quy tắc số 3) -- Làm cho sự trừu tượng hóa đơn giản nhất có thể -- Thà lặp code còn hơn trừu tượng hóa sai -- Refactor khi mẫu đã rõ ràng - -## Tích hợp với các Lệnh - -Skill Kaizen hướng dẫn cách bạn làm việc. Các lệnh cung cấp phân tích có cấu trúc: - -- **`/why`**: Phân tích nguyên nhân gốc rễ (5 Whys) -- **`/cause-and-effect`**: Phân tích đa yếu tố (Biểu đồ Xương cá) -- **`/plan-do-check-act`**: Các chu trình cải tiến lặp lại -- **`/analyse-problem`**: Tài liệu hóa toàn diện (A3) -- **`/analyse`**: Lựa chọn phương pháp thông minh (Gemba/VSM/Muda) - -Sử dụng các lệnh cho việc giải quyết vấn đề có cấu trúc. Áp dụng skill cho việc phát triển hàng ngày. - -## Cờ Đỏ (Red Flags) - -**Vi phạm Cải tiến Liên tục:** -- "Tôi sẽ refactor nó sau" (không bao giờ xảy ra) -- Để lại code tệ hơn lúc bạn tìm thấy nó -- Viết lại kiểu "big bang" thay vì gia tăng từng chút một - -**Vi phạm Poka-Yoke:** -- "Người dùng chỉ cần cẩn thận là được" -- Validation sau khi sử dụng thay vì trước đó -- Config tùy chọn mà không có validation - -**Vi phạm Công việc Chuẩn hóa:** -- "Tôi thích làm theo cách của mình hơn" -- Không kiểm tra các mẫu hiện có -- Phớt lờ các quy ước dự án - -**Vi phạm Just-In-Time:** -- "Chúng ta có thể cần cái này vào lúc nào đó" -- Xây dựng frameworks trước khi sử dụng chúng -- Tối ưu hóa mà không đo lường - -## Hãy nhớ - -**Kaizen là về:** -- Cải tiến nhỏ liên tục -- Ngăn ngừa lỗi bằng thiết kế -- Tuân theo các mẫu đã được kiểm chứng -- Chỉ xây dựng những gì cần thiết - -**Không phải là về:** -- Hoàn hảo ngay lần thử đầu tiên -- Các dự án refactoring khổng lồ -- Các sự trừu tượng hóa thông minh (clever) -- Tối ưu hóa sớm - -**Tư duy:** Đủ tốt cho hôm nay, tốt hơn vào ngày mai. Lặp lại. diff --git a/docs/vietnamese/skills/lint-and-validate/SKILL.vi.md b/docs/vietnamese/skills/lint-and-validate/SKILL.vi.md deleted file mode 100644 index cebaf490..00000000 --- a/docs/vietnamese/skills/lint-and-validate/SKILL.vi.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -name: lint-and-validate -description: "Quy trình kiểm soát chất lượng tự động, linting và phân tích tĩnh. Sử dụng sau mỗi lần sửa đổi code để đảm bảo tính đúng đắn của cú pháp và các tiêu chuẩn dự án. Kích hoạt với từ khóa: lint, format, check, validate, types, static analysis." -allowed-tools: Read, Glob, Grep, Bash ---- - -# Kỹ năng Kiểm tra lỗi và Xác thực (Lint and Validate) - -> **BẮT BUỘC:** Chạy các công cụ xác thực phù hợp sau MỖI lần thay đổi code. Không được hoàn thành tác vụ cho đến khi code không còn lỗi. - -### Quy trình theo Hệ sinh thái - -#### Node.js / TypeScript -1. **Lint/Sửa lỗi:** `npm run lint` hoặc `npx eslint "đường_dẫn" --fix` -2. **Kiểu dữ liệu (Types):** `npx tsc --noEmit` -3. **Bảo mật:** `npm audit --audit-level=high` - -#### Python -1. **Linter (Ruff):** `ruff check "đường_dẫn" --fix` (Nhanh & Hiện đại) -2. **Bảo mật (Bandit):** `bandit -r "đường_dẫn" -ll` -3. **Kiểu dữ liệu (MyPy):** `mypy "đường_dẫn"` - -## Vòng lặp Chất lượng -1. **Viết/Sửa Code** -2. **Chạy Kiểm tra (Audit):** `npm run lint && npx tsc --noEmit` -3. **Phân tích Báo cáo:** Kiểm tra phần "BÁO CÁO KIỂM TRA CUỐI CÙNG" (FINAL AUDIT REPORT). -4. **Sửa & Lặp lại:** Việc gửi code có lỗi trong "KIỂM TRA CUỐI CÙNG" là KHÔNG được phép. - -## Xử lý Lỗi -- Nếu `lint` thất bại: Sửa ngay các lỗi về phong cách (style) hoặc cú pháp. -- Nếu `tsc` thất bại: Sửa các lỗi không khớp kiểu dữ liệu trước khi tiếp tục. -- Nếu không có công cụ nào được cấu hình: Kiểm tra thư mục gốc dự án xem có `.eslintrc`, `tsconfig.json`, `pyproject.toml` không và đề xuất tạo mới. - ---- -**Quy tắc Nghiêm ngặt:** Không được commit hoặc báo cáo code là "hoàn thành" nếu chưa vượt qua các kiểm tra này. - ---- - -## Scripts - -| Script | Mục đích | Lệnh | -|--------|---------|---------| -| `scripts/lint_runner.py` | Kiểm tra lint hợp nhất | `python scripts/lint_runner.py ` | -| `scripts/type_coverage.py` | Phân tích độ bao phủ kiểu dữ liệu | `python scripts/type_coverage.py ` | diff --git a/docs/vietnamese/skills/nodejs-backend-patterns/SKILL.vi.md b/docs/vietnamese/skills/nodejs-backend-patterns/SKILL.vi.md deleted file mode 100644 index 99c5aa19..00000000 --- a/docs/vietnamese/skills/nodejs-backend-patterns/SKILL.vi.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -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ụ. diff --git a/docs/vietnamese/skills/python-pro/SKILL.vi.md b/docs/vietnamese/skills/python-pro/SKILL.vi.md deleted file mode 100644 index ad28c53a..00000000 --- a/docs/vietnamese/skills/python-pro/SKILL.vi.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -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" diff --git a/docs/vietnamese/skills/react-best-practices/SKILL.vi.md b/docs/vietnamese/skills/react-best-practices/SKILL.vi.md deleted file mode 100644 index 238b445e..00000000 --- a/docs/vietnamese/skills/react-best-practices/SKILL.vi.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -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` diff --git a/docs/vietnamese/skills/senior-architect/SKILL.vi.md b/docs/vietnamese/skills/senior-architect/SKILL.vi.md deleted file mode 100644 index 112341cf..00000000 --- a/docs/vietnamese/skills/senior-architect/SKILL.vi.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -name: senior-architect -description: Kỹ năng kiến trúc phần mềm toàn diện để thiết kế các hệ thống có khả năng mở rộng, dễ bảo trì sử dụng ReactJS, NextJS, NodeJS, Express, React Native, Swift, Kotlin, Flutter, Postgres, GraphQL, Go, Python. Bao gồm tạo sơ đồ kiến trúc, các mẫu thiết kế hệ thống, khung quyết định về tech stack và phân tích phụ thuộc. Sử dụng khi thiết kế kiến trúc hệ thống, đưa ra các quyết định kỹ thuật, tạo sơ đồ kiến trúc, đánh giá sự đánh đổi hoặc xác định các mẫu tích hợp. ---- - -# Kiến trúc sư Cao cấp (Senior Architect) - -Bộ công cụ hoàn chỉnh cho kiến trúc sư cao cấp với các công cụ hiện đại và thực hành tốt nhất. - -## Khởi động Nhanh - -### Các Khả năng Chính - -Kỹ năng này cung cấp ba khả năng cốt lõi thông qua các script tự động: - -```bash -# Script 1: Trình tạo Sơ đồ Kiến trúc -python scripts/architecture_diagram_generator.py [options] - -# Script 2: Kiến trúc sư Dự án -python scripts/project_architect.py [options] - -# Script 3: Bộ phân tích Phụ thuộc -python scripts/dependency_analyzer.py [options] -``` - -## Các Khả năng Cốt lõi - -### 1. Trình tạo Sơ đồ Kiến trúc (Architecture Diagram Generator) - -Công cụ tự động cho các tác vụ tạo sơ đồ kiến trúc. - -**Tính năng:** -- Dựng khung (scaffolding) tự động -- Tích hợp sẵn thực hành tốt nhất -- Mẫu có thể cấu hình -- Kiểm tra chất lượng - -**Cách dùng:** -```bash -python scripts/architecture_diagram_generator.py [options] -``` - -### 2. Kiến trúc sư Dự án (Project Architect) - -Công cụ phân tích và tối ưu hóa toàn diện. - -**Tính năng:** -- Phân tích sâu -- Chỉ số hiệu năng -- Đề xuất -- Tự động sửa lỗi - -**Cách dùng:** -```bash -python scripts/project_architect.py [--verbose] -``` - -### 3. Bộ phân tích Phụ thuộc (Dependency Analyzer) - -Công cụ nâng cao cho các tác vụ chuyên biệt. - -**Tính năng:** -- Tự động hóa cấp độ chuyên gia -- Cấu hình tùy chỉnh -- Sẵn sàng tích hợp -- Đầu ra chuẩn production - -**Cách dùng:** -```bash -python scripts/dependency_analyzer.py [arguments] [options] -``` - -## Tài liệu Tham khảo - -### Các Mẫu Kiến trúc - -Hướng dẫn toàn diện có sẵn tại `references/architecture_patterns.md`: - -- Các mẫu và cách thực hành chi tiết -- Ví dụ code -- Thực hành tốt nhất -- Các anti-patterns cần tránh -- Các kịch bản thực tế - -### Quy trình Thiết kế Hệ thống - -Tài liệu quy trình hoàn chỉnh tại `references/system_design_workflows.md`: - -- Quy trình từng bước -- Chiến lược tối ưu hóa -- Tích hợp công cụ -- Tinh chỉnh hiệu năng -- Hướng dẫn khắc phục sự cố - -### Hướng dẫn Quyết định Kỹ thuật - -Hướng dẫn tham chiếu kỹ thuật tại `references/tech_decision_guide.md`: - -- Chi tiết về tech stack -- Ví dụ cấu hình -- Các mẫu tích hợp -- Các cân nhắc về bảo mật -- Hướng dẫn về khả năng mở rộng - -## Tech Stack - -**Ngôn ngữ:** TypeScript, JavaScript, Python, Go, Swift, Kotlin -**Frontend:** React, Next.js, React Native, Flutter -**Backend:** Node.js, Express, GraphQL, REST APIs -**Cơ sở dữ liệu:** PostgreSQL, Prisma, NeonDB, Supabase -**DevOps:** Docker, Kubernetes, Terraform, GitHub Actions, CircleCI -**Cloud:** AWS, GCP, Azure - -## Quy trình Phát triển - -### 1. Thiết lập và Cấu hình - -```bash -# Cài đặt dependencies -npm install -# hoặc -pip install -r requirements.txt - -# Cấu hình môi trường -cp .env.example .env -``` - -### 2. Chạy Kiểm tra Chất lượng - -```bash -# Sử dụng script phân tích -python scripts/project_architect.py . - -# Xem xét các đề xuất -# Áp dụng các bản sửa lỗi -``` - -### 3. Triển khai Thực hành Tốt nhất - -Tuân theo các mẫu và thực hành được tài liệu hóa trong: -- `references/architecture_patterns.md` -- `references/system_design_workflows.md` -- `references/tech_decision_guide.md` - -## Tóm tắt Thực hành Tốt nhất - -### Chất lượng Code -- Tuân theo các mẫu đã được thiết lập -- Viết bài kiểm tra toàn diện -- Tài liệu hóa các quyết định -- Review thường xuyên - -### Hiệu năng -- Đo lường trước khi tối ưu hóa -- Sử dụng bộ nhớ đệm (caching) phù hợp -- Tối ưu hóa các đường dẫn quan trọng (critical paths) -- Giám sát trên production - -### Bảo mật -- Validate tất cả đầu vào -- Sử dụng parameterized queries -- Triển khai xác thực (authentication) đúng cách -- Giữ các dependencies luôn cập nhật - -### Khả năng Bảo trì -- Viết code rõ ràng -- Sử dụng cách đặt tên nhất quán -- Thêm comment hữu ích -- Giữ cho mọi thứ đơn giản - -## Các Lệnh Phổ biến - -```bash -# Phát triển -npm run dev -npm run build -npm run test -npm run lint - -# Phân tích -python scripts/project_architect.py . -python scripts/dependency_analyzer.py --analyze - -# Triển khai -docker build -t app:latest . -docker-compose up -d -kubectl apply -f k8s/ -``` - -## Khắc phục Sự cố - -### Các Vấn đề Phổ biến - -Kiểm tra phần khắc phục sự cố toàn diện trong `references/tech_decision_guide.md`. - -### Nhận Trợ giúp - -- Xem lại tài liệu tham khảo -- Kiểm tra thông báo đầu ra của script -- Tham khảo tài liệu của tech stack -- Xem lại nhật ký lỗi (error logs) - -## Tài nguyên - -- Tham chiếu Mẫu: `references/architecture_patterns.md` -- Hướng dẫn Quy trình: `references/system_design_workflows.md` -- Hướng dẫn Kỹ thuật: `references/tech_decision_guide.md` -- Tool Scripts: Thư mục `scripts/` diff --git a/docs/vietnamese/skills/typescript-expert/SKILL.vi.md b/docs/vietnamese/skills/typescript-expert/SKILL.vi.md deleted file mode 100644 index 9c8221af..00000000 --- a/docs/vietnamese/skills/typescript-expert/SKILL.vi.md +++ /dev/null @@ -1,405 +0,0 @@ ---- -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 & { __brand: T }; -type UserId = Brand; -type OrderId = Brand; - -// 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 extends (...args: any[]) => any - ? T - : T extends object - ? { readonly [K in keyof T]: DeepReadonly } - : T; - -// Template literal type magic -type PropEventSource = { - on - (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; -// 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` - 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 | InfiniteArray[]; - -// Tốt: Đệ quy có giới hạn -type NestedArray = - D extends 0 ? T : T | NestedArray[]; -``` - -**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().toHaveProperty('size') - expectTypeOf().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. From 2467d6a2acaf6e60b0888777ef9c91a267704cd5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C4=90=E1=BB=97=20Kh=E1=BA=AFc=20Gia=20Khoa?= Date: Thu, 29 Jan 2026 04:48:06 +0700 Subject: [PATCH 09/10] docs: translate security policy and skills readme, mark agent skills as english-only --- docs/vietnamese/SECURITY.vi.md | 19 +++++ docs/vietnamese/SKILLS_README.vi.md | 106 +++++++++++++++++++++++++ docs/vietnamese/TRANSLATION_PLAN.vi.md | 2 + 3 files changed, 127 insertions(+) create mode 100644 docs/vietnamese/SECURITY.vi.md create mode 100644 docs/vietnamese/SKILLS_README.vi.md diff --git a/docs/vietnamese/SECURITY.vi.md b/docs/vietnamese/SECURITY.vi.md new file mode 100644 index 00000000..7ef906e5 --- /dev/null +++ b/docs/vietnamese/SECURITY.vi.md @@ -0,0 +1,19 @@ +# Chính sách Bảo mật (Security Policy) + +## Các Phiên bản được Hỗ trợ + +Chúng tôi theo dõi nhánh `main`. + +## Báo cáo Lổ hổng + +**KHÔNG** mở Issue công khai cho các lổ hổng bảo mật. + +Nếu bạn tìm thấy một lổ hổng bảo mật (ví dụ: một kỹ năng vượt qua kiểm tra "Chỉ Sử dụng được Ủy quyền" hoặc thực thi mã độc hại mà không cảnh báo): + +1. Email: `security@antigravity.dev` (Placeholder) +2. Hoặc mở một **Private Advisory** (Cảnh báo Riêng tư) trên repository này. + +## Chính sách Kỹ năng Tấn công (Offensive Skills Policy) + +Vui lòng đọc [Rào chắn Bảo mật (Security Guardrails)](docs/vietnamese/SECURITY_GUARDRAILS.vi.md) của chúng tôi. +Tất cả các kỹ năng tấn công (offensive skills) chỉ dành nghiêm ngặt cho **mục đích giáo dục và chuyên nghiệp được ủy quyền**. diff --git a/docs/vietnamese/SKILLS_README.vi.md b/docs/vietnamese/SKILLS_README.vi.md new file mode 100644 index 00000000..55b08f6b --- /dev/null +++ b/docs/vietnamese/SKILLS_README.vi.md @@ -0,0 +1,106 @@ +# Thư mục Kỹ năng (Skills Directory) + +**Chào mừng đến với thư mục Kỹ năng!** Đây là nơi lưu trú của tất cả 179+ kỹ năng AI chuyên biệt. + +## 🤔 Kỹ năng là gì? + +Kỹ năng là các bộ hướng dẫn chuyên biệt dạy trợ lý AI cách xử lý các tác vụ cụ thể. Hãy nghĩ về chúng như các module kiến thức chuyên gia mà AI của bạn có thể tải theo yêu cầu. + +**Ẩn dụ đơn giản:** Giống như bạn có thể tham khảo ý kiến các chuyên gia khác nhau (một nhà thiết kế, một chuyên gia bảo mật, một nhà tiếp thị), các kỹ năng cho phép AI của bạn trở thành chuyên gia trong các lĩnh vực khác nhau khi bạn cần. + +--- + +## 📂 Cấu trúc Thư mục + +Mỗi kỹ năng nằm trong thư mục riêng của nó với cấu trúc sau: + +``` +skills/ +├── skill-name/ # Thư mục kỹ năng riêng lẻ +│ ├── SKILL.md # Định nghĩa kỹ năng chính (bắt buộc) +│ ├── scripts/ # Scripts hỗ trợ (tùy chọn) +│ ├── examples/ # Ví dụ sử dụng (tùy chọn) +│ └── resources/ # Templates & tài nguyên (tùy chọn) +``` + +**Điểm mấu chốt:** Chỉ `SKILL.md` là bắt buộc. Mọi thứ khác là tùy chọn! + +--- + +## Cách sử dụng Kỹ năng + +### Bước 1: Đảm bảo kỹ năng đã được cài đặt +Kỹ năng nên nằm trong thư mục `.agent/skills/` của bạn (hoặc `.claude/skills/`, `.gemini/skills/`, v.v.) + +### Bước 2: Gọi kỹ năng trong chat AI của bạn +Sử dụng biểu tượng `@` theo sau bởi tên kỹ năng: + +``` +@brainstorming giúp tôi thiết kế một ứng dụng todo +``` + +hoặc + +``` +@stripe-integration thêm xử lý thanh toán vào ứng dụng của tôi +``` + +### Bước 3: AI trở thành chuyên gia +AI tải kiến thức của kỹ năng đó và giúp bạn với chuyên môn đặc thù! + +--- + +## Tìm kiếm Kỹ năng + +### Cách 1: Duyệt thư mục này +```bash +ls skills/ +``` + +### Cách 2: Tìm kiếm theo từ khóa +```bash +ls skills/ | grep "từ khóa" +``` + +### Cách 3: Kiểm tra README chính +Xem [README chính](../README.vi.md) để biết danh sách đầy đủ tất cả 179+ kỹ năng được tổ chức theo danh mục. + +--- + +## 💡 Các Kỹ năng Phổ biến để Thử nghiệm + +**Cho người mới bắt đầu:** +- `@brainstorming` - Thiết kế trước khi code +- `@systematic-debugging` - Sửa lỗi một cách có phương pháp +- `@git-pushing` - Commit với thông báo tốt + +**Cho lập trình viên:** +- `@test-driven-development` - Viết test trước +- `@react-best-practices` - Các mẫu React hiện đại +- `@senior-fullstack` - Phát triển Full-stack + +**Cho bảo mật:** +- `@ethical-hacking-methodology` - Cơ bản về bảo mật +- `@burp-suite-testing` - Kiểm thử bảo mật ứng dụng web + +--- + +## Tạo Kỹ năng Riêng của Bạn + +Muốn tạo một kỹ năng mới? Hãy xem: +1. [CONTRIBUTING.vi.md](../docs/vietnamese/CONTRIBUTING.vi.md) - Cách đóng góp +2. [docs/vietnamese/SKILL_ANATOMY.vi.md](../docs/vietnamese/SKILL_ANATOMY.vi.md) - Hướng dẫn cấu trúc kỹ năng +3. `@skill-creator` - Sử dụng kỹ năng này để tạo kỹ năng mới! + +--- + +## Tài liệu Tham khảo + +- **[Bắt đầu](../docs/vietnamese/GETTING_STARTED.vi.md)** - Hướng dẫn bắt đầu nhanh +- **[Ví dụ](../docs/vietnamese/EXAMPLES.vi.md)** - Ví dụ sử dụng thực tế +- **[FAQ](../docs/vietnamese/FAQ.vi.md)** - Các câu hỏi thường gặp +- **[Hướng dẫn Trực quan](../docs/vietnamese/VISUAL_GUIDE.vi.md)** - Biểu đồ và lưu đồ + +--- + +**Cần trợ giúp?** Kiểm tra [FAQ](../docs/vietnamese/FAQ.vi.md) hoặc mở một issue trên GitHub! diff --git a/docs/vietnamese/TRANSLATION_PLAN.vi.md b/docs/vietnamese/TRANSLATION_PLAN.vi.md index b8273beb..5979c3b6 100644 --- a/docs/vietnamese/TRANSLATION_PLAN.vi.md +++ b/docs/vietnamese/TRANSLATION_PLAN.vi.md @@ -36,6 +36,8 @@ Tài liệu này dùng để theo dõi tiến độ dịch thuật toàn bộ re - [x] `docs/vietnamese/SKILL_ANATOMY.vi.md` - [x] `docs/vietnamese/SOURCES.vi.md` - [x] `docs/vietnamese/VISUAL_GUIDE.vi.md` +- [x] `docs/vietnamese/SECURITY.vi.md` +- [x] `docs/vietnamese/SKILLS_README.vi.md` ### 🟢 Giai đoạn 1: Essentials Bundle (Core Skills) > **TRẠNG THÁI: GIỮ NGUYÊN TIẾNG ANH (KEPT IN ENGLISH)** From b282aeee33ffd61e3c0dcf3c5ff885eeaae916bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C4=90=E1=BB=97=20Kh=E1=BA=AFc=20Gia=20Khoa?= Date: Thu, 29 Jan 2026 04:50:43 +0700 Subject: [PATCH 10/10] docs: refine vietnamese translations for natural flow and correct terminology --- docs/vietnamese/README.vi.md | 82 ++++------------------------- docs/vietnamese/SECURITY.vi.md | 10 ++-- docs/vietnamese/SKILLS_README.vi.md | 14 ++--- 3 files changed, 21 insertions(+), 85 deletions(-) diff --git a/docs/vietnamese/README.vi.md b/docs/vietnamese/README.vi.md index 64c23a1d..c933c3cf 100644 --- a/docs/vietnamese/README.vi.md +++ b/docs/vietnamese/README.vi.md @@ -21,84 +21,20 @@ - 🟠 **Cursor** (AI-native IDE) - ⚪ **OpenCode** (Mã nguồn mở CLI) -Repository này cung cấp các kỹ năng thiết yếu để biến trợ lý AI của bạn thành một **digital agency toàn diện**, bao gồm các khả năng chính thức từ **Anthropic**, **OpenAI**, **Google**, **Supabase**, và **Vercel Labs**. +**Chào mừng bạn đến với Phiên bản V4.0.0 Enterprise.** Đây không chỉ là một danh sách các tập lệnh (scripts); nó là một hệ điều hành hoàn chỉnh cho Trợ lý AI của bạn. -## Mục lục +### 1. 🐣 Bối cảnh: Đây là gì? -- [🚀 Bạn mới đến đây? Hãy bắt đầu tại đây!](#bạn-mới-đến-đây-hãy-bắt đầu-tại-đây) -- [🔌 Khả năng tương thích & Cách gọi lệnh](#khả-năng-tương-thích--cách-gọi-lệnh) -- [📦 Tính năng & Danh mục](#tính-năng--danh-mục) -- [🎁 Bộ sưu tập được tuyển chọn (Bundles)](#bộ-sưu-tập-được-tuyển-chọn) -- [📚 Duyệt hơn 552 Kỹ năng](#duyệt-hơn-552-kỹ-năng) -- [🛠️ Cài đặt](#cài-đặt) -- [🤝 Cách thức Đóng góp](#cách-thức-đóng-góp) -- [👥 Người đóng góp & Ghi công](#người-đóng-góp--ghi-công) -- [⚖️ Giấy phép](#giấy-phép) -- [👥 Những người đóng góp cho Repo](#những-người-đóng-góp-cho-repo) -- [🌟 Lịch sử Star](#lịch-sử-star) - ---- - -## Bạn mới đến đây? Hãy bắt đầu tại đây! - -**Chào mừng bạn đến với Phiên bản V4.0.0 Enterprise.** Đây không chỉ là một danh sách các kịch bản; nó là một hệ điều hành hoàn chỉnh cho Trợ lý AI của bạn. - -### 1. 🐣 Bối cảnh: Đây là cái gì? - -**Antigravity Awesome Skills** (Phiên bản 4.0.0) là một bản nâng cấp khổng lồ cho khả năng của AI của bạn. - -Các trợ lý AI (như Claude Code, Cursor, hoặc Gemini) rất thông minh, nhưng chúng thiếu các **công cụ cụ thể**. Chúng không biết "Giao thức Triển khai" của công ty bạn hoặc cú pháp cụ thể cho "AWS CloudFormation". -**Skills** là các tệp markdown nhỏ dạy cho chúng cách thực hiện những tác vụ cụ thể này một cách hoàn hảo trong mọi lần thực hiện. - -### 2. ⚡️ Khởi động nhanh (Theo cách dùng "Gói kỹ năng") - -Đừng cài đặt 552+ kỹ năng một cách thủ công. Hãy sử dụng các **Gói khởi đầu (Starter Packs)** của chúng tôi: - -1. **Sao chép repo**: - ```bash - git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills - ``` -2. **Chọn vai trò của bạn** (Xem [docs/vietnamese/BUNDLES.md](docs/vietnamese/BUNDLES.vi.md)): - - **Lập trình Web?** sử dụng gói `Web Wizard`. - - **Hacker?** sử dụng gói `Security Engineer`. - - **Chỉ tò mò thôi?** bắt đầu với gói `Essentials`. - -### 3. 🧠 Cách sử dụng - -Sau khi cài đặt, chỉ cần hỏi trợ lý của bạn một cách tự nhiên: - -> "Sử dụng kỹ năng **@brainstorming** để giúp tôi lập kế hoạch cho một dự án SaaS." -> "Chạy **@lint-and-validate** trên file này." - -👉 **[Đọc Hướng dẫn bắt đầu đầy đủ](docs/vietnamese/GETTING_STARTED.vi.md)** - ---- - -## Khả năng tương thích & Cách gọi lệnh - -Các kỹ năng này tuân theo định dạng chuẩn **SKILL.md** phổ quát và hoạt động với bất kỳ trợ lý lập trình AI nào hỗ trợ các kỹ năng agentic. - -| Công cụ | Loại | Ví dụ gọi lệnh | Đường dẫn | -| :-------------- | :--- | :-------------------------------- | :---------------- | -| **Claude Code** | CLI | `>> /skill-name giúp tôi...` | `.claude/skills/` | -| **Gemini CLI** | CLI | `(User Prompt) Dùng skill-name...`| `.gemini/skills/` | -| **Antigravity** | IDE | `(Agent Mode) Dùng skill...` | `.agent/skills/` | -| **Cursor** | IDE | `@skill-name (trong Chat)` | `.cursor/skills/` | -| **Copilot** | Ext | `(Dán nội dung thủ công)` | (N/A) | - -> [!TIP] -> **Đường dẫn Phổ quát**: Chúng tôi khuyên bạn nên clone về thư mục `.agent/skills/`. Hầu hết các công cụ hiện đại (Antigravity, các CLI gần đây) đều tìm kiếm ở đây theo mặc định. - -> [!WARNING] -> **Người dùng Windows**: Repository này sử dụng **symlinks** cho các kỹ năng chính thức. -> Bạn phải bật Chế độ nhà phát triển (Developer Mode) hoặc chạy Git với quyền Admin: -> `git clone -c core.symlinks=true https://github.com/...` - ---- +**Antigravity Awesome Skills** (Phiên bản 4.0.0) là một bản nâng cấp khổng lồ cho khả năng của AI. +Các trợ lý AI (như Claude Code, Cursor, hoặc Gemini) rất thông minh, nhưng chúng thiếu các **công cụ chuyên biệt**. Chúng không biết "Quy trình Triển khai" của công ty bạn hoặc cú pháp cụ thể cho "AWS CloudFormation". +**Skills** là các tệp markdown nhỏ dạy cho chúng cách thực hiện những tác vụ cụ thể này một cách chính xác trong mọi lần thực thi. +... +Repository này cung cấp các kỹ năng thiết yếu để biến trợ lý AI của bạn thành một **đội ngũ chuyên gia số toàn năng**, bao gồm các khả năng chính thức từ **Anthropic**, **OpenAI**, **Google**, **Supabase**, và **Vercel Labs**. +... Cho dù bạn đang sử dụng **Gemini CLI**, **Claude Code**, **Codex CLI**, **Cursor**, **GitHub Copilot**, **Antigravity**, hay **OpenCode**, những kỹ năng này được thiết kế để có thể sử dụng ngay lập tức và tăng cường sức mạnh cho trợ lý AI của bạn. -Repository này tập hợp những khả năng tốt nhất từ khắp cộng đồng mã nguồn mở, biến trợ lý AI của bạn thành một digital agency toàn diện có khả năng Kỹ thuật, Thiết kế, Bảo mật, Marketing và Vận hành Tự động. +Repository này tập hợp những khả năng tốt nhất từ khắp cộng đồng mã nguồn mở, biến trợ lý AI của bạn thành một đội ngũ chuyên gia số toàn năng có khả năng Kỹ thuật, Thiết kế, Bảo mật, Marketing và Vận hành Tự động. ## Tính năng & Danh mục diff --git a/docs/vietnamese/SECURITY.vi.md b/docs/vietnamese/SECURITY.vi.md index 7ef906e5..d137403e 100644 --- a/docs/vietnamese/SECURITY.vi.md +++ b/docs/vietnamese/SECURITY.vi.md @@ -4,16 +4,16 @@ Chúng tôi theo dõi nhánh `main`. -## Báo cáo Lổ hổng +## Báo cáo Lỗ hổng -**KHÔNG** mở Issue công khai cho các lổ hổng bảo mật. +**KHÔNG** mở Issue công khai cho các lỗ hổng bảo mật. -Nếu bạn tìm thấy một lổ hổng bảo mật (ví dụ: một kỹ năng vượt qua kiểm tra "Chỉ Sử dụng được Ủy quyền" hoặc thực thi mã độc hại mà không cảnh báo): +Nếu bạn tìm thấy một lỗ hổng bảo mật (ví dụ: một kỹ năng vượt qua kiểm tra "Sử dụng có Phép" hoặc thực thi mã độc hại mà không cảnh báo): 1. Email: `security@antigravity.dev` (Placeholder) -2. Hoặc mở một **Private Advisory** (Cảnh báo Riêng tư) trên repository này. +2. Hoặc mở một **Private Advisory** (Cảnh báo Bảo mật Riêng tư) trên repository này. ## Chính sách Kỹ năng Tấn công (Offensive Skills Policy) Vui lòng đọc [Rào chắn Bảo mật (Security Guardrails)](docs/vietnamese/SECURITY_GUARDRAILS.vi.md) của chúng tôi. -Tất cả các kỹ năng tấn công (offensive skills) chỉ dành nghiêm ngặt cho **mục đích giáo dục và chuyên nghiệp được ủy quyền**. +Tất cả các kỹ năng tấn công (offensive skills) chỉ dành nghiêm ngặt cho **mục đích giáo dục và hoạt động chuyên nghiệp đã được cấp phép**. diff --git a/docs/vietnamese/SKILLS_README.vi.md b/docs/vietnamese/SKILLS_README.vi.md index 55b08f6b..81eeaf9c 100644 --- a/docs/vietnamese/SKILLS_README.vi.md +++ b/docs/vietnamese/SKILLS_README.vi.md @@ -1,18 +1,18 @@ # Thư mục Kỹ năng (Skills Directory) -**Chào mừng đến với thư mục Kỹ năng!** Đây là nơi lưu trú của tất cả 179+ kỹ năng AI chuyên biệt. +**Chào mừng đến với thư mục Kỹ năng!** Đây là nơi tập hợp tất cả 179+ kỹ năng AI chuyên biệt. ## 🤔 Kỹ năng là gì? Kỹ năng là các bộ hướng dẫn chuyên biệt dạy trợ lý AI cách xử lý các tác vụ cụ thể. Hãy nghĩ về chúng như các module kiến thức chuyên gia mà AI của bạn có thể tải theo yêu cầu. -**Ẩn dụ đơn giản:** Giống như bạn có thể tham khảo ý kiến các chuyên gia khác nhau (một nhà thiết kế, một chuyên gia bảo mật, một nhà tiếp thị), các kỹ năng cho phép AI của bạn trở thành chuyên gia trong các lĩnh vực khác nhau khi bạn cần. +**Hình dung đơn giản:** Giống như bạn có thể tham khảo ý kiến các chuyên gia khác nhau (một nhà thiết kế, một chuyên gia bảo mật, một chuyên gia Marketing), các kỹ năng cho phép AI trở thành chuyên gia trong các lĩnh vực khác nhau ngay khi bạn cần. --- ## 📂 Cấu trúc Thư mục -Mỗi kỹ năng nằm trong thư mục riêng của nó với cấu trúc sau: +Mỗi kỹ năng nằm trong thư mục riêng với cấu trúc sau: ``` skills/ @@ -23,16 +23,16 @@ skills/ │ └── resources/ # Templates & tài nguyên (tùy chọn) ``` -**Điểm mấu chốt:** Chỉ `SKILL.md` là bắt buộc. Mọi thứ khác là tùy chọn! +**Lưu ý quan trọng:** Chỉ file `SKILL.md` là bắt buộc. Mọi thứ khác là tùy chọn! --- ## Cách sử dụng Kỹ năng -### Bước 1: Đảm bảo kỹ năng đã được cài đặt -Kỹ năng nên nằm trong thư mục `.agent/skills/` của bạn (hoặc `.claude/skills/`, `.gemini/skills/`, v.v.) +### Bước 1: Đảm bảo kỹ năng đã được thiết lập +Các file kỹ năng nên nằm trong thư mục `.agent/skills/` của bạn (hoặc `.claude/skills/`, `.gemini/skills/`, v.v.) -### Bước 2: Gọi kỹ năng trong chat AI của bạn +### Bước 2: Kích hoạt kỹ năng trong cuộc trò chuyện với AI Sử dụng biểu tượng `@` theo sau bởi tên kỹ năng: ```