Subagent-Driven 與 Parallel Session：AI 協作開發的兩種典範

// 開發者指令：「建立一個熱力圖元件，使用 D3.js 繪製」

// Subagent 1: Component Builder
// 輸出：元件骨架
const HeatmapComponent = {
  props: ['data', 'width', 'height'],
  setup(props) {
    // 基本結構
  }
}

// Subagent 2: Logic Implementer
// 輸出：D3.js 繪圖邏輯
import * as d3 from 'd3'

const drawHeatmap = (data, width, height) => {
  const svg = d3.select('#heatmap')
    .attr('width', width)
    .attr('height', height)

  // 色階設定
  const colorScale = d3.scaleSequential(d3.interpolateYlOrRd)
    .domain([0, d3.max(data, d => d.value)])

  // 繪製矩形
  svg.selectAll('rect')
    .data(data)
    .enter()
    .append('rect')
    .attr('x', d => d.x)
    .attr('y', d => d.y)
    .attr('width', 20)
    .attr('height', 20)
    .attr('fill', d => colorScale(d.value))
}

// Subagent 3: Code Reviewer
// 輸出：審查建議
/*
建議改進：
1. 色階應該使用 props 傳入，提高可重用性
2. 缺少 tooltip 互動功能
3. 需要處理資料為空的情況
*/

// Subagent 4: Test Validator
// 輸出：測試結果
describe('HeatmapComponent', () => {
  it('should render correct number of cells', () => {
    const data = [{x: 0, y: 0, value: 5}]
    const result = mount(HeatmapComponent, { props: { data } })
    expect(result.findAll('rect').length).toBe(1)
  })
})
// ✅ All tests passed

# 1. 建立主要開發分支
git checkout -b feature/user-dashboard

# 2. 為不同任務建立 worktree
git worktree add ../user-dashboard-frontend feature/frontend
git worktree add ../user-dashboard-backend feature/backend
git worktree add ../user-dashboard-tests feature/tests

# 3. 查看所有 worktree
git worktree list
# /Users/dev/project              abc1234 [feature/user-dashboard]
# /Users/dev/user-dashboard-frontend  def5678 [feature/frontend]
# /Users/dev/user-dashboard-backend   ghi9012 [feature/backend]
# /Users/dev/user-dashboard-tests     jkl3456 [feature/tests]

# 4. 使用 Superpowers 執行計畫
# 在每個 worktree 中啟動獨立的 Claude Code session
# Session 1 (frontend): 專注於 React 元件開發
# Session 2 (backend): 專注於 Express API 開發
# Session 3 (tests): 專注於 Cypress E2E 測試

# implementation-plan.md

## 前端開發 (Session 1)

### Task 1.1: 建立 Dashboard 佈局
- 檔案: `src/components/Dashboard.tsx`
- 需求: 響應式網格佈局，支援 2x2 卡片
- 驗證: 在 1920x1080 和 375x667 解析度下測試

### Task 1.2: 實作使用者統計卡片
- 檔案: `src/components/UserStatsCard.tsx`
- 需求: 顯示總使用者數、活躍使用者、新註冊數
- API: `GET /api/stats/users`
- 驗證: Mock API 回應測試

### Task 1.3: 建立圖表元件
- 檔案: `src/components/UsageChart.tsx`
- 需求: 使用 Chart.js 繪製過去 7 天使用量
- 驗證: 測試資料更新動畫

---

## 後端開發 (Session 2)

### Task 2.1: 設計資料庫 Schema
- 檔案: `prisma/schema.prisma`
- 需求: User, Session, Activity 三個 model
- 驗證: `prisma generate` 無錯誤

### Task 2.2: 實作統計 API
- 檔案: `src/api/stats.ts`
- 端點: `GET /api/stats/users`
- 回應格式: `{ total: number, active: number, new: number }`
- 驗證: Postman 測試所有情境

### Task 2.3: 實作使用量查詢
- 檔案: `src/api/usage.ts`
- 端點: `GET /api/usage?days=7`
- 需求: 聚合過去 N 天的 activity 資料
- 驗證: 測試邊界條件（0 天、365 天）

