ai-developer-skill-os 8.1.7 → 8.1.10

package/.agents/README.md

@@ -1,8 +1,8 @@
-# 🚀 AI Developer Skill OS (ai-developer-skill-os) v8.1.4
+# 🚀 AI Developer Skill OS (ai-developer-skill-os) v8.1.7
 
-> **v8.1.4 "Agent Engineering OS + Design Intelligence"**
+> **v8.1.7 "Agent Engineering OS + Design Intelligence"**
 
-Hệ sinh thái AI Developer Skill OS đã lột xác hoàn toàn. Từ một bộ "công cụ phân tán" (Toolbox) ở V7, phiên bản V8.1.4 được thiết kế như một **Hệ điều hành khép kín (Agent Engineering OS)**, sở hữu năng lực giám sát, bảo vệ ranh giới quyết định (Decision Boundaries) và được trang bị thêm tầng **Design Intelligence**.
+Hệ sinh thái AI Developer Skill OS đã lột xác hoàn toàn. Từ một bộ "công cụ phân tán" (Toolbox) ở V7, phiên bản V8.1.7 được thiết kế như một **Hệ điều hành khép kín (Agent Engineering OS)**, sở hữu năng lực giám sát, bảo vệ ranh giới quyết định (Decision Boundaries) và được trang bị thêm tầng **Design Intelligence**.
 
 ---
 

package/.agents/skills/qk-code-review/SKILL.md

