AI 協作實戰：從需求到部署

完整案例：用 AI 從零建一個吉他教學網站

💡 比喻：蓋房子 傳統方式：你一個人搬磚、砌牆、裝修 → 很慢 AI 協作：你當建築師畫設計圖，AI 幫你施工 → 很快

但你還是要會看設計圖（看得懂 code）， 知道什麼結構安全（理解架構）， 以及驗收品質（測試和 Review）。

接下來我們用一個真實案例，示範從需求描述到成功部署的完整流程。

Step 1：寫好 Prompt（需求描述）

一切的起點是一個好的需求描述。

初始 Prompt 範例

你是一個資深 ASP.NET Core 開發者。

請幫我從零建立一個吉他教學網站 "GuitarSchool"：

【技術棧】
- .NET 8 + ASP.NET Core MVC
- SQLite + Entity Framework Core
- Bootstrap 5 + 自訂 CSS

【功能需求】
1. 首頁：Hero Banner + 精選課程 + 老師介紹
2. 課程列表：依難度篩選（初學/中級/進階），卡片排版
3. 課程詳情：Markdown 內容渲染、影片嵌入
4. 聯絡表單：Name, Email, Phone, Message
5. 關於頁面：學校介紹 + Google Map

【設計風格】
- 暖米色系（背景 #F5F1EB，文字 #2C3E50）
- 圓角按鈕、卡片陰影
- 響應式設計（手機、平板、桌面）
- 字體：Google Fonts Noto Sans TC

【部署方式】
- Docker container
- Railway 平台
- 需要 Dockerfile

【注意事項】
- View 文字全部繁體中文
- 所有 action 用 async/await
- 加上中文註解
- Seed Data 至少 6 堂課程

為什麼這個 Prompt 有效？

✅ 明確的角色：「資深 ASP.NET Core 開發者」
✅ 完整的技術棧：.NET 8、SQLite、Bootstrap 5
✅ 具體的功能：5 個頁面，每個都有描述
✅ 設計規範：色碼、圓角、字體
✅ 部署資訊：Docker + Railway
✅ 限制條件：繁體中文、async/await、註解

Step 2：AI 規劃架構

不要讓 AI 直接寫 code！先讓它規劃。

使用 Plan Mode

> 先用 plan mode 規劃這個專案的架構，
> 不要直接寫 code。
> 列出：
> 1. 資料夾結構
> 2. 所有 Model
> 3. 所有 Controller 和 Action
> 4. 所有 View
> 5. 實作順序

AI 會回傳一個完整的規劃，像這樣：

實作順序：
1. 建立專案 + 基本架構
2. Model + DbContext + Migration
3. Seed Data（課程資料）
4. HomeController + 首頁 View
5. CourseController + 課程列表/詳情 View
6. ContactController + 聯絡表單
7. CSS 調整 + 響應式設計
8. Dockerfile + 部署設定

你確認計畫 OK 後，AI 才開始實作。

Step 3：分批執行

💡 比喻：吃飯 不要把整桌菜一口塞進嘴裡，一道一道吃。 不要一次給 AI 所有工作，分批做品質更好。

批次執行策略

第一批：基礎建設
"建立專案 + Model + DbContext + Migration + Seed Data"
→ 確認 dotnet build 成功

第二批：頁面開發
"建立 HomeController + 首頁 View + 課程列表 View"
→ 確認 dotnet run 後頁面正常

第三批：功能完善
"加上聯絡表單 + 課程詳情 + 關於頁面"
→ 手動測試每個功能

第四批：樣式調整
"CSS 調整：暖米色系、圓角、陰影、響應式"
→ 用不同裝置尺寸檢查

第五批：部署
"建立 Dockerfile + docker-compose.yml + Railway 設定"
→ 本地 Docker 測試 → 部署到 Railway

每批完成後的檢查清單

□ dotnet build 編譯成功？
□ dotnet run 啟動正常？
□ 頁面載入正確？
□ 功能操作正確？
□ 手機版顯示正常？
□ 沒有 console 錯誤？
□ git commit 備份？

Step 4：遇到問題怎麼辦

真實開發一定會遇到問題。以下是常見問題和解決方式。