---

## 測試開發 (Session 3)

### Task 3.1: Dashboard E2E 測試
- 檔案: `cypress/e2e/dashboard.cy.ts`
- 測試: 頁面載入、卡片顯示、圖表渲染
- 驗證: CI 環境通過測試

### Task 3.2: API 整合測試
- 檔案: `tests/integration/stats.test.ts`
- 測試: API 回應格式、錯誤處理、效能
- 驗證: 所有測試覆蓋率 > 80%

### Task 3.3: 效能測試
- 檔案: `tests/performance/load.test.ts`
- 測試: 1000 併發請求，p95 延遲 < 200ms
- 驗證: Artillery 報告通過

# 在 Claude Code 中使用 slash command
/superpowers:execute-plan implementation-plan.md

# 系統會：
# 1. 解析計畫檔案
# 2. 批次 1: 執行 Task 1.1, 2.1, 3.1 (獨立任務)
# 3. 報告進度並等待審查
# 4. 批次 2: 執行 Task 1.2, 2.2, 3.2 (依賴批次 1)
# 5. 報告進度並等待審查
# 6. 批次 3: 執行 Task 1.3, 2.3, 3.3 (依賴批次 2)
# 7. 最終整合驗證

# .antigravity/checkpoints/task-1-1.yml
task_id: "1.1"
status: "completed"
timestamp: "2025-11-30T10:30:00Z"
files_modified:
  - "src/components/Dashboard.tsx"
  - "src/components/Dashboard.test.tsx"
git_commit: "abc1234"
verification:
  - type: "test"
    command: "npm test Dashboard"
    result: "passed"
  - type: "visual"
    screenshot: ".antigravity/screenshots/dashboard-1920x1080.png"
    status: "approved"

# 恢復執行
/superpowers:execute-plan implementation-plan.md --resume-from task-1-2

# 系統會：
# 1. 載入 task-1-1 的 checkpoint
# 2. 跳過已完成的任務
# 3. 從 task-1-2 繼續執行

// 開發者指令：「建立一個 Vue 3 熱力圖元件，使用 D3.js」

// Subagent 1 輸出：基本結構
<template>
  <div ref="container" class="heatmap-container"></div>
</template>

<script setup>
import { ref, onMounted, watch } from 'vue'
import * as d3 from 'd3'

const props = defineProps({
  data: {
    type: Array,
    required: true
  },
  width: {
    type: Number,
    default: 800
  },
  height: {
    type: Number,
    default: 600
  }
})

const container = ref(null)

onMounted(() => {
  initHeatmap()
})

const initHeatmap = () => {
  // TODO: D3.js 繪圖邏輯
}
</script>

// 開發者指令：「實作 D3.js 繪圖，使用 YlOrRd 色階」

// Subagent 2 輸出：完整繪圖邏輯
const initHeatmap = () => {
  const svg = d3.select(container.value)
    .append('svg')
    .attr('width', props.width)
    .attr('height', props.height)

  // 計算格子尺寸
  const rows = [...new Set(props.data.map(d => d.row))].length
  const cols = [...new Set(props.data.map(d => d.col))].length
  const cellWidth = props.width / cols
  const cellHeight = props.height / rows

  // 色階設定
  const colorScale = d3.scaleSequential(d3.interpolateYlOrRd)
    .domain([0, d3.max(props.data, d => d.value)])

  // 繪製熱力圖格子
  svg.selectAll('rect')
    .data(props.data)
    .enter()
    .append('rect')
    .attr('x', d => d.col * cellWidth)
    .attr('y', d => d.row * cellHeight)
    .attr('width', cellWidth)
    .attr('height', cellHeight)
    .attr('fill', d => colorScale(d.value))
    .attr('stroke', '#fff')
    .attr('stroke-width', 1)
}

// 開發者：「色彩太淺了，能否調整為更鮮豔的色階？」

// Subagent 3 即時調整：
const colorScale = d3.scaleSequential()
  .interpolator(d3.interpolateRgbBasis(['#fee5d9', '#fcae91', '#fb6a4a', '#de2d26', '#a50f15']))
  .domain([0, d3.max(props.data, d => d.value)])