@@ -0,0 +1,189 @@
+---
+# ── Identity ───────────────────────────────────────────────
+name: qk-code-review
+version: 8.0.0
+status: stable
+description: "Elite AI/Code Review System: Kiểm toán, Review code và cấu hình AI với tư duy Architect, áp dụng 4-Phase Review."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+
+# ── V8: Classification ─────────────────────────────────────
+type: utility
+
+intent:
+  - code-review
+  - quality-assurance
+  - architecture-review
+  - ai-config-audit
+
+complexity:
+  level: high
+  criteria:
+    files_affected: "1-15"
+    has_behavior_change: false
+    has_external_dependency: false
+    has_breaking_change: false
+
+triggers:
+  - "review code"
+  - "code review"
+  - "kiểm tra code"
+  - "đánh giá code"
+  - "review skin"
+  - "review rule"
+  - "review ai"
+
+selection:
+  priority: high
+  confidence_threshold: 0.85
+
+# ── V8: References ─────────────────────────────────────────
+workflow: code-review
+
+rules:
+  - global
+
+tools:
+  - filesystem
+
+related_skills:
+  - qk-validation-gate
+  - qk-engineering-standard
+  - qk-project-health
+
+knowledge_scope:
+  owns:
+    - code-review-standards
+    - ai-configuration-review
+    - feedback-delivery
+  references:
+    - architecture
+    - security-best-practices
+
+# ── V8: Verification ───────────────────────────────────────
+verification:
+  required: true
+  strategy: review
+
+# ── V8: Knowledge links ────────────────────────────────────
+examples: []
+learnings: []
+
+# ── V7 Runtime ─────────────────────────────────────────────
+execution_mode: deterministic
+cost: high
+latency: medium
+risk: low
+side_effects: read_only
+produces: [report]
+consumes: [source-code, rules, workflows]
+
+token_budget:
+  max_files_read: 10
+  max_lines_per_read: 300
+  max_shell_commands: 2
+  stop_early: false
+
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+---
+
+# qk-code-review — Elite Review System
+
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
+Biến quá trình Code Review từ "bắt bẻ" (gatekeeping) thành "chia sẻ tri thức" (knowledge sharing) thông qua phản hồi mang tính xây dựng, phân tích có hệ thống và hợp tác cải tiến.
+
+---
+
+## Preconditions
+
+- [ ] Xác định rõ đối tượng cần review: Mã nguồn phần mềm (React, Java, etc.) hay Cấu hình AI (Skin, Rules, Workflows).
+- [ ] Cung cấp ngữ cảnh hoặc mục tiêu của đoạn code/cấu hình cần review.
+
+```
+On missing precondition → EXIT: BLOCKED
+Report: "Missing: Vui lòng cung cấp ngữ cảnh hoặc chỉ định rõ file cần review."
+```
+
+---
+
+## Dynamic Context Loading (Tải Ngữ Cảnh Động)
+
+> **BẮT BUỘC:** Trước khi bắt đầu review, Agent phải sử dụng tool `view_file` để nạp các bí kíp tương ứng từ thư mục `references/` nhằm đảm bảo chất lượng review sâu sát nhất.
+
+- **Nếu review AI Config (Skin, Rule, Workflow):**
+  - Mở đọc: `references/ai/v8-schema-validation.md` và `references/ai/ai-anti-patterns.md`.
+- **Nếu review Code Phần mềm (VD: React, Java, Go, v.v.):**
+  - Nhận diện ngôn ngữ/framework.
+  - Mở đọc file tương ứng: `references/languages/[tên-ngôn-ngữ].md` (VD: `react.md`, `java.md`).
+- **Nếu review ở mức tổng quát hoặc PR lớn (Cross-cutting):**
+  - Đọc thêm: `references/cross-cutting/architecture-review-guide.md`, hoặc các file về security/performance nếu phù hợp.
+
+---
+
+## 4-Phase Review Process
+
+Là một AI Architect, quá trình review phải tuân thủ nghiêm ngặt 4 giai đoạn sau:
+
+### Phase 1: Context Gathering & Loading (Thu thập & Nạp Ngữ Cảnh)
+- Đọc file mô tả (PR, Issue) hoặc yêu cầu của người dùng.
+- **Thực thi Dynamic Context Loading** (đọc các file reference cần thiết như đã định nghĩa ở trên).
+
+### Phase 2: High-Level Review (Kiến trúc & Chuẩn mực)
+- **Đối với AI Config:** Kiểm tra cấu trúc V8 (Identity, Intent, Complexity, Triggers). 
+- **Đối với Code Phần mềm:** Kiểm tra SOLID, Coupling/Cohesion, Performance, Security (Tham chiếu theo `cross-cutting` guides).
+
+### Phase 3: Deep-dive & Logic Review (Phân tích chi tiết)
+- **Đối với AI Config:** Kiểm tra rủi ro "ảo giác" (hallucination), token abuse, side-effects, stop_early.
+- **Đối với Code Phần mềm:** Rà soát edge cases, lỗi logic chuyên sâu theo từng ngôn ngữ (Tham chiếu theo `languages` guides).
+
+### Phase 4: Summary & Decision (Tổng hợp & Quyết định)
+- Đưa ra báo cáo theo `Output Format`.
+- Gắn nhãn `Severity Tags` rõ ràng.
+
+---
+
+## Feedback Principles (Nguyên tắc Phản hồi)
+
+- **Collaborative Language (Ngôn từ hợp tác)**: Thay vì ra lệnh ("Sửa cái này thành X", "Bỏ dòng này đi"), hãy dùng câu hỏi gợi mở ("Nếu chúng ta dùng X ở đây thì có tối ưu hiệu năng hơn không?", "Có vẻ logic này bị lặp, chúng ta extract nó ra hàm riêng được không?").
+- **Differentiate Severity (Phân biệt mức độ)**: Bắt buộc sử dụng các nhãn sau để phân loại mức độ phản hồi:
+  - 🔴 `[blocking]` - Lỗi nghiêm trọng (VD: Security flaw, thiếu token_budget). Bắt buộc phải sửa.
+  - 🟡 `[important]` - Lỗi quan trọng (VD: Performance leak, trigger quá rộng). Nên sửa hoặc cần thảo luận.
+  - 🟢 `[nit]` - Cải thiện nhỏ (VD: Lỗi chính tả, format, naming). Không bắt buộc.
+  - 💡 `[suggestion]` - Cách tiếp cận hoặc thư viện thay thế để tham khảo.
+  - 📚 `[learning]` - Giải thích nguyên lý (Why) để chia sẻ kiến thức, không yêu cầu hành động.
+  - 🎉 `[praise]` - Lời khen cho đoạn code / logic thiết kế tốt.
+
+---
+
+## Output Format
+
+```markdown
+## qk-code-review Report
+─────────────────────────────────────────────────
+**Target:** [Tên file / Chức năng]
+**Status:** SUCCESS | BLOCKED | FAILED | PARTIAL
+
+### 📊 Executive Summary
+[1-2 câu tóm tắt chất lượng tổng thể của mã nguồn/cấu hình. VD: "Kiến trúc rõ ràng, nhưng tiềm ẩn rủi ro lặp vô hạn ở dòng 45."]
+
+### 🔍 Findings & Recommendations
+
+[Nhóm các findings theo mức độ nghiêm trọng giảm dần. LUÔN đính kèm snippet / file line nếu có thể]
+
+- 🔴 `[blocking]`: [Vấn đề nghiêm trọng]
+  - *Location*: `file.ts:L45`
+  - *Feedback*: [Câu hỏi/Gợi ý sửa chữa]
+  
+- 🟡 `[important]`: [Vấn đề quan trọng]
+- 💡 `[suggestion]`: [Gợi ý cải thiện]
+- 🟢 `[nit]`: [Góp ý nhỏ]
+- 🎉 `[praise]`: [Khen ngợi]
+
+### 🛠️ Suggested Fixes (Optional)
+[Cung cấp Code diff hoặc YAML chuẩn xác để user dễ dàng copy & paste. TUYỆT ĐỐI KHÔNG tự sửa file nếu user chưa yêu cầu]
+
+### ✅ Verdict
+- [ ] Approve (Có thể merge/deploy ngay)
+- [ ] Changes Requested (Cần sửa các mục `[blocking]`)
+- [ ] Comment (Chỉ là gợi ý, quyền quyết định ở user)
+```

