Claude Code 作為 Anthropic 官方推出的 AI 驅動開發工具,正在改變軟體開發的工作方式。然而,要充分發揮其潛力,需要掌握正確的使用方法和最佳實踐。本文彙整了 20 個實用技巧,幫助開發者更有效地使用 Claude Code。
🎯 為什麼需要最佳實踐?
在深入技巧之前,先理解為什麼最佳實踐如此重要:
❌ 常見錯誤使用方式:
使用者: "幫我修這個 bug"
Claude: [不知道要看哪個檔案]
使用者: "檢查 app.js"
Claude: [讀取後發現需要其他檔案]
使用者: "還需要 utils.js"
...反覆來回多次...
✅ 最佳實踐方式:
使用者: "在 src/app.js 的第 45 行有個錯誤,當使用者
登入時會拋出 'undefined is not a function'。
可能與 src/utils/auth.js 的 validateToken
函式有關。請幫我診斷並修復。"
Claude: [一次性理解問題背景,高效解決]
效率差異:
- 錯誤方式:5-10 次對話來回,耗時 10-15 分鐘
- 最佳實踐:1-2 次對話,耗時 2-3 分鐘
- 效率提升:5 倍以上
📋 最佳實踐總覽
本文將最佳實踐分為五大類別:
┌─────────────────────────────────────────────────────┐
│ Claude Code 最佳實踐架構 │
│ │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ 溝通技巧 │ │ 專案管理 │ │
│ │ │ │ │ │
│ │ • 清晰指令 │ │ • 檔案組織 │ │
│ │ • 提供背景 │ │ • 版本控制 │ │
│ │ • 分步驟 │ │ • 文檔維護 │ │
│ └────────────────┘ └────────────────┘ │
│ │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ 效率優化 │ │ 品質保證 │ │
│ │ │ │ │ │
│ │ • Context 管理 │ │ • 程式碼審查 │ │
│ │ • 工具使用 │ │ • 測試策略 │ │
│ │ • 批次處理 │ │ • 安全檢查 │ │
│ └────────────────┘ └────────────────┘ │
│ │
│ ┌────────────────┐ │
│ │ 團隊協作 │ │
│ │ │ │
│ │ • 共享規範 │ │
│ │ • 知識傳承 │ │
│ │ • 工作流程 │ │
│ └────────────────┘ │
└─────────────────────────────────────────────────────┘
🗣️ 類別一:有效溝通技巧
1. 提供清晰、具體的指令
❌ 不好的做法:
"幫我優化這個函式"
"這裡有個 bug"
"讓這個程式更快"
✅ 好的做法:
"優化 src/utils/dataProcessor.js:processLargeDataset()
函式的效能。目前處理 10,000 筆資料需要 5 秒,目標
是降到 1 秒以內。可能的優化方向:
1. 使用 Map 取代陣列查找
2. 實作批次處理
3. 考慮使用 Web Workers"
範例對比:
1// ❌ 模糊指令
2"改善這個 API"
3
4// ✅ 具體指令
5"重構 src/api/userService.ts 的 fetchUserData() 方法:
61. 加入請求快取機制(5 分鐘過期)
72. 實作錯誤重試邏輯(最多 3 次,指數退避)
83. 加入 TypeScript 型別定義
94. 新增單元測試
105. 使用現有的 axios 實例(src/config/axios.ts)"
2. 提供充足的背景資訊
背景資訊檢查清單:
1在請求協助前,確認是否提供:
2
3✓ 專案背景
4 - 專案類型(React SPA、Node.js API、Python CLI 等)
5 - 技術棧(使用的框架、函式庫)
6 - 開發環境(Node 版本、套件管理工具)
7
8✓ 問題背景
9 - 預期行為 vs 實際行為
10 - 重現步驟
11 - 錯誤訊息(完整的 stack trace)
12 - 相關檔案路徑
13
14✓ 限制條件
15 - 必須使用的技術或方法
16 - 不能修改的部分
17 - 效能或安全性要求
18 - 相容性需求
實際範例:
// ❌ 缺乏背景
"使用者無法登入"
// ✅ 完整背景
"在生產環境中,使用者嘗試用 Google OAuth 登入時失敗。
【環境資訊】
- Next.js 14.0 with App Router
- next-auth 5.0.0
- 部署在 Vercel
【錯誤訊息】
OAuthAccountNotLinked: Another account already exists with
the same email address
【重現步驟】
1. 使用者先用 email/password 註冊(user@example.com)
2. 登出
3. 嘗試用 Google 帳號登入(同樣的 email)
4. 出現上述錯誤
【相關檔案】
- src/app/api/auth/[...nextauth]/route.ts
- src/lib/auth.ts
- prisma/schema.prisma
【預期行為】
應該自動連結現有帳號,或顯示友善的錯誤訊息"
3. 將複雜任務分解為小步驟
為什麼要分步驟?
大任務(一次完成):
┌────────────────────────────────────┐
│ 建立完整的電商網站 │
│ • 前端 UI │
│ • 後端 API │
│ • 資料庫設計 │
│ • 使用者認證 │
│ • 支付整合 │
│ • Email 通知 │
└────────────────────────────────────┘
↓
❌ 問題:
• 難以追蹤進度
• 錯誤難以定位
• 無法逐步驗證
• 容易超出 context
小步驟(逐步完成):
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Step 1 │ → │ Step 2 │ → │ Step 3 │
│ 資料庫 │ │ API 基礎 │ │ 使用者 │
│ Schema │ │ 架構 │ │ CRUD │
└──────────┘ └──────────┘ └──────────┘
↓ ↓ ↓
✅ 優點:
• 逐步驗證功能
• 問題容易定位
• 可隨時調整方向
• Context 保持清晰
實際步驟規劃範例:
1任務:實作使用者認證系統
2
3【Step 1: 資料庫設計】(15 分鐘)
4- 設計 User schema(Prisma)
5- 包含必要欄位:email, password hash, roles
6- 建立 migration
7
8【Step 2: 註冊功能】(20 分鐘)
9- POST /api/auth/register endpoint
10- Email 驗證
11- 密碼雜湊(bcrypt)
12- 寫入資料庫
13- 單元測試
14
15【Step 3: 登入功能】(20 分鐘)
16- POST /api/auth/login endpoint
17- 驗證憑證
18- 產生 JWT token
19- 單元測試
20
21【Step 4: JWT 中介層】(15 分鐘)
22- 建立 authenticateToken middleware
23- 驗證 token 有效性
24- 將 user 資訊附加到 request
25
26【Step 5: 保護路由】(10 分鐘)
27- 套用 middleware 到需要認證的路由
28- 測試保護機制
29
30【Step 6: 前端整合】(30 分鐘)
31- 登入/註冊表單
32- Token 儲存(localStorage)
33- API 呼叫攔截器
34- 錯誤處理
35
36每個步驟完成後都要測試驗證!
4. 使用範例和參考資料
提供範例的好處:
1// ❌ 只描述需求
2"建立一個 API endpoint 來取得使用者資料"
3
4// ✅ 提供參考範例
5"建立一個類似現有 getProducts 的 API endpoint 來取得
6使用者資料。參考 src/api/products.ts:
7
8現有範例:
9export async function getProducts(req: Request, res: Response) {
10 try {
11 const products = await db.product.findMany({
12 where: { active: true },
13 include: { category: true }
14 });
15 return res.json({ data: products });
16 } catch (error) {
17 return res.status(500).json({ error: error.message });
18 }
19}
20
21請建立類似的 getUsers endpoint,但需要:
221. 只返回 active users
232. Include user's roles 和 profile
243. 支援 pagination(page, limit 參數)
254. 加入 search 功能(by email or name)"
5. 明確指出不要改動的部分
範例:
1// ✅ 明確標示不可修改的部分
2"重構 src/services/paymentService.ts,改善錯誤處理。
3
4⚠️ 不要修改:
5- processPayment() 的函式簽名
6- PAYMENT_GATEWAY_URL 常數
7- 現有的 webhook 處理邏輯
8
9✅ 可以修改:
10- 錯誤處理方式
11- 重試邏輯
12- 日誌記錄
13- 型別定義"
📁 類別二:專案與檔案管理
6. 維護清晰的檔案結構
良好的專案結構:
src/
├── components/ # UI 元件
│ ├── common/ # 共用元件
│ ├── features/ # 功能特定元件
│ └── layouts/ # 版面配置
├── services/ # API 服務層
│ ├── api/ # API 呼叫
│ └── business/ # 業務邏輯
├── utils/ # 工具函式
│ ├── validation/ # 驗證函式
│ └── formatting/ # 格式化函式
├── types/ # TypeScript 型別定義
├── hooks/ # React Hooks
├── contexts/ # React Contexts
└── config/ # 設定檔
【原則】
✓ 按功能分組,而非檔案類型
✓ 每個資料夾有明確的職責
✓ 避免巢狀超過 3 層
✓ 相關檔案放在一起
7. 使用描述性的檔案和函式命名
命名對比:
1// ❌ 不好的命名
2data.ts
3utils.ts
4helper.ts
5function doStuff() {}
6function handle() {}
7
8// ✅ 好的命名
9userDataTransformer.ts
10dateFormatUtils.ts
11authenticationHelper.ts
12function transformUserDataForDisplay() {}
13function handleUserLoginSuccess() {}
命名規範範例:
1// 檔案命名
2userAuthenticationService.ts // 服務類別
3formatUserName.ts // 工具函式
4UserProfileCard.tsx // React 元件
5useUserData.ts // Custom Hook
6UserContext.tsx // React Context
7
8// 函式命名(動詞開頭)
9function fetchUserData() {} // 取得資料
10function validateEmail() {} // 驗證
11function transformToDTO() {} // 轉換
12function calculateTotalPrice() {} // 計算
13function isUserAuthenticated() {} // 布林判斷
14
15// 變數命名(名詞)
16const userData = ...
17const isLoading = ...
18const hasError = ...
19const userCount = ...
8. 適時使用 .claudeignore
範例 .claudeignore 檔案:
1# .claudeignore
2
3# 依賴套件
4node_modules/
5.pnp/
6.pnp.js
7
8# 建置產物
9dist/
10build/
11.next/
12out/
13
14# 快取
15.cache/
16.parcel-cache/
17.eslintcache
18
19# 環境變數(敏感資訊)
20.env
21.env.local
22.env.*.local
23
24# 日誌
25*.log
26npm-debug.log*
27
28# IDE 設定
29.vscode/
30.idea/
31*.swp
32*.swo
33
34# 測試覆蓋率報告
35coverage/
36.nyc_output/
37
38# 大型資料檔案
39*.csv
40*.json.large
41data/raw/
42
43# 圖片和媒體(通常不需要 Claude 讀取)
44*.png
45*.jpg
46*.jpeg
47*.gif
48*.mp4
49*.pdf
50
51# 編譯後的檔案
52*.min.js
53*.bundle.js
何時使用 .claudeignore:
✅ 應該忽略:
- 第三方套件(node_modules)
- 編譯產物(dist, build)
- 大型資料檔案
- 二進位檔案
- 機密資訊(.env)
❌ 不應該忽略:
- 原始碼檔案
- 設定檔(tsconfig.json, package.json)
- 測試檔案
- 文檔檔案
9. 保持程式碼庫的文檔更新
必要的文檔類型:
1專案根目錄/
2├── README.md # 專案概述、快速開始
3├── CONTRIBUTING.md # 貢獻指南
4├── ARCHITECTURE.md # 架構說明
5└── docs/
6 ├── API.md # API 文檔
7 ├── DEPLOYMENT.md # 部署指南
8 └── DEVELOPMENT.md # 開發指南
README.md 範本:
1# 專案名稱
2
3簡短的專案描述(1-2 句話)
4
5## 🚀 快速開始
6
7\`\`\`bash
8# 安裝依賴
9npm install
10
11# 啟動開發伺服器
12npm run dev
13
14# 執行測試
15npm test
16\`\`\`
17
18## 📁 專案結構
19
20\`\`\`
21src/
22├── components/ # React 元件
23├── services/ # API 服務
24└── utils/ # 工具函式
25\`\`\`
26
27## 🔧 技術棧
28
29- **前端**: React 18 + TypeScript
30- **狀態管理**: Zustand
31- **樣式**: Tailwind CSS
32- **API**: REST + Axios
33
34## 📝 主要功能
35
361. 使用者認證(JWT)
372. 資料視覺化(Chart.js)
383. 即時通知(WebSocket)
39
40## 🤝 貢獻指南
41
42請參閱 [CONTRIBUTING.md](CONTRIBUTING.md)
43
44## 📄 授權
45
46MIT License
10. 定期進行程式碼審查(Code Review)
使用 Claude Code 進行 Code Review:
1# 使用 /review-pr 技能
2/review-pr 123
3
4# 或明確指示審查重點
5"審查 Pull Request #123,重點檢查:
61. 安全性漏洞(SQL injection, XSS)
72. 效能問題(N+1 queries, 記憶體洩漏)
83. 程式碼品質(複雜度、可讀性)
94. 測試覆蓋率
105. 文檔完整性"
自動化 Code Review 檢查清單:
1// 建立 .github/PULL_REQUEST_TEMPLATE.md
2
3## 變更描述
4<!-- 描述這次 PR 的變更內容 -->
5
6## 變更類型
7- [ ] Bug 修復
8- [ ] 新功能
9- [ ] 重構
10- [ ] 文檔更新
11- [ ] 效能優化
12
13## 檢查清單
14- [ ] 程式碼遵循專案風格指南
15- [ ] 已新增/更新相關測試
16- [ ] 所有測試通過
17- [ ] 已更新文檔
18- [ ] 無安全性疑慮
19- [ ] 已執行 ESLint/Prettier
20- [ ] PR 標題清楚描述變更
⚡ 類別三:效率優化技巧
11. 善用 Claude Code 的內建工具
常用工具與使用時機:
1// 1. Read Tool - 讀取檔案
2"讀取 src/components/UserProfile.tsx 檢查錯誤"
3
4// 2. Edit Tool - 精確編輯
5"在 src/utils/format.ts:23 將 formatDate 改為使用
6date-fns 而非 moment.js"
7
8// 3. Write Tool - 建立新檔案
9"建立 src/hooks/useAuth.ts,實作自訂的認證 Hook"
10
11// 4. Bash Tool - 執行命令
12"執行 npm test 檢查測試結果"
13
14// 5. Grep Tool - 搜尋程式碼
15"在整個專案中搜尋所有使用 'localStorage' 的地方"
16
17// 6. Glob Tool - 尋找檔案
18"找出所有 .test.ts 檔案"
工具使用最佳實踐:
✅ 有效使用:
"使用 Grep 找出所有包含 'TODO' 的檔案,然後逐一處理"
"用 Glob 列出所有 React 元件,檢查哪些缺少 PropTypes"
❌ 無效使用:
"搜尋整個專案" (太模糊)
"看看有什麼檔案" (無明確目標)
12. 批次處理相似任務
範例:批次重構
1// ❌ 逐一處理
2"重構 UserCard.tsx"
3"重構 ProductCard.tsx"
4"重構 OrderCard.tsx"
5...
6
7// ✅ 批次處理
8"批次重構所有 Card 元件(UserCard, ProductCard,
9OrderCard, CommentCard),統一:
101. 將 class components 改為 functional components
112. 使用 TypeScript interface 定義 props
123. 套用統一的樣式結構
134. 加入 data-testid 屬性
14
15請使用 Glob 找出所有 *Card.tsx 檔案並逐一處理"
批次任務規劃:
1【批次任務範本】
2
3任務:將所有 API 呼叫從 fetch 遷移到 axios
4
5Step 1: 掃描識別
6- 使用 Grep 找出所有包含 'fetch(' 的檔案
7- 列出受影響的檔案清單
8
9Step 2: 建立遷移計畫
10- 為每個檔案規劃變更內容
11- 識別共通模式
12
13Step 3: 批次執行
14- 按優先順序逐一遷移
15- 每個檔案遷移後執行測試
16
17Step 4: 驗證
18- 執行完整測試套件
19- 手動測試關鍵功能
13. 利用 Skills 簡化重複工作
建立自訂 Skill 範例:
1// 範例:建立元件的 Skill
2
3// ~/.config/claude-code/skills/create-component.ts
4export const createComponentSkill: Skill = {
5 name: 'create-react-component',
6 description: '建立標準的 React 元件(含測試和故事書)',
7
8 arguments: {
9 componentName: {
10 type: 'string',
11 required: true,
12 description: '元件名稱(PascalCase)'
13 },
14 hasState: {
15 type: 'boolean',
16 default: false,
17 description: '是否需要狀態管理'
18 }
19 },
20
21 async execute(args, context) {
22 const { componentName, hasState } = args;
23
24 // 1. 建立元件檔案
25 await context.write(
26 `src/components/${componentName}/${componentName}.tsx`,
27 generateComponentCode(componentName, hasState)
28 );
29
30 // 2. 建立測試檔案
31 await context.write(
32 `src/components/${componentName}/${componentName}.test.tsx`,
33 generateTestCode(componentName)
34 );
35
36 // 3. 建立 Storybook 故事
37 await context.write(
38 `src/components/${componentName}/${componentName}.stories.tsx`,
39 generateStoryCode(componentName)
40 );
41
42 // 4. 建立 index.ts
43 await context.write(
44 `src/components/${componentName}/index.ts`,
45 `export { ${componentName} } from './${componentName}';\n`
46 );
47
48 return {
49 success: true,
50 message: `✅ 元件 ${componentName} 建立完成!`
51 };
52 }
53};
使用 Skill:
1# 使用自訂 Skill
2/create-react-component UserAvatar --hasState=true
3
4# 結果:自動產生
5# - UserAvatar.tsx
6# - UserAvatar.test.tsx
7# - UserAvatar.stories.tsx
8# - index.ts
14. 設定合適的編輯器整合
VS Code 設定範例:
1// .vscode/settings.json
2{
3 // Claude Code 相關設定
4 "claude.autoSave": true,
5 "claude.contextFiles": [
6 "package.json",
7 "tsconfig.json",
8 ".env.example"
9 ],
10
11 // 編輯器設定
12 "editor.formatOnSave": true,
13 "editor.codeActionsOnSave": {
14 "source.fixAll.eslint": true
15 },
16
17 // TypeScript 設定
18 "typescript.tsdk": "node_modules/typescript/lib",
19 "typescript.enablePromptUseWorkspaceTsdk": true,
20
21 // 檔案排除(與 .claueignore 同步)
22 "files.exclude": {
23 "**/node_modules": true,
24 "**/dist": true,
25 "**/.next": true
26 }
27}
推薦的 VS Code 擴充套件:
1{
2 "recommendations": [
3 "anthropics.claude-code", // Claude Code 官方擴充
4 "dbaeumer.vscode-eslint", // ESLint
5 "esbenp.prettier-vscode", // Prettier
6 "ms-vscode.vscode-typescript-next", // TypeScript
7 "bradlc.vscode-tailwindcss", // Tailwind CSS
8 "formulahendry.auto-rename-tag", // HTML 標籤重命名
9 "streetsidesoftware.code-spell-checker" // 拼字檢查
10 ]
11}
15. 使用 Todo List 追蹤進度
何時使用 TodoWrite 工具:
1// ✅ 應該使用 Todo List 的情況:
2
3// 1. 複雜的多步驟任務
4"實作使用者認證系統(包含註冊、登入、JWT、密碼重設)"
5
6// 2. 需要追蹤進度的功能開發
7"建立電商購物車功能"
8
9// 3. 有多個子任務的重構工作
10"重構整個資料層以使用 TypeScript"
11
12// ❌ 不需要 Todo List 的情況:
13
14// 1. 簡單的單一修改
15"修正 Button 元件的樣式"
16
17// 2. 快速的 bug 修復
18"修正拼字錯誤"
19
20// 3. 簡單的查詢或問答
21"解釋這個函式的作用"
Todo List 使用範例:
1// Claude 會自動建立並管理 Todo List
2
3任務:實作使用者認證系統
4
5✓ 完成:設計 User schema(Prisma)
6✓ 完成:實作註冊 API endpoint
7🔄 進行中:實作登入功能
8⏳ 待處理:建立 JWT middleware
9⏳ 待處理:保護需要認證的路由
10⏳ 待處理:前端整合(登入表單)
11⏳ 待處理:撰寫整合測試
12
13【優點】
14• 清楚追蹤進度
15• 隨時了解剩餘工作
16• 容易從中斷處繼續
17• 可以隨時調整優先順序
🎯 類別四:品質保證
16. 要求測試覆蓋
測試策略:
1// 明確要求測試類型
2
3"實作 calculateShippingCost() 函式,並包含以下測試:
4
5【單元測試】(calculateShippingCost.test.ts)
6- 基本運費計算
7- 重量超過限制的情況
8- 偏遠地區加價
9- 無效輸入的錯誤處理
10- 邊界值測試(0, 負數, 極大值)
11
12【整合測試】(shippingService.integration.test.ts)
13- 與實際 API 的整合
14- 資料庫查詢
15- 快取機制
16
17【期望覆蓋率】
18- 語句覆蓋率 > 90%
19- 分支覆蓋率 > 85%
20- 函式覆蓋率 = 100%"
測試驅動開發(TDD)流程:
1. 先寫測試
"為 UserService.createUser() 撰寫測試,包含:
- 成功建立使用者
- Email 已存在的錯誤
- 無效 Email 格式
- 密碼強度不足"
2. 實作功能
"根據上述測試實作 UserService.createUser()"
3. 重構優化
"重構 createUser() 以提升可讀性,保持測試通過"
17. 進行安全性檢查
安全檢查清單:
1"審查 src/api/userController.ts 的安全性,檢查:
2
3【注入攻擊】
4✓ SQL Injection 防護
5✓ NoSQL Injection 防護
6✓ Command Injection 防護
7
8【XSS 防護】
9✓ 輸入驗證
10✓ 輸出編碼
11✓ Content Security Policy
12
13【認證與授權】
14✓ 密碼雜湊(bcrypt, 不是 MD5)
15✓ JWT token 驗證
16✓ 角色權限檢查
17✓ Rate limiting
18
19【敏感資訊】
20✓ 無密碼或 API key 寫在程式碼中
21✓ 錯誤訊息不洩漏內部資訊
22✓ 日誌不記錄敏感資料
23
24【依賴套件】
25✓ 無已知漏洞的套件
26✓ 套件版本為最新穩定版"
常見安全漏洞範例:
1// ❌ 不安全的程式碼
2app.get('/user/:id', (req, res) => {
3 const query = `SELECT * FROM users WHERE id = ${req.params.id}`;
4 db.query(query); // SQL Injection 風險
5});
6
7// ✅ 安全的程式碼
8app.get('/user/:id', async (req, res) => {
9 const userId = parseInt(req.params.id);
10 if (isNaN(userId)) {
11 return res.status(400).json({ error: 'Invalid user ID' });
12 }
13
14 const user = await db.query(
15 'SELECT * FROM users WHERE id = ?',
16 [userId]
17 );
18});
19
20// 請 Claude Code 檢查
21"審查上述程式碼的安全性,並提供改善建議"
18. 要求性能優化說明
效能分析要求:
1"分析 src/components/DataTable.tsx 的效能問題:
2
3【目前狀況】
4- 渲染 1000 筆資料需要 3 秒
5- 捲動時有明顯卡頓
6- 每次篩選都重新渲染整個表格
7
8【請執行】
91. 使用 React DevTools Profiler 識別瓶頸
102. 列出效能問題清單
113. 提供優化方案(含預期改善幅度)
124. 實作最有效的 3 個優化
135. 測試優化後的效能
14
15【優化技術參考】
16- React.memo()
17- useMemo() / useCallback()
18- 虛擬捲動(react-window)
19- 分頁或無限捲動
20- Web Workers"
效能優化對比:
1// ❌ 效能不佳
2function DataTable({ data }) {
3 return (
4 <table>
5 {data.map(item => (
6 <Row
7 key={item.id}
8 data={item}
9 onEdit={() => handleEdit(item)} // 每次都建立新函式
10 />
11 ))}
12 </table>
13 );
14}
15
16// ✅ 效能優化
17import { memo, useMemo, useCallback } from 'react';
18import { FixedSizeList } from 'react-window';
19
20const Row = memo(({ data, onEdit }) => {
21 return <tr>{/* ... */}</tr>;
22});
23
24function DataTable({ data }) {
25 const handleEdit = useCallback((item) => {
26 // 處理編輯
27 }, []);
28
29 const sortedData = useMemo(() => {
30 return data.sort((a, b) => a.id - b.id);
31 }, [data]);
32
33 return (
34 <FixedSizeList
35 height={600}
36 itemCount={sortedData.length}
37 itemSize={50}
38 >
39 {({ index, style }) => (
40 <Row
41 style={style}
42 data={sortedData[index]}
43 onEdit={handleEdit}
44 />
45 )}
46 </FixedSizeList>
47 );
48}
19. 驗證邊界情況和錯誤處理
完整的錯誤處理範例:
1"實作 processPayment() 函式,包含完整的錯誤處理:
2
3【輸入驗證】
4- 金額必須 > 0
5- 信用卡號碼格式檢查
6- CVV 長度檢查
7- 過期日期驗證
8
9【錯誤情境處理】
10- 網路逾時(30 秒)
11- API 回傳 4xx 錯誤
12- API 回傳 5xx 錯誤
13- 餘額不足
14- 信用卡過期
15- 信用卡被拒
16
17【重試策略】
18- 網路錯誤:重試 3 次,指數退避
19- 5xx 錯誤:重試 2 次
20- 4xx 錯誤:不重試,直接返回錯誤
21
22【日誌記錄】
23- 成功交易:記錄金額、時間
24- 失敗交易:記錄錯誤原因、重試次數
25- 敏感資訊:遮罩信用卡號(只顯示後 4 碼)"
邊界測試範例:
1// 測試邊界情況
2describe('calculateDiscount', () => {
3 it('handles zero amount', () => {
4 expect(calculateDiscount(0, 0.1)).toBe(0);
5 });
6
7 it('handles negative amount', () => {
8 expect(() => calculateDiscount(-100, 0.1))
9 .toThrow('Amount must be positive');
10 });
11
12 it('handles 100% discount', () => {
13 expect(calculateDiscount(100, 1)).toBe(0);
14 });
15
16 it('handles discount > 100%', () => {
17 expect(() => calculateDiscount(100, 1.5))
18 .toThrow('Discount cannot exceed 100%');
19 });
20
21 it('handles very large amounts', () => {
22 expect(calculateDiscount(Number.MAX_SAFE_INTEGER, 0.1))
23 .toBeLessThan(Number.MAX_SAFE_INTEGER);
24 });
25
26 it('handles floating point precision', () => {
27 expect(calculateDiscount(0.1 + 0.2, 0.1))
28 .toBeCloseTo(0.27, 2);
29 });
30});
20. 要求程式碼文檔
文檔要求範例:
1"為 src/services/emailService.ts 新增完整的 JSDoc 文檔:
2
3【要求】
4- 每個 public 函式都要有 JSDoc
5- 描述函式用途、參數、返回值
6- 包含使用範例
7- 說明可能拋出的錯誤
8- 標註 @since 版本資訊"
良好的文檔範例:
1/**
2 * 發送歡迎郵件給新註冊的使用者
3 *
4 * 此函式會根據使用者的語言偏好發送對應語言的歡迎郵件。
5 * 郵件包含帳號啟用連結,有效期限為 24 小時。
6 *
7 * @param {string} email - 使用者的電子郵件地址
8 * @param {string} username - 使用者名稱
9 * @param {string} [locale='en'] - 語言代碼(en, zh-TW, ja 等)
10 * @returns {Promise<EmailResult>} 郵件發送結果
11 *
12 * @throws {InvalidEmailError} 當 email 格式無效時
13 * @throws {EmailServiceError} 當郵件服務發生錯誤時
14 *
15 * @example
16 * // 發送英文歡迎郵件
17 * await sendWelcomeEmail('user@example.com', 'John');
18 *
19 * @example
20 * // 發送繁體中文歡迎郵件
21 * await sendWelcomeEmail('user@example.com', '王小明', 'zh-TW');
22 *
23 * @since 1.0.0
24 */
25export async function sendWelcomeEmail(
26 email: string,
27 username: string,
28 locale: string = 'en'
29): Promise<EmailResult> {
30 // 實作...
31}
32
33/**
34 * 郵件發送結果
35 *
36 * @typedef {Object} EmailResult
37 * @property {boolean} success - 是否發送成功
38 * @property {string} messageId - 郵件訊息 ID
39 * @property {number} timestamp - 發送時間戳記
40 */
🤝 類別五:團隊協作
團隊使用 Claude Code 的最佳實踐
建立團隊規範:
1# 團隊 Claude Code 使用規範
2
3## 1. 提示詞風格指南
4
5### 命名規則
6- 使用清晰、描述性的變數名稱
7- 遵循專案的命名慣例(camelCase, PascalCase)
8- 避免縮寫(除非是廣為人知的)
9
10### 程式碼風格
11- 遵循 ESLint 規則
12- 使用 Prettier 格式化
13- 優先使用 TypeScript
14
15### 文檔要求
16- 所有 public API 必須有 JSDoc
17- 複雜邏輯需要註解說明
18- README 保持更新
19
20## 2. Git 工作流程
21
22### Commit 訊息格式
23feat: 新增使用者認證功能
24fix: 修復登入按鈕樣式
25refactor: 重構資料處理邏輯
26docs: 更新 API 文檔
27test: 新增單元測試
28
29### Branch 命名
30feature/user-authentication
31bugfix/login-button-style
32refactor/data-processing
33docs/api-documentation
34
35## 3. Code Review 標準
36
37- 安全性檢查
38- 效能考量
39- 測試覆蓋率
40- 文檔完整性
41- 程式碼可讀性
42
43## 4. 使用 Claude Code 的時機
44
45✅ 適合使用:
46- 實作新功能
47- 重構舊程式碼
48- 撰寫測試
49- 文檔生成
50- Bug 診斷
51
52⚠️ 謹慎使用:
53- 關鍵安全性程式碼(需人工審查)
54- 複雜的架構決策(需團隊討論)
55- 生產環境熱修復(需多重驗證)
📋 最佳實踐總結檢查清單
使用前檢查:
1☐ 提供清晰、具體的指令
2☐ 包含充足的背景資訊
3☐ 將複雜任務分解為小步驟
4☐ 指明參考資料或範例
5☐ 標示不可修改的部分
專案設定檢查:
1☐ 專案結構清晰且合邏輯
2☐ 檔案命名具描述性
3☐ .claudeignore 正確設定
4☐ README 文檔完整
5☐ 編輯器整合已設定
程式碼品質檢查:
1☐ 包含適當的測試
2☐ 進行安全性審查
3☐ 效能已優化
4☐ 錯誤處理完整
5☐ 文檔齊全
🎯 實戰範例:完整開發流程
情境:實作一個使用者註冊功能
1// Step 1: 明確需求
2"實作使用者註冊功能,包含以下需求:
3
4【功能需求】
5- Email 和密碼註冊
6- Email 格式驗證
7- 密碼強度檢查(最少 8 字元,含大小寫和數字)
8- Email 重複檢查
9- 註冊成功後發送驗證郵件
10
11【技術棧】
12- Backend: Node.js + Express + TypeScript
13- Database: PostgreSQL + Prisma
14- Email: SendGrid
15
16【檔案結構】
17src/
18├── api/
19│ └── auth/
20│ └── register.ts
21├── services/
22│ ├── userService.ts
23│ └── emailService.ts
24├── validators/
25│ └── authValidator.ts
26└── types/
27 └── user.ts
28
29【要求】
301. 包含完整的錯誤處理
312. 撰寫單元測試(Jest)
323. 加入 JSDoc 文檔
334. 遵循 RESTful API 慣例"
34
35// Step 2: 使用 Todo List 追蹤進度
36// Claude Code 會自動建立:
37// ✓ 建立 User type 定義
38// ✓ 實作 auth validator
39// 🔄 實作 userService.createUser()
40// ⏳ 實作 emailService.sendVerificationEmail()
41// ⏳ 實作 API endpoint
42// ⏳ 撰寫測試
43
44// Step 3: 逐步實作並驗證
45// 每個步驟完成後執行測試
46
47// Step 4: Code Review
48"/review-pr --focus=security,performance,tests"
49
50// Step 5: 文檔更新
51"更新 API.md,新增註冊 endpoint 的文檔"
52
53// Step 6: Commit
54"/commit"
🚀 結論:持續改進
使用 Claude Code 是一個持續學習和改進的過程:
進階技巧學習路徑:
初級(1-2 週)
├─ 基本指令使用
├─ 檔案讀寫操作
└─ 簡單的程式碼修改
中級(1 個月)
├─ 複雜任務分解
├─ 多檔案協調
├─ 測試與文檔
└─ Sub-agent 使用
高級(2-3 個月)
├─ 自訂 Skills
├─ MCP 整合
├─ 工作流程優化
└─ 團隊協作規範
專家級(持續)
├─ 架構設計諮詢
├─ 效能深度優化
├─ 安全審計
└─ 最佳實踐貢獻
關鍵心態:
- Claude Code 是助手,不是替代品 - 仍需人工判斷和決策
- 明確溝通比速度重要 - 花時間寫清楚需求可節省後續時間
- 持續驗證和測試 - 不要盲目信任 AI 生成的程式碼
- 文檔和註解很重要 - 幫助 Claude 理解專案背景
- 從錯誤中學習 - 記錄有效和無效的提示方式
下一步行動:
1☐ 檢視並更新專案的 README.md
2☐ 建立 .claudeignore 檔案
3☐ 設定編輯器整合
4☐ 與團隊分享使用規範
5☐ 建立常用 Skills
6☐ 定期進行 Code Review
7☐ 持續學習新功能和最佳實踐
延伸閱讀
標籤: #claude-code #最佳實踐 #AI開發 #提示工程 #開發效率 #程式設計