// 立即看到效果，滿意後繼續下一步

// 開發者：「滑鼠移到格子上時顯示數值」

// Subagent 4 輸出：Tooltip 邏輯
const tooltip = d3.select('body')
  .append('div')
  .attr('class', 'heatmap-tooltip')
  .style('position', 'absolute')
  .style('visibility', 'hidden')
  .style('background', '#fff')
  .style('padding', '8px')
  .style('border', '1px solid #ddd')
  .style('border-radius', '4px')
  .style('font-size', '12px')

svg.selectAll('rect')
  // ... 前面的屬性 ...
  .on('mouseover', function(event, d) {
    tooltip
      .style('visibility', 'visible')
      .html(`
        <strong>Row ${d.row}, Col ${d.col}</strong><br/>
        Value: ${d.value.toFixed(2)}
      `)

    d3.select(this)
      .attr('stroke', '#000')
      .attr('stroke-width', 2)
  })
  .on('mousemove', function(event) {
    tooltip
      .style('top', (event.pageY - 10) + 'px')
      .style('left', (event.pageX + 10) + 'px')
  })
  .on('mouseout', function() {
    tooltip.style('visibility', 'hidden')
    d3.select(this)
      .attr('stroke', '#fff')
      .attr('stroke-width', 1)
  })

// Subagent 5: Code Reviewer 自動執行
// 輸出審查報告：

/*
✅ 程式碼品質評估：

優點：
1. 使用 Vue 3 Composition API，符合現代最佳實踐
2. D3.js 色階設定正確
3. Tooltip 互動流暢

建議改進：
1. 【效能】color scale 應該快取，避免每次 render 重新計算
2. 【可維護性】繪圖邏輯應拆分為獨立函式
3. 【響應式】缺少視窗 resize 處理
4. 【可訪問性】缺少 ARIA 標籤
5. 【類型安全】建議加入 TypeScript 類型定義

優先級排序：
🔴 高優先級：#1 效能優化、#3 響應式處理
🟡 中優先級：#2 程式碼重構
🟢 低優先級：#4 可訪問性、#5 TypeScript
*/

// 開發者：「先處理效能和響應式問題」

// Subagent 6 快速修復：

// 1. 快取 color scale
const colorScale = computed(() => {
  return d3.scaleSequential()
    .interpolator(d3.interpolateRgbBasis([...colors]))
    .domain([0, d3.max(props.data, d => d.value)])
})

// 2. 響應式處理
const handleResize = () => {
  d3.select(container.value).select('svg').remove()
  initHeatmap()
}

onMounted(() => {
  initHeatmap()
  window.addEventListener('resize', debounce(handleResize, 300))
})

onBeforeUnmount(() => {
  window.removeEventListener('resize', handleResize)
})

// 3. Debounce 工具函式
const debounce = (fn, delay) => {
  let timeoutId
  return (...args) => {
    clearTimeout(timeoutId)
    timeoutId = setTimeout(() => fn(...args), delay)
  }
}

# graphql-migration-plan.md

## Phase 1: GraphQL Schema 設計 (Session 1)

### Task 1.1: 設計核心 Types
**檔案：** `schema/types/user.graphql`
**需求：**
- User, Profile, Settings 類型定義
- 欄位對應到現有 Prisma schema
- 加入必要的 nullable 設定

