1. 快速原型開發
   - 從需求文字快速生成初版程式碼
   - 產生 API 骨架與資料模型

2. 遺留系統維護
   - 解讀複雜的舊程式碼
   - 漸進式重構建議

3. 程式碼審查輔助
   - 自動檢測潛在問題
   - 提供改善建議

4. 文件與測試生成
   - 自動產生 API 文件
   - 生成單元測試案例

5. 學習與教學
   - 解釋程式碼邏輯
   - 示範設計模式

1. 高度機密的商業邏輯
   - 需評估資料外洩風險
   - 考慮使用私有部署版本

2. 即時系統的關鍵路徑
   - AI 回應延遲不確定
   - 不適合作為線上服務依賴

3. 需要 100% 正確性的場景
   - AI 可能產生「看似正確但有缺陷」的程式碼
   - 永遠需要人工審查

4. 複雜的演算法開發
   - AI 擅長套用模式，但創新能力有限
   - 核心演算法仍需人工設計

# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell（原生安裝）
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

# 更新到最新版本
claude update

# macOS / Linux — Homebrew
brew install --cask claude-code

# Windows — WinGet
winget install Anthropic.ClaudeCode

# 從 VS Code Marketplace 搜尋 "Claude Code by Anthropic" 安裝
# 或命令列安裝
code --install-extension anthropic.claude-code

# 安裝完成後以 Cmd+Esc (macOS) 或 Ctrl+Esc (Windows/Linux) 啟動

# 方法 A：互動式登入（推薦，使用 OAuth）
claude login

# 方法 B：使用 API 金鑰
export ANTHROPIC_API_KEY="sk-ant-..."

# 方法 C：使用 AWS Bedrock
# 設定 AWS 認證環境變數即可

# 方法 D：使用 Google Vertex AI
# 設定 GCP 認證即可

全域配置
~/.claude/
├── settings.json          # 全域設定（hooks、permissions、MCP servers）
├── CLAUDE.md              # 全域指引（所有專案共用）
└── credentials.json       # 認證資訊（自動管理）

專案配置
專案根目錄/
├── .claude/
│   └── settings.json      # 專案設定（hooks、permissions）
├── .mcp.json              # MCP Server 配置（提交至 Git）
├── CLAUDE.md              # 專案級指引
├── AGENTS.md              # Agent 定義（可選）
└── .claudeignore          # 忽略檔案清單（類似 .gitignore）

企業配置
/etc/claude/               # Linux
~/Library/Application Support/claude/  # macOS
├── managed-settings.json  # 企業強制設定（管理員部署）
└── managed-mcp.json       # 企業級 MCP 配置

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Edit(*)",
      "Bash(npm test)",
      "Bash(npm run lint)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)"
    ]
  },
  "env": {
    "NODE_ENV": "development",
    "CLAUDE_CODE_MAX_TURNS": "50"
  }
}

# 專案指引

## 程式碼規範
- 使用 TypeScript strict mode
- 所有 public function 需要 JSDoc 註解
- 遵循 ESLint 配置的規則

## 測試要求
- 新功能必須有單元測試
- 測試覆蓋率不低於 80%
- 使用 vitest 作為測試框架

## 專案結構
- src/ — 原始碼
- tests/ — 測試檔案
- docs/ — 文件

## 常用命令
- `npm test` — 執行測試
- `npm run build` — 建構專案
- `npm run lint` — 程式碼檢查

1. 系統提示 (System Prompt)
   └── Anthropic 官方提供的基礎指引

2. 全域 CLAUDE.md
   └── ~/.claude/CLAUDE.md

3. 專案 CLAUDE.md
   └── 專案根目錄/CLAUDE.md

4. 目錄 CLAUDE.md（依層級）
   └── 工作目錄中各層級的 CLAUDE.md

5. .claude/settings.json 設定
   └── 專案設定覆蓋全域設定

6. .mcp.json MCP Server 連線
   └── 載入外部工具伺服器

7. Hooks 註冊
   └── 註冊事件鉤子

8. 使用者對話
   └── 開始接收使用者輸入

# 手動壓縮上下文
/compact

# 帶有自訂摘要指示的壓縮
/compact 保留所有與 API 設計相關的討論

瀏覽器 → claude.ai/code → 雲端虛擬機（沙箱）→ 執行程式碼
                                                  ↓
                                           可 clone GitHub repo
                                           可安裝依賴、執行測試
                                           可將變更推回 GitHub

# 啟動 Claude Code 並啟用 channel
claude --channels

# Channel MCP Server 需宣告 claude/channel 能力
# 詳見 4.4 節

📱 手機
  ↓ (Dispatch 指令)
💻 Desktop App (本機)
  ↓
🤖 Claude Code 執行任務
  ↓
📱 結果回傳手機

1. 使用者輸入 → UserPromptSubmit Hook 觸發
2. 載入上下文：
   - CLAUDE.md（全域 → 專案 → 目錄層級）
   - 對話歷史
   - 活動檔案內容
3. 組裝完整 prompt 發送至 Anthropic API

迴圈開始：
├── Claude 模型分析任務
├── 選擇並呼叫工具
│   ├── PreToolUse Hook → 權限檢查
│   ├── 執行工具（讀檔/寫檔/命令/搜尋）
│   ├── PostToolUse Hook → 結果處理
│   └── 將結果回傳模型
├── Claude 分析結果，決定下一步
└── 重複直到任務完成或達到 turn 上限

1. Stop Hook 觸發 → 可執行最終清理
2. TaskCompleted Hook 觸發（若有配置排程任務）
3. 結果呈現給使用者
4. 等待下一個使用者輸入或結束對話

# 記憶體管理命令
/memory                    # 檢視記憶體狀態
/memory add "偏好使用函數式風格"  # 新增記憶

1. 系統預設值
2. ~/.claude/settings.json（使用者全域設定）
3. .claude/settings.json（專案設定）
4. 環境變數
5. CLI 旗標與參數
6. Enterprise Policy（企業政策）
7. Managed Settings（管理員強制設定）

~/.claude/CLAUDE.md          ← 全域（所有專案共用）
      ↓
專案根目錄/CLAUDE.md          ← 專案級
      ↓
子目錄/CLAUDE.md              ← 目錄級（遞迴載入至工作目錄）
      ↓
CLAUDE.local.md               ← 本地覆蓋（不提交至 Git）

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Edit(src/**)",
      "Write(src/**)",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff *)",
      "mcp__github__*"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)",
      "Bash(curl * | bash)",
      "Edit(.env*)"
    ]
  }
}

✅ 推薦做法：
- 使用 allowlist（白名單）模式，明確列出允許的操作
- 限制 Bash 命令只允許已知安全的命令
- 在 .claude/settings.json 中設定專案特定權限
- 使用企業 Managed Settings 強制安全政策

❌ 避免做法：
- 不要在 allow list 中使用 Bash(*)（允許任何命令）
- 不要將 API 金鑰寫在 CLAUDE.md 或 settings.json 中
- 不要關閉權限提示系統

使用者: "修復 UserService.ts 中 getUserById 回傳 null 的問題"

Claude Code Agentic Loop:
┌─ Step 1: Read src/services/UserService.ts
│   → 找到 getUserById 方法
│
├─ Step 2: Grep "getUserById" in src/
│   → 找到相關呼叫位置
│
├─ Step 3: Read src/repositories/UserRepository.ts  
│   → 發現 Repository 的查詢有問題
│
├─ Step 4: Read tests/UserService.test.ts
│   → 確認原本的測試案例
│
├─ Step 5: Edit src/repositories/UserRepository.ts
│   → 修復查詢邏輯
│
├─ Step 6: Edit src/services/UserService.ts
│   → 增加 null check 和錯誤處理
│
├─ Step 7: Edit tests/UserService.test.ts
│   → 新增針對 null 的測試案例
│
├─ Step 8: Bash "npm test -- UserService"
│   → 測試通過 ✅
│
└─ Step 9: 回覆使用者修復結果和變更摘要

cd ~/projects/my-web-app
claude

╭───────────────────────────────────────────────────╮
│ Claude Code v1.x                                  │
│ Project: my-web-app                               │
│ Memory: CLAUDE.md loaded ✓                        │
╰───────────────────────────────────────────────────╯

You: 幫我了解這個專案的架構

Claude: 我來分析這個專案...
[Read] package.json
[Read] tsconfig.json
[Glob] src/**/*.ts
[Read] src/index.ts
[Read] src/routes/index.ts

這是一個 Express.js + TypeScript 的 REST API 專案，結構如下：
┌─────────────────────────────────────────┐
│ src/                                    │
│ ├── index.ts          # 應用程式入口     │
│ ├── routes/           # API 路由定義     │
│ ├── controllers/      # 控制器邏輯       │
│ ├── services/         # 業務邏輯層       │
│ ├── models/           # 資料模型         │
│ └── middleware/        # 中介軟體        │
└─────────────────────────────────────────┘
技術棧：Node.js 20, Express 4.18, TypeScript 5.4, Prisma ORM
資料庫：PostgreSQL 15
...

You: 根據這個專案的結構和程式碼，幫我建立一份 CLAUDE.md

Claude: 我先仔細分析專案結構...
[Read] package.json
[Read] tsconfig.json
[Read] .eslintrc.js
[Read] prisma/schema.prisma
[Bash] git log --oneline -10
[Write] CLAUDE.md

已建立 CLAUDE.md，包含：
- 專案概述與技術棧
- 編碼規範（從 eslint 配置推斷）
- 常用命令（build, test, lint, migrate）
- 架構說明
- 禁止事項

# My Web App

## 技術棧
- Runtime: Node.js 20 LTS
- Framework: Express.js 4.18
- Language: TypeScript 5.4 (strict mode)
- ORM: Prisma 5.x with PostgreSQL 15
- Testing: Jest + Supertest
- Linter: ESLint + Prettier

## 編碼規範
- 使用 camelCase 命名變數和函式
- 使用 PascalCase 命名類別和介面
- 所有函式必須有明確的回傳型別
- 不使用 any 型別
- 錯誤處理使用自訂 AppError 類別

## 常用命令
- `npm run dev` — 啟動開發伺服器
- `npm run build` — 編譯 TypeScript
- `npm test` — 執行全部測試
- `npm run test:watch` — 測試 watch 模式
- `npx prisma migrate dev` — 執行資料庫遷移
- `npx prisma generate` — 重新生成 Prisma Client

## 架構規範
- Controller 只負責解析請求和回傳回應
- Service 處理業務邏輯，不直接操作 HTTP
- Repository 模式封裝資料存取（透過 Prisma）
- 中介軟體處理認證、日誌、錯誤處理

## 禁止事項
- 不要修改 prisma/migrations/ 中的已存在遷移檔案
- 不要在 Controller 中直接操作資料庫
- 不要提交 .env 檔案
- 不要使用 console.log，請使用專案的 Logger

You: 新增一個 GET /api/v1/products 端點，支援分頁和搜尋

Claude: 我來實作這個端點...

[Read] src/routes/index.ts          # 了解現有路由結構
[Read] src/controllers/userController.ts  # 參考現有模式
[Read] prisma/schema.prisma         # 確認資料模型

需要建立/修改以下檔案：

1. 資料模型（如果不存在）
[Edit] prisma/schema.prisma           # 新增 Product model

2. 路由定義
[Edit] src/routes/index.ts            # 註冊 product 路由
[Write] src/routes/productRoutes.ts   # 產品路由

3. 控制器
[Write] src/controllers/productController.ts

4. 服務層
[Write] src/services/productService.ts

5. 測試
[Write] src/__tests__/products.test.ts

[Bash] npx prisma migrate dev --name add-product  # 執行遷移
[Bash] npm test                                     # 執行測試

✅ 所有測試通過。新增了 GET /api/v1/products 端點：
- 支援 ?page=1&limit=20 分頁
- 支援 ?search=keyword 全文搜尋
- 支援 ?category=electronics 過濾

You: 使用者回報登入後有時候 session 會遺失，幫我查一下

Claude: 我來調查這個問題...

[Grep] session|cookie|auth  # 搜尋相關程式碼
[Read] src/middleware/auth.ts
[Read] src/config/session.ts
[Bash] git log --all -20 --oneline -- src/middleware/ src/config/

找到可能的原因：

問題：在 src/config/session.ts 第 23 行
cookie.secure 設為 true，但在開發環境使用 HTTP
導致 session cookie 未被瀏覽器儲存

[Edit] src/config/session.ts   # 修正：根據環境設定 secure

修正內容：
- cookie.secure 改為 process.env.NODE_ENV === 'production'
- 新增 sameSite: 'lax' 屬性
- 確保 cookie.maxAge 與 session TTL 一致

[Bash] npm test  # 確認修正未破壞其他功能
✅ 測試全部通過

You: 把 userService.ts 裡重複的驗證邏輯抽取成獨立的 validator

Claude: 我先分析 userService.ts 中的重複模式...

[Read] src/services/userService.ts
[Grep] validate|check|verify  # 搜尋驗證邏輯

發現 3 處重複的驗證邏輯：
1. createUser() — email 格式、密碼強度
2. updateUser() — email 格式（重複）
3. resetPassword() — 密碼強度（重複）

重構計畫：
1. 建立 src/validators/userValidator.ts
2. 抽取共用驗證函式
3. 更新 userService.ts 使用新的 validator
4. 新增 validator 測試

[Write] src/validators/userValidator.ts
[Edit] src/services/userService.ts     # 移除重複邏輯，改用 validator
[Write] src/__tests__/userValidator.test.ts

[Bash] npm test
✅ 所有測試通過（15 passed, 0 failed）
程式碼減少 47 行，消除了 3 處重複

✅ 自動觸發場景：
- 搜尋大量檔案（避免搜尋結果佔滿主 context）
- 處理獨立的子任務（如：修改模組 A 時順便修模組 B 的相依）
- 並行探索多個方案
- 分析大型程式碼庫

💡 手動觸發方式：
- 在 CLAUDE.md 中指引使用 subagent
- 透過自訂 Agent 定義
- 使用 /agents 命令

特性：
- 使用 Haiku 模型（快速、低成本）
- 只有唯讀工具（Read, Grep, Glob, Search）
- 適合「找到 X 在哪裡定義」這類探索任務
- 不會修改任何檔案

自動觸發場景：
- 需要搜尋符號定義位置
- 需要了解程式碼結構
- 需要找到相關檔案

特性：
- 使用 Sonnet 或 Opus 模型
- 可讀取檔案和搜尋程式碼
- 產出結構化的任務計畫
- 適合大型重構、架構變更

自動觸發場景：
- 複雜任務需要前期規劃
- 使用者明確要求 "先規劃再執行"

建議放置位置：
├── .claude/agents/          # 專案級 Agent 定義
├── ~/.claude/agents/        # 全域 Agent 定義
└── AGENTS.md                # 在專案根目錄定義（簡易方式）

---
name: "security-reviewer"
description: "專責安全審查的代理，檢查 OWASP Top 10 和常見漏洞"
argument-hint: "提供要審查的檔案路徑或描述"
model: "claude-sonnet-4-20250514"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Search
  - Bash(npm audit)
  - Bash(semgrep *)
context:
  - "docs/security-guidelines.md"
  - "CLAUDE.md"
hooks:
  agent:
    - event: "Stop"
      type: "command"
      command: "echo 'Security review completed' >> .claude/security-log.txt"
---

# Security Reviewer Agent

你是一位資深資安審查專家。你的任務是：

## 審查範圍
1. 檢查 OWASP Top 10 漏洞
2. 審查認證與授權邏輯
3. 檢查敏感資料處理
4. 驗證輸入驗證機制
5. 審查 SQL 注入和 XSS 防護

## 輸出格式
使用以下格式回報：
- 🔴 **嚴重**: [問題描述] — [修復建議]
- 🟡 **警告**: [問題描述] — [修復建議]  
- 🟢 **良好**: [已正確實作的部分]

## 規則
- 不修改任何檔案，只產出審查報告
- 優先檢查面向外部的 API 端點
- 特別注意第三方依賴的已知漏洞

# 在 Claude Code 對話中查看可用 Agent
/agents

# 輸出範例：
# Available agents:
#   explore         - Fast read-only codebase exploration  
#   haiku           - Quick tasks using Haiku model
#   plan            - Complex task planning
#   security-reviewer - 專責安全審查的代理（自訂）
#   api-designer    - API 設計專家（自訂）

---
name: "api-designer"
description: "RESTful API 設計專家，負責設計符合 OpenAPI 規範的 API"
argument-hint: "描述需要設計的 API 功能"
model: "claude-sonnet-4-20250514"
allowed-tools:
  - Read
  - Write
  - Edit
  - Grep
  - Glob
  - Search
context:
  - "docs/api-conventions.md"
  - "openapi.yaml"
---

# API Designer Agent

你是 API 設計專家，專門設計符合團隊標準的 RESTful API。

## 設計原則
1. 遵循 RESTful 設計最佳實踐
2. 使用 OpenAPI 3.0 規範
3. 統一的錯誤回應格式
4. 版本化 API（URI 版本 /v1/）
5. 使用 HTTP 標準狀態碼

## 命名慣例
- 資源名稱使用複數形式（/users, /orders）
- 使用 kebab-case（/order-items）
- 查詢參數使用 camelCase（?pageSize=20）

## 回應格式
統一使用：
{
  "data": { ... },
  "meta": { "page": 1, "total": 100 },
  "errors": []
}

## 輸出要求
1. OpenAPI YAML 定義
2. 端點清單與說明
3. 請求/回應範例
4. 認證需求說明

# Claude Code 對話中：
使用者: 找出所有直接操作資料庫的 Controller，這違反了分層架構原則

# Claude Code 自動啟動 Explore subagent：
# → 使用 Grep 搜尋 Controller 中的 Repository/EntityManager 引用
# → 使用 Read 讀取可疑檔案
# → 回傳摘要結果給主代理
# 
# 主代理根據摘要提供完整分析報告

# Claude Code 對話中：
使用者: 將所有 API 端點從 /api/v1 遷移到 /api/v2，同時更新對應的測試

# Claude Code 可能的執行策略：
# 主代理: 規劃遷移策略
# → Subagent 1: 修改路由定義
# → Subagent 2: 更新整合測試
# → Subagent 3: 更新 API 文件
# 主代理: 整合所有變更，驗證一致性

# 呼叫自訂的 security-reviewer agent
使用者: @security-reviewer 請審查 src/auth/ 目錄下所有認證相關程式碼

# security-reviewer agent 執行：
# 1. 讀取 src/auth/ 下所有檔案
# 2. 使用 Grep 搜尋常見漏洞模式
# 3. 分析認證流程
# 4. 產出安全審查報告

# CLAUDE.md

## Subagent 使用指引

### 搜尋策略
- 搜尋超過 3 個檔案時，使用 subagent 進行探索
- 大型程式碼分析任務優先使用 Explore agent

### Agent 分工
- API 相關修改：使用 api-designer agent 先設計，再實作
- 安全相關變更：完成後必須使用 security-reviewer agent 審查
- 資料庫遷移：使用 Plan agent 先規劃遷移策略

---
name: "read-only-analyzer"
description: "唯讀分析器，只進行程式碼分析不做任何修改"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Search
  # 注意：不包含 Edit、Write、Bash —— 完全唯讀
---

---
name: "code-generator"
description: "程式碼生成代理"
hooks:
  agent:
    - event: "SubagentStart"
      type: "command"
      command: "echo '[$(date)] Code generator started' >> .claude/agent-log.txt"
    - event: "SubagentStop"
      type: "command"
      command: |
        echo '[$(date)] Code generator completed' >> .claude/agent-log.txt
        npm run lint --fix 2>/dev/null || true
---

---
name: "heavy-analyzer"
description: "深度程式碼分析代理"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Search
model: opus
effort: max
maxTurns: 50
permissionMode: "auto"
context: fork
---

# 前景執行（預設）
Claude: 我委派 security-reviewer 分析這段程式碼...
（等待 security-reviewer 完成）
Claude: 安全審查結果顯示...

# 背景執行
Claude: 我在背景啟動了 doc-generator 來產生文件，同時繼續處理你的修改需求...
（doc-generator 在背景執行）
Claude: 修改已完成。文件生成也在背景完成了，結果如下...

# 恢復之前的 Subagent 會話
Claude 使用 SendMessage 工具：
- target: "security-reviewer"  
- message: "請繼續檢查 controllers/ 目錄"
→ security-reviewer 在之前的 context 基礎上繼續工作

.claude/agents/
├── api-designer.md          # API 設計師
├── db-migration.md          # 資料庫遷移專家
├── frontend-component.md    # 前端元件開發
├── test-writer.md           # 測試撰寫專家
├── security-reviewer.md     # 安全審查員
└── performance-analyzer.md  # 效能分析師

---
name: "api-designer"
description: "設計 RESTful API 端點，產出 OpenAPI 規格"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Write
---

# API 設計專家

## 工作流程
1. 分析需求描述
2. 檢查現有 API 端點（src/routes/ 和 src/controllers/）
3. 設計新的 API 端點，遵循現有命名慣例
4. 產出 OpenAPI 3.0 規格片段
5. 撰寫 Controller 和 Route 程式碼

## 設計規範
- URL 使用 kebab-case 命名
- 使用 RESTful 動詞：GET（查詢）、POST（建立）、PUT（完整更新）、PATCH（部分更新）、DELETE（刪除）
- 分頁使用 cursor-based pagination
- 錯誤回應使用 RFC 7807 Problem Details 格式
- 所有端點需要驗證 JWT Token

## 回應格式
```json
{
  "方案摘要": "...",
  "新增端點": [
    {
      "method": "POST",
      "path": "/api/v1/...",
      "description": "...",
      "request_body": "...",
      "response": "..."
    }
  ],
  "需要修改的檔案": ["..."],
  "OpenAPI 規格": "..."
}

##### test-writer.md

```markdown
---
name: "test-writer"
description: "為指定模組撰寫完整的單元測試和整合測試"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Write
  - Bash
---

# 測試撰寫專家

## 測試策略
1. 先讀取目標原始碼，理解所有公開方法
2. 為每個公開方法撰寫測試案例
3. 測試案例包含：正常路徑、邊界條件、錯誤處理
4. 執行測試確認全部通過

## 測試模板
- 使用 describe/it 結構
- 採用 AAA（Arrange-Act-Assert）模式
- Mock 外部依賴（資料庫、API 呼叫）
- 測試檔案放在 __tests__/ 或 *.test.ts 中

## 覆蓋率要求
- 行覆蓋率 > 80%
- 分支覆蓋率 > 70%
- 所有公開方法 100% 覆蓋

---
name: "performance-analyzer"
description: "分析程式碼效能瓶頸，提供具體優化建議"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Search
---

# 效能分析專家

## 分析重點
1. **資料庫查詢**：N+1 問題、缺少索引、不必要的 JOIN
2. **記憶體使用**：大陣列操作、記憶體洩漏、不必要的物件複製
3. **API 效能**：回應時間、Payload 大小、快取策略
4. **前端效能**：Bundle 大小、渲染效能、圖片優化

## 輸出格式
| 問題 | 位置 | 嚴重度 | 建議修復 | 預期改善 |
|------|------|--------|---------|---------|
| ... | file:line | 高/中/低 | ... | ~30% 改善 |

# CLAUDE.md

## 功能開發標準流程

當要開發新功能時，按以下順序執行：

### Step 1: 設計
- 使用 `api-designer` agent 設計 API
- 輸出 OpenAPI 規格和程式碼架構

### Step 2: 實作
- 主 Agent 根據設計結果實作程式碼
- 包含 Controller、Service、Repository、Model

### Step 3: 測試
- 使用 `test-writer` agent 撰寫測試
- 確保覆蓋率達標

### Step 4: 資料庫
- 如需 DB 變更，使用 `db-migration` agent
- 產出 migration 檔案

### Step 5: 安全審查
- 使用 `security-reviewer` agent 進行安全掃描
- 修復所有「高」嚴重度問題

### Step 6: 效能分析
- 使用 `performance-analyzer` agent 分析效能
- 修復所有效能瓶頸

# 🆕 先啟用實驗性功能旗標
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# 以 Cowork 模式啟動（成為 Lead Agent）
claude --cowork

# 或在互動模式中使用 /agents 啟動
> /agents

# 也可以在互動式會話中使用 /leaders 或 /teammates 命令管理

Agent Teams 共享任務清單：
┌────┬────────────────────────┬───────────┬──────────┐
│ ID │ 任務描述                │ 負責人     │ 狀態      │
├────┼────────────────────────┼───────────┼──────────┤
│ 1  │ 重構 UserService 認證   │ Teammate 1│ ✅ 完成   │
│ 2  │ 新增 BatchOrderAPI      │ Teammate 2│ 🔄 進行中 │
│ 3  │ 更新單元測試            │ Teammate 3│ ⏳ 等待中 │
│ 4  │ 整合測試                │ Lead Agent│ ⏳ 等待中 │
└────┴────────────────────────┴───────────┴──────────┘

Lead Agent → [Mailbox] → Teammate 1
  "請優先處理認證中介層的重構"

Teammate 1 → [Mailbox] → Lead Agent
  "認證重構完成，發現需要同步更新 middleware/auth.ts"

Lead Agent → [Mailbox] → Teammate 2
  "注意 auth middleware 有變更，請在你的 worktree 中 pull 最新程式碼"

# 使用 tmux 分割面板顯示 (macOS/Linux)
# Agent Teams 會自動偵測 tmux 環境
tmux
claude --cowork  # 每個 Teammate 自動在獨立 pane 中顯示

# 使用者在 Cowork 模式下的對話：

User: 我需要同時完成以下三個任務：
      1. 重構 UserService，將認證邏輯抽離
      2. 為 OrderAPI 新增批次查詢端點
      3. 更新所有相關的單元測試

Lead Agent: 我會建立三個並行工作流來處理這些任務。

[建立 worktree: .worktrees/refactor-auth]
  → Teammate 1: 重構 UserService 認證邏輯

[建立 worktree: .worktrees/batch-order-api]
  → Teammate 2: 新增 OrderAPI 批次查詢端點

[建立 worktree: .worktrees/update-tests]
  → Teammate 3: 等待前兩個任務完成後更新測試

Status:
  ✓ Teammate 1: 正在分析 UserService 依賴...
  ✓ Teammate 2: 正在建立 BatchOrderController...
  ○ Teammate 3: 等待中...

{
  "hooks": {
    "TeammateIdle": [
      {
        "type": "command",
        "command": "echo '[$(date)] Teammate idle in $(pwd)' >> .claude/team-log.txt"
      }
    ],
    "WorktreeCreate": [
      {
        "type": "command",
        "command": "echo '[$(date)] Worktree created: $WORKTREE_PATH' >> .claude/team-log.txt"
      }
    ],
    "WorktreeRemove": [
      {
        "type": "command",
        "command": "echo '[$(date)] Worktree removed: $WORKTREE_PATH' >> .claude/team-log.txt"
      }
    ]
  }
}

任務：實作「使用者通知偏好設定」功能

Lead Agent 計劃：
├── Teammate 1 (worktree: notification-backend)
│   ├── 建立 NotificationPreference 模型
│   ├── 實作 CRUD API 端點
│   └── 新增資料庫 migration
├── Teammate 2 (worktree: notification-frontend)
│   ├── 建立偏好設定頁面元件
│   ├── 實作表單驗證邏輯
│   └── 串接後端 API
└── Teammate 3 (worktree: notification-tests)
    ├── 等待 Teammate 1 & 2 完成
    ├── 撰寫後端 API 整合測試
    └── 撰寫前端元件測試

任務：將 Monolith 中的 Payment 模組拆分為獨立微服務

Lead Agent 計劃：
├── Teammate 1 (worktree: extract-payment-service)
│   └── 抽離 Payment 相關程式碼到新模組
├── Teammate 2 (worktree: update-api-gateway)
│   └── 更新 API Gateway 路由配置
├── Teammate 3 (worktree: migrate-database)
│   └── 建立獨立的 Payment 資料庫 schema
└── 整合順序：Teammate 3 → Teammate 1 → Teammate 2

任務：對 PR #1234 進行全面審查

Lead Agent 計劃：
├── Teammate 1: 安全性審查（SQL Injection、XSS、認證）
├── Teammate 2: 效能審查（N+1 查詢、記憶體洩漏、索引）
├── Teammate 3: 架構合規審查（設計模式、SOLID 原則）
└── Lead Agent: 彙整所有審查意見並生成統一報告

You: 使用 pipeline 模式實作使用者認證功能：
     1. 先設計 API 規格（OpenAPI）
     2. 按照規格實作後端
     3. 按照規格實作前端
     4. 整合測試

You: 使用專家模式重新設計購物車系統

Lead Agent 分配：
├── 架構師 Agent（使用 opus 模型）
│   └── 設計整體架構、定義介面
├── 後端專家 Agent  
│   └── 實作 API 和業務邏輯
├── 前端專家 Agent
│   └── 實作 UI 元件和狀態管理
├── DBA 專家 Agent
│   └── 設計 database schema 和最佳化查詢
└── QA 專家 Agent
    └── 撰寫測試計畫和自動化測試

{
  "hooks": {
    "TeammateNotification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '[Teammate Update] $(date)' >> .claude/cowork-log.txt"
          }
        ]
      }
    ],
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Worktree created: ${CLAUDE_WORKTREE_PATH}' >> .claude/worktree-log.txt"
          }
        ]
      }
    ],
    "WorktreeRemove": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Worktree removed: ${CLAUDE_WORKTREE_PATH}' >> .claude/worktree-log.txt"
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/notify-teammate-done.js"
          }
        ]
      }
    ]
  }
}

