# Trang 5.4: Nâng cấp và cải tiến mã nguồn hiện có với /enhance.

## 1. Mục đích và triết lý

**`/enhance`** là công cụ của vòng lặp phát triển hàng ngày — dùng để **thêm tính năng mới vào hệ thống đang chạy** mà không làm gián đoạn hoặc phá vỡ những gì đang hoạt động.

Triết lý cốt lõi của `/enhance` là **"phẫu thuật chính xác" (surgical precision)**: chỉ thay đổi đúng những gì cần thiết, không viết lại, không refactor không liên quan.

> **Khi nào `/enhance` vs `/create`?**
> 
> - **`/enhance`**: "Dự án đang chạy, tôi muốn thêm tính năng X" → ENHANCE
> - **`/create`**: "Tôi chưa có gì, tôi muốn xây dựng tính năng X từ đầu" → CREATE

---

## 2. Điều đặc biệt: Phân tích code trước khi thay đổi

Khác với `/create` (bắt đầu từ trang trắng), `/enhance` **bắt buộc phải đọc và hiểu codebase hiện tại** trước khi đề xuất bất kỳ thay đổi nào.

```html
/enhance [yêu cầu]
│
▼
📖 AI đọc cấu trúc dự án hiện tại
│
▼
🔍 Phân tích các file liên quan đến yêu cầu
│
▼
📋 Lập kế hoạch thay đổi tối thiểu cần thiết
│
▼
✅ Đề xuất plan → Bạn phê duyệt → AI triển khai
│
▼
🧪 Chạy kiểm tra để xác nhận không có regression
```

---

## 3. Phương pháp "Vertical Slice" (Lát cắt dọc)

Khi thêm tính năng mới, `/enhance` áp dụng phương pháp **Vertical Slice** — triển khai đầy đủ một tính năng theo chiều dọc từ database đến UI, thay vì làm từng lớp riêng lẻ.

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-v%C3%AD-d%E1%BB%A5%3A-th%C3%AAm-t%C3%ADnh-n%C4%83n" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5"><div class="font-sans text-sm text-ide-text-color opacity-60">  
</div><div class="flex flex-row gap-2 justify-end"></div></div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"><span class="mtk1">Ví dụ: Thêm tính năng "Bình luận bài viết"</span></div></div><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content">  
</div></div><div class="code-line" data-line-end="3" data-line-number="3" data-line-start="3"></div></div></div></div></div>```html
Vertical Slice (✅ cách /enhance làm):
├── Database: Bảng comments + migration
├── Backend: API /comments (GET, POST, DELETE)
├── Frontend: Component CommentSection + CommentItem
└── Testing: Unit test + Integration test


Thay vì (❌ cách dễ gây lỗi):
├── Tuần 1: Xong hết phần database
├── Tuần 2: Xong hết phần backend
└── Tuần 3: Xong hết phần frontend

Ưu điểm: Bạn có thể test và dùng tính năng ngay khi một Vertical Slice hoàn thành, không cần đợi toàn bộ.
```

---

## 4. Quy trình thực hiện

### Bước 1: Mô tả tính năng cần thêm

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--3" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```bash
bash
/enhance [mô tả tính năng + ràng buộc nếu có]
```

### Bước 2: AI phân tích codebase

AI sẽ đọc:

- <div>  
    </div><span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">package.json</span></span></span> để biết tech stack và thư viện.
- Cấu trúc thư mục `src/` để hiểu tổ chức code.
- Các file liên quan đến yêu cầu của bạn.

### Bước 3: AI đề xuất kế hoạch thay đổi

```html
📋 Kế hoạch thay đổi:


Tìm thấy:
- Framework: Next.js 14 với App Router
- Đang dùng Tailwind CSS
- Chưa có cấu hình dark mode


Thay đổi dự kiến:
1. Cập nhật tailwind.config.ts (thêm darkMode: 'class')
2. Tạo component ThemeProvider (dùng next-themes)
3. Tạo component ThemeToggle
4. Cập nhật app/layout.tsx để bọc trong ThemeProvider
5. Thêm class dark: vào các component chính


Thư viện cần cài: next-themes
Không ảnh hưởng đến: logic nghiệp vụ, database, API


