docs: restructure translation formatting - moving all localized content to docs/vietnamese

2026-01-28 18:01:08 +01:00
parent 76e0dffad7
commit a16b57e581
31 changed files with 3024 additions and 1423 deletions
--- a/docs/vietnamese/skills/architecture/SKILL.md
+++ 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
--- a/docs/vietnamese/skills/concise-planning/SKILL.md
+++ 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
+
+<Cách tiếp cận cấp cao>
+
+## Phạm vi (Scope)
+
+- Trong phạm vi (In):
+- Ngoài phạm vi (Out):
+
+## Hạng mục Hành động (Action Items)
+
+[ ] <Bước 1: Khám phá/Tìm hiểu>
+[ ] <Bước 2: Triển khai>
+[ ] <Bước 3: Triển khai>
+[ ] <Bước 4: Xác thực/Kiểm thử>
+[ ] <Bước 5: Triển khai/Commit>
+
+## Câu hỏi Mở
+
+- <Câu hỏi 1 (tối đa 3)>
+```
+
+## 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ể.
--- a/docs/vietnamese/skills/git-pushing/SKILL.md
+++ 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.
--- a/docs/vietnamese/skills/kaizen/SKILL.md
+++ 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
+
+<Good>
+```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
+</Good>
+
+<Bad>
+```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
+</Bad>
+
+#### 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
+
+<Good>
+```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
+</Good>
+
+<Good>
+```typescript
+// Làm cho trạng thái không hợp lệ không thể biểu diễn
+type NonEmptyArray<T> = [T, ...T[]];
+
+const firstItem = <T>(items: NonEmptyArray<T>): 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<number>); // An toàn
+}
+```
+Chữ ký hàm đảm bảo an toàn
+</Good>
+
+#### Chống lỗi bằng Validation
+
+<Good>
+```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
+</Good>
+
+#### Guards và Điều kiện tiên quyết
+
+<Good>
+```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
+</Good>
+
+#### Chống lỗi Cấu hình
+
+<Good>
+```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
+</Good>
+
+#### 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<T, E> 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)
+
+<Good>
+```typescript
+// Mẫu codebase hiện tại cho API clients
+class UserAPIClient {
+  async getUser(id: string): Promise<User> {
+    return this.fetch(`/users/${id}`);
+  }
+}
+
+// Code mới tuân theo cùng một mẫu
+class OrderAPIClient {
+  async getOrder(id: string): Promise<Order> {
+    return this.fetch(`/orders/${id}`);
+  }
+}
+```
+Sự nhất quán làm cho codebase dễ dự đoán
+</Good>
+
+<Bad>
+```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<Order> => {
+  // 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
+</Bad>
+
+#### Các Mẫu Xử lý Lỗi
+
+<Good>
+```typescript
+// Tiêu chuẩn dự án: Kiểu Result cho các lỗi có thể phục hồi
+type Result<T, E> = { 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<Result<User, Error>> => {
+  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
+</Good>
+
+#### Tiêu chuẩn Tài liệu
+
+<Good>
+```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 <T>(
+  operation: () => Promise<T>,
+  options: RetryOptions
+): Promise<T> => {
+  // Implementation...
+};
+```
+Tài liệu hóa tại sao, khi nào và làm thế nào
+</Good>
+
+#### 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
+
+<Good>
+```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
+</Good>
+
+<Bad>
+```typescript
+// Kỹ thuật quá mức cho "nhu cầu tương lai"
+interface LogTransport {
+  write(level: LogLevel, message: string, meta?: LogMetadata): Promise<void>;
+}
+
+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
+</Bad>
+
+**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
+
+<Good>
+```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
+</Good>
+
+#### Trừu tượng hóa Sớm (Premature Abstraction)
+
+<Bad>
+```typescript
+// Một trường hợp sử dụng, nhưng xây dựng framework chung chung
+abstract class BaseCRUDService<T> {
+  abstract getAll(): Promise<T[]>;
+  abstract getById(id: string): Promise<T>;
+  abstract create(data: Partial<T>): Promise<T>;
+  abstract update(id: string, data: Partial<T>): Promise<T>;
+  abstract delete(id: string): Promise<void>;
+}
+
+class GenericRepository<T> { /* 300 dòng */ }
+class QueryBuilder<T> { /* 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
+</Bad>
+
+<Good>
+```typescript
+// Các hàm đơn giản cho nhu cầu hiện tại
+const getUsers = async (): Promise<User[]> => {
+  return db.query('SELECT * FROM users');
+};
+
+const getUserById = async (id: string): Promise<User | null> => {
+  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
+</Good>
+
+#### Tối ưu hóa Hiệu suất
+
+<Good>
+```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
+</Good>
+
+<Bad>
+```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
+</Bad>
+
+#### 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.
--- a/docs/vietnamese/skills/lint-and-validate/SKILL.md
+++ 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 <project_path>` |
+| `scripts/type_coverage.py` | Phân tích độ bao phủ kiểu dữ liệu | `python scripts/type_coverage.py <project_path>` |
--- a/docs/vietnamese/skills/senior-architect/SKILL.md
+++ 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 <project-path> [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 <target-path> [--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/`