# Cẩm Nang Thuật Ngữ Kỹ Thuật Cho Vibe Coder (Tech Keywords & Decision Matrix)

> **Mục tiêu:** Giúp người xây dựng sản phẩm bằng AI (Vibe Coder / Non-tech Builder) nhanh chóng gọi đúng "tên kỹ thuật chuẩn" (Best Practice Pattern) tương ứng với từng bối cảnh cụ thể, rút ngắn chu kỳ sửa lỗi và nâng cao độ bền bỉ của sản phẩm.

## 1. Nguyên Tắc 2 Bước Giao Tiếp Với AI

Thay vì yêu cầu AI viết code ngay lập tức bằng ngôn ngữ đời thường, hãy áp dụng quy trình 2 bước:

1. **Bước 1 (Chẩn đoán rủi ro):**

   > *"Tôi muốn xây dựng tính năng `[mô tả đời thường]`. Đối với tính năng này, có những rủi ro thực tế (production issues) nào thường gặp và cần áp dụng các pattern / từ khóa kỹ thuật chuẩn nào?"*

2. **Bước 2 (Chỉ định triển khai):**

   > *"Hãy áp dụng các pattern `[Keyword A, Keyword B]` theo chuẩn kiến trúc sạch (clean architecture) để sinh mã nguồn hoàn chỉnh cho tôi."*

## 2. Bảng Tra Cứu Theo "Triệu Chứng & Tình Huống" (When to Use What)

### 2.1. Quy trình & Luồng nghiệp vụ (Business Logic & Flow)

| Tình huống / Triệu chứng gặp phải | Thuật ngữ chuẩn (Keyword) | Bản chất kỹ thuật & Lợi ích mang lại | 
 | ----- | ----- | ----- | 
| Quy trình có nhiều bước (vd: Đơn hàng, Duyệt bài viết, Vé hỗ trợ). Code bắt đầu xuất hiện quá nhiều `if-else` lồng nhau, dễ bị nhảy cóc bước hoặc trạng thái mâu thuẫn. | **Finite State Machine (FSM)** | AI tạo enum trạng thái và bảng chuyển đổi (transition table) hợp lệ, chặn đứng mọi trạng thái bất hợp lệ. | 
| Người dùng bấm nút gửi (thanh toán, tạo bài viết, gửi email) nhiều lần liên tiếp do mạng lag làm trùng lặp bản ghi hoặc trừ tiền 2 lần. | **Idempotency / Idempotent Request** | Thêm header `Idempotency-Key` hoặc khóa giao dịch dựa trên token duy nhất, đảm bảo gọi 10 lần kết quả vẫn chỉ xử lý 1 lần. | 
| Một thao tác tác động vào nhiều bảng dữ liệu (vd: Trừ điểm ví -> Tạo hóa đơn -> Giảm số lượng kho). Lỗi xảy ra ở bước giữa làm dữ liệu cọc cạch. | **Atomic Transaction (ACID) / Database Rollback** | Gom toàn bộ thao tác vào 1 giao dịch cơ sở dữ liệu. Thành công thì lưu hết (Commit), lỗi thì khôi phục về trạng thái cũ (Rollback). | 
| Hành động mất thời gian xử lý (gửi email, xuất PDF, import file Excel 10.000 dòng) làm đứng cả màn hình và treo request HTTP. | **Background Job / Asynchronous Processing / Message Queue** | Trả kết quả thành công tức thì cho người dùng, đẩy tác vụ nặng vào hàng đợi (queue) để worker xử lý ngầm. | 
| Dữ liệu cấu hình hoặc bản ghi nhạy cảm dễ bị sửa đổi ngoài ý muốn ở nhiều chỗ khác nhau trong code. | **Immutable Data / Read-only Pattern** | Đóng băng đối tượng dữ liệu, không cho phép mutate trực tiếp, tránh tác dụng phụ (side-effects). | 

### 2.2. Hiệu năng & Giao diện người dùng (Frontend & UI/UX Performance)

| Tình huống / Triệu chứng gặp phải | Thuật ngữ chuẩn (Keyword) | Bản chất kỹ thuật & Lợi ích mang lại | 
 | ----- | ----- | ----- | 
