ai-developer-skill-os 9.1.2 → 9.3.0

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

@@ -1,8 +1,8 @@
----
+---
 name: qk-refactor
-version: 9.1.0
+version: 9.2.0
 status: stable
-description: "Tái cấu trúc và dọn dẹp mã nguồn để dễ bảo trì hơn mà không làm thay đổi logic hoạt động bên ngoài."
+description: "Tái cấu trúc code để dễ bảo trì, dễ test hơn — không thay đổi external behavior. Dùng skill này khi user nhắc đến: refactor, tái cấu trúc, tách file, extract function/component/module, clean code, reduce complexity, file quá dài, God class, quá nhiều responsibilities — kể cả khi chỉ nói \"file này lộn xộn quá\"."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
 
 type: capability
@@ -20,13 +20,17 @@ complexity:
     has_external_dependency: false
     has_breaking_change: false
 
-triggers:
-  - refactor
-  - tái cấu trúc
-  - clean up this code
-  - simplify
-  - reduce complexity
-  - dẫn cấu trúc code
+triggers:
+  - "refactor"
+  - "tái cấu trúc"
+  - "tách file"
+  - "extract function/component/module"
+  - "clean code"
+  - "reduce complexity"
+  - "file quá dài"
+  - "God class"
+  - "quá nhiều responsibilities"
+
 
 selection:
   priority: medium
@@ -44,7 +48,7 @@ tools:
   - terminal
 
 related_skills:
-  - qk-engineering-standard
+  - qk-code-review
   - qk-project-health
 
 knowledge_scope:
@@ -76,385 +80,164 @@ token_budget:
   max_shell_commands: 2
   stop_early: true
 
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 ---
 
 # qk-refactor - Safe Refactor
 
-> Language rule: Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
+Chịu trách nhiệm tái cấu trúc mã nguồn để tăng khả năng bảo trì, giảm độ phức tạp và tăng tính kiểm thử mà **TUYỆT ĐỐI KHÔNG làm thay đổi hành vi bên ngoài (External Behavior)**.
+
+---
 
-## Memory Workflow
-
-### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
-- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
-  - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
-  - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
-
----
-
-### Pre-flight Retrieve (Trước khi thực thi)
-- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
-  bắt buộc tra cứu:
-  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
-
-- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
-  - Architecture
-  - Hard Bug
-  - Convention
-  - Pattern
-  - Tech Debt Pattern
-  - 👉 *Domain Focus:* Pattern / Convention (vd: chiến lược tách file anti-slop, bảo toàn public contract).
-
-- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
-  Không được xem Memory là Source of Truth.
-  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
-
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Pattern tái cấu trúc mã nguồn hiệu quả (vd: bẻ gẫy god-file thành module O(1)).
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .ai-local/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* Các thao tác đổi tên biến (rename) hoặc format đơn giản.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
-
-
-
-### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
-- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
-  - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
-  - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
-
----
-
-### Pre-flight Retrieve (Trước khi thực thi)
-- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
-  bắt buộc tra cứu:
-  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
-
-- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
-  - Architecture
-  - Hard Bug
-  - Convention
-  - Pattern
-  - Tech Debt Pattern
-  - 👉 *Domain Focus:* Pattern / Convention (vd: chiến lược tách file anti-slop, bảo toàn public contract).
-
-- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
-  Không được xem Memory là Source of Truth.
-  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
-
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Pattern tái cấu trúc mã nguồn hiệu quả (vd: bẻ gẫy god-file thành module O(1)).
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .ai-local/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* Các thao tác đổi tên biến (rename) hoặc format đơn giản.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
-
-
-
-### Pre-flight Retrieve (Trước khi thực thi)
-- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
-  bắt buộc tra cứu:
-  - `.agents/knowledge/index.yaml` (Shared Project Knowledge)
-  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
-
-- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
-  - Architecture
-  - Hard Bug
-  - Convention
-  - Pattern
-  - Tech Debt Pattern
-  - 👉 *Domain Focus:* Pattern / Convention (vd: chiến lược tách file anti-slop, bảo toàn public contract).
-
-- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
-  Không được xem Memory là Source of Truth.
-  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
-
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Pattern tái cấu trúc mã nguồn hiệu quả (vd: bẻ gẫy god-file thành module O(1)).
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* Các thao tác đổi tên biến (rename) hoặc format đơn giản.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Pattern tái cấu trúc mã nguồn hiệu quả (vd: bẻ gẫy god-file thành module O(1)).
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* Các thao tác đổi tên biến (rename) hoặc format đơn giản.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Pattern tái cấu trúc mã nguồn hiệu quả (vd: bẻ gẫy god-file thành module O(1)).
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* Các thao tác đổi tên biến (rename) hoặc format đơn giản.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
----
----
----
-
 ## Preconditions
