dramaling-vocab-learning/docs/03_development/claude-code-development-sop.md

# Claude Code 開發 SOP 流程

## 🎯 目標
確保使用 Claude Code 進行開發時，能夠穩定、有序地修正和增強現有功能。

## 📋 標準作業流程

### 1️⃣ 需求分析階段

#### 1.1 明確定義需求
```markdown
## 修改需求
- **功能名稱**: [例如: 登入流程]
- **現況問題**: [描述現有問題]
- **期望結果**: [描述預期行為]
- **影響範圍**: [列出可能受影響的檔案/功能]
- **優先級**: [高/中/低]
```

#### 1.2 需求模板
```markdown
# 需求：[功能名稱]

## 現況
- 現有行為：
- 問題描述：
- 相關檔案：

## 期望
- 新行為：
- 成功標準：
- 測試案例：

## 限制
- 必須保留：
- 不可更動：
- 效能要求：
```

### 2️⃣ 開發前準備

#### 2.1 環境檢查
```bash
# 1. 確認開發伺服器狀態
npm run dev

# 2. 確認 Git 狀態
git status

# 3. 創建新分支
git checkout -b feature/[功能名稱]
```

#### 2.2 備份關鍵檔案
```bash
# 備份將要修改的檔案
cp app/[檔案名].tsx app/[檔案名].tsx.backup
```

### 3️⃣ 與 Claude Code 協作流程

#### 3.1 初始對話模板
```markdown
我需要修改 [功能名稱]，請幫我：

1. 先讀取相關檔案：
   - [檔案路徑1]
   - [檔案路徑2]

2. 分析現有實作

3. 確認修改方案

4. 實施修改

要求：
- 保持現有功能不受影響
- 遵循現有程式碼風格
- 加入適當的錯誤處理
```

#### 3.2 階段性確認
```markdown
## 檢查點
- [ ] 需求理解正確
- [ ] 影響範圍評估完成
- [ ] 修改方案確認
- [ ] 程式碼修改完成
- [ ] 功能測試通過
- [ ] 無破壞現有功能
```

### 4️⃣ 實作階段

#### 4.1 修改優先順序
1. **資料模型** (types, interfaces)
2. **API 邏輯** (API routes, services)
3. **狀態管理** (stores, contexts)
4. **UI 組件** (components)
5. **樣式調整** (CSS, Tailwind)

#### 4.2 程式碼修改原則
```typescript
// ❌ 避免：直接覆蓋整個檔案
// ✅ 建議：精準修改特定函數或區塊

// ❌ 避免：刪除未使用的程式碼
// ✅ 建議：先註解，確認無誤後再刪除

// ❌ 避免：一次修改多個功能
// ✅ 建議：單一功能逐步修改
```

#### 4.3 安全修改策略
```markdown
## 修改策略
1. **增量修改**：先新增，後替換，最後刪除舊代碼
2. **功能開關**：使用 feature flag 控制新舊功能
3. **漸進式重構**：保持功能可用的前提下逐步改進
```

### 5️⃣ 測試驗證

#### 5.1 功能測試清單
```markdown
## 測試項目
- [ ] 正常流程測試
- [ ] 邊界條件測試
- [ ] 錯誤處理測試
- [ ] 響應式設計測試
- [ ] 效能測試
```

#### 5.2 測試指令
```bash
# 1. 本地測試
npm run dev
# 手動測試各項功能

# 2. 建置測試
npm run build
# 確認無編譯錯誤

# 3. TypeScript 檢查
npx tsc --noEmit

# 4. Lint 檢查
npm run lint
```

### 6️⃣ 版本控制

#### 6.1 提交規範
```bash
# 提交格式
git add [修改的檔案]
git commit -m "[type]: [description]"

# Type 類型：
# feat: 新功能
# fix: 修復錯誤
# refactor: 重構
# style: 樣式修改
# docs: 文檔更新
# test: 測試相關
# chore: 其他修改
```

#### 6.2 提交前檢查
```markdown
## 提交前確認
- [ ] 功能正常運作
- [ ] 無 console.log 遺留
- [ ] 無敏感資訊外洩
- [ ] 程式碼已格式化
- [ ] 註解已更新
```

### 7️⃣ 問題處理

#### 7.1 常見問題與解決
```markdown
## 編譯錯誤
1. 清除快取：rm -rf .next
2. 重新安裝：rm -rf node_modules && npm install
3. 重啟開發伺服器

## 樣式不生效
1. 檢查 Tailwind 類名
2. 清除瀏覽器快取
3. 檢查 CSS 載入順序

## 狀態不同步
1. 檢查 useState/useEffect
2. 確認資料流向
3. 使用 React DevTools 調試
```

#### 7.2 回滾策略
```bash
# 方法 1：使用備份
cp app/[檔案名].tsx.backup app/[檔案名].tsx

# 方法 2：Git 回滾
git checkout -- [檔案路徑]

# 方法 3：回到上一個提交
git reset --hard HEAD^
```

### 8️⃣ 最佳實踐

#### 8.1 與 Claude Code 溝通技巧
```markdown
## 有效溝通
1. **具體明確**：提供檔案路徑、行號、函數名
2. **分步進行**：複雜修改分解為多個小步驟
3. **即時反饋**：發現問題立即告知
4. **保存對話**：重要決策和方案記錄下來
```

#### 8.2 開發習慣
```markdown
## 良好習慣
- ✅ 每完成一個小功能就測試
- ✅ 定期提交到 Git
- ✅ 保持開發伺服器運行
- ✅ 使用瀏覽器開發工具監控
- ✅ 記錄修改日誌
```

### 9️⃣ 文檔維護

#### 9.1 修改記錄模板
```markdown
# 修改記錄

## [日期] - [功能名稱]
### 修改內容
- 檔案：[路徑]
- 改動：[描述]
- 原因：[為什麼修改]

### 測試結果
- [x] 功能測試通過
- [x] 無副作用
- [x] 效能正常

### 備註
[任何特殊說明]
```

#### 9.2 知識累積
```markdown
## 經驗總結
- 問題：[遇到的問題]
- 解決：[解決方案]
- 學習：[獲得的經驗]
- 建議：[未來改進建議]
```

## 🔄 持續改進

### 定期檢視
- 每週回顧開發流程
- 記錄痛點和改進點
- 更新 SOP 文檔

### 工具優化
- 建立程式碼片段庫
- 自動化重複任務
- 優化開發環境配置

## 📊 檢查清單總覽

```markdown
# 快速檢查清單

## 開始前
- [ ] 需求明確
- [ ] 環境就緒
- [ ] 分支創建

## 開發中
- [ ] 讀取相關檔案
- [ ] 分析影響範圍
- [ ] 逐步實施修改
- [ ] 即時測試驗證

## 完成後
- [ ] 全面功能測試
- [ ] 程式碼檢查
- [ ] Git 提交
- [ ] 文檔更新
```

## 🚀 快速開始指令

```bash
# 1. 開始新功能
git checkout -b feature/new-feature
npm run dev

# 2. 測試修改
npm run build
npx tsc --noEmit

# 3. 提交更改
git add .
git commit -m "feat: add new feature"
git push origin feature/new-feature
```