# 方式一：官方下載 DMG（macOS 10.14+）
# 前往 https://www.warp.dev/download 下載 DMG 檔案

# 方式二：Homebrew 安裝（推薦）
brew install --cask warp

# Debian / Ubuntu（.deb）
# x64
wget https://app.warp.dev/get_warp?package=deb -O warp.deb
sudo dpkg -i warp.deb

# ARM64
wget https://app.warp.dev/get_warp?package=deb_arm64 -O warp-arm64.deb
sudo dpkg -i warp-arm64.deb

# Red Hat / Fedora / SUSE（.rpm）
wget https://app.warp.dev/get_warp?package=rpm -O warp.rpm
sudo rpm -i warp.rpm

# Arch Linux（Pacman）
wget https://app.warp.dev/get_warp?package=pacman -O warp.pkg.tar.zst
sudo pacman -U warp.pkg.tar.zst

# AppImage（通用）
wget https://app.warp.dev/get_warp?package=appimage -O warp.AppImage
chmod +x warp.AppImage
./warp.AppImage

# 方式一：winget 安裝（推薦，Windows 10/11）
winget install Warp.Warp

# 方式二：官方下載 .exe
# x64: https://app.warp.dev/get_warp?package=exe_x86_64
# ARM64: https://app.warp.dev/get_warp?package=exe_arm64

# Clone 開源 Repo
git clone https://github.com/warpdotdev/warp.git
cd warp

# 平台相關環境設定
./script/bootstrap

# 建置並執行
./script/run

# 執行 pre-submit 檢查（格式化 + clippy + 測試）
./script/presubmit

# Linux 安裝 Vulkan 驅動（Ubuntu）
sudo apt install mesa-vulkan-drivers vulkan-tools

# 驗證 Vulkan 支援
vulkaninfo | head -20

# 設定預設 Shell
# Warp Settings > Terminal > Shell > 選擇 Shell 路徑

# 確認目前 Shell
echo $SHELL       # macOS / Linux
$PSVersionTable   # PowerShell

# 確認 Git 已安裝
git --version

# Warp 自動偵測 Git 狀態，在 Prompt 顯示：
# - 當前分支
# - 變更檔案數
# - 未推送的 commit 數

# 搭配 Warp Block 使用 Git
git log --oneline -20    # 輸出自動成為獨立 Block
git diff                 # 差異內容可在 Block 內搜尋

# Docker
docker ps                         # 容器狀態即時監控
docker compose up -d              # Block 中追蹤啟動日誌

# Podman（企業級替代方案）
podman ps --format "{{.Names}}\t{{.Status}}\t{{.Ports}}"
podman compose up -d

# Warp AI 輔助 Docker 指令
# 在 Agent Mode 中詢問：
# "幫我寫一個 multi-stage Dockerfile，前端用 node:20-alpine 建置 Vue 3，
#  後端用 eclipse-temurin:21-jre-alpine 執行 Spring Boot JAR"

# Node.js（前端開發）
node --version
npm --version
nvm use 20         # Warp 自動載入 .nvmrc

# Java（後端開發）
java --version
mvn --version
# JAVA_HOME 自動偵測

# Python（腳本 / AI 工具鏈）
python3 --version
pip3 --version

# 版本管理工具整合
# Warp 自動支援 nvm / sdkman / pyenv 的 shell hook

# 在 Warp 中執行 Maven 建置
mvn clean compile -P dev

# 輸出自動分為 Block：
# Block 1: [INFO] Scanning for projects...
# Block 2: [INFO] BUILD SUCCESS

# 使用 Warp AI 分析建置錯誤
# 選取失敗的 Block → 右鍵 → "Explain with AI"

# Block 過濾範例：只顯示失敗的指令
# 使用 Command Palette → "Filter Blocks" → 選擇 "Failed"

# 背景 Block：長時間建置
mvn clean package -DskipTests    # 可將此 Block 移至背景

# 場景：分析生產環境問題
kubectl logs pod/api-server --tail=500    # Block 1：取得日誌
grep -n "ERROR" app.log | tail -20        # Block 2：過濾錯誤
curl -s http://localhost:8080/health      # Block 3：健康檢查

# 每個 Block 獨立可搜尋、可複製、可分享
# 選取 Block 2 → "Explain with AI" → AI 自動分析錯誤原因

# 開啟方式
Cmd+Shift+P  (macOS)
Ctrl+Shift+P (Windows / Linux)

# 常用功能
- 切換 Terminal / Agent Mode
- 搜尋設定
- 切換主題
- 管理 Tab / Pane
- 開啟 Warp Drive
- GPU 設定
- Shell 切換

# 自然語言生成指令：在輸入框中按 # 開頭
# 範例輸入：
# find all java files modified in the last 7 days

# Warp 自動生成：
find . -name "*.java" -mtime -7

# 指令解釋：選取任何 Block → "Explain with AI"
# Warp 會解釋指令的作用與各參數含義

# Active AI Recommendations：
# 當指令執行失敗時，Warp 會主動提供修復建議
# 無需手動觸發，自動偵測錯誤並建議修正方案

# 切換至 Agent Mode
# 快捷鍵：Cmd/Ctrl + L
# 或 Command Palette → "Switch to Agent Mode"

# Agent Mode 功能：
# - 多輪對話（支援 Conversation Forking 分支對話）
# - 程式碼生成與修改（產生 Code Diff）
# - Interactive Code Review（行內評論、Agent 回應修改）
# - 錯誤診斷（自動分析 Block 錯誤）
# - 自動執行指令（Full Terminal Use）
# - 語音輸入（Voice）
# - 網路搜尋（Web Search）
# - Computer Use（操控桌面 GUI）
# - Codebase Context（語意索引理解專案）
# - Cloud-synced Conversations（跨裝置同步對話）

# 在 Agent Mode 中切換模型
# 點擊輸入框中顯示的模型名稱 → 開啟下拉選單選擇
# 或在 Settings > Agents > Profiles 中設定各 Agent Profile 的基礎模型

# Model Fallback 機制：
# 當選定模型暫時不可用時，Warp 自動切換至備援模型，
# 原模型恢復後自動切回，確保服務不中斷

# AGENTS.md（置於專案根目錄）
# 檔名必須全大寫：AGENTS.md