# 在 Claude Code 會話中直接使用
> /debug 這個 API 調用總是回傳 401，但 token 是有效的

Claude Code 會啟動系統化偵錯流程：
1. 檢查 HTTP 請求 headers
2. 驗證 token 格式與過期時間
3. 追蹤認證中介層邏輯
4. 識別出 Bearer prefix 缺失問題

> /batch 將所有 .java 檔案中的 javax.persistence 改為 jakarta.persistence

Claude Code 會：
1. 掃描所有 .java 檔案
2. 列出受影響的檔案清單
3. 逐一執行替換
4. 驗證編譯是否通過

---
name: java-entity-generator
description: >
  根據資料庫 Schema 描述或 DDL 語句，自動生成符合 JPA 規範的
  Java Entity 類別，支援 Lombok、Builder Pattern 等選項。
---

# Java Entity Generator

## 使用時機

當使用者需要：
- 從資料庫表結構生成 Java Entity
- 建立新的 JPA 實體類
- 將 DDL 轉換為 Java 程式碼

## 操作步驟

1. 分析使用者提供的表結構資訊或 DDL
2. 確認目標套件路徑和命名規範
3. 生成 Entity 類別，包含：
   - 適當的 JPA 註解（@Entity, @Table, @Column 等）
   - 主鍵策略（@Id, @GeneratedValue）
   - 關聯映射（@OneToMany, @ManyToOne 等）
   - Auditing 欄位（@CreatedDate, @LastModifiedDate）
4. 如啟用 Lombok，加入 @Data, @Builder 等註解
5. 生成對應的 Repository 介面

## 輸出格式

- 使用專案現有的程式碼風格
- 遵循專案的套件結構慣例
- 包含必要的 import 陳述式

## 範例

輸入：使用者表，包含 id、username、email、created_at
輸出：User.java Entity + UserRepository.java

---
name: spring-migration
description: 將 Spring Boot 2.x 專案遷移至 3.x
argument-hint: "指定目標 Spring Boot 版本（如 3.2.0）"
allowed-tools:
  - Read
  - Edit
  - Bash(mvn *)
  - Bash(./gradlew *)
model: opus
effort: max
paths:
  - "src/main/java/**"
  - "pom.xml"
  - "build.gradle"
shell: bash
---

---
name: test-file
description: 為指定檔案生成測試
---

# 為 $1 生成測試

讀取 $1 的內容，並使用 ${CLAUDE_SKILL_DIR}/templates/test-template.ts 
作為模板生成對應的測試檔案。

{
  "permissions": {
    "allow": [
      "Skill(spring-migration)",
      "Skill(security-review)"
    ],
    "deny": [
      "Skill(dangerous-skill)"
    ]
  }
}

export SLASH_COMMAND_TOOL_CHAR_BUDGET=50000  # 預設值

---
name: explain
description: 解釋指定的程式碼或概念
user-invocable: true
---

請詳細解釋以下內容：$ARGUMENTS

使用者呼叫方式：

---
name: review-changes
description: 審查目前的 git 變更
---

# 審查目前變更

以下是目前的 git diff：
!`git diff --staged`

請根據以上變更進行程式碼審查。

---
# .claude/agents/security-reviewer.md
name: security-reviewer
description: 安全性程式碼審查代理
skills:
  - name: owasp-checker
    description: 檢查 OWASP Top 10 安全漏洞
    file: .claude/skills/owasp-checker/SKILL.md
  - name: dependency-auditor
    description: 檢查第三方依賴的已知漏洞
    file: .claude/skills/dependency-auditor/SKILL.md
tools:
  - Bash
  - Read
  - Grep
---

# Security Reviewer Agent

## 審查流程
1. 載入 owasp-checker 和 dependency-auditor Skills
2. 掃描目標程式碼
3. 依照 OWASP Top 10 逐項檢查
4. 執行 npm audit / mvn dependency-check
5. 生成統一安全報告

✅ 好的 Skill 設計：
├── api-endpoint-generator    → 專注於生成 REST API 端點
├── unit-test-writer          → 專注於撰寫單元測試
├── sql-optimizer             → 專注於 SQL 查詢優化
└── changelog-generator       → 專注於生成變更日誌

❌ 不好的 Skill 設計：
└── do-everything-skill       → 範圍太廣，什麼都做

專案結構：
.claude/
└── skills/
    ├── api-endpoint-generator/
    │   └── SKILL.md
    ├── unit-test-writer/
    │   └── SKILL.md
    └── sql-optimizer/
        └── SKILL.md

---
name: spring-boot-api-generator
description: >
  根據業務需求描述，生成完整的 Spring Boot REST API 端點，
  包含 Controller、Service、Repository 三層架構程式碼，
  以及對應的 DTO、Exception Handler 和 Swagger 文件註解。
---

# Spring Boot API 端點產生器

## 觸發條件

當使用者請求以下操作時啟動：
- 建立新的 REST API 端點
- 為現有 Entity 新增 CRUD API
- 生成 Spring Boot Controller + Service + Repository

## 生成規範

### Controller 層
- 使用 @RestController 和 @RequestMapping
- 實作標準 HTTP 方法（GET/POST/PUT/DELETE）
- 加入 @Operation (Swagger) 註解
- 使用 @Valid 進行請求驗證
- 回傳適當的 HTTP 狀態碼

### Service 層
- 定義 Service 介面和實作類
- 實作業務邏輯和資料轉換
- 使用 @Transactional 管理交易
- 處理業務例外

### Repository 層
- 繼承 JpaRepository
- 定義自訂查詢方法
- 使用 @Query 處理複雜查詢

### DTO 層
- 建立 Request/Response DTO
- 使用 Jakarta Validation 註解
- 實作 Entity ↔ DTO 轉換

## 命名規範
- 遵循專案現有的命名慣例
- Controller: XxxController
- Service: XxxService / XxxServiceImpl
- Repository: XxxRepository
- DTO: XxxRequest / XxxResponse

---
# .claude/agents/backend-developer.md
name: backend-developer
description: Spring Boot 後端開發代理
skills:
  - name: spring-boot-api-generator
    description: 生成 Spring Boot REST API
    file: .claude/skills/api-endpoint-generator/SKILL.md
  - name: java-entity-generator
    description: 生成 JPA Entity
    file: .claude/skills/java-entity-generator/SKILL.md
---

# Backend Developer Agent
（Agent 的詳細指引...）

推薦的 Skills 目錄結構：

.claude/
├── skills/                          # 專案級 Skills
│   ├── code-generation/
│   │   ├── SKILL.md                 # API 產生器
│   │   └── templates/               # 可選：模板檔案
│   ├── testing/
│   │   └── SKILL.md                 # 測試產生器
│   └── documentation/
│       └── SKILL.md                 # 文件產生器
├── agents/                          # Agent 定義
│   └── backend-developer.md         # 引用上述 Skills
└── CLAUDE.md                        # 專案級指引

~/.claude/
└── skills/                          # 全域 Skills（所有專案共用）
    ├── personal-style/
    │   └── SKILL.md                 # 個人程式碼風格
    └── review-checklist/
        └── SKILL.md                 # 個人 code review 清單

---
name: migration-review
description: 審查資料庫遷移腳本的安全性、效能影響和向後相容性。
  支援 Prisma、TypeORM、Flyway、Liquibase 等遷移框架。
tools: read_file, grep_search, semantic_search
---

# Database Migration Review

## 審查清單

### 安全性
- 是否有資料遺失風險？（DROP TABLE, DROP COLUMN）
- 大表變更是否使用 online DDL？
- 是否需要資料回填（backfill）？

### 效能
- 是否在大表上建立索引？（需要 CONCURRENTLY）
- 是否有鎖表風險？
- 預估執行時間

### 向後相容性
- 新舊版本程式碼能否同時運行？
- 是否需要分階段部署？
  1. 先部署相容的程式碼
  2. 執行遷移
  3. 部署使用新 schema 的程式碼

## 輸出格式
| 項目 | 狀態 | 說明 |
|------|------|------|
| 資料安全 | ✅/⚠️/❌ | 詳細說明 |
| 效能影響 | ✅/⚠️/❌ | 預估影響 |
| 向後相容 | ✅/⚠️/❌ | 相容性分析 |
| 回滾方案 | 有/無 | 如何回滾 |

---
name: commit-message
description: 根據已暫存的變更生成 Conventional Commit 格式的 commit 訊息。
  支援 feat/fix/refactor/docs/test/chore 等類型。
tools: bash
---

# Commit Message Generator

## 分析步驟
1. 執行 `git diff --staged --stat` 查看變更摘要
2. 執行 `git diff --staged` 查看詳細變更
3. 根據變更內容判斷 commit 類型

## Commit 訊息格式
type(scope): 簡短描述

詳細說明（如果需要）

## 類型判斷規則
- feat: 新功能
- fix: Bug 修復
- refactor: 重構（不改變功能）
- docs: 文件變更
- test: 測試相關
- chore: 建置/工具改動
- perf: 效能改善
- style: 程式碼格式

## 範例
feat(auth): 新增 OAuth 2.0 Google 登入支援

- 實作 Google OAuth2 flow
- 新增 /api/auth/google callback endpoint
- 整合現有的 JWT token 系統

---
name: dependency-upgrade
description: 分析和執行專案依賴升級，包含安全漏洞修復、
  breaking changes 檢查、和升級路徑規劃。
tools: read_file, bash, write_file, grep_search
---

# Dependency Upgrade Skill

