# 專案規則

## 技術棧
- Next.js 15 App Router
- TypeScript（嚴格模式）
- Drizzle ORM + PostgreSQL

## 程式碼規範
- 使用 Server Components 優先
- Client Component 加 "use client"
- 禁止使用 any 型別

## 禁止事項
- 不要修改 .env.local
- 不要跳過 TypeScript 錯誤

⚠️ 此層痛點

內容超過 200 行後，AI 遵守率明顯下降

🚀 升級時機

當 CLAUDE.md 越來越長但 AI 遵守率下降，把工作流程抽成 Skills。

LEVEL3

Skills

按需技能，Token 零消耗

Token：僅呼叫時才注入適用：有重複性工作流程需要標準化

放在 `.claude/skills/` 的 Markdown 文件，只有你呼叫 `/skill名稱` 時才讀入，不使用等於 Token 消耗為零。

Front Matter 關鍵欄位

name — 命令名稱（呼叫時用）
description — AI 自動判斷何時使用
allowed-tools — 限制可用工具
context: fork — 在子代理中執行

動態內容注入

!\gh pr diff\`` — 執行 Shell 並注入結果
$ARGUMENTS — 接收呼叫時傳入的參數
呼叫前自動執行，結果取代命令位置

CLAUDE.md vs Skills

CLAUDE.md：自動生效 ✓，持續消耗 ✗
Skills：手動呼叫 ✓，按需消耗 ✓
規範 → CLAUDE.md；工作流程 → Skills

PR 摘要 Skill

---
name: pr-summary
allowed-tools: Bash(gh *)
description: 自動摘要 PR 的變更與影響
---

## 當前 PR 資訊
- 程式碼差異: !`gh pr diff`
- 評論紀錄: !`gh pr view --comments`

請根據以上資訊，生成：
1. 變更摘要（一段話）
2. 主要影響範圍
3. 需要特別注意的風險點

⚠️ 此層痛點

無法驗證 Claude 是否真的按流程執行

🚀 升級時機

當你想確保 AI 每次執行後都符合品質標準，需要 Hooks 自動驗證。

LEVEL4

Hooks

生命週期自動化，品質變基礎設施

Token：幾乎不消耗適用：需要自動品質把關、安全攔截

在特定事件自動觸發的腳本。Claude 做任何動作前後，都能自動執行檢查、Lint、通知、安全攔截。

7 種觸發事件

SessionStart — Session 開始
PreToolUse — 工具使用前（可攔截）
PostToolUse — 工具使用後（自動檢查）
Stop — 回應完成（品質閘門）
UserPromptSubmit — 提示送出時

4 種 Hook 處理器

type: command — 執行 Shell 腳本
type: http — 呼叫 HTTP endpoint
type: prompt — 詢問另一個 LLM
type: agent — 啟動子代理

exit code 控制行為

exit 0 — 允許繼續
exit 1 — 輸出警告但繼續
exit 2 — 攔截，阻止執行

攔截危險指令 + 自動 Lint

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "./.claude/hooks/block-dangerous.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "npm run lint --silent"
      }]
    }]
  }
}

// block-dangerous.sh
COMMAND=$(jq -r '.tool_input.command' < /dev/stdin)
if echo "$COMMAND" | grep -q 'rm -rf'; then
  echo "已攔截：不允許 rm -rf 指令" >&2
  exit 2
fi
exit 0

⚠️ 此層痛點

單一 Session 工作量有限，大型任務需要拆分

🚀 升級時機

當任務大到需要多個 Agent 同時進行，進入 Level 5。

LEVEL5

Orchestration

多代理並列協調，突破上下文限制

Token：與代理數量成正比適用：大規模重構、並列審查、複雜任務拆解

用多個 Claude 代理並列執行任務。每個子代理負責一個子任務，主代理統籌協調，突破單一上下文視窗限制。

三種代理模型

Explore（Haiku）— 快速搜尋、唯讀任務
Plan — 計畫擬定與架構設計
General-purpose — 通用執行

Subagents vs Agent Teams

Subagents：回傳結果給主代理，彼此不通訊
Agent Teams：直接互相溝通、共享狀態（實驗性）
建議從 3-5 個代理開始，避免衝突

自訂子代理（.claude/agents/）