package/.agents/skills/qk-code-review/references/ai/ai-anti-patterns.md

@@ -0,0 +1,28 @@
+# AI Agent Anti-Patterns
+
+Khi review các cấu hình AI (Skills, Rules, Workflows), hãy lưu ý các "Code Smells" hoặc Anti-patterns phổ biến sau đây:
+
+## 1. Mất kiểm soát Token (Token Abuse)
+- **Dấu hiệu**: Không định nghĩa `token_budget`, hoặc định nghĩa `max_files_read: 50`, `max_lines_per_read: 1000`.
+- **Rủi ro**: Agent sẽ đọc lướt quá nhiều file, làm cạn kiệt context window, dẫn đến "ảo giác" (hallucination) và tốn kém chi phí.
+- **Cách khắc phục**: Ép buộc một giới hạn cứng hợp lý (VD: `max_files_read: 3`, `max_lines_per_read: 150`). Bắt buộc agent dùng `grep` thay vì `read_file` toàn bộ.
+
+## 2. Phạm vi quá rộng (Scope Creep)
+- **Dấu hiệu**: Phần `Scope` hoặc `Intent` bao gồm quá nhiều chức năng không liên quan (VD: Vừa viết code, vừa test, vừa deploy, vừa viết docs).
+- **Rủi ro**: Agent mất tập trung, không biết ưu tiên tác vụ nào, thường xuyên bỏ dở công việc giữa chừng.
+- **Cách khắc phục**: Áp dụng nguyên tắc Single Responsibility. Tách thành nhiều skill nhỏ và dùng Orchestrator hoặc Workflow để phối hợp. Yêu cầu làm rõ mục `This skill does NOT`.
+
+## 3. Lạm dụng quyền thực thi (Unsafe Side-Effects)
+- **Dấu hiệu**: Cấu hình `side_effects: run_commands` nhưng không có Verification Gate hoặc không bắt buộc user approval.
+- **Rủi ro**: Có thể vô tình xóa file (`rm -rf`), chạy mã độc, hoặc làm hỏng môi trường phát triển của User.
+- **Cách khắc phục**: Đánh giá Risk level (High/Medium). Nếu có `run_commands`, phải ép buộc chạy ở môi trường giả lập (sandbox) hoặc chỉ sinh ra script để user tự chạy (Dry-run mode).
+
+## 4. Thiếu điều kiện tiền quyết (Missing Preconditions)
+- **Dấu hiệu**: Bỏ trống phần `Preconditions`, agent lao vào thực thi ngay lập tức.
+- **Rủi ro**: Chạy sai ngữ cảnh, sửa bậy bạ vào mã nguồn khi chưa đủ thông tin, tốn token vô ích.
+- **Cách khắc phục**: Bắt buộc phải có `EXIT: BLOCKED` nếu thiếu thông tin đầu vào quan trọng (ví dụ: thiếu file config, thiếu đường dẫn dự án).
+
+## 5. Prompt mang tính "Bức ép" (Aggressive Prompts)
+- **Dấu hiệu**: Dùng nhiều từ in hoa "MUST", "DO NOT", "NEVER" nhưng thiếu giải thích nguyên lý (Why).
+- **Rủi ro**: LLM (Large Language Model) thường bị over-constrained (bị kìm kẹp quá mức), dẫn đến việc từ chối trả lời (refusal) hoặc phản hồi cứng nhắc, mất đi khả năng sáng tạo.
+- **Cách khắc phục**: Chuyển từ "Cấm làm X" sang "Chỉ làm X khi Y, vì Z". Cung cấp `examples` cụ thể thay vì cấm đoán suông.

