AstroUI Anatomy

khoa@macbook  ~/Projects/review-app  (main)  $
  ↑ máy của bạn      ↑ ĐANG Ở THƯ MỤC NÀY   ↑ nhánh git   ↑ gõ lệnh sau dấu này

90% rắc rối của người mới là gõ lệnh sai thư mục. Chạy npm run dev ở ngoài thư mục dự án thì báo lỗi khó hiểu. Không chắc thì gõ pwd xem đang ở đâu và ls xem có file package.json không — có nghĩa là đang đứng đúng chỗ.

Terminal in ra bốn loại thứ. Phân biệt được là hết hoảng:

Mở file package.json ở gốc dự án, tìm mục scripts. Đó là danh sách lệnh riêng của dự án, chạy bằng npm run [tên]:

"scripts": {
  "dev":   "next dev",         ← chạy bản phát triển ở máy, tự cập nhật khi sửa code
  "build": "next build",       ← dựng bản thật, đây là bước hay báo lỗi khi deploy
  "start": "next start",       ← chạy bản đã dựng
  "lint":  "next lint"         ← soi lỗi cú pháp và code cẩu thả
}

bạn sửa code ở máy
      │
      ├─ git push                        đẩy lên GitHub
      │        │
      │        ├─ hosting tự phát hiện có thay đổi
      │        │
      │        ├─ BUILD   dựng bản thật     ← lỗi cú pháp, lỗi kiểu dữ liệu hiện ở đây
      │        ├─ TEST    chạy kiểm thử     ← fail thì DỪNG, không cho lên
      │        │
      │        ├─ đẩy lên nhánh phụ  →  URL PREVIEW riêng   gửi khách xem trước
      │        └─ đẩy lên nhánh main →  PRODUCTION          người dùng thật thấy ngay
      │
      └─ hỏng? rollback về bản trước trong khoảng 30 giây

Điểm hay nhất với người làm dịch vụ như bạn: mỗi nhánh được một URL riêng. Muốn cho khách xem thử một hướng giao diện mới thì tạo nhánh, đẩy lên, gửi link — bản chính không hề bị đụng tới. Đúng bằng workflow gửi cut cho khách duyệt.

Đây là nguyên nhân số một của "máy tôi chạy được mà lên mạng thì hỏng":

CI/CD là quy trình tự động chạy mỗi lần bạn đẩy code lên. Với vibe-coder giá trị lớn nhất của nó không phải tự động hoá — mà là chặn bạn deploy một bản hỏng, giống gate QC không cho file sai spec đi qua.

Thứ tự này quan trọng. Người mới hay làm ngược lại và kéo dài thời gian app chết:

Mở DevTools → tab Lighthouse → Analyze. Chạy ở chế độ ẩn danh để tiện ích trình duyệt không làm sai kết quả. Điểm dưới 50 là đỏ, 50–89 là vàng, từ 90 là xanh.

Không cần chuyên gia. Ba cách kiểm nhanh: bấm Tab đi hết trang, chạy Lighthouse, phóng to trình duyệt lên 200%. Ngoài lý do đúng đắn, làm tốt phần này còn giúp SEO và là yêu cầu pháp lý ở nhiều thị trường.

Mỗi lần bạn bảo AI "chỗ này màu xám nhạt hơn tí", nó đặt một mã màu mới ngay tại chỗ đó. Làm 30 lần thì app có 30 sắc xám khác nhau, không cái nào giống cái nào — và muốn đổi tông toàn app thì phải sửa 30 chỗ.

Token là biến dùng chung. Định nghĩa một lần ở đầu, mọi nơi gọi tên biến. Đổi một dòng là đổi cả app — đúng nguyên lý bạn dùng LUT thay vì grade tay từng shot.

Năm nhóm token cần có. Chỉ dùng giá trị trong thang, không chế số lẻ:

Khai báo một lần ở đầu file CSS gốc:

:root {
  /* màu — theo vai trò, không theo tên màu */
  --bg: #0d0f13;          --surface: #14171d;
  --text: #e6e9ef;        --text-muted: #9aa4b4;
  --accent: #5b8cff;      --danger: #ff5d5d;
  --success: #3ecf8e;     --warning: #f5b642;

  /* khoảng cách — thang 4px, cấm số ngoài thang */
  --sp-1: 4px;  --sp-2: 8px;  --sp-3: 12px;  --sp-4: 16px;
  --sp-5: 24px; --sp-6: 32px; --sp-7: 48px;

  /* chữ */
  --fs-xs: 12px; --fs-sm: 14px; --fs-md: 16px;
  --fs-lg: 20px; --fs-xl: 24px; --fs-2xl: 32px;

  /* bo góc và độ nổi */
  --r-sm: 6px; --r-md: 10px; --r-full: 99px;
  --sh-1: 0 1px 2px rgba(0,0,0,.4);
  --sh-2: 0 4px 10px rgba(0,0,0,.5);
}

