npx openspec init

node -v

id         SERIAL PRIMARY KEY,
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()

main        → 正式環境（穩定版本）
dev         → 開發整合分支
feature/xxx → 單一功能開發
fix/xxx     → 臭蟲修復

feat: 新增案件查詢功能
fix: 修正日期格式解析錯誤
refactor: 重構 API 回傳結構
docs: 更新 README 安裝說明
chore: 升級套件版本

git checkout -b feature/xxx   # 建立新功能分支
git add -p                    # 逐段暫存，避免誤提交
git stash                     # 暫存目前工作，切換分支用
git log --oneline --graph     # 視覺化分支歷史

{
  "success": true,
  "data": { ... },
  "error": null
}

{
  "success": false,
  "data": null,
  "error": "錯誤描述訊息"
}

Arrange  → 準備測試資料與環境
Act      → 執行要測試的動作
Assert   → 驗證結果是否符合預期

openspec config list          # 查看所有目前設定值
openspec config get <key>     # 取得特定設定值
openspec config set <key> <value>  # 修改設定值
openspec config unset <key>   # 移除設定，恢復預設值
openspec config reset         # 重設所有設定為預設值
openspec config path          # 顯示設定檔位置
openspec config edit          # 用 $EDITOR 直接開啟設定檔編輯

/opsx

探索需求         → /opsx:explore
建立規格         → /opsx:new 或 /opsx:ff
實作功能         → /opsx:apply
驗證成果         → /opsx:verify
封存歸檔         → /opsx:archive

# 在專案根目錄執行，讓 Claude 認識你的 Codebase
> /init

# 確認目前載入哪些 MCP 插件
> /plugins

✅ filesystem  - 本機檔案讀寫
✅ github      - GitHub 倉庫操作
✅ supabase    - 資料庫直連
✅ puppeteer   - 無頭瀏覽器自動化
❌ slack       - 未連線（缺少 Token）

事件發生 → Hook 被觸發 → 自動執行腳本 → 結果回饋給 Claude

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "yarn test --passWithNoTests"
          }
        ]
      }
    ],
    "PostToolCall": [
      {
        "matcher": "Write|Edit|Create",
        "hooks": [
          {
            "type": "command",
            "command": "yarn lint --fix"
          }
        ]
      }
    ]
  }
}

┌─────────────┐         MCP 協議          ┌──────────────────┐
│  Claude     │ ←─────────────────────→  │  MCP Server      │
│  (Host)     │   標準化的 Tools / Prompts │  (外部服務介面)    │
└─────────────┘                          └──────────────────┘
                                                  │
                              ┌───────────────────┼──────────────────┐
                              ▼                   ▼                  ▼
                         GitHub API         Supabase DB         本機檔案系統

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Projects"]
    }
  }
}

主代理 (Orchestrator)
  ├── 子代理 A：分析現有程式碼
  ├── 子代理 B：研究外部文件
  └── 子代理 C：執行測試驗證
          ↓
    彙整結果 → 主代理輸出最終答案

主代理：「幫我 Review 這個 PR 的所有變更檔案」
  ├── Subagent 1：分析 api/users.ts
  ├── Subagent 2：分析 components/UserCard.tsx
  └── Subagent 3：分析 tests/users.test.ts
→ 主代理彙整三者的 Review 意見

主代理：「整合第三方支付 API」
  ├── Subagent 1：爬取 API 官方文件，整理欄位規格
  └── Subagent 2：分析現有程式碼，找出整合切入點
→ 主代理擁有完整資訊後開始實作

請用並行方式分析 src/api/ 目錄下的所有路由檔案，
各自獨立評估後，彙整安全性建議。

# 在啟動複雜任務前，先建立 Git 快照
git stash  # 或
git commit -m "chore: snapshot before AI session"

# 若 Claude 走偏，先 Rewind 對話，再回滾程式碼
git checkout HEAD  # 回到最後一個 commit
# 或
git stash pop      # 還原 stash 的工作狀態

