ai-developer-skill-os 8.2.1 → 8.3.0

package/.agents/skills/qk-devops-platform/SKILL.md

@@ -1,117 +1,241 @@
----
-# ── Identity ───────────────────────────────────────────────
-name: qk-devops-platform
-version: 8.1.1
-status: experimental
-description: "Kỹ sư nền tảng: Chiến lược CI/CD, kiến trúc triển khai, quản lý môi trường và chiến lược rollback."
-platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
-
-# ── V8: Classification ─────────────────────────────────────
-type: capability
-
-intent:
-  - devops-strategy
-  - cicd-pipeline
-  - deployment-architecture
-  - environment-management
-
-complexity:
-  level: high
-  criteria:
-    files_affected: "1-5"
-    has_behavior_change: true
-    has_external_dependency: true
-    has_breaking_change: false
-
-triggers:
-  - "cấu hình ci/cd"
-  - "deployment strategy"
-  - "quản lý môi trường"
-  - "devops platform"
-  - "dockerize"
-
-# ── V8: References ─────────────────────────────────────────
-workflow: feature-delivery
-
-rules:
-  - global
-  - coding
-  - security
-
-tools:
-  - filesystem
-  - terminal
-
-related_skills:
-  - qk-production-release
-  - qk-security-audit
-
-knowledge_scope:
-  domain:
-    - devops
-    - platform-engineering
-    - cloud-infrastructure
-  concepts:
-    - continuous-integration
-    - continuous-deployment
-    - containerization
-    - rollback-strategy
-  references:
-    - architecture
-
-decision_boundary:
-  owns:
-    - CI/CD strategy
-    - deployment architecture
-    - environment management
-    - rollback strategy
-  does_not_own:
-    - application code
-    - cloud billing
-    - releasing features
-  conflicts_with:
-    - qk-production-release
-
-# ── V8: Verification ───────────────────────────────────────
-verification:
-  required: true
-  strategy: feature
-
-selection:
-  priority: medium
-  confidence_threshold: 0.80
-
-examples: []
-learnings: []
-
-# ── V7 Runtime ─────────────────────────────────────────────
-execution_mode: deterministic
-cost: medium
-latency: medium
-risk: high
-side_effects: edit_files
-produces: [report, plan, code]
-consumes: [user-description]
-
-token_budget:
-  max_files_read: 5
-  max_lines_per_read: 150
-  max_shell_commands: 2
-  stop_early: true
-
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
----
-
-# qk-devops-platform — Platform Engineer
-
-> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
-
-## Preconditions
-- [ ] Requirements cho môi trường triển khai đã có sẵn.
-
-## Scope
-- Thiết kế và thiết lập luồng CI/CD (GitHub Actions, GitLab CI, v.v.).
-- Xây dựng kiến trúc deployment, quản lý các container (Docker, Kubernetes).
-- Đưa ra chiến lược Rollback an toàn khi có sự cố.
-- Quản lý và phân tách các môi trường (Dev, Staging, Prod).
-- KHÔNG thay thế `qk-production-release` (đóng gói và release app), skill này quản lý *hạ tầng và quy trình* bên dưới việc release đó.
+---
+# ── Identity ───────────────────────────────────────────────
+name: qk-devops-platform
+version: 8.1.1
+status: experimental
+description: "Kỹ sư nền tảng: Chiến lược CI/CD, kiến trúc triển khai, quản lý môi trường và chiến lược rollback."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+
+# ── V8: Classification ─────────────────────────────────────
+type: capability
+
+intent:
+  - devops-strategy
+  - cicd-pipeline
+  - deployment-architecture
+  - environment-management
+
+complexity:
+  level: high
+  criteria:
+    files_affected: "1-5"
+    has_behavior_change: true
+    has_external_dependency: true
+    has_breaking_change: false
+
+triggers:
+  - "cấu hình ci/cd"
+  - "deployment strategy"
+  - "quản lý môi trường"
+  - "devops platform"
+  - "dockerize"
+
+# ── V8: References ─────────────────────────────────────────
+workflow: feature-delivery
+
+rules:
+  - global
+  - coding
+  - security
+
+tools:
+  - filesystem
+  - terminal
+
+related_skills:
+  - qk-production-release
+  - qk-security-audit
+
+knowledge_scope:
+  domain:
+    - devops
+    - platform-engineering
+    - cloud-infrastructure
+  concepts:
+    - continuous-integration
+    - continuous-deployment
+    - containerization
+    - rollback-strategy
+  references:
+    - architecture
+    - security
+    - anti-patterns
+
+decision_boundary:
+  owns:
+    - CI/CD strategy
+    - deployment architecture
+    - environment management
+    - rollback strategy
+  does_not_own:
+    - application code
+    - cloud billing
+    - releasing features
+  conflicts_with:
+    - qk-production-release
+
+# ── V8: Verification ───────────────────────────────────────
+verification:
+  required: true
+  strategy: feature
+
+selection:
+  priority: medium
+  confidence_threshold: 0.80
+
+examples: []
+learnings: []
+
+# ── V7 Runtime ─────────────────────────────────────────────
+execution_mode: deterministic
+cost: medium
+latency: medium
+risk: high
+side_effects: edit_files
+produces: [report, plan, code]
+consumes: [user-description]
+
+token_budget:
+  max_files_read: 5
+  max_lines_per_read: 150
+  max_shell_commands: 2
+  stop_early: true
+
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+---
+
+# qk-devops-platform — Platform Engineer
+
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
+## Preconditions
+- [ ] Requirements cho môi trường triển khai đã có sẵn.
+
+## Scope
+- Thiết kế và thiết lập luồng CI/CD (GitHub Actions, GitLab CI, v.v.).
+- Xây dựng kiến trúc deployment, quản lý các container (Docker, Kubernetes).
+- Đưa ra chiến lược Rollback an toàn khi có sự cố.
+- Quản lý và phân tách các môi trường (Dev, Staging, Prod).
+- **Bắt buộc tuân thủ R-SEC-04: Mọi secrets/credentials trong CI/CD phải được inject qua biến môi trường an toàn (Github Secrets/Vault), KHÔNG BAO GIỜ hardcode.**
+- KHÔNG thay thế `qk-production-release` (đóng gói và release app), skill này quản lý *hạ tầng và quy trình* bên dưới việc release đó.
+
+## Non-Goals
+- ❌ Provide implementation outside of DevOps & CI/CD scope
+- ❌ Override explicit user directives without explanation
+- ❌ Guess ambiguous requirements without asking
+
+## Priority Order
+
+| Priority | Task | Skip Threshold |
+|----------|------|----------------|
+| P1 | Core DevOps & CI/CD analysis and decision making | Never |
+| P2 | Validation of existing patterns | Budget < 30% |
+| P3 | Detailed documentation generation | Budget < 50% |
+| P4 | Edge case exploration | Budget < 70% |
+
+## Workflow
+
+### Phase 1 — Context Loading
+**Steps:**
+1. Read existing configuration and requirements related to DevOps & CI/CD.
+2. Check for missing preconditions.
+
+**Decision:**
+```
+IF context is clear
+  → Confidence: HIGH → go to Phase 2
+ELSE
+  → EXIT: BLOCKED — ask user
+```
+
+### Phase 2 — Analysis & Strategy
+**Steps:**
+1. Analyze the current state against DevOps & CI/CD best practices.
+2. Formulate strategy or audit report based on findings.
+
+**Decision:**
+```
+IF strategy/audit is complete
+  → Confidence: HIGH → go to Phase 3
+ELSE IF minor gaps exist
+  → Confidence: MEDIUM → proceed with assumptions noted
+```
+
+### Phase 3 — Finalization
+**Steps:**
+1. Generate final report or configuration.
+2. Prepare handoff data for subsequent skills.
+
+## Confidence Model
+
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | All preconditions met, context fully understood | Proceed directly |
+| MEDIUM | Some context missing but safe defaults exist | Proceed and note assumptions |
+| LOW | Core requirements missing | EXIT: BLOCKED |
+
+## Severity (for findings)
+
+| Level | Definition |
+|-------|-----------|
+| CRITICAL | Severe violation of DevOps & CI/CD principles |
+| HIGH | Significant risk or technical debt |
+| MEDIUM | Suboptimal pattern but functional |
+| LOW | Minor style or documentation issue |
+
+## Evidence Format
+
+```
+[SEVERITY] Context/File
+Issue:      [what was found]
+Confidence: HIGH
+Recommendation: [actionable advice]
+```
+
+## Retry Policy
+```
+Task fails due to missing context
+  └─ Ask user for clarification
+       ├─ Provided → Retry Phase 1
+       └─ Not provided → EXIT: BLOCKED
+```
+
+## Escalation Rules
+
+```
+BLOCKED: Missing critical context for DevOps & CI/CD
+Missing:
+  - [Specific requirement]
+Questions:
+  1. Bạn có thể cung cấp thêm thông tin về yêu cầu này không?
+  2. Mục tiêu chính của bạn là gì?
+Recommended Assumptions: none
+```
+
+## Handoff Contract
+
+### Consumes
+```json
+{
+  "from": "user or qk-orchestrator",
+  "required_fields": ["context"],
+  "optional_fields": ["existing_config"]
+}
+```
+
+### Produces
+```json
+{
+  "to": "user or downstream skill",
+  "output_fields": ["strategy_report", "exit_code"]
+}
+```
+
+## Exit Codes
+
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | DevOps & CI/CD task completed successfully | Strategy/audit generated |
+| PARTIAL | Task completed with assumptions | Medium confidence |
+| BLOCKED | Missing context | Cannot proceed |
+| FAILED | Critical conflict or error | Unresolvable constraint |