指定名稱、工具、使用模型
寫入專屬任務說明與審查清單
主代理可按需召喚

自訂程式碼審查代理

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: 審查程式碼品質、資安與測試覆蓋
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是資深程式碼審查員。

審查清單：
- [ ] 程式碼可讀性與命名
- [ ] 錯誤處理是否完整
- [ ] 是否有資安漏洞
- [ ] 測試覆蓋是否足夠
- [ ] 效能影響評估

---
# 呼叫方式（在主 Session 中）
建立 Agent Team 審查 PR #142：
- 審查員①：專注資安影響
- 審查員②：專注效能面向
- 審查員③：專注測試覆蓋
Lead 整合三者結果，產出完整報告

⚠️ 此層痛點

Token 消耗高，多代理編輯同檔案可能產生衝突

升級路線圖

你不會自己決定要升級 — 摩擦感會把你推上去。認識這些信號，自然知道何時該進階。

Level 1 → 2

📍 信號：每次開新 Session 都要重複說同樣規則

✅ 行動：執行 /init 生成 CLAUDE.md

約 10 分鐘

Level 2 → 3

📍 信號：CLAUDE.md 超過 150 行，AI 遵守率下降

✅ 行動：把工作流程抽成 Skills

約 30 分鐘

Level 3 → 4

📍 信號：Skills 執行後品質仍不穩定

✅ 行動：設定 PostToolUse Hook 自動 Lint

約 30 分鐘

Level 4 → 5

📍 信號：任務大到單一 Session 塞不下

✅ 行動：定義 Subagent 委派子任務

約 30 分鐘

# 專案規則 ## 技術棧 - Next.js 15 App Router - TypeScript（嚴格模式） - Drizzle ORM + PostgreSQL ## 程式碼規範 - 使用 Server Components 優先 - Client Component 加 "use client" - 禁止使用 any 型別 ## 禁止事項 - 不要修改 .env.local - 不要跳過 TypeScript 錯誤

--- name: pr-summary allowed-tools: Bash(gh *) description: 自動摘要 PR 的變更與影響 --- ## 當前 PR 資訊 - 程式碼差異: !`gh pr diff` - 評論紀錄: !`gh pr view --comments` 請根據以上資訊，生成： 1. 變更摘要（一段話） 2. 主要影響範圍 3. 需要特別注意的風險點

// .claude/settings.json { "hooks": { "PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "./.claude/hooks/block-dangerous.sh" }] }], "PostToolUse": [{ "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "npm run lint --silent" }] }] } } // block-dangerous.sh COMMAND=$(jq -r '.tool_input.command' < /dev/stdin) if echo "$COMMAND" | grep -q 'rm -rf'; then echo "已攔截：不允許 rm -rf 指令" >&2 exit 2 fi exit 0

# .claude/agents/code-reviewer.md --- name: code-reviewer description: 審查程式碼品質、資安與測試覆蓋 tools: Read, Grep, Glob, Bash model: sonnet --- 你是資深程式碼審查員。審查清單： - [ ] 程式碼可讀性與命名 - [ ] 錯誤處理是否完整 - [ ] 是否有資安漏洞 - [ ] 測試覆蓋是否足夠 - [ ] 效能影響評估 --- # 呼叫方式（在主 Session 中）建立 Agent Team 審查 PR #142： - 審查員①：專注資安影響 - 審查員②：專注效能面向 - 審查員③：專注測試覆蓋 Lead 整合三者結果，產出完整報告

升級路線圖

你不會自己決定要升級 — 摩擦感會把你推上去。認識這些信號，自然知道何時該進階。

Level 1 → 2

📍 信號：每次開新 Session 都要重複說同樣規則

✅ 行動：執行 /init 生成 CLAUDE.md

約 10 分鐘

Level 2 → 3

📍 信號：CLAUDE.md 超過 150 行，AI 遵守率下降

✅ 行動：把工作流程抽成 Skills

約 30 分鐘

Level 3 → 4

📍 信號：Skills 執行後品質仍不穩定

✅ 行動：設定 PostToolUse Hook 自動 Lint

約 30 分鐘

Level 4 → 5

📍 信號：任務大到單一 Session 塞不下

✅ 行動：定義 Subagent 委派子任務

約 30 分鐘