Chuẩn bị project thực hành

Uigen là gì?

Giới thiệu

Uigen = "UI generator". Một Next.js 14 web app dùng Claude API để generate React component từ prompt người dùng.

Tech stack

Tại sao chọn project này?

• Đủ nhỏ để hiểu trong 10 phút (~50 file)
• Đủ phức tạp để có Grep/Read/Edit thực sự có ý nghĩa
• Có flow end-to-end (UI → API → DB)
• Có integration với Claude (bạn dùng Claude Code để phát triển app dùng Claude API — recursive fun)
• Có test suite để thấy Claude Code workflow hoàn chỉnh

┌──────────────────────────────────────────────────────────┐
│                                                          │
│  User nhập: "Tạo pricing card 3 tier cho SaaS"           │
│                     │                                    │
│                     ▼                                    │
│           ┌──────────────────┐                           │
│           │  Next.js API     │                           │
│           │  /api/generate   │                           │
│           └─────────┬────────┘                           │
│                     │                                    │
│                     ▼                                    │
│           ┌──────────────────┐                           │
│           │   Claude API     │  ◀── prompt template     │
│           │   (Anthropic)    │      + user input        │
│           └─────────┬────────┘                           │
│                     │ stream                             │
│                     ▼                                    │
│           ┌──────────────────┐                           │
│           │  UI preview      │                           │
│           │  + save SQLite   │                           │
│           └──────────────────┘                           │
│                                                          │
└──────────────────────────────────────────────────────────┘

Yêu cầu trước khi setup

Bắt buộc

Optional (khuyến khích cho trải nghiệm đầy đủ)

Kiểm tra prerequisite

• ☐ Node.js 18+ (nodejs.org)
• ☐ npm (đi kèm Node)
• ☐ Git
• ☐ Claude Code đã cài (Bài 4.4)
• ☐ Anthropic API key (console.anthropic.com) — nếu muốn uigen thực sự generate thay vì trả fake output

node --version   # >= 18.0.0
npm --version    # >= 9.0.0
git --version    # >= 2.30.0
claude --version # đã cài ở Bài 4.4

Setup bước-bằng-bước

Bước 1: Tải source

Có 2 cách:

Cách A — Zip từ course:

Cách B — Git (nếu có repo):

Bước 2: Setup

• Download uigen.zip từ material đi kèm khóa học
• Giải nén vào ~/Projects/uigen (hoặc path bạn muốn)

cd ~/Projects
git clone https://github.com/anthropic-edu/uigen.git
cd uigen

Bước 2: Setup

Script setup làm hai việc:

Output success giống:

• npm install (cài deps — ~30–60 giây)
• Init SQLite DB local (prisma migrate)

cd ~/Projects/uigen
npm run setup

Setup bước-bằng-bước (tiếp)

Bước 3 (optional): Cấu hình API key

Nếu muốn test full workflow generate real:

• Mở .env ở root project (đã có template .env.example)
• Paste API key:

✓ Installed 320 packages
✓ Database ./prisma/dev.db created
✓ Schema synced
✓ Setup complete

Bước 3 (optional): Cấu hình API key

Nếu bỏ qua bước này, app vẫn chạy — chỉ là endpoint /api/generate trả static fake code thay vì gọi Claude thật. Đủ cho 90% bài học.

Bước 4: Chạy dev server

• Save.

ANTHROPIC_API_KEY=sk-ant-api03-...

Bước 4: Chạy dev server

Expected output:

npm run dev

Setup bước-bằng-bước (tiếp)

Mở http://localhost:3000 trong browser. Bạn thấy UI đơn giản với input box.

Bước 5: Test end-to-end

Nếu 4 bước trên pass → project sẵn sàng.

• Trong UI: nhập "Create a simple button" → submit
• Watch console: có log request /api/generate
• Component generated được preview render
• Check prisma/dev.db có record mới (dùng sqlite3 prisma/dev.db hoặc tool GUI)

▲ Next.js 14.x.x
- Local:        http://localhost:3000
- Ready in 2.1s

