<!-- .claude/agents/security-reviewer.md -->
---
name: security-reviewer
description: 審查程式碼的安全漏洞
tools: Read, Grep, Glob, Bash
model: opus
---
你是資深資安工程師。審查程式碼是否有：
- 注入漏洞（SQL / XSS / Command Injection）
- 身份驗證與授權缺陷
- 程式碼中的密鑰或憑證
- 不安全的資料處理

提供具體行號引用與修復建議。

Session A（Writer）：實作功能
    ↓ 產出程式碼
Session B（Reviewer）：審查 Session A 的產出
    ↓ 回饋建議
Session A：根據回饋修改

# 安裝 GitHub CLI（Claude Code 會自動使用）
gh auth login

# Claude Code 可直接操作
claude -p "建立一個 PR，標題為 feat: add user authentication"

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

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Claude Code Review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          review_type: comprehensive

# 連接 Jira MCP Server
claude mcp add jira -- npx @anthropic-ai/mcp-server-jira

# 連接資料庫 MCP Server
claude mcp add postgres -- npx @anthropic-ai/mcp-server-postgres

# 連接 Sentry 監控
claude mcp add sentry -- npx @anthropic-ai/mcp-server-sentry

irm https://claude.ai/install.ps1 | iex

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

winget install Anthropic.ClaudeCode

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

brew install --cask claude-code

claude --version
# 預期輸出：claude-code v2.x.x

# 首次啟動
cd your-project
claude
# 系統會提示登入

// .vscode/settings.json
{
  "claude-code.autoStart": true,
  "claude-code.defaultModel": "opus",
  "editor.formatOnSave": true,
  "terminal.integrated.defaultProfile.windows": "PowerShell"
}

claude
# 首次執行自動開啟瀏覽器認證

# 設定環境變數
export ANTHROPIC_API_KEY=sk-ant-api03-xxxxx

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-api03-xxxxx"

# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
# 需設定 AWS 認證（AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY）

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
# 需設定 GCP 認證（GOOGLE_APPLICATION_CREDENTIALS）

# Microsoft Azure AI Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
# 需設定 Azure 認證

cd your-project
claude
# 進入互動模式後執行
/init

# 建立 .claude 目錄結構
mkdir -p .claude/skills .claude/agents .claude/rules

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(mvn *)",
      "Bash(git *)",
      "Bash(gh *)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(DROP TABLE*)"
    ]
  },
  "autoMemoryEnabled": true
}

claude -p "審查這次 PR 變更的安全性與程式碼品質" \
  --permission-mode auto \
  --allowedTools "Read,Grep,Glob" \
  --output-format stream-json \
  --verbose

your-project/
├── .claude/                          # Claude Code 設定根目錄
│   ├── CLAUDE.md                     # 專案級指令（團隊共用，commit 進 Git）
│   ├── settings.json                 # 專案級設定（權限、Hook 等）
│   ├── settings.local.json           # 個人本地設定（加入 .gitignore）
│   ├── agents/                       # 自訂 Subagent 定義
│   │   ├── planner.md                # 規劃 Agent
│   │   ├── security-reviewer.md      # 安全審查 Agent
│   │   ├── code-reviewer.md          # 程式碼審查 Agent
│   │   └── test-generator.md         # 測試產出 Agent
│   ├── skills/                       # 可重用技能
│   │   ├── fix-issue/
│   │   │   └── SKILL.md              # 修復 Issue 技能
│   │   ├── create-api/
│   │   │   └── SKILL.md              # 建立 API 技能
│   │   ├── security-scan/
│   │   │   └── SKILL.md              # 安全掃描技能
│   │   └── ssdlc-review/
│   │       └── SKILL.md              # SSDLC 審查技能
│   └── rules/                        # 規則檔案
│       ├── code-style.md             # 程式碼風格
│       ├── security.md               # 安全規則
│       ├── testing.md                # 測試規則
│       └── api-design.md             # API 設計規則
├── CLAUDE.md                         # 專案根目錄指令（或放 .claude/ 內）
├── CLAUDE.local.md                   # 個人偏好（加入 .gitignore）
├── src/
├── tests/
├── docs/
└── .github/
    └── workflows/
        └── claude-code-review.yml    # CI/CD 整合

# 專案指引

## 建置與測試
- 建置：`mvn clean compile`
- 測試：`mvn test`
- 型別檢查：`mvn checkstyle:check`

## 程式碼風格
- 使用 4 空格縮排
- Java 類別使用 PascalCase
- 方法與變數使用 camelCase
- 常數使用 UPPER_SNAKE_CASE
- 使用 JavaDoc 格式撰寫註解

## 測試
- 每個 Service 類別必須有對應的 Unit Test
- 使用 JUnit 5 + Mockito
- 測試覆蓋率需達 80%
- 優先執行單一測試，避免整包跑

## Git 規範
- 分支命名：`feature/JIRA-123-description`
- Commit 訊息：`type(scope): description`
  - type: feat, fix, refactor, test, docs, chore
- PR 必須通過 Code Review 後才可合併

## 安全
- 敏感資料不可 hardcode
- 所有外部輸入必須驗證
- SQL 使用 Prepared Statement
- 啟用 CORS 白名單

## 參考
- @docs/architecture.md
- @docs/api-spec.md