**驗證：**
```bash
npm run graphql:validate

export const userQueries = {
  getUser: async (_parent, { id }, { prisma }) => {
    return prisma.user.findUnique({ where: { id } })
  },

  listUsers: async (_parent, { limit = 10, offset = 0 }, { prisma }) => {
    return prisma.user.findMany({
      take: limit,
      skip: offset,
      orderBy: { createdAt: 'desc' }
    })
  },

  searchUsers: async (_parent, { query }, { prisma }) => {
    return prisma.user.findMany({
      where: {
        OR: [
          { name: { contains: query, mode: 'insensitive' } },
          { email: { contains: query, mode: 'insensitive' } }
        ]
      }
    })
  }
}

npm test src/resolvers/user.queries.test.ts

export const userFieldResolvers = {
  User: {
    posts: async (parent, _args, { prisma }) => {
      return prisma.post.findMany({
        where: { authorId: parent.id }
      })
    },

    profile: async (parent, _args, { prisma }) => {
      return prisma.profile.findUnique({
        where: { userId: parent.id }
      })
    }
  }
}

// 舊版: GET /api/users/:id
// 新版: 內部轉換為 GraphQL query

app.get('/api/users/:id', async (req, res) => {
  const query = `
    query GetUser($id: ID!) {
      getUser(id: $id) {
        id
        name
        email
        createdAt
      }
    }
  `

  const result = await executeGraphQL(query, { id: req.params.id })

  res.set('X-API-Deprecated', 'true')
  res.set('X-Migration-Deadline', '2026-03-01')
  res.json(result.data.getUser)
})

npm test src/api/graphql-client.test.ts

const useUser = (id: string) => {
  return useSWR(`/api/users/${id}`, fetcher)
}

const GET_USER = gql`
  query GetUser($id: ID!) {
    getUser(id: $id) {
      id
      name
      email
      profile {
        avatar
        bio
      }
      posts {
        id
        title
      }
    }
  }
`

const useUser = (id: string) => {
  return useQuery(GET_USER, { variables: { id } })
}

npm run test:e2e

artillery run tests/performance/graphql-load.yml

# Session 1: 資料庫 Schema
prisma/schema.prisma

model Product {
  id          String   @id @default(cuid())
  name        String
  price       Decimal
  stock       Int
  category    Category @relation(fields: [categoryId], references: [id])
  categoryId  String
}

# Session 2: API 架構
src/api/routes/products.ts
src/api/routes/cart.ts
src/api/routes/orders.ts

# Session 3: 認證系統
src/auth/jwt.ts
src/auth/middleware.ts
src/auth/providers/ (Google, Email)

# 執行時間：2 小時（自動），人工時間：15 分鐘（審查）

// Task 2.1: 產品列表 UI (Subagent-Driven)
// 理由：需要視覺調整，色彩、間距、響應式佈局

// 開發者與 subagent 互動：
// 「建立產品列表，使用 grid 佈局」
// → 查看效果
// 「卡片間距太小，改為 24px」
// → 即時調整
// 「加入 hover 效果，放大 1.05 倍」
// → 立即驗證

<template>
  <div class="product-grid">
    <ProductCard
      v-for="product in products"
      :key="product.id"
      :product="product"
      @add-to-cart="handleAddToCart"
    />
  </div>
</template>

<style scoped>
.product-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
  gap: 24px; /* 即時調整後的值 */
}
</style>

// Task 2.2: 產品搜尋 API (Parallel Session)
// 理由：純邏輯實作，有明確規格，可自動執行

// implementation-plan.md
### Task 2.2: 產品搜尋 API
**端點：** GET /api/products/search?q=keyword&category=id
**需求：**
- 全文搜尋（名稱、描述）
- 分類篩選
- 價格範圍篩選
- 排序（價格、熱度、新品）
- 分頁（limit, offset）

**實作：**
src/api/search/products.ts

**測試：**
- 測試各種搜尋組合
- 測試邊界條件
- 效能測試（1000+ 商品）

// Task 2.3: 篩選器元件 (Subagent-Driven)
// 理由：高度互動，需要即時調整 UI/UX

// 開發者與 subagent 互動：
// 「建立價格範圍滑桿」
// → 「顏色改為品牌色 #3B82F6」
// → 「加入即時預覽（顯示符合的商品數量）」
// → 「加入重置按鈕」

// Task 3.1: 購物車 UI (Subagent-Driven)
// 理由：複雜的拖放互動、動畫效果

// 開發者與 subagent 互動：
// 「實作拖放功能，可以調整商品順序」
// → 使用 Vue Draggable
// 「加入刪除動畫（淡出）」
// → 調整動畫時長
// 「總價需要即時更新」
// → 驗證計算邏輯

// Task 3.2: 庫存管理邏輯 (Parallel Session)
// 理由：複雜的業務邏輯，可完全自動化

### Task 3.2: 庫存管理邏輯
**需求：**
- 即時庫存檢查（防止超賣）
- 預留庫存（加入購物車後鎖定 15 分鐘）
- 庫存釋放（購物車過期、結帳失敗）
- 庫存警告（低於 10 件時提示）

**實作：**
```typescript
class InventoryManager {
  async reserveStock(productId: string, quantity: number, userId: string): Promise<boolean> {
    // 1. 檢查庫存充足
    // 2. 建立預留記錄
    // 3. 設定 15 分鐘過期
    // 4. 返回成功/失敗
  }

