Vibe Coding：
用 AI 寫網站的真功夫

什麼是 Vibe Coding？

Vibe Coding 一詞 2025 年初由 Andrej Karpathy 提出，意思是：

「你只要照感覺寫，剩下的 AI 處理。」

但這詞被誤解很大。新手以為 = 對 ChatGPT 喊「做個 app」。真正的 Vibe Coding 是：

• 你負責架構決策、產品方向、程式碼審查
• AI 負責實作、樣板碼、查文件
• 你跟 AI 之間用文檔當合約，不是用聊天

三大文檔：你跟 AI 的合約

每個專案 root 必備這三個檔：

README.md（給人）

# SnowRealm Insight

AI 驅動的問卷 / 內容 / 社群平台。

## 跑起來

```bash
pnpm install
cp .env.example .env  # 填上 Supabase / OpenAI key
pnpm dev
```

## 技術棧

- Next.js 15 App Router
- Supabase (Postgres + Auth)
- shadcn/ui + Tailwind
- 部署在 Zeabur Tokyo

## 目錄

- `app/` — 路由
- `components/` — UI 元件
- `lib/` — 商業邏輯

CLAUDE.md：給 AI 的工程規範

這是 Vibe Coding 最關鍵的檔。寫好 CLAUDE.md，AI 寫出的 code 會跟你的專案 100% 一致風格。

# CLAUDE.md — Engineering Guidelines

## 你是誰
你是 SnowRealm 的工程助手，負責 Insight 專案。

## 鐵律（不能違反）
- 永遠用 TypeScript，禁止 `any`
- 所有 API route 用 Zod 驗證輸入
- 禁止把 secret 寫進 code
- 禁止用 useEffect 做資料 fetch（用 Server Component / SWR）
- 樣式用 Tailwind，禁止 inline style

## 命名
- 元件：PascalCase（`UserCard.tsx`）
- 工具函式：camelCase（`formatDate`）
- 常數：UPPER_SNAKE（`MAX_UPLOAD_SIZE`）

## 資料夾
- `app/[lang]/...` — 路由
- `components/ui/` — shadcn 元件，不要改
- `components/feature/` — 我們自己的元件
- `lib/supabase/` — DB query
- `lib/llm/` — LLM 相關

## Commit
用 conventional commits：`feat:`, `fix:`, `refactor:`, `docs:`
全英文。

## 改 code 前
1. 先讀 `design.md` 確認任務
2. 先讀相關檔案理解現狀
3. 再動手

## 改完後
1. 跑 `pnpm typecheck`
2. 跑 `pnpm lint`
3. 自己寫測試（Vitest）

design.md：規格驅動開發

每次要做新功能，先寫 design.md 給 AI 讀。範例：要做一個「訂閱電子報」功能。

# 訂閱電子報功能設計

## 目標
讓未登入訪客留 email，加進電子報名單。

## 使用者流程
1. 訪客點 footer 的「訂閱」按鈕
2. 跳出 modal，填 email
3. 送出 → 顯示「請查收驗證信」
4. 點驗證信內連結 → 啟用訂閱

## 技術方案
- 資料表：`newsletter_subscribers`
  - `id`, `email` (unique), `verified` (bool), `verified_at`, `created_at`
- API：
  - `POST /api/newsletter/subscribe` — 收 email，寄驗證信
  - `GET /api/newsletter/verify?token=...` — 驗證
- 信件用 Resend，模板用 React Email

## 邊界條件
- 同一 email 重複訂閱 → 重寄驗證信，不報錯
- 驗證 token 24 小時失效
- 驗證後不能再用同一 token

## 不做
- 取消訂閱（v2 再做）
- 寄電子報內容（這只是收名單）

把這個 design.md 丟給 AI，跟它說「按這個設計實作」，產出品質會差到天上去。

多 Agent 工作流：分工才會強

單一 AI agent 寫整個專案會崩。實戰上要分工：

典型一輪

1. 你給規劃 Agent 一句話需求：「做訂閱電子報功能」
2. 規劃 Agent 寫 design.md + 任務清單
3. 你檢查 design.md，調整
4. 執行 Agent 按任務清單一個個做
5. 每個任務做完，審查 Agent 看一遍
6. 你做最後 PR review，merge

實戰示範：SnowRealm 的雙 Agent 流程

以下是我們在 SnowRealm 真實用的流程，2025 年起跑了一年多，蓋出 Insight、YukiBoard、毛行天下、GLACÉRA 等多個產品。

環境

• Claude Code CLI（規劃 + 執行主力）
• Codex CLI（執行副手，跑長任務）
• 每個專案 root 有：CLAUDE.md、README.md、docs/ 目錄
• 每個 feature 開新 branch，新 docs/features/xxx-design.md

典型開發一個新功能

# 1. 開分支
git checkout -b feat/newsletter

# 2. 跟 Claude（規劃）對話
claude
> 我要做電子報訂閱功能。先讀 CLAUDE.md 跟 README.md，
> 然後幫我寫 docs/features/newsletter-design.md，
> 包含 schema、API、流程、邊界條件。

# Claude 寫好 design.md，你看過、修