## 升級流程
1. 執行 `npm outdated` 或 `mvn versions:display-dependency-updates`
   了解哪些依賴有新版本
2. 檢查每個依賴的 CHANGELOG 和 breaking changes
3. 分類為：patch（安全）、minor（通常安全）、major（需要檢查）
4. 逐步升級，每次只升級一個 major 版本
5. 每次升級後執行測試

## 優先順序
1. 🔴 有已知 CVE 的依賴 → 立即升級
2. 🟡 Major 版本落後 2+ 的依賴 → 規劃升級
3. 🟢 Minor/Patch 更新 → 批量升級

## 輸出格式
| 套件 | 目前版本 | 最新版本 | 類型 | Breaking Changes | 建議 |
|------|---------|---------|------|-----------------|------|

{
  "name": "spring-boot-toolkit",
  "version": "1.0.0",
  "description": "Spring Boot 開發工具包，包含 API 生成器、Entity 生成器和測試輔助",
  "author": "DevTeam",
  "license": "MIT",
  "repository": "https://github.com/example/claude-spring-boot-toolkit",
  
  "agents": [
    {
      "name": "spring-boot-developer",
      "file": "agents/spring-boot-developer.md",
      "description": "Spring Boot 全棧開發代理"
    },
    {
      "name": "spring-test-writer",
      "file": "agents/spring-test-writer.md",
      "description": "Spring Boot 測試撰寫代理"
    }
  ],
  
  "skills": [
    {
      "name": "api-generator",
      "file": "skills/api-generator/SKILL.md",
      "description": "生成 REST API Controller + Service + Repository"
    },
    {
      "name": "entity-generator",
      "file": "skills/entity-generator/SKILL.md",
      "description": "生成 JPA Entity 和 Repository"
    }
  ],
  
  "commands": [
    {
      "name": "/spring-init",
      "file": "commands/spring-init.md",
      "description": "初始化 Spring Boot 專案結構"
    }
  ]
}

my-plugin/
├── .claude-plugin/
│   └── plugin.json                  # Plugin 清單檔（必要）
├── CLAUDE.md                        # Plugin 級指引（自動載入）
├── settings.json                    # 🆕 Plugin 的預設設定（agent 配置等）
├── .mcp.json                        # 🆕 Plugin 提供的 MCP Server 配置
├── .lsp.json                        # 🆕 Plugin 提供的 LSP Server 配置
├── agents/
│   ├── spring-boot-developer.md     # Agent 定義（YAML frontmatter + 指引）
│   └── spring-test-writer.md
├── skills/
│   ├── api-generator/
│   │   └── SKILL.md                 # Skill 定義
│   └── entity-generator/
│       └── SKILL.md
├── hooks/
│   └── hooks.json                   # 🆕 Plugin 提供的 Hook 定義
└── commands/
    └── spring-init.md               # 自訂 Slash Command

// .mcp.json（Plugin 根目錄）
{
  "mcpServers": {
    "my-plugin-server": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp-server/dist/index.js"],
      "env": {
        "DATA_DIR": "${CLAUDE_PLUGIN_DATA}"
      }
    }
  }
}

// .lsp.json（Plugin 根目錄）
{
  "servers": {
    "java": {
      "command": "jdtls",
      "args": ["--data", "${CLAUDE_PLUGIN_DATA}/jdtls-data"]
    }
  }
}

# 呼叫 Plugin 的 Skill
> /spring-boot-toolkit:api-generator 建立使用者管理 API

# 不帶命名空間時，Claude Code 會自動匹配最相關的 Skill
> /api-generator 建立使用者管理 API

# 🆕 從官方 Marketplace 搜尋
> /plugin marketplace search spring-boot

# 🆕 瀏覽分類
> /plugin marketplace browse --category "code-intelligence"

# 🆕 從 Marketplace 安裝
> /plugin marketplace add java

# 搜尋已發布的 Plugins
> /plugins search spring-boot

Found 5 plugins matching "spring-boot":
  1. spring-boot-toolkit (v1.0.0) - Spring Boot 開發工具包
  2. spring-security-helper (v0.8.0) - Spring Security 配置輔助
  ...

# 查看已安裝的 Plugins
> /plugins list

# 🆕 從官方 Marketplace 安裝
> /plugin marketplace add java

# 從 Git 倉庫安裝
> /install-plugin https://github.com/example/claude-spring-boot-toolkit

# 從本地目錄安裝（適合開發測試）
> /install-plugin /path/to/my-plugin

# 安裝特定版本
> /install-plugin spring-boot-toolkit@1.0.0

# 指定安裝範圍
> /install-plugin spring-boot-toolkit --scope project
> /install-plugin security-scanner --scope user

# 使用 --plugin-dir 載入本地 Plugin 進行測試（不需安裝）
claude --plugin-dir ./my-plugin-dev

# 重新載入所有 Plugins（無需重啟）
> /reload-plugins

# 強制更新所有插件
export FORCE_AUTOUPDATE_PLUGINS=1
claude

// ~/.claude/settings.json
{
  "extraKnownMarketplaces": [
    "https://github.com/your-org/claude-plugins-internal",
    "git@github.com:your-org/claude-plugins-private.git"
  ]
}

{
  "plugins": {
    "allowed": [
      "spring-boot-toolkit",
      "security-scanner",
      "code-quality-checker"
    ],
    "blocked": [
      "untrusted-plugin-*"
    ],
    "required": [
      "company-code-standards"
    ],
    "sources": {
      "allowedRegistries": [
        "https://plugins.company.internal"
      ]
    }
  }
}

# 建立 Plugin 目錄
mkdir -p .claude-plugin/{agents,skills,commands}

# 建立 plugin.json
cat > .claude-plugin/plugin.json << 'EOF'
{
  "name": "my-custom-plugin",
  "version": "0.1.0",
  "description": "我的自訂 Plugin",
  "author": "My Team"
}
EOF

<!-- .claude-plugin/agents/my-agent.md -->
---
name: my-custom-agent
description: 自訂的開發輔助代理
skills:
  - name: my-skill
    description: 自訂能力
    file: skills/my-skill/SKILL.md
tools:
  - Read
  - Edit
  - Write
  - Bash
---

# My Custom Agent

## 角色
你是一個專門處理 [特定領域] 的開發代理。

## 工作流程
1. 分析使用者需求
2. 搜尋相關程式碼
3. 執行變更
4. 驗證結果

<!-- .claude-plugin/skills/my-skill/SKILL.md -->
---
name: my-custom-skill
description: 專門處理 [特定任務] 的能力模組
---

# My Custom Skill

## 使用時機
（描述何時應該使用此 Skill）

## 操作步驟
（詳細的操作指引）

<!-- .claude-plugin/CLAUDE.md -->
# My Custom Plugin 指引

使用此 Plugin 時，請遵循以下原則：

1. 所有生成的程式碼必須通過 lint 檢查
2. 遵循專案現有的命名慣例
3. 變更前先確認不會破壞現有功能

{
  "name": "spring-boot-dev",
  "version": "1.0.0",
  "description": "Spring Boot 開發輔助工具集",
  "tools": [
    {
      "name": "spring-init",
      "description": "快速初始化 Spring Boot 模組（Controller, Service, Repository, DTO）",
      "command": "./tools/spring-init.sh",
      "args": ["--type", "{type}", "--name", "{name}", "--package", "{package}"]
    },
    {
      "name": "spring-test",
      "description": "生成 Spring Boot 測試（Unit, Integration, Slice Test）",
      "command": "./tools/spring-test.sh",
      "args": ["--target", "{target_class}", "--type", "{test_type}"]
    },
    {
      "name": "spring-actuator-check",
      "description": "檢查 Actuator 端點健康狀態並生成報告",
      "command": "./tools/actuator-check.sh",
      "args": ["--url", "{base_url}"]
    }
  ],
  "agents": [
    {
      "name": "spring-architect",
      "path": "./agents/spring-architect.md"
    }
  ],
  "skills": [
    { "path": "./skills/entity-design/" },
    { "path": "./skills/api-design/" },
    { "path": "./skills/security-config/" }
  ]
}

# agents/spring-architect.md

---
name: spring-architect
description: Spring Boot 架構顧問，負責設計 API、規劃模組結構、審查架構決策
model: claude-sonnet-4-20250514
skills:
  - ./skills/entity-design/
  - ./skills/api-design/
  - ./skills/security-config/
tools:
  - read_file
  - grep_search
  - semantic_search
  - spring-init
  - spring-test
---

## 角色
你是一位 Spring Boot 架構師，精通 Spring 生態圈所有核心模組。

## 設計原則
- 遵循 Clean Architecture / Hexagonal Architecture
- API 設計遵循 RESTful 最佳實踐
- 安全配置遵循 OWASP 指引
- 資料庫設計遵循 Third Normal Form

## 輸出標準
- 每個設計決策都要說明「為什麼」
- 提供替代方案的比較
- 附帶適當的 UML 圖（Mermaid 格式）

{
  "name": "react-component-toolkit",
  "version": "1.0.0",
  "description": "React 元件開發工具集，含 Storybook 整合",
  "tools": [
    {
      "name": "create-component",
      "description": "建立 React 元件（含 TSX, Styles, Tests, Stories）",
      "command": "./tools/create-component.sh",
      "args": ["--name", "{name}", "--type", "{type}"]
    },
    {
      "name": "a11y-audit",
      "description": "對元件執行無障礙可及性 (a11y) 檢查",
      "command": "./tools/a11y-audit.sh",
      "args": ["--component", "{component_path}"]
    }
  ],
  "agents": [
    {
      "name": "ui-reviewer",
      "path": "./agents/ui-reviewer.md"
    }
  ]
}

{
  "name": "security-compliance",
  "version": "2.0.0",
  "description": "自動化安全合規檢查，支援 OWASP/SOC2/GDPR",
  "tools": [
    {
      "name": "owasp-scan",
      "description": "執行 OWASP Top 10 漏洞掃描",
      "command": "./tools/owasp-scan.sh"
    },
    {
      "name": "secret-scan",
      "description": "掃描程式碼中的密鑰和敏感資料洩漏",
      "command": "./tools/secret-scan.sh"
    },
    {
      "name": "license-check",
      "description": "檢查所有依賴的授權協議合規性",
      "command": "./tools/license-check.sh"
    },
    {
      "name": "gdpr-check",
      "description": "檢查個人資料處理流程是否符合 GDPR",
      "command": "./tools/gdpr-check.sh"
    }
  ],
  "skills": [
    { "path": "./skills/threat-modeling/" },
    { "path": "./skills/compliance-report/" }
  ]
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "type": "command",
        "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\" 2>/dev/null || true"
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "type": "http",
        "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
        "method": "POST",
        "headers": {
          "Content-Type": "application/json"
        }
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "type": "prompt",
        "prompt": "在執行任何 Shell 命令前，請確認：1) 不包含 rm -rf 2) 不會修改系統檔案 3) 不包含敏感資訊"
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "type": "agent",
        "agent": "code-reviewer",
        "prompt": "請審查剛才的程式碼變更，確認是否符合團隊規範"
      }
    ]
  }
}

優先順序（由高到低）：
1. 專案級：.claude/settings.json
2. 使用者級：~/.claude/settings.json
3. 企業級：managed-settings.json（由組織管理員控制）

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "echo '[SESSION START] $(date)' >> .claude/session.log"
      }
    ],
    
    "UserPromptSubmit": [
      {
        "type": "command",
        "command": "echo '[PROMPT] $(date): ${PROMPT_PREVIEW}' >> .claude/audit.log"
      }
    ],
    
    "PreToolUse": [
      {
        "matcher": "Bash",
        "type": "command",
        "command": "bash .claude/hooks/check-bash-safety.sh"
      },
      {
        "matcher": "Write|Edit|MultiEdit",
        "type": "command",
        "command": "bash .claude/hooks/pre-write-check.sh"
      }
    ],
    
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "type": "command",
        "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\" 2>/dev/null; npx eslint --fix \"$TOOL_INPUT_FILE_PATH\" 2>/dev/null || true"
      }
    ],
    
    "Stop": [
      {
        "type": "http",
        "url": "https://hooks.slack.com/services/T.../B.../xxx",
        "method": "POST",
        "headers": { "Content-Type": "application/json" }
      },
      {
        "type": "command",
        "command": "echo '[STOP] $(date)' >> .claude/session.log"
      }
    ],
    
    "SessionEnd": [
      {
        "type": "command",
        "command": "bash .claude/hooks/cleanup.sh"
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "if": "tool_input.command contains 'rm' && tool_input.command contains '-rf'",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'BLOCK: 禁止 rm -rf 命令' >&2; exit 1"
          }
        ]
      },
      {
        "matcher": "Edit",
        "if": "tool_input.file_path matches '.*\\.lock$'",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'BLOCK: 禁止直接編輯 lock 檔案' >&2; exit 1"
          }
        ]
      }
    ]
  }
}

// Hook 輸出的 JSON 格式
{
  "hookSpecificOutput": {
    "permissionDecision": "allow"
  }
}

#!/bin/bash
# auto-permission.sh — 根據規則自動決定權限
TOOL_NAME="$CLAUDE_TOOL_NAME"
FILE_PATH="$CLAUDE_FILE_PATH"

# 對測試檔案自動允許
if echo "$FILE_PATH" | grep -qE '\.(test|spec)\.(ts|js)$'; then
  echo '{"hookSpecificOutput": {"permissionDecision": "allow"}}'
  exit 0
fi

# 對 production 目錄檔案要求確認
if echo "$FILE_PATH" | grep -q '/prod/'; then
  echo '{"hookSpecificOutput": {"permissionDecision": "ask"}}'
  exit 0
fi

exit 0

#!/bin/bash
# rewrite-path.sh — 自動修正檔案路徑
# Hook stdout 輸出 JSON，包含 updatedInput 欄位
echo "{\"updatedInput\": {\"file_path\": \"$(echo $CLAUDE_FILE_PATH | sed 's|src/old/|src/new/|')\"}}"

#!/bin/bash
# setup-env.sh — 在 SessionStart Hook 中設定持久環境
echo "PROJECT_VERSION=$(cat VERSION)" >> "$CLAUDE_ENV_FILE"
echo "BUILD_NUMBER=$(git rev-list --count HEAD)" >> "$CLAUDE_ENV_FILE"

{
  "disableAllHooks": true
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "type": "command",
        "command": "FILE=\"$TOOL_INPUT_FILE_PATH\"; case \"$FILE\" in *.ts|*.tsx|*.js|*.jsx) npx prettier --write \"$FILE\" 2>/dev/null;; *.java) google-java-format -i \"$FILE\" 2>/dev/null;; *.py) black \"$FILE\" 2>/dev/null;; esac || true"
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/check-bash-safety.sh
# 檢查即將執行的 Bash 命令是否安全

COMMAND="$TOOL_INPUT_COMMAND"

# 危險命令模式清單
DANGEROUS_PATTERNS=(
    "rm -rf /"
    "rm -rf ~"
    "mkfs"
    "dd if="
    "> /dev/sd"
    "chmod 777"
    "curl.*|.*sh"
    "wget.*|.*sh"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
    if echo "$COMMAND" | grep -qE "$pattern"; then
        echo "❌ BLOCKED: 偵測到潛在危險命令模式: $pattern"
        echo "命令: $COMMAND"
        exit 1  # 非零退出碼會阻止工具執行
    fi
done

echo "✅ 命令安全檢查通過"
exit 0

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "type": "command",
        "command": "FILE=\"$TOOL_INPUT_FILE_PATH\"; if echo \"$FILE\" | grep -qE '\\.(ts|js|java|py)$'; then echo '🧪 Running related tests...'; npm test -- --findRelatedTests \"$FILE\" 2>/dev/null || true; fi"
      }
    ]
  }
}

{
  "hooks": {
    "TaskCompleted": [
      {
        "type": "http",
        "url": "https://hooks.slack.com/services/T.../B.../xxx",
        "method": "POST",
        "headers": {
          "Content-Type": "application/json"
        }
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "type": "prompt",
        "prompt": "安全提醒：執行 Shell 命令前請確認：\n1. 不會刪除重要檔案\n2. 不會暴露敏感資訊（API keys、密碼等）\n3. 不會對生產環境造成影響\n如果命令有風險，請先向使用者確認。"
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/layer1-blocklist.sh"
          },
          {
            "type": "command",
            "command": "bash .claude/hooks/layer2-path-check.sh"
          },
          {
            "type": "prompt",
            "prompt": "Layer 3: 執行此命令前，請確認不會影響生產環境資料或系統穩定性"
          }
        ]
      },
      {
        "matcher": "write_file|edit_file",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/file-protection.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/layer1-blocklist.sh — 第一層：命令黑名單

BLOCKLIST=(
  "rm -rf /"
  "rm -rf ~"
  "rm -rf \$HOME"
  "mkfs"
  "dd if=/dev"
  "> /dev/sd"
  "chmod -R 777 /"
  ":(){ :|:& };:"
)

INPUT="$CLAUDE_TOOL_INPUT"
for pattern in "${BLOCKLIST[@]}"; do
  if echo "$INPUT" | grep -qF "$pattern"; then
    echo "BLOCK: 命令包含黑名單模式: $pattern" >&2
    exit 1
  fi
done
exit 0

#!/bin/bash
# .claude/hooks/layer2-path-check.sh — 第二層：路徑保護

PROTECTED_PATHS=(
  "/etc"
  "/usr"
  "/var/lib"
  "$HOME/.ssh"
  "$HOME/.aws"
  "$HOME/.kube"
)

INPUT="$CLAUDE_TOOL_INPUT"
for path in "${PROTECTED_PATHS[@]}"; do
  if echo "$INPUT" | grep -q "$path"; then
    echo "BLOCK: 命令涉及受保護路徑: $path" >&2
    exit 1
  fi
done
exit 0

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "write_file|edit_file",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/quality-pipeline.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/quality-pipeline.sh — 完整品質管道

FILE="$CLAUDE_FILE_PATH"
EXT="${FILE##*.}"
REPORT=""
PASS=true

# Stage 1: 格式化
case "$EXT" in
  ts|tsx|js|jsx)
    npx prettier --write "$FILE" 2>/dev/null
    RESULT=$(npx eslint "$FILE" 2>&1)
    if [ $? -ne 0 ]; then
      REPORT="$REPORT\n⚠️ ESLint: $(echo "$RESULT" | grep -c 'error') errors"
      npx eslint --fix "$FILE" 2>/dev/null
    fi
    ;;
  py)
    python -m black "$FILE" 2>/dev/null
    RESULT=$(python -m ruff check "$FILE" 2>&1)
    if [ $? -ne 0 ]; then
      REPORT="$REPORT\n⚠️ Ruff: $(echo "$RESULT" | wc -l) issues"
      python -m ruff check --fix "$FILE" 2>/dev/null
    fi
    ;;
  java)
    google-java-format --replace "$FILE" 2>/dev/null
    ;;
  go)
    gofmt -w "$FILE" 2>/dev/null
    RESULT=$(go vet "./$(dirname "$FILE")/..." 2>&1)
    if [ $? -ne 0 ]; then
      REPORT="$REPORT\n⚠️ Go vet: $(echo "$RESULT" | wc -l) issues"
    fi
    ;;
esac

# Stage 2: Type Checking (TypeScript/Java)
case "$EXT" in
  ts|tsx)
    RESULT=$(npx tsc --noEmit "$FILE" 2>&1)
    if [ $? -ne 0 ]; then
      REPORT="$REPORT\n❌ TypeScript: 型別錯誤"
      PASS=false
    fi
    ;;