  async releaseStock(reservationId: string): Promise<void> {
    // 1. 刪除預留記錄
    // 2. 恢復庫存數量
  }

  async commitReservation(reservationId: string): Promise<void> {
    // 1. 確認訂單付款
    // 2. 永久扣減庫存
    // 3. 刪除預留記錄
  }
}

// 技巧 1: 定期總結上下文
// Prompt: 「總結目前的進度和待辦事項」

/*
Subagent 輸出：
✅ 已完成：
- ProductCard 元件基本結構
- 圖片 lazy loading
- 響應式佈局

🔄 進行中：
- 價格格式化（剩餘千分位逗號）

📋 待辦：
- Skeleton loading 動畫
- 加入購物車按鈕互動
- Hover 效果
*/

// 技巧 2: 使用「記憶點」
// Prompt: 「記住：這個專案使用 Tailwind CSS，色彩使用 blue-600 作為主色」
// 後續 subagent 會自動使用這些偏好

// 技巧 3: 關鍵決策寫入註解
// 請 subagent 在程式碼中加入關鍵決策的註解
/**
 * 價格計算邏輯
 *
 * 決策記錄：
 * 1. 使用 Decimal.js 避免浮點數精度問題
 * 2. 折扣優先級：會員折扣 > 促銷折扣 > 折扣碼
 * 3. 運費計算：訂單 > $1000 免運費
 */

GET /api/products/search

Query Parameters:
- q: string (搜尋關鍵字)
- categoryId?: string
- minPrice?: number
- maxPrice?: number
- inStock?: boolean
- brandId?: string
- sortBy?: 'relevance' | 'price_asc' | 'price_desc' | 'popularity' | 'newest'
- limit?: number (預設 20, 最大 100)
- offset?: number (預設 0)

Response:
{
  products: Product[],
  total: number,
  limit: number,
  offset: number
}

import { prisma } from '@/lib/prisma'
import { redis } from '@/lib/redis'
import type { SearchParams, SearchResult } from '@/types/search'

export async function searchProducts(params: SearchParams): Promise<SearchResult> {
  // 1. 生成快取 key
  const cacheKey = generateCacheKey(params)

  // 2. 檢查快取
  const cached = await redis.get(cacheKey)
  if (cached) return JSON.parse(cached)

  // 3. 建立搜尋條件
  const where = buildWhereClause(params)
  const orderBy = buildOrderByClause(params.sortBy)

  // 4. 執行查詢
  const [products, total] = await Promise.all([
    prisma.product.findMany({
      where,
      orderBy,
      take: params.limit,
      skip: params.offset,
      include: {
        category: true,
        brand: true,
        images: { take: 1 }
      }
    }),
    prisma.product.count({ where })
  ])

  // 5. 組合結果
  const result = {
    products,
    total,
    limit: params.limit,
    offset: params.offset
  }

  // 6. 快取結果
  await redis.setex(cacheKey, 300, JSON.stringify(result))

  return result
}

# ❌ 不好的拆分（任務過大）

## Task 1: 實作使用者認證系統
- 登入功能
- 註冊功能
- 密碼重置
- Email 驗證
- OAuth 整合（Google, GitHub）
- JWT token 管理
- 權限控制
- 測試

# ✅ 好的拆分（細粒度任務）

