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

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

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

# 🟧 Claude Code
irm https://claude.ai/install.ps1 | iex
# 或 winget install Anthropic.ClaudeCode

# 🟢 Codex CLI（需先安裝 Node.js）
npm install -g @openai/codex

# 🔵 Antigravity CLI
irm https://antigravity.google/cli/install.ps1 | iex

claude                 # 🟧 互動模式（首次啟動會引導登入）
codex                  # 🟢 互動模式
agy                    # 🔵 互動模式

# 認證（首次使用）
claude auth login      # 或在 Claude Code 對話中輸入 /login
codex login            # 或首次啟動時選 Sign in with ChatGPT
# Antigravity：首次啟動時用 Google 帳號登入

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

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

/ask codex "我們的資料庫應該選 PostgreSQL 還是 MongoDB?"
/ask antigravity "我們的資料庫應該選 PostgreSQL 還是 MongoDB?"
# 再請 Claude 統整兩方意見並給出建議

agy plugin import gemini

npm install -g @openai/codex@latest

claude update
# 原生安裝器預設會在背景自動更新；Homebrew / WinGet 則用 brew upgrade / winget upgrade

# 列出所有指令與說明
> /help

# 輸入 / 後繼續打字，選單會即時篩選（例如找 model 相關指令）
> /mod

# 一般 compact
> /compact

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

> /btw 剛剛那個設定檔叫什麼名字？

# 打開模型選單（支援的模型可用 ← → 調整 effort）
> /model

# 直接用別名切換
> /model opus
> /model fable

# 用完整模型 ID 鎖定特定版本
> /model claude-opus-5-5

# 啟動時就指定（在終端機執行）
claude --model sonnet

# 不帶參數：打開滑桿
> /effort

# 直接指定：low / medium / high / xhigh / max
> /effort high

# 清除你存的設定，回到模型預設值
> /effort auto

# 打開設定介面
> /config

# 直接設定
> /config theme=dark
> /config model=sonnet

# 列出可用的 key
> /config --help

# allow：完全符合這個指令
Bash(npm run build)

# allow：npm run 開頭的任何指令
Bash(npm run *)

# ask：git push 前一定要問我
Bash(git push *)

> /usage

Total cost:            $0.55
Total duration (API):  6m 20s
Total duration (wall): 6h 33m 10s
Total code changes:    0 lines added, 0 lines removed
Usage by model:
   claude-sonnet-5-5:  1.2k input, 5.3k output, 940.0k cache read, 50.0k cache write ($0.55)

# 列出可用風格並標示目前的風格
> /output-style

# 切換（不分大小寫）
> /output-style learning

> /theme
> /config theme=dark

> /init

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

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

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

> 說明一下 @src/components 的結構

# 對話中加入
> /add-dir ~/projects/shared-lib

# 或啟動時就加入（在終端機執行）
claude --add-dir ~/projects/shared-lib

> /memory

# 存進 auto memory
> 記住：這個專案一律用 pnpm，不要用 npm

# 寫進 CLAUDE.md，跟團隊共用
> 把「所有 API 路由前綴都是 /api/v2」加到 CLAUDE.md

> 在 CLAUDE.md 註明：不要修改 legacy/ 資料夾的程式碼

> 幫我建一個 code-reviewer 子代理，只能用 Read、Grep、Glob，
  專門檢查安全性和效能問題，存到 .claude/agents/

# 打開伺服器清單：看連線狀態、做 OAuth 驗證
> /mcp

# 重新連線某個（或全部）伺服器
> /mcp reconnect github
> /mcp reconnect all

# 暫時停用／啟用
> /mcp disable figma
> /mcp enable figma

# Add a remote HTTP server
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# List / remove servers
claude mcp list
claude mcp remove sentry

# 列出可用 skills（可打字篩選、調整是否顯示）
> /skills

# 直接呼叫自訂 skill：.claude/skills/deploy/SKILL.md
> /deploy

# 剛新增或修改 skill 檔案後重新掃描
> /reload-skills

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

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

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

> 幫我 commit 目前的變更，訊息用 Conventional Commits 格式

> 先用 /diff 讓我看一下改了什麼，沒問題再 commit

> 推上去並開一個 PR，描述寫清楚改了什麼、怎麼測試

> 看一下 PR #42 有哪些 review 留言，逐一處理