## 專案概述
這是一個 Spring Boot 3.4 + Java 21 的企業級微服務專案。

## 程式碼風格
- 使用 Java Records 取代簡單 POJO
- 使用 Sealed Interfaces 定義業務狀態
- 金額欄位一律使用 BigDecimal
- 日誌使用 Log4j2，格式為 JSON

## 安全規範
- 所有使用者輸入必須驗證與 sanitize
- 密碼不可出現在日誌中
- API 端點需加 @PreAuthorize 授權

## 測試要求
- 每個 Use Case 必須有 JUnit 5 測試
- 使用 Given-When-Then 模式
- 覆蓋率目標 80%

# Code Review 流程：
# 1. Agent 生成程式碼修改 → 自動產生 Diff
# 2. 在 Code Review 面板中查看所有變更
# 3. 可逐行接受/拒絕/修改
# 4. 支援 Interactive Code Review：
#    - 在 Diff 上留下行內評論
#    - Agent 自動回應並修改
#    - 持續對話直到滿意

# 專案初始化（啟用 Codebase Context）：
# 方式一：開啟新 Tab → Create New Project / Open Repository / Clone Repository
# 方式二：在 Agent Mode 中執行 /init 指令

# 範例：Spring Boot 專案建置 Workflow
# 儲存位置：Warp Drive > Team > Workflows
---
name: "Spring Boot 建置與測試"
command: |
  echo "🔨 開始建置 {{project_name}}..."
  cd {{project_dir}}
  mvn clean compile -P {{profile}}
  echo "🧪 執行單元測試..."
  mvn test
  echo "📦 打包..."
  mvn package -DskipTests
  echo "✅ 完成！JAR 位於 target/ 目錄"
tags:
  - java
  - spring-boot
  - build
arguments:
  - name: project_name
    description: "專案名稱"
    default_value: "my-app"
  - name: project_dir
    description: "專案目錄"
    default_value: "."
  - name: profile
    description: "Maven Profile"
    default_value: "dev"

# Warp Drive 環境變數可依環境分組：
# DEV / SIT / UAT / PROD

# 範例：DEV 環境
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp_dev
DB_USER=dev_user
SPRING_PROFILES_ACTIVE=dev
LOG_LEVEL=DEBUG

# 使用方式：
# Warp Drive → Environment Variables → 選擇環境 → Apply
# 變數自動載入至當前 Terminal Session

# Block 分享流程：
# 1. 選取要分享的 Block（含指令與輸出）
# 2. 右鍵 → "Share Block"
# 3. 產生唯一連結，可貼到 Slack / Teams / Issue

# Session 分享：
# 1. 開啟 Session Sharing
# 2. 邀請團隊成員
# 3. 成員可即時觀看或操控

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

# 設定 API Key
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# 在 Warp 中啟動 Claude Code
claude

# 或帶入專案目錄
cd /path/to/project && claude

# Claude Code 在 Warp 中享有增強體驗：
# 1. Rich Input：多行 prompt 編輯
# 2. Code Review 面板：查看 Claude 修改的差異
# 3. 通知：長時間任務完成後桌面通知
# 4. Block 化：每次互動自動成為獨立 Block

# 範例：使用 Claude Code 重構服務層
claude "Refactor UserService to follow Clean Architecture:
- Extract domain logic from service to domain entity
- Create port interfaces
- Separate infrastructure concerns
- Keep backward compatibility"

# 企業級 Prompt 模板（存入 Warp Drive > Prompts）

# 模板 1：程式碼審查
claude "Review the following Java file for:
1. Clean Architecture violations
2. SOLID principle adherence
3. Security vulnerabilities (OWASP Top 10)
4. Performance concerns (N+1 query, connection leak)
5. Test coverage gaps

File: {{file_path}}

Output format:
- Issue category
- Severity (Critical/High/Medium/Low)
- Line number
- Description
- Suggested fix"

# 模板 2：API 設計
claude "Design a RESTful API for {{domain}} following:
- OpenAPI 3.0 spec
- Enterprise naming conventions (kebab-case URLs)
- Proper HTTP status codes
- Pagination (cursor-based)
- HATEOAS links
- Error response format (RFC 7807)
Output as OpenAPI YAML."

# 安裝 GitHub CLI
winget install GitHub.cli          # Windows
brew install gh                     # macOS

# 安裝 Copilot CLI 擴充
gh extension install github/gh-copilot

# 認證
gh auth login

# 驗證安裝
gh copilot --help

# 指令建議
gh copilot suggest "find all Spring Boot controllers with security annotations"

# 指令解釋
gh copilot explain "kubectl get pods -l app=api-server -o jsonpath='{.items[*].status.phase}'"

# 與 Warp Workflow 整合
# 建立 Workflow：Copilot 輔助除錯
---
name: "Copilot Debug Helper"
command: |
  echo "📋 收集錯誤資訊..."
  ERROR_LOG=$(tail -50 {{log_file}})
  echo "🤖 請 Copilot 分析..."
  gh copilot explain "$ERROR_LOG"
arguments:
  - name: log_file
    description: "日誌檔案路徑"
    default_value: "logs/app.log"

# 安裝 Gemini CLI
npm install -g @google/gemini-cli

# 設定 API Key
export GOOGLE_API_KEY="AIza..."

# 在 Warp 中使用
gemini

# Gemini 特色：超大上下文窗口
# 適合分析大型程式碼庫、長文件理解
gemini "Analyze the entire project structure under src/ and:
1. Generate a complete class diagram (Mermaid format)
2. Identify architectural patterns in use
3. List all external dependencies and their purposes
4. Suggest refactoring opportunities"

# 安裝 Codex CLI
npm install -g @openai/codex

# 設定（Warp 與 OpenAI 為創始合作夥伴）
export OPENAI_API_KEY="sk-..."

# 在 Warp 中使用
codex

# Codex 特色：深度程式碼生成
codex "Generate a complete Spring Boot REST controller for
employee management with CRUD operations, validation,
error handling, and OpenAPI annotations"

# Sourcegraph 的 CLI 程式碼智慧體
# 特色：深度程式碼搜尋與理解，整合 Sourcegraph 的程式碼圖譜
npm install -g @sourcegraph/amp
amp