# 3. Claude 拆任務
> 根據 design.md 列出實作 task list，
> 每個 task 一個檔案、一個 commit。

# 4. Codex（執行）開另一個視窗
codex
> 讀 docs/features/newsletter-design.md 跟 task list，
> 從 task 1 開始做。每個 task 做完跑 typecheck，
> 確認沒錯再做下一個。

# 5. 你定期回來看，調方向，merge

為什麼分兩個 Agent？

• 分工專注：規劃時不要寫 code，寫 code 時不要改架構
• 避免 context 爆掉：兩邊各自的 context window 短而精準
• 降低錯誤：執行 Agent 不會「自作主張改 schema」
• 方便審查：你可以隨時叫第三個 Agent 檢查另兩邊產出

把任務拆到 AI 寫得動

AI 一次能處理的範圍有限。學會拆任務是 Vibe Coding 的核心技能。

反例（會失敗）

「做一個訂閱電子報功能」— 這太大，AI 會寫一堆殘缺不全的東西。

正例（會成功）

## Task List

- [ ] T1. 建 newsletter_subscribers 資料表（migration）
- [ ] T2. 寫 lib/email/resend.ts（Resend client）
- [ ] T3. 寫 lib/email/templates/verify.tsx（React Email 模板）
- [ ] T4. 寫 POST /api/newsletter/subscribe（含 Zod 驗證）
- [ ] T5. 寫 GET /api/newsletter/verify
- [ ] T6. 寫 components/feature/newsletter/SubscribeModal.tsx
- [ ] T7. 在 footer 加按鈕觸發 modal
- [ ] T8. 寫測試（Vitest，每個 API 至少 3 個 case）
- [ ] T9. 更新 README.md 加 Resend env var 說明

每個 task 一個檔案、一件事、20–80 行 code。AI 做這種大小最穩。

跟 AI 一起 Debug

Bug 出現時的對話模板：

我遇到一個 bug。

【現象】
使用者 submit form 後，顯示「成功」但資料庫沒紀錄。

【已知資訊】
- API 是 /api/newsletter/subscribe
- console 沒 error
- 資料庫 query 直接跑會成功

【我試過】
- 加 console.log，看到 req.body 是對的
- 看 supabase log，沒有任何 query 進來

【我猜】
是不是 supabase client 沒拿到正確 env var？

【請你做】
1. 讀 lib/supabase/client.ts
2. 讀 app/api/newsletter/subscribe/route.ts
3. 找出問題，給修正方案
4. 不要直接動 code，先告訴我原因

關鍵：給結構化資訊、要求結構化回答、先要求診斷再要求修。

Refactor 時的協作

程式碼變亂了想重構？AI 是最好的搭擋，但要分階段：

1. Phase 1：診斷「讀 components/UserCard.tsx，告訴我它有什麼壞 smell」
2. Phase 2：規劃「擬定一個重構計畫，不要動 public API，分 5 個 commit」
3. Phase 3：執行「執行第 1 個 commit，做完跑 test 確認沒壞」
4. Phase 4：驗證「對比重構前後，列出行為差異」

絕對不要

• 沒測試就重構（你會永遠不知道是不是壞了）
• 一次重構一大塊（diff 太大看不出問題）
• 讓 AI 改名字（變數、檔案）但沒看 reference

Context 管理：AI 的記憶有限

每個 LLM 有 context window 上限。聊太久 AI 會忘前面講過什麼，產出品質直線下降。

三招維持 context 品質

1. 定期重啟：聊到 50 輪以上就開新對話，把關鍵結論摘要進 design.md
2. 用文檔當 memory：重要決策寫成檔案，新對話開頭叫 AI 讀
3. 分 session 任務：一個 session 做一件事，做完關掉

SnowRealm 實作

我們專案有 docs/decisions/ 目錄，每個重大決策一個 ADR（Architecture Decision Record）：

# ADR-007 SnowRealmClaw 三層權限

## Status
Accepted (2025-04)

## Context
SnowRealmClaw 要同時服務 Luffysky 個人、自家產品、B2C 客戶。

## Decision
A+B+C 三層：
- A：個人（Max OAuth，僅 Luffysky）
- B：產品（API key，自家產品 backend）
- C：B2C（Z-coin + API）

## Consequences
- 每個 Skill 必須宣告 allowed_modes
- Day 1 就要有 auth-routing 層
- Max token 嚴禁服務外人

每次新對話讓 AI 讀 docs/decisions/，它就有所有歷史脈絡。

實戰：用這套做出第一個產品

步驟模板（複製來用）：

1. Day 1：寫 README.md（產品是什麼、誰用）
2. Day 1：寫 CLAUDE.md（技術規範）
3. Day 2：跟 Claude 一起寫 docs/architecture.md（整體架構）
4. Day 3：列 MVP feature list，每個 feature 一個 design.md
5. Day 4–N：每天做 1–2 個 feature，嚴格走 design.md → task list → 執行 → review
6. 每週：回顧、更新 CLAUDE.md（把這週踩到的雷加進去）

這套不快，但穩。新手 1 個月能做出一個能上線的產品。