核心功能詳解

// 引用單一檔案
@src/components/Button.tsx 這個元件的 props 型別是什麼？

// 引用資料夾
@src/utils 幫我找出所有處理日期格式的函式

// 引用整個程式碼庫
@codebase 我的專案中哪些地方有使用 Redux？

// 引用網路文件
@https://docs.react.dev/reference/react/useState
根據官方文件，useState 的最佳實踐是什麼？

// 引用最近的錯誤訊息
@errors 這個錯誤是什麼意思，如何修復？

// 解釋程式碼
"解釋這段程式碼的邏輯，用繁體中文說明"

// 發現潛在問題
"這段程式碼有什麼潛在的 bug 或效能問題？"

// 生成測試
"為這個函式生成 Jest 單元測試，涵蓋邊界情況"

// 改善程式碼
"重構這段程式碼使其更符合 SOLID 原則"

// 生成文件
"為這個模組生成 JSDoc 說明，包含參數與回傳值"

// 新增功能
"在 src/components 目錄下建立一個 Modal 元件，
支援標題、內容、確認/取消按鈕，並加入動畫效果"

// 重構任務
"將 src/utils/dateHelper.js 轉換為 TypeScript，
加入完整的型別定義並更新所有引用的檔案"

// 修復 Bug
"找出並修復應用程式中所有造成記憶體洩漏的地方，
特別注意 useEffect 的清理函式"

// 加入測試
"為 src/services 目錄下的所有服務建立單元測試，
使用 Jest 和 React Testing Library"

// 情境一：完成函式實作
// 當你輸入函式簽名後，Cursor 可能直接預測完整實作
function calculateTax(amount: number, rate: number) {
  // Cursor 可能自動補全：
  return amount * (rate / 100);
}

// 情境二：重複模式的延伸
// 當你輸入第一個 case，Cursor 預測後續的 case
switch (action.type) {
  case 'INCREMENT':
    return { ...state, count: state.count + 1 };
  case 'DECREMENT':     // ← 你輸入到這，Tab 補完整行
    return { ...state, count: state.count - 1 };

// 情境三：測試程式碼生成
// 輸入一個 describe 區塊的標題，Cursor 預測 test 內容
describe('calculateTax', () => {
  it('should return correct tax amount', () => {
    // Cursor 可能預測：
    expect(calculateTax(100, 10)).toBe(10);
  });
});

// 場景一：型別轉換
// 選取 JavaScript 函式，輸入：
"轉換為 TypeScript，加入完整型別定義"

// 場景二：重構
// 選取多層巢狀的 if-else，輸入：
"重構為 early return 風格，提高可讀性"

// 場景三：加入錯誤處理
// 選取 API 呼叫，輸入：
"加入完整的錯誤處理，包含 try-catch 與錯誤訊息"

// 場景四：效能最佳化
// 選取迴圈邏輯，輸入：
"用 Array.reduce 重寫這個邏輯，提高效能"

// 場景五：加入文件
// 選取函式，輸入：
"加入 JSDoc 說明，包含 @param 和 @returns"

# .cursorrules
你是一個精通 React 與 TypeScript 的資深前端工程師。

## 程式碼規範
- 使用 functional components，不使用 class components
- 所有 props 都必須有 TypeScript 型別定義
- 使用 const 宣告，避免 let（除非值需要改變）
- import 順序：React → 第三方套件 → 本地模組

## 命名規範
- 元件：PascalCase（例如 UserProfile）
- Hooks：camelCase 且以 use 開頭（例如 useUserData）
- 常數：SCREAMING_SNAKE_CASE（例如 MAX_RETRIES）
- 一般變數與函式：camelCase

## 架構規範
- 元件拆分原則：單一職責，不超過 150 行
- 將業務邏輯抽取到自訂 hooks
- 使用 React Query 管理伺服器狀態
- 使用 Zustand 管理客戶端狀態

## 回覆格式
- 說明文字使用繁體中文
- 程式碼範例完整可執行，不省略
- 有多種實作方式時，說明各自優缺點

# .cursorrules（後端版本）
你是一個 Node.js 後端工程師，熟悉 Express 和 PostgreSQL。

- 使用 async/await，避免 callback 風格
- 所有資料庫操作使用 Drizzle ORM
- API 路由遵循 RESTful 規範
- 輸入驗證使用 Zod schema
- 錯誤統一透過 middleware 處理
- 環境變數使用 dotenv，不硬編碼任何密鑰

// ~/.cursor/mcp.json 或 .cursor/mcp.json（專案層級）
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}