<!-- .claude/skills/create-api/SKILL.md -->
---
name: create-api
description: 建立 RESTful API 端點
---
根據以下需求建立新的 API 端點：$ARGUMENTS

### 執行步驟
1. 分析需求，確認 HTTP Method、URL Path、Request/Response Schema
2. 在 `src/main/java/com/tutorial/api/` 建立 Controller
3. 在 `src/main/java/com/tutorial/service/` 建立 Service
4. 在 `src/main/java/com/tutorial/repository/` 建立 Repository（如需要）
5. 建立 DTO（Data Transfer Object）
6. 加入輸入驗證（使用 Jakarta Validation）
7. 撰寫 Unit Test
8. 撰寫 Integration Test
9. 更新 API 文件
10. 執行測試驗證

### 安全要求
- 所有輸入使用 @Valid 驗證
- 使用 Prepared Statement
- 啟用 Rate Limiting
- 記錄 Audit Log

# 在 Claude Code 中使用
/create-api 用戶管理 CRUD API，包含建立、查詢、更新、刪除

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx eslint --fix $FILE 2>/dev/null || true"
      }
    ],
    "PreCommit": [
      {
        "command": "mvn checkstyle:check && mvn test"
      }
    ]
  }
}

<!-- .claude/agents/planner.md -->
---
name: planner
description: 負責需求分析與任務拆解
tools: Read, Glob, Grep, WebSearch, AskUserQuestion
model: opus
---
你是資深架構師。負責：

1. 閱讀需求文件，整理為結構化 User Story
2. 識別技術風險與安全需求
3. 將大任務拆解為可執行的小任務（每個任務 < 2hr）
4. 建立依賴關係圖
5. 產出 SPEC.md

### 輸出格式
```markdown
# Feature: [功能名稱]
## User Stories
- [ ] US-001: 描述...
## Tasks
- [ ] T-001: 描述... (預估：1hr)
## Security Requirements
- SR-001: 描述...
## Dependencies
- T-002 depends on T-001
```

<!-- .claude/agents/security-reviewer.md -->
---
name: security-reviewer
description: 審查程式碼安全性，依據 OWASP Top 10
tools: Read, Grep, Glob, Bash
model: opus
---
你是資深資安工程師。依據 OWASP Top 10 (2025) 審查程式碼：

## 檢查項目
1. **A01 - Broken Access Control**：權限控制缺陷
2. **A02 - Cryptographic Failures**：加密不當
3. **A03 - Injection**：注入攻擊（SQL, XSS, Command）
4. **A04 - Insecure Design**：不安全的設計
5. **A05 - Security Misconfiguration**：配置錯誤
6. **A06 - Vulnerable Components**：含已知弱點的元件
7. **A07 - Auth Failures**：身份驗證失敗
8. **A08 - Data Integrity Failures**：資料完整性問題
9. **A09 - Logging Failures**：日誌與監控不足
10. **A10 - SSRF**：伺服器端請求偽造

## 輸出格式
| 嚴重度 | OWASP | 檔案:行號 | 問題描述 | 修復建議 |

❌ 錯誤做法：在同一個 Session 討論不同主題
    → Context 混亂，AI 品質下降

✅ 正確做法：
    Session 1：需求分析 → /clear
    Session 2：架構設計 → /clear
    Session 3：功能實作 → /clear

# 讓 Subagent 去探索 Codebase，不汙染主 Session
> 使用 subagent 調查 authentication 模組的 token refresh 機制

# 手動壓縮：保留 API 變更的上下文
/compact 專注在 API 變更和安全修正

# 自動壓縮：CLAUDE.md 中設定
# 壓縮時，永遠保留修改過的檔案清單和測試指令

# 恢復上次 Session
claude --continue

# 選擇歷史 Session
claude --resume

# 命名 Session 方便識別
/rename oauth-migration

.claude/skills/
├── fix-issue/
│   └── SKILL.md          # 主指令（必要）
├── create-api/
│   ├── SKILL.md           # 主指令
│   ├── template.md        # 範本
│   └── examples/
│       └── sample.md      # 範例輸出
└── deploy/
    ├── SKILL.md
    └── scripts/
        └── validate.sh    # Claude 可執行的腳本

---
name: fix-issue                       # 顯示名稱，也是 /slash-command
description: 修復 GitHub Issue         # Claude 用此判斷何時自動載入
disable-model-invocation: true        # 僅手動呼叫，Claude 不會自動觸發
allowed-tools: Bash(git *) Read Edit  # 此 Skill 啟用時自動授權的工具
disallowed-tools: Bash(rm *)          # 明確禁用的工具，與 allowed-tools 互補
model: sonnet                         # 覆寫此 Skill 執行時使用的模型
argument-hint: "<issue-number>"       # /fix-issue 自動完成時顯示的參數提示
context: fork                         # 在獨立 Subagent Context 中執行
agent: Explore                        # context: fork 時使用的 Agent 類型
paths:                                # 限制 Skill 僅在特定路徑啟用
  - "src/api/**/*.ts"
---

<!-- .claude/rules/api-security.md -->
---
paths:
  - "src/api/**/*.ts"
  - "src/controllers/**/*.java"
---