| Người dùng gõ vào ô tìm kiếm, mỗi ký tự gửi 1 request về server làm server quá tải và kết quả nhảy liên tục. | **Debounce** | Đợi người dùng ngừng gõ sau một khoảng thời gian ngắn (ví dụ 300ms) mới gửi request một lần duy nhất. | 
| Người dùng bấm nút thích (Like), thả tim hoặc lưu bài, phải chờ 1-2 giây quay vòng tròn xoay xoay mới thấy đổi màu. | **Optimistic UI Update** | Đổi màu giao diện ngay lập tức khi click, ngầm gửi request lên server; nếu server báo lỗi thì mới rollback giao diện lại kèm thông báo. | 
| Màn hình hiển thị danh sách hàng chục ngàn phần tử (tin nhắn chat, lịch sử giao dịch) làm đơ trình duyệt hoặc tràn RAM. | **Virtual Scrolling / Windowing** | Chỉ render vào DOM những phần tử đang nằm trong tầm mắt nhìn thấy của người dùng trên màn hình. | 
| Trang web load xong bị nhảy giật khung hình do hình ảnh hoặc nội dung bất ngờ xuất hiện, làm người dùng bấm nhầm nút. | **Cumulative Layout Shift (CLS) / Skeleton Screen** | Dựng sẵn khung xám mô phỏng kích thước thực của nội dung trong lúc chờ tải dữ liệu. | 
| Người dùng cuộn chuột hoặc di chuột liên tục phát sinh hàng trăm sự kiện mỗi giây làm giao diện lag giật. | **Throttle** | Giới hạn tần suất kích hoạt hàm xử lý theo một chu kỳ thời gian cố định (ví dụ tối đa 1 lần mỗi 100ms). | 

### 2.3. Bền bỉ, Chịu lỗi & "Future-Proof" (Resilience & Extensibility)

| Tình huống / Triệu chứng gặp phải | Thuật ngữ chuẩn (Keyword) | Bản chất kỹ thuật & Lợi ích mang lại | 
 | ----- | ----- | ----- | 
| Sửa một tính năng ở module này lại vô tình làm hỏng tính năng ở module khác; khó mở rộng loại đối tượng mới. | **Open-Closed Principle (OCP) / Loose Coupling** | Mở rộng tính năng bằng cách thêm module mới kế thừa interface, không chỉnh sửa trực tiếp vào mã nguồn đã chạy ổn định. | 
| Tích hợp dịch vụ bên thứ 3 (Cổng thanh toán, AI API, SMS). Khi đối tác bảo trì hoặc gặp sự cố, cả hệ thống của mình lăn ra chết theo. | **Circuit Breaker & Graceful Degradation** | Ngắt tự động kết nối khi phát hiện lỗi vượt ngưỡng, chuyển sang phương án dự phòng (fallback) an toàn thay vì làm nghẽn toàn bộ server. | 
| Kết nối mạng chập chờn khiến gọi API thỉnh thoảng thất bại ngẫu nhiên một cách đáng tiếc. | **Retry with Exponential Backoff & Jitter** | Tự động gọi lại với thời gian chờ tăng dần theo cấp số nhân kèm độ trễ ngẫu nhiên để tránh dồn tải lên server đích. | 
| Cần hỗ trợ nhiều nhà cung cấp cùng loại (ví dụ: vừa dùng Stripe, vừa dùng MoMo, ZaloPay) mà không muốn viết code rải rác. | **Strategy Pattern / Adapter Pattern** | Định nghĩa một interface chuẩn chung (vd: `IPaymentService`) và tạo các lớp adapter riêng cho từng nhà cung cấp. | 
| Kẻ xấu hoặc bot spam bấm request liên tục làm server cạn kiệt tài nguyên CPU/RAM. | **Rate Limiting / Token Bucket Algorithm** | Thiết lập ngưỡng giới hạn số request tối đa theo IP hoặc User Token trong một đơn vị thời gian. | 

### 2.4. Dữ liệu, Lưu trữ & Bảo mật (Data, Database & Security)

| Tình huống / Triệu chứng gặp phải | Thuật ngữ chuẩn (Keyword) | Bản chất kỹ thuật & Lợi ích mang lại | 
 | ----- | ----- | ----- | 