Cấu trúc project cần hiểu

Trước khi đến bài 4.6 (CLAUDE.md), nên nắm sơ layout:

Ba file bạn sẽ touch nhiều nhất trong khóa học:

• src/lib/prompts/generation.tsx — prompt template
• src/app/api/generate/route.ts — API logic
• CLAUDE.md (chưa có — sẽ tạo ở Bài 4.6)

uigen/
├── prisma/
│   ├── schema.prisma      ← DB schema
│   └── dev.db             ← SQLite file (gitignored)
├── src/
│   ├── app/
│   │   ├── page.tsx       ← Landing page
│   │   ├── api/
│   │   │   └── generate/
│   │   │       └── route.ts   ← API endpoint
│   │   └── (dashboard)/   ← Dashboard route group
│   ├── components/
│   │   ├── Editor.tsx
│   │   ├── Preview.tsx
│   │   └── PromptInput.tsx
│   └── lib/
│       ├── prompts/
│       │   └── generation.tsx  ← Prompt template cho Claude API
│       └── db/
│           └── client.ts
├── scripts/
│   └── init-claude.js     ← Setup helper cho Hooks (Bài 4.15)
├── .env.example
├── package.json
└── README.md

Nếu bạn muốn dùng project riêng

Hoàn toàn ủng hộ. Chỉ cần:

Khi khóa học tham chiếu file cụ thể trong uigen (ví dụ src/lib/prompts/generation.tsx), bạn tự map tương đương trong project của bạn.

Lưu ý an toàn:

• ☐ Project có ít nhất 20–30 file source
• ☐ Có package.json hoặc equivalent (requirements.txt, go.mod, Cargo.toml)
• ☐ Có ít nhất 1 test (để demo hook typecheck/test sau này)
• ☐ Đang trên Git (để experiment có thể rollback)
• ☐ Đừng dùng production branch để học — luôn tạo branch claude-code-experiments
• ☐ Đừng dùng project chứa secret chưa scrub
• ☐ Đừng dùng project có khách hàng paying nếu chưa tự tin — dùng side project trước

Ví dụ thực chiến: Setup + first task

Tình huống

Bạn vừa setup xong uigen. Dùng Claude Code làm task đầu tiên.

Prompt

cd ~/Projects/uigen
claude

Prompt

Kết quả

5 phút, bạn có overview ngang senior dành 30 phút đọc manual.

You: Xem project này, tóm tắt giúp tôi:
     1. Tech stack
     2. Flow chính
     3. 3 file quan trọng nhất
     4. Command để chạy dev và test

Claude:
  [Read] package.json
  [Read] README.md
  [Read] prisma/schema.prisma
  [Glob] src/**/*.{ts,tsx} → 47 files
  [Read] src/app/page.tsx
  [Read] src/app/api/generate/route.ts
  [Read] src/lib/prompts/generation.tsx

  Tóm tắt:
  
  1. Tech stack: Next.js 14, TypeScript, Prisma+SQLite, 
     Tailwind, Anthropic SDK, Vitest
  
  2. Flow: user prompt → POST /api/generate → Claude API 
     với system template từ lib/prompts/generation.tsx → 
     stream response về UI → lưu DB
  
  3. File trung tâm:
     - src/lib/prompts/generation.tsx (template prompt gửi Claude)
     - src/app/api/generate/route.ts (endpoint chính)
     - prisma/schema.prisma (model Generation, User)
  
  4. Commands:
     - npm run dev (port 3000)
     - npm run test (Vitest)
     - npm run typecheck

Case studies setup tương tự

💼 Startup founder — Học Claude Code trên MVP thực

Tình huống: Founder đang xây MVP SaaS, muốn học Claude Code trên product thật thay vì demo.

Approach:

🏫 University CS professor — Setup cho 60 sinh viên

Tình huống: Setup uigen cho class 60 SV, không muốn mỗi em tự debug setup.

Approach:

🛠️ Tech team lead — Uigen cho team workshop

Tình huống: Workshop 2-ngày Claude Code cho team 12 dev.