# API 安全規則
- 所有 API 端點必須包含輸入驗證
- 使用標準化的錯誤回應格式
- 加入 OpenAPI 文件註解

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 插件描述檔（name, version, description）
├── skills/                  # 插件內的 Skills
│   └── code-review/
│       └── SKILL.md
├── agents/                  # 插件內的 Agents
│   └── security-reviewer.md
├── hooks/
│   └── hooks.json           # 插件內的 Hooks
├── monitors/                # 插件內的背景監控設定
│   └── monitors.json        # 監控規則描述檔
├── bin/                     # 可執行檔，啟用插件時加入 PATH
├── .mcp.json                # MCP Server 設定
├── .lsp.json                # LSP Server 設定（Code Intelligence）
└── settings.json            # 預設設定

# 瀏覽插件市集
/plugin

# 安裝插件
/plugin install my-plugin

# 本地開發測試
claude --plugin-dir ./my-plugin

# 重新載入插件（開發中修改後）
/reload-plugins

# 使用 Plan Mode 分析需求
claude
# 按 Ctrl+G 切換到 Plan Mode

> 閱讀以下需求文件，產出結構化的 SPEC.md：
> @docs/requirements/user-management.md
> 
> 需包含：
> 1. User Stories（含驗收標準）
> 2. 非功能性需求（效能、安全、可用性）
> 3. 安全需求（依 OWASP Top 10）
> 4. 資料模型
> 5. API 端點清單
> 6. 異常情境處理

<!-- .claude/skills/analyze-requirements/SKILL.md -->
---
name: analyze-requirements
description: 將原始需求轉化為結構化規格文件
---
分析以下需求並產出完整規格文件：$ARGUMENTS

### 輸出結構
1. **功能需求**
   - User Story 格式：As a [角色], I want [功能], so that [價值]
   - 每個 Story 附帶驗收標準（Given-When-Then）

2. **非功能性需求**
   - 效能：回應時間 < 200ms (P95)
   - 可用性：99.9% SLA
   - 安全：OWASP Top 10 防護

3. **安全需求**
   - 身份驗證方式
   - 授權模型（RBAC/ABAC）
   - 資料加密需求
   - 稽核日誌需求

4. **技術約束**
   - 相容性要求
   - 第三方依賴限制

# 讓 Claude Code 產出需求追蹤矩陣
> 讀取 SPEC.md，產出需求追蹤矩陣（Requirements Traceability Matrix），
> 格式為 Markdown 表格，包含需求 ID、描述、對應測試案例、狀態

# 使用 Claude Code 產出架構設計
> 基於 @SPEC.md 的需求，設計系統架構：
> - 使用 Clean Architecture
> - 前端：Vue 3 + TypeScript
> - 後端：Spring Boot 3
> - 資料庫：PostgreSQL
> - 快取：Redis
> - 訊息佇列：RabbitMQ
> 
> 產出：
> 1. 系統架構圖（Mermaid）
> 2. 元件圖
> 3. 部署圖
> 4. 資料流圖
> 5. 安全架構圖

# 使用 Skill 產出 API 規格
/create-api 用戶管理模組，包含：
- POST /api/v1/users（建立用戶）
- GET /api/v1/users/{id}（查詢用戶）
- PUT /api/v1/users/{id}（更新用戶）
- DELETE /api/v1/users/{id}（刪除用戶）
- GET /api/v1/users（列表查詢，支援分頁）

需包含 OpenAPI 3.0 規格檔

# 使用 Security Agent 審查設計
> 使用 subagent security-reviewer 審查 @docs/architecture.md 的安全設計：
> - 認證機制是否安全
> - 授權模型是否完整
> - 資料傳輸是否加密
> - 敏感資料存儲策略
> - API 安全防護

# 步驟 1：Explore（Plan Mode）
# 按 Ctrl+G 切換到 Plan Mode
> 閱讀 @src/main/java/com/tutorial/ 理解目前的程式架構和命名慣例。
> 同時看一下測試是怎麼寫的。

# 步驟 2：Plan（Plan Mode）
> 我要新增 UserService，需要哪些檔案需要修改？
> 建立實作計畫。

# 按 Ctrl+G 可在文字編輯器中直接修改計畫後再讓 Claude 執行

# 步驟 3：Implement（Normal Mode）
# 切回 Normal Mode
> 依照你的計畫實作 UserService。
> 寫完後執行測試，修正所有失敗的測試。

# 步驟 4：Verify
> 使用 subagent 審查剛才的修改，檢查邊界情況和安全問題。

<!-- .claude/agents/code-reviewer.md -->
---
name: code-reviewer
description: 全面審查程式碼品質。Claude 在程式碼修改後會主動使用。
tools: Read, Grep, Glob, Bash
model: opus
memory: project
---
你是資深程式碼審查員。啟動後先執行 `git diff` 查看近期變更。

審查標準：

## 正確性
- 邏輯錯誤
- 邊界條件處理
- 空值處理
- 並發安全

## 可維護性
- 命名清晰度
- 方法長度（< 20 行）
- 類別職責單一
- 重複程式碼

## 效能
- N+1 查詢
- 不必要的記憶體配置
- 缺少快取
- 阻塞操作

## 安全
- 輸入驗證
- SQL Injection
- XSS
- 權限檢查

輸出格式：按嚴重度排列（Critical > Major > Minor > Info）