# Augment Code 的 CLI Agent
# 特色：企業級程式碼生成，支援大型程式碼庫上下文
npm install -g @augmentcode/auggie
auggie

# Cursor 的 CLI Agent
# 特色：與 Cursor IDE 共享配置與上下文
cursor-cli

# Factory 的 CLI Agent
# 特色：自動化軟體工廠流程，CI/CD 整合
npm install -g @factory/droid
droid

# 開源 CLI Agent
# 特色：社群驅動，可自訂擴展
npm install -g @anthropic/pi
pi

# GitHub Actions 觸發範例
name: "Warp Cloud Agent - PR Review"
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  warp-review:
    runs-on: ubuntu-latest
    steps:
      - uses: warpdotdev/cloud-agent-action@v1
        with:
          task: "review-pr"
          model: "auto-genius"
          warp-api-key: ${{ secrets.WARP_API_KEY }}

# Managed Docker 部署範例
docker pull warpdotdev/cloud-agent:latest
docker run -d \
  --name warp-cloud-agent \
  -e WARP_API_KEY=$WARP_API_KEY \
  -e WARP_ORG_ID=$WARP_ORG_ID \
  warpdotdev/cloud-agent:latest

# Managed Kubernetes 部署範例
helm repo add warp https://charts.warp.dev
helm install warp-agent warp/cloud-agent \
  --set apiKey=$WARP_API_KEY \
  --set orgId=$WARP_ORG_ID \
  --namespace warp-agents

# Oz CLI 範例
# 安裝
npm install -g @warpdotdev/oz-cli

# 登入
oz login

# 列出所有 Cloud Agents
oz agents list

# 建立排程任務
oz schedule create \
  --name "daily-dependency-check" \
  --cron "0 9 * * 1-5" \
  --task "check-dependencies" \
  --model "auto-efficient"

# 手動觸發任務
oz run --task "review-security" --repo "my-org/my-repo"

# 檢視任務日誌
oz logs --task-id abc123 --follow

# 方式一：使用 Spring Initializr CLI
curl https://start.spring.io/starter.tgz \
  -d type=maven-project \
  -d language=java \
  -d bootVersion=3.4.0 \
  -d groupId=com.enterprise \
  -d artifactId=order-service \
  -d dependencies=web,data-jpa,security,actuator,validation \
  -d javaVersion=21 \
  -d packaging=jar | tar -xzf -

# 方式二：使用 Maven Archetype
mvn archetype:generate \
  -DarchetypeGroupId=com.enterprise \
  -DarchetypeArtifactId=clean-arch-archetype \
  -DgroupId=com.enterprise.order \
  -DartifactId=order-service \
  -DinteractiveMode=false

# 在 Warp Agent Mode 中：

"建立一個 Spring Boot 3.4 + Java 21 的企業級微服務專案，需求如下：
1. Clean Architecture 分層（domain / application / infrastructure / presentation）
2. Maven 多模組結構
3. 整合：Spring Web, JPA, Security, Actuator, Validation
4. 資料庫：PostgreSQL（開發用 H2）
5. 包含：
   - Dockerfile（multi-stage build）
   - docker-compose.yml（含 PostgreSQL + Redis）
   - .github/workflows/ci.yml（GitHub Actions）
   - log4j2.xml（JSON 格式日誌）
   - ArchUnit 測試（確保分層約束）
6. 使用 records 與 sealed interfaces
請直接在當前目錄生成完整專案結構。"

# 在 Warp Code Editor 中開啟檔案
# File Tree → 選擇檔案
# 或使用 Command Palette → "Open File"

# 使用 Agent Mode 撰寫程式碼
# Cmd/Ctrl + L → 進入 Agent Mode

# Domain Entity 生成
"在 domain/model/ 下建立 Order.java：
- 使用 Java record 或 sealed class
- 包含業務驗證邏輯（金額 > 0、狀態機轉換）
- 實作 DDD Aggregate Root 模式
- 提供工廠方法 createOrder()
- 包含 JavaDoc 註解"

# Repository Port 生成
"在 domain/port/ 下建立 OrderRepository.java：
- 定義為介面（Port）
- 方法包含：findById, save, findByStatus, findByDateRange
- 使用 Optional 回傳
- 加入 JavaDoc"

# Use Case 生成
"在 application/usecase/ 下建立 CreateOrderUseCase.java：
- 注入 OrderRepository（透過建構子）
- 實作 CreateOrderCommand → OrderResult 轉換
- 包含交易管理
- 包含事件發佈（OrderCreatedEvent）
- 完整錯誤處理"

# 執行全部測試
mvn test

# 執行特定測試類
mvn test -Dtest=OrderServiceTest

# 執行特定方法
mvn test -Dtest=OrderServiceTest#shouldCreateOrder

# 產生測試報告
mvn surefire-report:report

# 查看覆蓋率
mvn jacoco:report
open target/site/jacoco/index.html    # macOS
start target/site/jacoco/index.html   # Windows

# 單元測試生成
"為 CreateOrderUseCase 撰寫完整的 JUnit 5 測試：
1. 使用 @ExtendWith(MockitoExtension.class)
2. Mock OrderRepository
3. 測試案例：
   - 正常建立訂單
   - 金額為零應拋出例外
   - 重複訂單號應拋出例外
   - 庫存不足場景
   - 併發建立場景
4. 使用 @DisplayName 中文描述
5. 遵循 Given-When-Then 模式
6. 使用 AssertJ 斷言"

# 整合測試生成
"為 OrderController 撰寫整合測試：
1. 使用 @SpringBootTest + @AutoConfigureMockMvc
2. 使用 @Testcontainers + PostgreSQL
3. 測試 CRUD API 完整流程
4. 包含認證測試（JWT Token）
5. 驗證回應狀態碼與 Body
6. 驗證資料庫狀態"

# 啟動 Debug 模式
mvn spring-boot:run -Dspring-boot.run.jvmArguments="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005"

# 查看應用日誌（即時）
tail -f logs/app.log | grep -E "ERROR|WARN"

# 使用 Warp AI 分析錯誤
# 選取錯誤 Block → "Explain with AI"

# 堆積分析
jmap -heap <PID>
jstack <PID> > thread-dump.txt

"我在執行以下指令時遇到錯誤：

[貼上錯誤 Block 內容]