## Task 1.1: JWT Token 工具函式
- 檔案: `src/auth/jwt.ts`
- 功能: generateToken, verifyToken, refreshToken
- 驗證: 單元測試 100% 覆蓋率
- 時間: 30 分鐘

## Task 1.2: 使用者註冊 API
- 檔案: `src/api/auth/register.ts`
- 功能: 驗證輸入、hash 密碼、建立使用者
- 驗證: 整合測試（成功、重複 email、無效輸入）
- 時間: 45 分鐘

## Task 1.3: Email 驗證服務
- 檔案: `src/services/email-verification.ts`
- 功能: 發送驗證信、驗證 token
- 驗證: 使用 email sandbox 測試
- 時間: 60 分鐘

## Task 1.4: 使用者登入 API
- 檔案: `src/api/auth/login.ts`
- 功能: 驗證憑證、生成 JWT
- 依賴: Task 1.1
- 驗證: 整合測試
- 時間: 30 分鐘

## Task 1.5: 密碼重置流程
- 檔案: `src/api/auth/reset-password.ts`
- 功能: 請求重置、驗證 token、更新密碼
- 依賴: Task 1.3
- 驗證: E2E 測試完整流程
- 時間: 60 分鐘

## Task 1.6: Google OAuth 整合
- 檔案: `src/auth/oauth/google.ts`
- 功能: OAuth 流程、使用者關聯
- 驗證: 使用 Google OAuth playground 測試
- 時間: 90 分鐘

## Task 1.7: GitHub OAuth 整合
- 檔案: `src/auth/oauth/github.ts`
- 功能: OAuth 流程、使用者關聯
- 依賴: Task 1.6 (可重用 OAuth 基礎架構)
- 驗證: 使用 GitHub OAuth app 測試
- 時間: 45 分鐘

## Task 1.8: 權限控制中介層
- 檔案: `src/middleware/auth.ts`
- 功能: requireAuth, requireRole
- 依賴: Task 1.1
- 驗證: 單元測試 + 整合測試
- 時間: 45 分鐘

## Task 1.9: E2E 認證測試
- 檔案: `tests/e2e/auth.spec.ts`
- 功能: 完整流程測試
- 依賴: 所有前面的任務
- 驗證: Cypress 測試通過
- 時間: 60 分鐘

# .antigravity/config.yml

checkpoint:
  auto: true
  trigger:
    - on_task_complete  # 每個任務完成後
    - on_test_pass      # 測試通過後
    - on_git_commit     # Git commit 後

  保存內容:
    - modified_files    # 修改的檔案列表
    - git_commit_hash   # Git commit SHA
    - test_results      # 測試結果
    - execution_log     # 執行日誌
    - performance_metrics  # 效能指標

# 在計畫中標記關鍵 checkpoint

## 🔖 Checkpoint Alpha: 基礎架構完成
**觸發條件：** Task 1.1-1.5 全部完成
**驗證：**
- [ ] 所有 API 端點可正常呼叫
- [ ] 資料庫 migrations 成功
- [ ] 基本認證流程運作

**Review 重點：**
- Schema 設計是否合理？
- API 介面是否符合前端需求？
- 安全性是否考慮周全？

---

## 🔖 Checkpoint Beta: 核心功能完成
**觸發條件：** Task 2.1-2.8 全部完成
**驗證：**
- [ ] 產品CRUD 功能完整
- [ ] 搜尋效能達標
- [ ] 購物車邏輯正確

**Review 重點：**
- 效能是否符合預期？
- 錯誤處理是否完善？
- 使用者體驗是否流暢？

---

## 🔖 Checkpoint RC: 上線前驗證
**觸發條件：** 所有任務完成
**驗證：**
- [ ] E2E 測試 100% 通過
- [ ] 效能測試達標
- [ ] 安全性掃描無嚴重問題
- [ ] 文件完整

**Review 重點：**
- 是否有遺漏的功能？
- 是否有技術債需要處理？
- 上線計畫是否完整？

# 列出所有 checkpoint
/superpowers:list-checkpoints