> 使用 subagent code-reviewer 審查 src/main/java/com/tutorial/service/ 的所有變更

# 產出 Unit Test
> 為 @src/main/java/com/tutorial/service/UserService.java 撰寫完整的 Unit Test：
> - 使用 JUnit 5 + Mockito
> - 覆蓋所有公開方法
> - 包含正常情境和異常情境
> - 包含邊界條件測試
> - 執行測試確認全部通過

# 產出 Integration Test
> 為 UserController 撰寫 Integration Test：
> - 使用 @SpringBootTest
> - 使用 TestRestTemplate
> - 測試完整 HTTP Request/Response
> - 包含認證測試

<!-- .claude/skills/generate-tests/SKILL.md -->
---
name: generate-tests
description: 為指定類別產出完整測試
---
為以下類別產出完整測試：$ARGUMENTS

### 測試層級
1. **Unit Test**
   - Mock 所有外部依賴
   - 測試每個公開方法
   - 包含 Happy Path + Error Path + Edge Case

2. **Integration Test**（如為 Controller）
   - 測試完整 HTTP 流程
   - 驗證 Response Status / Body / Headers

3. **安全測試**
   - 未授權存取
   - 權限不足
   - 輸入驗證（XSS / SQL Injection payload）

### 測試命名規範
`test_[方法名]_[情境]_[預期結果]`

### 執行驗證
撰寫完後執行 `mvn test -pl :module-name` 驗證

# 使用 Security Agent 進行安全掃描
> 使用 subagent security-reviewer 掃描整個 src/ 目錄：
> - 依據 OWASP Top 10
> - 檢查 hardcoded secrets
> - 檢查 SQL Injection
> - 檢查 XSS
> - 檢查不安全的依賴
> 
> 產出安全報告至 docs/security-report.md

# 依賴弱點掃描
> 執行 `mvn dependency-check:check` 並分析報告，
> 列出所有 CVE 漏洞及建議修復方式

# .github/workflows/ssdlc-pipeline.yml
name: SSDLC Pipeline

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

jobs:
  # 階段 1：程式碼品質檢查
  quality-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Java
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
      - name: Code Style Check
        run: mvn checkstyle:check
      - name: Unit Tests
        run: mvn test
      - name: Coverage Report
        run: mvn jacoco:report

  # 階段 2：安全掃描
  security-scan:
    runs-on: ubuntu-latest
    needs: quality-check
    steps:
      - uses: actions/checkout@v4
      - name: SAST Scan
        run: mvn spotbugs:check
      - name: Dependency Check
        run: mvn dependency-check:check
      - name: Claude Code Security Review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            審查此 PR 的安全性，依據 OWASP Top 10 進行檢查。
            如發現安全問題，請在對應程式碼行留下 Review Comment。

  # 階段 3：Claude Code Review
  ai-code-review:
    runs-on: ubuntu-latest
    needs: quality-check
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4
      - name: Claude Code Review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          review_type: comprehensive

  # 階段 4：建置與部署
  deploy:
    runs-on: ubuntu-latest
    needs: [security-scan, ai-code-review]
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: mvn package -DskipTests
      - name: Deploy
        run: |
          # 部署邏輯
          echo "Deploying to production..."

> 為這個 Spring Boot 專案產出最佳化的 multi-stage Dockerfile：
> - 使用 Eclipse Temurin JDK 21
> - 使用非 root 使用者
> - 最小化 image size
> - 設定健康檢查
> - 設定安全最佳實務（no-new-privileges, read-only filesystem）

# 日誌分析
cat application.log | claude -p "分析這份日誌，找出異常模式和潛在問題"

# 效能分析
> 分析 @monitoring/metrics.json，找出效能瓶頸：
> - API 回應時間異常
> - 記憶體洩漏跡象
> - 資料庫連線池使用率

# Incident 處理
> 線上系統出現以下錯誤：[貼上錯誤訊息]
> 1. 分析根因
> 2. 提供臨時修復方案
> 3. 提供永久修復方案
> 4. 建議防護措施避免再次發生

# 主 Session：分配任務
> 我需要實作用戶管理模組。請：
> 1. 使用 subagent planner 分析 @SPEC.md 中的用戶管理需求
> 2. 根據分析結果，依序實作各個 API
> 3. 每完成一個 API，使用 subagent code-reviewer 審查
> 4. 最後使用 subagent security-reviewer 進行安全掃描

# 自動化反饋迴圈
> 實作 UserService.createUser() 方法：
> 1. 撰寫實作
> 2. 撰寫測試
> 3. 執行測試，修正到全部通過
> 4. 使用 subagent 審查程式碼品質
> 5. 根據審查結果修改，直到通過
> 6. 使用 subagent security-reviewer 檢查安全性
> 7. 修正安全問題
> 完成後 commit

Session 1：犯錯 → 被糾正 → Auto Memory 記錄教訓
Session 2：讀取 Memory → 避免相同錯誤 → 品質提升
Session N：累積大量知識 → 效率持續提升

// .claude/settings.json
{
  "autoMemoryEnabled": true
}

memory/
├── MEMORY.md          # 記憶索引（每次 Session 自動載入前 200 行）
├── debugging.md       # Debug 經驗
├── api-conventions.md # API 慣例
├── security-notes.md  # 安全筆記
└── build-issues.md    # 建置問題