package/.agents/skills/qk-docs/SKILL.md

@@ -47,6 +47,8 @@ knowledge_scope:
     - architecture-docs
   references:
     - source-code
+    - security
+    - anti-patterns
 
 # ── V8: Verification ───────────────────────────────────────
 verification:
@@ -202,7 +204,7 @@ Fix:        [specific correction]
 ## Severity
 | Level | Definition | Example |
 |-------|-----------|---------|
-| CRITICAL | Docs instruct user to do something dangerous | Documenting destructive API without warnings |
+| CRITICAL | Docs instruct user to do something dangerous, bypass auth, or expose secrets | Documenting destructive API without warnings, or writing guides to call internal APIs unauthenticated |
 | HIGH | API params documented incorrectly | Says string instead of object |
 | MEDIUM | Missing docs for edge cases | Doesn't explain error throws |
 | LOW | Typo or poor formatting | Misaligned markdown table |

package/.agents/skills/qk-engineering-standard/SKILL.md

@@ -49,6 +49,8 @@ knowledge_scope:
     - best-practices
   references:
     - architecture
+    - security
+    - anti-patterns
 
 # ── V8: Verification ───────────────────────────────────────
 verification:
@@ -93,11 +95,6 @@ On missing precondition:
   Message: "Vui lòng chỉ định file hoặc module cần kiểm tra."
 ```
 
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
 ## Scope
 - ✅ Detect violations with exact file:line references
 - ✅ Classify by severity with concrete thresholds
@@ -108,12 +105,8 @@ schema_version: 2
 - ❌ Rewrite architecture
 - ❌ Touch files outside the specified scope
 
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
 ## Concrete Thresholds (Non-Negotiable)
+**Các giới hạn dưới đây được dùng để định lượng vi phạm rác mã (R-C-09) và bảo mật (R-SEC-04):**
 
 ```yaml
 function:
@@ -139,11 +132,6 @@ dependency:
   max_imports_per_file: 15  # Beyond this: likely a God File
 ```
 
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
 ## Priority Order
 
 | Priority | Check | Severity | Skip Threshold |
@@ -156,11 +144,6 @@ schema_version: 2
 | P6 | Naming convention violations | LOW | Budget < 70% |
 | P7 | Excessive imports / coupling | LOW | Budget < 80% |
 
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
 ## Workflow
 
 ### Phase 1 — Scan for Critical & High Violations
@@ -187,11 +170,6 @@ IF file line count > 300
 - All P1+P2+P3 checks done → go to Phase 2
 - Token budget < 30% → go to Phase 3 directly with PARTIAL flag
 
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
 ### Phase 2 — Scan for Medium & Low Violations
 
 **Steps:**
@@ -211,11 +189,6 @@ IF token budget < 50%
   → Skip P6+P7, go to Phase 3
 ```
 
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
 ### Phase 3 — Score & Report
 
 **Steps:**
@@ -243,11 +216,6 @@ IF score < 60 OR any CRITICAL violations
   → EXIT: FAILED — requires immediate action
 ```
 
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
 ## Confidence Model
 
 | Level | Condition | Action |
@@ -256,11 +224,6 @@ schema_version: 2
 | MEDIUM | Inferred cyclomatic complexity without tool | Note estimate |
 | LOW | Architectural smell inferred from structure | Mark as "suspected — verify manually" |
 
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
 ## Severity
 
 | Level | Definition | Example |
@@ -270,11 +233,6 @@ schema_version: 2
 | MEDIUM | DRY or SoC violation, fixable in < 1 hour | Same validation logic in 3 components |
 | LOW | Style/naming issue, non-blocking | Single-letter variable `x` outside loop |
 
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
 ## Evidence Format
 
 ```
