┌─────────────────────────────────────────────────────────────────┐
│                     開發者工作環境                                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐    │
│  │ Terminal  │  │ VS Code  │  │  Chrome  │  │ Claude Web   │    │
│  │ (CLI)     │  │ Extension│  │ Extension│  │ (claude.ai)  │    │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └──────┬───────┘    │
│       └──────────────┼───────────┬─┘               │            │
│                      ▼           ▼                 ▼            │
│              ┌───────────────────────────────────────┐          │
│              │        Claude Code Core Engine         │          │
│              │  ┌─────────┐ ┌────────┐ ┌──────────┐ │          │
│              │  │Subagents│ │ Skills │ │  Hooks   │ │          │
│              │  └─────────┘ └────────┘ └──────────┘ │          │
│              │  ┌─────────┐ ┌────────┐ ┌──────────┐ │          │
│              │  │Commands │ │  MCP   │ │ Plugins  │ │          │
│              │  └─────────┘ └────────┘ └──────────┘ │          │
│              └──────────────┬────────────────────────┘          │
│                             ▼                                   │
│              ┌──────────────────────────────┐                   │
│              │     專案檔案系統 / Git        │                   │
│              └──────────────────────────────┘                   │
└─────────────────────────────────────────────────────────────────┘

Command → Agent → Skill
   │         │        │
   │         │        └── 具體技能執行（SKILL.md + 支援檔案）
   │         └── 子代理分派（.claude/agents/<name>.md）
   └── 使用者觸發點（.claude/commands/<name>.md）

# 使用者只需輸入一個 command
claude
/weather-orchestrator

# 背後自動觸發：
# 1. Command 解析使用者意圖
# 2. 分派給對應的 Agent
# 3. Agent 調用 Skill 完成任務
# 4. 結果回傳主 context

┌─────────────────────────────────────┐
│          Main Context               │
│  （架構規劃、任務分派、結果整合）      │
│                                     │
│  ┌──────┐ ┌──────┐ ┌──────┐        │
│  │Auth  │ │API   │ │DB    │        │
│  │Agent │ │Agent │ │Agent │        │
│  └──┬───┘ └──┬───┘ └──┬───┘        │
│     │        │        │             │
│  ┌──┴───┐ ┌──┴───┐ ┌──┴───┐        │
│  │Auth  │ │API   │ │DB    │        │
│  │Skill │ │Skill │ │Skill │        │
│  └──────┘ └──────┘ └──────┘        │
└─────────────────────────────────────┘

# .github/workflows/claude-review.yml
name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Claude Code Review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          command: |
            Review this PR for:
            1. Security vulnerabilities
            2. Performance issues
            3. Code quality
            4. Test coverage

# 1. 安裝 Claude Code CLI
npm install -g @anthropic-ai/claude-code

# 2. 驗證安裝
claude --version

# 3. 認證（首次使用）
claude auth login

# 4. 診斷安裝問題
claude /doctor

# Windows 使用 npx 啟動 MCP Server 時需注意路徑問題
# 建議使用 PowerShell 7+ 而非 cmd.exe

# 安裝 PowerShell 7
winget install Microsoft.PowerShell

# 設定預設終端
# VS Code: Terminal > Default Profile > PowerShell 7

# 優化終端顯示和換行邏輯
claude /terminal-setup

# No Flicker Mode — 消除畫面閃爍（beta）
export CLAUDE_CODE_NO_FLICKER=1
claude /tui fullscreen

# 1. 進入專案目錄
cd /path/to/your-project

# 2. 啟動 Claude Code
claude

# 3. Claude 會自動掃描專案結構，建議執行初始化
# 在 Claude 對話中：
> 分析這個專案結構，幫我建立 CLAUDE.md 和 .claude/ 設定

# 4. 或使用現成的工作流初始化
> /speckit.constitution   # 使用 Spec Kit 工作流
> /gsd-new-project        # 使用 Get Shit Done 工作流

your-project/
├── CLAUDE.md                     # 專案級規則（< 200 行）
├── .claude/
│   ├── settings.json             # Claude Code 設定
│   ├── settings.local.json       # 本地設定（不進版控）
│   ├── agents/                   # 子代理定義
│   │   ├── backend-agent.md
│   │   ├── frontend-agent.md
│   │   └── security-agent.md
│   ├── commands/                 # 自訂斜線指令
│   │   ├── plan.md
│   │   ├── review.md
│   │   └── ship.md
│   ├── skills/                   # 技能模組
│   │   └── api-design/
│   │       ├── SKILL.md
│   │       └── references/
│   ├── hooks/                    # 事件鉤子腳本
│   │   ├── pre-tool-use.sh
│   │   └── post-tool-use.sh
│   └── rules/                    # 延遲載入規則
│       ├── backend.md
│       ├── frontend.md
│       └── security.md
├── .mcp.json                     # MCP Server 設定
└── src/                          # 專案源碼

// .vscode/settings.json
{
  "terminal.integrated.defaultProfile.windows": "PowerShell",
  "terminal.integrated.fontSize": 14,
  "editor.formatOnSave": true,
  "files.autoSave": "afterDelay"
}

# 使用 --remote 啟動雲端 session
claude --remote

# 設定預設遠端環境
/remote-env

# 從 claude.ai 拉取雲端 session 到本地終端
/teleport

# 專案名稱：Enterprise Banking System

## 專案概述
Java 17 + Spring Boot 3.2 企業級銀行系統，使用 Clean Architecture。

## 建置與執行
- 建置：`mvn clean compile`
- 測試：`mvn test`
- 執行：`mvn spring-boot:run`
- 程式碼風格檢查：`mvn checkstyle:check`

## 架構規範
- 遵循 Clean Architecture（Domain → Application → Infrastructure）
- API 設計遵循 RESTful 規範
- 所有 Controller 方法需有 @Operation 註解

## 編碼規範
- 使用 JavaDoc 格式撰寫公開方法註解
- 類別名稱使用 PascalCase
- 常數使用 UPPER_SNAKE_CASE
- 禁止在 Controller 層直接存取 Repository