# Session 1：Claude Code 第一次寫 DAO，使用了字串拼接
# 你糾正：必須使用 PreparedStatement
# → Auto Memory 自動記錄

# Session 2：Claude Code 寫新的 DAO
# → 自動使用 PreparedStatement，不再犯同樣錯誤

# 查看 Memory
/memory
# 選擇 Auto Memory folder 瀏覽

參見 @README.md 了解專案概述，@package.json 查看可用指令。

# 額外指引
- Git 工作流程：@docs/git-instructions.md
- 個人覆寫：@~/.claude/my-project-instructions.md

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 簡潔索引（每 Session 載入前 200 行 / 25KB）
├── debugging.md       # 除錯模式筆記（按需讀取）
├── api-conventions.md # API 設計決策（按需讀取）
└── ...                # Claude 自行建立的主題檔案

# 1. CLAUDE.md：簡潔精準（< 200 行）
# 只放 Claude 無法自己推斷的資訊

# 2. Rules：依路徑分類
# .claude/rules/frontend.md → 只在碰到前端檔案時載入
# .claude/rules/backend.md → 只在碰到後端檔案時載入

# 3. Skills：按需載入
# /fix-issue 1234 → 只在需要時觸發

# 4. Auto Memory：自動管理
# Claude 自行決定哪些值得記住

# 瀏覽官方插件市集
/plugin

# 安裝 Code Intelligence 插件（TypeScript、Python 等）
/plugin install typescript-intelligence

# 本地開發中測試插件
claude --plugin-dir ./my-plugin

# 重新載入已安裝的插件
/reload-plugins

# 參考單一檔案
> 基於 @src/main/java/com/tutorial/service/UserService.java 撰寫測試

# 參考目錄（Claude 會遞迴讀取）
> 理解 @src/main/java/com/tutorial/ 的架構

# 參考 Agent
> 使用 subagent @security-reviewer 審查 @src/

# 組合使用
> 依照 @SPEC.md 的需求，參考 @src/service/OrderService.java 的模式，實作 PaymentService

# 當前正在實作功能，突然想查個語法
/btw Java 的 Optional.ofNullable 和 Optional.of 的差別？

# 不中斷當前 Context 的快速查詢
/btw Spring Security 6 的 SecurityFilterChain 怎麼設定？

我需要實作 [功能描述]。

## 背景
- 這是 [系統名稱] 的一部分
- 目標使用者：[角色]
- 技術棧：[語言/框架]

## 需求
1. [具體需求 1]
2. [具體需求 2]

## 約束
- [技術約束]
- [安全約束]
- [效能約束]

## 驗證標準
- [ ] [測試案例 1]
- [ ] [測試案例 2]
- [ ] 通過安全掃描
- [ ] 效能 < [閾值]

請先 Plan（不要直接寫程式），等我確認後再實作。

依照 @SPEC.md 中 [章節] 的需求，實作 [功能]。

## 參考
- 現有模式：看 @src/service/ExistingService.java 的實作方式
- API 規格：@docs/api-spec.yaml

## 實作要求
1. 遵循 Clean Architecture
2. 使用 DI（Dependency Injection）
3. 加入 Jakarta Validation
4. 寫完 Unit Test

## 測試驗證
實作完後：
1. 執行 `mvn test` 確認測試通過
2. 執行 `mvn checkstyle:check` 確認風格
3. 列出所有新增/修改的檔案

.claude/skills/
├── requirements/
│   └── analyze-requirements/SKILL.md    # 需求分析
├── design/
│   ├── create-api/SKILL.md              # API 設計
│   ├── create-architecture/SKILL.md     # 架構設計
│   └── create-data-model/SKILL.md       # 資料模型設計
├── development/
│   ├── implement-feature/SKILL.md       # 功能實作
│   ├── fix-issue/SKILL.md               # 修復 Issue
│   └── refactor/SKILL.md               # 重構
├── testing/
│   ├── generate-tests/SKILL.md          # 測試產出
│   └── security-test/SKILL.md           # 安全測試
├── review/
│   ├── code-review/SKILL.md             # 程式碼審查
│   └── security-review/SKILL.md         # 安全審查
└── devops/
    ├── create-pipeline/SKILL.md         # CI/CD Pipeline
    └── create-dockerfile/SKILL.md       # Dockerfile

<!-- .claude/skills/fix-issue/SKILL.md -->
---
name: fix-issue
description: 修復 GitHub Issue
disable-model-invocation: true
---
分析並修復 GitHub Issue：$ARGUMENTS

1. 使用 `gh issue view` 取得 Issue 詳情
2. 理解問題描述
3. 搜尋 Codebase 找到相關檔案
4. 實作修復
5. 撰寫並執行測試驗證
6. 確保 Lint 和型別檢查通過
7. 建立描述性 Commit Message
8. Push 並建立 PR

> 我要修改 AuthService 的 token refresh 邏輯。
> 
> 在動手之前，請先：
> 1. 讀取目前的實作
> 2. 列出所有呼叫 refreshToken() 的地方
> 3. 分析目前的問題
> 4. 提出修改方案（至少 2 個）
> 5. 分析每個方案的優缺點
> 6. 等我選擇方案後再實作