問題 1：500 Internal Server Error

你："網站出現 500 錯誤，幫我找原因"

AI 的處理流程：
1. 讀取 log 檔案或 console 輸出
2. 找到錯誤訊息：
   "System.InvalidOperationException:
    The ForwardedHeaders middleware must be added..."
3. 定位問題：Railway 用 reverse proxy，
   需要設定 ForwardedHeaders
4. 修復：在 Program.cs 加上 ForwardedHeaders 設定

修復後你只需要確認：頁面正常載入了嗎？

問題 2：部署失敗

你："Railway 部署後網站無法登入，Cookie 有問題"

AI 的處理流程：
1. 分析問題：Railway 用 HTTPS proxy
   但 Cookie 的 SameSite 設定不相容
2. 修復：把 Cookie SameSite 改成 SameSiteMode.Lax
   或在 production 環境設定正確的 Cookie policy
3. 重新部署

你只需要確認：登入功能正常了嗎？

問題 3：CSS 跑版

你："手機版的 Navbar 跑版，漢堡選單打不開"

好的問題描述：
"手機版（<768px）的 Navbar 有兩個問題：
  1. 漢堡選單按鈕點擊沒反應
  2. 下拉選單的背景色是透明的，看不到文字
  請檢查 Bootstrap JS 有沒有正確引入，
  以及 navbar-collapse 的 CSS"

Step 5：自動化設定

當網站基本完成後，設定自動化讓開發更順暢。

設定 CLAUDE.md

# GuitarSchool 專案

## 技術棧
- .NET 8 + ASP.NET Core MVC
- SQLite + EF Core
- Bootstrap 5
- 部署：Railway

## 重要指令
- dotnet build：編譯
- dotnet run：啟動（port 5001）
- docker build -t guitarschool .：建 Docker image

## CSS 色碼
- 背景：#F5F1EB
- 文字：#2C3E50
- 強調：#E67E22

## 注意
- 繁體中文
- async/await
- 不用 Repository Pattern

設定 bypassPermissions

{
  "permissions": {
    "allow": [
      "Bash(dotnet *)",
      "Bash(git *)",
      "Read(*)",
      "Write(*.cs)",
      "Write(*.cshtml)",
      "Write(*.css)",
      "Write(*.json)"
    ]
  }
}

設定 Deploy Skill

建立 .claude/skills/deploy/SKILL.md：

---
description: 部署 GuitarSchool 到 Railway
command: deploy
---

1. dotnet build -c Release
2. dotnet test（如果有測試）
3. git add -A
4. git commit -m "deploy: update"
5. git push origin main
6. 回報部署結果

以後只要在 Claude Code 輸入 /deploy 就能一鍵部署。

Step 6：持續迭代

網站上線後，你還可以持續用 AI 加功能。

一句話加功能

"幫我在首頁加上老師介紹區塊，
  三個老師的照片和簡介，用 Bootstrap Card 排版"

"幫我加上 SEO meta tags，
  每個頁面都要有 title 和 description"

"幫我在課程詳情頁加上價格表，
  分成單堂/10堂/20堂，用表格呈現"

"幫我把聯絡表單改成能寄 Email，
  用 MailKit 套件，SMTP 設定放環境變數"

每個需求都只要一句話，因為 AI 已經透過 CLAUDE.md 知道你的專案。

迭代的最佳實踐

1. 每次只做一個功能
2. 做完就 commit（備份）
3. 測試完再進入下一個功能
4. 重大變更前先開 branch
5. 定期更新 CLAUDE.md

給新手的建議

建議 1：從小任務開始

不要一開始就叫 AI 做一整個系統。
先從小任務建立信心：

Week 1："幫我改按鈕顏色"
Week 2："幫我加一個頁面"
Week 3："幫我建一個 CRUD 功能"
Week 4："幫我從零建一個小專案"

像學開車一樣，先在停車場練習，再上馬路。

建議 2：習慣看 AI 的程式碼

❌ AI 寫完 → 直接用 → 出問題不知道怎麼修

