# 🟧 Claude Code
curl -fsSL https://claude.ai/install.sh | bash

# 🟢 Codex CLI
npm install -g @openai/codex
# 或 brew install codex

# 🔵 Antigravity CLI
brew install google/antigravity/antigravity
# 或 curl -fsSL https://antigravity.dev/install.sh | bash

# 🟧 Claude Code
winget install Anthropic.ClaudeCode

# 🟢 Codex CLI
winget install OpenAI.Codex

# 🔵 Antigravity CLI
winget install Google.Antigravity

claude                 # 🟧 互動模式
codex                  # 🟢 互動模式
antigravity            # 🔵 互動模式

# 認證(首次使用)
claude /login
codex login
antigravity auth login

# Claude 做主力重構
claude "refactor the auth module to use JWT"

# Codex 做獨立 review
codex "review the recent changes for security issues"

/ccg "我們的資料庫應該選 PostgreSQL 還是 MongoDB?"
# 同時取得 Claude、Codex、Gemini 三方意見

antigravity migrate --from-gemini-cli

npm install -g @openai/codex@latest

claude --update
# 或重新跑安裝指令

> /help

Available commands:
  /help        Show this help message
  /clear       Clear conversation history
  /compact     Compact conversation to save tokens
  /model       Change AI model
  /agents      Manage sub-agents
  ...

# 一般 compact
> /compact

# 帶上指示，告訴 Claude 該保留什麼
> /compact 請特別保留資料庫 schema 設計和 API 路由規劃

> /model

選擇模型：
  > opus     - 最強推理能力，適合複雜任務（耗 token 多）
    sonnet   - 平衡選擇，日常開發推薦
    haiku    - 最快最便宜，適合簡單任務

> /config

設定項目：
  - 預設模型
  - 通知偏好
  - 自動 commit 行為
  - 編輯器整合（VSCode、Cursor）
  - 主題（淺色 / 深色）
  - 語言偏好

> /permissions

允許清單（不再詢問）：
  ✓ Edit files
  ✓ Run: npm test
  ✓ Run: git commit
  
拒絕清單：
  ✗ Run: rm -rf
  ✗ Run: sudo *

> /cost

本次對話：
  Input tokens:  45,231
  Output tokens: 8,452
  Estimated cost: $0.42
  訂閱方案使用率: 12%

> /theme dark
> /theme light

> /init

Claude 會：
  1. 掃描專案結構
  2. 識別語言、框架、套件管理工具
  3. 找出主要目錄與檔案
  4. 生成 CLAUDE.md（專案指南）
  5. 建議常用指令（測試、建構、執行）

> 幫我重構 @src/utils/api.py，把所有 sync 函式改成 async

> 比較 @models/user.py 和 @models/admin.py 的差異

> /add-dir ~/projects/shared-lib

✓ 已加入 ~/projects/shared-lib，現在可以引用此目錄的檔案

> /memory

記憶層次：
  1. 全域：~/.claude/CLAUDE.md       （所有專案共用）
  2. 專案：./CLAUDE.md               （此專案的指引）
  3. 子目錄：./src/CLAUDE.md          （特定目錄的細節）

> # 這個專案的所有 API 路由前綴都是 /api/v2

> # 測試用 pytest，覆蓋率目標 90%

> # 不要修改 legacy/ 資料夾的程式碼

> /agents

選項：
  1. 建立新代理（互動精靈）
  2. 編輯現有代理
  3. 列出所有代理
  4. 刪除代理
  5. 切換代理（針對當前對話）

> /mcp

已連線的 MCP servers：
  ✓ github      (issues, PRs, repos)
  ✓ postgres    (查詢、執行 SQL)
  ○ figma       (未連線)
  
選項：
  - add        新增 server
  - remove     移除 server
  - status     檢查連線狀態
  - reconnect  重新連線

> /skills

可用技能：
  /skill deploy        部署到 staging（含測試、build、上傳）
  /skill release       建立 release（含版號、changelog、tag）
  /skill onboard       新人 onboarding（讀文件、跑教學）
  /skill bug-triage    Bug 分類與初步分析

> 把現在的變更分成兩個 commit，第一個是 bug 修復，第二個是新功能

> 看一下 main 跟我這個 branch 的差異，幫我寫 PR 描述

> rebase 到最新的 main，遇到衝突就停下來問我

> /commit

分析變更...

建議的 commit 訊息：
  feat(api): add pagination support to user list endpoint
  
  - Add limit/offset query parameters
  - Update OpenAPI spec
  - Add tests for boundary cases

執行？(y/n)

# 建立 PR
> /pr create

# 列出 PR
> /pr list

# 檢視特定 PR
> /pr view 42

# 對 PR 加 review 意見
> /pr review 42

> /review

🔍 Code Review 結果（5 個檔案，+234 -56 行）

✅ 通過：
  - 命名清晰、結構合理
  - 測試覆蓋良好

⚠️ 建議：
  - api.py:45  未處理 ConnectionError，建議加 retry
  - user.py:88  N+1 查詢問題，建議改用 select_related
  - 缺少 README 更新

🔴 必須修正：
  - auth.py:12  密碼以明文儲存（嚴重安全問題）

> /issue list           # 列出開啟中的 issue
> /issue view 123       # 看單一 issue 詳情
> /issue create         # 建立新 issue
> /issue close 123      # 關閉 issue

# 或自然語言
> 找 issue 123，分析根因並幫我修復

> !ls -la
> !git status
> !pytest tests/test_api.py -v
> !npm run dev

> # 這個專案用 black 格式化，行寬 88

Claude 會問你要存到哪個層級：
  1. 全域 (~/.claude/CLAUDE.md)
  2. 專案 (./CLAUDE.md)
  3. 子目錄 (./src/CLAUDE.md)

> 幫我寫一個 Python script，需求是： \
這個 script 接受 CSV 檔案路徑當參數， \
讀取後印出每個欄位的統計資料， \
包含平均值、中位數、標準差。

> 我要做一個訂單管理系統。先不要寫程式，
  我們分階段做：
  
  階段 1：列出需要的資料模型（User、Order、Product...）
  階段 2：設計 API 端點
  階段 3：寫 schema migration
  階段 4：實作 endpoint
  階段 5：寫測試
  
  我們先做階段 1，列出每個 model 需要的欄位。

> 我要建一個部落格網站，但還沒想清楚需求。
  你來問我問題，幫我釐清。