Approach:

• Tạo branch learning-claude-code
• Chạy /init → Claude hiểu MVP
• Mỗi bài khóa học, áp dụng luôn task thực tế có
• Kết quả: học vừa xong, MVP cũng tiến 2 sprint — double win.
• Teacher docker-hóa uigen + Claude Code
• SV pull image, docker run, ready to learn
• Kết quả: 100% SV dùng được trong 5 phút, focus vào học Claude Code thay vì debug Node version.
• Pre-work: gửi uigen zip + setup script 1 tuần trước workshop
• Ngày 1 sáng: kiểm tra ai chưa setup xong, fix ngay
• Cả ngày workshop dùng chung uigen
• Kết quả: không mất thời gian workshop để setup, done 100% curriculum trong 2 ngày.

Anti-patterns khi setup

❌ Bỏ qua npm run setup vì "tôi biết npm install rồi"

Hậu quả: prisma migrate không chạy → SQLite rỗng → app crash lúc save generation.

Fix: Luôn chạy command setup đúng như docs, không tự thay thế.

❌ Dùng Node.js 16 hoặc cũ hơn

Hậu quả: Next.js 14 require Node 18+. Sẽ lỗi lạ lúc npm run dev.

Fix:

❌ Chạy project trong folder path có space hoặc tiếng Việt

Ví dụ xấu: ~/Projects/Khóa học Claude/uigen

Hậu quả: Một số script shell parse path sai, crash ngẫu nhiên.

Fix: Dùng path ASCII, không space: ~/Projects/uigen hoặc ~/dev/uigen.

❌ Commit .env với API key

Đã nhắc ở Bài 4.4 nhưng quan trọng nhắc lại. .env.example OK commit (template), .env (chứa secret) KHÔNG.

Kiểm tra trước mỗi push:

nvm install 20
nvm use 20

❌ Commit .env với API key

❌ Không verify app chạy được trước khi qua Bài 4.6

Hậu quả: Sau 2 bài nữa bạn phát hiện setup sai → phải quay lại debug, mất flow học.

Fix: Làm đủ 5 bước verify ở phần "Setup" phía trên trước khi chuyển bài.

git status
git diff --cached | grep -i "api_key\|secret\|token"

Áp dụng ngay

Bài tập 1: Setup + verify uigen (15 phút)

Bước 1: Download/clone uigen.

Bước 2: npm run setup. Ghi thời gian: _____

Bước 3: npm run dev. Mở browser localhost:3000.

Bước 4: Thử tạo 1 component ("Create a badge with text"). Verify có response trong UI.

Bước 5: Check:

Nếu cả 3 ✅ → sẵn sàng Bài 4.6.

Bài tập 2 (optional, 10 phút): Explore với Claude Code

Mở Claude Code trong uigen folder. Chạy 3 prompt sau, ghi lại điều bạn học:

• DB file prisma/dev.db có tồn tại? ☐ Có ☐ Không
• Dev server chạy không lỗi warning? ☐ Có ☐ Không
• Component preview render? ☐ Có ☐ Không (nếu không có API key → fake code OK)
• "Xem schema DB, giải thích model chính."
• "Đọc src/lib/prompts/generation.tsx, nhận xét prompt engineering."

   Note: ________________________________

Bài tập 2 (optional, 10 phút): Explore với Claude Code

• "Xem test hiện có, có gap nào đáng viết thêm không?"

   Note: ________________________________

Áp dụng ngay (tiếp)

Ba prompt này chính là warm-up cho các bài tiếp theo.

   Note: ________________________________

Tóm tắt bài học

🎯 Uigen = project thực hành xuyên khóa — Next.js app dùng Claude API generate UI component.

🎯 Setup 3 bước — npm run setup, npm run dev, optional API key.

🎯 Có thể dùng project riêng — chỉ cần ≥20 file, Git, test tối thiểu.

🎯 Verify trước khi next bài — 5 checkpoint: npm, db, server, UI, request flow.

🎯 Không commit .env — luôn .gitignore trước khi test.