# 輸出：
# 🔖 Checkpoint Alpha (2025-11-30 10:00)
#    Status: ✅ Passed
#    Tasks: 1.1-1.5 (5/5 completed)
#
# 🔖 Checkpoint Beta (2025-11-30 14:30)
#    Status: ⚠️  Partial (7/8 tasks)
#    Failed: Task 2.7 (效能測試未達標)
#
# 🔖 Checkpoint RC
#    Status: ⏳ Pending

# 從 Beta checkpoint 恢復並重試失敗任務
/superpowers:resume-from checkpoint-beta --retry-failed

# 系統會：
# 1. 恢復到 Beta checkpoint 的狀態
# 2. 檢查 Task 2.7 失敗原因
# 3. 調整實作（例如加入 index、優化查詢）
# 4. 重新執行效能測試
# 5. 如果通過，繼續後續任務

# implementation-plan.yml

retry_strategy:
  max_attempts: 3
  backoff: exponential  # linear, exponential, fixed

  retry_conditions:
    - test_failure
    - performance_threshold_not_met
    - compilation_error
    - linting_error

  no_retry_conditions:
    - manual_approval_rejected
    - dependency_missing
    - external_service_down

task_specific_retry:
  "Task 2.7":  # 效能測試任務
    max_attempts: 5
    strategy: optimize_and_retry
    optimization_steps:
      - add_database_index
      - enable_query_cache
      - implement_connection_pooling
      - use_batch_processing
      - add_cdn_caching

// Task 2.7: 產品搜尋效能優化
// 第一次嘗試：基本實作
// 結果：p95 延遲 450ms ❌ (目標 < 200ms)

// 第二次嘗試：加入資料庫 index
await prisma.$executeRaw`
  CREATE INDEX idx_product_search ON products
  USING GIN (to_tsvector('english', name || ' ' || description));
`
// 結果：p95 延遲 280ms ❌ (仍未達標)

// 第三次嘗試：加入 Redis 快取
const cacheKey = `search:${hashParams(params)}`
const cached = await redis.get(cacheKey)
if (cached) return JSON.parse(cached)
// ... 執行查詢 ...
await redis.setex(cacheKey, 300, JSON.stringify(result))
// 結果：p95 延遲 180ms ✅ (達標！)

// Checkpoint 記錄：
// Attempt 1: Failed (450ms > 200ms)
// Attempt 2: Failed (280ms > 200ms) - Added DB index
// Attempt 3: Passed (180ms < 200ms) - Added Redis cache
// Final solution: DB index + Redis cache

// 策略 1: 定期總結並重置
// 每完成一個功能模組，要求總結並開啟新 session

// Prompt: 「總結目前完成的工作，列出關鍵決策和下一步」
/*
總結：
✅ 完成 ProductCard 元件（支援 lazy loading、響應式）
✅ 完成價格格式化（使用 Decimal.js）
✅ 完成 hover 效果（scale 1.05）

關鍵決策：
- 使用 Tailwind CSS
- 主色 blue-600
- 間距 24px
- 圖片比例 4:3

下一步：
- 購物車元件
- 結帳流程
*/

// 策略 2: 使用「記憶檔案」
// 將關鍵決策寫入專案的 DECISIONS.md
// 新 session 可以快速載入這個檔案

// DECISIONS.md
/*
# 專案決策記錄

## UI/UX
- 主色: #3B82F6 (blue-600)
- 間距標準: 8px 為基準單位
- 圓角: 8px (卡片), 4px (按鈕)
- 動畫時長: 200ms (hover), 300ms (轉場)

## 技術選型
- 狀態管理: Pinia
- UI 框架: Tailwind CSS
- 圖表: Chart.js
- 日期: date-fns
- 數字精度: Decimal.js

## API 規範
- 日期格式: ISO 8601
- 錯誤格式: { error: { code, message, details } }
- 分頁: limit/offset
*/

// 新 session 開始時：
// Prompt: 「請閱讀 DECISIONS.md，遵循這些決策」

# 範例：大型資料庫遷移