┌─────────────────────────────────────────────┐
│ [≡]  File Edit ...  ← 選單列                 │
├──┬──────────────────────────────────────────┤
│📁│                                          │
│🔍│  ← 主編輯區                              │
│🔃│                                          │
│🐛│                                          │
│🧩│  Extensions 在這 ↑                       │
│⚙️│                                          │
├──┴──────────────────────────────────────────┤
│ > Terminal（PowerShell / bash / zsh）       │ ← Ctrl+`
└─────────────────────────────────────────────┘
 ↑
 左側活動列：檔案、搜尋、版控、除錯、擴充、設定

# VSCode
code --install-extension ms-ceintl.vscode-language-pack-zh-hant

# Antigravity
antigravity --install-extension ms-ceintl.vscode-language-pack-zh-hant

按 Ctrl+Shift+P
> 設定顯示語言（Configure Display Language）
> 選擇 "en"
重新啟動

{
  "locale": "zh-tw"
}

{
  // Python 直譯器
  "python.defaultInterpreterPath": "./.venv/bin/python",
  
  // 自動匯入
  "python.analysis.autoImportCompletions": true,
  "python.analysis.typeCheckingMode": "basic",
  
  // 使用 Ruff 做格式化與 linting
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": "explicit",
      "source.fixAll": "explicit"
    }
  },
  
  // 測試設定
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": ["tests"],
  
  // 終端機自動啟用 venv
  "python.terminal.activateEnvironment": true
}

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: 當前檔案",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "justMyCode": true
    },
    {
      "name": "FastAPI 開發伺服器",
      "type": "debugpy",
      "request": "launch",
      "module": "uvicorn",
      "args": ["src.main:app", "--reload"],
      "jinja": true
    },
    {
      "name": "pytest（所有測試）",
      "type": "debugpy",
      "request": "launch",
      "module": "pytest",
      "args": ["-v"],
      "console": "integratedTerminal"
    }
  ]
}

code --install-extension rjwang.vscode-office-enhanced

右鍵點選檔案 > Open With...
> 選擇 "Office Viewer"
// 或設成預設
> Configure default editor...

{
  "workbench.editorAssociations": {
    "*.md": "default",
    "*.markdown": "default"
  }
}

┌──────────────┬──────────────────────────────┐
│              │                              │
│  📁 檔案     │  📝 程式碼編輯區             │
│  總管        │                              │
│              │                              │
│              ├──────────────────────────────┤
│              │                              │
│              │  $ cc                        │
│              │  > 幫我重構這個檔案...        │
│              │  Claude Code 終端機          │
│              │                              │
└──────────────┴──────────────────────────────┘

## 開發環境
- 編輯器：VSCode
- 必裝擴充：Python (ms-python.python)、Ruff、Office Viewer
- 終端機：在 VSCode 內建終端機跑指令
- Debug：用 launch.json 的 "Python: 當前檔案" 設定檔

> 把剛剛產生的測試結果用 VSCode 開出來給我看
> !code reports/coverage.html

> 開啟剛建立的 Excel 報表
> !code output/sales_summary.xlsx

{
  // 開啟這個 workspace 時，VSCode 會建議裝以下擴充
  "recommendations": [
    "ms-ceintl.vscode-language-pack-zh-hant",
    "ms-python.python",
    "ms-python.vscode-pylance",
    "charliermarsh.ruff",
    "ms-python.mypy-type-checker",
    "ms-toolsai.jupyter",
    "cweijan.vscode-office",
    "eamodio.gitlens",
    "njpwerner.autodocstring"
  ]
}

[
  {
    // 在終端機跑 cc
    "key": "ctrl+alt+c",
    "command": "workbench.action.terminal.sendSequence",
    "args": { "text": "cc\u000D" }
  },
  {
    // 對目前檔案執行 Claude review
    "key": "ctrl+alt+r",
    "command": "workbench.action.terminal.sendSequence",
    "args": { "text": "cc -p \"review ${file}\"\u000D" }
  }
]

{
  "name": "Python + Claude Code",
  "image": "mcr.microsoft.com/devcontainers/python:3.12",
  
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-ceintl.vscode-language-pack-zh-hant",
        "ms-python.python",
        "charliermarsh.ruff",
        "cweijan.vscode-office"
      ]
    }
  },
  
  "postCreateCommand": "curl -fsSL https://claude.ai/install.sh | bash"
}

my-project/
├── .claude/
│   ├── agents/              # 子代理定義
│   ├── hooks/               # 自動化 hooks
│   └── settings.local.json  # 本地權限設定
├── src/
│   └── my_project/
│       ├── __init__.py
│       ├── main.py
│       ├── api/
│       ├── models/
│       └── services/
├── tests/
│   ├── conftest.py
│   ├── test_api.py
│   └── test_models.py
├── docs/
│   ├── requirements.md      # 需求文件
│   ├── design.md            # 設計文件
│   └── tasks.md             # 任務拆解
├── CLAUDE.md                # 專案指南（給 Claude 看）
├── pyproject.toml
├── .gitignore
└── README.md

# Project: My FastAPI Service

## 專案概覽
這是一個 FastAPI 後端服務，提供使用者管理 API。
資料庫使用 PostgreSQL，ORM 用 SQLAlchemy 2.0。

## 技術棧
- Python 3.12+
- FastAPI 0.110+
- SQLAlchemy 2.0（async 風格）
- Pydantic v2
- pytest（測試）
- uv（套件管理）

## 專案結構
- `src/my_project/api/` — API 路由
- `src/my_project/models/` — DB models
- `src/my_project/schemas/` — Pydantic schemas
- `src/my_project/services/` — 業務邏輯
- `tests/` — 對應結構的測試

## 開發規範
1. 所有函式必須加 type hints
2. 公開 API 必須寫 docstring（Google style）
3. 行寬限制 88 字（Black 預設）
4. import 順序由 ruff 自動處理
5. commit 訊息遵循 Conventional Commits

## 常用指令
- 啟動開發伺服器：`uv run uvicorn src.my_project.main:app --reload`
- 跑測試：`uv run pytest`
- 跑單一測試：`uv run pytest tests/test_api.py::test_create_user -v`
- 格式化：`uv run ruff format .`
- Lint：`uv run ruff check . --fix`
- 類型檢查：`uv run mypy src/`

## 測試規範
- 每個新功能必須有對應測試
- 整體覆蓋率目標：85%+
- 測試獨立，不依賴執行順序
- 用 fixtures 而非 setUp/tearDown

## 重要規則
- ❌ 不要修改 `migrations/` 已存在的檔案，要新增 migration
- ❌ 不要在 model 層寫業務邏輯，那是 service 層的事
- ❌ 不要 commit `.env` 或任何 secrets
- ✅ 所有 DB 操作必須是 async
- ✅ 使用者輸入必須用 Pydantic schema 驗證

## 環境變數
參考 `.env.example`，必須提供：
- `DATABASE_URL`
- `JWT_SECRET`
- `REDIS_URL`

# 個人開發偏好

## 回應風格
- 用繁體中文回答
- 程式碼註解用英文,討論用中文

## 程式碼風格
- Python:遵循 PEP 8,type hints 必加
- JavaScript:偏好 TypeScript over JS
- 變數命名用全名而非縮寫(`user_count` 而非 `uc`)

## 安全規則
- 絕對不在 code 寫入 API key、密碼
- 不要執行 `rm -rf` 或 `sudo` 指令,有需要需先經過同意
- 修改前先確認檔案路徑


These rules apply to every task in this project unless explicitly overridden.
Bias: caution over speed on non-trivial work. Use judgment on trivial tasks.

## Rule 1 — Think Before Coding

State assumptions explicitly. If uncertain, ask rather than guess.
Present multiple interpretations when ambiguity exists.
Push back when a simpler approach exists.
Stop when confused. Name what's unclear.

## Rule 2 — Simplicity First

Minimum code that solves the problem. Nothing speculative.
No features beyond what was asked. No abstractions for single-use code.
Test: would a senior engineer say this is overcomplicated? If yes, simplify.

## Rule 3 — Surgical Changes

Touch only what you must. Clean up only your own mess.
Don't "improve" adjacent code, comments, or formatting.
Don't refactor what isn't broken. Match existing style.

## Rule 4 — Goal-Driven Execution

Define success criteria. Loop until verified.
Don't follow steps. Define success and iterate.
Strong success criteria let you loop independently.

## Rule 5 — Use the model only for judgment calls

Use me for: classification, drafting, summarization, extraction.
Do NOT use me for: routing, retries, deterministic transforms.
If code can answer, code answers.

## Rule 6 — Token budgets are not advisory

Per-task: 4,000 tokens. Per-session: 30,000 tokens.
If approaching budget, summarize and start fresh.
Surface the breach. Do not silently overrun.

## Rule 7 — Surface conflicts, don't average them

If two patterns contradict, pick one (more recent / more tested).
Explain why. Flag the other for cleanup.
Don't blend conflicting patterns.

## Rule 8 — Read before you write

Before adding code, read exports, immediate callers, shared utilities.
"Looks orthogonal" is dangerous. If unsure why code is structured a way, ask.

## Rule 9 — Tests verify intent, not just behavior

Tests must encode WHY behavior matters, not just WHAT it does.
A test that can't fail when business logic changes is wrong.

## Rule 10 — Checkpoint after every significant step

Summarize what was done, what's verified, what's left.
Don't continue from a state you can't describe back.
If you lose track, stop and restate.

## Rule 11 — Match the codebase's conventions, even if you disagree

Conformance > taste inside the codebase.
If you genuinely think a convention is harmful, surface it. Don't fork silently.

## Rule 12 — Fail loud

"Completed" is wrong if anything was skipped silently.
"Tests pass" is wrong if any were skipped.
Default to surfacing uncertainty, not hiding it.

## single-file HTML 或 一頁式 HTML
當我提出這份內容產生一份 single-file HTML 或 一頁式 HTML 報告要求時,請依照下列要求生成:
- 深色主題、現代漸層、無外部相依
- 頂部執行摘要 + 狀態徽章(紅 / 黃 / 綠)
- 內嵌 SVG 圖表呈現重要數據
- 至少一個可篩選或可搜尋的清單
- 主要區塊使用可折疊 details 元件
- 包含一個含 checkbox 的行動清單
- sticky TOC 與閱讀進度條
- 互動以 vanilla JS 實作
最後將整份輸出包在 ```html``` 區塊中。

> 我們今天加了 Celery 跑背景任務，請更新 CLAUDE.md
  把 Celery 加入技術棧，並補上啟動 worker 的指令

> @src/services/order_service.py 這個檔案太大了（800 行），
  幫我拆成幾個小檔案。
  
  原則：
  1. 先確認所有測試通過
  2. 規劃拆分方案後給我確認
  3. 一次只動一塊，每動完跑一次測試
  4. 保持 API 不變（外部呼叫不能壞）
  5. 完成後跑完整測試套件

> 我剛接手這個專案，幫我：
  1. 畫出主要模組之間的關係
  2. 列出最重要的 5 個檔案
  3. 解釋整個請求的處理流程
  4. 找出可能的技術債或風險點

> 把 SQLAlchemy 從 1.4 升到 2.0。
  
  請：
  1. 先看 release notes 找出 breaking changes
  2. 列出我們專案中需要改的地方
  3. 一個個改、改完跑測試
  4. 全部過了再 commit

> 我們要用 TDD 開發購物車模組。遵循這個流程：
  
  1. 我給需求，你先寫測試
  2. 跑測試確認失敗
  3. 寫最小實作讓測試通過
  4. 跑測試確認綠燈
  5. 看是否需要重構
  
  測試框架：pytest
  專案結構：src/cart/ + tests/test_cart.py
  
  第一個功能：建立空購物車

from src.cart import Cart


def test_new_cart_is_empty():
    cart = Cart()
    assert cart.is_empty()
    assert cart.total() == 0
    assert len(cart.items) == 0

$ uv run pytest tests/test_cart.py -v

FAILED tests/test_cart.py::test_new_cart_is_empty
  ImportError: cannot import name 'Cart' from 'src.cart'

class Cart:
    def __init__(self):
        self.items = []
    
    def is_empty(self) -> bool:
        return len(self.items) == 0
    
    def total(self) -> float:
        return 0.0

> 下一個：加入商品到購物車，可以指定數量。
  繼續 TDD 流程。

> 為 Cart.add_item() 補上邊界與錯誤測試：
  - 加入負數量應該 raise ValueError
  - 加入價格為 0 的商品應該被允許
  - 加入相同商品應該累加數量
  - 加入後 is_empty() 必須回 False
  
  用 pytest.mark.parametrize 整理

> !uv run pytest --cov=src --cov-report=term-missing

> 看 coverage 報告，找出沒被覆蓋到的行，
  為這些情境補上測試

> 我改了三個檔案：修了 bug、加了新功能、更新文件。
  幫我分成三個獨立的 commit，每個都用 Conventional Commits 格式

feat(api): add user search endpoint
fix(auth): handle expired JWT correctly
docs(readme): update installation steps
refactor(db): extract query builder
test(cart): add edge cases for discount
chore(deps): bump fastapi to 0.110.0
perf(query): add index on user.email

main                # 生產環境
develop             # 整合 branch
feature/user-auth   # 新功能
fix/login-bug       # 修 bug
hotfix/crit-issue   # 緊急修復（直接 → main）
chore/upgrade-deps  # 維護任務
docs/api-spec       # 文件

> git pull 之後出現衝突，幫我看一下衝突的檔案，
  分析雙方的修改意圖，給我合理的合併建議

gh auth login

# 選 GitHub.com → HTTPS → 用瀏覽器登入
# 之後 Claude Code 就能用 gh 做所有 GitHub 操作了

> 列出所有開啟超過 90 天沒人回的 issue，
  讀內容後分類並加 label：
  - 已過時的 → close 並留言說明
  - 還有效但低優先 → 加 "stale" label
  - 重要的 → 加 "needs-attention" label

> 在 my-org 下所有 Python repo 中，
  找出還在用 pydantic v1 的，
  幫每個建立 issue 提醒升級

> 看新的 issue #156，分析它屬於哪個模組，
  到 CODEOWNERS 找對應的人，自動 assign 給他們

> /mcp add github

# 之後就能用更精細的操作：
> 在 PR #42 第 35 行加 review comment：「這裡可能有 N+1」

## 動機
解決 #42：使用者反映搜尋結果排序不一致。

## 變更內容
- 新增 `SearchService.rank_results()` 統一排序邏輯
- 將 `api/search.py` 改為呼叫 service
- 移除 `models/post.py` 中重複的排序程式碼
- 補上 12 個測試案例

## 測試
- ✅ pytest: 156 passed
- ✅ coverage: 87% (+2%)
- ✅ 手動測試 5 種搜尋情境

## Breaking Changes
無

## Checklist
- [x] 通過所有測試
- [x] 更新文件
- [x] 自我 review 完成
- [ ] 等待團隊 review

> /review

# 或更具體
> review 我這個 PR 的變更，特別注意：
  - 是否有 SQL injection 風險
  - error handling 是否完整
  - 命名是否符合專案慣例

> 幫我 review PR #156，給出建設性意見。
  寫成 GitHub review comments 格式，
  分成 must-fix、suggestion、nitpick 三類

> 看一下 PR #42 上 reviewer 的意見，
  分類處理：
  - 同意且簡單的：直接修
  - 同意但要討論的：先在 thread 回應
  - 不同意的：寫理由回應
  
  修改後重新跑測試、push、回 reviewer

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.11", "3.12"]
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Install uv
        uses: astral-sh/setup-uv@v3
      
      - name: Set up Python
        run: uv python install ${{ matrix.python-version }}
      
      - name: Install dependencies
        run: uv sync --all-extras --dev
      
      - name: Lint with ruff
        run: uv run ruff check .
      
      - name: Format check
        run: uv run ruff format --check .
      
      - name: Type check
        run: uv run mypy src/
      
      - name: Run tests
        run: uv run pytest --cov=src --cov-report=xml
      
      - name: Upload coverage
        uses: codecov/codecov-action@v4

> 幫我為這個專案建立 CI/CD：
  
  CI（push & PR）：
  - 跑 ruff、mypy、pytest
  - 測 Python 3.11 和 3.12
  - 上傳 coverage 到 Codecov
  
  CD（push 到 main 且 tag 為 v*）：
  - build Docker image
  - push 到 GHCR
  - 部署到 staging（手動觸發到 production）

name: PR Checks

on:
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: 檢查 commit 訊息格式
        uses: wagoid/commitlint-github-action@v6
      
      - name: 檢查 PR 標題
        uses: amannn/action-semantic-pull-request@v5
      
      - name: 標記檔案類型
        uses: actions/labeler@v5

name: Release to PyPI

on:
  push:
    tags: ['v*']

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
      
      - name: Build
        run: uv build
      
      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Docker image
        run: docker build -t myapp:${{ github.sha }} .
      
      - name: Push to registry
        run: |
          echo ${{ secrets.GITHUB_TOKEN }} | docker login ghcr.io -u ${{ github.actor }} --password-stdin
          docker push ghcr.io/${{ github.repository }}:${{ github.sha }}
      
      - name: Deploy to Kubernetes
        run: kubectl set image deployment/myapp myapp=ghcr.io/${{ github.repository }}:${{ github.sha }}

docs/
├── specs/
│   ├── user-auth/
│   │   ├── requirements.md
│   │   ├── design.md
│   │   └── tasks.md
│   ├── payment-flow/
│   │   ├── requirements.md
│   │   ├── design.md
│   │   └── tasks.md
│   └── search-feature/
│       └── ...
└── adr/                    # Architecture Decision Records
    ├── 001-use-postgres.md
    └── 002-jwt-vs-session.md

# Requirements: 使用者認證系統

## 背景與動機
目前系統沒有使用者認證，所有 API 都是公開的。
為了上線商業服務，需要實作完整的註冊/登入/權限管理。

## 目標使用者
- 一般訪客：可註冊新帳號
- 已註冊使用者：可登入、修改個資、登出
- 管理員：可管理其他使用者

## 功能需求

### FR-1: 註冊
**作為** 訪客  
**我希望** 用 email 和密碼註冊  
**這樣** 我就能擁有自己的帳號  

驗收標準：
- [ ] email 格式必須有效
- [ ] 密碼至少 8 字元，含大小寫與數字
- [ ] 同 email 不能重複註冊
- [ ] 註冊成功後自動寄送驗證信
- [ ] 未驗證 email 不能登入

### FR-2: 登入
**作為** 已驗證使用者  
**我希望** 用 email 和密碼登入  
**這樣** 我就能存取受保護的資源  

驗收標準：
- [ ] 正確憑證回傳 JWT（有效期 1 小時）
- [ ] 同時回傳 refresh token（有效期 30 天）
- [ ] 錯誤密碼 5 次後鎖定 15 分鐘
- [ ] 登入紀錄寫入 audit log

### FR-3: 權限管理
**作為** 管理員  
**我希望** 指派使用者角色（admin、editor、viewer）  
**這樣** 我能控制不同人的權限  

驗收標準：
- [ ] 三種角色預設權限明確定義
- [ ] 角色變更立即生效
- [ ] 變更紀錄保留

## 非功能需求

### NFR-1: 安全性
- 密碼用 bcrypt + salt，cost ≥ 12
- JWT 用 RS256 簽章
- 所有 auth endpoint 必須 HTTPS
- 敏感操作要寫 audit log

### NFR-2: 效能
- 登入回應時間 P95 ≤ 200ms
- 註冊回應時間 P95 ≤ 500ms（含寄信）
- 支援同時 1000 個併發登入

### NFR-3: 可靠性
- Email 寄送失敗不能讓註冊失敗（異步處理）
- DB 連線斷開要自動重試

## 範圍外（這次不做）
- 第三方登入（OAuth）
- 雙因素認證（2FA）
- Magic link 登入
- SSO 整合

## 相關文件
- Design: ./design.md
- Tasks: ./tasks.md
- ADR: ../../adr/003-jwt-strategy.md

> 我想做一個訂單管理系統。請以 SDD 流程幫我，
  先寫 requirements.md。
  
  背景：B2B SaaS，客戶下單後我們出貨。
  訪談我，把需求問清楚再寫。

# Design: 使用者認證系統

## 技術選型
- Web framework: FastAPI
- DB: PostgreSQL（既有）
- ORM: SQLAlchemy 2.0 (async)
- Password hashing: passlib + bcrypt
- JWT: python-jose
- Email: SendGrid via Celery（異步）
- Rate limiting: slowapi
- Audit log: 寫入既有的 audit_logs 表

## 架構圖
```
┌──────────┐    ┌────────────┐    ┌──────────┐
│  Client  │───▶│ Auth API   │───▶│ Auth     │
│          │    │ (FastAPI)  │    │ Service  │
└──────────┘    └────────────┘    └─────┬────┘
                                        │
                ┌───────────────────────┼───────────────────┐
                ▼                       ▼                   ▼
         ┌──────────┐           ┌──────────────┐    ┌──────────┐
         │  Users   │           │ Email Queue  │    │  Redis   │
         │   Table  │           │  (Celery)    │    │ (sessions│
         └──────────┘           └──────────────┘    │  + rate) │
                                                    └──────────┘