> 調查 API /api/v1/users 的回應時間為什麼從 50ms 變成 500ms。
> 
> 每一步都要：
> 1. 說明你要做什麼（Reason）
> 2. 執行（Act）
> 3. 分析結果（Observe）
> 4. 決定下一步
> 
> 不要跳躍結論，每一步都要有證據。

> 我想建立一個用戶認證系統。使用 AskUserQuestion 工具詳細訪談我。
> 
> 深入問技術實作、UI/UX、邊界情況、關注點和取捨。
> 不要問顯而易見的問題，挖掘我可能沒考慮到的困難點。
> 
> 訪談完後寫一份完整的 SPEC.md。

# 策略 1：要求引用來源
> 分析 authentication 模組的安全性。
> 每個發現都要引用具體的檔案名和行號。
> 如果不確定，明確說「不確定」而不是猜測。

# 策略 2：提供驗證方法
> 實作 validateEmail 函數。
> 測試案例：user@example.com = true, invalid = false
> 實作完後跑測試。如果測試失敗，分析原因並修正。

# 策略 3：限制範圍
> 只修改 src/service/UserService.java 中的 createUser() 方法。
> 不要修改其他檔案。
> 不要新增依賴。

# 策略 4：交叉驗證
> 實作完後，使用 subagent 審查這段程式碼的正確性和安全性。

在回答之前，請遵守以下安全規則：

1. **不要猜測**：如果不確定，查看原始碼或詢問我
2. **不要產出危險程式碼**：
   - 不使用 eval()
   - 不使用字串拼接 SQL
   - 不 hardcode 密碼或 API Key
   - 不停用安全功能（CSRF, CORS 等）
3. **驗證所有輸入**：使用型別安全的驗證方式
4. **最小權限原則**：只申請必要的權限
5. **日誌安全**：不要在日誌中記錄敏感資料

claude
# Plan Mode
> 我要建立一個任務管理系統（Task Manager）。使用 AskUserQuestion 訪談我，
> 深入了解功能需求、技術需求、安全需求。
> 訪談完後產出 SPEC.md。

# Task Manager 系統規格

## User Stories
- US-001: As a User, I want to create a task, so that I can track my work.
  - AC-1: Given valid input, When POST /api/v1/tasks, Then return 201 with task ID
  - AC-2: Given missing title, When POST /api/v1/tasks, Then return 400

## API Endpoints
| Method | Path | Description | Auth |
|---|---|---|---|
| POST | /api/v1/tasks | 建立任務 | User+ |
| GET | /api/v1/tasks | 列表查詢 | User+ |
| GET | /api/v1/tasks/{id} | 查詢單一 | User+ |
| PUT | /api/v1/tasks/{id} | 更新任務 | Owner/Admin |
| DELETE | /api/v1/tasks/{id} | 刪除任務 | Admin |

## Security Requirements
- SR-001: JWT Token 有效期 15 分鐘
- SR-002: Refresh Token 有效期 7 天
- SR-003: 所有 API 需要驗證
- SR-004: 刪除操作需 Admin 權限

# Plan Mode
> 基於 @SPEC.md，設計系統架構：
> - 後端：Spring Boot 3 + Java 21
> - 前端：Vue 3 + TypeScript
> - 資料庫：PostgreSQL
> - 認證：JWT
> 
> 產出：架構圖（Mermaid）、資料模型、API 規格（OpenAPI）

# Normal Mode
> 基於 @SPEC.md 和 @docs/architecture.md，依序實作：
> 
> 1. Entity 層：Task, User, Role
> 2. Repository 層：JPA Repository
> 3. Service 層：TaskService, UserService
> 4. Controller 層：TaskController, UserController
> 5. Security 配置：JWT Filter, SecurityConfig
> 6. DTO：Request/Response DTO
> 7. Exception Handler：Global Exception Handler
> 
> 每完成一層就寫測試並執行驗證。

# 產出測試
> /generate-tests TaskService - 包含建立、查詢、更新、刪除、權限檢查

# 安全測試
> 使用 subagent security-reviewer 掃描所有已寫的程式碼

# 效能測試基準
> 產出簡單的 JMH 基準測試，測量 TaskService 的 CRUD 效能

> 產出以下 DevOps 檔案：
> 1. Dockerfile（multi-stage, 非 root 用戶）
> 2. docker-compose.yml（包含 PostgreSQL, Redis）
> 3. GitHub Actions workflow（Build → Test → Security → Deploy）
> 4. Kubernetes manifest（Deployment + Service + Ingress）

# 步驟 1：需求分析
> 分析以下批次系統需求，產出 SPEC.md：
> - 每日凌晨 2:00 執行
> - 從交易資料庫讀取前一天的紀錄（預估 100 萬筆）
> - 產出 CSV 和 PDF 報表
> - 上傳至 S3
> - 異常發送 Email 告警
> 
> 特別考慮：效能、容錯、重試機制

# 步驟 2：設計
> 使用 Spring Batch 設計批次系統：
> - Chunk-oriented processing（chunk size: 1000）
> - 使用 JdbcPagingItemReader 讀取
> - Custom ItemProcessor 處理
> - CompositeItemWriter 輸出 CSV + PDF
> - 加入 Retry Policy（最多 3 次）
> - 加入 Skip Policy（容許 10 筆失敗）

