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

Mở đầu: Tại sao không học trên project giả?

Claude Code chỉ phát huy khi ở codebase thực sự. Với 3 file, Grep không cần thiết, Planning Mode cũng vô dụng, Hooks không có gì để hook vào. Bạn sẽ không cảm nhận được giá trị.

Giải pháp: chúng tôi cung cấp uigen — một Next.js app thật, nhỏ nhưng có cấu trúc đầy đủ (API route, DB, React component, test, prompt template). Bạn có thể:

• Follow example chính xác như khóa học
• Hoặc dùng project thật của bạn (khuyên dùng nếu có) — chỉ cần đọc kỹ để map concept

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.

┌──────────────────────────────────────────────────────────┐
│                                                          │
│  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   │                           │
│           └──────────────────┘                           │
│                                                          │
└──────────────────────────────────────────────────────────┘

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

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

Bắt buộc

• Node.js 18+ (nodejs.org)
• npm (đi kèm Node)
• Git
• Claude Code đã cài (Bài 4.4)

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

• Anthropic API key (console.anthropic.com) — nếu muốn uigen thực sự generate thay vì trả fake output

Kiểm tra prerequisite

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:

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

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

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

Bước 2: Setup

cd ~/Projects/uigen
npm run setup

Script setup làm hai việc:

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

Output success giống:

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

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

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

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

ANTHROPIC_API_KEY=sk-ant-api03-...

1. Save.

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

npm run dev

Expected output:

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

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

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

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

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:

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

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

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

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

Hoàn toàn ủng hộ. Chỉ cầ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)

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:

• Đừ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

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

Kết quả

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

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:

• 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.

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:

• 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.

Tech team lead — Uigen cho team workshop

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

Approach:

• 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:

nvm install 20
nvm use 20

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:

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

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.

Á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:

• 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)

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:

1. "Xem schema DB, giải thích model chính."

   Note: ________________________________

1. "Đọc src/lib/prompts/generation.tsx, nhận xét prompt engineering."

   Note: ________________________________

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

   Note: ________________________________

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

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

Tài liệu tham khảo

• Next.js 14 docs
• Prisma docs
• Anthropic SDK (TS)
• Bài 4.4 — Cài đặt Claude Code
• Bài 4.6 — Thêm context với CLAUDE.md (cho uigen)