esac

# Stage 3: 安全性快速掃描
if grep -qE "(eval\(|exec\(|__import__|subprocess\.call)" "$FILE" 2>/dev/null; then
  REPORT="$REPORT\n🔒 Security: 偵測到潛在危險函數呼叫"
fi

# 輸出報告
if [ -n "$REPORT" ]; then
  echo -e "📋 品質檢查報告 ($FILE):$REPORT"
fi

# 記錄到日誌
echo "[$(date -Iseconds)] Quality check: $FILE${REPORT:+ |$REPORT}" >> .claude/quality-log.txt

exit 0  # PostToolUse hook 不阻止操作

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'ENV=${CLAUDE_ENV:-development}; if [ \"$ENV\" = \"production\" ]; then echo \"BLOCK: 生產環境禁止執行 Shell 命令\" >&2; exit 1; fi'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "write_file|edit_file",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'ENV=${CLAUDE_ENV:-development}; if [ \"$ENV\" = \"development\" ]; then npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null; fi; if [ \"$ENV\" = \"staging\" ] || [ \"$ENV\" = \"production\" ]; then npx eslint \"$CLAUDE_FILE_PATH\" 2>&1 || true; fi'"
          }
        ]
      }
    ]
  }
}

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL:-postgresql://localhost:5432/devdb}"
      }
    },
    
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    },
    
    "custom-api": {
      "type": "sse",
      "url": "https://mcp.company.internal/api/sse",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

#### Transport 類型比較

| Transport | 配置方式 | 適用場景 | 說明 |
|-----------|---------|---------|------|
| **http**（🆕 推薦） | `url` | 遠端 MCP Server | HTTP Streamable Transport，最新推薦方式 |
| **sse** | `url` | 遠端 MCP Server | HTTP Server-Sent Events，舊版遠端方式 |
| **stdio** | `command` + `args` | 本地 MCP Server | 啟動本地程序，透過 stdin/stdout 通訊 |

> **📌 注意**：新專案建議使用 **HTTP Streamable Transport**（`"type": "http"`），它比 SSE 更穩定且支援雙向通訊。

#### 使用 Claude Code 互動式新增 MCP Server

```bash
# 使用 /mcp 命令互動式新增
> /mcp add github npx -y @modelcontextprotocol/server-github

# 列出已設定的 MCP Servers
> /mcp list

# 移除 MCP Server
> /mcp remove github

# 測試 MCP Server 連線
> /mcp status

# 推薦：自動模式（根據工具數量自動決定）
export ENABLE_TOOL_SEARCH=auto

# 強制啟用（適合連接大量 MCP Server 的場景）
export ENABLE_TOOL_SEARCH=1

# 在 VS Code 中使用 @ 引用 MCP 資源
@mcp:postgres/schema/users      → 引用 users 表的 schema 定義
@mcp:confluence/page/12345      → 引用 Confluence 頁面內容
@mcp:github/file/src/README.md  → 引用 GitHub 上的檔案

# 在 CLI 中使用
> 幫我分析 @mcp:postgres/schema/orders 這個表的效能問題

# 預設 25,000 tokens，超過 10,000 tokens 會顯示警告
export MAX_MCP_OUTPUT_TOKENS=25000

# 啟動 Claude Code 作為 MCP Server
claude mcp serve

# 其他 MCP Client 可以連接到 Claude Code 的 stdio
# 使用 Claude Code 的所有工具（Read, Edit, Bash 等）

{
  "mcpServers": {
    "company-mcp": {
      "type": "sse",
      "url": "https://mcp.company.com/sse",
      "auth": {
        "type": "oauth2",
        "clientId": "claude-code-client",
        "scope": "read write",
        "authorizationUrl": "https://auth.company.com/oauth/authorize",
        "tokenUrl": "https://auth.company.com/oauth/token"
      }
    }
  }
}

{
  "mcpServers": {
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DB_CONNECTION_STRING}"
      }
    }
  }
}

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.company.internal/api",
      "headersHelper": "node ./scripts/get-auth-header.js"
    }
  }
}

MCP Server 回傳 elicitation 請求
  → Claude Code 顯示問題給使用者
  → 使用者回答
  → 回傳給 MCP Server 繼續處理

# MCP Server 暴露的 prompt 會出現在可用命令中
> /mcp-server-name:prompt-name

# 例如 GitHub MCP Server 提供的 prompt
> /github:create-pr-description

{
  "mcpServers": {
    "company-tools": {
      "type": "http",
      "url": "https://mcp.company.internal/api",
      "auth": {
        "type": "oauth2",
        "clientId": "claude-code",
        "scope": "company-tools"
      }
    },
    "security-scanner": {
      "type": "stdio",
      "command": "/usr/local/bin/security-mcp-server",
      "args": ["--strict-mode"]
    }
  },
  "policy": {
    "allowUserMcpServers": true,
    "allowlist": [
      "@anthropic/mcp-server-*",
      "company-*"
    ],
    "denylist": [
      "*torrent*",
      "*proxy*",
      "*bypass*"
    ],
    "requiredServers": [
      "company-tools",
      "security-scanner"
    ]
  }
}

// my-mcp-server/src/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "company-internal-tools",
  version: "1.0.0",
});

// 定義工具：查詢公司內部 Wiki
server.tool(
  "search_wiki",
  "搜尋公司內部 Wiki 文件",
  {
    query: z.string().describe("搜尋關鍵字"),
    limit: z.number().optional().default(5).describe("最多返回幾筆"),
  },
  async ({ query, limit }) => {
    const results = await searchInternalWiki(query, limit);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(results, null, 2),
        },
      ],
    };
  }
);

// 定義工具：查詢部署狀態
server.tool(
  "deployment_status",
  "查詢應用程式的部署狀態",
  {
    app_name: z.string().describe("應用程式名稱"),
    environment: z.enum(["dev", "staging", "production"]).describe("環境"),
  },
  async ({ app_name, environment }) => {
    const status = await getDeploymentStatus(app_name, environment);
    return {
      content: [
        {
          type: "text",
          text: `${app_name} (${environment}): ${status.state}\n` +
                `版本: ${status.version}\n` +
                `上次部署: ${status.lastDeployed}`,
        },
      ],
    };
  }
);

// 啟動 Server
const transport = new StdioServerTransport();
await server.connect(transport);

// .mcp.json
{
  "mcpServers": {
    "company-tools": {
      "command": "node",
      "args": ["./my-mcp-server/dist/index.js"],
      "env": {
        "WIKI_API_KEY": "${WIKI_API_KEY}",
        "DEPLOY_API_URL": "https://deploy.company.internal"
      }
    }
  }
}

# 啟動 MCP debug 模式
claude --mcp-debug

# 互動模式中查看 MCP 狀態
/mcp

# 手動測試 MCP Server 啟動
npx -y @modelcontextprotocol/server-github 2>&1

# 檢查 MCP Server 日誌
cat ~/.claude/logs/mcp-*.log

<!-- ~/.claude/output-styles/enterprise-report.md -->
---
name: enterprise-report
description: 企業報告風格，正式語氣、結構化輸出
keep-coding-instructions: true
---

## 輸出規範
- 使用正式中文語氣
- 每次回應以「摘要」開始
- 使用表格呈現結構化資訊
- 程式碼區塊附帶語言標記
- 變更清單使用勾選框格式

{
  "outputStyle": "concise",
  
  "outputPreferences": {
    "codeComments": "minimal",
    "explanationLevel": "brief",
    "language": "zh-TW"
  }
}

# CLAUDE.md 中的輸出風格設定

## 輸出偏好
- 回應請使用繁體中文
- 程式碼註解使用英文
- 優先展示程式碼，解釋放在後面
- 變更摘要使用表格格式
- 每次修改後列出受影響的檔案清單

# 在會話中即時調整
> /output-style concise    # 切換為簡潔模式
> /output-style detailed   # 切換為詳細模式

## 程式碼生成輸出格式

生成程式碼時，請遵循以下格式：

1. **摘要**：一行說明這次變更做了什麼
2. **檔案清單**：列出所有修改的檔案
3. **程式碼**：展示變更的程式碼
4. **驗證**：說明如何驗證變更是否正確

## Code Review 輸出格式

進行程式碼審查時，請使用以下格式：

| 嚴重度 | 位置 | 問題描述 | 建議修復 |
|--------|------|---------|---------|
| 🔴 高 | 檔案:行號 | 描述 | 修復方式 |
| 🟡 中 | 檔案:行號 | 描述 | 修復方式 |
| 🟢 低 | 檔案:行號 | 描述 | 修復方式 |

# CLAUDE.md — PR Review 輸出風格

## 輸出偏好（PR Review 模式）
- 先列出整體評估摘要（一段話）
- 使用表格列出所有問題，按嚴重度排序
- 對每個問題提供「修正前 vs 修正後」的對比程式碼
- 最後給出「Approve / Request Changes / Comment」建議
- 統計數據：新增行數、刪除行數、影響的模組

## 嚴重度分類
| 等級 | 定義 | 是否阻擋合併 |
|------|------|-------------|
| 🔴 Critical | 安全漏洞、資料遺失風險 | 是 |
| 🟠 High | 效能問題、邏輯錯誤 | 是 |
| 🟡 Medium | 程式風格、可讀性 | 否 |
| 🟢 Low | 建議改善、最佳實踐 | 否 |

# CLAUDE.md — 除錯模式輸出風格

## 輸出偏好（除錯模式）
- 先重現問題：列出錯誤訊息和 stack trace
- 分析根本原因（Root Cause Analysis）
- 列出可能的原因（機率從高到低）
- 每個可能原因提供：
  1. 驗證方法（如何確認是否為此原因）
  2. 修復方案
  3. 預防措施
- 使用流程圖展示除錯步驟

# CLAUDE.md — 文件撰寫輸出風格

## 輸出偏好（文件撰寫模式）
- 使用正式語氣
- 包含目的、適用對象、前置條件
- 步驟使用有序列表，每步搭配截圖說明佔位符
- 重要注意事項使用 admonition 格式（> **⚠️ 注意**）
- 所有專有名詞第一次出現時附英文原名
- 末尾包含 FAQ 和相關文件連結

# agents/senior-reviewer.md

---
name: senior-reviewer
description: 資深程式碼審查者，用嚴格標準檢查程式碼
output-style: detailed
---

## 角色定義
你是一位具有 15 年經驗的資深軟體工程師...

## 輸出風格要求
- 使用專業語氣，引用具體 RFC 或規範
- 問題描述包含「為什麼這是問題」的解釋
- 提供 benchmark 數據（如適用）
- 每個建議標注「必須修改」或「建議修改」

# CLAUDE.md

## Subagent 風格配置
呼叫 code-reviewer agent 時，使用 detailed 檢查模式。
呼叫 quick-fix agent 時，使用 concise 模式，僅輸出修改的檔案和行號。
呼叫 documentation agent 時，使用 pedagogical 教學模式，附帶完整範例。

> /loop 每 30 分鐘檢查 npm test 是否全部通過，如果有失敗的測試就修復它

Claude 會：
1. 執行 npm test
2. 如果有失敗，嘗試修復
3. 等待 30 分鐘後再次執行
4. 持續循環直到使用者中止或會話結束

# 在會話中使用自然語言建立排程
> 幫我設定一個每天早上 9 點跑安全掃描的排程任務

Claude 會呼叫 CronCreate 工具：
- name: "daily-security-scan"
- schedule: "0 9 * * *"  
- prompt: "執行 OWASP Top 10 安全掃描..."

# 列出所有排程
> 列出我目前所有的排程任務
→ 呼叫 CronList

# 刪除排程
> 刪除 daily-security-scan 排程
→ 呼叫 CronDelete

{
  "scheduledTasks": [
    {
      "name": "dependency-check",
      "schedule": "0 9 * * 1",
      "prompt": "檢查所有專案依賴是否有已知的安全漏洞，並生成報告",
      "outputPath": ".claude/reports/dependency-check.md"
    },
    {
      "name": "weekly-code-review",
      "schedule": "0 10 * * 5",
      "prompt": "對本週新增的所有程式碼進行全面審查，包括安全性、效能和程式碼品質",
      "agent": "code-reviewer",
      "outputPath": ".claude/reports/weekly-review.md"
    },
    {
      "name": "daily-test-run",
      "schedule": "0 6 * * *",
      "prompt": "執行所有測試套件並生成覆蓋率報告",
      "outputPath": ".claude/reports/test-results.md"
    }
  ]
}

{
  "name": "security-scan",
  "schedule": "0 2 * * *",
  "prompt": "對整個程式碼庫進行安全掃描，檢查 OWASP Top 10 常見漏洞，並將結果寫入報告",
  "agent": "security-reviewer",
  "outputPath": ".claude/reports/security-scan.md",
  "notification": {
    "type": "slack",
    "webhook": "${SLACK_WEBHOOK_URL}",
    "onlyOnIssues": true
  }
}

{
  "name": "dependency-update",
  "schedule": "0 8 * * 1",
  "prompt": "檢查所有 npm 依賴的最新版本，建立更新 PR 並確保測試通過",
  "outputPath": ".claude/reports/dependency-update.md"
}

{
  "name": "code-quality-report",
  "schedule": "0 7 * * 1-5",
  "prompt": "分析程式碼庫的品質指標，包括：測試覆蓋率趨勢、程式碼重複度、循環複雜度排行、新增的 TODO/FIXME 統計。輸出為 Markdown 表格。",
  "outputPath": ".claude/reports/code-quality.md",
  "notification": {
    "type": "slack",
    "channel": "#dev-metrics"
  }
}

{
  "name": "doc-sync-check",
  "schedule": "0 11 * * 3",
  "prompt": "比對 API 程式碼和文件，找出文件中缺少或過時的 API endpoint 描述。列出不一致之處。",
  "agent": "documentation",
  "outputPath": ".claude/reports/doc-sync.md"
}

# /etc/cron.d/claude-tasks

# 每天凌晨 2:00 執行安全掃描
0 2 * * * devops cd /opt/projects/myapp && claude -p "執行 OWASP Top 10 安全掃描" --output-format json > /var/log/claude/security-scan-$(date +\%Y\%m\%d).json 2>&1

# 每週一 9:00 檢查依賴更新
0 9 * * 1 devops cd /opt/projects/myapp && claude -p "檢查所有依賴是否有安全漏洞或新版本" --output-format json > /var/log/claude/deps-$(date +\%Y\%m\%d).json 2>&1

# 每週五 17:00 生成週報
0 17 * * 5 devops cd /opt/projects/myapp && claude -p "根據本週的 git log 生成開發週報" > /opt/reports/weekly-$(date +\%Y\%m\%d).md 2>&1

# scheduled-security-scan.ps1
$projectPath = "D:\Projects\MyApp"
$reportPath = "D:\Reports\claude"
$timestamp = Get-Date -Format "yyyyMMdd-HHmmss"

Set-Location $projectPath

# 執行掃描
$result = claude -p "對程式碼執行完整安全掃描" --output-format json 2>&1

# 儲存報告
$result | Out-File "$reportPath\security-$timestamp.json" -Encoding UTF8

# 檢查是否有高嚴重度問題並發通知
$parsed = $result | ConvertFrom-Json
if ($parsed.issues | Where-Object { $_.severity -eq "critical" }) {
    Send-MailMessage -To "security@company.com" `
        -Subject "Claude 安全掃描發現 Critical 問題" `
        -Body "詳見報告：$reportPath\security-$timestamp.json" `
        -SmtpServer "smtp.company.com"
}

# 方法一：VS Code 擴充套件市場搜尋
在 Extensions 面板搜尋 "Claude Code" 並安裝

# 方法二：命令列安裝
code --install-extension anthropic.claude-code

# 方法三：在 Claude Code CLI 中啟用
claude --install-vscode

@filename.ts        → 引用特定檔案
@src/services/      → 引用整個目錄
@git:diff           → 引用目前的 git diff
@git:log            → 引用最近的 git 歷史
@terminal           → 引用終端機輸出
@problems           → 引用 VS Code 問題面板
@selection          → 引用目前選取的程式碼
@browser            → 🆕 引用瀏覽器頁面內容（DevTools 整合）

// VS Code settings.json
{
  "claude-code.autoAccept": true,
  "claude-code.autoAcceptPatterns": [
    "*.test.ts",
    "*.spec.ts",
    "*.md"
  ]
}

// VS Code settings.json
{
  "claude-code.provider": "anthropic",
  "claude-code.model": "claude-sonnet-4-20250514",
  
  // 或使用第三方 Provider
  "claude-code.provider": "custom",
  "claude-code.apiEndpoint": "https://api.custom-provider.com/v1",
  "claude-code.apiKey": "${CUSTOM_API_KEY}"
}

# 設定環境變數
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret

# 或使用 AWS Profile
export AWS_PROFILE=your-profile

# 設定環境變數
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id

# 確保已通過 gcloud 認證
gcloud auth application-default login

Claude Code: Open Chat               → 開啟聊天面板
Claude Code: Explain Selection        → 解釋選取的程式碼
Claude Code: Fix Selection            → 修正選取的程式碼
Claude Code: Generate Tests           → 為選取的程式碼生成測試
Claude Code: Refactor Selection       → 重構選取的程式碼
Claude Code: Add Documentation        → 為選取的程式碼加上文件
Claude Code: Send to Terminal         → 將命令傳送到終端機
Claude Code: Toggle Plan Mode         → 切換 Plan 模式
Claude Code: Toggle Auto-Accept       → 切換自動接受模式

## 執行計畫

### 步驟 1：分析現有程式碼結構
- 讀取 `src/services/UserService.ts`
- 讀取 `src/models/User.ts`
- 讀取 `src/tests/UserService.test.ts`

### 步驟 2：重構 UserService
- 將認證邏輯抽取到 `AuthService`
- 修改 `UserService` 移除認證相關程式碼
- 更新導入路徑

### 步驟 3：更新測試
- 新增 `AuthService.test.ts`
- 更新 `UserService.test.ts` 移除認證測試
- 確保覆蓋率不下降

### 影響範圍
- 修改：3 個檔案
- 新增：2 個檔案
- 刪除：0 個檔案

是否繼續執行？ [Y/n]

# 從瀏覽器或其他應用程式開啟 Claude Code
vscode://anthropic.claude-code/open?prompt=分析這個專案的架構

# 帶入檔案 context
vscode://anthropic.claude-code/open?file=src/services/UserService.ts&prompt=審查這個檔案

# 帶入指定技能
vscode://anthropic.claude-code/open?skill=code-review&prompt=Review%20this%20PR

{
  // === Claude Code 核心設定 ===
  "claude-code.enable": true,
  "claude-code.provider": "anthropic",
  "claude-code.model": "claude-sonnet-4-20250514",
  
  // === 行為設定 ===
  "claude-code.autoAccept": false,
  "claude-code.planMode": false,
  "claude-code.showSpark": true,
  "claude-code.inlineSuggestions": true,
  
  // === 顯示設定 ===
  "claude-code.panelPosition": "right",
  "claude-code.fontSize": 14,
  "claude-code.theme": "auto",
  
  // === 進階設定 ===
  "claude-code.maxTokens": 200000,
  "claude-code.timeout": 300,
  "claude-code.debugMode": false,
  "claude-code.telemetry": true,
  
  // === Terminal 整合 ===
  "claude-code.terminal.autoDetect": true,
  "claude-code.terminal.shell": "default"
}

# 啟動 Claude Code 並開啟 Remote Control
claude --remote-control

# 或在會話中啟用
> /remote-control start