App vibe-code hầu như luôn chỉ có một trạng thái: bình thường, dữ liệu đầy đủ, mọi thứ suôn sẻ. Người dùng thật thì bấm khi đang tải, bấm khi không có quyền, mở màn hình chưa có dữ liệu, gõ sai định dạng. Bảng dưới là thứ bạn đưa cho AI để nó không quên. Bấm vào ô để đánh dấu đã làm:

Ô gạch chéo = không áp dụng cho loại component đó.

Đây là danh sách để bạn tự soi app mình. Không đều một trong sáu thứ này là nhìn ra ngay dù không biết vì sao:

Diff là bảng so sánh trước và sau. Dòng có dấu trừ là bị bỏ đi, dấu cộng là được thêm vào. Xem bằng git diff, hoặc trong Cursor/VS Code, hoặc trên GitHub.

--- a/components/ProjectCard.tsx
+++ b/components/ProjectCard.tsx
@@ -20,7 +20,12 @@                          ← đang xem quanh dòng 20
   export function ProjectCard({ project }) {
-   return <h3>{project.name}</h3>              ← DÒNG BỊ BỎ ĐI
+   if (!project) return null                   ← DÒNG ĐƯỢC THÊM
+   return (
+     <h3>{project.name ?? 'Chưa đặt tên'}</h3>
+   )
   }
   (dòng không dấu = không đổi, chỉ để bạn biết ngữ cảnh)

Ba câu hỏi bắt buộc khi nhìn một diff, theo đúng thứ tự:

Bạn không cần hiểu code vẫn nhận ra được những dấu hiệu này. Thấy là bảo AI dọn ngay, để lâu thì càng khó gỡ:

Nợ kỹ thuật là làm nhanh cho xong, biết là chưa chuẩn, tính sửa sau. Không phải lúc nào cũng xấu — vấn đề là nợ có ý thức hay nợ mà không biết mình đang nợ. Cứ ghi vào một file NO-KY-THUAT.md mỗi lần bạn cố tình chọn đường tắt.

Không cần lý thuyết. Đặt hai câu hỏi bằng tiếng Việt thường là ra ngay loại quan hệ và cách làm:

Đọc thử để thấy một schema đủ dùng trông ra sao. Chú ý mọi bảng đều có id, created_at, và bảng trung gian ở cuối:

users
  id            uuid       khoá chính
  email         text       duy nhất
  full_name     text
  created_at    timestamp

projects
  id            uuid
  name          text
  owner_id      uuid   → users.id      một user có nhiều project
  status        text       'offline' | 'online' | 'delivered'
  deadline      date
  created_at    timestamp
  deleted_at    timestamp  null = chưa xoá (xoá mềm)

videos
  id            uuid
  project_id    uuid   → projects.id   một project có nhiều bản cut
  version       int        v1, v2, v3…
  storage_path  text       ĐƯỜNG DẪN file, không phải file
  duration_ms   int
  created_at    timestamp

comments
  id            uuid
  video_id      uuid   → videos.id
  author_id     uuid   → users.id
  timecode_ms   int        comment gắn vào giây thứ mấy
  body          text
  resolved      boolean
  created_at    timestamp

project_members   ← BẢNG TRUNG GIAN cho quan hệ nhiều–nhiều
  project_id    uuid   → projects.id
  user_id       uuid   → users.id
  role          text       'owner' | 'editor' | 'viewer'
  khoá chính = (project_id, user_id) — một người chỉ vào một lần

Đây là kỹ thuật giá trị nhất trong cả tab này. Thay vì mô tả mơ hồ rồi chờ AI đoán, bạn tự chỉnh trong DevTools cho tới khi ưng mắt, rồi đưa con số chính xác cho AI. Một vòng là xong thay vì năm vòng.

Mở tab Network, lọc Fetch/XHR, rồi thao tác lại trên trang. Hỏi ba câu theo đúng thứ tự:

App có ba nơi sinh lỗi khác nhau. Mở nhầm chỗ là tìm cả buổi không thấy gì:

Lỗi trông dài và đáng sợ, nhưng chỉ có hai dòng quan trọng:

TypeError: Cannot read properties of undefined (reading 'name')   ← DÒNG 1: LỖI GÌ
    at ProjectCard (components/ProjectCard.tsx:24:31)              ← DÒNG 2: Ở ĐÂU (file của BẠN)
    at renderWithHooks (node_modules/react-dom/cjs/react-dom.js:16305)   ← nhiễu, bỏ qua
    at mountIndeterminateComponent (node_modules/react-dom/...:20074)    ← nhiễu, bỏ qua
    at beginWork (node_modules/react-dom/cjs/react-dom.js:21587)         ← nhiễu, bỏ qua

Thấy trong tab Network. Con số đầu tiên cho biết ngay nên đi sửa phía nào:

Làm theo thứ tự này thay vì dán lỗi rồi cầu nguyện. Hầu hết lỗi được tìm ra ở bước 2:

Chạy local ổn nhưng deploy lên là hỏng — bốn nguyên nhân chiếm gần hết:

File .gitignore tối thiểu — đặt ở gốc dự án, tạo trước commit đầu tiên:

# bí mật — quan trọng nhất
.env
.env.local
.env.*.local
*.pem

# thư viện và file sinh ra tự động
node_modules/
.next/
dist/
build/

# rác hệ thống
.DS_Store
Thumbs.db
*.log

# media nặng — dùng dịch vụ lưu trữ riêng
*.mp4
*.mov
*.prproj
*.drp

main       ──●──●──●─────────────────●──▶   luôn chạy được, đây là bản deploy
                    ╲               ╱
thu-nghiem           ●──●──●──●────╯        thử tính năng mới ở đây
                     ↑           ↑
                tạo nhánh      gộp lại khi ổn
                                             nếu tệ: xoá nhánh, main không hề hấn gì

Với vibe-code, nhánh có giá trị nhất khi bạn muốn bảo AI thử một hướng lớn: tạo nhánh, cho nó làm thoải mái, hỏng thì xoá cả nhánh — main vẫn nguyên vẹn. Giống duplicate timeline trước khi thử một cấu trúc dựng khác.

Bảo AI "làm cho tôi cái app quản lý project" là brief một câu cho một phim 3 phút. Chốt 6 thứ dưới đây trước, mọi thứ sau đó nhanh gấp ba:

Bước 5 là bước bị bỏ nhiều nhất và cũng là bước cứu bạn. Commit = lưu version. Có commit thì mọi sai lầm sau đó chỉ tốn 30 giây để quay lại. Không commit thì một lần AI "dọn dẹp giúp" có thể xoá mất hai ngày làm việc.

AI không nhớ gì giữa hai phiên, và trong một phiên dài nó cũng quên dần phần đầu. Cách xử lý: đưa trí nhớ ra file.

Tạo file quy ước ở gốc dự án — Claude Code đọc CLAUDE.md, Codex đọc AGENTS.md, Cursor đọc .cursorrules. Nội dung gần như nhau, tạo cả ba cũng được:

# DỰ ÁN
App review cut cho khách hàng. Khách xem video và comment theo timecode.

# STACK — KHÔNG ĐỔI
Next.js App Router · TypeScript · Supabase (DB + Auth) · Tailwind · Vercel

# NGUYÊN TẮC BẢO MẬT — BẮT BUỘC
- Mọi bảng phải bật RLS. Không tạo bảng mới mà không kèm policy.
- Không bao giờ đặt khoá bí mật ở frontend. Chỉ dùng NEXT_PUBLIC cho thứ vô hại.
- Mọi route backend phải kiểm tra người gọi là ai và có quyền không.
- Validate lại toàn bộ input ở phía server.

# CÁCH LÀM VIỆC VỚI TÔI
- Luôn trình bày kế hoạch trước, chờ tôi duyệt rồi mới code.
- Mỗi lần chỉ làm một việc. Không tự ý sửa file ngoài phạm vi tôi nêu.
- Tôi không rành backend: giải thích bằng tiếng Việt, không dùng từ chuyên môn mà không giải thích.
- Chọn cách đơn giản nhất chạy được. Không thêm thư viện nếu chưa hỏi tôi.
- Sau mỗi thay đổi, tóm tắt đã sửa file nào và tại sao.

# ĐANG LÀM DỞ
(cập nhật cuối phiên: đang làm màn hình comment, chưa xong phần timecode)

Ai cũng gặp: bảo sửa, nó sửa, vẫn lỗi, sửa tiếp, hỏng thêm chỗ khác. Vòng xoáy này đốt tiền và làm nát code. Quy tắc: thử 3 lần không xong thì dừng, đổi cách — đừng thử lần 4.

Không cần phủ 100%. Vibe-coder chỉ cần đủ để biết thứ đang chạy có bị hỏng khi sửa cái khác không — giống check gate trước khi gửi master, không phải xem lại từng frame.

App của bạn gồm những mảnh nào

Đối chiếu sang pipeline post cho dễ hình dung:

Stack mặc định an toàn cho vibe-coder

Không phải lựa chọn duy nhất, nhưng là bộ ít gây tai nạn nhất khi bạn không rành backend:

Đèn đỏ — thấy những dòng này thì dừng lại hỏi

Từ điển backend — hiểu Claude đang nói gì

4 prompt bắt Claude tự kiểm tra

Phần pháp lý ở trên chỉ là thông tin tham khảo, không phải tư vấn pháp lý. Nếu app xử lý dữ liệu cá nhân ở quy mô thật, nên hỏi luật sư về Nghị định 13/2023/NĐ-CP.