# 階段 1: 使用 Subagent-Driven 設計遷移腳本
# (30 分鐘，需要即時調整邏輯)
Prompt: 「設計 User 資料表遷移腳本，從 MySQL 到 PostgreSQL」
→ 生成遷移腳本
→ 審查並調整
→ 測試小量資料

# 階段 2: 切換到 Parallel Session 執行大規模遷移
# (3 小時，背景執行)
/superpowers:execute-plan migration-plan.md
→ 系統自動執行
→ 開發者可以去做其他事
→ 完成後通知審查

# 使用 Subagent 幫忙撰寫 Parallel Session 計畫

Prompt: 「我需要實作使用者認證系統，包含註冊、登入、OAuth。請幫我撰寫一份適合 Parallel Session 執行的實作計畫」

# Subagent 會生成詳細的 implementation-plan.md
# 包含：
# - 任務拆分（每個 30-90 分鐘）
# - 檔案路徑
# - 程式碼範例
# - 驗證條件
# - 相依性圖

# 開發者審查並調整計畫
# 然後執行 Parallel Session

# 情境：正在執行 Phase 2，但 Phase 1 的設計需要調整

# 1. 暫停 Parallel Session
/superpowers:pause-execution

# 2. 切換到 Subagent-Driven 快速調整
Prompt: 「Phase 1 的 User Schema 需要加入 role 欄位，請幫我調整」
→ 快速修改 schema
→ 更新 migration
→ 測試驗證

# 3. 更新實作計畫
# 修改 implementation-plan.md，反映新的 schema

# 4. 恢復 Parallel Session
/superpowers:resume-execution --update-plan
→ 系統重新載入計畫
→ 繼續執行，使用新的 schema

# 配置詳細日誌

logging:
  level: debug
  output:
    - console
    - file: .antigravity/logs/execution.log

  include:
    - executed_commands
    - test_output
    - error_stack_traces
    - performance_metrics
    - git_operations

  on_error:
    - capture_screenshot  # 如果是 UI 相關
    - dump_database_state  # 如果是資料相關
    - save_network_logs    # 如果是 API 相關
    - pause_execution      # 暫停讓開發者介入

// Task 執行失敗時的處理流程

async function executeTask(task: Task) {
  let attempt = 0
  const maxAttempts = 3

  while (attempt < maxAttempts) {
    try {
      attempt++

      // 執行任務
      const result = await runTask(task)

      // 執行測試
      const testResult = await runTests(task.tests)

      if (testResult.passed) {
        // 成功，建立 checkpoint
        await createCheckpoint(task, result)
        return result
      } else {
        // 測試失敗，分析原因
        const analysis = await analyzeFailure(testResult)

        if (analysis.canAutoFix) {
          // 自動修復並重試
          await applyFix(analysis.suggestedFix)
          continue
        } else {
          // 無法自動修復，暫停並通知開發者
          await pauseExecution()
          await notifyDeveloper({
            task,
            attempt,
            error: testResult.errors,
            analysis
          })

          // 等待人工介入
          await waitForManualFix()
          continue
        }
      }
    } catch (error) {
      // 執行階段錯誤
      logger.error(`Task ${task.id} attempt ${attempt} failed:`, error)

      if (attempt === maxAttempts) {
        // 最終失敗，記錄並暫停
        await logFailure(task, error)
        await pauseExecution()
        throw new TaskExecutionError(task, error)
      }

      // 重試前等待（exponential backoff）
      await sleep(Math.pow(2, attempt) * 1000)
    }
  }
}

# 核心 skills
- superpowers:brainstorming           # 任務規劃前腦力激盪
- superpowers:writing-plans           # 撰寫 Parallel Session 計畫
- superpowers:executing-plans         # 執行 Parallel Session 計畫
- superpowers:verification-before-completion  # 完成前驗證
- superpowers:code-reviewer          # 程式碼審查
- superpowers:test-driven-development # TDD 工作流程
- superpowers:systematic-debugging    # 系統化除錯

# 進階 skills
- superpowers:using-git-worktrees    # Git worktree 管理
- superpowers:subagent-driven-development  # Subagent 最佳實踐
- superpowers:dispatching-parallel-agents  # 並行代理管理