Cursor Rules：如何撰寫真正有效的 .cursor/rules 檔案

mkdir -p .cursor/rules

---
description: "When this rule should apply"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

Your instructions go here in plain markdown.

---
alwaysApply: true
---

---
globs: ["src/api/**/*.ts", "src/routes/**/*.ts"]
alwaysApply: false
---

---
description: "Database migration patterns using Drizzle ORM"
alwaysApply: false
---

---
---

# All TypeScript files in src
globs: ["src/**/*.ts", "src/**/*.tsx"]

# Only component files
globs: ["**/components/**/*.tsx"]

# Python files, excluding tests
globs: ["**/*.py", "!**/test_*.py"]

# Multiple specific directories
globs: ["src/api/**", "src/services/**"]

---
alwaysApply: true
---

# Project: Acme Dashboard

## Tech Stack
- Next.js 15 (App Router only — no Pages Router)
- TypeScript strict mode
- Tailwind CSS v4
- Drizzle ORM with PostgreSQL
- pnpm for package management

## Critical Conventions
- All components are React Server Components by default
- Use "use client" only when the component needs interactivity
- Import paths use @/ alias mapped to src/
- Error handling: wrap async operations in try/catch, never use .catch()
- No default exports except for pages and layouts

---
description: "React component patterns and conventions"
globs: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
alwaysApply: false
---

# React Component Rules

## Structure
Every component file follows this order:
1. Imports
2. Type definitions (Props interface)
3. Component function (named export)
4. Sub-components (if any)

## Patterns

Use named exports, not default:
- YES: `export function Button({ label }: ButtonProps)`
- NO: `export default function Button()`

For data fetching in Server Components:
```tsx
// 直接在元件中獲取資料，不使用 useEffect
export async function UserProfile({ id }: { id: string }) {
  const user = await db.query.users.findFirst({
    where: eq(users.id, id)
  });
  return <div>{user.name}</div>;
}

### Python API 規則 (Auto-Attached)

```yaml
---
description: "FastAPI endpoint conventions and patterns"
globs: ["src/api/**/*.py", "src/routes/**/*.py"]
alwaysApply: false
---

# FastAPI Conventions

## Endpoint Structure
- Use APIRouter for route grouping
- Type all request/response models with Pydantic v2
- Dependency injection for database sessions

## Pattern
```python
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

router = APIRouter(prefix="/users", tags=["users"])

@router.get("/{user_id}", response_model=UserResponse)
async def get_user(
    user_id: int,
    db: AsyncSession = Depends(get_db)
) -> UserResponse:
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return UserResponse.model_validate(user)

### Go Service 規則 (Auto-Attached)

```yaml
---
description: "Go service patterns and error handling"
globs: ["**/*.go", "!**/*_test.go"]
alwaysApply: false
---

# Go Conventions

## Error Handling
- Always handle errors immediately — no _ for error returns
- Wrap errors with fmt.Errorf("context: %w", err)
- Use sentinel errors for expected failure cases

## Project Layout
- cmd/ for entrypoints
- internal/ for private packages
- pkg/ for public libraries

## Pattern
```go
func (s *UserService) GetByID(ctx context.Context, id string) (*User, error) {
    user, err := s.repo.Find(ctx, id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
        }
        return nil, fmt.Errorf("fetching user %s: %w", id, err)
    }
    return user, nil
}

## 管理 Token 稅負

這是大多數 Cursor 指南忽略的一點：你撰寫的每個規則都會消耗 Token。一個擁有 20 個始終啟用規則的專案，可能在 AI 甚至查看你的程式碼之前，每個請求就消耗 **2,000+ Token** 僅用於指令。

這很重要，因為 Cursor 的聊天上下文在標準模式下大約為 20,000 Token。如果你的規則吃掉了其中的 25%，你就損失了四分之一的 AI「思考空間」來處理你的實際問題。隨著規則累積，你會注意到輸出品質變差，特別是在較長的對話中。

三個原則能保持你的 Token 預算健康：

**1. 積極使用自動附加和代理程式請求規則。** 只有你的專案堆疊聲明應該始終啟用。其他一切都應條件式載入。那個 React 元件規則？當你撰寫 SQL 遷移腳本時，它不需要存在於上下文中。

**2. 寫得精簡，不要囉嗦。** 將「強烈建議開發者在定義公共 API 合約時使用 TypeScript 介面而非類型別名」替換為「公共 API 優先使用 `interface` 而非 `type`」。AI 不需要說服，它需要指令。

**3. 應用「三次規則」。** 只有在 AI 犯錯三次後，才將模式編碼為規則。如果 Cursor 已經在沒有規則的情況下正確處理了你的命名規範，那就跳過該規則。每個不必要的規則都是浪費的上下文。

你可以在 Cursor 聊天面板底部的狀態列監控 Token 使用情況。注意它是否接近 100%，那是你需要修剪規則的信號。

## 為真實專案組織規則

一個生產環境專案通常需要 5-8 個規則檔案。以下是一個運作良好的結構：

```text
.cursor/rules/
  base.mdc            # Tech stack, always-apply (< 30 lines)
  components.mdc      # React/Vue patterns, glob to component dirs
  api.mdc             # Backend conventions, glob to API dirs
  database.mdc        # ORM patterns, glob to models/migrations
  testing.mdc         # Test conventions, glob to test files
  deployment.mdc      # CI/CD patterns, manual trigger
  personal.mdc        # Your preferences (gitignored)