請分析：
1. 根本原因
2. 影響範圍
3. 修復步驟
4. 預防措施
5. 相關的 Spring Boot 配置調整"

# 使用 AI Agent 進行重構
# 進入 Agent Mode → 描述重構需求

# 重構後驗證
mvn clean test                              # 確認測試通過
mvn checkstyle:check                        # 程式碼風格
mvn spotbugs:check                          # 靜態分析

"重構 UserService.java，將 587 行的 God Class 拆分為：
1. UserRegistrationService（註冊相關）
2. UserAuthenticationService（認證相關）
3. UserProfileService（個人資料相關）
4. UserNotificationService（通知相關）

要求：
- 保持所有現有測試通過
- 使用介面解耦
- 每個服務不超過 150 行
- 保持向後相容（原 UserService 委派到新服務）"

# 生成 JavaDoc
mvn javadoc:javadoc

# 生成 API 文件（OpenAPI）
mvn springdoc-openapi:generate

# 生成架構文件
# 在 Agent Mode 中使用 AI

"分析 src/main/java/com/enterprise/order/ 下所有 Java 檔案，產出：
1. README.md（專案說明、快速開始、架構圖）
2. API.md（所有 REST API 說明，含 curl 範例）
3. ARCHITECTURE.md（Clean Architecture 分層說明 + Mermaid 圖）
4. CHANGELOG.md（基於 git log 產生）
5. 資料庫 ER Diagram（Mermaid 格式）

全部使用繁體中文。"

# 在 Warp 中建立 Vue 3 + TS 專案
npm create vue@latest frontend -- \
  --typescript \
  --jsx \
  --router \
  --pinia \
  --vitest \
  --e2e-cypress \
  --eslint-with-prettier

cd frontend
npm install

# 安裝企業常用套件
npm install @vueuse/core axios dayjs
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

# Warp Agent Mode Prompt：

"在 Vue 3 + TypeScript + Tailwind 環境下，建立訂單管理模組：

1. components/order/OrderList.vue
   - 使用 Composition API + <script setup>
   - 資料表格（分頁、排序、搜尋）
   - 響應式設計（Tailwind）

2. components/order/OrderForm.vue
   - 表單驗證（VeeValidate + Zod）
   - 日期選擇器
   - 下拉選單（客戶、商品）

3. stores/orderStore.ts
   - Pinia Store
   - CRUD 操作
   - 錯誤處理
   - Loading 狀態

4. composables/useOrder.ts
   - API 呼叫封裝
   - 型別定義（TypeScript interface）

5. types/order.ts
   - Order / OrderItem / OrderStatus 型別

所有檔案使用 TypeScript strict mode。"

# AI 生成 Clean Architecture 結構
# Warp Agent Mode：

"建立 order-service Spring Boot 專案，使用 Clean Architecture：

order-service/
├── domain/
│   ├── model/          # Entity, Value Object, Aggregate
│   ├── port/           # Repository Interface (SPI)
│   ├── event/          # Domain Event
│   └── exception/      # Domain Exception
├── application/
│   ├── usecase/        # Use Case Implementation
│   ├── dto/            # Command / Query DTO
│   └── service/        # Application Service
├── infrastructure/
│   ├── persistence/    # JPA Entity, Repository Impl
│   ├── messaging/      # Kafka Producer/Consumer
│   └── config/         # Spring Config
└── presentation/
    ├── controller/     # REST Controller
    ├── request/        # Request DTO
    └── response/       # Response DTO

請生成每個層的基礎類別與 ArchUnit 分層測試。"

// application/usecase/CreateOrderUseCase.java
// AI 生成後人工審查的程式碼

@UseCase
@RequiredArgsConstructor
public class CreateOrderUseCase {

    private final OrderRepository orderRepository;
    private final EventPublisher eventPublisher;

    @Transactional
    public OrderResult execute(CreateOrderCommand command) {
        // 1. 驗證業務規則
        Order order = Order.create(
            command.customerId(),
            command.items().stream()
                .map(item -> OrderItem.of(
                    item.productId(),
                    item.quantity(),
                    item.unitPrice()
                ))
                .toList()
        );

        // 2. 持久化
        Order savedOrder = orderRepository.save(order);

        // 3. 發佈領域事件
        eventPublisher.publish(new OrderCreatedEvent(savedOrder.getId()));

        // 4. 回傳結果
        return OrderResult.from(savedOrder);
    }
}

# Warp Agent Mode Prompt：

"根據 Order domain model，設計 RESTful API：

要求：
1. 遵循 REST 成熟度 Level 3（HATEOAS）
2. URL 命名：kebab-case
3. 版本控制：/api/v1/
4. 分頁：cursor-based pagination
5. 錯誤回應：RFC 7807 Problem Details
6. 認證：Bearer JWT Token
7. 限流：Rate Limiting Headers

API 列表：
- POST   /api/v1/orders           建立訂單
- GET    /api/v1/orders           查詢訂單列表
- GET    /api/v1/orders/{id}      取得訂單詳情
- PUT    /api/v1/orders/{id}      更新訂單
- DELETE /api/v1/orders/{id}      取消訂單
- POST   /api/v1/orders/{id}/confirm  確認訂單

請生成 OpenAPI 3.0 YAML 規格與對應 Controller。"

# 在 Warp 中管理資料庫

# PostgreSQL 連線
psql -h localhost -p 5432 -U dev_user -d myapp_dev

# Flyway 資料庫版本管理
mvn flyway:migrate
mvn flyway:info
mvn flyway:validate

# AI 生成 Migration Script

# Warp Agent Mode Prompt：

"根據以下 Domain Model，生成 Flyway migration SQL：

Order:
  - id: UUID (PK)
  - customer_id: UUID (FK)
  - status: ENUM(DRAFT, CONFIRMED, SHIPPED, DELIVERED, CANCELLED)
  - total_amount: DECIMAL(15,2)
  - currency: VARCHAR(3)
  - created_at: TIMESTAMP WITH TIME ZONE
  - updated_at: TIMESTAMP WITH TIME ZONE

OrderItem:
  - id: UUID (PK)
  - order_id: UUID (FK → Order)
  - product_id: UUID (FK)
  - quantity: INTEGER
  - unit_price: DECIMAL(12,2)
  - line_total: DECIMAL(15,2)