# 步驟 3：實作
> 依照設計實作 Spring Batch Job：
> 1. BatchConfig：Job 和 Step 定義
> 2. TransactionReader：分頁讀取
> 3. ReportProcessor：資料轉換
> 4. CsvWriter：CSV 輸出
> 5. PdfWriter：PDF 輸出
> 6. NotificationListener：完成/失敗通知
> 
> 實作完後跑 Integration Test 驗證

# 步驟 4：安全審查
> 使用 subagent security-reviewer 審查批次系統：
> - 資料庫連線安全
> - 檔案存取權限
> - 密碼管理
> - 日誌中不可含敏感資料

# 步驟 5：部署
> 產出 Kubernetes CronJob manifest，排程每日凌晨 2:00 執行

# 分析應用程式日誌
cat /var/log/app/application.log | claude -p "
分析這份日誌，找出：
1. ERROR 等級的錯誤模式
2. 重複出現的 WARN
3. 異常的回應時間
4. 可疑的安全事件
提供摘要和建議。
"

# 即時監控
tail -f application.log | claude -p "
持續監控日誌，如果發現以下情況立即告警：
- OOM（OutOfMemoryError）
- 連線池耗盡
- 認證失敗超過 5 次
- 回應時間 > 3 秒
"

<!-- .claude/skills/analyze-logs/SKILL.md -->
---
name: analyze-logs
description: 分析應用程式日誌找出問題
---
分析以下日誌或日誌檔案：$ARGUMENTS

### 分析維度
1. **錯誤模式**：分類並統計 ERROR/WARN
2. **效能問題**：找出慢查詢、慢回應
3. **安全事件**：認證失敗、異常存取
4. **資源問題**：記憶體、連線池、Thread

### 輸出格式
| 嚴重度 | 類型 | 出現次數 | 描述 | 建議 |

# Debug 範例
> API /api/v1/users 回傳 500 錯誤，錯誤訊息如下：
> [貼上 Stack Trace]
> 
> 請：
> 1. 分析 Stack Trace 找出根因
> 2. 在 Codebase 中找到問題點
> 3. 提出修復方案
> 4. 實作修復
> 5. 撰寫一個能重現此問題的測試
> 6. 確認測試通過
> 7. 提交修復

<!-- .claude/skills/handle-incident/SKILL.md -->
---
name: handle-incident
description: 處理線上 Incident
disable-model-invocation: true
---
處理以下 Incident：$ARGUMENTS

### 處理流程
1. **評估影響**
   - 受影響的服務
   - 受影響的用戶數
   - 業務影響等級

2. **臨時修復（Mitigation）**
   - 能否 rollback 到上一版？
   - 能否關閉有問題的功能？
   - 能否增加 Circuit Breaker？

3. **根因分析（Root Cause Analysis）**
   - 閱讀相關日誌
   - 檢查最近的程式碼變更
   - 分析監控指標

4. **永久修復**
   - 實作修復
   - 撰寫防護測試
   - 更新監控規則

5. **Post-Mortem**
   - 時間線
   - 根因
   - 修復措施
   - 預防措施

// .claude/settings.json — 維運 Hook 範例
{
  "hooks": {
    // 當 Claude 發現需要通知的事件時觸發
    "Notification": [
      {
        "command": "curl -X POST $SLACK_WEBHOOK -d '{\"text\": \"Claude Code Alert: $EVENT_MESSAGE\"}'",
        "if": "severity == 'error'"
      }
    ],
    // 當工作目錄中的檔案變動時觸發
    "FileChanged": [
      {
        "command": "bash scripts/check-config-drift.sh $FILE_PATH",
        "if": "path matches 'config/**'"
      }
    ]
  }
}

.claude/
├── skills/
│   ├── v1/                    # 舊版本保留
│   │   └── fix-issue/
│   │       └── SKILL.md
│   └── fix-issue/             # 當前版本
│       └── SKILL.md
├── CHANGELOG.md               # 變更記錄
└── rules/
    └── versioning.md          # 版本規則

# Claude Code Settings Changelog

## 2026-04-15
- 新增 security-reviewer Agent
- 更新 fix-issue Skill：加入安全掃描步驟
- 更新 CLAUDE.md：加入 PostgreSQL 遷移規範

## 2026-04-01
- 新增 handle-incident Skill
- 修改 code-reviewer Agent：加入效能檢查

# 定期評估 Agent 效能
> 審查 security-reviewer Agent 最近一個月的表現：
> 1. 查看 Auto Memory 中的安全相關記錄
> 2. 是否有遺漏的安全問題
> 3. 是否有誤報
> 4. 建議改善 Agent 的指令

# 升級 Agent
# 修改 .claude/agents/security-reviewer.md
# 加入新的檢查項目
# commit 並通知團隊

<!-- .claude/agents/security-reviewer.md -->
---
name: security-reviewer
memory: project
---

# 查看特定 Agent 的累積知識
/memory
# 進入 Auto Memory → 檢視 Agent 相關的主題檔案

# 定期回顧 Agent 學到了什麼
> 列出 Auto Memory 中所有與 security-reviewer 相關的記錄，
> 評估哪些是有價值的、哪些需要更正