# API 預設監聽在 localhost 的動態端口
# 啟動後會輸出 WebSocket URL

# Python 範例：透過 WebSocket 控制 Claude Code
import asyncio
import websockets
import json

async def control_claude():
    uri = "ws://localhost:PORT/ws"
    async with websockets.connect(uri) as ws:
        # 傳送任務
        await ws.send(json.dumps({
            "type": "send_message",
            "message": "幫我找出所有未處理的 TODO 註解並建立 issue 清單"
        }))
        
        # 接收回應
        while True:
            response = json.loads(await ws.recv())
            if response["type"] == "response":
                print(response["content"])
            elif response["type"] == "done":
                break

asyncio.run(control_claude())

const WebSocket = require('ws');

class ClaudeRemoteClient {
  constructor(url) {
    this.url = url;
    this.ws = null;
  }

  async connect() {
    return new Promise((resolve, reject) => {
      this.ws = new WebSocket(this.url);
      this.ws.on('open', resolve);
      this.ws.on('error', reject);
    });
  }

  async sendMessage(message) {
    return new Promise((resolve, reject) => {
      const responses = [];
      
      this.ws.on('message', (data) => {
        const parsed = JSON.parse(data);
        if (parsed.type === 'response') {
          responses.push(parsed.content);
        } else if (parsed.type === 'done') {
          resolve(responses.join('\n'));
        }
      });

      this.ws.send(JSON.stringify({
        type: 'send_message',
        message: message
      }));
    });
  }

  async getStatus() {
    return new Promise((resolve) => {
      this.ws.on('message', (data) => {
        resolve(JSON.parse(data));
      });
      this.ws.send(JSON.stringify({ type: 'get_status' }));
    });
  }

  disconnect() {
    if (this.ws) this.ws.close();
  }
}

// 使用範例
async function main() {
  const client = new ClaudeRemoteClient('ws://localhost:PORT/ws');
  await client.connect();
  
  // 檢查狀態
  const status = await client.getStatus();
  console.log('Claude Code 狀態:', status);
  
  // 傳送任務
  const result = await client.sendMessage(
    '分析 src/services/ 目錄下所有 Service 的依賴關係，繪製 Mermaid 圖'
  );
  console.log('結果:', result);
  
  client.disconnect();
}

main().catch(console.error);

# dashboard.py - 多實例監控
import asyncio
import websockets
import json

class ClaudeDashboard:
    def __init__(self):
        self.instances = {}
    
    async def add_instance(self, name, url):
        """新增一個 Claude Code 實例到監控"""
        ws = await websockets.connect(url)
        self.instances[name] = {
            'ws': ws,
            'url': url,
            'status': 'connected'
        }
    
    async def monitor_all(self):
        """監控所有實例狀態"""
        while True:
            for name, instance in self.instances.items():
                try:
                    await instance['ws'].send(
                        json.dumps({'type': 'get_status'})
                    )
                    response = json.loads(
                        await asyncio.wait_for(
                            instance['ws'].recv(), timeout=5
                        )
                    )
                    instance['status'] = response.get('state', 'unknown')
                    print(f"[{name}] 狀態: {instance['status']}")
                except Exception as e:
                    instance['status'] = 'disconnected'
                    print(f"[{name}] 連線中斷: {e}")
            
            await asyncio.sleep(10)  # 每 10 秒檢查一次

# event_driven_automation.py
import asyncio
import websockets
import json
import subprocess

class EventDrivenAutomation:
    """基於 Claude Code 事件的自動化觸發器"""
    
    def __init__(self, ws_url, handlers=None):
        self.ws_url = ws_url
        self.handlers = handlers or {}
    
    def on(self, event_type, handler):
        """註冊事件處理器"""
        self.handlers[event_type] = handler
    
    async def start(self):
        """啟動事件監聽"""
        async with websockets.connect(self.ws_url) as ws:
            # 訂閱所有事件
            await ws.send(json.dumps({
                "type": "subscribe",
                "events": ["tool_use", "file_change", "error", "done"]
            }))
            
            while True:
                message = json.loads(await ws.recv())
                event_type = message.get("type", "unknown")
                
                if event_type in self.handlers:
                    await self.handlers[event_type](message)

# 使用範例
automation = EventDrivenAutomation("ws://localhost:PORT/ws")

async def on_file_change(event):
    """檔案變更時自動執行測試"""
    changed_files = event.get("files", [])
    test_files = [f for f in changed_files if "test" in f or "spec" in f]
    
    if test_files:
        print(f"偵測到測試檔變更: {test_files}")
        # 自動觸發相關測試
        result = subprocess.run(
            ["npm", "test", "--", "--findRelatedTests"] + test_files,
            capture_output=True, text=True
        )
        print(f"測試結果: {'通過' if result.returncode == 0 else '失敗'}")

async def on_error(event):
    """錯誤發生時通知 Slack"""
    error_msg = event.get("message", "未知錯誤")
    # 發送 Slack 通知（簡化範例）
    print(f"⚠️ Claude Code 錯誤: {error_msg}")

automation.on("file_change", on_file_change)
automation.on("error", on_error)

# asyncio.run(automation.start())

# load_balancer.py - 多實例任務分配
import asyncio
import websockets
import json
from collections import deque

class ClaudeLoadBalancer:
    """在多個 Claude Code 實例之間分配任務"""
    
    def __init__(self):
        self.instances = {}  # name -> {ws, status, current_task}
        self.task_queue = deque()
    
    async def register_instance(self, name, url):
        """註冊一個 Claude Code 實例"""
        ws = await websockets.connect(url)
        self.instances[name] = {
            "ws": ws,
            "url": url,
            "status": "idle",
            "current_task": None
        }
        print(f"已註冊實例: {name}")
    
    def get_idle_instance(self):
        """取得一個閒置的實例"""
        for name, inst in self.instances.items():
            if inst["status"] == "idle":
                return name
        return None
    
    async def submit_task(self, task):
        """提交任務到佇列"""
        self.task_queue.append(task)
        await self._dispatch()
    
    async def _dispatch(self):
        """分配佇列中的任務給閒置實例"""
        while self.task_queue:
            name = self.get_idle_instance()
            if not name:
                print("所有實例忙碌中，任務排隊等待")
                break
            
            task = self.task_queue.popleft()
            inst = self.instances[name]
            inst["status"] = "busy"
            inst["current_task"] = task["id"]
            
            print(f"分配任務 [{task['id']}] 到 {name}")
            await inst["ws"].send(json.dumps({
                "type": "send_message",
                "message": task["message"]
            }))
    
    async def get_status_report(self):
        """取得所有實例的狀態報告"""
        report = []
        for name, inst in self.instances.items():
            report.append({
                "instance": name,
                "status": inst["status"],
                "current_task": inst["current_task"]
            })
        return report

# 使用範例
async def main():
    lb = ClaudeLoadBalancer()
    
    # 註冊多個實例
    await lb.register_instance("worker-1", "ws://localhost:3001/ws")
    await lb.register_instance("worker-2", "ws://localhost:3002/ws")
    await lb.register_instance("worker-3", "ws://localhost:3003/ws")
    
    # 批次提交任務
    tasks = [
        {"id": "review-1", "message": "Review src/auth/ 所有檔案的安全性"},
        {"id": "review-2", "message": "Review src/api/ 所有 endpoint 的錯誤處理"},
        {"id": "review-3", "message": "Review src/db/ 所有 query 的 SQL injection 風險"},
        {"id": "test-1", "message": "為 src/services/OrderService.ts 撰寫完整單元測試"},
        {"id": "doc-1", "message": "為 src/api/ 所有 controller 生成 OpenAPI 文件"},
    ]
    
    for task in tasks:
        await lb.submit_task(task)
    
    # 查看狀態
    status = await lb.get_status_report()
    for s in status:
        print(f"  {s['instance']}: {s['status']} (任務: {s['current_task']})")

# asyncio.run(main())

// web-ui-integration.js - 將 Claude Code 嵌入自訂 Web 應用
const express = require('express');
const WebSocket = require('ws');
const app = express();

// Claude Code WebSocket 連線池
const claudeConnections = new Map();

// REST API 端點，讓前端透過 HTTP 與 Claude Code 互動
app.post('/api/claude/task', express.json(), async (req, res) => {
  const { instanceId, message } = req.body;
  
  let ws = claudeConnections.get(instanceId);
  if (!ws || ws.readyState !== WebSocket.OPEN) {
    ws = new WebSocket(`ws://localhost:${3000 + parseInt(instanceId)}/ws`);
    await new Promise((resolve) => ws.on('open', resolve));
    claudeConnections.set(instanceId, ws);
  }
  
  const responses = [];
  
  return new Promise((resolve) => {
    ws.on('message', (data) => {
      const parsed = JSON.parse(data);
      if (parsed.type === 'response') {
        responses.push(parsed.content);
      } else if (parsed.type === 'done') {
        res.json({ success: true, result: responses.join('\n') });
        resolve();
      }
    });

    ws.send(JSON.stringify({
      type: 'send_message',
      message: message
    }));
  });
});

// 取得所有實例狀態
app.get('/api/claude/status', async (req, res) => {
  const statuses = [];
  for (const [id, ws] of claudeConnections) {
    statuses.push({
      id,
      connected: ws.readyState === WebSocket.OPEN,
      url: `ws://localhost:${3000 + parseInt(id)}/ws`
    });
  }
  res.json(statuses);
});

app.listen(8080, () => {
  console.log('Claude Code Web UI API 啟動於 port 8080');
});

# 基本 Headless 執行
claude -p "分析 src/ 目錄下所有 Java 檔案的程式碼品質"

# 指定輸出格式
claude -p "列出所有 TODO 註解" --output-format json

# 🆕 串流 JSON 輸出（每個事件獨立一行 JSON）
claude -p "分析程式碼" --output-format stream-json

# 🆕 結構化 JSON Schema 輸出
claude -p "列出所有 API endpoint" --output-format json --json-schema '{"type":"object","properties":{"endpoints":{"type":"array","items":{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"}}}}}}'

# 🆕 --bare 模式（跳過自動發現，極速啟動）
claude -p "直接回答：1+1=?" --bare

# 從 stdin 讀取輸入
echo "重構 UserService 的認證邏輯" | claude -p -

# 使用 Headless 模式 + Agent
claude -p "進行安全掃描" --agent security-reviewer

# 追加系統提示
claude -p "分析程式碼" --bare --append-system-prompt "你是安全專家。請專注 OWASP Top 10。"

# 從檔案追加系統提示
claude -p "審查 PR" --bare --append-system-prompt-file ./prompts/security-review.md

# 指定設定檔
claude -p "分析" --bare --settings ./custom-settings.json

# 指定 MCP 配置
claude -p "查詢" --bare --mcp-config ./custom-mcp.json

# 載入特定 agents
claude -p "審查" --bare --agents ./agents/

# 載入特定 plugin
claude -p "分析" --bare --plugin-dir ./my-plugin/