要求：
1. 同時支援 PostgreSQL 與 Oracle 語法
2. 包含索引設計（覆蓋常用查詢）
3. 包含 CHECK 約束
4. 包含 Audit 欄位
5. 檔名格式：V1.0.0__create_order_tables.sql"

# 完整流程一鍵執行（Warp Workflow）
---
name: "Full Stack Generation"
command: |
  echo "📋 Step 1: 分析需求..."
  # Agent Mode 分析需求文件
  
  echo "🗄️ Step 2: 生成 DB Migration..."
  mvn flyway:migrate
  
  echo "☕ Step 3: 後端建置..."
  cd backend && mvn clean test
  
  echo "🎨 Step 4: 前端建置..."
  cd ../frontend && npm run build
  
  echo "🧪 Step 5: E2E 測試..."
  cd ../frontend && npm run test:e2e
  
  echo "📦 Step 6: 打包..."
  cd ../backend && mvn package -DskipTests
  
  echo "🐳 Step 7: Docker 映像..."
  podman build -t order-service:latest .
  
  echo "✅ 完成！"

# 在 Warp 中進行 Legacy 程式碼分析

# Step 1: 統計專案規模
find /path/to/legacy -name "*.java" | wc -l
find /path/to/legacy -name "*.java" -exec cat {} + | wc -l
cloc /path/to/legacy --include-lang=Java,XML,SQL,Properties

# Step 2: 相依性分析
cd /path/to/legacy
mvn dependency:tree > dependency-tree.txt
mvn dependency:analyze > dependency-analysis.txt

# Step 3: 使用 AI 分析架構

# Warp Agent Mode：Legacy 系統分析

"分析以下 Legacy Java 專案（Java 8 + Spring MVC + Hibernate）：

目錄：/path/to/legacy/src/main/java

請產出：
1. 【架構報告】
   - 現有架構模式識別
   - 模組間耦合度分析
   - 技術債務清單（依嚴重度排序）
   
2. 【類別關係圖】（Mermaid class diagram）

3. 【相依性風險報告】
   - EOL（End of Life）元件
   - 已知 CVE 漏洞
   - 無維護的 Library

4. 【遷移建議】
   - 優先級排序
   - 風險評估
   - 工作量估計（Story Points）

5. 【程式碼品質指標】
   - 圈複雜度（Cyclomatic Complexity）
   - God Class 清單
   - 重複程式碼比例"

# Step 1: 產生現有 API 清單
# Warp Agent Mode Prompt：
"掃描 Legacy 專案中所有 @RequestMapping / @GetMapping / @PostMapping，
產出完整的 API 對照表：
| 現有 URL | HTTP Method | Controller | 參數 | 說明 |"

# Step 2: 設計新架構
# Warp Agent Mode Prompt：
"基於上述 API 對照表，設計 Clean Architecture 微服務架構：
1. 服務拆分建議（依 DDD Bounded Context）
2. 每個服務的 API 設計（RESTful + OpenAPI）
3. 服務間通訊方式（同步 REST / 非同步 MQ）
4. 資料庫拆分策略
5. 遷移順序（Strangler Fig Pattern）"

# Step 3: 逐步遷移
# 使用 Strangler Fig Pattern
# 在 Warp 中同時監控新舊系統

# Warp Agent Mode：批量文件生成

"為 Legacy 專案中的以下服務自動產生：

1. 【技術文件】
   - 每個 Service 的功能說明
   - 輸入/輸出資料流程
   - 業務規則描述

2. 【API 規格】
   - 將現有 Controller 轉換為 OpenAPI 3.0
   - 包含 Request/Response 範例

3. 【測試案例】
   - 根據現有邏輯反推 Unit Test
   - 使用 JUnit 5 + Mockito
   - 覆蓋所有分支條件

4. 【資料庫文件】
   - ER Diagram（Mermaid）
   - 資料字典
   - Stored Procedure 說明

請將所有產出放在 docs/ 目錄下。"

# Step 1: 分析 Breaking Changes
# 使用 Spring Boot Migrator
git clone https://github.com/spring-projects-experimental/spring-boot-migrator.git
cd spring-boot-migrator
mvn clean install
java -jar target/spring-boot-migrator.jar /path/to/project

# Step 2: 使用 OpenRewrite 自動遷移
mvn -U org.openrewrite.maven:rewrite-maven-plugin:run \
  -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-spring:LATEST \
  -Drewrite.activeRecipes=org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_4

# Step 3: 驗證
mvn clean compile
mvn test

# Warp Agent Mode：Spring Boot 升級分析

"分析當前專案的 Spring Boot 2.7 → 3.4 升級影響：

1. 掃描 pom.xml 中所有依賴
2. 識別 javax.* 引用（需改為 jakarta.*）
3. 檢查 Spring Security 配置（WebSecurityConfigurerAdapter 已移除）
4. 檢查 Spring Data 變更（Repository 方法命名）
5. 檢查 Actuator 端點變更
6. 檢查 Properties 名稱變更

產出：
- 影響清單（依風險排序）
- 每項變更的修改指引
- 自動修復可行的項目標記
- 需人工審查的項目標記
- 預估工時"

# Step 1: 確認目前版本
java -version
mvn --version

# Step 2: 安裝 Java 21
# Windows
winget install EclipseAdoptium.Temurin.21.JDK

# macOS
brew install openjdk@21

# 或使用 SDKMAN
sdk install java 21.0.5-tem
sdk use java 21.0.5-tem

# Step 3: 更新 pom.xml

# Warp Agent Mode：Java 升級

"將專案從 Java 8 升級至 Java 21，自動轉換以下內容：

1. 【語法現代化】
   - Anonymous class → Lambda
   - for loop → Stream API
   - String concatenation → Text Block / String.format
   - instanceof + cast → Pattern Matching
   - switch statement → switch expression
   - Optional 鏈式呼叫

2. 【新 API 使用】
   - java.time 替換 java.util.Date
   - HttpClient 替換 Apache HttpClient
   - Records 替換簡單 POJO
   - Sealed classes（適用場景）

3. 【模組化準備】
   - 檢查 internal API 使用
   - 檢查反射存取（--add-opens 需求）

4. 【建置設定】
   - pom.xml 的 maven.compiler.source/target
   - Dockerfile 基礎映像更新