@@ -296,22 +254,12 @@ Fix:        Extract payment logic to `processPayment()`, shipping to `scheduleSh
 Deduction:  -10 pts
 ```
 
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
 ## Retry Policy
 ```
 Audit is read-only — no retry needed.
 If file is inaccessible → skip and note in report as PARTIAL.
 ```
 
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
 ## Escalation Rules
 
 ```
@@ -323,11 +271,6 @@ Questions:
   2. Có ngưỡng cụ thể nào bạn muốn thay đổi không? (mặc định: 30 lines/function)
 ```
 
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
 ## Handoff Contract
 
 ### Consumes
@@ -347,11 +290,6 @@ schema_version: 2
 }
 ```
 
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
 ## Output Format
 
 ```
@@ -375,11 +313,6 @@ Required Actions:
 Exit Code:   [SUCCESS | PARTIAL | FAILED]
 ```
 
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
 ## Exit Codes
 
 | Code | Meaning | When |
@@ -389,13 +322,9 @@ schema_version: 2
 | BLOCKED | No target specified | Cannot audit without scope |
 | FAILED | Score < 60 or CRITICAL found | Immediate action required |
 
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
 ## References
 - Detailed thresholds with rationale: `references/thresholds.md`
+- Anti-Patterns Blacklist: `references/anti-patterns.md`
 
 ---
 

package/.agents/skills/qk-engineering-standard/references/anti-patterns.md

@@ -0,0 +1,121 @@
+# 🚫 Anti-Patterns Blacklist — Engineering Standard
+
+> Đây là danh sách đỏ. AI Agent **KHÔNG ĐƯỢC PHÉP** tạo ra code vi phạm các mục dưới đây,
+> trừ khi người dùng yêu cầu tường minh và chấp nhận rủi ro (kèm comment giải thích lý do).
+> Mục tiêu: chống "code rác" (slop), giữ codebase dễ bảo trì, an toàn kiểu dữ liệu, và có thể mở rộng.
+
+---
+
+## 1. TypeScript
+
+| Cấm | Thay bằng |
+|---|---|
+| `any` tùy tiện | `unknown` + type guard, hoặc định nghĩa type/interface cụ thể |
+| `// @ts-ignore` không có lý do | `// @ts-expect-error: <lý do cụ thể>` chỉ khi thực sự cần thiết tạm thời |
+| Ép kiểu ép buộc (`as unknown as X`, `!` non-null assertion tràn lan) | Type guard, Zod/valibot schema validation ở boundary (API, form input) |
+| Kiểu `object`, `Function` mơ hồ | Định nghĩa interface/type rõ ràng, dùng generic khi cần tái sử dụng |
+| Enum số học không rõ nghĩa | `as const` object hoặc string union type |
+| Interface/type định nghĩa lặp lại nhiều nơi | Tách vào `types/` hoặc co-locate cạnh feature, export dùng chung |
+
+**Ví dụ SAI:**
+```ts
+function handleData(data: any) {
+  return data.value; // không có gì đảm bảo `value` tồn tại
+}
+```
+
+**Ví dụ ĐÚNG:**
+```ts
+interface ApiResponse {
+  value: string;
+}
+function handleData(data: ApiResponse) {
+  return data.value;
+}
+```
+
+---
+
+## 2. React / UI
+
+| Cấm | Thay bằng |
+|---|---|
+| Mutate state trực tiếp (`state.items.push(...)`, `state.x = y`) | Tạo object/array mới (`setState(prev => [...prev, item])`) hoặc dùng Immer |
+| Spaghetti component: logic nghiệp vụ + fetch + JSX trộn chung 1 hàm khổng lồ | Tách Custom Hook (logic) khỏi Component (JSX thuần) — xem `component-cookbook.md` |
+| Inline style (`style={{color: 'red'}}`) thay vì Design Token | Dùng class Tailwind ánh xạ token (`text-danger`), hoặc CSS variable đã định nghĩa |
+| `useEffect` dùng để đồng bộ state phái sinh (derived state) | Tính toán trực tiếp trong render, hoặc `useMemo` nếu tốn kém |
+| `useEffect` không có dependency array hoặc dependency sai (gây vòng lặp/render thừa) | Khai báo đầy đủ dependency, dùng ESLint `react-hooks/exhaustive-deps` |
+| Component nhận > 5-6 props rời rạc không liên quan | Gom nhóm thành object prop, hoặc tách nhỏ component |
+| Key trong list dùng `index` khi list có thể reorder/filter | Dùng ID ổn định (`item.id`) |
+| Hardcode text UI trực tiếp (không chuẩn bị cho i18n) khi dự án có đa ngôn ngữ | Đưa qua lớp i18n / constants |
+| Bỏ qua trạng thái loading / error / empty khi render dữ liệu async | Luôn xử lý đủ 3 trạng thái: loading, error, empty, success |
+| Bỏ ARIA attributes / semantic HTML (`<div onClick>` thay vì `<button>`) | Dùng đúng thẻ semantic, thêm `aria-*` khi cần |
+
+---
+
+## 3. Kiến trúc (Architecture)
+
+| Cấm | Thay bằng |
+|---|---|
+| Import chéo tạo circular dependency giữa các module | Tách shared logic ra module trung lập (`shared/`, `lib/`), kiểm tra bằng `madge` hoặc lint rule |
+| Gọi API trực tiếp trong UI Component (`fetch()` ngay trong JSX/handler của component trình bày) | Tách vào `services/` hoặc data-layer hook (`useXxxQuery`) — component chỉ gọi hook |
+| Business logic nằm trong Component thay vì layer riêng | Tách `hooks/`, `utils/`, `services/` — Component chỉ điều phối |
+| Global mutable state ngoài store chính thức (biến module-level bị mutate) | Dùng Context/Zustand store có kiểm soát |
+| Magic number/string rải rác trong code | Đưa vào `constants.ts` |
+| Folder structure lộn xộn (component, hook, style của cùng 1 feature nằm rải rác nhiều nơi) | Co-location theo feature: `features/xxx/{components,hooks,services,types}` |
+| Duplicate logic dán đè (copy-paste) ở nhiều nơi thay vì tái sử dụng | Trích xuất thành hàm/hook dùng chung |
+| Commit code có `console.log` debug, code chết (dead code), TODO không có ticket | Dọn dẹp trước khi merge, hoặc gắn issue tracking rõ ràng |
+
+---
+
+## 4. React Query / TanStack Query
+
+| Cấm | Thay bằng |
+|---|---|
+| Copy dữ liệu từ `useQuery` vào `useState` cục bộ (`const [x,setX]=useState(); useEffect(()=>setX(data),[data])`) | Dùng thẳng `data` trả về từ `useQuery` — nó đã là single source of truth |
+| Tự quản lý loading/error bằng `useState` song song với `useQuery` | Dùng `isPending`/`isError`/`isFetching` có sẵn |
+| `queryKey` viết tay rải rác nhiều nơi (`["user", id]` gõ lại ở 5 file khác nhau) | Tập trung vào 1 file `queryKeys.ts` theo factory pattern |
+| Gọi `queryFn` chứa logic biến đổi dữ liệu phức tạp (mapping, tính toán nặng) | `queryFn` chỉ fetch thô; biến đổi dữ liệu qua `select` option hoặc hook riêng |
+| Dùng `useQuery` cho dữ liệu thuần client (không đến từ server) | Đó là client state → dùng `useState`/Context/Zustand |
+| `staleTime: 0` mặc định cho mọi query, gây refetch liên tục không cần thiết | Đặt `staleTime` phù hợp với tần suất đổi của dữ liệu |
+| `invalidateQueries` tràn lan sau mọi mutation dù chỉ đổi 1 field nhỏ | Ưu tiên `setQueryData` cập nhật cache trực tiếp khi biết chính xác dữ liệu mới |
+| Gọi `useQuery`/`useMutation` bên trong service/utility function (không phải React component/hook) | Hooks của React Query chỉ được gọi trong component hoặc custom hook |
+| Nuốt lỗi mutation im lặng (không xử lý `onError`, không hiển thị gì cho user) | Luôn xử lý `onError` hoặc kiểm tra `error` để phản hồi UI |
+| Trộn React Query với Redux/Zustand để lưu cùng một loại server-state ở 2 nơi | Server-state chỉ sống trong React Query cache, không đồng bộ ngược vào store khác |
+
+---
+
+## 5. TanStack Router / Table / Form / Virtual / Store
+
+| Cấm | Thay bằng |
+|---|---|
+| Định nghĩa route bằng object thường, params/search không có type (dễ gõ sai tên param) | TanStack Router — dùng `createFileRoute`/`createRoute`, params & search suy kiểu tự động |
+| Fetch dữ liệu trang trong component sau khi route đã mount (waterfall: chờ route load → mới fetch) | Prefetch trong `loader` của route (`loader: ({context}) => context.queryClient.ensureQueryData(...)`) |
+| Đọc/ghi query string bằng `URLSearchParams` tay khi đã dùng TanStack Router | Dùng `useSearch`/`Route.useSearch()` có type-safe, validate qua schema (Zod) |
+| Tự viết sort/filter/pagination state rời rạc bằng nhiều `useState` cho bảng dữ liệu | TanStack Table — quản lý qua `state` + `onXxxChange`, tách rõ khỏi cách render |
+| Trộn logic tính toán dữ liệu bảng (sort/filter) vào trong JSX render row | Định nghĩa `columns` + xử lý qua Table instance (`table.getRowModel()`), JSX chỉ map render |
+| Render toàn bộ hàng trăm/nghìn row DOM node cùng lúc trong Table/List | Kết hợp TanStack Virtual (`useVirtualizer`) để chỉ render row trong viewport |
+| Tự quản lý field, error, touched bằng `useState` rời rạc cho form nhiều field | TanStack Form (`useForm`, `field.state`) — validate đồng bộ/bất đồng bộ tập trung, tránh re-render toàn form mỗi keystroke |
+| Validate form chỉ ở client, không đồng bộ schema với backend | Dùng chung 1 schema (Zod) cho cả TanStack Form validator và backend validation |
+| Đưa state UI đơn giản (theme, sidebar open/close) vào Redux/Context nặng nề | TanStack Store (hoặc `useState` cục bộ) cho state nhỏ gọn, framework-agnostic |
+| Gọi trực tiếp DOM API để đo scroll/kích thước item thay vì dùng API của Virtual | Dùng `measureElement`/`estimateSize` của TanStack Virtual, tránh đọc/ghi layout thủ công gây jank |
+
+---
+
+## 6. Nguyên tắc review nhanh (Checklist trước khi xuất code)
+
+- [ ] Không còn `any`/`ts-ignore` không giải thích
+- [ ] Component tách rõ Logic (hook) / UI (JSX thuần)
+- [ ] State được update immutable
+- [ ] Không gọi API trực tiếp trong component trình bày
+- [ ] Có xử lý loading/error/empty cho dữ liệu async
+- [ ] Dùng Design Token, không inline style tùy tiện
+- [ ] Không có circular dependency
+- [ ] Không có console.log / code chết còn sót lại
+- [ ] Server-state đi qua React Query, không bị copy lại vào `useState`/store khác
+- [ ] `queryKey` lấy từ factory tập trung, không viết tay rải rác
+- [ ] Bảng/list dữ liệu lớn dùng TanStack Table/Virtual thay vì tự viết + render toàn bộ DOM
+- [ ] Form nhiều field dùng TanStack Form (hoặc RHF nếu đã có sẵn), không rời rạc `useState`
+- [ ] Route params/search có type-safe qua TanStack Router, không parse tay
+
+> Ghi chú: Nếu dự án dùng Redux thay vì Context/Zustand, áp dụng thêm quy tắc "không dispatch action trực tiếp trong component con sâu — đi qua thunk/selector có kiểm soát". Redux (nếu có) chỉ nên giữ **client state**; server-state luôn thuộc về React Query.