✅ AI 寫完 → 你看一遍 → 理解邏輯 → 有問題問 AI：
"這段 code 的 .Where() 為什麼用 Contains 而不是 ==？"
"這個 async Task<IActionResult> 是什麼意思？"

→ 每次 Review 都是學習機會

建議 3：學會用 Git 備份

AI 也會犯錯。它可能：
- 不小心刪掉你的檔案
- 大改架構後編譯不過
- 改壞一個功能的同時影響另一個功能

保護自己的方法：

# 每次讓 AI 大改前
git add -A && git commit -m "backup before AI changes"

# AI 改壞了？一鍵還原
git checkout .

# 更安全：開一個新 branch
git checkout -b feature/new-feature
# 讓 AI 在 branch 上改
# 確認沒問題後再 merge

建議 4：建立自己的 Prompt 模板

隨著經驗累積，你會發現某些 Prompt 模式特別有效。
把它們存起來：

模板 1：新功能
"在 {Controller} 加上 {功能名稱}，
  Model 是 {Model}（{欄位列表}），
  View 用 {排版方式}，
  注意 {限制條件}"

模板 2：修 Bug
"{檔案} 第 {行數} 出現 {錯誤類型}，
  {變數/物件} 是 {狀態}，
  請檢查 {可能原因}"

模板 3：改樣式
"把 {元件} 的 {屬性} 改成 {值}，
  hover 時 {變化}，
  加上 {動畫}"

完整工作流程圖

┌─────────────────────────────────────────────────────┐
│                    AI 協作開發流程                      │
├─────────────────────────────────────────────────────┤
│                                                      │
│  1. 準備階段                                          │
│     ├── 寫好 CLAUDE.md（專案記憶）                     │
│     ├── 設定 .mcp.json（MCP 插件）                     │
│     ├── 設定 bypassPermissions（免問許可）              │
│     └── 建立 Skills（常用指令）                         │
│                                                      │
│  2. 開發階段                                          │
│     ├── 寫好 Prompt（具體需求）                         │
│     ├── 讓 AI 規劃（Plan Mode）                        │
│     ├── 分批執行（一次一個功能）                         │
│     ├── 每批檢查（build + run + test）                  │
│     └── git commit 備份                                │
│                                                      │
│  3. 問題排除                                          │
│     ├── 看 error log                                  │
│     ├── 描述具體錯誤給 AI                               │
│     ├── AI 修復 → 你驗證                                │
│     └── 修不好？還原 git → 換方式                        │
│                                                      │
│  4. 部署上線                                           │
│     ├── Docker build 測試                               │
│     ├── 部署到 Railway                                  │
│     ├── 線上測試所有功能                                 │
│     └── 設定自動部署 Hook                                │
│                                                      │
│  5. 持續迭代                                           │
│     ├── 一句話加新功能                                   │
│     ├── 每次 commit 備份                                │
│     ├── 定期更新 CLAUDE.md                               │
│     └── 經驗存入 Memory MCP                              │
│                                                      │
└─────────────────────────────────────────────────────┘

🤔 常見錯誤

錯誤 1：不備份就讓 AI 大改

❌ 直接跟 AI 說「重構整個專案」
→ AI 改壞了 → 沒有備份 → 全部重來

✅ 大改之前一定先備份：
git add -A && git commit -m "backup before refactor"
→ 改壞了隨時還原

錯誤 2：不測試就部署

❌ AI 說「改好了」→ 直接部署到線上
→ 線上爆炸 → 用戶看到 500 錯誤

✅ 部署前檢查清單：
□ dotnet build 成功？
□ dotnet run 本地正常？
□ Docker build 成功？
□ Docker run 本地正常？
□ 所有頁面都能載入？
□ 表單提交正常？
□ 手機版正常？
→ 全部通過才部署

錯誤 3：把 API Key 給 AI 貼在公開地方

❌ 在 Prompt 裡告訴 AI：
"SMTP 密碼是 abc123，寫在 appsettings.json"
→ 如果 appsettings.json 被 commit 到 GitHub → 密碼外洩

✅ 正確做法：
"SMTP 設定用環境變數，
  本地用 dotnet user-secrets，
  Railway 用 Variables 設定，
  不要寫在任何會被 commit 的檔案裡"

本章重點整理