每項轉換標記 [AUTO] 或 [MANUAL]，
[MANUAL] 需說明原因與建議修改方式。"

# Warp Drive Workflow：Framework 升級流程
---
name: "Framework Upgrade Pipeline"
command: |
  echo "📋 Phase 1: 分析..."
  echo "  掃描 Breaking Changes..."
  mvn versions:display-dependency-updates > dep-updates.txt
  mvn versions:display-plugin-updates > plugin-updates.txt
  
  echo "🔧 Phase 2: 自動修復..."
  echo "  執行 OpenRewrite..."
  mvn -U org.openrewrite.maven:rewrite-maven-plugin:run \
    -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-spring:LATEST \
    -Drewrite.activeRecipes={{recipe}}
  
  echo "🔨 Phase 3: 編譯驗證..."
  mvn clean compile 2>&1 | tee compile-result.txt
  
  echo "🧪 Phase 4: 測試..."
  mvn test 2>&1 | tee test-result.txt
  
  echo "📊 Phase 5: 報告..."
  echo "  編譯結果: $(grep -c 'ERROR' compile-result.txt) 個錯誤"
  echo "  測試結果: $(grep 'Tests run:' test-result.txt | tail -1)"
  
  echo "✅ 升級流程完成，請查閱報告"
arguments:
  - name: recipe
    description: "OpenRewrite Recipe 名稱"
    default_value: "org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_4"

# 1. Java Maven Build Workflow
---
name: "Java Maven Build"
command: |
  echo "🔨 Building {{project_name}}..."
  cd {{project_dir}}
  mvn clean {{goal}} \
    -P {{profile}} \
    -DskipTests={{skip_tests}} \
    -T {{threads}}
  echo "✅ Build completed"
tags: [java, maven, build]
arguments:
  - name: project_name
    description: "專案名稱"
  - name: project_dir
    description: "專案目錄"
    default_value: "."
  - name: goal
    description: "Maven Goal"
    default_value: "package"
  - name: profile
    description: "Maven Profile"
    default_value: "dev"
  - name: skip_tests
    description: "是否跳過測試"
    default_value: "false"
  - name: threads
    description: "平行建置執行緒"
    default_value: "2C"

# 2. Health Check Workflow
---
name: "Service Health Check"
command: |
  echo "🏥 Checking {{service_name}} health..."
  
  # HTTP Health Check
  HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" {{health_url}})
  echo "HTTP Status: $HTTP_STATUS"
  
  # Response Time
  RESPONSE_TIME=$(curl -s -o /dev/null -w "%{time_total}" {{health_url}})
  echo "Response Time: ${RESPONSE_TIME}s"
  
  # Detailed Health
  curl -s {{health_url}} | jq '.'
  
  if [ "$HTTP_STATUS" = "200" ]; then
    echo "✅ {{service_name}} is healthy"
  else
    echo "❌ {{service_name}} is unhealthy!"
  fi
tags: [ops, health, monitoring]
arguments:
  - name: service_name
    description: "服務名稱"
  - name: health_url
    description: "健康檢查 URL"
    default_value: "http://localhost:8080/actuator/health"

# Level 1-2：使用 Warp Drive Environment Variables
# 直接在 Warp Drive 中設定，團隊可見

# Level 3：使用 Warp Drive + 權限控管
# Warp Drive → Environment Variables → 設定存取權限

# Level 4：使用外部密鑰管理
# HashiCorp Vault / AWS Secrets Manager / Azure Key Vault
# Warp 中透過 CLI 取得

# Vault 整合範例
export DB_PASSWORD=$(vault kv get -field=password secret/myapp/db)
export JWT_SECRET=$(vault kv get -field=secret secret/myapp/jwt)

# ⚠️ 禁止事項
# ❌ 不可將密碼寫在 Workflow 中
# ❌ 不可將 API Key commit 到 Git
# ❌ 不可在 Block 分享中包含密鑰
# ❌ 不可截圖包含密鑰的 Block

# SpotBugs + Find Security Bugs
mvn spotbugs:check -Dspotbugs.plugins.plugin.groupId=com.h3xstream.findsecbugs \
  -Dspotbugs.plugins.plugin.artifactId=findsecbugs-plugin

# SonarQube 掃描
mvn sonar:sonar \
  -Dsonar.projectKey=order-service \
  -Dsonar.host.url=http://sonar.internal:9000 \
  -Dsonar.login={{SONAR_TOKEN}}

# Semgrep（開源 SAST）
semgrep --config=p/java --config=p/owasp-top-ten src/

# 在 Warp 中查看結果
# 掃描結果自動成為 Block，可用 AI 分析

# Warp Agent Mode Prompt：

"分析以下 Java 程式碼的安全漏洞：

[貼上程式碼或指定檔案路徑]

請依 OWASP Top 10:2025（2026 年 1 月正式發布版本）檢查：
1. A01:2025 - Broken Access Control
2. A02:2025 - Security Misconfiguration
3. A03:2025 - Software Supply Chain Failures
4. A04:2025 - Cryptographic Failures
5. A05:2025 - Injection（SQL / XSS / Command）
6. A06:2025 - Insecure Design
7. A07:2025 - Authentication Failures
8. A08:2025 - Software or Data Integrity Failures
9. A09:2025 - Security Logging and Alerting Failures
10. A10:2025 - Mishandling of Exceptional Conditions

產出格式：
| 風險等級 | OWASP 類別 | 檔案:行號 | 說明 | 修復建議 |"

# OWASP Dependency Check
mvn org.owasp:dependency-check-maven:check

# Maven Dependency 漏洞掃描
mvn versions:display-dependency-updates

# npm audit（前端）
cd frontend && npm audit --production

# Trivy（容器掃描）
trivy image order-service:latest
trivy fs --security-checks vuln,config .