# 基本用法：單次執行，印出結果
claude --print "修復所有 lint 錯誤"

# 輸出為 JSON 格式（方便 pipeline 解析）
claude -p "分析程式碼品質" --output-format json

# 限制最多幾輪對話（避免無限迴圈）
claude -p "重構這個模組" --max-turns 5

# 從 stdin 讀取輸入（管線串接）
echo "解釋這段 code" | claude -p

# 建立新的 worktree（同時建立新分支）
git worktree add ../feature-payment feature/payment

# 列出所有 worktree
git worktree list

# 移除已完成的 worktree
git worktree remove ../feature-payment

allow  → 直接執行，不詢問
ask    → 每次執行前彈出確認視窗
deny   → 直接拒絕，不執行

{
  "permissions": {
    "allow": ["git commit*", "yarn test*", "yarn lint*"],
    "ask": ["git push*", "rm *"],
    "deny": ["rm -rf *", "DROP TABLE*"]
  }
}

團隊共用規範  → .claude/settings.json（commit 進 Repo）
個人偏好覆蓋  → .claude/settings.local.json（加入 .gitignore）
企業強制政策  → /etc/claude-code/managed-settings.json（IT 部署）

// 定義函數
function greet(name: string): string {
  return `你好，${name}！`
}

// 呼叫函數
const message = greet("Tom")
console.log(message) // 輸出：你好，Tom！

// 箭頭函數語法更簡潔
const add = (a: number, b: number): number => {
  return a + b
}

// 單行可省略 return 和大括號
const multiply = (a: number, b: number): number => a * b

console.log(add(3, 5))      // 8
console.log(multiply(4, 6)) // 24

// 只執行動作，不回傳資料
function logError(message: string): void {
  console.error(`[ERROR] ${message}`)
}

logError("資料庫連線失敗")

// 計算台北的稅金
const taipeiPrice = 1000
const taipeiTax = taipeiPrice * 0.05
console.log(`台北稅金：${taipeiTax}`)

// 計算新竹的稅金（完全相同的邏輯，複製貼上）
const hsinChuPrice = 2000
const hsinChuTax = hsinChuPrice * 0.05
console.log(`新竹稅金：${hsinChuTax}`)

// 把重複邏輯包成函數
function calculateTax(price: number, taxRate: number = 0.05): number {
  return price * taxRate
}

console.log(`台北稅金：${calculateTax(1000)}`)
console.log(`新竹稅金：${calculateTax(2000)}`)
// 若稅率調整，只需改函數內部一個地方

function formatCurrency(amount: number): string {
  return `NT$ ${amount.toLocaleString()}`
}

console.log(formatCurrency(50000)) // NT$ 50,000

function isEligibleForDiscount(age: number, isMember: boolean): boolean {
  return age >= 65 || isMember
}

if (isEligibleForDiscount(70, false)) {
  console.log("享有折扣")
}

// async/await 函數：處理需要等待的操作（如網路請求）
async function fetchUserData(userId: string) {
  const response = await fetch(`/api/users/${userId}`)
  const data = await response.json()
  return data
}

// 呼叫非同步函數
const user = await fetchUserData("user-123")

// ✅ 動詞開頭，描述行為
function getUser() {}
function createCase() {}
function validateEmail() {}
function isLoggedIn() {}   // 回傳 boolean 用 is/has/can 開頭

// ❌ 名詞開頭或意義不明
function user() {}
function data() {}
function doStuff() {}

// ❌ 拆之前：一個函數做太多事
async function handleOrder(orderId: string) {
  // 第一段：驗證訂單
  const order = await db.orders.findById(orderId)
  if (!order) throw new Error("訂單不存在")
  if (order.status !== "pending") throw new Error("訂單狀態錯誤")

  // 第二段：計算金額
  const subtotal = order.items.reduce((sum, item) => sum + item.price * item.qty, 0)
  const tax = subtotal * 0.05
  const total = subtotal + tax

  // 第三段：發送通知
  await fetch("/api/notify", {
    method: "POST",
    body: JSON.stringify({ userId: order.userId, message: `訂單金額：${total}` })
  })
}