## 測試規範
- 每個 Service 類別需有對應的單元測試
- 測試覆蓋率目標 > 80%
- 使用 @SpringBootTest 進行整合測試

## 安全規範
- 不可在程式碼中硬編碼密碼或 API Key
- SQL 查詢必須使用參數化查詢
- 所有外部輸入必須驗證

monorepo/
├── CLAUDE.md                 # 根層規則（全域適用）
├── packages/
│   ├── backend/
│   │   └── CLAUDE.md         # 後端特定規則
│   ├── frontend/
│   │   └── CLAUDE.md         # 前端特定規則
│   └── shared/
│       └── CLAUDE.md         # 共用套件規則

.claude/rules/
├── backend.md        # 後端開發規則
├── frontend.md       # 前端開發規則
├── security.md       # 安全開發規則
├── database.md       # 資料庫操作規則
└── testing.md        # 測試撰寫規則

---
# .claude/rules/spring-boot.md
paths:
  - "src/main/java/**/*.java"
  - "src/test/java/**/*.java"
---

# Spring Boot 開發規則

## Controller 層
- 所有 REST API 需使用 @RestController
- 回傳值統一使用 ResponseEntity<>
- 路徑命名使用 kebab-case

## Service 層
- 使用 @Transactional 管理交易
- 業務例外使用自訂 Exception 類別
- 不可直接在 Service 中使用 HttpServletRequest

---
# .claude/rules/react-components.md
paths:
  - "src/components/**/*.tsx"
  - "src/pages/**/*.tsx"
---

# React 元件開發規則

## 元件設計
- 使用 Functional Components + Hooks
- Props 必須定義 TypeScript Interface
- 狀態管理使用 Zustand 或 React Query

// .claude/settings.json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "effortLevel": "high",
  "language": "chinese",
  "tui": "fullscreen",
  "viewMode": "default",

  "permissions": {
    "allow": [
      "Bash(mvn *)",
      "Bash(npm run *)",
      "Bash(git diff *)",
      "Edit(src/**)",
      "Edit(docs/**)",
      "Agent(*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Read(.env*)",
      "Edit(**/secrets/**)"
    ],
    "defaultMode": "acceptEdits"
  },

  "attribution": {
    "commit": ""
  },

  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"],
    "sparsePaths": ["packages/my-app", "shared/utils"]
  },

  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker", "gh"]
  },

  "statusLine": {
    "type": "command",
    "command": "git branch --show-current 2>/dev/null || echo 'no-branch'",
    "refreshInterval": 5
  },

  "env": {
    "CLAUDE_CODE_EFFORT_LEVEL": "high",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
  }
}

// .claude/settings.json — Plugin 設定
{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "deployer@acme-tools": true
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  }
}

# 方法 1：在 Claude 對話中切換
> Shift+Tab  # 循環切換 Ask → Plan → Auto 模式

# 方法 2：使用 /model 選擇規劃用模型
> /model     # 選擇 Opus 做規劃，Sonnet 做編碼

# 請 Claude 先面試你，釐清需求
> 使用 AskUserQuestion 工具來面試我，了解這個功能的需求

# 規劃完成後，開一個新 session 來執行
> /clear
> 根據以下規劃執行實作：[貼上規劃內容]

# 請第二個 Claude 以 Staff Engineer 角色審核規劃
> 以 Staff Engineer 的角度審核這份規劃，指出風險和遺漏

# 確認目前 context 用量
> /context

# 將大任務拆解
> 請將這個功能拆解成可獨立完成的子任務，每個子任務需在 50% context 內完成

# 任務拆解範例輸出：
# 1. 建立 Domain Entity（預計 10% context）
# 2. 建立 Repository Interface（預計 5% context）
# 3. 實作 Service Layer（預計 15% context）
# 4. 實作 Controller（預計 10% context）
# 5. 撰寫單元測試（預計 15% context）

# 帶提示的 compact（推薦）
> /compact focus on the auth refactor, drop the test debugging

# 純 compact（不推薦，壓縮時缺乏方向）
> /compact

# 在 /rewind 之前，先讓 Claude 寫一份交接摘要
> 從這裡開始，寫一份摘要說明你做了什麼、下一步是什麼

# 然後 /rewind 到之前的狀態
> /rewind

# 再把摘要貼回來，就像「未來的 Claude 給過去的 Claude 的筆記」

# 重新命名 session（方便識別）
> /rename [TODO - auth refactor]

# 恢復之前的 session
> /resume

# 查看 session 歷史
> claude --resume

Claude 完成一個 turn
    ├── Continue    → 繼續目前任務
    ├── /rewind     → 回到之前的檢查點重試
    ├── /clear      → 清空 context 重新開始
    ├── /compact    → 壓縮 context 繼續
    └── Subagent    → 分派給子代理處理

# 錯誤做法：在失敗的嘗試上疊加修正
> 這個方法不對，請改用 xxx

# 正確做法：回退到失敗前，用學到的資訊重新嘗試
> Esc Esc  # 雙擊 Escape 取消
> /rewind   # 回到失敗前的狀態
> 使用 xxx 方法來實作這個功能  # 用新的方向重新嘗試

# 在需要深度推理的 prompt 中加入 ultrathink 關鍵字
> ultrathink 分析這個分散式交易的一致性問題，並提出解決方案

# 或使用 Opus 4.7 的 Adaptive Thinking 調整努力等級
# low → medium → high → xhigh → max

# 設定 Effort Level
> /effort high       # 直接設定
> /effort auto       # 重設為模型預設

# 在 Skill 中使用努力等級模板變數
# ${CLAUDE_EFFORT} — 取得當前 effort level

# 建立對話分支（不影響原始對話）
> /branch my-experiment

# 快速旁白問題（不加入主對話）
> /btw 這個 API 的回傳格式是什麼？

# 產生 session 摘要
> /recap

# 使用 Ultraplan 在雲端規劃
> /ultraplan 設計微服務拆分方案

# 啟動 Auto Mode
claude --permission-mode auto

# 在 session 中循環切換
> Shift+Tab  # Ask → Plan → Auto