```

## 資料模型
### users 表
| 欄位 | 型別 | 說明 |
|------|------|------|
| id | UUID PK | |
| email | VARCHAR(255) UNIQUE | |
| password_hash | VARCHAR(255) | bcrypt |
| email_verified | BOOLEAN | 預設 False |
| role | ENUM | admin / editor / viewer |
| failed_login_count | INTEGER | 預設 0 |
| locked_until | TIMESTAMP NULL | |
| created_at | TIMESTAMP | |
| updated_at | TIMESTAMP | |

### audit_logs 表（既有）
寫入 type 為 `auth.login.success`、`auth.login.failure`、`auth.register` 的事件

## API 設計

### POST /api/v1/auth/register
Request:
```json
{
  "email": "user@example.com",
  "password": "SecurePass123",
  "name": "Alice"
}
```
Response 201:
```json
{
  "user_id": "uuid",
  "email": "user@example.com",
  "verification_email_sent": true
}
```
Errors:
- 400: 格式錯誤
- 409: email 已存在
- 422: 密碼強度不足

### POST /api/v1/auth/login
（類似格式...）

## 流程圖：登入流程
```
Client → API: POST /login
API → Service: authenticate(email, password)
Service → DB: 查 user
  ├─ 不存在 → 回 401
  ├─ 被鎖定 → 回 423
  └─ 找到 user:
       Service: bcrypt.verify(password, hash)
         ├─ 失敗 → failed_count++, 寫 audit, 回 401
         └─ 成功 → 產生 JWT + refresh token, 寫 audit, 回 200