// ✅ 拆之後：每個函數只做一件事
async function validateOrder(orderId: string) {
  const order = await db.orders.findById(orderId)
  if (!order) throw new Error("訂單不存在")
  if (order.status !== "pending") throw new Error("訂單狀態錯誤")
  return order
}

function calculateTotal(items: OrderItem[]): number {
  const subtotal = items.reduce((sum, item) => sum + item.price * item.qty, 0)
  return subtotal * 1.05
}

async function notifyUser(userId: string, total: number) {
  await fetch("/api/notify", {
    method: "POST",
    body: JSON.stringify({ userId, message: `訂單金額：${total}` })
  })
}

// 主函數變得像一份清單，一眼看懂流程
async function handleOrder(orderId: string) {
  const order = await validateOrder(orderId)
  const total = calculateTotal(order.items)
  await notifyUser(order.userId, total)
}

src/
├── api/          # 所有對外 API 呼叫（fetch、axios）
├── utils/        # 純函數工具（格式化、計算、驗證）
├── hooks/        # React 自訂 Hook（狀態邏輯）
├── components/   # UI 元件（只管畫面）
├── services/     # 業務邏輯（組合 api + utils）
└── types/        # TypeScript 型別定義

// ❌ 拆之前：所有東西擠在 orderPage.tsx（500+ 行）
// - fetch 邏輯
// - 金額計算
// - 日期格式化
// - JSX 渲染

// ✅ 拆之後：各司其職
// api/orderApi.ts      → 負責 fetch
// utils/formatDate.ts  → 負責格式化
// utils/calcOrder.ts   → 負責計算
// components/OrderCard.tsx → 負責渲染
// orderPage.tsx        → 只負責組裝以上模組（50 行以內）

主函數
├── 子函數 A（處理步驟一）
├── 子函數 B（處理步驟二）
│   ├── 子子函數 B1
│   └── 子子函數 B2
└── 子函數 C（處理步驟三）

// ── 子函數：各自負責一個細節 ──────────────────────

function getCartItems(userId: string): CartItem[] {
  // 從資料庫取得購物車內容
  return db.cart.findByUserId(userId)
}

function applyDiscount(subtotal: number, coupon: string): number {
  const discountMap: Record<string, number> = { SAVE10: 0.9, SAVE20: 0.8 }
  return subtotal * (discountMap[coupon] ?? 1)
}

function calcTax(amount: number): number {
  return amount * 0.05
}

async function chargePayment(userId: string, total: number): Promise<boolean> {
  const result = await paymentGateway.charge({ userId, amount: total })
  return result.success
}

async function sendReceipt(userId: string, total: number): Promise<void> {
  await emailService.send({ to: userId, subject: "訂單確認", body: `總金額：${total}` })
}

// ── 主函數：只描述流程，細節交給子函數 ───────────────

async function checkout(userId: string, coupon: string) {
  const items     = getCartItems(userId)
  const subtotal  = items.reduce((sum, i) => sum + i.price * i.qty, 0)
  const discounted = applyDiscount(subtotal, coupon)
  const total     = discounted + calcTax(discounted)
  const paid      = await chargePayment(userId, total)
  if (paid) await sendReceipt(userId, total)
}

<標籤名稱 屬性="值">內容</標籤名稱>

<p>這是一段文字</p>
<h1>這是標題</h1>
<a href="https://example.com">點我連結</a>

<img src="photo.jpg" alt="照片說明" />
<input type="text" placeholder="請輸入文字" />
<br />

<!-- class：套用 CSS 樣式 -->
<div class="card highlight">內容</div>

<!-- id：唯一識別，用於 JS 選取或錨點連結 -->
<section id="about">關於我們</section>