package/.agents/skills/qk-code-review/references/ai/v8-schema-validation.md

@@ -0,0 +1,65 @@
+# V8 Schema Validation Guide
+
+Tài liệu này dùng để đối chiếu khi review các file `SKILL.md` hoặc các file cấu hình AI khác trong dự án. Đảm bảo mọi cấu hình tuân thủ chặt chẽ định dạng và kiến trúc của V8 Skin.
+
+## 1. Frontmatter (YAML Metadata) Bắt buộc
+
+Mọi file `SKILL.md` **phải** bắt đầu bằng khối YAML chứa các thông tin sau:
+
+```yaml
+---
+# ── Identity ───────────────────────────────────────────────
+name: qk-[tên-skill]          # Bắt buộc có tiền tố qk-
+version: [X.Y.Z]              # Phiên bản semantic
+status: [stable/beta/draft]
+description: "[Mô tả ngắn gọn bằng tiếng Việt]"
+platforms: [danh sách platform hỗ trợ]
+
+# ── V8: Classification ─────────────────────────────────────
+type: [utility/capability/orchestrator]
+intent:
+  - [mục-đích-chính]
+
+complexity:
+  level: [low/medium/high/critical]
+  criteria:
+    files_affected: "[range]"
+    # ... các criteria khác
+
+triggers:                     # Rất quan trọng, bắt buộc có
+  - "[từ khóa 1]"
+  - "[từ khóa 2]"
+
+# ── V7 Runtime ─────────────────────────────────────────────
+# Phần này cấu hình cách Agent thực thi
+side_effects: [read_only/edit_files/run_commands]
+produces: [...]
+consumes: [...]
+
+token_budget:                 # Bắt buộc để tránh cạn kiệt Token
+  max_files_read: [số]
+  max_lines_per_read: [số]
+  max_shell_commands: [số]
+  stop_early: [true/false]
+
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+---
+```
+
+## 2. Các phần Body (Markdown) Bắt buộc
+
+1. **Title & Language Rule**: Ngay sau frontmatter, phải có tiêu đề và rule ngôn ngữ chuẩn:
+   ```markdown
+   > **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+   ```
+2. **Preconditions**: Định nghĩa rõ điều kiện tiên quyết để skill này có thể chạy. Phải mô tả hành động (thường là `EXIT: BLOCKED`) nếu thiếu thông tin.
+3. **Scope (What it does / What it does NOT)**: Phải rõ ràng giới hạn của skill. Đặc biệt phần `Does NOT` để ngăn scope creep.
+4. **Output Format**: Format chuẩn mà AI sẽ phản hồi lại cho user sau khi thực thi.
+
+## 3. Checklist khi Review
+
+- [ ] Tiền tố tên có đúng chuẩn (`qk-`) không?
+- [ ] Triggers có bao phủ đủ các cách gọi thông dụng không? Có bị trùng lặp với skill khác không?
+- [ ] `token_budget` có được cấu hình hợp lý so với `complexity` không? (Ví dụ: complexity low nhưng lại cho đọc 50 files là sai).
+- [ ] Nếu `side_effects` là `run_commands` hoặc `edit_files`, phần Preconditions đã đủ chặt chẽ chưa?
+- [ ] Format đầu ra (Output format) có chuẩn mực và chuyên nghiệp không?

package/.agents/skills/qk-code-review/references/cross-cutting/architecture-review-guide.md