## AI 使用規範

### 允許的使用場景
- 程式碼撰寫與重構
- 測試產出
- 程式碼審查
- 日誌分析
- 文件撰寫

### 禁止的使用場景
- 將公司敏感資料貼入公有 API
- 未經審查直接部署 AI 產出的程式碼
- 停用安全功能以「提升效率」
- 使用 AI 產出繞過合規要求

### 審查要求
- 所有 AI 產出的程式碼必須經過人工 Code Review
- 安全相關的修改需要額外的安全審查
- AI 產出的測試需驗證是否真的在測試目標邏輯

<!-- C:\Program Files\ClaudeCode\CLAUDE.md -->
# 組織級 Claude Code 規範（Managed Policy）

## 安全規則（不可覆寫）
- 所有敏感資料必須使用環境變數
- 禁止在程式碼中 hardcode 任何憑證
- 所有 SQL 查詢必須使用 Parameterized Query
- 所有外部輸入必須驗證和消毒

## 合規要求
- 遵循公司資安政策
- 日誌不可記錄 PII（個人識別資訊）
- 所有 API 必須有認證和授權

Layer 1：Managed Policy（組織級，不可覆寫）
    ↓
Layer 2：Permission Rules（專案級，限制工具使用）
    ↓
Layer 3：Hooks（自動觸發，確保安全檢查）
    ↓
Layer 4：Subagent Security Review（AI 層安全審查）
    ↓
Layer 5：CI/CD Security Gate（Pipeline 安全閘門）

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(mvn *)",
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(git push *)",
      "Bash(gh pr create *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(DROP *)",
      "Bash(curl * | bash)",
      "Bash(wget * | sh)",
      "Bash(*password*)",
      "Bash(*secret*)"
    ]
  }
}

# CI/CD 中的非互動式安全掃描
claude -p "掃描 src/ 的安全問題" --permission-mode auto --allowedTools "Read,Grep,Glob"

# 搭配 --allowedTools 限制可用工具，遵循最小權限原則
claude -p "修復 lint 錯誤" --permission-mode auto --allowedTools "Read,Edit,Bash(npm run lint*)"

// .claude/settings.json
{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["./src", "./tests"],
      "denyWrite": ["./node_modules", "./.git"]
    },
    "network": {
      "allowDomains": ["api.github.com", "registry.npmjs.org"]
    }
  }
}

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        // 使用 if 條件篩選：僅當工具為 Bash 時觸發
        "if": "tool == 'Bash'",
        "command": "bash scripts/check-dangerous-command.sh \"$COMMAND\"",
        // exit 0 = 允許, exit 2 = 阻擋
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "grep -rn 'password\\|secret\\|api_key\\|token' $FILE && echo 'WARNING: 可能包含敏感資訊！' || true"
      },
      {
        // HTTP Hook：每次檔案編輯後通知審計系統
        "matcher": "Edit",
        "http": {
          "url": "https://audit.internal/api/events",
          "method": "POST",
          "headers": { "Authorization": "Bearer $AUDIT_TOKEN" }
        }
      }
    ],
    "ConfigChange": [
      {
        // 設定變更時自動記錄稽核日誌
        "command": "echo \"$(date) Config changed: $EVENT_DATA\" >> /var/log/claude-audit.log"
      }
    ]
  }
}

# 安全的 Fan-Out：限制每個子程序的工具權限
for file in src/service/*.java; do
  claude -p "審查 $file 的安全性" \
    --permission-mode auto \
    --allowedTools "Read,Grep,Glob" &
done
wait

# 每個子程序只能讀取，不能修改檔案

# 查看目前 Session 的 Context 使用量
# Claude Code 介面底部會顯示 Token 使用狀態

# 設定 Token 預算（CI/CD 環境）
claude -p "fix lint errors" --max-tokens 50000

# 使用自訂 Status Line 即時監控
# 在 CLAUDE.md 中設定

# 方法 1：清除重來
/clear

# 方法 2：壓縮保留重要內容
/compact 保留 API 變更和測試指令

# 方法 3：Rewind 到特定點
# 按 Esc + Esc 開啟 Rewind Menu
# 選擇 "Summarize from here"

# 方法 4：使用 Subagent 減少主 Context 負擔
> 使用 subagent 調查 auth 模組的實作方式

# 設定 Proxy
export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1

# 使用第三方 Provider（Bedrock / Vertex）
# 如果可以走內部雲端
export CLAUDE_CODE_USE_BEDROCK=1

# CI/CD 中自動修復 Lint 問題
claude -p "fix all lint errors" --permission-mode auto --allowedTools "Read,Edit,Bash(npm run lint*)"

# 批次遷移檔案（Fan-Out 模式）
for file in $(cat files.txt); do
  claude -p "Migrate $file from Java 11 to Java 21" \
    --permission-mode auto \
    --allowedTools "Read,Edit,Bash(git commit *)" &
done
wait

# 自動 Code Review（非互動，JSON 格式輸出）
claude -p "Review the changes in this PR for security and code quality issues" --output-format json

# 指定 Agent 啟動
claude --agent security-reviewer

# 在獨立 Worktree 中執行（不影響主分支）
claude --worktree -p "嘗試將 Hibernate 5 升級到 6，如果測試失敗就回退"