| Người dùng vô tình bấm xóa hoặc có tranh chấp dữ liệu, cần giữ lại lịch sử nhưng không hiển thị trên giao diện thông thường. | **Soft Delete** | Thêm trường `deleted_at` hoặc cờ `is_deleted` thay vì dùng lệnh `DELETE` vật lý khỏi cơ sở dữ liệu. | 
| Bảng dữ liệu lên đến hàng trăm ngàn dòng, các câu lệnh truy vấn lọc theo ngày tháng hoặc trạng thái chạy quá chậm. | **Database Indexing & Query Plan Optimization** | Tạo chỉ mục (index) đúng cột thường xuyên được dùng trong mệnh đề `WHERE` hoặc `JOIN`. | 
| Cần lấy danh sách dữ liệu lớn để hiển thị theo từng trang, nhưng dùng `OFFSET` lớn làm server truy vấn rất nặng nề. | **Cursor-based Pagination (Keyset Pagination)** | Phân trang dựa trên ID hoặc mốc thời gian của phần tử cuối cùng thay vì đếm nhảy cóc số trang. | 
| Một số dữ liệu ít khi thay đổi (danh mục hàng hóa, bảng giá cấu hình) nhưng mỗi lần load trang lại gọi vào cơ sở dữ liệu. | **In-memory Cache with TTL (Time To Live)** | Lưu tạm vào bộ nhớ đệm (Redis hoặc memory) có thời hạn tự hủy để giảm tải triệt để cho database. | 
| Dữ liệu đầu vào từ form hoặc URL có nguy cơ chứa mã độc tấn công hoặc dữ liệu sai định dạng gây crash server. | **Input Validation & Schema Sanitization** | Dùng schema validator (như Zod, Joi, Pydantic) để kiểm tra chặt chẽ kiểu dữ liệu trước khi xử lý logic. | 

### 2.5. Kiểm thử, Bảo trì & Nhật ký (Testing & Observability)

| Tình huống / Triệu chứng gặp phải | Thuật ngữ chuẩn (Keyword) | Bản chất kỹ thuật & Lợi ích mang lại | 
 | ----- | ----- | ----- | 
| Muốn đảm bảo các hàm tính toán quan trọng (tính giá, chiết khấu, thuế) luôn cho kết quả chính xác tuyệt đối. | **Unit Testing & Boundary Value Analysis** | Viết các ca kiểm thử tự động tập trung vào các trường hợp biên (số âm, số 0, số cực lớn, ký tự lạ). | 
| Có lỗi xảy ra trên production nhưng không thể tái hiện lại được do không biết người dùng đã thao tác những gì trước đó. | **Structured Logging & Audit Trail** | Ghi log dưới dạng JSON có cấu trúc (gồm Timestamp, Request ID, User ID, Context) thay vì log văn bản thô. | 
| Sợ thay đổi một đoạn code nhỏ sẽ làm phát sinh lỗi ngầm ở các tính năng cũ mà không phát hiện kịp thời. | **Regression Testing & CI/CD Pipeline** | Thiết lập kịch bản chạy lại toàn bộ bài test tự động mỗi khi có code mới được tích hợp. | 

## 3. Bản Chỉ Dẫn Nhanh (Cheat Sheet Cài Vào AI Rules / Custom Instructions)

Sao chép đoạn dưới đây vào mục **Custom Instructions** hoặc file `.cursorrules` / `.windsurfrules` của bạn, trong Claude Code thì bạn có thể tạo 1 agent:

```
Role: Senior Software Architect & Technical Mentor.
Context: I am a Vibe Coder / Product Builder with strong domain knowledge but non-traditional technical background.

Instructions:
1. When I describe a feature or problem in plain business language, DO NOT just write ad-hoc code.
2. First, analyze my request and explicitly identify 2-3 standard software architecture patterns / technical keywords that solve the problem properly (e.g., Idempotency, FSM, Debounce, Soft Delete, Circuit Breaker).
3. Briefly explain "Why" each pattern is critical for production resilience in 1-2 bullet points.
4. Implement the solution adhering strictly to those stated patterns.

```