> 列出目前開著的 issue，挑跟登入有關的

> 找 issue 123，分析根因並幫我修復

# 也可以用 ! 自己跑 gh 指令，輸出會留在對話中
> !gh pr list

# 檢查目前的變更
> /code-review

# 用較高 effort 審查 PR #1234
> /code-review high 1234

# 審查並直接修正
> /code-review --fix

# 安全性專門審查（比對目前分支與 origin 預設分支）
> /security-review

> /install-github-app

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

# 存進 Claude 的 auto memory
> 記住：這個專案用 black 格式化，行寬 88

# 寫進 CLAUDE.md（或用 /memory 自己編輯）
> 把「用 black 格式化，行寬 88」加到專案的 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

按 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"
  }
}

/ide

┌──────────────┬──────────────────────────────┐
│              │                              │
│  📁 檔案     │  📝 程式碼編輯區             │
│  總管        │                              │
│              │                              │
│              ├──────────────────────────────┤
│              │                              │
│              │  $ 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": [
    "anthropic.claude-code",
    "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.13",

  "features": {
    "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
  },

  "customizations": {
    "vscode": {
      "extensions": [
        "ms-ceintl.vscode-language-pack-zh-hant",
        "ms-python.python",
        "charliermarsh.ruff",
        "cweijan.vscode-office"
      ]
    }
  }
}

my-project/
├── .claude/
│   ├── settings.json        # 團隊共用設定：權限、hooks、環境變數（commit）
│   ├── settings.local.json  # 個人本地設定（不 commit）
│   ├── rules/               # 依主題拆分的規則 *.md（可用 paths 限定檔案範圍）
│   ├── skills/              # 專案技能，每個技能一個資料夾含 SKILL.md
│   └── agents/              # 子代理定義 *.md
├── .mcp.json                # 專案層級 MCP 伺服器設定（commit）
├── 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 看；也可放在 .claude/CLAUDE.md）
├── pyproject.toml
├── .gitignore
└── README.md

---
paths:
  - "src/my_project/api/**/*.py"
---

# API Rules
- Every endpoint validates input with a Pydantic schema
- Return errors in the shared error response format

See @README.md for the project overview and @docs/design.md for architecture.

## Personal preferences
- @~/.claude/my-project-instructions.md

# Project: My FastAPI Service

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

## 技術棧
- Python 3.12+
- FastAPI 0.115+
- 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 — Keep context lean

Read only the files the task needs; search before opening whole directories.
When a session gets long or switches topics, summarize progress and suggest /clear.
Never paste large logs back verbatim — quote the relevant lines.

## 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 給他們

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

> 在 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

> /code-review          # review the current diff for correctness bugs (/review is an alias)
> /code-review 156      # review PR #156
> /security-review      # check the branch diff for security issues

# 或更具體
> 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.12", "3.13"]

    steps:
      - uses: actions/checkout@v6

      - name: Install uv
        uses: astral-sh/setup-uv@v10.2.0  # setup-uv has no floating major tag; pin a full version
      
      - 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@v7
        with:
          token: ${{ secrets.CODECOV_TOKEN }}

> 幫我為這個專案建立 CI/CD：
  
  CI（push & PR）：
  - 跑 ruff、mypy、pytest
  - 測 Python 3.12 和 3.13
  - 上傳 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@v6
        with:
          fetch-depth: 0  # commitlint needs the full history

      - name: 檢查 commit 訊息格式
        uses: wagoid/commitlint-github-action@v6

      - name: 檢查 PR 標題
        uses: amannn/action-semantic-pull-request@v6
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: 標記檔案類型  # requires .github/labeler.yml
        uses: actions/labeler@v7

