00. Nền Tảng & Setup — Vibe Coding Series

Lần đầu tôi dùng AI agent “thả ga” là vào một buổi tối thứ Sáu. Tôi có một ý tưởng về một SaaS tool nhỏ — quản lý task cho team indie — và tôi nghĩ: “Thôi, cứ mô tả hết cho Claude Code, để nó lo.”

Tôi paste vào một đoạn brief dài khoảng 400 từ: auth, CRUD task, dashboard, invite member, email notification. Rồi tôi đi pha cà phê.

Khi quay lại, agent đã chạy xong. Code nhìn khá ổn. Tôi chạy thử — app lên được, UI mượt, đăng nhập được. Tôi hào hứng push lên staging.

Đến thứ Hai, tôi mở lại để tiếp tục. Và mọi thứ bắt đầu sụp đổ.

Cái “invite member” flow hoạt động nhưng không gửi email. Cái dashboard query không có pagination — nếu có 1000 task thì load hết vào RAM. Auth dùng JWT nhưng không có refresh token logic. Và tệ nhất: không có một dòng test nào.

Tôi mất gần một tuần để fix những thứ mà đáng ra phải được thiết kế đúng từ đầu. Không phải vì AI viết code xấu — mà vì tôi không có framework để làm việc với nó.

Đó là lúc tôi bắt đầu xây dựng cái gọi là Vibe Coding Framework.

---

Tại sao cần một framework?

“Vibe coding” — thuật ngữ do Andrej Karpathy đặt ra — mô tả cách lập trình nơi bạn mô tả ý tưởng bằng ngôn ngữ tự nhiên và để AI lo phần còn lại. Nghe rất hấp dẫn. Và thực ra nó hoạt động — nhưng chỉ khi bạn biết mình đang làm gì.

Vibe coding không có cấu trúc trông như thế này:

• Mô tả feature mơ hồ → AI generate code → chạy thử → thấy bug → fix → thấy bug mới → lặp lại
• Sau 2 tuần: codebase rối, không test, không ai hiểu flow, AI bắt đầu “quên” context
• Kết quả: rewrite từ đầu hoặc abandon project

Vibe coding có cấu trúc trông như thế này:

• Requirements rõ ràng → API contract trước → task nhỏ có acceptance criteria → AI implement từng task → human review checkpoint → test pass → merge
• Sau 2 tuần: feature hoàn chỉnh, có test, có docs, AI vẫn hiểu context vì được feed đúng cách

Sự khác biệt không nằm ở tool hay model. Nó nằm ở quy trình.

Series này là quy trình đó — được đúc kết từ kinh nghiệm thực chiến, không phải lý thuyết.

---

8 Phases của Vibe Coding Framework

Đây là toàn bộ framework, từ ý tưởng đến production:

Mỗi phase giải quyết một vấn đề cụ thể mà tôi đã gặp phải khi làm việc với AI agent. Bạn có thể đọc từng bài độc lập, nhưng đọc theo thứ tự sẽ cho thấy tại sao mỗi phase lại đứng ở vị trí đó.

---

Example Project: TaskFlow

Xuyên suốt series, tôi sẽ dùng một dự án thực tế để minh họa từng phase: TaskFlow — một SaaS tool quản lý task nhỏ cho team indie.

TaskFlow có đủ độ phức tạp để minh họa các vấn đề thực tế, nhưng không quá lớn để mất tập trung:

• Auth: đăng ký, đăng nhập, JWT + refresh token, invite member
• CRUD: tạo/sửa/xóa task, assign, set deadline, tag
• Dashboard: overview task theo status, filter, pagination
• Notification: email khi được assign task hoặc deadline sắp đến

Stack: Next.js 15, Supabase (PostgreSQL + Auth), Resend (email), Vercel.

Tôi chọn stack này vì nó phổ biến, AI agent hiểu rất tốt, và đủ “thật” để các ví dụ không bị giả tạo. Bạn không cần dùng đúng stack này — framework hoạt động với bất kỳ tech stack nào.

---

Setup Nền Tảng

Trước khi bắt đầu bất kỳ phase nào, bạn cần setup đúng môi trường. Đây là những thứ tôi coi là bắt buộc:

1. Chọn AI Agent

Hai lựa chọn chính hiện tại:

• Cursor: IDE-first, tích hợp sâu vào VS Code, tốt cho workflow có nhiều file editing đồng thời. Dùng .cursorrules để định nghĩa project context.
• Claude Code: CLI-first, mạnh về automation và scripting, tốt cho backend-heavy workflow. Dùng CLAUDE.md để định nghĩa project memory.

Tôi dùng cả hai tùy context — Cursor cho UI work, Claude Code cho backend và automation. Nhưng nếu bạn mới bắt đầu, chọn một cái và stick với nó.

2. Git Workflow

Commit thường xuyên — sau mỗi task hoàn thành, không phải sau mỗi feature. Lý do: khi AI đi sai hướng (và nó sẽ đi sai), bạn cần checkpoint để revert về.

Convention tôi dùng:

feat: add user authentication endpoint
fix: handle refresh token expiry edge case
chore: update CLAUDE.md with auth module context

Branch strategy: main → develop → feature/task-name. Mỗi task của AI chạy trên branch riêng, merge vào develop sau khi human review.

3. Project Memory File

Đây là thứ quan trọng nhất mà hầu hết mọi người bỏ qua.

AI agent không có memory giữa các session. Mỗi lần bạn mở chat mới, nó bắt đầu từ đầu. CLAUDE.md (hoặc .cursorrules) là cách bạn “dạy” AI về project của mình một lần, dùng mãi.

Đây là template tôi dùng cho TaskFlow:

# TaskFlow — Project Memory

## Stack
- Next.js 15 (App Router), TypeScript strict mode
- Supabase (PostgreSQL + Auth + Realtime)
- Resend for transactional email
- Deployed on Vercel

## Architecture
- /app: Next.js App Router pages
- /components: UI components (atomic design)
- /lib: business logic, utilities
- /lib/supabase: Supabase client + server helpers
- /types: TypeScript interfaces

## Coding Standards
- No `any` type — use proper TypeScript
- All async functions must handle errors explicitly
- API routes return { data, error } shape consistently
- Use Zod for all input validation

## Current Phase
Phase 1 — Requirements & Architecture
Last updated: [date]

## Key Decisions
- Using Supabase Auth (not custom JWT) for simplicity
- Row Level Security enabled on all tables
- Email via Resend, not Supabase built-in (better deliverability)

Cập nhật file này sau mỗi phase. Đây là “source of truth” cho AI về project của bạn.

---

Glossary

Các thuật ngữ sẽ xuất hiện xuyên suốt series:

HITL (Human-in-the-Loop): Checkpoint bắt buộc có human review trước khi tiếp tục. Không phải mọi bước đều cần HITL — nhưng những bước quan trọng (merge code, deploy, thay đổi schema) thì phải có.

Context rot: Hiện tượng AI bắt đầu “quên” hoặc hiểu sai context khi conversation quá dài. Dấu hiệu: AI bắt đầu lặp lại code đã có, đề xuất giải pháp mâu thuẫn với quyết định trước đó, hoặc ignore constraint đã được đặt ra. Cách xử lý: reset session, feed lại CLAUDE.md và context cần thiết.

Ownership map: Tài liệu xác định phần nào của codebase do AI implement, phần nào do human implement, và phần nào cần human review bắt buộc. Giúp tránh tình trạng “không ai biết đoạn code này từ đâu ra”.

AI_CONTEXT.md: File context chuyên biệt cho từng module hoặc feature, bổ sung cho CLAUDE.md. Ví dụ: auth/AI_CONTEXT.md chứa spec của auth module, data model, và constraint cụ thể. AI đọc file này trước khi implement bất kỳ thứ gì liên quan đến auth.

---

Tiếp theo

Bài tiếp theo đi vào Phase 1: cách làm việc với AI để phân tích yêu cầu, tránh bẫy “build sai thứ”, và chốt kiến trúc trước khi viết dòng code đầu tiên. Đây là phase mà hầu hết mọi người bỏ qua — và đó là lý do tại sao họ mất hàng tuần để fix những thứ đáng ra không nên tồn tại.

→ Bài 01: Nhận yêu cầu, phân tích, chốt kiến trúc