# Warp Drive Workflow：每日安全掃描
---
name: "Daily Security Scan"
command: |
  echo "🔐 Security Scan Starting..."
  DATE=$(date +%Y%m%d)
  
  echo "📦 Step 1: Dependency Check..."
  mvn org.owasp:dependency-check-maven:check \
    -DfailBuildOnCVSS=7 2>&1 | tee security/dep-check-$DATE.txt
  
  echo "🔍 Step 2: SAST..."
  semgrep --config=p/java --config=p/owasp-top-ten \
    --json src/ > security/sast-$DATE.json
  
  echo "🐳 Step 3: Container Scan..."
  trivy image --severity HIGH,CRITICAL \
    order-service:latest > security/container-$DATE.txt
  
  echo "📊 Step 4: Report..."
  echo "  CVE High+: $(grep -c 'HIGH\|CRITICAL' security/dep-check-$DATE.txt)"
  echo "  SAST Issues: $(jq '.results | length' security/sast-$DATE.json)"
  
  echo "✅ Security Scan Complete"
tags: [security, sast, scan, daily]

# Gitleaks（Git 歷史中的機密掃描）
gitleaks detect --source=. --verbose

# TruffleHog
trufflehog git file://. --since-commit HEAD~50

# 在 pre-commit hook 中防止機密提交
# .pre-commit-config.yaml
cat > .pre-commit-config.yaml << 'EOF'
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.0
    hooks:
      - id: gitleaks
EOF

pre-commit install

# 使用 Warp Block 分析日誌
# 每個指令輸出自動成為 Block，可搜尋、過濾

# 即時日誌監控
tail -f /var/log/app/application.log | grep --line-buffered "ERROR"

# 結構化日誌查詢（JSON 格式日誌）
cat app.log | jq 'select(.level == "ERROR") | {time: .timestamp, msg: .message, trace: .stackTrace}'

# 統計錯誤分佈
cat app.log | jq -r 'select(.level == "ERROR") | .logger' | sort | uniq -c | sort -rn | head -20

# Kubernetes 日誌
kubectl logs -f deployment/order-service --all-containers --since=1h | grep "ERROR"

# AI 分析日誌
# 選取日誌 Block → "Explain with AI"

# Warp Agent Mode：日誌分析

"分析以下應用日誌中的異常模式：

[貼上日誌或指定檔案]

請產出：
1. 異常類型分類與統計
2. 時間分佈熱力圖（文字描述）
3. 根本原因分析（Top 5）
4. 關聯性分析（相同 traceId 的錯誤鏈）
5. 建議的修復優先順序
6. 監控告警規則建議（Prometheus alerting rules）"

# Warp Drive Workflow：系統巡檢
---
name: "System Daily Check"
command: |
  echo "🔍 系統巡檢 - $(date '+%Y-%m-%d %H:%M')"
  echo "================================"
  
  echo "📊 1. 服務狀態"
  for svc in order-service user-service payment-service; do
    STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://$svc:8080/actuator/health)
    if [ "$STATUS" = "200" ]; then
      echo "  ✅ $svc: UP"
    else
      echo "  ❌ $svc: DOWN (HTTP $STATUS)"
    fi
  done
  
  echo ""
  echo "💾 2. 磁碟使用"
  df -h | grep -E "^/dev" | awk '{print "  " $6 ": " $5 " used (" $4 " free)"}'
  
  echo ""
  echo "🐳 3. 容器狀態"
  podman ps --format "  {{.Names}}: {{.Status}}"
  
  echo ""
  echo "📈 4. 資源使用"
  echo "  CPU: $(top -bn1 | grep 'Cpu(s)' | awk '{print $2}')%"
  echo "  MEM: $(free -m | awk 'NR==2{printf "%.1f%%", $3*100/$2}')"
  
  echo ""
  echo "🔐 5. 安全事件"
  journalctl --since "24 hours ago" | grep -c "authentication failure"
  
  echo "================================"
  echo "巡檢完成"
tags: [ops, daily, health-check]

# Warp Drive Workflow：事件處理 SOP
---
name: "Incident Response"
command: |
  echo "🚨 Incident Response - {{incident_id}}"
  echo "================================"
  
  echo "📋 Step 1: 收集資訊"
  echo "  服務: {{service_name}}"
  echo "  環境: {{environment}}"
  echo "  時間: $(date)"
  
  echo ""
  echo "📊 Step 2: 取得即時狀態"
  kubectl get pods -n {{namespace}} -l app={{service_name}}
  kubectl top pods -n {{namespace}} -l app={{service_name}}
  
  echo ""
  echo "📝 Step 3: 取得最近日誌"
  kubectl logs -n {{namespace}} deployment/{{service_name}} --tail=100 --since=10m
  
  echo ""
  echo "🔍 Step 4: 取得事件"
  kubectl get events -n {{namespace}} --sort-by='.lastTimestamp' | tail -20
  
  echo ""
  echo "💡 請使用 AI Agent Mode 分析上述資訊"
  echo "   建議 Prompt: '分析以上 K8s 日誌與事件，找出根本原因並提供修復步驟'"
arguments:
  - name: incident_id
    description: "事件編號"
  - name: service_name
    description: "受影響的服務名稱"
  - name: environment
    description: "環境（dev/sit/uat/prod）"
  - name: namespace
    description: "K8s Namespace"
    default_value: "default"
tags: [ops, incident, emergency]

# CLEAR 框架（企業級 AI Prompt 設計）

C - Context（上下文）
    專案技術棧、架構模式、團隊約定

L - Language（語言/格式）
    輸出格式、程式語言、命名規範

E - Examples（範例）
    期望的輸入輸出範例

A - Action（動作）
    明確的任務指令

R - Restrictions（限制）
    安全約束、效能要求、相容性

# ✅ 好的 Prompt
"Context: Spring Boot 3.4 + Java 21 + Clean Architecture 專案
Language: Java，使用 records, sealed classes, pattern matching
Action: 建立 PaymentService，實作信用卡付款邏輯
Examples:
  - 輸入：PaymentCommand(orderId, amount, cardToken)
  - 輸出：PaymentResult(transactionId, status, timestamp)
Restrictions:
  - 金額需用 BigDecimal（不可用 double）
  - 敏感資料（cardToken）不可出現在日誌
  - 需加入冪等性檢查（Idempotency Key）
  - 交易需要 @Transactional"

# ❌ 不好的 Prompt
"幫我寫一個付款功能"

# ❌ 錯誤做法
claude "寫一個登入功能" → 直接複製到 production code

# ✅ 正確做法
claude "寫一個登入功能" → Code Review → 安全審查 → 單元測試 → 整合測試 → 合併