name: Release to PyPI

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

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    steps:
      - uses: actions/checkout@v6
      - uses: astral-sh/setup-uv@v10.2.0

      - 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
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v6

      - name: Build Docker image
        run: docker build -t ghcr.io/${{ github.repository }}:${{ 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（不依賴前兩者）
  
  完成後彙整結果給我

> 幫我在 .claude/agents/ 建立一個 code-reviewer 子代理，
  專門 review 程式碼變更，只能讀檔不能改檔，使用 Sonnet 模型

---
name: code-reviewer
description: 資深 code reviewer。程式碼有變更後主動使用，檢查安全性、正確性與可維護性。
tools: Read, Grep, Glob, Bash
model: sonnet
color: blue
---

你是一位資深 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 編號 + 修復建議

# 1. 自動委派（Claude 依 description 判斷）
> 我剛改了 auth.py，請 review 一下

# 2. 用自然語言指名
> 用 code-reviewer 子代理看 @src/api/users.py

# 3. @ 提及：保證一定派給這個代理（輸入 @ 後從選單挑選）
> @agent-code-reviewer 看一下 auth 的變更

# 4. 一次派出多個（可平行執行）
> 同時派出 test-writer 寫測試、docs-writer 寫文件、
  security-auditor 做安全稽核

# Run the whole session as the code-reviewer agent
claude --agent code-reviewer

# Define agents on the fly with JSON (not saved to disk)
claude --agents '{
  "reviewer": {
    "description": "Reviews code after changes",
    "prompt": "You are a senior code reviewer.",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}'

> 我們要把整個專案從 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 完成後跟我同步進度

# Start a session in an isolated worktree at .claude/worktrees/feature-auth
claude --worktree feature-auth

# Short form; omit the name to get a generated one
claude -w

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

> 派出三個 teammates 一起 review PR #142：
  一個看安全性、一個看效能、一個檢查測試覆蓋率，
  各自回報後由你彙整

# Remote HTTP server: claude mcp add --transport http <name> <url>
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Remote server that needs a header (e.g. GitHub with a personal access token)
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

# Local stdio server: everything after -- is the command that starts the server
claude mcp add playwright -- npx -y @playwright/mcp@latest

# Local stdio server with environment variables (-e / --env)
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY airtable -- npx -y airtable-mcp-server

# Share with the team via .mcp.json
claude mcp add --scope project --transport http sentry https://mcp.sentry.dev/mcp

# Manage servers
claude mcp list            # list servers and their health
claude mcp get sentry      # show details for one server
claude mcp remove sentry   # remove a server

{
  "mcpServers": {
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}"
      }
    },
    "airtable": {
      "command": "npx",
      "args": ["-y", "airtable-mcp-server"],
      "env": {
        "AIRTABLE_API_KEY": "${AIRTABLE_API_KEY}"
      }
    }
  }
}

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

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

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

uv add "mcp[cli]"      # or: pip install "mcp[cli]"

from mcp.server import MCPServer

mcp = MCPServer("my-tools")


@mcp.tool()
def get_user_stats(user_id: int) -> dict:
    """Return order statistics for a user."""
    # Replace with a real database / API lookup
    return {"user_id": user_id, "orders": 42, "total": 1234.5}


if __name__ == "__main__":
    mcp.run()  # stdio transport by default

# Test it in the MCP Inspector
uv run mcp dev my_mcp.py

# Register it with Claude Code (stdio)
claude mcp add my-tools -- uv run my_mcp.py

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format-python.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# PostToolUse hook: format edited Python files with ruff
file_path=$(jq -r '.tool_input.file_path // empty')

if [[ "$file_path" == *.py ]]; then
  uv run ruff format "$file_path"
  uv run ruff check --fix "$file_path"
fi
exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous.sh" }
        ]
      }
    ]
  }
}

#!/bin/bash
# PreToolUse hook: block destructive shell commands
command=$(jq -r '.tool_input.command // empty')

if echo "$command" | grep -qE 'rm -rf|git push --force|DROP TABLE'; then
  echo "Blocked by hook: destructive command is not allowed" >&2
  exit 2   # exit 2 = block the tool call, stderr is shown to Claude
fi
exit 0

#!/bin/bash
# PreToolUse hook (matcher: "Edit|Write"): refuse edits to secret files
file_path=$(jq -r '.tool_input.file_path // empty')

case "$file_path" in
  *.env|*.env.*|*.pem|*id_rsa*)
    echo "Blocked: $file_path is a protected file" >&2
    exit 2 ;;
esac
exit 0

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code 需要你的注意\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          { "type": "command", "command": "git status --short && git log --oneline -5" }
        ]
      }
    ]
  }
}

.claude/skills/deploy/
├── SKILL.md          # required: frontmatter + instructions
├── checklist.md      # optional: loaded only when referenced
└── scripts/
    └── healthcheck.sh

---
name: deploy
description: 部署應用程式到 staging 或 production 環境
argument-hint: [staging|prod]
disable-model-invocation: true
---