# 自訂 Auto Mode 規則
# ~/.claude/settings.json（不可放在共享的 .claude/settings.json）

{
  "autoMode": {
    "environment": [
      "Source control: github.example.com/acme-corp",
      "Trusted internal domains: *.internal.example.com"
    ],
    "soft_deny": [
      "$defaults",
      "Never run terraform apply",
      "Never delete production databases"
    ],
    "allow": [
      "$defaults",
      "Allow running npm test without prompting"
    ]
  }
}

<!-- .claude/agents/backend-agent.md -->
---
name: backend-agent
description: "PROACTIVELY 處理後端 Java/Spring Boot 開發任務"
model: sonnet
tools: Read, Edit, Bash, Grep, Glob
disallowedTools: "Bash(rm -rf *), Bash(git push *)"
effort: high
color: blue
---

# Backend Agent

你是一個專精 Java / Spring Boot 的後端開發代理。

## 職責
- 實作 Service、Repository、Controller 層
- 撰寫單元測試
- 處理資料庫 Migration

## 規範
- 遵循 Clean Architecture
- 使用 @Transactional 管理交易
- 所有公開方法需撰寫 JavaDoc

## 限制
- 不可修改 .env 或設定檔
- 不可直接操作生產資料庫
- 遇到架構問題需回報主 context

<!-- .claude/agents/security-agent.md -->
---
name: security-agent
description: "PROACTIVELY 負責安全審查和弱點掃描"
model: opus
tools: Read, Grep, Glob, Bash
disallowedTools: Edit, "Bash(git *)"
color: red
maxTurns: 30
---

# Security Agent

你是一個專精資安的安全審查代理。

## 職責
- 掃描程式碼中的安全弱點（OWASP Top 10）
- 檢查敏感資料暴露風險
- 驗證輸入驗證機制
- 審查 SQL Injection 風險
- 檢查 XSS 風險

## 輸出格式
以結構化報告回報：
- 風險等級（Critical / High / Medium / Low）
- 影響範圍
- 修復建議
- 參考標準（CWE / CVE）

<!-- .claude/agents/db-agent.md -->
---
name: db-agent
description: "處理資料庫設計、Migration 和查詢最佳化"
model: sonnet
tools: Read, Grep, Glob, Bash
disallowedTools: "Bash(DROP *), Bash(DELETE FROM *), Bash(TRUNCATE *)"
isolation: worktree
color: green
---

# Database Agent

你是一個專精資料庫設計的代理。

## 職責
- 設計資料表結構
- 撰寫 Flyway/Liquibase Migration
- 最佳化慢查詢
- 設計索引策略

## 規範
- 所有查詢必須使用參數化（防 SQL Injection）
- 禁止使用 SELECT *
- 大量資料查詢需加上分頁
- Migration 必須可回滾

# 主 context 依序分派任務
> 使用 backend-agent 建立 User Entity 和 Repository
> [等待完成]
> 使用 backend-agent 建立 UserService
> [等待完成]
> 使用 security-agent 審查上述程式碼的安全性

# 使用 Agent Teams（需 tmux + git worktrees）
# 多個 Claude 實例在不同 worktree 同時工作

# 設定方式：
# 1. 建立 git worktree
git worktree add ../project-auth feature/auth
git worktree add ../project-api feature/api

# 2. 在不同 tmux 窗格啟動 Claude
tmux new-session -d -s auth "cd ../project-auth && claude"
tmux new-session -d -s api "cd ../project-api && claude"

# 3. 各自獨立開發
# auth 窗格：實作認證模組
# api 窗格：實作 API 端點

<!-- .claude/commands/implement-feature.md -->
---
description: 使用多 Agent 協作實作功能
---

# 功能實作工作流

1. **規劃階段**：分析需求，拆解為子任務
2. **實作階段**：
   - 使用 @backend-agent 實作後端邏輯
   - 使用 @frontend-agent 實作前端 UI
   - 使用 @db-agent 處理資料庫 Migration
3. **驗證階段**：
   - 使用 @security-agent 執行安全審查
   - 使用 @test-agent 補齊測試
4. **整合階段**：
   - 合併所有變更
   - 執行整合測試
   - 產生 PR

請先以 Plan Mode 規劃，待使用者確認後再執行。

主 Context                    子 Context（Subagent）
┌──────────┐                 ┌──────────────────────┐
│ 任務描述  │ ──分派──▶      │ 20 次檔案讀取         │
│ 期望結果  │                │ 12 次搜尋             │
│          │                │ 3 次失敗嘗試           │
│          │                │ 最終成功方案           │
│ 結論報告  │ ◀──回收──      │                      │
└──────────┘                 └──────────────────────┘

主 context 只看到結論，中間的探索過程留在子 context

# SDK 模式啟動
claude -p "分析這個專案" --output-format json

# 結合 CI/CD pipeline
claude -p "review this PR for security issues" \
  --permission-mode bypassPermissions \
  --no-session-persistence

# 讓本地 session 可被 claude.ai 遠端控制
> /remote-control

# 從 claude.ai 拉取雲端 session 到本地
> /teleport