claude -p "列出所有 API endpoints" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"endpoints":{"type":"array","items":{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"},"description":{"type":"string"}},"required":["method","path"]}}}}'

# 回傳的 JSON 中包含：
# {
#   "result": "success",
#   "output": "...",
#   "structured_output": {
#     "endpoints": [
#       {"method": "GET", "path": "/api/users", "description": "列出所有使用者"},
#       {"method": "POST", "path": "/api/users", "description": "建立新使用者"}
#     ]
#   }
# }

import { ClaudeCode } from '@anthropic-ai/claude-code';

// 建立 Claude Code 實例
const claude = new ClaudeCode({
  apiKey: process.env.CLAUDE_API_KEY,
});

// 執行任務
const result = await claude.run({
  prompt: "分析這段程式碼的安全漏洞",
  context: {
    files: ["src/auth/login.ts"],
  },
});

console.log(result.output);

from claude_code import ClaudeCode

# 建立 Claude Code 實例
claude = ClaudeCode(api_key=os.environ["CLAUDE_API_KEY"])

# 執行任務
result = claude.run(
    prompt="分析 src/auth/ 目錄的安全性",
    output_format="json"
)

print(result.output)

import { ClaudeCode, Conversation } from '@anthropic-ai/claude-code';

const claude = new ClaudeCode({
  apiKey: process.env.CLAUDE_API_KEY,
});

// 建立多輪對話
const conversation = claude.createConversation({
  systemPrompt: "你是一個專業的程式碼審查員",
  workingDirectory: "/path/to/project",
});

// 第一輪：分析程式碼結構
const step1 = await conversation.send(
  "分析 src/services/ 的程式碼結構"
);
console.log("結構分析:", step1.output);

// 第二輪：基於第一輪結果，深入分析
const step2 = await conversation.send(
  "針對你發現的問題，提供具體的重構建議"
);
console.log("重構建議:", step2.output);

// 第三輪：執行重構
const step3 = await conversation.send(
  "請執行第一項重構建議"
);
console.log("重構結果:", step3.output);

// 結束對話
await conversation.close();

const claude = new ClaudeCode({
  apiKey: process.env.CLAUDE_API_KEY,
});

// 使用串流模式獲取即時輸出
const stream = claude.stream({
  prompt: "解釋 src/core/engine.ts 的運作原理",
});

for await (const chunk of stream) {
  switch (chunk.type) {
    case 'text':
      process.stdout.write(chunk.content);
      break;
    case 'tool_use':
      console.log(`\n[工具呼叫] ${chunk.tool}: ${chunk.input}`);
      break;
    case 'tool_result':
      console.log(`[工具結果] ${chunk.output.substring(0, 100)}...`);
      break;
    case 'done':
      console.log('\n完成');
      break;
  }
}

# JSON 輸出範例
claude -p "列出 src/ 下的所有 TODO" --output-format json

# 輸出：
{
  "result": "success",
  "output": "找到 15 個 TODO 項目...",
  "files_read": ["src/services/UserService.ts", "..."],
  "files_modified": [],
  "tokens": {
    "input": 12500,
    "output": 3200
  },
  "cost": 0.05
}

import { App } from '@slack/bolt';
import { ClaudeCode } from '@anthropic-ai/claude-code';

const slackApp = new App({
  token: process.env.SLACK_BOT_TOKEN,
  signingSecret: process.env.SLACK_SIGNING_SECRET,
});

const claude = new ClaudeCode({
  apiKey: process.env.CLAUDE_API_KEY,
});

// 監聽 Slack 命令
slackApp.command('/claude', async ({ command, ack, respond }) => {
  await ack();

  // 使用 Claude Code 執行任務
  const result = await claude.run({
    prompt: command.text,
    workingDirectory: '/path/to/project',
    outputFormat: 'text',
  });

  await respond({
    text: `Claude Code 回覆:\n\`\`\`\n${result.output}\n\`\`\``,
  });
});

// 監聽 PR 審查請求
slackApp.event('app_mention', async ({ event, say }) => {
  if (event.text.includes('review PR')) {
    const prNumber = event.text.match(/PR #(\d+)/)?.[1];
    if (prNumber) {
      const result = await claude.run({
        prompt: `Review PR #${prNumber}. Focus on security and code quality.`,
        workingDirectory: '/path/to/project',
        outputFormat: 'json',
      });
      
      await say({
        text: `PR #${prNumber} 審查完成:\n${result.output}`,
        thread_ts: event.ts,
      });
    }
  }
});

slackApp.start(3000);

#!/bin/bash
# security-scan.sh - 搭配 cron 執行定期安全掃描

REPO_DIR="/path/to/project"
REPORT_DIR="/path/to/reports"
DATE=$(date +%Y-%m-%d)

cd "$REPO_DIR"

# 執行安全掃描
RESULT=$(claude -p "
  執行完整的安全審查：
  1. 檢查所有依賴是否有已知漏洞
  2. 掃描程式碼中的安全漏洞模式（SQL injection、XSS、CSRF 等）
  3. 檢查認證和授權邏輯
  4. 檢查敏感資料處理（密碼、API key 等）
  5. 產出 JSON 格式的安全報告
" --output-format json)

# 儲存報告
echo "$RESULT" > "$REPORT_DIR/security-scan-$DATE.json"

# 檢查是否有高危漏洞
HIGH_RISK=$(echo "$RESULT" | python3 -c "
import json, sys
data = json.load(sys.stdin)
# 解析高風險項目數量
print(data.get('high_risk_count', 0))
")

if [ "$HIGH_RISK" -gt 0 ]; then
  # 發送告警通知
  curl -X POST "$SLACK_WEBHOOK_URL" \
    -H 'Content-Type: application/json' \
    -d "{\"text\": \"⚠️ 安全掃描發現 $HIGH_RISK 個高風險漏洞！報告：$REPORT_DIR/security-scan-$DATE.json\"}"
fi

#!/bin/bash
# auto-feature-pipeline.sh — 自動化功能開發管道
# 用法: ./auto-feature-pipeline.sh "功能描述"

FEATURE_DESC="$1"
PROJECT_DIR=$(pwd)
LOG_DIR=".claude/pipeline-logs"
mkdir -p "$LOG_DIR"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

echo "🚀 啟動自動化功能開發管道..."

# Step 1: 需求分析
echo "📋 Step 1: 分析需求..."
ANALYSIS=$(claude -p "
分析以下功能需求，產出實施計畫：
$FEATURE_DESC

輸出 JSON 格式包含：
- affected_files: 需要修改的檔案清單
- new_files: 需要新建的檔案清單
- dependencies: 需要新增的依賴
- estimated_complexity: low/medium/high
- implementation_steps: 實施步驟
" --output-format json 2>"$LOG_DIR/step1-$TIMESTAMP.log")

echo "$ANALYSIS" > "$LOG_DIR/analysis-$TIMESTAMP.json"
echo "   分析完成 ✓"

# Step 2: 實作程式碼
echo "💻 Step 2: 實作程式碼..."
claude -p "
根據以下分析結果實作功能：
$ANALYSIS

要求：
- 遵循專案現有的程式碼風格
- 包含錯誤處理
- 加上必要的註解
- 不要修改不相關的檔案
" --output-format text > "$LOG_DIR/step2-$TIMESTAMP.log" 2>&1

echo "   實作完成 ✓"

# Step 3: 撰寫測試
echo "🧪 Step 3: 撰寫測試..."
claude -p "
為剛才新增/修改的檔案撰寫測試：

已修改的檔案：
$(git diff --name-only)

要求：
- 單元測試覆蓋所有公開方法
- 包含正向和反向測試案例
- 使用 describe/it 結構
" --output-format text > "$LOG_DIR/step3-$TIMESTAMP.log" 2>&1

echo "   測試撰寫完成 ✓"

# Step 4: 執行驗證
echo "🔍 Step 4: 驗證..."
npm test 2>"$LOG_DIR/step4-test-$TIMESTAMP.log"
TEST_EXIT=$?

npm run lint 2>"$LOG_DIR/step4-lint-$TIMESTAMP.log"
LINT_EXIT=$?

if [ $TEST_EXIT -eq 0 ] && [ $LINT_EXIT -eq 0 ]; then
    echo "   驗證通過 ✓"
else
    echo "   ⚠️ 驗證失敗，嘗試自動修復..."
    claude -p "
    修復以下問題：
    Test output: $(cat "$LOG_DIR/step4-test-$TIMESTAMP.log" | tail -30)
    Lint output: $(cat "$LOG_DIR/step4-lint-$TIMESTAMP.log" | tail -30)
    " --output-format text > "$LOG_DIR/step4-fix-$TIMESTAMP.log" 2>&1
fi

# Step 5: 產出摘要
echo "📝 Step 5: 產出變更摘要..."
SUMMARY=$(claude -p "
產出本次功能開發的變更摘要：
$(git diff --stat)

格式：
- 功能描述
- 修改的檔案和原因
- 測試覆蓋情況
- PR 建議標題和描述
" --output-format text 2>/dev/null)

echo "$SUMMARY" > "$LOG_DIR/summary-$TIMESTAMP.md"
echo ""
echo "=================================="
echo "$SUMMARY"
echo "=================================="
echo ""
echo "✅ 管道完成！日誌位於: $LOG_DIR/"

#!/usr/bin/env python3
"""stream_claude.py - 處理 Claude Code 串流輸出"""

import subprocess
import json
import sys

def stream_claude(prompt: str, project_dir: str):
    """串流接收 Claude Code 回應"""
    process = subprocess.Popen(
        [
            'claude', '-p', prompt,
            '--output-format', 'stream-json',
            '--verbose'
        ],
        cwd=project_dir,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True
    )
    
    full_response = []
    
    for line in process.stdout:
        line = line.strip()
        if not line:
            continue
            
        try:
            event = json.loads(line)
            event_type = event.get('type', '')
            
            if event_type == 'assistant':
                # Claude 回應文字
                content = event.get('content', '')
                print(content, end='', flush=True)
                full_response.append(content)
                
            elif event_type == 'tool_use':
                # 工具呼叫
                tool = event.get('tool', '')
                print(f"\n🔧 使用工具: {tool}", flush=True)
                
            elif event_type == 'tool_result':
                # 工具執行結果
                status = event.get('status', '')
                print(f"   結果: {status}", flush=True)
                
            elif event_type == 'error':
                # 錯誤
                error = event.get('message', '')
                print(f"\n❌ 錯誤: {error}", file=sys.stderr)
                
            elif event_type == 'done':
                # 完成
                cost = event.get('cost', {})
                print(f"\n\n💰 費用: ${cost.get('total', 0):.4f}")
                print(f"📊 Input tokens: {cost.get('input_tokens', 0)}")
                print(f"📊 Output tokens: {cost.get('output_tokens', 0)}")
                
        except json.JSONDecodeError:
            continue
    
    process.wait()
    return ''.join(full_response), process.returncode

if __name__ == '__main__':
    prompt = sys.argv[1] if len(sys.argv) > 1 else "分析專案架構"
    project = sys.argv[2] if len(sys.argv) > 2 else "."
    
    response, code = stream_claude(prompt, project)
    sys.exit(code)

#!/bin/bash
# batch-claude.sh — 批次執行多個 Claude Code 任務
# 用法: ./batch-claude.sh tasks.txt

TASK_FILE="$1"
RESULT_DIR="results/$(date +%Y%m%d)"
mkdir -p "$RESULT_DIR"

if [ ! -f "$TASK_FILE" ]; then
    echo "用法: $0 <task-file>"
    echo "task-file 每行一個任務提示"
    exit 1
fi

TOTAL=$(wc -l < "$TASK_FILE")
CURRENT=0
SUCCESS=0
FAILED=0

while IFS= read -r task; do
    CURRENT=$((CURRENT + 1))
    echo "[$CURRENT/$TOTAL] 執行: ${task:0:50}..."
    
    OUTPUT_FILE="$RESULT_DIR/task-$CURRENT.md"
    
    if claude -p "$task" --output-format text > "$OUTPUT_FILE" 2>&1; then
        echo "  ✓ 成功"
        SUCCESS=$((SUCCESS + 1))
    else
        echo "  ✗ 失敗"
        FAILED=$((FAILED + 1))
    fi
done < "$TASK_FILE"

echo ""
echo "======= 批次執行結果 ======="
echo "總計: $TOTAL"
echo "成功: $SUCCESS"
echo "失敗: $FAILED"
echo "結果目錄: $RESULT_DIR"

# 開發工作流程

## 需求分析
當收到新需求時：
1. 先查閱 /docs/requirements/ 中的現有文件
2. 建立 User Story 並寫入 /docs/stories/
3. 產生 Acceptance Criteria

## 架構設計
設計新功能時：
1. 遵循 /docs/architecture/ 中的架構決策記錄 (ADR)
2. 使用 Mermaid 繪製架構圖
3. 考慮現有模組的相容性

## 程式碼開發
實作程式碼時：
1. 遵循 /docs/coding-standards.md 中的編碼規範
2. 寫程式碼前先寫測試（TDD）
3. 每個功能建立獨立分支

## 測試驗證
完成開發後：
1. 確保所有現有測試通過
2. 新增功能的測試覆蓋率 > 80%
3. 執行整合測試

## 程式碼審查
提交 PR 前：
1. 自我審查所有變更
2. 確認 CHANGELOG 已更新
3. 檢查是否有安全疑慮

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "write_file",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Validating code patterns...'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "write_file",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ]
  }
}

// .mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "..." }
    }
  }
}

# 在 GitHub Actions 中
claude -p "
  Review the changes in this PR.
  Check for:
  1. Code quality and readability
  2. Test coverage
  3. Security vulnerabilities
  4. Performance implications
  
  Output your review as structured JSON.
" --output-format json

# 啟動 Cowork 模式進行大型重構
> /agents

# 在 Agent 聊天中分配任務
Lead Agent：「將單體應用拆分為微服務」

# Lead Agent 自動建立 git worktree 並分配 Teammate
# Teammate 1: 拆分 UserService → user-service/
# Teammate 2: 拆分 OrderService → order-service/  
# Teammate 3: 拆分 PaymentService → payment-service/

# 每個 Teammate 在獨立 worktree 中工作
# Lead Agent 負責整合和衝突解決

project-root/
├── CLAUDE.md                    # 專案層級指令
├── .claude/
│   └── settings.json            # Hooks、權限配置
├── .mcp.json                    # MCP Server 配置
├── .claude-plugins/             # 本地 Plugin
│   └── my-plugin/
│       ├── plugin.json
│       └── tools/
├── src/
│   ├── CLAUDE.md                # src 目錄特定指令
│   ├── services/
│   │   └── CLAUDE.md            # services 目錄特定指令
│   └── tests/
│       └── CLAUDE.md            # 測試目錄特定指令
└── docs/
    └── CLAUDE.md                # 文件目錄特定指令

# MyProject

## 技術棧
- Language: TypeScript 5.x
- Runtime: Node.js 20
- Framework: Express.js
- Database: PostgreSQL 16
- ORM: Prisma

## 開發規範
- 使用 ESLint + Prettier
- 測試框架：Vitest
- 提交訊息遵循 Conventional Commits
- 分支策略：Git Flow

## 禁止事項
- 不要修改 prisma/migrations/ 中的已有遷移檔案
- 不要在 production 環境直接修改資料庫
- 不要在程式碼中硬編碼密碼或 API key

# 測試規範

- 測試檔案命名：*.test.ts
- 使用 describe/it 區塊組織測試
- 每個公開方法至少一個測試
- Mock 外部依賴，不要 mock 被測試的模組本身
- 使用 factory pattern 建立測試資料

You: 幫我處理 GitHub Issue #42

Claude: 正在透過 MCP 讀取 Issue #42...

[mcp__github__get_issue] Issue #42: 使用者編輯資料後畫面未即時更新
分類：Bug | 優先級：High | 標籤：frontend

問題描述：使用者在 /settings/profile 編輯個人資料後，
需要重新整理頁面才能看到更新後的內容。

我來分析相關程式碼...

[Read] src/pages/settings/Profile.tsx
[Read] src/hooks/useProfile.ts
[Read] src/services/profileService.ts
[Grep] 搜尋 mutate|invalidate|refetch

分析結果：
- Profile.tsx 呼叫 updateProfile API 後沒有 invalidate React Query cache
- 導致快取中的舊資料持續顯示

修復計畫：
1. 在 useProfile.ts 中的 mutation 成功回呼中，
   加入 queryClient.invalidateQueries(['profile'])
2. 新增樂觀更新（Optimistic Update）提升 UX
3. 新增對應的測試案例

確認後我開始修復？

You: 好，開始

Claude: 
[Bash] git checkout -b fix/issue-42-profile-update
[Edit] src/hooks/useProfile.ts    # 加入 cache invalidation
[Edit] src/pages/settings/Profile.tsx  # 加入 loading 狀態
[Write] src/__tests__/useProfile.test.ts  # 新增測試

[Bash] npm test -- --testPathPattern=useProfile
✅ 4 tests passed

[Bash] git add -A && git commit -m "fix(profile): invalidate query cache after profile update

- Add queryClient.invalidateQueries on mutation success
- Add optimistic update for better UX
- Add unit tests for cache invalidation

Closes #42"

[mcp__github__create_pull_request]
✅ PR #58 已建立：fix(profile): invalidate query cache after profile update
  - 引用 Issue #42
  - 自動加入 Labels: bug, frontend
  - CI pipeline 已觸發

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Edit(src/**)",
      "Write(src/**)",
      "Bash(npm test *)",
      "Bash(npm run lint *)",
      "Bash(npm run build)",
      "Bash(npx prisma *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git checkout *)",
      "Bash(git branch *)",
      "mcp__github__*"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Bash(npx prisma migrate deploy *)",
      "Edit(.env*)",
      "Edit(prisma/migrations/**)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/check-file-size.js"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix ${CLAUDE_FILE_PATH} 2>/dev/null || true"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/send-slack-notification.js"
          }
        ]
      }
    ]
  }
}

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "${DEV_DATABASE_URL}" }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

# 團隊開發規範

## 程式碼風格
- 使用 Prettier 格式化（設定見 .prettierrc）
- 使用 ESLint 檢查（設定見 .eslintrc.js）
- 每個檔案不超過 300 行
- 每個方法不超過 30 行

## Git 規範
- 提交訊息遵循 Conventional Commits
- 分支策略：main → develop → feature/*
- PR 必須有至少一個 Reviewer
- Squash merge 到 main

## 架構規範
- Service 層不直接存取資料庫，透過 Repository
- Controller 不包含業務邏輯
- 使用 DTO 進行資料轉換
- 所有 API 需要有 OpenAPI 文件

{
  "permissions": {
    "deny": [
      "mcp tool edit in directory /prod/",
      "shell command rm -rf"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "write_file",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix $CLAUDE_FILE_PATH"
          }
        ]
      }
    ]
  }
}

# CLAUDE.md 中的分支規範
## Git 分支保護
- 不要直接推送到 main 或 develop
- 所有變更透過 PR 合併
- PR 標題格式：[類型] 描述（如 [feat] 新增使用者認證）

# 專案知識庫

## 系統架構
本系統採用微服務架構，包含以下服務：
- user-service: 使用者管理（Port 8081）
- order-service: 訂單管理（Port 8082）
- payment-service: 支付處理（Port 8083）
- notification-service: 通知服務（Port 8084）

## 常見問題
- 連線 Redis 逾時：檢查 VPN 是否連線
- 測試資料庫 schema 不同步：執行 npm run db:push
- Docker build 失敗：確認 Node.js 版本 >= 20

## API 設計慣例
- 分頁用 cursor-based pagination
- 錯誤回應用 RFC 7807（Problem Details）
- 認證用 JWT，透過 Authorization: Bearer 標頭

# CLAUDE.md

## Custom Commands

### /project:setup
初始化開發環境：
1. npm install
2. cp .env.example .env
3. docker compose up -d
4. npm run db:migrate
5. npm run db:seed

### /project:review
執行完整的程式碼審查：
1. 檢查所有修改的檔案
2. 執行 npm run lint
3. 執行 npm run test
4. 檢查測試覆蓋率
5. 列出潛在的安全問題

# 新人入職指南

## 專案簡介
本專案是 [產品名稱] 的後端服務，提供 RESTful API 給前端和行動端使用。

## 技術棧速覽
- **語言**：Java 17 + Spring Boot 3.2
- **資料庫**：PostgreSQL 16（主資料庫）、Redis 7（快取）
- **訊息佇列**：RabbitMQ 3.12
- **容器化**：Docker + Kubernetes
- **CI/CD**：GitHub Actions

## 核心模組
| 模組 | 路徑 | 說明 |
|------|------|------|
| 認證 | src/auth/ | OAuth2 + JWT 認證 |
| 使用者 | src/user/ | 使用者 CRUD + 權限管理 |
| 訂單 | src/order/ | 訂單處理與狀態機 |
| 支付 | src/payment/ | 第三方支付整合 |

## 常用命令
- `./gradlew bootRun` - 啟動開發伺服器
- `./gradlew test` - 執行測試
- `./gradlew spotlessApply` - 格式化程式碼
- `docker compose up -d` - 啟動相依服務

## 環境變數
參見 `.env.example` 檔案

## 分支策略
- `main` - 生產環境
- `develop` - 開發環境
- `feature/*` - 功能分支
- `hotfix/*` - 緊急修復

## 新人常見問題
1. Redis 連線失敗 → 執行 `docker compose up -d redis`
2. 資料庫 migration 失敗 → 執行 `./gradlew flywayRepair`
3. 測試資料不存在 → 執行 `./gradlew seedTestData`

// settings.json - Code Review Hook
{
  "hooks": {
    "Notification": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"[$(date)] Claude Code notification: $CLAUDE_NOTIFICATION\" >> /tmp/claude-review.log"
          }
        ]
      }
    ]
  }
}

# CLAUDE.md 衝突預防策略

## 檔案鎖定規則
- 同一 Sprint 中，每個 Service 檔案只由一個工程師負責修改
- Schema migration 檔案由 DBA 角色統一管理
- 共用工具函式修改需在 Stand-up 會議中提出

## Agent Teams 衝突預防
使用 Cowork 模式時：
1. Lead Agent 先進行模組切分
2. 每個 Teammate 只在指定的目錄工作
3. 公共介面的變更必須經過 Lead Agent 確認
4. 使用獨立的 git worktree 避免檔案衝突

# 不建議：過度冗長的指令
這個專案是一個使用 TypeScript 開發的網路應用程式，
我們使用了很多現代的開發工具和框架...
（大量描述性文字）

# 建議：精準的指令
## 技術棧
TypeScript 5.x | Node.js 20 | Express | PostgreSQL | Prisma

## 規範
- Conventional Commits
- 測試覆蓋率 > 80%
- 不允許 any 型別

# .claudeignore
node_modules/
dist/
build/
.next/
coverage/
*.min.js
*.lock
package-lock.json

project/
├── CLAUDE.md              # 專案全域指令
├── src/
│   └── CLAUDE.md          # 僅在需要時：如特殊編碼規範
├── tests/
│   └── CLAUDE.md          # 測試規範
└── docs/                  # 不需要 CLAUDE.md

# 不建議：載入整個目錄
@src/

# 建議：只引用需要的檔案
@src/services/UserService.ts
@src/models/User.ts

# 不建議：一次給予過多任務
claude -p "重構整個專案的所有 Service、Controller、Model、Test..."

# 建議：分階段執行
claude -p "先分析 UserService 的程式碼結構，列出建議的重構項目"
# 確認後
claude -p "根據上述分析，重構 UserService 的認證邏輯"
# 確認後
claude -p "為重構後的 UserService 更新測試"

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "write_file",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH && npx eslint --fix $CLAUDE_FILE_PATH"
          }
        ]
      }
    ]
  }
}

# 在長對話中，使用 /compact 壓縮歷史對話
> /compact

# 帶自訂提示的 compact
> /compact 保留關於 UserService 重構的決策和進度

# 設定自動 compact
# 在 settings.json 中：
{
  "autoCompact": true,
  "autoCompactThreshold": 80
}

首次載入 CLAUDE.md:
  Cache Write: 5,000 tokens （完整計費）

後續使用:
  Cache Read: 5,000 tokens  （僅 10% 費用）

節省: 90% 的重複 context 費用

> /doctor

Claude Code Doctor 診斷結果：
✅ Node.js 版本: v22.4.0
✅ Git: 已安裝 (2.45.0)
✅ Git Bash: 已偵測到 (Windows)
✅ 認證: OAuth 有效
✅ MCP Servers: 3/3 連線正常
⚠️ 設定檔: CLAUDE.md 超過 5000 字，可能影響效能
❌ Plugin: my-plugin 版本過舊，建議更新

# 啟動 Claude Code 的 Debug 模式
claude --debug

# 查看詳細日誌
claude --verbose

# 檢查配置
> /config

# 查看已載入的 CLAUDE.md 檔案
> /memory

# 查看目前會話的 Token 使用量
> /cost

# 輸出範例：
# Session cost: $0.42
# Input tokens: 125,000
# Output tokens: 15,000
# Cache read: 80,000 tokens
# Cache write: 45,000 tokens

# 如果 Token 使用過高，檢查：
# 1. 是否有過大的檔案被載入到 context
# 2. CLAUDE.md 是否包含過多不必要的內容
# 3. 是否可以使用 /compact 壓縮歷史

# 測試 MCP Server 是否正常啟動
npx -y @modelcontextprotocol/server-github

# 檢查 .mcp.json 格式是否正確
cat .mcp.json | python -m json.tool

# 在 Claude Code 中檢查已連接的 MCP Servers
> /mcp

# 重新連接 MCP Server
> /mcp reset

# 檢查 Hook 是否被正確載入
claude --debug

# Hook 不觸發的常見原因：
# 1. matcher 不匹配 → 確認使用正確的工具名稱
# 2. command 路徑錯誤 → 使用絕對路徑
# 3. 權限不足 → chmod +x hook-script.sh
# 4. 環境變數未設定 → 檢查 Hook 環境變數

# Hook 調試範例（在 command 中加入日誌）
# "command": "echo \"[DEBUG] Hook triggered: tool=$CLAUDE_TOOL_NAME file=$CLAUDE_FILE_PATH\" >> /tmp/claude-hooks.log && your-actual-command"

# 查看 Claude Code 說明
claude --help

# 查看特定命令的說明
claude run --help

# 回報 Bug
> /bug

# 加入社群
# GitHub Discussions: github.com/anthropics/claude-code/discussions
# Discord: Anthropic 官方 Discord

## 環境資訊
- Claude Code 版本: [claude --version]
- Node.js 版本: [node --version]
- 作業系統: [macOS/Linux/Windows WSL]
- IDE: [VS Code 版本 / Terminal]

## 問題描述
[清楚描述問題]

## 重現步驟
1. [步驟 1]
2. [步驟 2]
3. [觀察到的結果]

## 預期行為
[預期應該發生什麼]

## 實際行為
[實際發生了什麼]

## 相關配置
```json
// settings.json
{}

// .mcp.json
{}

[claude --debug 的輸出]

---

## 3.8 Cowork 協同開發實戰

> 🆕 **v3.0 新增章節**：本章節全面介紹如何在團隊中實現 Claude Code 的協同開發模式。

### 3.8.1 Cowork 概念與模式

**Cowork（協同開發）** 是指多位開發者透過 Claude Code 的各種機制，實現高效的人機協作與團隊協作。Claude Code 提供多層次的協同模式：

```mermaid
graph TB
    subgraph "個人層 (Solo)"
        S1[單人 + Claude Code]
        S2[使用 Subagent 委派子任務]
    end
    
    subgraph "雙人層 (Pair)"
        P1[開發者 A + Claude Code]
        P2[開發者 B + Claude Code]
        P1 -.->|共享 CLAUDE.md| P2
        P1 -.->|共享 .mcp.json| P2
    end
    
    subgraph "團隊層 (Team)"
        T1[Agent Teams<br/>Lead + Teammates]
        T2[Plugin Marketplace<br/>共享工具與技能]
        T3[CI/CD 整合<br/>自動化協作]
    end
    
    subgraph "組織層 (Org)"
        O1[Managed Settings<br/>企業統一配置]
        O2[Team Marketplaces<br/>內部插件分發]
        O3[Channels / Dispatch<br/>跨平台協作]
    end
    
    S1 --> P1
    P1 --> T1
    T1 --> O1
    
    style T1 fill:#6366f1,stroke:#4f46e5,color:#fff
    style O1 fill:#f59e0b,stroke:#d97706,color:#fff

組織根目錄/
├── CLAUDE.md                        # 全組織共用指引
├── frontend/
│   ├── CLAUDE.md                    # 前端團隊指引
│   └── packages/
│       └── ui-components/
│           └── CLAUDE.md            # 子專案指引
├── backend/
│   ├── CLAUDE.md                    # 後端團隊指引
│   └── services/
│       └── auth-service/
│           └── CLAUDE.md            # 微服務指引
└── .claude/
    ├── settings.json                # 專案共享設定（提交至 Git）
    ├── settings.local.json          # 個人覆寫（不提交）
    └── rules/
        ├── security.md              # 安全規則（自動載入）
        ├── code-style.md            # 風格規則
        └── testing.md               # 測試規則

# 專案指引 — 電商平台

## 🏗️ 架構決策
- 前端使用 Next.js 14 App Router
- 後端使用 NestJS + Prisma
- 資料庫使用 PostgreSQL 16
- 快取使用 Redis 7

## 📐 編碼規範
- TypeScript strict mode，禁止 any
- 使用 ESLint flat config
- CSS 使用 Tailwind CSS
- 所有 API 需有 OpenAPI 文件

## 🧪 測試要求
- 單元測試覆蓋率 ≥ 80%
- 使用 Vitest + Testing Library
- E2E 測試使用 Playwright
- 執行 `npm test` 確認所有測試通過

## 🔒 安全規範
- 禁止 hardcode 任何密鑰
- SQL 必須使用 parameterized query
- API 必須驗證 JWT token
- 禁止 `eval()` 和 `innerHTML`

## 📦 常用命令
- `npm test` — 執行測試
- `npm run build` — 建構
- `npm run lint` — 風格檢查
- `npm run db:migrate` — 資料庫遷移

~/.claude/
├── CLAUDE.md          # 全域指引（前 200 行自動載入）

專案根目錄/
├── CLAUDE.md          # 專案指引（前 200 行自動載入）
├── CLAUDE.local.md    # 個人本地指引（不提交 Git）

// .mcp.json（提交至 Git，團隊共享）
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "jira": {
      "type": "http",
      "url": "${JIRA_MCP_URL:-https://mcp.atlassian.com/v1/mcp}"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"],
      "env": {}
    }
  }
}

# 啟用 Agent Teams（實驗性功能）
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

使用者: "重構 auth 模組，包含前端表單、後端 API、資料庫遷移"

Lead Agent（你的對話）:
├── 分析任務 → 建立 task list
├── 指派 Teammate 1: "處理資料庫遷移"
├── 指派 Teammate 2: "重構後端 API"
├── 指派 Teammate 3: "更新前端表單"
└── 匯總結果 → 確認整合

Teammate 1 (worktree):     Teammate 2 (worktree):     Teammate 3 (worktree):
├── 讀取 schema            ├── 讀取現有 API            ├── 讀取 UI 元件
├── 建立 migration         ├── 重構 controllers        ├── 更新表單邏輯
├── 執行 db:migrate        ├── 更新 middleware          ├── 更新樣式
└── 回報完成               ├── 撰寫測試               └── 回報完成
                           └── 回報完成

// ~/.claude/settings.json（團隊成員配置）
{
  "extraKnownMarketplaces": [
    "https://github.com/your-org/claude-plugins-internal"
  ]
}

1. 開發 Plugin
   └── .claude-plugin/plugin.json + skills/ + agents/ + hooks/

2. 測試 Plugin
   └── claude --plugin-dir ./my-plugin

3. 發佈到內部 Marketplace
   └── git push 到 org 的 marketplace repo

4. 團隊成員安裝
   └── 在 Claude Code 中搜尋並安裝

5. 自動更新
   └── Marketplace 更新後自動同步

# 在開發機器上啟動 server mode
claude --server --spawn

# 產生 QR Code 供其他裝置連接
# 或透過 claude.ai/code 連接

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Bash(npm run *)",
      "Bash(npx prettier *)",
      "Bash(npx eslint *)",
      "Bash(git *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "mcp tool edit in directory /etc/",
      "mcp tool edit in directory /prod/"
    ]
  },
  "env": {
    "ANTHROPIC_API_KEY": "",
    "CLAUDE_CODE_MAX_TOKENS": "100000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "hooks": {
    "PostSession": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /opt/company/audit-log.py --session-end"
          }
        ]
      }
    ]
  }
}

{
  "mcpServers": {
    "company-knowledge-base": {
      "command": "npx",
      "args": ["-y", "@company/mcp-knowledge-base"],
      "env": {
        "KB_API_URL": "https://kb.company.com/api"
      }
    },
    "company-jira": {
      "command": "npx",
      "args": ["-y", "@company/mcp-jira"],
      "env": {
        "JIRA_URL": "https://jira.company.com"
      }
    }
  }
}

# .claudeignore - 排除敏感檔案
.env
.env.*
*.pem
*.key
*.p12
secrets/
credentials/
*.secret
config/production.yaml

# 設定企業 OAuth
claude config set oauthProvider "https://sso.company.com"

# 使用企業 API endpoint
claude config set apiEndpoint "https://api-proxy.company.com/claude"

# 登入（會開啟瀏覽器進行 OAuth 授權）
claude login

// managed-settings.json（企業管理員設定）
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"timestamp\":\"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'\",\"user\":\"'$USER'\",\"tool\":\"'$CLAUDE_TOOL_NAME'\",\"action\":\"pre\"}' >> /var/log/claude-audit.jsonl"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"timestamp\":\"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'\",\"user\":\"'$USER'\",\"tool\":\"'$CLAUDE_TOOL_NAME'\",\"action\":\"post\"}' >> /var/log/claude-audit.jsonl"
          }
        ]
      }
    ]
  }
}

// managed-settings.json — 生產環境配置（最嚴格）
{
  "env": "production",
  "permissions": {
    "allow": [],
    "deny": [
      "shell command rm -rf",
      "shell command DROP",
      "shell command TRUNCATE",
      "mcp tool edit in directory /prod/",
      "mcp tool edit in directory /release/",
      "shell command docker rm",
      "shell command docker rmi",
      "shell command kubectl delete"
    ]
  },
  "api": {
    "provider": "bedrock",
    "region": "ap-northeast-1",
    "model": "claude-sonnet-4-20250514"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "write_file|edit_file",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo \"{\\\"timestamp\\\": \\\"$(date -Iseconds)\\\", \\\"user\\\": \\\"$USER\\\", \\\"action\\\": \\\"file_modified\\\", \\\"file\\\": \\\"$CLAUDE_FILE_PATH\\\"}\" >> /var/log/claude-code/audit.jsonl'"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash /opt/claude-code/hooks/enterprise-safety-check.sh"
          }
        ]
      }
    ]
  },
  "disable_nonessential_traffic": true
}

// managed-settings.json — 開發環境配置（較寬鬆）
{
  "env": "development",
  "permissions": {
    "allow": [
      "shell command npm",
      "shell command npx",
      "shell command git",
      "shell command docker compose"
    ],
    "deny": [
      "shell command rm -rf /",
      "shell command sudo"
    ]
  },
  "api": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  }
}

# 🆕 使用 /install-github-app 一鍵安裝到 GitHub 倉庫
> /install-github-app

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

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review the changes in this PR.
            Focus on:
            1. Code quality and readability
            2. Potential bugs
            3. Security vulnerabilities
            4. Test coverage
            
            Provide actionable suggestions as PR comments.

# .github/workflows/claude-advanced.yml
name: Claude Code Advanced
on:
  pull_request:
    types: [opened, synchronize]
  issue_comment:
    types: [created]

jobs:
  # 自動 PR 審查
  auto-review:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          model: claude-sonnet-4-20250514
          timeout_minutes: 10
          # 🆕 claude_args 傳遞額外參數
          claude_args: "--output-format json --bare"
          prompt: |
            Perform a thorough code review.
            Check for OWASP Top 10 security issues.
            
  # 回應 PR 中的 @claude 提及
  respond-to-mention:
    if: >
      github.event_name == 'issue_comment' &&
      contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          trigger_phrase: "@claude"

# 使用 Amazon Bedrock
- uses: anthropics/claude-code-action@v1
  with:
    use_bedrock: true
    aws_region: us-east-1
    aws_access_key_id: ${{ secrets.AWS_ACCESS_KEY_ID }}
    aws_secret_access_key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

# 使用 Google Vertex AI
- uses: anthropics/claude-code-action@v1
  with:
    use_vertex: true
    vertex_project_id: ${{ secrets.GCP_PROJECT_ID }}
    vertex_region: us-east5

# .gitlab-ci.yml
stages:
  - review

claude-code-review:
  stage: review
  image: node:20
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
    # 🆕 AI_FLOW_* 變數由 GitLab CI 自動注入
    # AI_FLOW_MR_IID: Merge Request ID
    # AI_FLOW_PROJECT_PATH: 專案路徑
    # AI_FLOW_BASE_SHA: 基準 commit SHA
  before_script:
    - npm install -g @anthropic-ai/claude-code
  script:
    - |
      claude -p "
        Review the merge request changes.
        Files changed: $(git diff --name-only origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME)
        
        Focus on:
        1. Code quality
        2. Security issues
        3. Breaking changes
        
        Output as structured markdown.
      " --output-format text > review-report.md
    - cat review-report.md
  artifacts:
    paths:
      - review-report.md
    expire_in: 7 days

# 在 MR 評論中
@claude 請審查這個 MR 的安全性

# 在 Issue 中
@claude 這個 bug 可能的原因是什麼？請分析相關程式碼

#!/bin/bash
# ci-claude-tasks.sh

# 1. 程式碼品質檢查
claude -p "Analyze code quality in src/ directory. Report issues." \
  --output-format json > quality-report.json

# 2. 安全掃描
claude -p "Scan for security vulnerabilities in the codebase." \
  --output-format json > security-report.json

# 3. 文件生成
claude -p "Generate API documentation for all public endpoints." \
  --output-format text > api-docs.md

# 4. 變更摘要
claude -p "Summarize all changes since the last tag." \
  --output-format text > changelog-entry.md

# CLAUDE.md - CI 環境特別指令

## CI 環境注意事項
- 這是 CI 環境，不要嘗試開啟瀏覽器或互動式界面
- 所有輸出應該是結構化的（JSON 或 Markdown）
- 不要修改 .github/ 或 .gitlab-ci.yml
- 測試失敗時提供詳細的錯誤分析，不要嘗試修復

## 審查標準
- 依照 /docs/code-review-checklist.md 的清單
- 安全問題標記為 CRITICAL
- 效能問題標記為 WARNING
- 程式碼風格問題標記為 INFO

# .github/workflows/release-notes.yml
name: Auto Release Notes
on:
  push:
    tags:
      - 'v*'

jobs:
  release-notes:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          
      - name: Get previous tag
        id: prev_tag
        run: echo "tag=$(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || echo '')" >> $GITHUB_OUTPUT
          
      - name: Generate Release Notes with Claude
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Generate release notes for ${{ github.ref_name }}.
            Compare changes since ${{ steps.prev_tag.outputs.tag }}.
            
            Format:
            ## What's New
            - Feature descriptions with PR references
            
            ## Bug Fixes
            - Bug fix descriptions
            
            ## Breaking Changes
            - Any breaking changes (highlight clearly)
            
            ## Contributors
            - List contributors
            
            Write in both English and Traditional Chinese (繁體中文).
          timeout_minutes: 5

# .github/workflows/issue-analysis.yml
name: Issue Auto Analysis
on:
  issues:
    types: [opened]

jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      issues: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Analyze issue #${{ github.event.issue.number }}:
            Title: ${{ github.event.issue.title }}
            Body: ${{ github.event.issue.body }}
            
            Tasks:
            1. Identify the type (bug/feature/question)
            2. If bug: locate likely affected files and suggest a fix
            3. If feature: suggest implementation approach
            4. Estimate complexity (low/medium/high)
            5. Suggest labels
            
            Output as a helpful comment on the issue.
          trigger_phrase: "auto-analyze"

# .github/workflows/dependency-review.yml
name: Dependency Security Review
on:
  pull_request:
    paths:
      - 'package.json'
      - 'package-lock.json'
      - 'pom.xml'
      - 'build.gradle'
      - 'requirements.txt'
      - 'go.mod'

jobs:
  review-deps:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Get changed dependency files
        id: deps
        run: |
          echo "files=$(git diff --name-only ${{ github.event.pull_request.base.sha }} -- | grep -E '(package\.json|pom\.xml|build\.gradle|requirements\.txt|go\.mod)' | tr '\n' ' ')" >> $GITHUB_OUTPUT
      
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          model: claude-sonnet-4-20250514
          prompt: |
            Review dependency changes in files: ${{ steps.deps.outputs.files }}
            
            For each changed dependency:
            1. Check if it's a known vulnerable version
            2. Verify the version bump is appropriate (major/minor/patch)
            3. Check license compatibility
            4. Flag any dependencies with known security issues
            
            Rate overall risk: LOW / MEDIUM / HIGH / CRITICAL

# bitbucket-pipelines.yml
pipelines:
  pull-requests:
    '**':
      - step:
          name: Claude Code Review
          image: node:20
          script:
            - npm install -g @anthropic-ai/claude-code
            - |
              claude -p "
                Review the code changes in this pull request.
                Changed files: $(git diff --name-only origin/$BITBUCKET_PR_DESTINATION_BRANCH)
                
                Focus on:
                1. Code quality and maintainability
                2. Security vulnerabilities (OWASP Top 10)
                3. Performance issues
                4. Test coverage
                
                Output as structured markdown suitable for PR comment.
              " --output-format text > review.md
            - cat review.md
          artifacts:
            - review.md

  custom:
    weekly-security-scan:
      - step:
          name: Weekly Security Audit
          image: node:20
          script:
            - npm install -g @anthropic-ai/claude-code
            - claude -p "Perform a comprehensive security audit of the entire codebase. Focus on OWASP Top 10. Output findings in JSON format." --output-format json > security-audit.json
          artifacts:
            - security-audit.json

# azure-pipelines.yml
trigger:
  - none

pr:
  branches:
    include:
      - main
      - develop

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'
    displayName: 'Install Node.js'

  - script: npm install -g @anthropic-ai/claude-code
    displayName: 'Install Claude Code'

  - script: |
      claude -p "
        Review the code changes in the current PR.
        Changed files: $(git diff --name-only origin/$(System.PullRequest.TargetBranch))
        
        Provide:
        1. Summary of changes
        2. Code quality assessment
        3. Security review
        4. Suggestions for improvement
      " --output-format text > $(Build.ArtifactStagingDirectory)/review.md
    displayName: 'Claude Code Review'
    env:
      ANTHROPIC_API_KEY: $(ANTHROPIC_API_KEY)

  - task: PublishBuildArtifacts@1
    inputs:
      PathtoPublish: '$(Build.ArtifactStagingDirectory)/review.md'
      ArtifactName: 'claude-review'
    displayName: 'Publish Review'

// my-mcp-server/src/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "company-tools",
  version: "1.0.0",
});

// 定義工具：查詢 JIRA Issue
server.tool(
  "get-jira-issue",
  "取得 JIRA Issue 的詳細資訊",
  {
    issueKey: z.string().describe("JIRA Issue Key，例如 PROJ-123"),
  },
  async ({ issueKey }) => {
    const response = await fetch(
      `https://jira.company.com/rest/api/2/issue/${issueKey}`,
      {
        headers: {
          "Authorization": `Bearer ${process.env.JIRA_TOKEN}`,
          "Content-Type": "application/json",
        },
      }
    );
    const issue = await response.json();
    
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            key: issue.key,
            summary: issue.fields.summary,
            status: issue.fields.status.name,
            assignee: issue.fields.assignee?.displayName,
            description: issue.fields.description,
          }, null, 2),
        },
      ],
    };
  }
);

// 定義工具：搜尋 Confluence 文件
server.tool(
  "search-confluence",
  "搜尋 Confluence 知識庫",
  {
    query: z.string().describe("搜尋關鍵字"),
    spaceKey: z.string().optional().describe("Confluence Space Key"),
  },
  async ({ query, spaceKey }) => {
    const cql = spaceKey
      ? `space = "${spaceKey}" AND text ~ "${query}"`
      : `text ~ "${query}"`; 
    
    const response = await fetch(
      `https://confluence.company.com/rest/api/content/search?cql=${encodeURIComponent(cql)}`,
      {
        headers: {
          "Authorization": `Bearer ${process.env.CONFLUENCE_TOKEN}`,
        },
      }
    );
    const results = await response.json();
    
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            results.results.map((r: any) => ({
              title: r.title,
              url: `https://confluence.company.com${r._links.webui}`,
              excerpt: r.excerpt,
            })),
            null,
            2
          ),
        },
      ],
    };
  }
);

// 啟動 Server
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Company Tools MCP Server running");
}

main().catch(console.error);

{
  "mcpServers": {
    "company-tools": {
      "command": "node",
      "args": ["./my-mcp-server/dist/index.js"],
      "env": {
        "JIRA_TOKEN": "${JIRA_TOKEN}",
        "CONFLUENCE_TOKEN": "${CONFLUENCE_TOKEN}"
      }
    }
  }
}

---
name: security-review
description: 進行程式碼安全審查，檢查 OWASP Top 10 漏洞
tools: read_file, grep_search, semantic_search
---

# Security Review Skill

## 審查流程
1. 讀取目標檔案
2. 檢查以下安全問題：
   - SQL Injection
   - XSS (Cross-Site Scripting)
   - CSRF (Cross-Site Request Forgery)
   - Insecure Direct Object References
   - Security Misconfiguration
   - Sensitive Data Exposure
   - Missing Authentication
   - Broken Access Control

## 輸出格式
以 Markdown 表格輸出，包含：
- 檔案名稱
- 行號
- 漏洞類型
- 嚴重程度（Critical/High/Medium/Low）
- 建議修正方式

## 注意事項
- 只報告確認的漏洞，避免誤報
- 對於不確定的問題，標記為「建議審查」
- 提供具體的修正程式碼範例

---
name: performance-review
description: 分析程式碼效能問題，識別 N+1 查詢、記憶體洩漏、不必要的計算
tools: read_file, grep_search, semantic_search
---

# Performance Review Skill

## 檢查項目
1. **資料庫**
   - N+1 查詢模式
   - 缺少索引的查詢
   - 過大的查詢結果集

2. **記憶體**
   - 未關閉的資源（Stream、Connection）
   - 不必要的大型集合
   - 快取未設定過期時間

3. **演算法**
   - O(n²) 或更高複雜度的迴圈
   - 重複計算
   - 不必要的字串拼接

## 輸出格式
| 檔案 | 行號 | 問題類型 | 影響程度 | 建議 |
|------|------|---------|---------|------|

---
name: api-doc-generator
description: 從程式碼自動產生 API 文件，支援 RESTful 和 GraphQL
tools: read_file, grep_search, write_file
---

# API Documentation Generator

## 支援格式
- OpenAPI 3.0 (Swagger)
- Markdown
- API Blueprint

## 生成流程
1. 掃描 Controller/Route 定義
2. 提取：HTTP Method, Path, Parameters, Request Body, Response
3. 從程式碼註解提取描述
4. 產生 OpenAPI YAML 文件
5. 產生人類可讀的 Markdown 文件

## 輸出位置
- OpenAPI: `docs/api/openapi.yaml`
- Markdown: `docs/api/README.md`

my-plugin/
├── plugin.json          # Plugin 描述檔
├── agents/              # Agent 定義
│   ├── reviewer.md      # 程式碼審查 Agent
│   └── architect.md     # 架構設計 Agent
├── skills/              # Skill 定義
│   ├── SKILL.md         # 根 Skill
│   └── security/
│       └── SKILL.md     # 安全相關 Skill
├── tools/
│   ├── analyze.sh       # 分析工具
│   ├── generate.sh      # 生成工具
│   └── validate.sh      # 驗證工具
├── prompts/
│   └── review.md        # Prompt 模板
├── mcp-servers/
│   └── custom-server/   # 自訂 MCP Server
│       ├── index.ts
│       └── package.json
└── README.md            # 說明文件

{
  "name": "company-dev-tools",
  "version": "1.0.0",
  "description": "公司內部開發工具集",
  "author": "DevOps Team",
  "license": "MIT",
  "repository": "https://github.com/company/claude-plugin-dev-tools",
  "claude-code": {
    "minVersion": "1.0.0"
  },
  "tools": [
    {
      "name": "analyze-dependencies",
      "description": "分析專案依賴的安全性和版本狀態",
      "command": "./tools/analyze.sh",
      "args": ["--format", "json"]
    },
    {
      "name": "generate-api-client",
      "description": "從 OpenAPI spec 生成 API client",
      "command": "./tools/generate.sh",
      "args": ["--spec", "{spec_url}", "--output", "{output_dir}"]
    },
    {
      "name": "validate-schema",
      "description": "驗證資料庫 schema 變更的向後相容性",
      "command": "./tools/validate.sh",
      "args": ["--migration", "{migration_file}"]
    }
  ],
  "agents": [
    {
      "name": "code-reviewer",
      "path": "./agents/reviewer.md"
    },
    {
      "name": "solution-architect",
      "path": "./agents/architect.md"
    }
  ],
  "skills": [
    {
      "path": "./skills/"
    }
  ],
  "configuration": {
    "registry_url": {
      "type": "string",
      "description": "公司 npm registry URL",
      "default": "https://npm.company.com"
    },
    "team_name": {
      "type": "string",
      "description": "團隊名稱，用於產生的文件標頭"
    }
  }
}

#!/bin/bash
# tools/analyze.sh - 依賴分析工具

set -euo pipefail

FORMAT=${1:-"text"}

echo "Analyzing project dependencies..."

# 檢查 Node.js 專案
if [ -f "package.json" ]; then
    echo "## Node.js Dependencies"
    npm audit --json 2>/dev/null | jq '.vulnerabilities | to_entries[] | {
        package: .key,
        severity: .value.severity,
        title: .value.title,
        url: .value.url
    }'
fi

# 檢查 Java 專案
if [ -f "pom.xml" ] || [ -f "build.gradle" ]; then
    echo "## Java Dependencies"
    if [ -f "pom.xml" ]; then
        mvn dependency:tree -DoutputType=dot 2>/dev/null
    fi
fi

# 檢查 Python 專案
if [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
    echo "## Python Dependencies"
    pip-audit --format json 2>/dev/null || echo "pip-audit not installed"
fi

醫療系統開發套件
├── .mcp.json
│   └── mcpServers:
│       ├── fhir-server      ← FHIR API 整合
│       ├── hl7-parser       ← HL7 訊息解析
│       └── medical-terms    ← 醫學術語查詢
├── .claude/
│   └── skills/
│       ├── hipaa-check/SKILL.md    ← HIPAA 合規檢查
│       ├── phi-detection/SKILL.md  ← PHI 資料偵測
│       └── audit-log/SKILL.md      ← 存取稽核
└── CLAUDE.md
    └── 醫療系統開發規範、合規要求、術語對照

// .mcp.json
{
  "mcpServers": {
    "fhir-server": {
      "command": "node",
      "args": ["./tools/mcp-fhir/dist/index.js"],
      "env": {
        "FHIR_BASE_URL": "${FHIR_SERVER_URL}",
        "FHIR_AUTH_TOKEN": "${FHIR_TOKEN}"
      }
    },
    "medical-terms": {
      "command": "node",
      "args": ["./tools/mcp-medical-terms/dist/index.js"],
      "env": {
        "TERMINOLOGY_DB": "./data/medical-terms.db"
      }
    }
  }
}

<!-- .claude/skills/hipaa-check/SKILL.md -->
---
name: hipaa-compliance-check
description: 檢查程式碼是否符合 HIPAA 法規要求，包括 PHI 保護、存取控制、稽核日誌
tools: read_file, grep_search, semantic_search
---

# HIPAA 合規檢查

## 檢查項目
1. **PHI 處理**
   - 所有 PHI 欄位是否加密儲存
   - 傳輸中是否使用 TLS
   - 日誌中是否不含 PHI

2. **存取控制**
   - 是否實作 RBAC
   - 是否有 session timeout
   - 是否記錄存取日誌

3. **稽核**
   - 是否記錄所有 PHI 存取
   - 日誌是否不可竄改
   - 是否有定期審查機制

## 輸出格式
| 規則 | 狀態 | 檔案 | 行號 | 說明 |
|------|------|------|------|------|

// CLAUDE.md 中定義多語言開發規範和 Custom Commands

# 全端專案開發規範

## 各子系統 CLAUDE.md 架構
本專案包含多個子系統，各自有獨立的 CLAUDE.md：

### 前端（frontend/CLAUDE.md）
- React 18 + TypeScript 5.5
- 使用 Tailwind CSS
- 測試用 Vitest + Testing Library
- 分支策略：feature/* → develop → main

### 後端（backend/CLAUDE.md）  
- Go 1.23 + Gin Framework
- PostgreSQL 16 + Redis 7
- 測試用 go test + testify
- API 規範：RESTful + OpenAPI 3.1

### 基礎設施（infra/CLAUDE.md）
- Terraform 1.9 + AWS
- Kubernetes 1.31
- ArgoCD + GitOps
- 監控：Prometheus + Grafana

## 跨系統 Custom Commands

### /project:fullstack-feature
開發完整的全端功能：
1. 在 backend/ 建立 API endpoint
2. 在 frontend/ 建立對應的 UI 元件
3. 撰寫前後端的測試
4. 更新 OpenAPI 文件
5. 建立 database migration（如需要）

### /project:deploy-check
跨系統部署前檢查：
1. 後端 API 相容性檢查
2. 前端 bundle size 檢查
3. Database migration 向後相容性
4. Kubernetes manifest 驗證
5. 環境變數完整性確認

<!-- .claude/skills/test-framework/SKILL.md -->
---
name: comprehensive-test-generator
description: 產生全面的測試案例，包括單元測試、整合測試、E2E 測試
tools: read_file, write_file, grep_search, run_terminal_command
---

# 全面測試生成框架

## 測試層次
1. **單元測試**（target: 80%+ 覆蓋率）
   - Happy path
   - Edge cases（null、空值、邊界值）
   - Error cases（exception、timeout）
   
2. **整合測試**
   - API endpoint 測試
   - Database query 測試
   - 第三方服務 mock 測試

3. **E2E 測試**
   - 使用者關鍵路徑
   - 認證/授權流程
   - 交易流程

## 測試命名規範
- 格式：should_[預期行為]_when_[條件]
- 範例：should_return_404_when_user_not_found

## 測試資料策略
- 使用 Factory Pattern 建立測試資料
- 每個測試獨立的資料隔離
- 不依賴外部服務（使用 stub/mock）

## 輸出結構
```plaintext
tests/
├── unit/           ← 單元測試（映射 src/ 結構）
├── integration/    ← 整合測試
├── e2e/           ← E2E 測試
└── fixtures/       ← 測試資料 factory

#### 自訂開發成熟度模型

| 等級 | 名稱 | 配置內容 | 適用團隊 |
|------|------|---------|---------|
| **L1 基礎** | 單一 CLAUDE.md | 基本規範、常用命令 | 個人開發者 |
| **L2 標準** | CLAUDE.md + Custom Commands | 標準化流程、共享配置 | 小團隊（3-5人） |
| **L3 進階** | + Skills + Hooks | 自動化品質檢查、CI/CD | 中型團隊（5-15人） |
| **L4 平台** | + MCP Servers + Plugins | 企業工具整合、統一平台 | 大型團隊（15+人） |
| **L5 生態** | + Agent Teams + 自動化 | 全自動化開發流程 | 組織級導入 |

```mermaid
graph LR
    L1[L1 基礎<br>CLAUDE.md] --> L2[L2 標準<br>+Custom Commands]
    L2 --> L3[L3 進階<br>+Skills +Hooks]
    L3 --> L4[L4 平台<br>+MCP +Plugins]
    L4 --> L5[L5 生態<br>+Agent Teams]
    
    style L1 fill:#f3f4f6,stroke:#9ca3af
    style L2 fill:#dbeafe,stroke:#3b82f6
    style L3 fill:#dcfce7,stroke:#22c55e
    style L4 fill:#fef3c7,stroke:#f59e0b
    style L5 fill:#fce7f3,stroke:#ec4899

# 啟動 Claude Code 並啟用已配置的 channel
claude --channels

# channels 會在啟動時連接所有宣告 claude/channel 能力的 MCP Server

# channel_server.py — 簡易 Channel MCP Server 範例概念
"""
Channel MCP Server 需要：
1. 宣告 claude/channel capability
2. 實作訊息接收與推送邏輯
3. 遵循 MCP protocol 規範

詳細規範請參考：
- MCP SDK: https://modelcontextprotocol.io/quickstart/server
- Channels reference: https://code.claude.com/docs/en/channels-reference
"""

企業 Channel 架構：

┌─────────────────────────────────────────┐
│           企業訊息匯流排                    │
│  (Slack / Teams / 自建系統)               │
└────────┬────────────┬───────────────────┘
         │            │
    ┌────▼────┐  ┌───▼────┐
    │ Channel │  │Channel │
    │ Server A│  │Server B│
    └────┬────┘  └───┬────┘
         │           │
    ┌────▼───────────▼────┐
    │  Claude Code 實例    │
    │  (managed-mcp.json) │
    └─────────────────────┘

---
name: my-skill
description: 技能的簡要描述
user-invocable: true
disable-model-invocation: false
allowed-tools:
  - Read
  - Edit
  - Bash(npm test*)
model: sonnet
effort: high
---

# 技能指引

[技能的完整指引內容，Claude 會依據這些指引執行任務]

## 使用方式

使用者可以透過 `/my-skill` 呼叫此技能。

$ARGUMENTS 會被替換為使用者提供的參數。

SKILL.md             SKILL.md             SKILL.md
    ↓                    ↓                    ↓
Claude Code          VS Code Copilot      其他 AI Editor
    ↓                    ↓                    ↓
相同行為              相同行為              相同行為

# 啟動互動式 Claude Code
claude

# 啟動並恢復最近的對話
claude --continue
claude -c

# Headless 模式（非互動式）
claude -p "你的 prompt"
claude --print "你的 prompt"

# 指定輸出格式
claude -p "prompt" --output-format json
claude -p "prompt" --output-format text
claude -p "prompt" --output-format stream-json

# 🆕 結構化輸出（JSON Schema）
claude -p "列出 API" --output-format json --json-schema '{"type":"object",...}'

# 🆕 --bare 模式（跳過自動發現，極速啟動）
claude -p "prompt" --bare

# 從 stdin 讀取
echo "prompt" | claude -p -
cat file.txt | claude -p "分析這個檔案"

# 指定模型
claude --model claude-sonnet-4-20250514
claude --model claude-opus-4-20250514

# 🆕 啟動 Server 模式（Remote Control）
claude --server
claude --spawn

# 🆕 啟用 Channels
claude --channels

# Debug 模式
claude --debug
claude --verbose

## Custom Commands

### /project:setup
執行專案初始化步驟...

### /project:test
執行完整測試套件...

### /project:deploy
執行部署流程...

# 查看配置
claude config list

# 設定配置值
claude config set <key> <value>

# 重設配置
claude config reset

# 常用配置項
claude config set theme dark
claude config set autoCompact true
claude config set preferredModel claude-sonnet-4-20250514

# 指定最大 Token 數
claude -p "prompt" --max-tokens 4096

# 停用特定工具
claude --disable-tool Bash
claude --disable-tool Edit

# 指定 CLAUDE.md 路徑
claude --memory /path/to/CLAUDE.md

# 指定允許的權限（非互動模式重要）
claude -p "prompt" --allowedTools "Read,Edit,Bash(npm test)"

# 完全跳過權限提示（CI 用）
claude -p "prompt" --dangerously-skip-permissions

# 設定 API Base URL（企業 Proxy）
claude --api-base-url https://proxy.company.com/v1

# 啟用 MCP debug
claude --mcp-debug

# 指定配置目錄
claude --config-dir /custom/config/path

# 多輪 Headless 對話（帶 session ID）
claude -p "分析這段程式碼" --session-id my-session-123
claude -p "繼續上面的分析" --session-id my-session-123 --continue

# 🆕 追加系統提示（可與 --bare 搭配）
claude -p "prompt" --append-system-prompt "額外系統指令"
claude -p "prompt" --append-system-prompt-file ./system-prompt.md

# 🆕 指定配置檔案（搭配 --bare 模式）
claude -p "prompt" --bare --settings ./custom-settings.json
claude -p "prompt" --bare --mcp-config ./custom-mcp.json
claude -p "prompt" --bare --agents ./agents/
claude -p "prompt" --bare --plugin-dir ./my-plugin/

# 分析程式碼複雜度
claude -p "分析 src/ 目錄下所有檔案的程式碼複雜度，列出 Cyclomatic Complexity > 10 的方法" \
  --output-format json > complexity-report.json

# 尋找技術債
claude -p "搜尋專案中的所有 TODO、FIXME、HACK 註解，依嚴重度分類並建議處理順序" \
  --output-format text > tech-debt-report.md

# 程式碼風格一致性檢查
claude -p "檢查專案是否有不一致的命名慣例（camelCase vs snake_case），列出所有不一致的地方" \
  --output-format text

# 跨檔案依賴分析
claude -p "分析 src/services/ 下所有 Service 的依賴關係，產出 Mermaid 依賴圖" \
  --output-format text > dependency-graph.md

# 生成 API 文件
claude -p "為 src/controllers/ 下所有 Controller 生成 OpenAPI 3.0 規格文件" \
  --output-format text > openapi-spec.yaml

# 生成 README
claude -p "根據專案的 package.json、目錄結構和主要原始碼，生成完整的 README.md，包含安裝步驟、使用方式、API 說明" \
  --output-format text > README.md

# 生成 CHANGELOG
claude -p "根據 git log 生成從上一個 tag 到現在的 CHANGELOG，使用 Keep a Changelog 格式" \
  --output-format text > CHANGELOG-entry.md

# 生成架構文件
claude -p "分析專案架構，產出系統架構文件，包含 Mermaid 架構圖、模組說明、資料流" \
  --output-format text > architecture.md

# 為特定檔案生成測試
claude -p "為 src/services/PaymentService.ts 生成完整的單元測試，包含正向、反向、邊界測試案例" \
  --output-format text

# 分析測試覆蓋率缺口
claude -p "分析 coverage/lcov.info，找出測試覆蓋率低於 80% 的檔案，建議需要補充的測試案例" \
  --output-format json > coverage-gaps.json

# 生成 E2E 測試場景
claude -p "根據 src/routes/ 的 API 端點，生成 Playwright E2E 測試場景" \
  --output-format text

# 修復失敗的測試
claude -p "以下測試失敗了，請分析原因並修復：$(npm test 2>&1 | tail -50)" \
  --output-format text

# OWASP 安全掃描
claude -p "掃描專案程式碼，檢查 OWASP Top 10 安全漏洞，產出詳細報告" \
  --output-format json > security-scan.json

# 授權檢查
claude -p "檢查所有依賴的授權（license），標記任何可能與 MIT License 不相容的依賴" \
  --output-format text

# 敏感資料掃描
claude -p "掃描專案中是否有硬編碼的密碼、API Key、Token 等敏感資料（不包含 .env.example）" \
  --output-format json > secrets-scan.json

# 智慧 Commit 訊息
claude -p "根據 $(git diff --cached) 生成符合 Conventional Commits 格式的提交訊息" \
  --output-format text

# PR 描述生成
claude -p "根據 $(git log --oneline origin/main..HEAD) 的提交歷史，生成 Pull Request 描述，包含變更摘要、測試步驟、影響範圍" \
  --output-format text > pr-description.md

# 衝突分析
claude -p "分析 $(git diff --name-only --diff-filter=U) 中的合併衝突，建議最佳的解決方案" \
  --output-format text

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Bash(npm run *)",
      "mcp tool server_name tool_name"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "mcp tool edit in directory /production/"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "tool_name",
        "hooks": [
          {
            "type": "command",
            "command": "script.sh"
          }
        ]
      }
    ],
    "PostToolUse": [],
    "PrePrompt": [],
    "PostPrompt": [],
    "Notification": [],
    "Stop": [],
    "SubagentStop": [],
    "PreCompact": [],
    "PostCompact": [],
    "PreToolUse_Edit": [],
    "PostSession": []
  },
  "env": {
    "VARIABLE_NAME": "value"
  }
}

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@scope/server-package"],
      "env": {
        "API_KEY": "value"
      },
      "cwd": "/optional/working/directory"
    },
    "remote-server": {
      "type": "sse",
      "url": "https://mcp-server.example.com/sse",
      "headers": {
        "Authorization": "Bearer token"
      }
    },
    "streamable-http-server": {
      "type": "streamable-http",
      "url": "https://mcp-server.example.com/mcp"
    }
  }
}

# 專案名稱

## 技術棧
（列出語言、框架、資料庫等）

## 編碼規範
（列出命名慣例、格式規範等）

## 架構說明
（描述專案架構、目錄結構等）

## 常用命令
（列出 build、test、deploy 等命令）

## 禁止事項
（列出 Claude Code 不應該做的事情）

## Custom Commands
（定義專案特定的 slash commands）

{
  "permissions": {
    "deny": [
      "Bash(curl * | bash)",
      "Bash(wget * | sh)",
      "Bash(rm -rf /)",
      "Bash(git push --force *)",
      "Edit(/etc/*)",
      "Edit(*.pem)",
      "Edit(*.key)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/opt/security/audit-command.sh"
          }
        ]
      }
    ],
    "PostSession": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/opt/security/session-audit.sh"
          }
        ]
      }
    ]
  },
  "env": {
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "ANTHROPIC_API_BASE_URL": "https://claude-proxy.company.internal/v1"
  }
}

{
  "mcpServers": {
    "company-auth": {
      "command": "npx",
      "args": ["-y", "@company/mcp-auth-server"],
      "env": {
        "AUTH_URL": "https://auth.company.internal"
      }
    },
    "company-wiki": {
      "command": "npx",
      "args": ["-y", "@company/mcp-wiki-server"],
      "env": {
        "WIKI_URL": "https://wiki.company.internal"
      }
    }
  }
}

# 排除大型資料目錄
data/
*.csv
*.parquet

# 排除建置輸出
dist/
build/
node_modules/

# 排除敏感檔案
*.pem
*.key
.env*
secrets/

# 排除非程式碼檔案
*.jpg
*.png
*.gif
*.mp4
*.zip

# 排除日誌
logs/
*.log

# 但保留特定日誌
!error.log