-- [ ] Target file(s) or module(s) are specified
-- [ ] Tests exist for the target code (or can be created)
 
-On missing precondition:
-  EXIT: BLOCKED
-  Message: "Missing: target files or test coverage"
+Trước khi tái cấu trúc bất kỳ file nào, AI BẮT BUỘC kiểm tra:
+
+- [ ] Xác định rõ mục tiêu refactor (tách file, giảm cognitive complexity, khử duplication, áp dụng Design Pattern).
+- [ ] Xác định public contracts (functions, classes, API routes, props) cần giữ nguyên vẹn.
+- [ ] Kiểm tra hệ thống test hiện có: có tests để verify behavior không?
+- [ ] Nếu yêu cầu refactor kèm theo thay đổi nghiệp vụ hoặc đổi behavior:
+  → **EXIT: BLOCKED**
+  → Báo cáo user: Tách riêng việc refactor (qk-refactor) và việc đổi tính năng (qk-feature-delivery).
+
+---
 
 ## Scope
-- Improve internal code quality without changing external behavior
-- Reduce complexity, improve naming, extract functions
-- Remove dead code and duplication
-
-## Non-Goals
-- Add new functionality
-- Change public API signatures
-- Modify behavior or business logic
-
-## Workflow
-1. Establish baseline (current behavior + tests)
-2. Plan refactor steps
-3. Execute step by step
-4. Verify behavior unchanged
-5. Run validation gate
-
-## Exit Codes
-| Code | Meaning |
-|------|---------|
-| SUCCESS | Refactor complete, behavior preserved, tests pass |
-| PARTIAL | Refactor done, some tests need attention |
-| BLOCKED | Missing preconditions |
-| FAILED | Behavior changed or tests broken |
+
+✅ Skill này làm:
+- Trích xuất hàm, component, custom hooks hoặc helper modules (Extract method/module).
+- Giảm độ phức tạp cyclomatic (lồng if/else sâu, switch case khổng lồ).
+- Khử trùng lặp mã nguồn (DRY) mà không tạo ra over-abstraction gượng ép.
+- Tối ưu đặt tên biến, hàm theo đúng quy ước sạch (Clean Code).
+- Bảo đảm 100% backward compatibility với các consumer của module.
+
+❌ Skill này KHÔNG làm:
+- Sửa đổi business logic hoặc thay đổi đầu ra mong đợi của hệ thống.
+- Viết tính năng mới ngoài lề trong quá trình refactor.
+- Tự ý thay đổi schema cơ sở dữ liệu (→ `qk-data-lifecycle`).
+
+---
+
+## Execution Steps
+
+### Step 1 — Current State & Contract Lock
+```
+Inputs:  Mã nguồn mục tiêu, Public interface
+Actions:
+  - Phân tích luồng thực thi và các điểm vào/ra (inputs/outputs, exceptions).
+  - Khóa (lock) contract công khai: không thay đổi signature của exported functions/components.
+  - Kiểm tra test coverage hiện có (nếu có).
+Output: Refactor Safety Boundary
+```
+
+### Step 2 — Incremental Transformation
+```
+Inputs:  Target code, Safety boundary
+Actions:
+  - Tách nhỏ từng phần (baby steps): trích xuất hàm con, module độc lập.
+  - Thay thế cấu trúc lồng ghép bằng Guard Clauses (early return).
+  - Di chuyển các helper/utility sang vị trí phù hợp theo kiến trúc dự án.
+Output: Refactored code
+```
+
+### Step 3 — Verification & Equivalence Check
+```
+Inputs:  Refactored code, Original tests
+Actions:
+  - Chạy linter và typecheck: 0 type errors, 0 lint warnings.
+  - Chạy tests để xác nhận tính tương đương hành vi (behavior equivalence).
+  - So sánh diff để đảm bảo không xóa nhầm logic hay import.
+Exit: SUCCESS nếu code sạch hơn, pass linter/types và giữ nguyên behavior.
+```
+
+---
+
+## Prompt Template
+
+AI đọc `DEV_PROFILE.md` để biết conventions. Mô tả vấn đề — AI đọc code thật trước khi refactor.
+
+```
+Target:      [File / module / function cần refactor — đường dẫn cụ thể]
+Vấn đề:     [Code đang gây ra vấn đề gì — quá dài / khó test / lặp lại / ...]
+Mục tiêu:   [Muốn đạt được gì sau refactor]
+Giữ nguyên: [Public interface / behavior / test cases không được đổi]
+```
+
+---
+
+### Theo Role — AI refactor theo chiều sâu khác nhau:
+
+**role: fe**
+```
+Target:      src/pages/CheckoutPage.tsx (380 dòng)
+Vấn đề:     Một file trộn lẫn: form state, API calls, validation, UI rendering,
+             cart calculation — không test được, không reuse được
+Mục tiêu:   Tách thành: CheckoutPage (UI) + useCheckout (logic hook) +
+             checkoutSchema (validation) + cartUtils (calculation)
+Giữ nguyên: Props interface của CheckoutPage không đổi, behavior submit không đổi
+```
+→ AI refactor: custom hook extraction pattern, co-location vs separation of concerns,
+  memoization opportunities (useMemo/useCallback), type narrowing sau khi tách.
+
+**role: be**
+```
+Target:      src/services/OrderService.ts (420 dòng)
+Vấn đề:     God class — xử lý: tạo order, tính giá, gửi email, update inventory,
+             generate invoice — vi phạm SRP, unit test không isolate được
+Mục tiêu:   Tách ra theo domain: PricingService, InventoryService, NotificationService,
+             OrderService chỉ orchestrate
+Giữ nguyên: Public method signatures của OrderService, không đổi DB transactions
+```
+→ AI refactor: dependency injection pattern, service boundary design,
+  transaction scope sau khi tách (vẫn cần atomic), interface extraction cho testability.
+
+**role: fullstack**
+```
+Target:      src/features/products/ (toàn bộ folder)
+Vấn đề:     Feature folder có: API route, DB query, FE component, type definitions
+             — tất cả trong cùng 1 file products.ts (550 dòng)
+Mục tiêu:   Feature-based architecture: products/api.ts, products/db.ts,
+             products/components/, products/types.ts, products/hooks.ts
+Giữ nguyên: Import paths của các file khác đang dùng products types
+```
+→ AI refactor: barrel exports để preserve import paths, layer separation
+  (presentation/business/data), shared types location, circular dependency check.
+
+**role: data**
+```
+Target:      transforms/order_metrics.sql (250 dòng)
+Vấn đề:     SQL monolith — một query tính tất cả metrics, không reusable,
+             debug khó, CTE lồng nhau 6 cấp
+Mục tiêu:   Tách thành dbt models: stg_orders, int_order_items, fct_order_metrics
+             Mỗi model làm đúng một việc
+Giữ nguyên: Output schema của fct_order_metrics không đổi (downstream depends on it)
+```
+→ AI refactor: dbt model layering (staging/intermediate/mart), ref() dependencies,
+  incremental model strategy, documentation + schema.yml generation.
+
+**role: ai-engineer**
+```
+Target:      agents/rag_agent.py (300 dòng)
+Vấn đề:     Monolithic RAG function — embed + retrieve + rerank + generate
+             tất cả trong 1 hàm, không thể A/B test từng component
+Mục tiêu:   Tách thành pipeline: Retriever, Reranker, Generator — mỗi class
+             có interface rõ ràng, swap được implementation
+Giữ nguyên: Input/output interface của rag_agent() không đổi
+```
+→ AI refactor: Strategy pattern cho từng pipeline stage, dependency injection
+  cho model/embedding, eval hooks tại từng stage, config-driven pipeline.
+
+**role: devops**
+```
+Target:      .github/workflows/deploy.yml (200 dòng)
+Vấn đề:     Một workflow file làm tất cả: test + build + push image + deploy staging
+             + deploy prod + notify — không reusable, khó debug khi fail
+Mục tiêu:   Tách thành reusable workflows: test.yml, build-push.yml,
+             deploy.yml (reusable), notify.yml — orchestrated từ main.yml
+Giữ nguyên: Trigger conditions và environment variables không đổi
+```
+→ AI refactor: GitHub reusable workflows pattern (workflow_call),
+  matrix strategy cho multi-env deploy, secret scoping per environment,
+  concurrency groups để tránh parallel deploys.