@@ -0,0 +1,212 @@
+# Architecture Review Guide
+
+Hướng dẫn đánh giá thiết kế kiến trúc, giúp xác định xem kiến trúc của mã nguồn có hợp lý và thiết kế có chuẩn xác hay không.
+
+## Kiểm tra nguyên tắc SOLID
+
+### S - Single Responsibility Principle (SRP - Nguyên tắc đơn trách nhiệm)
+
+**Kiểm tra trọng tâm:**
+- Class/Module này có chỉ duy nhất một lý do để thay đổi không?
+- Các phương thức trong Class có cùng phục vụ cho một mục đích không?
+- Nếu phải mô tả Class này cho một người không rành kỹ thuật, bạn có thể nói rõ trong một câu không?
+
+**Dấu hiệu nhận biết (Code Smells):**
+```text
+⚠️ Tên Class chứa các từ mang tính chung chung như "And", "Manager", "Handler", "Processor".
+⚠️ Một Class vượt quá 200-300 dòng code.
+⚠️ Class có hơn 5-7 phương thức public.
+⚠️ Các phương thức khác nhau thao tác trên các tập dữ liệu hoàn toàn khác nhau.
+```
+
+**Câu hỏi Review:**
+- "Class này chịu trách nhiệm những việc gì? Có thể chia nhỏ được không?"
+- "Nếu yêu cầu X thay đổi, những phương thức nào cần sửa? Nếu yêu cầu Y thay đổi thì sao?"
+
+### O - Open/Closed Principle (OCP - Nguyên tắc đóng/mở)
+
+**Kiểm tra trọng tâm:**
+- Khi thêm tính năng mới, có cần phải sửa đổi code hiện tại không?
+- Có thể thêm hành vi mới thông qua việc mở rộng (inheritance, composition) không?
+- Có tồn tại quá nhiều câu lệnh `if/else` hoặc `switch` để xử lý các type (loại) khác nhau không?
+
+**Dấu hiệu nhận biết:**
+```text
+⚠️ Chuỗi switch/if-else dài để xử lý các loại (types) khác nhau.
+⚠️ Thêm tính năng mới đòi hỏi phải sửa đổi core class.
+⚠️ Rải rác các lệnh kiểm tra kiểu dữ liệu (instanceof, typeof) khắp mọi nơi.
+```
+
+**Câu hỏi Review:**
+- "Nếu muốn thêm một type X mới, chúng ta phải sửa những file nào?"
+- "Khối lệnh switch này có phình to ra khi chúng ta có thêm type mới không?"
+
+### L - Liskov Substitution Principle (LSP - Nguyên tắc thay thế Liskov)
+
+**Kiểm tra trọng tâm:**
+- Subclass (lớp con) có thể thay thế hoàn toàn cho Parent class (lớp cha) khi sử dụng không?
+- Subclass có làm thay đổi hành vi dự kiến của các phương thức ở Parent class không?
+- Subclass có throw ra các exception mà Parent class chưa từng khai báo không?
+
+**Dấu hiệu nhận biết:**
+```text
+⚠️ Ép kiểu tường minh (Explicit casting).
+⚠️ Phương thức ở Subclass ném ra lỗi `NotImplementedException`.
+⚠️ Phương thức ở Subclass để trống hoặc chỉ có `return`.
+⚠️ Nơi sử dụng Base class bắt buộc phải kiểm tra type cụ thể của nó.
+```
+
+**Câu hỏi Review:**
+- "Nếu dùng Subclass thay cho Parent class, đoạn code gọi (caller) có cần phải thay đổi không?"
+- "Hành vi của phương thức này trong Subclass có tuân thủ đúng contract của Parent class không?"
+
+### I - Interface Segregation Principle (ISP - Nguyên tắc phân tách Interface)
+
+**Kiểm tra trọng tâm:**
+- Interface đã đủ nhỏ và tập trung chưa?
+- Class implement (thực thi) có bị ép buộc phải code những phương thức mà nó không cần không?
+- Client có phụ thuộc vào những phương thức mà nó không hề dùng tới không?
+
+**Dấu hiệu nhận biết:**
+```text
+⚠️ Interface có hơn 5-7 phương thức.
+⚠️ Class implement có các phương thức rỗng hoặc ném `NotImplementedException`.
+⚠️ Tên Interface quá rộng (IManager, IService).
+⚠️ Các Client khác nhau chỉ sử dụng một phần phương thức của Interface.
+```
+
+**Câu hỏi Review:**
+- "Tất cả các phương thức của Interface này có thực sự được dùng bởi từng Class implement không?"
+- "Có thể chia Interface lớn này thành các Interface nhỏ, chuyên biệt hơn không?"
+
+### D - Dependency Inversion Principle (DIP - Nguyên tắc đảo ngược phụ thuộc)
+
+**Kiểm tra trọng tâm:**
+- Module cấp cao có phụ thuộc vào Abstraction (trừu tượng) thay vì Implementation (thực thi chi tiết) không?
+- Có sử dụng Dependency Injection thay vì trực tiếp `new` Object không?
+- Abstraction có được định nghĩa bởi Module cấp cao thay vì Module cấp thấp không?
+
+**Dấu hiệu nhận biết:**
+```text
+⚠️ Module cấp cao trực tiếp `new` các Class cụ thể của Module cấp thấp.
+⚠️ Import thẳng Class thực thi thay vì Interface/Abstract class.
+⚠️ Cấu hình và chuỗi kết nối (connection strings) bị hardcode trong business logic.
+⚠️ Rất khó để viết Unit Test cho một Class cụ thể.
+```
+
+**Câu hỏi Review:**
+- "Các phụ thuộc (dependencies) của Class này có thể được mock khi viết test không?"
+- "Nếu muốn đổi sang một Database/API khác, sẽ phải sửa bao nhiêu chỗ?"
+
+---
+
+## Nhận diện các Anti-patterns Kiến trúc
+
+### Các Anti-patterns Chí mạng (Fatal)
+
+| Anti-pattern | Dấu hiệu nhận biết (Signals) | Hệ quả |
+|--------|----------|------|
+| **Big Ball of Mud** | Không có ranh giới module rõ ràng, bất kỳ code nào cũng có thể gọi đoạn code khác. | Khó hiểu, khó sửa, khó test. |
+| **God Object** | Một Class gánh quá nhiều trách nhiệm, biết quá nhiều, làm quá nhiều. | Coupling cao, khó tái sử dụng và test. |
+| **Spaghetti Code** | Luồng điều khiển rối rắm, lạm dụng `goto` hoặc lồng (nesting) quá sâu, khó theo dõi đường thực thi. | Khó bảo trì. |
+| **Lava Flow** | Code cổ đại không ai dám đụng vào, thiếu tài liệu và test. | Tích tụ nợ kỹ thuật (Tech Debt). |
+
+### Các Anti-patterns Thiết kế (Design)
+
+| Anti-pattern | Dấu hiệu nhận biết (Signals) | Lời khuyên |
+|--------|----------|------|
+| **Golden Hammer** | Dùng chung một công nghệ/design pattern cho tất cả mọi vấn đề. | Chọn giải pháp phù hợp với từng bài toán. |
+| **Gas Factory (Over-engineering)** | Giải quyết vấn đề đơn giản bằng giải pháp phức tạp, lạm dụng Design patterns. | Tuân thủ YAGNI, làm từ đơn giản đến phức tạp. |
+| **Boat Anchor** | Viết code "phòng hờ cho tương lai" nhưng hiện tại không dùng tới. | Xóa code không dùng, khi nào cần thì viết lại. |
+| **Copy-Paste Programming** | Một logic xuất hiện ở nhiều nơi. | Đưa thành phương thức chung hoặc module chung. |
+
+---
+
+## Đánh giá Coupling (Độ kết dính) và Cohesion (Độ gắn kết)
+
+### Các loại Coupling (Từ Tốt đến Xấu)
+
+| Loại | Mô tả | Ví dụ |
+|------|------|------|
+| **Message Coupling** ✅ | Truyền dữ liệu qua tham số | `calculate(price, quantity)` |
+| **Data Coupling** ✅ | Chia sẻ cấu trúc dữ liệu đơn giản | `processOrder(orderDTO)` |
+| **Stamp Coupling** ⚠️ | Truyền cấu trúc dữ liệu phức tạp nhưng chỉ xài 1 phần | Truyền cả Object `User` nhưng chỉ dùng `name` |
+| **Control Coupling** ⚠️ | Truyền cờ (flags) điều khiển hành vi | `process(data, isAdmin=true)` |
+| **Common Coupling** ❌ | Chia sẻ biến toàn cục (global state) | Nhiều module cùng đọc/ghi chung một global state |
+| **Content Coupling** ❌ | Truy cập trực tiếp vào bên trong module khác | Thao tác trực tiếp với private properties của class khác |
+
+### Các loại Cohesion (Từ Tốt đến Xấu)
+
+| Loại | Mô tả | Đánh giá |
+|------|------|------|
+| **Functional Cohesion** | Mọi thành phần cùng thực hiện MỘT nhiệm vụ duy nhất | ✅ Tốt nhất |
+| **Sequential Cohesion** | Output của bước này là Input của bước sau | ✅ Tốt |
+| **Communicational Cohesion** | Thao tác trên cùng một cấu trúc dữ liệu | ⚠️ Chấp nhận được |
+| **Temporal Cohesion** | Các tác vụ thực thi cùng một thời điểm | ⚠️ Khá kém |
+| **Logical Cohesion** | Có liên quan về mặt logic nhưng khác biệt chức năng | ❌ Kém |
+| **Coincidental Cohesion** | Không hề có sự liên quan nào | ❌ Tệ nhất |
+
+---
+
+## Đánh giá Clean Architecture (Kiến trúc phân lớp)
+
+### Cấu trúc các Lớp
+
+```text
+┌─────────────────────────────────────┐
+│         Frameworks & Drivers        │ ← Lớp ngoài cùng: Web, DB, UI
+├─────────────────────────────────────┤
+│         Interface Adapters          │ ← Controllers, Gateways, Presenters
+├─────────────────────────────────────┤
+│          Application Layer          │ ← Use Cases, Application Services
+├─────────────────────────────────────┤
+│            Domain Layer             │ ← Entities, Domain Services
+└─────────────────────────────────────┘
+          ↑ Hướng phụ thuộc (Dependency Rule) CHỈ ĐƯỢC hướng vào trong ↑
+```
+
+### Quy tắc Phụ thuộc (Dependency Rule)
+
+**QUY TẮC CỐT LÕI: Mã nguồn chỉ được phép phụ thuộc hướng vào lớp bên trong.**
+
+```typescript
+// ❌ VI PHẠM: Domain layer phụ thuộc vào Infrastructure
+// domain/User.ts
+import { MySQLConnection } from '../infrastructure/database';
+
+// ✅ CHUẨN XÁC: Domain layer định nghĩa Interface, Infrastructure thực thi nó
+// domain/UserRepository.ts (Interface)
+interface UserRepository {
+  findById(id: string): Promise<User>;
+}
+
+// infrastructure/MySQLUserRepository.ts (Implementation)
+class MySQLUserRepository implements UserRepository {
+  findById(id: string): Promise<User> { /* ... */ }
+}
+```
+
+### Checklist Đánh giá
+- [ ] Lớp **Domain** có dính líu gì tới các phụ thuộc bên ngoài (DB, HTTP, File system) không?
+- [ ] Lớp **Application** có thao tác trực tiếp với DB hay gọi external API không?
+- [ ] Lớp **Controller** có chứa Business Logic không?
+- [ ] Có tồn tại việc gọi vượt lớp (VD: UI gọi thẳng Repository) không?
+
+---
+
+## Checklist Nhanh (5 phút review)
+
+```markdown
+□ Hướng phụ thuộc có chính xác không? (Lớp ngoài gọi lớp trong).
+□ Có bị Dependency Cycle (phụ thuộc vòng tròn) không?
+□ Business Logic cốt lõi đã tách bạch khỏi UI/Framework/Database chưa?
+□ Có vi phạm nguyên tắc SOLID không?
+□ Có các Anti-patterns lộ liễu nào không?
+```
+
+### Red Flags 🔴 (Bắt buộc sửa)
+- God Object: Class lớn hơn 1000 dòng.
+- Circular Dependency: A → B → C → A.
+- Tầng Domain chứa thư viện của Framework.
+- Hardcode Config / API Keys trong source code.
+- Gọi External Services mà không qua Interface.