<!-- data-*：自訂資料屬性，傳給 JavaScript 使用 -->
<button data-user-id="123" data-action="delete">刪除</button>

<!-- ❌ 全用 div，搜尋引擎看不懂結構 -->
<div class="header">...</div>
<div class="nav">...</div>
<div class="content">...</div>

<!-- ✅ 語意標籤，對 SEO 和無障礙設計友善 -->
<header>...</header>
<nav>...</nav>
<main>...</main>

# 建立 Annotated Tag（推薦）
git tag -a v1.0.0 -m "第一個正式發布版本"

# 建立 Lightweight Tag
git tag v1.0.0-beta

# 查看所有 Tag
git tag

# 查看特定 Tag 的詳細資訊
git show v1.0.0

# 推送單一 Tag 到遠端
git push origin v1.0.0

# 推送所有本地 Tag 到遠端
git push origin --tags

# 刪除本地 Tag
git tag -d v1.0.0

# 刪除遠端 Tag
git push origin --delete v1.0.0

v主版本.次版本.修補版本
  MAJOR . MINOR . PATCH

v1.0.0   → 首次正式發布
v1.1.0   → 新增功能（向下相容）
v1.1.1   → 修復 Bug（不影響功能）
v2.0.0   → 不向下相容的重大改版

# 開發完成，準備發布 v1.2.0
git checkout main
git pull --rebase

# 建立標籤並寫說明
git tag -a v1.2.0 -m "新增優惠券折扣功能，修復結帳金額計算錯誤"

# 推送程式碼與標籤
git push origin main
git push origin v1.2.0

# 現況
執行之後，程式毫無反應，也找不到任何錯誤訊息。

# 期待
執行之後，Google 試算表中「測試」工作表的 A 欄應該出現 XXX 資料。

async function writeToSheet() {
  console.log("▶ writeToSheet 開始執行")   // ← 加這行

  const data = await fetchData()
  console.log("▶ fetchData 完成，data =", data)  // ← 加這行

  await sheet.write(data)
  console.log("▶ sheet.write 完成")  // ← 加這行
}

// ❌ 常見錯誤：忘記 await，函數直接結束，資料根本還沒寫入
function saveData() {
  fetchAndWrite()  // 沒有 await！
  console.log("完成")  // 這行會在 fetchAndWrite 結束前就印出來
}

// ✅ 正確寫法
async function saveData() {
  await fetchAndWrite()
  console.log("完成")
}

// ❌ 靜默吞錯：發生錯誤也不會有任何提示
try {
  await writeToSheet()
} catch (e) {
  // 什麼都沒寫
}

// ✅ 至少要印出來
try {
  await writeToSheet()
} catch (e) {
  console.error("writeToSheet 失敗：", e)
}

// 明確印出你以為在操作的目標
console.log("試算表 ID：", spreadsheetId)
console.log("工作表名稱：", sheetName)
console.log("寫入範圍：", range)

import requests
from bs4 import BeautifulSoup

res = requests.get("https://example.com")
soup = BeautifulSoup(res.text, "html.parser")
print(soup.select_one("h1").text)

curl 'https://api.example.com/data?page=1' \
  -H 'Authorization: Bearer xxx' \
  -H 'Content-Type: application/json'

import requests

headers = {
    "Authorization": "Bearer xxx",
    "Content-Type": "application/json",
}

res = requests.get("https://api.example.com/data", params={"page": 1}, headers=headers)
print(res.json())

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.inner_text("h1"))
    browser.close()

目標網站有資料要抓
        │
        ▼
  檢視頁面原始碼（Ctrl+U）
  能看到資料？
   ┌──────┴──────┐
  是              否
   │              │
靜態網站        動態網站
requests +      開 Network 分頁
BeautifulSoup   找 Fetch/XHR 請求
                  │
              找到 API？
            ┌────┴────┐
           是          否
            │          │
        直接呼叫      無頭瀏覽器
        API 端點      (Playwright)