執行以下步驟部署到 $ARGUMENTS 環境（沒指定就用 staging）：

1. **檢查前置條件**
   - 確認在 main branch 或受信任的 release branch
   - 確認所有 CI 都通過
   - 確認沒有未 commit 的變更
   - 逐項核對 [checklist.md](checklist.md)

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

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

4. **更新 Kubernetes deployment**
   ```bash
   kubectl set image deployment/myapp \
     myapp=myapp:$(git rev-parse --short HEAD) \
     -n <目標環境>
   ```

5. **驗證部署**：執行 `scripts/healthcheck.sh` 檢查 pods 與 health endpoint

6. **回報結果**：commit hash、環境、健康檢查結果、監控連結

# 直接用斜線呼叫（名稱就是 skill 名稱）
> /deploy

# 後面的文字會代入 SKILL.md 裡的 $ARGUMENTS
> /deploy prod

# 沒設 disable-model-invocation 的 skill，Claude 也會依 description 自動使用
> 幫我看一下這個 PR 改了什麼

---
name: onboard
description: 帶新加入的成員認識這個專案。新人問「從哪裡開始」或要求專案導覽時使用。
---

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

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）
argument-hint: [major|minor|patch]
disable-model-invocation: true
allowed-tools: Bash(git *) Bash(gh release *)
---

版號升級類型：$ARGUMENTS（沒指定就用 patch）

1. 確認在 main、無未 commit 變更
2. 跑完整測試
3. 從上次 tag 到現在的 commit 整理成 changelog（依 Conventional Commits 分類）
4. 依升級類型更新 pyproject.toml 版號
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: 系統化分析一個 GitHub issue 回報的 bug
argument-hint: [issue-number]
disable-model-invocation: true
---

針對 issue #$ARGUMENTS：

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

---
name: upgrade-deps
description: 升級 Python 專案的依賴套件並逐一測試
disable-model-invocation: true
---

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

---
name: full-feature
description: 從需求到 staging 部署的完整功能開發流程
disable-model-invocation: true
---

功能需求：$ARGUMENTS

1. 派出 Explore 子代理盤點相關程式碼
2. 寫出 design.md，暫停讓我確認
3. 依設計拆解任務並實作
4. 派出 test-writer 子代理補測試
5. 派出 code-reviewer 子代理做 review
6. 派出 docs-writer 子代理更新文件
7. 全部通過後，提醒我執行 /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:antigravity "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 install superpowers@claude-plugins-official

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem@thedotmack

git clone https://github.com/ComposioHQ/awesome-claude-skills.git
cd awesome-claude-skills
claude --plugin-dir ./connect-apps-plugin

npx agentic-awesome-skills --claude

---
name: test-writer
description: 為 Python 檔案撰寫 pytest 測試。當使用者說「幫我寫測試」、「add tests」或提到 pytest 時使用。
argument-hint: [target-file]
allowed-tools: Read Grep Glob Bash(pytest *)
---

# Test Writer

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

1. 先讀 $ARGUMENTS(若沒有指定,詢問要測哪個檔案)
2. 識別公開的 function / class
3. 為每個寫至少 3 個測試(happy / edge / error)
4. 用 pytest fixtures,避免重複
5. 完成後跑測試確認都過

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

cd my-project
claude

# Start a new cloud session for the current repo (push your branch first)
claude --cloud "Fix the flaky test in auth.spec.ts"

# Pull a cloud session (and its branch) into your terminal
claude --teleport

# Start Claude Code with Chrome integration
claude --chrome

# Explore first, no edits until you approve a plan
claude --permission-mode plan

# Review every action yourself
claude --permission-mode manual

{
  "permissions": {
    "defaultMode": "default"
  }
}

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "WebFetch(domain:github.com)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)",
      "Bash(curl *)"
    ]
  }
}

/sandbox

sudo apt-get install bubblewrap socat

claude plugin marketplace add owner/repo        # add a marketplace
claude plugin marketplace list                 # list marketplaces
claude plugin marketplace update               # refresh all marketplaces
claude plugin install name@marketplace --scope project
claude plugin list                             # list installed plugins
claude plugin disable name@marketplace         # turn off without uninstalling
claude plugin enable name@marketplace
claude plugin update name@marketplace
claude plugin uninstall name@marketplace