# ❌ 適合 AI 自動化的任務
# - 樣板程式碼生成（CRUD / DTO / Mapper）
# - 測試案例生成
# - 文件生成
# - 指令查詢

# ✅ 需人工決策的任務
# - 架構設計決策
# - 安全策略制定
# - 資料庫 schema 設計（需 DBA 審查）
# - 生產環境部署審批
# - 效能關鍵路徑最佳化

Level 1 → Level 2：
☐ 全員安裝 Warp
☐ 完成基礎培訓
☐ 設定預設 Shell

Level 2 → Level 3：
☐ 建立 10+ 團隊 Workflow
☐ 建立 Prompt 範本庫
☐ Warp Drive 啟用

Level 3 → Level 4：
☐ 安全掃描整合 CI/CD
☐ AI 使用 Dashboard
☐ 成效量化報告

Level 4 → Level 5：
☐ Cloud Agent 自動化
☐ 自動 PR Review
☐ 自動化維運巡檢

環境建置
☐ 安裝 Warp（https://www.warp.dev/download）
☐ 設定預設 Shell（Bash / Zsh / PowerShell）
☐ 確認 GPU 加速已啟用
☐ 安裝 Warp 主題（團隊統一）
☐ 設定 Git 整合

AI Agent 設定
☐ 安裝 Claude Code（npm install -g @anthropic-ai/claude-code）
☐ 設定 ANTHROPIC_API_KEY
☐ 安裝 GitHub Copilot CLI（gh extension install github/gh-copilot）
☐ 認證 GitHub（gh auth login）
☐ 熟悉 Agent Mode（Cmd/Ctrl + L）

Warp Drive
☐ 加入團隊 Warp Drive
☐ 匯入團隊 Workflows
☐ 載入環境變數（DEV）
☐ 瀏覽 Prompt 範本庫

開發工具
☐ 安裝 Java 21（sdk install java 21.0.5-tem）
☐ 安裝 Maven（sdk install maven）
☐ 安裝 Node.js 20+（nvm install 20）
☐ 安裝 Podman / Docker

安全設定
☐ 安裝 pre-commit hooks（gitleaks）
☐ 確認不使用 PROD 環境變數
☐ 了解機密管理策略
☐ 閱讀 SSDLC 流程文件

日常作業
☐ 熟悉 Block 操作（導覽 / 搜尋 / 複製 / 分享）
☐ 練習使用 Warp AI Explain 功能
☐ 執行第一個團隊 Workflow
☐ 使用 AI Agent 完成一個小型任務
☐ 熟悉 Prompt Queueing（/queue）與 Custom Model Routers 設定

開工
☐ 啟動 Warp → 確認環境變數已載入
☐ git pull 取得最新程式碼
☐ 檢查 CI/CD Pipeline 狀態

開發中
☐ 使用 AI Agent 輔助（非取代）開發
☐ 每次 commit 前執行本地測試
☐ 每次 commit 前確認無敏感資訊

收工
☐ 推送所有變更至遠端
☐ 更新 Warp Drive 知識筆記（如有新發現）
☐ 分享有價值的 Block 給團隊

mvn clean compile                    # 清除並編譯
mvn test                             # 執行測試
mvn package -DskipTests              # 打包（跳過測試）
mvn dependency:tree                  # 相依性樹
mvn versions:display-dependency-updates  # 可更新的依賴
mvn spotbugs:check                   # 靜態分析
mvn sonar:sonar                      # SonarQube 掃描
mvn flyway:migrate                   # DB 遷移
mvn spring-boot:run                  # 啟動 Spring Boot

podman build -t app:latest .         # 建置映像
podman run -d -p 8080:8080 app       # 啟動容器
podman compose up -d                 # 啟動服務堆疊
podman logs -f <container>           # 查看日誌
podman exec -it <container> bash     # 進入容器

kubectl get pods -w                  # 監控 Pod 狀態
kubectl logs -f deploy/<name>        # 追蹤日誌
kubectl describe pod <name>          # Pod 詳情
kubectl rollout restart deploy/<name>  # 重啟部署
kubectl port-forward svc/<name> 8080:80  # 連接埠轉發

# CG-001：REST Controller 生成
"為 {{domain}} 建立 Spring Boot REST Controller：
- 使用 @RestController + @RequestMapping("/api/v1/{{path}}")
- CRUD 操作（GET/POST/PUT/DELETE）
- Request 驗證（@Valid + @Validated）
- OpenAPI 3.0 註解
- 統一例外處理
- 分頁查詢支援
- Java 21 語法"

# CG-002：Vue 3 Component 生成
"建立 Vue 3 + TS + Tailwind 元件 {{component_name}}：
- <script setup lang='ts'>
- Props 定義（defineProps with TypeScript）
- Emits 定義（defineEmits）
- 使用 Composition API
- 響應式設計
- Loading / Error 狀態處理"

# CG-003：Unit Test 生成
"為 {{class_name}} 撰寫 JUnit 5 測試：
- @ExtendWith(MockitoExtension.class)
- Mock 所有依賴
- Given-When-Then 模式
- @DisplayName 中文描述
- 涵蓋正常/異常/邊界情境
- AssertJ 斷言"

# AN-001：架構分析
"分析 {{project_path}} 的架構：
1. 識別架構模式
2. 繪製 Mermaid 元件圖
3. 分析耦合度
4. 列出技術債務
5. 提供重構建議"

# AN-002：效能分析
"分析以下 SQL 查詢的效能：
[SQL]
1. 執行計畫分析
2. 索引建議
3. 查詢改寫建議
4. N+1 問題檢查"

# AN-003：安全分析
"檢查以下程式碼的安全漏洞（OWASP Top 10）：
[程式碼]
產出：風險等級 | 類別 | 位置 | 說明 | 修復"

# OP-001：錯誤分析
"分析以下錯誤日誌：
[日誌]
1. 根本原因
2. 影響範圍
3. 修復步驟
4. 預防措施"

# OP-002：效能調優
"分析以下 JVM 記憶體報告：
[jmap output]
1. 記憶體洩漏風險
2. GC 調優建議
3. JVM 參數建議"

# 查看團隊 Credits 用量（Oz CLI）
oz credits usage --team my-team --period monthly

# 設定用量上限
oz credits limit --team my-team --monthly-limit 10000

# 查看個人用量
oz credits usage --user me