```

## 錯誤處理策略
| HTTP code | 情境 | Body |
|-----------|------|------|
| 400 | 請求格式錯誤 | { "error": "invalid_request", "details": ... } |
| 401 | 認證失敗 | { "error": "invalid_credentials" } |
| 422 | 密碼強度不足 | { "error": "weak_password", "requirements": [...] } |
| 423 | 帳號鎖定 | { "error": "account_locked", "retry_after": 900 } |
| 500 | 內部錯誤 | { "error": "internal_error", "trace_id": "..." } |

## 安全考量
- 密碼絕不出現在 log 或回應
- bcrypt cost = 12（升級時要遷移）
- JWT secret 從 vault 讀取，不放 env
- Rate limit：登入 5 次/分鐘/IP
- 註冊：3 次/小時/IP

## 測試策略
- 單元測試：service 層（mock DB）
- 整合測試：完整 API 流程（test DB）
- 安全測試：SQL injection、密碼洩漏、JWT 偽造
- 負載測試：1000 併發登入

> 根據 @docs/specs/user-auth/requirements.md，
  幫我寫 design.md。
  
  限制：
  - 必須符合既有架構（FastAPI + PG + Celery）
  - 不引入新的基礎設施
  - 安全優先於開發速度
  
  寫之前先列出設計決策，跟我討論再開始

# ADR-003: 認證用 JWT 而非 Session

**Date**: 2026-05-22
**Status**: Accepted

## Context
需要決定如何維持使用者登入狀態。
選項：Session（state on server）vs JWT（stateless）

## Decision
採用 JWT，搭配 Refresh Token 機制。

## Consequences
✅ 好處：
- 無狀態，水平擴展容易
- 不需 Redis 存 session
- 跨服務驗證簡單

❌ 壞處：
- 無法主動撤銷（用 short TTL + refresh 緩解）
- Token 體積較大
- 需要管理 secret rotation

## Alternatives Considered
- Session in Redis：擴展性夠但增加基礎設施依賴
- Session in DB：每次請求查 DB，效能差

# Tasks: 使用者認證系統

## Phase 1: 基礎建設

### T-1.1: 建立 users 表 migration
- 依賴：無
- 估時：30 分鐘
- 步驟：
  1. 在 alembic 建 migration
  2. 包含所有設計文件中的欄位
  3. 加 index on email
  4. 跑 migration 確認
- 驗收：
  - [ ] migration up/down 都能成功
  - [ ] 表結構符合 design.md

### T-1.2: 設定 JWT 相關套件
- 依賴：無
- 估時：20 分鐘
- 步驟：
  1. uv add python-jose passlib bcrypt
  2. 建 src/auth/config.py 讀 JWT secret
  3. 建 src/auth/security.py 放 hash/verify/jwt 函式
- 驗收：
  - [ ] 套件已加入 pyproject.toml
  - [ ] secret 從 env 讀取，無預設值

## Phase 2: Service 層

### T-2.1: AuthService.register()
- 依賴：T-1.1, T-1.2
- 估時：1 小時
- 步驟：
  1. 先寫測試：tests/services/test_auth.py
     - 成功註冊
     - email 重複
     - 弱密碼
  2. 實作 register 方法
  3. 整合 Celery 寄驗證信
- 驗收：
  - [ ] 所有測試通過
  - [ ] coverage ≥ 90%

### T-2.2: AuthService.login()
- 依賴：T-2.1
- 估時：1.5 小時
- 步驟：
  1. 寫測試
  2. 實作密碼驗證
  3. 實作鎖定邏輯
  4. 產生 JWT + Refresh Token
  5. 寫 audit log
- 驗收：
  - [ ] 所有測試通過
  - [ ] 鎖定 5 次後 15 分鐘

## Phase 3: API 層

### T-3.1: POST /auth/register endpoint
- 依賴：T-2.1
- 估時：45 分鐘
- 步驟：
  1. 建 schemas/auth.py（Pydantic）
  2. 建 api/v1/auth.py
  3. 寫整合測試
- 驗收：
  - [ ] 各種錯誤情境回正確 HTTP code
  - [ ] OpenAPI doc 正確顯示

### T-3.2: POST /auth/login endpoint
- 依賴：T-2.2
- 估時：45 分鐘
（類似格式...）

## Phase 4: 整合與部署

### T-4.1: Rate Limiting
- 依賴：T-3.1, T-3.2
- 估時：30 分鐘

### T-4.2: Auth Middleware
- 依賴：T-3.2
- 估時：1 小時
- 用於保護其他 API

### T-4.3: 文件與 Postman collection
- 依賴：T-4.2
- 估時：1 小時

## 預估總時程：6-8 小時

> 根據 @docs/specs/user-auth/design.md，
  拆成 tasks.md。
  
  原則：
  1. 每個任務 ≤ 2 小時工作量
  2. 標出依賴關係
  3. 每個任務都包含「寫測試」步驟
  4. 驗收條件用 checkbox 格式
  5. 按 phase 分組（基礎建設 → service → API → 整合）

> 開始執行 @docs/specs/user-auth/tasks.md。
  
  從 T-1.1 開始。每完成一個任務：
  1. 更新 tasks.md 的 checkbox
  2. commit
  3. 暫停讓我確認
  4. 我說 next 再做下一個

> 同時派出三個 sub-agent：
  - Agent 1: 做 T-1.1（建 migration）
  - Agent 2: 做 T-1.2（設定 JWT 套件）
  - Agent 3: 寫 schemas/auth.py（不依賴前兩者）
  
  完成後彙整結果給我

> /agents

選 1: 建立新代理

精靈會問你：
  1. 代理名稱：code-reviewer
  2. 描述：當需要 review 程式碼變更時自動觸發
  3. System prompt：（你可自訂或讓 Claude 幫你寫）
  4. 可用工具：Read, Grep, Glob, Bash(git diff)
  5. 儲存到：./.claude/agents/code-reviewer.md

---
name: code-reviewer
description: 自動觸發於檔案編輯後，做 code review
tools: Read, Grep, Glob, Bash
---

你是一位資深 Python code reviewer。

審查重點（依優先順序）：
1. 安全性：SQL injection、XSS、密碼處理、secret 洩漏
2. 正確性：邊界條件、錯誤處理、競爭條件
3. 效能：N+1 查詢、不必要的迴圈、記憶體洩漏
4. 可維護性：命名、結構、過長函式

回報格式：
🔴 Must fix：（必須修正的問題）
⚠️ Should consider：（建議改善）
💡 Nice to have：（細節優化）

每個問題給出：
- 檔案 + 行號
- 為什麼是問題
- 建議的修改方式
- 範例程式碼

簡潔但完整。不要逐字罵人。

---
name: test-writer
description: 撰寫 pytest 測試，包含單元、整合、邊界案例
tools: Read, Write, Edit, Bash
---

你是 Python 測試專家，專精 pytest。

撰寫測試時必須：
- 用 fixtures 而非 setUp
- 用 parametrize 涵蓋多種輸入
- 命名格式：test_<function>_<scenario>_<expected>
- 一個測試只驗一件事
- Mock 外部依賴（DB、API、檔案系統）
- 包含 happy path + edge case + error path
- 用 pytest.raises 驗證例外

完成後跑測試確認都通過。

---
name: docs-writer
description: 撰寫與更新技術文件、docstring、README
tools: Read, Write, Edit, Grep
---

你是技術寫作專家。

撰寫原則：
- 開門見山，先講重點
- 用「為什麼」而非「是什麼」
- 範例程式碼必須能直接執行
- 避免「顯而易見」、「簡單來說」等空話
- API 文件用 Google style docstring
- README 結構：簡介 → 安裝 → 快速開始 → 進階 → 貢獻

---
name: debugger
description: 系統化地除錯複雜問題
tools: Read, Grep, Bash, Edit
---

你是除錯專家。遇到 bug 時遵循：

1. 重現：先寫出能穩定重現 bug 的最小案例
2. 隔離：用二分法縮小問題範圍
3. 假設：列出 3 個可能的根因
4. 驗證：用 print/log/debugger 確認哪個對
5. 修復：先寫測試保證 bug 不再出現，再修
6. 回報：根因 + 解法 + 預防建議

不要猜。每個步驟都要有證據支持。

---
name: security-auditor
description: 安全漏洞掃描與稽核
tools: Read, Grep, Glob, Bash
---

你是應用程式安全專家（OWASP Top 10 為基準）。

掃描檢查項目：
- SQL injection（搜尋字串拼接的 SQL）
- XSS（未經 escape 的輸出）
- Hardcoded secrets（API key、密碼、token）
- 不安全的反序列化
- 認證/授權漏洞
- 敏感資訊 log
- 不安全的依賴（已知 CVE）
- CSRF 缺失
- Open redirect

每個發現給：嚴重度（Critical/High/Med/Low）+ CWE 編號 + 修復建議

# 自動觸發（依 description）
> 我剛改了 auth.py，請 review 一下

# 明確呼叫
> 請 code-reviewer 看 @src/api/users.py

# 一次叫多個
> 同時派出 test-writer 寫測試、docs-writer 寫文件、
  security-auditor 做安全稽核

> 我們要把整個專案從 SQLAlchemy 1.4 升到 2.0。
  
  你做 orchestrator，派出 4 個 worker：
  - Worker A: 升級 src/models/
  - Worker B: 升級 src/services/
  - Worker C: 升級 tests/
  - Worker D: 更新文件
  
  每個 worker 完成後回報，你彙整所有變更給我確認。

> 用 pipeline 模式做這個功能：
  
  1. analyst 代理：訪談我，產出 requirements.md
  2. architect 代理：根據需求產出 design.md
  3. task-planner 代理：把設計拆成 tasks.md
  4. implementer 代理：執行每個任務
  5. reviewer 代理：最終 code review
  
  每階段完成都暫停讓我確認

> 我們要選後端框架：FastAPI vs Django vs Flask
  
  派出三個代理同時評估，每個從不同角度：
  - performance-expert：從效能與擴展性
  - dx-expert：從開發者體驗與學習曲線
  - ops-expert：從部署、監控、生態系
  
  最後請你彙整三方意見，給出綜合建議

> 開發「訂單退款」功能，用混合模式：
  
  Phase 1（Pipeline）：
  - analyst → architect → task-planner
  
  Phase 2（Orchestrator-Worker，平行）：
  - 4 個 implementer 各自實作不同 layer
  
  Phase 3（Debate）：
  - security-auditor + performance-expert + reviewer
    同時 review，給多角度意見
  
  Phase 4（Pipeline）：
  - bug-fixer → docs-writer → release-manager
  
  你做最高層的協調者，每個 phase 完成後跟我同步進度

> /mcp add

選擇 server 類型：
  1. 從目錄選（推薦官方 server）
  2. 手動輸入 URL
  3. 從本地路徑

依精靈填入：
  - Server 名稱
  - URL 或 command
  - 認證資訊（Token / OAuth）
  - 範圍（專案級 / 使用者級）

# 加入 GitHub MCP
claude mcp add github --transport http --url https://api.githubcopilot.com/mcp/

# 加入 PostgreSQL MCP
claude mcp add postgres --command "npx @modelcontextprotocol/server-postgres" \
  --env DATABASE_URL="postgresql://..."

{
  "servers": {
    "github": {
      "transport": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "auth": "oauth"
    },
    "postgres": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "transport": "http",
      "url": "https://mcp.sentry.dev",
      "auth": "oauth"
    }
  }
}

> 讀 Figma 檔案 ABC123，
  把「Login Page」frame 轉成 React + Tailwind 元件，
  存到 src/pages/Login.tsx

> 連 production DB（read-only），
  找出過去 7 天訂單金額最大的 10 個客戶，
  我要他們的 email、訂單數、總金額

> 從 Sentry 找今天最頻繁的 5 個錯誤，
  分析 stack trace，建立對應的 GitHub issue，
  並嘗試提出修復建議

from mcp.server import Server
from mcp.types import Tool, TextContent

app = Server("my-tools")

@app.list_tools()
async def list_tools():
    return [
        Tool(
            name="get_user_stats",
            description="取得使用者統計資料",
            inputSchema={"type": "object", "properties": {...}},
        )
    ]

@app.call_tool()
async def call_tool(name: str, args: dict):
    if name == "get_user_stats":
        result = await fetch_stats(args)
        return [TextContent(type="text", text=str(result))]

if __name__ == "__main__":
    app.run()

{
  "hooks": {
    "post-edit": [
      {
        "matcher": "*.py",
        "command": "uv run ruff format $CLAUDE_FILE && uv run ruff check --fix $CLAUDE_FILE",
        "description": "格式化並修 lint"
      },
      {
        "matcher": "*.{ts,tsx,js,jsx}",
        "command": "npx prettier --write $CLAUDE_FILE"
      }
    ],
    "pre-tool-use": [
      {
        "matcher": "Bash(rm *)",
        "command": "echo 'BLOCKED: rm command' && exit 1",
        "description": "禁止任何 rm 指令"
      }
    ],
    "session-start": [
      {
        "command": "./.claude/scripts/load-context.sh",
        "description": "載入專案最新狀態"
      }
    ]
  }
}

{
  "hooks": {
    "post-edit": [
      {
        "matcher": "*.py",
        "command": "uv run ruff format $CLAUDE_FILE"
      }
    ]
  }
}

{
  "hooks": {
    "post-edit": [
      {
        "matcher": "src/**/*.py",
        "command": "uv run pytest tests/ --no-header -q",
        "on_failure": "notify"
      }
    ]
  }
}

{
  "hooks": {
    "pre-commit": [
      {
        "command": "./.claude/scripts/scan-secrets.sh",
        "description": "掃描 secrets，找到就阻止 commit",
        "block_on_failure": true
      }
    ]
  }
}

{
  "hooks": {
    "session-end": [
      {
        "command": "./.claude/scripts/save-checkpoint.sh",
        "description": "如有未 commit 變更，建立 WIP commit"
      }
    ]
  }
}

#!/bin/bash
# 掃描即將 commit 的內容，找出疑似 secret

if git diff --cached | grep -iE '(api_key|secret|password|token).{0,5}=.{0,5}["\047][^"\047]{16,}'; then
    echo "🚨 發現疑似 secret，請檢查上述內容！"
    exit 1
fi

echo "✓ 沒有發現 secret"
exit 0

---
name: deploy
description: 部署到 staging 環境
arguments:
  - name: target
    description: 目標環境（staging/prod）
    default: staging
---

執行以下步驟部署到 {{target}} 環境：

1. **檢查前置條件**
   - 確認在 main branch 或受信任的 release branch
   - 確認所有 CI 都通過
   - 確認沒有未 commit 的變更

2. **跑完整測試**
   ```bash
   uv run pytest --cov=src
   ```
   如果失敗就停止。

3. **建立 Docker image**
   ```bash
   docker build -t myapp:$(git rev-parse --short HEAD) .
   ```

4. **推送到 registry**
   ```bash
   docker push myapp:$(git rev-parse --short HEAD)
   ```

5. **更新 Kubernetes deployment**
   ```bash
   kubectl set image deployment/myapp \
     myapp=myapp:$(git rev-parse --short HEAD) \
     -n {{target}}
   ```

6. **驗證部署**
   等 60 秒，然後檢查 pods 狀態與 health endpoint。

7. **回報結果**
   - 部署的 commit hash
   - 環境
   - 健康檢查結果
   - 監控連結

> /skill deploy

# 或帶參數
> /skill deploy target=prod

# 也可用自然語言觸發
> 幫我部署到 staging

---
name: onboard
description: 新人 onboarding 互動教學
---

歡迎新加入！我會帶你熟悉這個專案。

1. 先讀 @README.md @CLAUDE.md @CONTRIBUTING.md
2. 列出專案 5 個最重要的檔案
3. 解釋整體架構
4. 跑一次完整的 dev 環境啟動流程
5. 問新人想從哪個模組開始
6. 安排第一個 onboarding task（從 good-first-issue label 找）

---
name: release
description: 建立新版本（含 changelog、tag、release notes）
arguments:
  - name: bump
    description: major / minor / patch
    default: patch
---

1. 確認在 main、無未 commit 變更
2. 跑完整測試
3. 從上次 tag 到現在的 commit 整理成 changelog（依 Conventional Commits 分類）
4. 更新 pyproject.toml 版號（依 {{bump}}）
5. 更新 CHANGELOG.md
6. Commit「chore(release): vX.Y.Z」
7. 建立 git tag
8. Push 包含 tag
9. 用 gh release create 建立 GitHub release
10. 回報新版號與 release 連結

---
name: bug-triage
description: 系統化分析新進 bug
arguments:
  - name: issue
    description: GitHub issue 編號
    required: true
---

針對 issue #{{issue}}：

1. 讀 issue 內容與所有評論
2. 嘗試在本地重現
3. 如能重現：
   - 寫出最小重現範例
   - 找出可能根因
   - 寫對應的失敗測試
   - 評估嚴重度（P0/P1/P2/P3）
   - 估修復時間
4. 如不能重現：
   - 留言請報告者補資訊
   - 標 needs-info label
5. 更新 issue：加 label、assign、提出修復計畫

---
name: upgrade-deps
description: 升級所有依賴並測試
---

1. 列出 pyproject.toml 中所有依賴的目前版本與最新版本
2. 分類：
   - patch 升級（自動執行）
   - minor 升級（執行，注意 release notes）
   - major 升級（先問人，不要直接做）
3. 一次升一個套件：
   - 升級
   - 跑完整測試
   - 過了就 commit，沒過就 revert 並回報
4. 全部完成後彙整：升了哪些、哪些有 breaking change

---
name: full-feature
description: 從需求到部署的完整功能開發
---

1. 派出 analyst 代理蒐集需求 → requirements.md
2. 派出 architect 代理 → design.md
3. 派出 task-planner 代理 → tasks.md
4. 派出 implementer 代理依任務實作
5. 派出 test-writer 代理補測試
6. 派出 reviewer 代理做 review
7. 派出 docs-writer 代理更新文件
8. 呼叫 /skill deploy 部署到 staging

/autopilot "build a REST API for managing tasks"

/team 3:executor "fix all TypeScript errors"

omc team 2:codex "review auth module"
omc team 2:gemini "redesign UI components"
omc team 1:claude "implement the payment flow"

cargo install --git https://github.com/lazy-poet/claude-img

rm ~/.local/bin/claude-img
rm -rf ~/.claude/skills/img

Remove-Item "$env:LOCALAPPDATA\Programs\claude-img" -Recurse
Remove-Item "$env:USERPROFILE\.claude\skills\img" -Recurse

/plugin marketplace add anthropics/skills
/plugin install superpowers

git clone https://github.com/obra/superpowers ~/.claude/skills/superpowers
cd ~/.claude/skills/superpowers
./install

/plugin install claude-mem

/plugin install connect-apps

npx antigravity-awesome-skills --claude
npx antigravity-awesome-skills --cursor
npx antigravity-awesome-skills --gemini

---
name: my-awesome-skill
description: 一句話描述這個 skill 做什麼
version: 1.0.0
author: Your Name
tags: [python, testing, automation]
triggers:
  - "幫我寫測試"
  - "add tests"
  - "pytest"
arguments:
  - name: target_file
    description: 要寫測試的目標檔案
    required: true
tools: Read, Write, Edit, Bash
---

# My Awesome Skill

你是測試專家,當使用者要寫測試時:

1. 先讀 {{target_file}}
2. 識別公開的 function / class
3. 為每個寫至少 3 個測試(happy / edge / error)
4. 用 pytest fixtures,避免重複
5. 完成後跑測試確認都過

絕對遵守:
- 不修改原本的 production code
- 不要 mock 不需要 mock 的東西
- 測試名稱要 self-documenting

claude -p "列出專案中所有 TODO 註解並彙整成清單"

name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Install Claude Code
        run: curl -fsSL https://claude.ai/install.sh | bash
      
      - name: Review PR
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          claude -p "分析此 PR 的變更（diff: $(git diff origin/main)），
          
          給出 code review，包含：
          - 🔴 Must fix（必須修正）
          - ⚠️ Suggestions（建議改善）
          - 💡 Nitpicks（細節）
          
          以 GitHub review comment 格式回應，
          用 gh pr review --comment 提交" \
            --max-turns 20 \
            --allowed-tools "Read,Grep,Bash"

name: Auto-fix Lints

on:
  workflow_dispatch:    # 手動觸發
  schedule:
    - cron: '0 2 * * *'   # 每日凌晨 2 點

jobs:
  fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
      - run: uv sync
      
      - name: Install Claude
        run: curl -fsSL https://claude.ai/install.sh | bash
      
      - name: Auto-fix
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "跑 ruff check，找出所有可修復的錯誤，修掉。
          不要改變任何邏輯，只做 ruff 建議的修正。
          完成後再跑一次 ruff 確認都過了。" \
            --max-turns 10
      
      - name: Create PR
        uses: peter-evans/create-pull-request@v6
        with:
          commit-message: "chore: auto-fix lint issues"
          title: "🤖 Auto-fix lint issues"
          branch: chore/auto-fix-lints

#!/bin/bash
# 把所有 Python 檔案的 print() 改成 logging

for file in $(find src -name "*.py"); do
    echo "Processing $file..."
    
    claude -p "檔案 $file 中的所有 print() 都改成 logging.info()。
    保留原本要印的訊息。如果有 print(..., file=sys.stderr) 改成 logging.error()" \
        --max-turns 5 \
        --allowed-tools "Read,Edit" \
        --output-format json > "logs/$(basename $file).log"
done

result=$(claude -p "列出所有 TODO" --output-format json)

# 取最終訊息
echo "$result" | jq '.final_response'

# 取 token 使用量
echo "$result" | jq '.usage.total_tokens'