// .claude/settings.json（hooks 區段）
{
  "hooks": {
    "SessionStart": [
      {
        "name": "load-project-context",
        "command": "cat docs/architecture.md docs/api-spec.md | head -200",
        "description": "載入專案架構和 API 規格"
      },
      {
        "name": "check-git-status",
        "command": "git status --short && git log --oneline -5",
        "description": "顯示 Git 狀態和最近 5 個 commit"
      },
      {
        "name": "load-todo",
        "command": "cat TODO.md 2>/dev/null || echo 'No TODO.md found'",
        "description": "載入待辦事項"
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/restore-context.sh
# SessionStart hook：恢復關鍵上下文

echo "=== 專案上下文 ==="
echo "Git Branch: $(git branch --show-current)"
echo "Last Commit: $(git log --oneline -1)"
echo ""
echo "=== 未完成任務 ==="
grep -r "TODO\|FIXME\|HACK" src/ --include="*.java" | head -10
echo ""
echo "=== 測試狀態 ==="
mvn test -q 2>&1 | tail -5

{
  "hooks": {
    "PreToolUse": [
      {
        "name": "protect-sensitive-files",
        "matcher": "Edit",
        "if": "path matches '**/.env*' or path matches '**/secrets/**' or path matches '**/credentials/**'",
        "command": "echo 'BLOCKED: Cannot modify sensitive files' && exit 1",
        "description": "禁止修改敏感檔案"
      },
      {
        "name": "readonly-sql",
        "matcher": "Bash",
        "if": "command contains 'psql' or command contains 'mysql'",
        "command": "bash .claude/hooks/validate-sql.sh",
        "description": "僅允許唯讀 SQL 查詢"
      },
      {
        "name": "track-skill-usage",
        "matcher": "*",
        "command": "echo \"$(date +%Y-%m-%dT%H:%M:%S) TOOL: $CLAUDE_TOOL_NAME\" >> .claude/hooks/usage.log",
        "description": "追蹤工具使用頻率"
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/validate-sql.sh
# 僅允許 SELECT 查詢，阻擋 DML/DDL

SQL_CMD="$1"
if echo "$SQL_CMD" | grep -iE "(INSERT|UPDATE|DELETE|DROP|ALTER|TRUNCATE|CREATE)" > /dev/null; then
    echo "BLOCKED: Only SELECT queries are allowed"
    exit 1
fi
echo "ALLOWED: Read-only query"
exit 0

{
  "hooks": {
    "PostToolUse": [
      {
        "name": "auto-format-java",
        "matcher": "Edit",
        "if": "path matches '**/*.java'",
        "command": "google-java-format --replace $CLAUDE_FILE_PATH",
        "description": "自動格式化 Java 程式碼"
      },
      {
        "name": "auto-lint-typescript",
        "matcher": "Edit",
        "if": "path matches '**/*.ts' or path matches '**/*.tsx'",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH",
        "description": "自動修正 TypeScript lint 問題"
      },
      {
        "name": "audit-log",
        "matcher": "Edit",
        "command": "echo \"$(date +%Y-%m-%dT%H:%M:%S) EDIT: $CLAUDE_FILE_PATH by Claude\" >> .claude/audit.log",
        "description": "記錄所有檔案修改到稽核日誌"
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "name": "verify-tests-pass",
        "command": "mvn test -q 2>&1 | tail -3",
        "description": "每次 turn 結束時驗證測試是否通過"
      },
      {
        "name": "nudge-continue",
        "command": "echo 'Before stopping, verify: 1) All tests pass 2) No security issues 3) Code is formatted'",
        "description": "提醒 Claude 在停止前驗證工作"
      }
    ]
  }
}

{
  "hooks": {
    "PermissionRequest": [
      {
        "name": "opus-security-gate",
        "command": "python3 .claude/hooks/security-gate.py",
        "description": "使用 Opus 模型掃描權限請求，自動批准安全操作"
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "name": "remote-audit",
        "type": "http",
        "url": "https://audit.company.com/claude-events",
        "description": "將工具使用事件傳送到企業審計系統"
      }
    ]
  }
}

# 在 Skill 中定義臨時 hooks
# /careful — 阻擋破壞性指令
# /freeze — 阻擋目錄外的編輯

# 1. API 設計（Plan Mode）
> 以 RESTful 風格設計使用者管理 API，包含：
> - CRUD 操作
> - 認證/授權
> - 分頁和篩選
> 請產出 OpenAPI 3.0 規格

# 2. 後端實作（分派給 Backend Agent）
> 使用 backend-agent 根據 api-spec.yaml 實作：
> - UserController
> - UserService
> - UserRepository
> - User Entity
> - 完整單元測試

# 3. 前端實作（分派給 Frontend Agent）
> 使用 frontend-agent 根據 api-spec.yaml 實作：
> - 使用者列表頁面
> - 使用者表單（新增/編輯）
> - API 整合層（axios/fetch）
> - 狀態管理

# 4. 整合測試
> 執行整合測試，驗證前後端 API 對接是否正確

# 使用 Claude Code 建立 Clean Architecture 骨架
> 請建立以下 Clean Architecture 結構：
> 
> domain/
>   ├── entities/         # 業務實體
>   ├── repositories/     # Repository 介面
>   └── usecases/         # 業務邏輯
> 
> application/
>   ├── services/         # 應用服務
>   ├── dto/              # 資料傳輸物件
>   └── mappers/          # Entity <-> DTO 轉換
> 
> infrastructure/
>   ├── persistence/      # Repository 實作
>   ├── web/              # Controller
>   └── config/           # 設定

# 同時使用 ArchUnit 測試驗證架構約束
> 撰寫 ArchUnit 測試，確保：
> 1. Domain 層不依賴 Infrastructure 層
> 2. Controller 不直接存取 Repository
> 3. Entity 不使用 Spring 註解

@AnalyzeClasses(packages = "com.example")
public class ArchitectureTest {

    @ArchTest
    static final ArchRule domain_should_not_depend_on_infrastructure =
        noClasses()
            .that().resideInAPackage("..domain..")
            .should().dependOnClassesThat()
            .resideInAPackage("..infrastructure..");

    @ArchTest
    static final ArchRule controllers_should_not_access_repositories =
        noClasses()
            .that().resideInAPackage("..web..")
            .should().dependOnClassesThat()
            .resideInAPackage("..persistence..");
}

# 1. 系統概觀分析
> ultrathink 分析這個專案的整體架構：
> - 辨識主要模組和它們的職責
> - 找出模組間的依賴關係
> - 辨識使用的技術棧和框架
> - 產出 ASCII 架構圖

# 2. 業務規則抽取
> 分析 src/main/java/com/legacy/ 目錄下的所有 Service 類別：
> - 抽取核心業務規則
> - 辨識隱藏的業務邏輯（寫在 Controller 或 DAO 中的）
> - 產出業務規則文件

# 3. 資料庫依賴分析
> 分析所有 SQL 查詢和資料庫操作：
> - 列出所有資料表和它們的關聯
> - 辨識未被使用的資料表
> - 找出效能問題（全表掃描、缺少索引）
> - 產出 ER Diagram（Mermaid 格式）

# 使用 ASCII 圖表理解架構（Boris 強調的技巧）
> 請使用 ASCII 圖表畫出這個系統的：
> 1. 系統架構圖
> 2. 資料流圖
> 3. 模組依賴圖
> 4. API 呼叫序列圖

# 範例輸出：
# ┌─────────┐    ┌──────────┐    ┌──────────┐
# │  Web UI │───▶│  Gateway │───▶│  Service │
# └─────────┘    └──────────┘    └────┬─────┘
#                                     │
#                                ┌────▼─────┐
#                                │    DB    │
#                                └──────────┘

# 產出 Mermaid 架構圖
> 分析 src/ 目錄，產出 Mermaid 格式的：
> 1. 類別圖（主要 Entity 和 Service 的關聯）
> 2. 序列圖（主要 API 的呼叫流程）
> 3. 元件圖（模組間的依賴關係）

<!-- .claude/skills/reverse-engineering/SKILL.md -->
---
description: "Triggered when analyzing legacy code or performing reverse engineering tasks"
---

# Legacy Code Analysis Skill

## 目標
分析舊系統程式碼，產出結構化的分析報告。

## 分析步驟
1. 掃描專案結構，辨識技術棧
2. 分析模組依賴關係
3. 抽取業務規則
4. 識別技術債
5. 評估安全風險
6. 產出遷移建議

## 輸出格式
### 系統概觀
- 技術棧：[列表]
- 模組數量：[數字]
- 程式碼行數：[數字]

### 架構分析
[ASCII 或 Mermaid 圖表]

### 業務規則清單
| 規則 ID | 描述 | 所在位置 | 複雜度 |
|---------|------|---------|--------|

### 技術債清單
| 項目 | 嚴重度 | 影響範圍 | 建議修復方式 |
|------|--------|---------|-------------|

### 安全風險
| 風險 | OWASP 分類 | 嚴重度 | 修復建議 |
|------|-----------|--------|---------|

# 1. 升級前評估
> 分析目前的 Spring Boot 版本（2.7.x），列出升級到 3.2 的：
> - Breaking Changes 清單
> - 需要修改的程式碼範圍
> - 相依套件相容性問題
> - 預估工作量

# 2. 分階段升級計畫
> 制定分階段升級計畫：
> Phase 1：更新 pom.xml 依賴
> Phase 2：修復編譯錯誤
> Phase 3：更新 API 變更（javax → jakarta）
> Phase 4：修復測試
> Phase 5：效能驗證

# 3. 自動重構
> 使用 subagent 批次修改所有 javax.* import 為 jakarta.*
> 同時更新相關的設定檔

<!-- .claude/skills/framework-upgrade/SKILL.md -->
---
description: "Triggered when upgrading framework versions or analyzing breaking changes"
---

# Framework Upgrade Analysis

## 分析步驟
1. 讀取目前的 dependency 版本
2. 與目標版本比較 release notes
3. 掃描程式碼中受影響的 API 使用
4. 產出影響分析報告
5. 提供自動修復建議

## Gotchas（常見踩坑）
- Spring Boot 2.x → 3.x：javax → jakarta namespace 變更
- Java 8 → 17：Records、Sealed Classes 可選用
- JUnit 4 → 5：@Test 和 Assert 語法變更
- 部分 deprecated API 在新版中已移除

# 直接在 Claude 對話中使用 BigQuery
> 查詢過去 7 天的使用者登入統計，按小時分組

# Claude 會自動產生並執行：
bq query --use_legacy_sql=false \
  'SELECT 
     TIMESTAMP_TRUNC(login_time, HOUR) as hour,
     COUNT(*) as login_count
   FROM `project.dataset.user_logins`
   WHERE login_time >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
   GROUP BY hour
   ORDER BY hour'

# 1. 自然語言查詢
> 找出過去一個月中，哪些 API 端點的回應時間超過 2 秒

# 2. Claude 自動：
#    a. 產生 SQL
#    b. 執行查詢
#    c. 分析結果
#    d. 產出視覺化建議

# 3. 進階分析
> 比較上週和這週的 API 效能差異，找出退化最嚴重的 5 個端點

# 產出效能報表
> 請根據以下資料產出效能分析報表（Markdown 格式）：
> - 包含圖表（Mermaid）
> - 包含趨勢分析
> - 包含異常偵測
> - 包含改善建議

# 定期報表生成（使用 /loop）
> /loop every 24h 產出每日系統健康報表，儲存到 reports/daily/

// .mcp.json
{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "bigquery": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-server-bigquery"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "${GOOGLE_CREDS_PATH}"
      }
    }
  }
}

# 步驟 1：Claude Code 做規劃（Opus）
claude --model opus
> 設計使用者認證系統的架構方案

# 步驟 2：切換到 Sonnet 做實作
> /model sonnet
> 根據上述架構方案實作

# 步驟 3：使用 Copilot 做微調
# 在 VS Code 中開啟生成的檔案，使用 Copilot 補完細節

# 步驟 4：Claude Code 做 Review
> /code-review
# 或使用另一個 Claude 實例做 cross-model review

早上啟動 → Claude Code Plan Mode（規劃今日任務）
    │
    ├── 大型功能開發 → Claude Code（Subagent 分派）
    │   └── 細節調整 → GitHub Copilot（即時補全）
    │
    ├── Bug Fix → GitHub Copilot（快速修復）
    │   └── 安全驗證 → Claude Code（Security Agent）
    │
    ├── Code Review → Claude Code（/code-review）
    │
    └── 文件更新 → GitHub Copilot + Claude Code
        │
下班前 → Claude Code（產出 PR + 每日報告）

# 同時開啟多個 Claude 終端，各負責不同任務
# Terminal 1（Opus — 規劃）
claude --model opus
> /plan 設計整個微服務架構

# Terminal 2（Sonnet — 實作）
claude --model sonnet
> 根據 architecture.md 實作 UserService

# Terminal 3（Haiku — 快速查詢）
claude --model haiku
> 搜尋所有使用 deprecated API 的檔案

# 使用 Security Agent 進行威脅建模
> 使用 security-agent 對以下系統進行威脅建模：
> - 使用者認證模組（JWT + OAuth2）
> - 支付處理模組（PCI DSS 合規）
> - API Gateway
> 
> 請使用 STRIDE 模型分析，產出威脅矩陣

# Claude 會自動分析並產出：
# 1. 資料流圖（DFD）
# 2. STRIDE 威脅分析
# 3. 風險評級
# 4. 緩解措施建議

<!-- .claude/skills/threat-modeling/SKILL.md -->
---
description: "Triggered when performing security analysis or threat modeling"
---

# Threat Modeling Skill

## 分析框架：STRIDE
- **S**poofing（身分偽造）
- **T**ampering（資料竄改）
- **R**epudiation（不可否認性）
- **I**nformation Disclosure（資訊洩漏）
- **D**enial of Service（阻斷服務）
- **E**levation of Privilege（權限提升）

## 輸出格式

### 威脅矩陣
| 威脅類型 | 元件 | 攻擊向量 | 影響 | 可能性 | 風險等級 | 緩解措施 |
|---------|------|---------|------|--------|---------|---------|

### 資料流圖
[Mermaid 圖表]

## 參考標準
- OWASP Top 10 (2021)
- CWE/SANS Top 25
- NIST SP 800-53

---
# .claude/rules/security.md
paths:
  - "src/**/*.java"
  - "src/**/*.ts"
---

# 安全編碼規範

## 輸入驗證（OWASP A03: Injection）
- 所有外部輸入必須使用白名單驗證
- SQL 查詢必須使用 PreparedStatement 或 JPA 參數化
- 禁止字串拼接 SQL
- URL 參數必須進行 URL 解碼後再驗證

## 認證與授權（OWASP A01: Broken Access Control）
- 密碼必須使用 BCrypt 或 Argon2 雜湊
- JWT Token 必須設定合理的過期時間（建議 15 分鐘）
- Refresh Token 必須存放在 HttpOnly Cookie
- 所有 API 端點必須驗證授權

## 敏感資料保護（OWASP A02: Cryptographic Failures）
- 禁止在日誌中輸出密碼、Token、個人資料
- 傳輸中資料必須使用 TLS 1.2+
- 靜態資料使用 AES-256 加密
- API Key 和密碼必須存放在環境變數或 Vault

## XSS 防護（OWASP A07: Cross-Site Scripting）
- 所有使用者輸出必須進行 HTML 編碼
- Content-Security-Policy Header 必須設定
- 禁止使用 innerHTML（前端）
- 使用 sanitize 函式庫處理 Rich Text

## CSRF 防護
- 所有狀態變更操作必須使用 CSRF Token
- SameSite Cookie 屬性設定為 Strict 或 Lax

{
  "hooks": {
    "PostToolUse": [
      {
        "name": "security-scan-on-edit",
        "matcher": "Edit",
        "if": "path matches '**/*.java'",
        "command": "bash .claude/hooks/security-scan.sh $CLAUDE_FILE_PATH",
        "description": "每次編輯 Java 檔案後自動執行安全掃描"
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/security-scan.sh
FILE_PATH="$1"

# 檢查常見安全問題
echo "=== Security Scan: $FILE_PATH ==="

# 1. SQL Injection 檢查
if grep -n "Statement\|createQuery.*+" "$FILE_PATH" 2>/dev/null; then
    echo "WARNING: Potential SQL Injection - Use PreparedStatement"
fi

# 2. 硬編碼密碼檢查
if grep -inE "password\s*=\s*\"[^\"]+\"|api_key\s*=\s*\"" "$FILE_PATH" 2>/dev/null; then
    echo "CRITICAL: Hard-coded credentials detected"
fi

# 3. 不安全的隨機數
if grep -n "java.util.Random" "$FILE_PATH" 2>/dev/null; then
    echo "WARNING: Use SecureRandom instead of Random for security purposes"
fi

# 4. 日誌中的敏感資訊
if grep -nE "log\.(info|debug|warn|error).*password|log\.(info|debug|warn|error).*token" "$FILE_PATH" 2>/dev/null; then
    echo "WARNING: Sensitive data may be logged"
fi

echo "=== Scan Complete ==="

# .github/workflows/security-scan.yml
name: Security Scan
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  sast:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: OWASP Dependency Check
        uses: dependency-check/Dependency-Check_Action@main
        with:
          project: 'my-project'
          path: '.'
          format: 'HTML'
          
      - name: SpotBugs Security
        run: mvn spotbugs:check -Dspotbugs.effort=max
        
      - name: Claude Security Review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          command: |
            使用 security-agent 審查此 PR 的安全性：
            1. OWASP Top 10 風險
            2. 敏感資料暴露
            3. 認證/授權問題
            4. 輸入驗證缺失

# CLI 啟用
claude --sandbox

# 或在對話中切換
> /sandbox

{
  "sandbox": {
    // 啟用沙箱
    "enabled": true,
    // 無法使用沙箱時的行為：true=報錯停止，false=退回正常模式
    "failIfUnavailable": false,
    // 沙箱啟用時自動允許 Bash 指令（不再逐一確認）
    "autoAllowBashIfSandboxed": true,
    // 排除不進沙箱的指令（如需要存取主機資源的）
    "excludedCommands": ["docker", "kubectl"],
    // 允許在沙箱外執行的指令（需明確列出）
    "allowUnsandboxedCommands": ["git"],
    
    // 網路設定
    "network": {
      // 允許沙箱內的網路存取（預設 false）
      "allowNetworkAccess": false,
      // 白名單域名
      "allowedDomains": ["registry.npmjs.org", "repo.maven.apache.org"]
    },
    
    // 檔案系統設定
    "filesystem": {
      // 額外掛載的唯讀路徑
      "readonlyPaths": ["/etc/ssl/certs"],
      // 額外掛載的可寫路徑
      "writablePaths": ["/tmp/build-output"]
    }
  }
}

# 合規性檢查指令
> 檢查此專案是否符合以下標準：
> 1. OWASP Top 10 (2021) — 逐項對照
> 2. OWASP ASVS Level 2
> 3. 銀行業 FISC 安全基準
> 4. 個資法（GDPR / 台灣個資法）相關要求
>
> 產出合規性差距分析報告

# SSDLC 整合流程
> 設計 SSDLC 安全閘門：
> - 需求階段：威脅建模 Gate
> - 設計階段：架構安全審查 Gate
> - 開發階段：SAST 掃描 Gate（每次 commit）
> - 測試階段：DAST 掃描 Gate
> - 部署階段：合規性驗證 Gate
> - 維運階段：持續監控 Gate

# 1. 檢查 CLAUDE.md 是否需要更新
> 審查 CLAUDE.md 的規則是否過時，建議更新項目

# 2. 審查 Skills 使用頻率
# 查看 PreToolUse hook 的使用日誌
cat .claude/hooks/usage.log | sort | uniq -c | sort -rn

# 3. 清理自動記憶
# 審查 ~/.claude/projects/<project>/memory/ 中的自動記憶
# 刪除過時或錯誤的記憶

# 1. 使用 /context 監控用量
> /context

# 2. 帶提示的 /compact（比自動 compact 好很多）
> /compact 保留認證模組的進度，移除測試除錯的 context

# 3. 使用 Subagent 做探索性搜尋
> 使用 subagent 搜尋所有使用 deprecated API 的檔案，只回報清單

# 4. 使用 Fast Mode 處理簡單任務（beta）
> /fast  # 使用較小模型處理簡單任務，節省 token

# 在對話中切換模型
> /model opus      # 切換到 Opus（規劃階段）
> /model sonnet    # 切換到 Sonnet（實作階段）
> /fast            # 開啟 Fast Mode（簡單任務）

# 使用 Adaptive Thinking 控制推理深度（Opus 4.7）
# low → medium → high → xhigh → max
# low：最快、最省 token
# max：最智能、最花 token

# 查看使用量和計畫限制
> /usage

# 設定 extra-usage 溢出計費
> /extra-usage

# 將所有 Claude Code 設定納入版本控制
.claude/
├── settings.json          # ✅ 進版控
├── settings.local.json    # ❌ 不進版控（.gitignore）
├── agents/                # ✅ 進版控
├── commands/              # ✅ 進版控
├── skills/                # ✅ 進版控
├── hooks/                 # ✅ 進版控
└── rules/                 # ✅ 進版控

# .gitignore 中排除的項目
# .claude/settings.local.json
# .claude/hooks/*.log
# .claude/audit.log

# 1. 更新 Claude Code CLI
npm update -g @anthropic-ai/claude-code

# 2. 閱讀 changelog 了解新功能
claude changelog
# 或查看 GitHub: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md

# 3. 檢查 settings.json 是否需要更新
# 新版本可能增加新的設定項
> 檢查目前的 .claude/settings.json 是否有需要更新的設定項

# 4. 測試現有 Hooks 和 Skills 是否相容
> 執行所有 skills 和 hooks 的冒煙測試

# 5. 更新團隊文件
> 更新 CLAUDE.md 和 .claude/rules/ 中的過時規則

# Prompt 版本管理策略
prompts/
├── v1/
│   ├── plan.md
│   └── review.md
├── v2/
│   ├── plan.md         # 改進版
│   └── review.md       # 改進版
└── current/            # 符號連結到最新版
    ├── plan.md -> ../v2/plan.md
    └── review.md -> ../v2/review.md

<!-- Agent 最佳化檢查清單 -->

## 每月 Agent 審查
- [ ] 檢查每個 Agent 的使用頻率
- [ ] 審查 Agent 的權限是否過大
- [ ] 更新 Agent 的 tools / disallowedTools 設定
- [ ] 調整 Agent 使用的模型（成本 vs 品質）
- [ ] 檢查 Agent 定義檔的行數是否過多
- [ ] 更新 Gotchas section
- [ ] 刪除不再使用的 Agent

## Agent 效能指標
- 任務完成率
- 平均 context 使用量
- 錯誤率
- 人工介入率

{
  // 啟用的 Plugin 列表
  "enabledPlugins": [
    "github:owner/repo",        // GitHub 倉庫
    "npm:package-name",         // npm 套件
    "directory:/path/to/plugin" // 本地目錄
  ],
  
  // 已知 Marketplace（預設 + 自訂）
  "extraKnownMarketplaces": [
    "https://marketplace.company.com"
  ],
  
  // 嚴格模式：僅允許已知 Marketplace 的 Plugin
  "strictKnownMarketplaces": true,
  
  // 封鎖的 Marketplace
  "blockedMarketplaces": [
    "https://untrusted.example.com"
  ]
}

# 1. 閱讀 repo 如同一門課程
# 先理解 Commands、Agents、Skills、Hooks 各自是什麼

# 2. Clone 並實際操作範例
git clone https://github.com/shanraisshan/claude-code-best-practice
cd claude-code-best-practice
claude
> /weather-orchestrator    # 試跑 Orchestration Workflow

# 3. 將最佳實踐應用到自己的專案
> 分析我的專案，建議應該從 claude-code-best-practice 中採用哪些實踐

# 建立團隊共用的 Starter Repository
team-claude-starter/
├── CLAUDE.md                    # 團隊通用規則
├── .claude/
│   ├── settings.json            # 團隊通用設定
│   ├── agents/
│   │   ├── backend-agent.md     # 團隊標準 Agent
│   │   ├── frontend-agent.md
│   │   └── security-agent.md
│   ├── commands/
│   │   ├── plan.md
│   │   ├── review.md
│   │   └── ship.md
│   ├── skills/
│   │   ├── code-review/
│   │   ├── security-scan/
│   │   └── api-design/
│   ├── hooks/
│   │   ├── security-check.sh
│   │   └── auto-format.sh
│   └── rules/
│       ├── coding-standards.md
│       └── security.md
├── .mcp.json                    # 團隊 MCP 設定
└── .github/
    └── workflows/
        └── claude-review.yml    # CI/CD 整合

## AI Code Review Checklist

### 功能正確性
- [ ] 邏輯是否正確
- [ ] 邊界條件是否處理
- [ ] 錯誤處理是否完整

### 安全性
- [ ] 輸入驗證是否到位
- [ ] 是否有 SQL Injection 風險
- [ ] 是否有 XSS 風險
- [ ] 敏感資料是否暴露

### 可維護性
- [ ] 命名是否清晰
- [ ] 是否有適當註解
- [ ] 是否遵循架構規範
- [ ] 是否有過度工程

### 效能
- [ ] 是否有 N+1 查詢問題
- [ ] 是否有不必要的迴圈
- [ ] 是否有記憶體洩漏風險

### 測試
- [ ] 是否有對應的單元測試
- [ ] 測試案例是否涵蓋邊界條件
- [ ] 是否有整合測試

# 在 PR 中 tag @claude 做自動 Review
# Claude GitHub App 會自動分析 PR

# 或使用 CLI 進行 Review
> /code-review

# 進階：將重複的 review 反饋轉成 lint 規則
# Boris: "tag @claude on a coworker's PR to auto-generate lint rules
# for recurring review feedback — automate yourself out of code review"

## 專案初始化 Checklist

### 環境設定
- [ ] 安裝 Claude Code CLI（最新版）
- [ ] 設定終端環境（iTerm/Ghostty/Windows Terminal）
- [ ] 安裝 VS Code Claude Code Extension（如需要）
- [ ] 設定認證（claude auth login）
- [ ] 執行 /doctor 驗證安裝

### 專案結構
- [ ] 建立 CLAUDE.md（< 200 行）
- [ ] 建立 .claude/settings.json
- [ ] 建立 .claude/rules/（延遲載入規則）
- [ ] 建立 .claude/agents/（功能導向 Agent）
- [ ] 建立 .claude/commands/（常用工作流）
- [ ] 建立 .claude/skills/（重複使用的技能）
- [ ] 建立 .claude/hooks/（安全和品質 Hook）
- [ ] 建立 .mcp.json（外部工具整合）

### 安全設定
- [ ] 設定 permissions allow/deny 清單
- [ ] 設定 PreToolUse 安全 Hook
- [ ] 禁止修改敏感檔案（.env, secrets/）
- [ ] 設定 SQL 只讀 Hook（如適用）
- [ ] 設定 audit log Hook

### CI/CD 整合
- [ ] 設定 GitHub Actions Claude Review workflow
- [ ] 設定安全掃描 workflow
- [ ] 測試 CI 流程

## 每日開發 Checklist

### 早上啟動
- [ ] 更新 Claude Code（npm update -g @anthropic-ai/claude-code）
- [ ] 閱讀 changelog
- [ ] 查看 Git 狀態
- [ ] 開啟 Plan Mode 規劃今日任務

### 開發中
- [ ] 使用 Plan Mode 規劃複雜任務
- [ ] 監控 /context 用量（保持 < 40%）
- [ ] 新任務用新 session
- [ ] 探索性任務用 Subagent
- [ ] 每小時至少 commit 一次
- [ ] 使用帶提示的 /compact

### Code Review
- [ ] 使用 /code-review 做 AI Review
- [ ] 每個 PR 保持小而專注（p50: 118 行）
- [ ] 使用 squash merge

### 下班前
- [ ] 確認所有測試通過
- [ ] 提交 PR
- [ ] /rename session（方便明天續接）

## 安全開發 Checklist

### 程式碼安全
- [ ] 所有外部輸入已驗證
- [ ] SQL 查詢使用參數化
- [ ] 無硬編碼密碼或 API Key
- [ ] 日誌不輸出敏感資訊
- [ ] XSS 防護到位
- [ ] CSRF Token 已設定

### Claude Code 安全
- [ ] permissions deny 清單已設定
- [ ] 敏感檔案保護 Hook 已啟用
- [ ] SQL 只讀 Hook 已設定
- [ ] Audit log 已啟用
- [ ] 不使用 dangerously-skip-permissions
- [ ] 使用 Auto Mode 或 /sandbox

### CI/CD 安全
- [ ] SAST 掃描已整合
- [ ] DAST 掃描已整合
- [ ] 依賴安全檢查已設定
- [ ] Claude Security Review 已整合
- [ ] API Key 使用 Secrets 管理

## 團隊導入 Checklist

### Phase 1（學習與試驗）
- [ ] 所有成員完成 Claude Code 安裝
- [ ] 完成基礎操作訓練
- [ ] 閱讀 claude-code-best-practice 文件
- [ ] 建立第一個 CLAUDE.md
- [ ] 完成第一次 AI Code Review

### Phase 2（標準化）
- [ ] 建立團隊共用 CLAUDE.md 範本
- [ ] 建立團隊共用 Agent 定義
- [ ] 建立 Security Hooks
- [ ] 整合 CI/CD
- [ ] 制定 AI Code Review 規範
- [ ] 建立 Skill Library

### Phase 3（全面採用）
- [ ] 量化指標追蹤已建立
- [ ] 每月 Agent 審查機制已建立
- [ ] 每季規則更新流程已建立
- [ ] 半年度安全審查已排程
- [ ] 跨團隊知識分享機制已建立

## Claude Code 升級 Checklist

### 升級前
- [ ] 備份 .claude/ 目錄設定
- [ ] 記錄目前版本號
- [ ] 閱讀目標版本的 changelog
- [ ] 檢查 breaking changes

### 升級中
- [ ] 執行 npm update -g @anthropic-ai/claude-code
- [ ] 驗證安裝：claude --version
- [ ] 執行 /doctor

### 升級後
- [ ] 測試 CLAUDE.md 載入
- [ ] 測試所有 Hooks 正常運作
- [ ] 測試所有 Skills 正常觸發
- [ ] 測試所有 Agents 正常分派
- [ ] 測試 MCP Server 連線
- [ ] 測試 CI/CD workflow
- [ ] 更新團隊文件