Tiến hành? (Y/N)
```

### Bước 4: Phê duyệt và triển khai

Sau khi bạn xác nhận, AI triển khai từng thay đổi và chạy kiểm tra.

---

## 5. Ví dụ phiên làm việc thực tế

### Ví dụ 1: Thêm dark mode

```html
👤 Bạn: /enhance thêm dark mode toggle vào ứng dụng Next.js của tôi,
đảm bảo lưu lại tùy chọn của người dùng


🤖 AI: Đang phân tích codebase...


📊 Kết quả phân tích:
- Next.js 14 + App Router ✅
- Tailwind CSS ✅ (chưa có darkMode config)
- localStorage có thể dùng (không có SSR conflict nếu dùng next-themes)


📋 Kế hoạch (5 thay đổi):
1. npm install next-themes
2. Cập nhật tailwind.config.ts
3. Tạo ThemeProvider component
4. Tạo ThemeToggle button (sun/moon icon)
5. Cập nhật layout.tsx


Tiến hành? (Y/N)


👤 Bạn: Y


🤖 AI:
✅ Đã cài next-themes
✅ Đã cập nhật tailwind.config.ts
✅ Đã tạo components/ThemeProvider.tsx
✅ Đã tạo components/ThemeToggle.tsx
✅ Đã cập nhật app/layout.tsx


Chạy /preview start để xem kết quả.
Tùy chọn dark/light mode được lưu vào localStorage tự động.
```

### Ví dụ 2: Thêm tính năng dashboard analytics

```html
👤 Bạn: /enhance thêm dashboard analytics cho admin.
Cần: biểu đồ doanh thu 30 ngày, top 5 sản phẩm bán chạy,
số lượng đơn hàng theo trạng thái
Requirements:
- Dùng Recharts cho biểu đồ
- API endpoint riêng để aggregate data
- Chỉ admin mới xem được


🤖 AI: Đang phân tích codebase...


📊 Kết quả phân tích:
- Tìm thấy role-based auth trong middleware.ts
- Đang dùng Prisma + PostgreSQL
- Chưa có Recharts


📋 Kế hoạch (Vertical Slice):
Database: Không cần migration mới (aggregate từ bảng orders)
Backend: GET /api/admin/analytics (3 queries tổng hợp)
Frontend: Trang /admin/analytics với 3 chart components
Testing: Test API endpoint + mock data


Tiến hành? (Y/N)
```

---

## 6. Bảo vệ code hiện có — Các nguyên tắc an toàn

`/enhance` theo các nguyên tắc sau để không làm hỏng hệ thống:

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-nguy%C3%AAn-t%E1%BA%AFc-di%E1%BB%85n-gi%E1%BA%A3i"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Nguyên tắc</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Diễn giải</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Thay đổi tối thiểu**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chỉ tạo/sửa file thực sự cần thiết</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Cô lập tính năng**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Tính năng mới trong thư mục/module riêng</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Không refactor ngoài phạm vi**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Không sửa những gì không liên quan đến yêu cầu</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Regression test**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chạy test hiện có sau mỗi thay đổi</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">**Phê duyệt trước khi làm**</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Luôn trình bày kế hoạch để bạn xem xét trước</td></tr></tbody></table>

</div>---

## 7. Mẹo để `/enhance` hoạt động hiệu quả

### Kiểm tra dependencies trước

```html
"Trước khi thêm thư viện XYZ, hãy kiểm tra xem
nó có tương thích với phiên bản Node.js/React hiện tại không"
```

### Yêu cầu xem kế hoạch trước khi làm

Luôn đọc kỹ kế hoạch thay đổi trước khi gõ Y. Đặc biệt chú ý:

- Số lượng file bị thay đổi có hợp lý không?
- Có file nào "không liên quan" cũng bị sửa không?

### Yêu cầu test cụ thể

```html
/enhance thêm tính năng export CSV,
và viết test để đảm bảo CSV output đúng định dạng
```

### Dùng với `/test` sau mỗi lần enhance

```bash
bash
# Sau khi enhance xong
/test # Chạy toàn bộ test suite để kiểm tra regression
```