[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7324YGFD2VR5DDDZRRDGMF2":3,"skill-same:01M7324YGFD2VR5DDDZRRDGMF2":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M7324YGFD2VR5DDDZRRDGMF2","coding-standards",null,"Universal coding standards, best practices, and patterns for TypeScript, JavaScript, React, and Node.js development.","SriramGandhiS\u002FSkills","SriramGandhiS","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F211849986?v=4","01M72WQCW12BYX71C6WN584TTA","Sriram S","01M72WQCWTJ2RD0ET1X31AF1RC",1,"MIT","https:\u002F\u002Fgithub.com\u002FSriramGandhiS\u002FSkills\u002Fblob\u002Fmaster\u002Fweb-assets\u002Fdocs\u002Fzh-TW\u002Fskills\u002Fcoding-standards\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: coding-standards\ndescription: Universal coding standards, best practices, and patterns for TypeScript, JavaScript, React, and Node.js development.\n---\n\n# 程式碼標準與最佳實務\n\n適用於所有專案的通用程式碼標準。\n\n## 程式碼品質原則\n\n### 1. 可讀性優先\n- 程式碼被閱讀的次數遠多於被撰寫的次數\n- 使用清晰的變數和函式名稱\n- 優先使用自文件化的程式碼而非註解\n- 保持一致的格式化\n\n### 2. KISS（保持簡單）\n- 使用最簡單的解決方案\n- 避免過度工程\n- 不做過早優化\n- 易於理解 > 聰明的程式碼\n\n### 3. DRY（不重複自己）\n- 將共用邏輯提取為函式\n- 建立可重用的元件\n- 在模組間共享工具函式\n- 避免複製貼上程式設計\n\n### 4. YAGNI（你不會需要它）\n- 在需要之前不要建置功能\n- 避免推測性的通用化\n- 只在需要時增加複雜度\n- 從簡單開始，需要時再重構\n\n## TypeScript\u002FJavaScript 標準\n\n### 變數命名\n\n```typescript\n\u002F\u002F PASS: 良好：描述性名稱\nconst marketSearchQuery = 'election'\nconst isUserAuthenticated = true\nconst totalRevenue = 1000\n\n\u002F\u002F FAIL: 不良：不清楚的名稱\nconst q = 'election'\nconst flag = true\nconst x = 1000\n```\n\n### 函式命名\n\n```typescript\n\u002F\u002F PASS: 良好：動詞-名詞模式\nasync function fetchMarketData(marketId: string) { }\nfunction calculateSimilarity(a: number[], b: number[]) { }\nfunction isValidEmail(email: string): boolean { }\n\n\u002F\u002F FAIL: 不良：不清楚或只有名詞\nasync function market(id: string) { }\nfunction similarity(a, b) { }\nfunction email(e) { }\n```\n\n### 不可變性模式（關鍵）\n\n```typescript\n\u002F\u002F PASS: 總是使用展開運算符\nconst updatedUser = {\n  ...user,\n  name: 'New Name'\n}\n\nconst updatedArray = [...items, newItem]\n\n\u002F\u002F FAIL: 永遠不要直接修改\nuser.name = 'New Name'  \u002F\u002F 不良\nitems.push(newItem)     \u002F\u002F 不良\n```\n\n### 錯誤處理\n\n```typescript\n\u002F\u002F PASS: 良好：完整的錯誤處理\nasync function fetchData(url: string) {\n  try {\n    const response = await fetch(url)\n\n    if (!response.ok) {\n      throw new Error(`HTTP ${response.status}: ${response.statusText}`)\n    }\n\n    return await response.json()\n  } catch (error) {\n    console.error('Fetch failed:', error)\n    throw new Error('Failed to fetch data')\n  }\n}\n\n\u002F\u002F FAIL: 不良：無錯誤處理\nasync function fetchData(url) {\n  const response = await fetch(url)\n  return response.json()\n}\n```\n\n### Async\u002FAwait 最佳實務\n\n```typescript\n\u002F\u002F PASS: 良好：可能時並行執行\nconst [users, markets, stats] = await Promise.all([\n  fetchUsers(),\n  fetchMarkets(),\n  fetchStats()\n])\n\n\u002F\u002F FAIL: 不良：不必要的順序執行\nconst users = await fetchUsers()\nconst markets = await fetchMarkets()\nconst stats = await fetchStats()\n```\n\n### 型別安全\n\n```typescript\n\u002F\u002F PASS: 良好：正確的型別\ninterface Market {\n  id: string\n  name: string\n  status: 'active' | 'resolved' | 'closed'\n  created_at: Date\n}\n\nfunction getMarket(id: string): Promise\u003CMarket> {\n  \u002F\u002F 實作\n}\n\n\u002F\u002F FAIL: 不良：使用 'any'\nfunction getMarket(id: any): Promise\u003Cany> {\n  \u002F\u002F 實作\n}\n```\n\n## React 最佳實務\n\n### 元件結構\n\n```typescript\n\u002F\u002F PASS: 良好：具有型別的函式元件\ninterface ButtonProps {\n  children: React.ReactNode\n  onClick: () => void\n  disabled?: boolean\n  variant?: 'primary' | 'secondary'\n}\n\nexport function Button({\n  children,\n  onClick,\n  disabled = false,\n  variant = 'primary'\n}: ButtonProps) {\n  return (\n    \u003Cbutton\n      onClick={onClick}\n      disabled={disabled}\n      className={`btn btn-${variant}`}\n    >\n      {children}\n    \u003C\u002Fbutton>\n  )\n}\n\n\u002F\u002F FAIL: 不良：無型別、結構不清楚\nexport function Button(props) {\n  return \u003Cbutton onClick={props.onClick}>{props.children}\u003C\u002Fbutton>\n}\n```\n\n### 自訂 Hooks\n\n```typescript\n\u002F\u002F PASS: 良好：可重用的自訂 hook\nexport function useDebounce\u003CT>(value: T, delay: number): T {\n  const [debouncedValue, setDebouncedValue] = useState\u003CT>(value)\n\n  useEffect(() => {\n    const handler = setTimeout(() => {\n      setDebouncedValue(value)\n    }, delay)\n\n    return () => clearTimeout(handler)\n  }, [value, delay])\n\n  return debouncedValue\n}\n\n\u002F\u002F 使用方式\nconst debouncedQuery = useDebounce(searchQuery, 500)\n```\n\n### 狀態管理\n\n```typescript\n\u002F\u002F PASS: 良好：正確的狀態更新\nconst [count, setCount] = useState(0)\n\n\u002F\u002F 基於先前狀態的函式更新\nsetCount(prev => prev + 1)\n\n\u002F\u002F FAIL: 不良：直接引用狀態\nsetCount(count + 1)  \u002F\u002F 在非同步情境中可能過時\n```\n\n### 條件渲染\n\n```typescript\n\u002F\u002F PASS: 良好：清晰的條件渲染\n{isLoading && \u003CSpinner \u002F>}\n{error && \u003CErrorMessage error={error} \u002F>}\n{data && \u003CDataDisplay data={data} \u002F>}\n\n\u002F\u002F FAIL: 不良：三元地獄\n{isLoading ? \u003CSpinner \u002F> : error ? \u003CErrorMessage error={error} \u002F> : data ? \u003CDataDisplay data={data} \u002F> : null}\n```\n\n## API 設計標準\n\n### REST API 慣例\n\n```\nGET    \u002Fapi\u002Fmarkets              # 列出所有市場\nGET    \u002Fapi\u002Fmarkets\u002F:id          # 取得特定市場\nPOST   \u002Fapi\u002Fmarkets              # 建立新市場\nPUT    \u002Fapi\u002Fmarkets\u002F:id          # 更新市場（完整）\nPATCH  \u002Fapi\u002Fmarkets\u002F:id          # 更新市場（部分）\nDELETE \u002Fapi\u002Fmarkets\u002F:id          # 刪除市場\n\n## 過濾用查詢參數\nGET \u002Fapi\u002Fmarkets?status=active&limit=10&offset=0\n```\n\n### 回應格式\n\n```typescript\n\u002F\u002F PASS: 良好：一致的回應結構\ninterface ApiResponse\u003CT> {\n  success: boolean\n  data?: T\n  error?: string\n  meta?: {\n    total: number\n    page: number\n    limit: number\n  }\n}\n\n\u002F\u002F 成功回應\nreturn NextResponse.json({\n  success: true,\n  data: markets,\n  meta: { total: 100, page: 1, limit: 10 }\n})\n\n\u002F\u002F 錯誤回應\nreturn NextResponse.json({\n  success: false,\n  error: 'Invalid request'\n}, { status: 400 })\n```\n\n### 輸入驗證\n\n```typescript\nimport { z } from 'zod'\n\n\u002F\u002F PASS: 良好：Schema 驗證\nconst CreateMarketSchema = z.object({\n  name: z.string().min(1).max(200),\n  description: z.string().min(1).max(2000),\n  endDate: z.string().datetime(),\n  categories: z.array(z.string()).min(1)\n})\n\nexport async function POST(request: Request) {\n  const body = await request.json()\n\n  try {\n    const validated = CreateMarketSchema.parse(body)\n    \u002F\u002F 使用驗證過的資料繼續處理\n  } catch (error) {\n    if (error instanceof z.ZodError) {\n      return NextResponse.json({\n        success: false,\n        error: 'Validation failed',\n        details: error.errors\n      }, { status: 400 })\n    }\n  }\n}\n```\n\n## 檔案組織\n\n### 專案結構\n\n```\nsrc\u002F\n├── app\u002F                    # Next.js App Router\n│   ├── api\u002F               # API 路由\n│   ├── markets\u002F           # 市場頁面\n│   └── (auth)\u002F           # 認證頁面（路由群組）\n├── components\u002F            # React 元件\n│   ├── ui\u002F               # 通用 UI 元件\n│   ├── forms\u002F            # 表單元件\n│   └── layouts\u002F          # 版面配置元件\n├── hooks\u002F                # 自訂 React hooks\n├── lib\u002F                  # 工具和設定\n│   ├── api\u002F             # API 客戶端\n│   ├── utils\u002F           # 輔助函式\n│   └── constants\u002F       # 常數\n├── types\u002F                # TypeScript 型別\n└── styles\u002F              # 全域樣式\n```\n\n### 檔案命名\n\n```\ncomponents\u002FButton.tsx          # 元件用 PascalCase\nhooks\u002FuseAuth.ts              # hooks 用 camelCase 加 'use' 前綴\nlib\u002FformatDate.ts             # 工具用 camelCase\ntypes\u002Fmarket.types.ts         # 型別用 camelCase 加 .types 後綴\n```\n\n## 註解與文件\n\n### 何時註解\n\n```typescript\n\u002F\u002F PASS: 良好：解釋「為什麼」而非「什麼」\n\u002F\u002F 使用指數退避以避免在服務中斷時壓垮 API\nconst delay = Math.min(1000 * Math.pow(2, retryCount), 30000)\n\n\u002F\u002F 為了處理大陣列的效能，此處刻意使用突變\nitems.push(newItem)\n\n\u002F\u002F FAIL: 不良：陳述顯而易見的事實\n\u002F\u002F 將計數器加 1\ncount++\n\n\u002F\u002F 將名稱設為使用者的名稱\nname = user.name\n```\n\n### 公開 API 的 JSDoc\n\n```typescript\n\u002F**\n * 使用語意相似度搜尋市場。\n *\n * @param query - 自然語言搜尋查詢\n * @param limit - 最大結果數量（預設：10）\n * @returns 按相似度分數排序的市場陣列\n * @throws {Error} 如果 OpenAI API 失敗或 Redis 不可用\n *\n * @example\n * ```typescript\n * const results = await searchMarkets('election', 5)\n * console.log(results[0].name) \u002F\u002F \"Trump vs Biden\"\n * ```\n *\u002F\nexport async function searchMarkets(\n  query: string,\n  limit: number = 10\n): Promise\u003CMarket[]> {\n  \u002F\u002F 實作\n}\n```\n\n## 效能最佳實務\n\n### 記憶化\n\n```typescript\nimport { useMemo, useCallback } from 'react'\n\n\u002F\u002F PASS: 良好：記憶化昂貴的計算\nconst sortedMarkets = useMemo(() => {\n  return markets.sort((a, b) => b.volume - a.volume)\n}, [markets])\n\n\u002F\u002F PASS: 良好：記憶化回呼函式\nconst handleSearch = useCallback((query: string) => {\n  setSearchQuery(query)\n}, [])\n```\n\n### 延遲載入\n\n```typescript\nimport { lazy, Suspense } from 'react'\n\n\u002F\u002F PASS: 良好：延遲載入重型元件\nconst HeavyChart = lazy(() => import('.\u002FHeavyChart'))\n\nexport function Dashboard() {\n  return (\n    \u003CSuspense fallback={\u003CSpinner \u002F>}>\n      \u003CHeavyChart \u002F>\n    \u003C\u002FSuspense>\n  )\n}\n```\n\n### 資料庫查詢\n\n```typescript\n\u002F\u002F PASS: 良好：只選擇需要的欄位\nconst { data } = await supabase\n  .from('markets')\n  .select('id, name, status')\n  .limit(10)\n\n\u002F\u002F FAIL: 不良：選擇所有欄位\nconst { data } = await supabase\n  .from('markets')\n  .select('*')\n```\n\n## 測試標準\n\n### 測試結構（AAA 模式）\n\n```typescript\ntest('calculates similarity correctly', () => {\n  \u002F\u002F Arrange（準備）\n  const vector1 = [1, 0, 0]\n  const vector2 = [0, 1, 0]\n\n  \u002F\u002F Act（執行）\n  const similarity = calculateCosineSimilarity(vector1, vector2)\n\n  \u002F\u002F Assert（斷言）\n  expect(similarity).toBe(0)\n})\n```\n\n### 測試命名\n\n```typescript\n\u002F\u002F PASS: 良好：描述性測試名稱\ntest('returns empty array when no markets match query', () => { })\ntest('throws error when OpenAI API key is missing', () => { })\ntest('falls back to substring search when Redis unavailable', () => { })\n\n\u002F\u002F FAIL: 不良：模糊的測試名稱\ntest('works', () => { })\ntest('test search', () => { })\n```\n\n## 程式碼異味偵測\n\n注意這些反模式：\n\n### 1. 過長函式\n```typescript\n\u002F\u002F FAIL: 不良：函式超過 50 行\nfunction processMarketData() {\n  \u002F\u002F 100 行程式碼\n}\n\n\u002F\u002F PASS: 良好：拆分為較小的函式\nfunction processMarketData() {\n  const validated = validateData()\n  const transformed = transformData(validated)\n  return saveData(transformed)\n}\n```\n\n### 2. 過深巢狀\n```typescript\n\u002F\u002F FAIL: 不良：5 層以上巢狀\nif (user) {\n  if (user.isAdmin) {\n    if (market) {\n      if (market.isActive) {\n        if (hasPermission) {\n          \u002F\u002F 做某事\n        }\n      }\n    }\n  }\n}\n\n\u002F\u002F PASS: 良好：提前返回\nif (!user) return\nif (!user.isAdmin) return\nif (!market) return\nif (!market.isActive) return\nif (!hasPermission) return\n\n\u002F\u002F 做某事\n```\n\n### 3. 魔術數字\n```typescript\n\u002F\u002F FAIL: 不良：無解釋的數字\nif (retryCount > 3) { }\nsetTimeout(callback, 500)\n\n\u002F\u002F PASS: 良好：命名常數\nconst MAX_RETRIES = 3\nconst DEBOUNCE_DELAY_MS = 500\n\nif (retryCount > MAX_RETRIES) { }\nsetTimeout(callback, DEBOUNCE_DELAY_MS)\n```\n\n**記住**：程式碼品質是不可協商的。清晰、可維護的程式碼能實現快速開發和自信的重構。\n","# 程式碼標準與最佳實務\n\n適用於所有專案的通用程式碼標準。\n\n## 程式碼品質原則\n\n### 1. 可讀性優先\n- 程式碼被閱讀的次數遠多於被撰寫的次數\n- 使用清晰的變數和函式名稱\n- 優先使用自文件化的程式碼而非註解\n- 保持一致的格式化\n\n### 2. KISS（保持簡單）\n- 使用最簡單的解決方案\n- 避免過度工程\n- 不做過早優化\n- 易於理解 > 聰明的程式碼\n\n### 3. DRY（不重複自己）\n- 將共用邏輯提取為函式\n- 建立可重用的元件\n- 在模組間共享工具函式\n- 避免複製貼上程式設計\n\n### 4. YAGNI（你不會需要它）\n- 在需要之前不要建置功能\n- 避免推測性的通用化\n- 只在需要時增加複雜度\n- 從簡單開始，需要時再重構\n\n## TypeScript\u002FJavaScript 標準\n\n### 變數命名\n\n```typescript\n\u002F\u002F PASS: 良好：描述性名稱\nconst marketSearchQuery = 'election'\nconst isUserAuthenticated = true\nconst totalRevenue = 1000\n\n\u002F\u002F FAIL: 不良：不清楚的名稱\nconst q = 'election'\nconst flag = true\nconst x = 1000\n```\n\n### 函式命名\n\n```typescript\n\u002F\u002F PASS: 良好：動詞-名詞模式\nasync function fetchMarketData(marketId: string) { }\nfunction calculateSimilarity(a: number[], b: number[]) { }\nfunction isValidEmail(email: string): boolean { }\n\n\u002F\u002F FAIL: 不良：不清楚或只有名詞\nasync function market(id: string) { }\nfunction similarity(a, b) { }\nfunction email(e) { }\n```\n\n### 不可變性模式（關鍵）\n\n```typescript\n\u002F\u002F PASS: 總是使用展開運算符\nconst updatedUser = {\n  ...user,\n  name: 'New Name'\n}\n\nconst updatedArray = [...items, newItem]\n\n\u002F\u002F FAIL: 永遠不要直接修改\nuser.name = 'New Name'  \u002F\u002F 不良\nitems.push(newItem)     \u002F\u002F 不良\n```\n\n### 錯誤處理\n\n```typescript\n\u002F\u002F PASS: 良好：完整的錯誤處理\nasync function fetchData(url: string) {\n  try {\n    const response = await fetch(url)\n\n    if (!response.ok) {\n      throw new Error(`HTTP ${response.status}: ${response.statusText}`)\n    }\n\n    return await response.json()\n  } catch (error) {\n    console.error('Fetch failed:', error)\n    throw new Error('Failed to fetch data')\n  }\n}\n\n\u002F\u002F FAIL: 不良：無錯誤處理\nasync function fetchData(url) {\n  const response = await fetch(url)\n  return response.json()\n}\n```\n\n### Async\u002FAwait 最佳實務\n\n```typescript\n\u002F\u002F PASS: 良好：可能時並行執行\nconst [users, markets, stats] = await Promise.all([\n  fetchUsers(),\n  fetchMarkets(),\n  fetchStats()\n])\n\n\u002F\u002F FAIL: 不良：不必要的順序執行\nconst users = await fetchUsers()\nconst markets = await fetchMarkets()\nconst stats = await fetchStats()\n```\n\n### 型別安全\n\n```typescript\n\u002F\u002F PASS: 良好：正確的型別\ninterface Market {\n  id: string\n  name: string\n  status: 'active' | 'resolved' | 'closed'\n  created_at: Date\n}\n\nfunction getMarket(id: string): Promise\u003CMarket> {\n  \u002F\u002F 實作\n}\n\n\u002F\u002F FAIL: 不良：使用 'any'\nfunction getMarket(id: any): Promise\u003Cany> {\n  \u002F\u002F 實作\n}\n```\n\n## React 最佳實務\n\n### 元件結構\n\n```typescript\n\u002F\u002F PASS: 良好：具有型別的函式元件\ninterface ButtonProps {\n  children: React.ReactNode\n  onClick: () => void\n  disabled?: boolean\n  variant?: 'primary' | 'secondary'\n}\n\nexport function Button({\n  children,\n  onClick,\n  disabled = false,\n  variant = 'primary'\n}: ButtonProps) {\n  return (\n    \u003Cbutton\n      onClick={onClick}\n      disabled={disabled}\n      className={`btn btn-${variant}`}\n    >\n      {children}\n    \u003C\u002Fbutton>\n  )\n}\n\n\u002F\u002F FAIL: 不良：無型別、結構不清楚\nexport function Button(props) {\n  return \u003Cbutton onClick={props.onClick}>{props.children}\u003C\u002Fbutton>\n}\n```\n\n### 自訂 Hooks\n\n```typescript\n\u002F\u002F PASS: 良好：可重用的自訂 hook\nexport function useDebounce\u003CT>(value: T, delay: number): T {\n  const [debouncedValue, setDebouncedValue] = useState\u003CT>(value)\n\n  useEffect(() => {\n    const handler = setTimeout(() => {\n      setDebouncedValue(value)\n    }, delay)\n\n    return () => clearTimeout(handler)\n  }, [value, delay])\n\n  return debouncedValue\n}\n\n\u002F\u002F 使用方式\nconst debouncedQuery = useDebounce(searchQuery, 500)\n```\n\n### 狀態管理\n\n```typescript\n\u002F\u002F PASS: 良好：正確的狀態更新\nconst [count, setCount] = useState(0)\n\n\u002F\u002F 基於先前狀態的函式更新\nsetCount(prev => prev + 1)\n\n\u002F\u002F FAIL: 不良：直接引用狀態\nsetCount(count + 1)  \u002F\u002F 在非同步情境中可能過時\n```\n\n### 條件渲染\n\n```typescript\n\u002F\u002F PASS: 良好：清晰的條件渲染\n{isLoading && \u003CSpinner \u002F>}\n{error && \u003CErrorMessage error={error} \u002F>}\n{data && \u003CDataDisplay data={data} \u002F>}\n\n\u002F\u002F FAIL: 不良：三元地獄\n{isLoading ? \u003CSpinner \u002F> : error ? \u003CErrorMessage error={error} \u002F> : data ? \u003CDataDisplay data={data} \u002F> : null}\n```\n\n## API 設計標準\n\n### REST API 慣例\n\n```\nGET    \u002Fapi\u002Fmarkets              # 列出所有市場\nGET    \u002Fapi\u002Fmarkets\u002F:id          # 取得特定市場\nPOST   \u002Fapi\u002Fmarkets              # 建立新市場\nPUT    \u002Fapi\u002Fmarkets\u002F:id          # 更新市場（完整）\nPATCH  \u002Fapi\u002Fmarkets\u002F:id          # 更新市場（部分）\nDELETE \u002Fapi\u002Fmarkets\u002F:id          # 刪除市場\n\n## 過濾用查詢參數\nGET \u002Fapi\u002Fmarkets?status=active&limit=10&offset=0\n```\n\n### 回應格式\n\n```typescript\n\u002F\u002F PASS: 良好：一致的回應結構\ninterface ApiResponse\u003CT> {\n  success: boolean\n  data?: T\n  error?: string\n  meta?: {\n    total: number\n    page: number\n    limit: number\n  }\n}\n\n\u002F\u002F 成功回應\nreturn NextResponse.json({\n  success: true,\n  data: markets,\n  meta: { total: 100, page: 1, limit: 10 }\n})\n\n\u002F\u002F 錯誤回應\nreturn NextResponse.json({\n  success: false,\n  error: 'Invalid request'\n}, { status: 400 })\n```\n\n### 輸入驗證\n\n```typescript\nimport { z } from 'zod'\n\n\u002F\u002F PASS: 良好：Schema 驗證\nconst CreateMarketSchema = z.object({\n  name: z.string().min(1).max(200),\n  description: z.string().min(1).max(2000),\n  endDate: z.string().datetime(),\n  categories: z.array(z.string()).min(1)\n})\n\nexport async function POST(request: Request) {\n  const body = await request.json()\n\n  try {\n    const validated = CreateMarketSchema.parse(body)\n    \u002F\u002F 使用驗證過的資料繼續處理\n  } catch (error) {\n    if (error instanceof z.ZodError) {\n      return NextResponse.json({\n        success: false,\n        error: 'Validation failed',\n        details: error.errors\n      }, { status: 400 })\n    }\n  }\n}\n```\n\n## 檔案組織\n\n### 專案結構\n\n```\nsrc\u002F\n├── app\u002F                    # Next.js App Router\n│   ├── api\u002F               # API 路由\n│   ├── markets\u002F           # 市場頁面\n│   └── (auth)\u002F           # 認證頁面（路由群組）\n├── components\u002F            # React 元件\n│   ├── ui\u002F               # 通用 UI 元件\n│   ├── forms\u002F            # 表單元件\n│   └── layouts\u002F          # 版面配置元件\n├── hooks\u002F                # 自訂 React hooks\n├── lib\u002F                  # 工具和設定\n│   ├── api\u002F             # API 客戶端\n│   ├── utils\u002F           # 輔助函式\n│   └── constants\u002F       # 常數\n├── types\u002F                # TypeScript 型別\n└── styles\u002F              # 全域樣式\n```\n\n### 檔案命名\n\n```\ncomponents\u002FButton.tsx          # 元件用 PascalCase\nhooks\u002FuseAuth.ts              # hooks 用 camelCase 加 'use' 前綴\nlib\u002FformatDate.ts             # 工具用 camelCase\ntypes\u002Fmarket.types.ts         # 型別用 camelCase 加 .types 後綴\n```\n\n## 註解與文件\n\n### 何時註解\n\n```typescript\n\u002F\u002F PASS: 良好：解釋「為什麼」而非「什麼」\n\u002F\u002F 使用指數退避以避免在服務中斷時壓垮 API\nconst delay = Math.min(1000 * Math.pow(2, retryCount), 30000)\n\n\u002F\u002F 為了處理大陣列的效能，此處刻意使用突變\nitems.push(newItem)\n\n\u002F\u002F FAIL: 不良：陳述顯而易見的事實\n\u002F\u002F 將計數器加 1\ncount++\n\n\u002F\u002F 將名稱設為使用者的名稱\nname = user.name\n```\n\n### 公開 API 的 JSDoc\n\n```typescript\n\u002F**\n * 使用語意相似度搜尋市場。\n *\n * @param query - 自然語言搜尋查詢\n * @param limit - 最大結果數量（預設：10）\n * @returns 按相似度分數排序的市場陣列\n * @throws {Error} 如果 OpenAI API 失敗或 Redis 不可用\n *\n * @example\n * ```typescript\n * const results = await searchMarkets('election', 5)\n * console.log(results[0].name) \u002F\u002F \"Trump vs Biden\"\n * ```\n *\u002F\nexport async function searchMarkets(\n  query: string,\n  limit: number = 10\n): Promise\u003CMarket[]> {\n  \u002F\u002F 實作\n}\n```\n\n## 效能最佳實務\n\n### 記憶化\n\n```typescript\nimport { useMemo, useCallback } from 'react'\n\n\u002F\u002F PASS: 良好：記憶化昂貴的計算\nconst sortedMarkets = useMemo(() => {\n  return markets.sort((a, b) => b.volume - a.volume)\n}, [markets])\n\n\u002F\u002F PASS: 良好：記憶化回呼函式\nconst handleSearch = useCallback((query: string) => {\n  setSearchQuery(query)\n}, [])\n```\n\n### 延遲載入\n\n```typescript\nimport { lazy, Suspense } from 'react'\n\n\u002F\u002F PASS: 良好：延遲載入重型元件\nconst HeavyChart = lazy(() => import('.\u002FHeavyChart'))\n\nexport function Dashboard() {\n  return (\n    \u003CSuspense fallback={\u003CSpinner \u002F>}>\n      \u003CHeavyChart \u002F>\n    \u003C\u002FSuspense>\n  )\n}\n```\n\n### 資料庫查詢\n\n```typescript\n\u002F\u002F PASS: 良好：只選擇需要的欄位\nconst { data } = await supabase\n  .from('markets')\n  .select('id, name, status')\n  .limit(10)\n\n\u002F\u002F FAIL: 不良：選擇所有欄位\nconst { data } = await supabase\n  .from('markets')\n  .select('*')\n```\n\n## 測試標準\n\n### 測試結構（AAA 模式）\n\n```typescript\ntest('calculates similarity correctly', () => {\n  \u002F\u002F Arrange（準備）\n  const vector1 = [1, 0, 0]\n  const vector2 = [0, 1, 0]\n\n  \u002F\u002F Act（執行）\n  const similarity = calculateCosineSimilarity(vector1, vector2)\n\n  \u002F\u002F Assert（斷言）\n  expect(similarity).toBe(0)\n})\n```\n\n### 測試命名\n\n```typescript\n\u002F\u002F PASS: 良好：描述性測試名稱\ntest('returns empty array when no markets match query', () => { })\ntest('throws error when OpenAI API key is missing', () => { })\ntest('falls back to substring search when Redis unavailable', () => { })\n\n\u002F\u002F FAIL: 不良：模糊的測試名稱\ntest('works', () => { })\ntest('test search', () => { })\n```\n\n## 程式碼異味偵測\n\n注意這些反模式：\n\n### 1. 過長函式\n```typescript\n\u002F\u002F FAIL: 不良：函式超過 50 行\nfunction processMarketData() {\n  \u002F\u002F 100 行程式碼\n}\n\n\u002F\u002F PASS: 良好：拆分為較小的函式\nfunction processMarketData() {\n  const validated = validateData()\n  const transformed = transformData(validated)\n  return saveData(transformed)\n}\n```\n\n### 2. 過深巢狀\n```typescript\n\u002F\u002F FAIL: 不良：5 層以上巢狀\nif (user) {\n  if (user.isAdmin) {\n    if (market) {\n      if (market.isActive) {\n        if (hasPermission) {\n          \u002F\u002F 做某事\n        }\n      }\n    }\n  }\n}\n\n\u002F\u002F PASS: 良好：提前返回\nif (!user) return\nif (!user.isAdmin) return\nif (!market) return\nif (!market.isActive) return\nif (!hasPermission) return\n\n\u002F\u002F 做某事\n```\n\n### 3. 魔術數字\n```typescript\n\u002F\u002F FAIL: 不良：無解釋的數字\nif (retryCount > 3) { }\nsetTimeout(callback, 500)\n\n\u002F\u002F PASS: 良好：命名常數\nconst MAX_RETRIES = 3\nconst DEBOUNCE_DELAY_MS = 500\n\nif (retryCount > MAX_RETRIES) { }\nsetTimeout(callback, DEBOUNCE_DELAY_MS)\n```\n\n**記住**：程式碼品質是不可協商的。清晰、可維護的程式碼能實現快速開發和自信的重構。\n",{"name":5,"description":7},"master","d6ca01da0f24a3b0e26e4a8b7b66cbd25d429f5d","web-assets\u002Fdocs\u002Fzh-TW\u002Fskills\u002Fcoding-standards",0,"https:\u002F\u002Fgithub.com\u002FSriramGandhiS\u002FSkills","https:\u002F\u002Fgithub.com\u002FSriramGandhiS","https:\u002F\u002Fsriram.website\u002F","Curious guy who keeps tinkering until something works","2026-05-20 16:21:34",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add SriramGandhiS\u002FSkills --skill coding-standards",{"tool":39,"command":40},"bunx","bunx skills add SriramGandhiS\u002FSkills --skill coding-standards",{"tool":42,"command":43},"pnpm","pnpm dlx skills add SriramGandhiS\u002FSkills --skill coding-standards","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FSriramGandhiS\u002FSkills\u002Fblob\u002Fmaster\u002Fweb-assets\u002Fdocs\u002Fzh-TW\u002Fskills\u002Fcoding-standards\u002FSKILL.md",true,[],[48,55,60,66,73,80],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":19},"01M732609EPJWV13PVTX3GT4TM","webgpu-threejs-tsl","Comprehensive guide for developing WebGPU-enabled Three.js applications using TSL (Three.js Shading Language). Covers WebGPU renderer setup, TSL syntax and node materials, compute shaders, post-processing effects, and WGSL integration. Use this skill when working with Three.js WebGPU, TSL shaders, node materials, or GPU compute in Three.js.","https:\u002F\u002Fgithub.com\u002FSriramGandhiS\u002FSkills\u002Fblob\u002Fmaster\u002Fwebgpu-threejs-tsl\u002Fskills\u002Fwebgpu-threejs-tsl\u002FSKILL.md",[],[],{"skillNo":56,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":19},"01M7325XM47AGWB6K6C4VXKE6B","https:\u002F\u002Fgithub.com\u002FSriramGandhiS\u002FSkills\u002Fblob\u002Fmaster\u002Fwebgpu-threejs-tsl\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":19},"01M7325WP6DES69JKC840VMFEP","verification-loop","https:\u002F\u002Fgithub.com\u002FSriramGandhiS\u002FSkills\u002Fblob\u002Fmaster\u002Fweb-assets\u002Fdocs\u002Fzh-TW\u002Fskills\u002Fverification-loop\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M7325TFQF1DZTQ6J3WGQQ1VR","tdd-workflow","Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests.","https:\u002F\u002Fgithub.com\u002FSriramGandhiS\u002FSkills\u002Fblob\u002Fmaster\u002Fweb-assets\u002Fdocs\u002Fzh-TW\u002Fskills\u002Ftdd-workflow\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M7325RGV9AY9PK92D2V8KKPW","strategic-compact","Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction.","https:\u002F\u002Fgithub.com\u002FSriramGandhiS\u002FSkills\u002Fblob\u002Fmaster\u002Fweb-assets\u002Fdocs\u002Fzh-TW\u002Fskills\u002Fstrategic-compact\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M7325MZC28SE86E7NMCNEFS4","security-review","Use this skill when adding authentication, handling user input, working with secrets, creating API endpoints, or implementing payment\u002Fsensitive features. Provides comprehensive security checklist and patterns.","https:\u002F\u002Fgithub.com\u002FSriramGandhiS\u002FSkills\u002Fblob\u002Fmaster\u002Fweb-assets\u002Fdocs\u002Fzh-TW\u002Fskills\u002Fsecurity-review\u002FSKILL.md",[],[]]