superpowers/                          # GitHub: obra/superpowers
├── skills/                           # 技能定義（核心）
│   ├── brainstorming.md
│   ├── test-driven-development.md
│   ├── systematic-debugging.md
│   ├── verification-before-completion.md
│   ├── writing-plans.md
│   ├── executing-plans.md
│   ├── dispatching-parallel-agents.md
│   ├── requesting-code-review.md
│   ├── receiving-code-review.md
│   ├── using-git-worktrees.md
│   ├── finishing-a-development-branch.md
│   ├── subagent-driven-development.md
│   ├── writing-skills.md
│   └── using-superpowers.md
├── references/                       # 參考資料（技能可引用）
│   └── testing-anti-patterns.md
├── hooks/                            # Hooks 系統
│   └── session-start.*               # 各平台的 session-start hook
├── tools/                            # 工具腳本
│   └── brainstorm-server/            # Visual Brainstorming Companion
│       ├── server.mjs                # 零依賴 Node.js 伺服器
│       └── index.html                # 瀏覽器端介面
├── INSTALL.md                        # 各平台安裝指南
├── CHANGELOG.md
├── RELEASE-NOTES.md
└── README.md

hooks/
└── session-start          # 依平台不同使用不同格式
    ├── 01-setup.sh        # Unix 環境初始化
    └── 01-setup.ps1       # Windows 環境初始化

# 在 Claude Code 中執行
/plugin install superpowers@claude-plugins-official

# 安裝完成後自動生效——技能會在每次 session 開始時自動載入

# 開始新的 Claude Code session
claude

# 輸入任何開發請求，觀察 Agent 是否自動啟動 Brainstorming
> "幫我加一個使用者登入功能"
# 預期：Agent 開始蘇格拉底式提問，而非直接寫程式碼

# 在 Cursor 中執行
/add-plugin superpowers

# 或透過 Cursor 的 Plugin Marketplace UI 搜尋 "superpowers"

// .cursor/settings.json — 通常 Plugin 安裝時自動設定
{
  "superpowers.hooks.sessionStart": true,
  "superpowers.visualCompanion": true
}

# 1. Clone Superpowers 倉庫到本機暫存
git clone https://github.com/obra/superpowers.git /tmp/superpowers

# 2. 複製 AGENTS.md 到專案（Codex 使用 AGENTS.md 作為指令檔）
cp /tmp/superpowers/INSTALL_CODEX/AGENTS.md ./AGENTS.md

# 3. 複製技能目錄
cp -r /tmp/superpowers/skills/ ./superpowers-skills/

# 4. Codex 會自動讀取 AGENTS.md 並套用技能

# v5.0.4 起支援一行安裝
opencode plugin install superpowers

# 或手動安裝（舊版本）
git clone https://github.com/obra/superpowers.git /tmp/superpowers
cp /tmp/superpowers/INSTALL_OPENCODE/instructions.md ~/.opencode/instructions.md
cp -r /tmp/superpowers/skills/ ~/.opencode/agents/superpowers/

# Extension 安裝
gemini extensions install superpowers

# 或手動設定
# 參照 INSTALL.md 中的 Gemini CLI 區段

<!-- .github/copilot-instructions.md -->
# Copilot 開發規範（基於 Superpowers 方法論）

## 強制規則
- 收到新功能需求時，先提問釐清（至少 5 個問題），不要直接寫程式碼
- 必須先產出微步驟計畫（每步 2-5 分鐘），人工核准後才開始
- 每個功能必須有對應的測試（TDD: Red → Green → Refactor）
- Debug 時必須先建立假設再驗證（Systematic Debugging 4 階段）
- 所有實驗性工作必須在 Git Worktree 中進行

<!-- CLAUDE.md -->
# 專案開發規範

## 技術堆疊
- Language: Java 21
- Framework: Spring Boot 3.x
- Build: Maven 3.9+
- Test: JUnit 5 + Mockito

## Superpowers 客製化
- Brainstorming 最少提問：5 題
- Planning 每步上限：5 分鐘
- TDD 覆蓋率最低：80%
- 所有 feature 開發必須使用 Git Worktree

<!-- .cursorrules -->
# Cursor 開發規範（Superpowers 增強）

遵循 Superpowers 工作流：
1. 新功能 → Brainstorming → Writing Plans → Subagent Development
2. 強制 TDD：先寫測試、再寫實作
3. Debug → Systematic Debugging（假設驅動 4 階段）
4. 所有實驗 → Git Worktree 隔離

your-project/
├── CLAUDE.md                    # Claude Code 專案指令（客製化用）
├── .cursorrules                 # Cursor 規範（客製化用）
├── .github/
│   ├── copilot-instructions.md  # Copilot 方法論注入
│   └── workflows/
│       ├── ci.yml
│       └── tdd-check.yml
├── src/
│   ├── main/java/...
│   └── test/java/...
├── pom.xml
└── README.md

your-project/
├── superpowers-skills/          # 手動複製的技能（Codex 等平台）
│   ├── brainstorming.md
│   ├── test-driven-development.md
│   ├── ...
│   └── using-superpowers.md
├── AGENTS.md                    # Codex 用
├── CLAUDE.md                    # Claude Code 用
├── src/
└── pom.xml

monorepo/
├── CLAUDE.md                    # 全域 Claude 指令
├── packages/
│   ├── frontend/
│   │   ├── CLAUDE.md            # 前端專屬覆寫
│   │   └── src/
│   ├── backend/
│   │   ├── CLAUDE.md            # 後端專屬覆寫
│   │   └── src/
│   └── shared/
│       └── src/
└── pom.xml / package.json

// .devcontainer/devcontainer.json
{
  "name": "Superpowers Dev Environment",
  "image": "mcr.microsoft.com/devcontainers/java:21",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {},
    "ghcr.io/devcontainers/features/git:1": {}
  },
  "postCreateCommand": "npm install -g @anthropic-ai/claude-code && claude /plugin install superpowers@claude-plugins-official",
  "customizations": {
    "vscode": {
      "extensions": [
        "vscjava.vscode-java-pack",
        "github.copilot",
        "github.copilot-chat"
      ]
    }
  }
}

# Claude Code
/plugin update superpowers

# Cursor
/update-plugin superpowers

# OpenCode
opencode plugin update superpowers

# 拉取最新版本
cd /path/to/superpowers-clone
git pull origin main

# 重新複製技能檔
cp -r skills/ /path/to/your-project/superpowers-skills/

# 安裝指定版本
/plugin install superpowers@5.0.5

# 或手動 checkout 特定 tag
git checkout v5.0.5

# 1. 確認 Git Worktree 可用
git worktree list

# 2. 確認 Node.js 版本（Visual Companion 需要）
node --version   # 預期：v18+

# 3. 測試 Git Worktree 建立
git worktree add ../sp-test -b sp/test/verify
git worktree remove ../sp-test

# 4. 開始新 session 並測試技能觸發
#    輸入任何開發請求，確認 Agent 自動啟動 Brainstorming

✅ Git Worktree 支援：正常
✅ Node.js 版本：v18+
✅ Superpowers Plugin：已安裝 v5.0.5
✅ 技能自動觸發：正常（15 個技能已載入）
✅ Visual Companion：可啟動（零依賴 Node.js 伺服器）

使用者：「我需要一個登入功能。」

AI Brainstorming 回覆：
1. 登入功能的目標使用者是誰？（內部員工 / 外部客戶 / 兩者皆是）
2. 需要支援哪些認證方式？（帳號密碼 / SSO / OAuth2 / 多因素認證）
3. 登入失敗時需要怎樣的處理？（鎖定次數 / 驗證碼 / 通知管理員）
4. 是否需要「記住我」功能？Session 有效期限為何？
5. 是否需要稽核日誌（Audit Log）？

使用者：「用 JWT 做認證就好。」

AI Brainstorming 回覆：
1. 確認一下，JWT 是否需要搭配 Refresh Token 機制？
2. Token 是否需要支援撤銷（Revocation）？純 JWT 無法實現即時撤銷。
3. 目前系統是否有現存的 Session 機制需要相容？
4. 前端 Token 儲存位置？（HttpOnly Cookie vs LocalStorage — 安全性考量）
5. 是否需要考慮跨域（CORS）場景？

AI Brainstorming 回覆：
1. 同一帳號是否允許多裝置同時登入？
2. 預計尖峰時段的並發登入數量？
3. 如果認證服務（如 LDAP/AD）不可用時，系統該如何處理？
4. 密碼規則的最低要求是什麼？
5. 是否需要支援密碼過期強制重設？

package com.tutorial.banking.service;

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.DisplayName;

import static org.junit.jupiter.api.Assertions.*;

/**
 * 帳戶轉帳服務測試類別。
 * 遵循 Superpowers TDD 技能：先寫測試，再寫實作。
 */
class TransferServiceTest {

    private TransferService transferService;
    private Account sourceAccount;
    private Account targetAccount;

    @BeforeEach
    void setUp() {
        transferService = new TransferService();
        sourceAccount = new Account("ACC-001", 10000.0);
        targetAccount = new Account("ACC-002", 5000.0);
    }

    @Test
    @DisplayName("正常轉帳：來源帳戶扣款、目標帳戶入款")
    void shouldTransferAmountBetweenAccounts() {
        // Given
        double transferAmount = 3000.0;

        // When
        TransferResult result = transferService.transfer(
            sourceAccount, targetAccount, transferAmount
        );

        // Then
        assertTrue(result.isSuccess());
        assertEquals(7000.0, sourceAccount.getBalance());
        assertEquals(8000.0, targetAccount.getBalance());
    }

    @Test
    @DisplayName("餘額不足時應拒絕轉帳")
    void shouldRejectTransferWhenInsufficientBalance() {
        // Given
        double transferAmount = 15000.0;

        // When
        TransferResult result = transferService.transfer(
            sourceAccount, targetAccount, transferAmount
        );

        // Then
        assertFalse(result.isSuccess());
        assertEquals("INSUFFICIENT_BALANCE", result.getErrorCode());
        assertEquals(10000.0, sourceAccount.getBalance()); // 餘額不變
        assertEquals(5000.0, targetAccount.getBalance());   // 餘額不變
    }

    @Test
    @DisplayName("轉帳金額不可為零或負數")
    void shouldRejectNonPositiveAmount() {
        assertAll(
            () -> {
                TransferResult result = transferService.transfer(
                    sourceAccount, targetAccount, 0
                );
                assertFalse(result.isSuccess());
                assertEquals("INVALID_AMOUNT", result.getErrorCode());
            },
            () -> {
                TransferResult result = transferService.transfer(
                    sourceAccount, targetAccount, -100
                );
                assertFalse(result.isSuccess());
                assertEquals("INVALID_AMOUNT", result.getErrorCode());
            }
        );
    }

    @Test
    @DisplayName("不可轉帳給自己")
    void shouldRejectSelfTransfer() {
        TransferResult result = transferService.transfer(
            sourceAccount, sourceAccount, 1000.0
        );
        assertFalse(result.isSuccess());
        assertEquals("SELF_TRANSFER", result.getErrorCode());
    }
}

mvn test -Dtest=TransferServiceTest
# 結果：4 tests, 0 passed, 4 failed ← 正確！這就是 Red 階段

package com.tutorial.banking.service;

/**
 * 帳戶轉帳服務。
 * 
 * @author AI (Superpowers TDD)
 */
public class TransferService {

    /**
     * 執行帳戶間轉帳。
     *
     * @param source 來源帳戶
     * @param target 目標帳戶
     * @param amount 轉帳金額
     * @return 轉帳結果
     */
    public TransferResult transfer(Account source, Account target, double amount) {
        // 驗證：金額必須為正數
        if (amount <= 0) {
            return TransferResult.failure("INVALID_AMOUNT", "轉帳金額必須大於零");
        }

        // 驗證：不可自轉
        if (source.getAccountId().equals(target.getAccountId())) {
            return TransferResult.failure("SELF_TRANSFER", "不可轉帳給自己");
        }

        // 驗證：餘額充足
        if (source.getBalance() < amount) {
            return TransferResult.failure("INSUFFICIENT_BALANCE", "餘額不足");
        }

        // 執行轉帳
        source.debit(amount);
        target.credit(amount);

        return TransferResult.success(source, target, amount);
    }
}

package com.tutorial.banking.service;

/**
 * 帳戶模型。
 */
public class Account {
    private final String accountId;
    private double balance;

    public Account(String accountId, double balance) {
        this.accountId = accountId;
        this.balance = balance;
    }

    public String getAccountId() { return accountId; }
    public double getBalance() { return balance; }

    public void debit(double amount) { this.balance -= amount; }
    public void credit(double amount) { this.balance += amount; }
}

package com.tutorial.banking.service;

/**
 * 轉帳結果。
 */
public class TransferResult {
    private final boolean success;
    private final String errorCode;
    private final String message;

    private TransferResult(boolean success, String errorCode, String message) {
        this.success = success;
        this.errorCode = errorCode;
        this.message = message;
    }

    public static TransferResult success(Account source, Account target, double amount) {
        return new TransferResult(true, null,
            String.format("成功轉帳 %.2f 從 %s 到 %s",
                amount, source.getAccountId(), target.getAccountId()));
    }

    public static TransferResult failure(String errorCode, String message) {
        return new TransferResult(false, errorCode, message);
    }

    public boolean isSuccess() { return success; }
    public String getErrorCode() { return errorCode; }
    public String getMessage() { return message; }
}

mvn test -Dtest=TransferServiceTest
# 結果：4 tests, 4 passed, 0 failed ← Green！

// 重構：將驗證邏輯抽取為私有方法
public class TransferService {

    public TransferResult transfer(Account source, Account target, double amount) {
        TransferResult validation = validate(source, target, amount);
        if (validation != null) {
            return validation;
        }

        execute(source, target, amount);
        return TransferResult.success(source, target, amount);
    }

    private TransferResult validate(Account source, Account target, double amount) {
        if (amount <= 0) {
            return TransferResult.failure("INVALID_AMOUNT", "轉帳金額必須大於零");
        }
        if (source.getAccountId().equals(target.getAccountId())) {
            return TransferResult.failure("SELF_TRANSFER", "不可轉帳給自己");
        }
        if (source.getBalance() < amount) {
            return TransferResult.failure("INSUFFICIENT_BALANCE", "餘額不足");
        }
        return null; // 驗證通過
    }

    private void execute(Account source, Account target, double amount) {
        source.debit(amount);
        target.credit(amount);
    }
}

mvn test -Dtest=TransferServiceTest
# 結果：4 tests, 4 passed, 0 failed ← Refactor 完成，行為不變

我需要實作「密碼重設功能」。

請使用 Superpowers TDD 技能：
1. 先幫我列出所有需要測試的案例（至少 5 個）
2. 從最簡單的案例開始，寫一個會失敗的測試
3. 等我確認後，再寫實作讓測試通過
4. 每次只處理一個測試案例

# 功能計畫：用戶認證模組

## 需求摘要
實作 JWT 認證，支援登入、登出、Token 刷新。

## 微任務列表

### 階段一：資料模型（預計 10 分鐘）
- [ ] 任務 1.1：建立 `User` 實體類別（3 min）
- [ ] 任務 1.2：建立 `UserRepository` 介面（2 min）
- [ ] 任務 1.3：寫 User 實體的單元測試（5 min）

### 階段二：認證服務（預計 20 分鐘）
- [ ] 任務 2.1：寫 AuthService.login() 的測試（5 min）
- [ ] 任務 2.2：實作 AuthService.login()（5 min）
- [ ] 任務 2.3：寫 AuthService.refreshToken() 的測試（5 min）
- [ ] 任務 2.4：實作 AuthService.refreshToken()（5 min）

## 驗收標準
- [ ] 所有測試通過
- [ ] 測試覆蓋率 ≥ 80%

主 Agent Context:
├── 完整計畫文件
├── 所有技能定義
└── 專案全貌

Subagent Context（隔離的）:
├── 單一任務描述
├── 相關 Spec 片段
├── 相關現有程式碼
└── TDD 技能定義
    （不包含其他任務的 Context）

## Debug 報告：訂單建立失敗

### 問題描述
使用者反映在下午 3 點後建立訂單時，偶爾會收到 500 Internal Server Error。

### 假設列表
| # | 假設 | 可能性 | 驗證方法 | 結果 |
|---|------|--------|---------|------|
| H1 | 資料庫連線池耗盡 | 高 | 檢查 HikariCP 指標 | ❌ 排除 |
| H2 | 第三方 API 超時 | 中 | 檢查 API 回應日誌 | ❌ 排除 |
| H3 | 庫存並發死鎖 | 中 | 檢查 DB lock 日誌 | ✅ 確認 |

### 修復方案
使用樂觀鎖 + @Retryable 處理並發更新

### 回歸測試
shouldHandleConcurrentStockUpdate — 驗證並發安全

=== Superpowers Brainstorming Session ===
功能：訂單結帳
日期：2026-03-23

1. 【釐清】結帳流程包含哪些步驟？（購物車確認 → 選擇付款 → 確認訂單 → 付款 → 完成？）
2. 【釐清】支援哪些付款方式？（信用卡 / 轉帳 / 第三方支付？）
3. 【假設驗證】結帳時是否需要即時檢查庫存？如果庫存在結帳過程中被他人搶購怎麼辦？
4. 【假設驗證】是否需要支援部分退款？還是只支援全額退款？
5. 【邊界探索】尖峰時段預計並發結帳數量？需要考慮限流嗎？
6. 【邊界探索】結帳過程中如果使用者離開頁面，訂單狀態如何處理？（逾時自動取消？）
7. 【安全性】付款資訊是否需要進行 PCI DSS 等級的加密？

## 需求結論

### 功能範圍
- 結帳流程：購物車確認 → 庫存鎖定 → 選擇付款 → 建立訂單 → 付款 → 完成
- 付款方式：信用卡（透過第三方綠界 ECPay）
- 庫存策略：結帳時鎖定庫存 15 分鐘，逾時自動釋放
- 退款：僅支援全額退款（v1）

### 非功能性需求
- 並發：支援 500 TPS 結帳
- 回應時間：< 2 秒
- 安全：付款資訊不經過我方後端，直接由前端送至 ECPay

### 排除範圍（v1 不做）
- 部分退款
- 折價券 / 優惠碼
- 跨幣別結帳

# 結帳功能開發計畫

## 階段一：資料模型（15 分鐘）
- [ ] 1.1 建立 Order 實體（id, userId, items, totalAmount, status, createdAt）— 3 min
- [ ] 1.2 建立 OrderItem 實體（id, orderId, productId, quantity, unitPrice）— 3 min
- [ ] 1.3 建立 OrderStatus 列舉（PENDING, STOCK_LOCKED, PAYMENT_PENDING, PAID, CANCELLED）— 2 min
- [ ] 1.4 建立 OrderRepository — 2 min
- [ ] 1.5 寫 Order 實體的單元測試 — 5 min

## 階段二：庫存鎖定服務（20 分鐘）
- [ ] 2.1 寫 StockLockService.lock() 的測試 — 5 min
  - 正常鎖定、庫存不足、重複鎖定
- [ ] 2.2 實作 StockLockService.lock() — 5 min
- [ ] 2.3 寫 StockLockService.release() 的測試 — 5 min
- [ ] 2.4 實作 StockLockService.release() — 3 min
- [ ] 2.5 寫定時釋放任務（15 分鐘逾時）的測試與實作 — 5 min

## 階段三：訂單服務（25 分鐘）
- [ ] 3.1 寫 CheckoutService.createOrder() 的測試 — 5 min
  - 正常建立、庫存不足、購物車為空
- [ ] 3.2 實作 CheckoutService.createOrder() — 5 min
- [ ] 3.3 寫 CheckoutService.confirmPayment() 的測試 — 5 min
  - 付款成功、付款失敗、訂單不存在
- [ ] 3.4 實作 CheckoutService.confirmPayment() — 5 min
- [ ] 3.5 寫 CheckoutService.cancelOrder() 的測試與實作 — 5 min

## 階段四：API 端點（20 分鐘）
- [ ] 4.1 寫 POST /api/orders/checkout 整合測試 — 5 min
- [ ] 4.2 實作 OrderController.checkout() — 5 min
- [ ] 4.3 寫 POST /api/orders/{id}/confirm-payment 整合測試 — 5 min
- [ ] 4.4 實作 OrderController.confirmPayment() — 5 min

## 階段五：整合測試與收尾（15 分鐘）
- [ ] 5.1 端到端整合測試（完整結帳流程）— 10 min
- [ ] 5.2 API 文件更新 — 5 min

### 預估總時間：95 分鐘
### 總 commit 數量：約 15-18 次

# 建立功能分支的 Worktree
git worktree add ../sp-checkout -b sp/tdd/checkout-feature

# 進入隔離環境
cd ../sp-checkout

# 確認狀態乾淨
git status
# On branch sp/tdd/checkout-feature
# nothing to commit, working tree clean

# 開始按計畫進行 TDD 開發
echo "🚀 Worktree 已建立，開始 Phase 4: TDD 開發"

package com.tutorial.ecommerce.service;

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;

import java.util.List;

import static org.junit.jupiter.api.Assertions.*;
import static org.mockito.ArgumentMatchers.*;
import static org.mockito.Mockito.*;

@ExtendWith(MockitoExtension.class)
class CheckoutServiceTest {

    @Mock
    private OrderRepository orderRepository;

    @Mock
    private StockLockService stockLockService;

    @Mock
    private CartService cartService;

    @InjectMocks
    private CheckoutService checkoutService;

    private List<CartItem> sampleCartItems;

    @BeforeEach
    void setUp() {
        sampleCartItems = List.of(
            new CartItem("PRD-001", 2, 500.0),
            new CartItem("PRD-002", 1, 1200.0)
        );
    }

    @Test
    @DisplayName("正常結帳：應建立訂單並鎖定庫存")
    void shouldCreateOrderAndLockStock() {
        // Given
        String userId = "USR-001";
        when(cartService.getItems(userId)).thenReturn(sampleCartItems);
        when(stockLockService.lockAll(anyList())).thenReturn(true);
        when(orderRepository.save(any(Order.class))).thenAnswer(
            invocation -> {
                Order order = invocation.getArgument(0);
                order.setId("ORD-001");
                return order;
            }
        );

        // When
        OrderResult result = checkoutService.createOrder(userId);

        // Then
        assertTrue(result.isSuccess());
        assertEquals("ORD-001", result.getOrderId());
        assertEquals(2200.0, result.getTotalAmount());
        assertEquals(OrderStatus.STOCK_LOCKED, result.getStatus());
        verify(stockLockService).lockAll(sampleCartItems);
        verify(orderRepository).save(any(Order.class));
    }

    @Test
    @DisplayName("庫存不足時應拒絕建立訂單")
    void shouldRejectWhenInsufficientStock() {
        // Given
        String userId = "USR-001";
        when(cartService.getItems(userId)).thenReturn(sampleCartItems);
        when(stockLockService.lockAll(anyList())).thenReturn(false);

        // When
        OrderResult result = checkoutService.createOrder(userId);

        // Then
        assertFalse(result.isSuccess());
        assertEquals("INSUFFICIENT_STOCK", result.getErrorCode());
        verify(orderRepository, never()).save(any());
    }

    @Test
    @DisplayName("購物車為空時不應建立訂單")
    void shouldRejectWhenCartEmpty() {
        // Given
        String userId = "USR-001";
        when(cartService.getItems(userId)).thenReturn(List.of());

        // When
        OrderResult result = checkoutService.createOrder(userId);

        // Then
        assertFalse(result.isSuccess());
        assertEquals("EMPTY_CART", result.getErrorCode());
        verify(stockLockService, never()).lockAll(anyList());
    }
}

mvn test -Dtest=CheckoutServiceTest
# BUILD FAILURE — 3 tests FAILED (expected: Red ✅)

package com.tutorial.ecommerce.service;

import java.util.List;

/**
 * 結帳服務。負責訂單建立、付款確認與取消。
 */
public class CheckoutService {

    private final OrderRepository orderRepository;
    private final StockLockService stockLockService;
    private final CartService cartService;

    public CheckoutService(OrderRepository orderRepository,
                           StockLockService stockLockService,
                           CartService cartService) {
        this.orderRepository = orderRepository;
        this.stockLockService = stockLockService;
        this.cartService = cartService;
    }

    /**
     * 建立訂單（含庫存鎖定）。
     *
     * @param userId 使用者 ID
     * @return 訂單建立結果
     */
    public OrderResult createOrder(String userId) {
        List<CartItem> items = cartService.getItems(userId);

        if (items.isEmpty()) {
            return OrderResult.failure("EMPTY_CART", "購物車為空");
        }

        if (!stockLockService.lockAll(items)) {
            return OrderResult.failure("INSUFFICIENT_STOCK", "庫存不足");
        }

        double totalAmount = items.stream()
            .mapToDouble(item -> item.getUnitPrice() * item.getQuantity())
            .sum();

        Order order = new Order(userId, items, totalAmount, OrderStatus.STOCK_LOCKED);
        order = orderRepository.save(order);

        return OrderResult.success(order.getId(), totalAmount, order.getStatus());
    }
}

mvn test -Dtest=CheckoutServiceTest
# BUILD SUCCESS — 3 tests PASSED (Green ✅)
git add . && git commit -m "feat(checkout): implement createOrder with TDD - Green"

## Debug Session: 整合測試偶發失敗

### 問題重現
CheckoutIntegrationTest.shouldCreateOrderEndToEnd() 在 CI 上約 20% 失敗。
本地難以重現。

### 假設列表
| # | 假設 | 可能性 | 驗證方法 |
|---|------|--------|---------|
| H1 | 測試之間有資料殘留（未清理 DB） | 高 | 檢查 @Transactional / @DirtiesContext |
| H2 | 非同步庫存鎖定導致時序問題 | 中 | 加入 Awaitility 等待機制 |
| H3 | CI 環境記憶體不足導致 GC 暫停 | 低 | 檢查 CI Runner 資源配置 |

### 驗證結果
| # | 結果 | 證據 |
|---|------|------|
| H1 | ✅ 確認 | 缺少 @Transactional，上一筆測試的 Order 未回滾 |

### 修復
- 加入 @Transactional 於整合測試類別
- 撰寫回歸測試確認資料隔離

# 在 Worktree 中完成所有開發
cd ../sp-checkout

# 觸發 verification-before-completion 技能
# 確認測試全通過
mvn test
# BUILD SUCCESS — 22 tests PASSED

# 確認測試覆蓋率
mvn jacoco:report
# Line coverage: 87% ✅ (threshold: 80%)

# 推送到遠端
git push origin sp/tdd/checkout-feature

# 建立 Pull Request
gh pr create \
  --title "feat(checkout): 實作訂單結帳功能" \
  --body "## 變更摘要
- 實作結帳流程（庫存鎖定 → 建立訂單 → 付款確認）
- 22 個測試案例，覆蓋率 87%
- 使用 Superpowers TDD + Subagent-Driven Development

## Superpowers 流程記錄
- Brainstorming：7 個問題，需求已確認
- Plan：通過 Document Review（2 輪）
- Two-Stage Review：Spec ✅ + Quality ✅"

- [ ] 是否有 Brainstorming 記錄（含 Spec Document）？
- [ ] 是否有微步驟計畫（通過 Document Review）？
- [ ] 每個功能是否有對應測試（TDD）？
- [ ] 測試覆蓋率 ≥ 80%？
- [ ] 是否經過 Two-Stage Review（Spec + Quality）？
- [ ] 是否在隔離的 Worktree 中開發？
- [ ] verification-before-completion 是否通過？
- [ ] 是否遵循小步 commit？

# finishing-a-development-branch 技能自動執行：
# 1. 合併完成後清理 Worktree
cd ../main-project
git worktree remove ../sp-checkout
git branch -d sp/tdd/checkout-feature
git worktree list  # 確認已移除

package com.tutorial.ecommerce.controller;

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.DisplayName;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.transaction.annotation.Transactional;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

/**
 * 訂單 API 整合測試。
 * 使用 Superpowers TDD 技能——先於 Controller 實作。
 */
@SpringBootTest
@AutoConfigureMockMvc
@ActiveProfiles("test")
@Transactional
class OrderControllerIntegrationTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    @DisplayName("POST /api/orders/checkout — 正常結帳")
    void shouldCheckoutSuccessfully() throws Exception {
        String requestBody = """
            {
                "userId": "USR-001",
                "items": [
                    {"productId": "PRD-001", "quantity": 2},
                    {"productId": "PRD-002", "quantity": 1}
                ]
            }
            """;

        mockMvc.perform(post("/api/orders/checkout")
                .contentType(MediaType.APPLICATION_JSON)
                .content(requestBody))
            .andExpect(status().isCreated())
            .andExpect(jsonPath("$.success").value(true))
            .andExpect(jsonPath("$.orderId").exists())
            .andExpect(jsonPath("$.totalAmount").isNumber());
    }

    @Test
    @DisplayName("POST /api/orders/checkout — 購物車為空應回傳 400")
    void shouldReturn400WhenCartEmpty() throws Exception {
        String requestBody = """
            {
                "userId": "USR-001",
                "items": []
            }
            """;

        mockMvc.perform(post("/api/orders/checkout")
                .contentType(MediaType.APPLICATION_JSON)
                .content(requestBody))
            .andExpect(status().isBadRequest())
            .andExpect(jsonPath("$.errorCode").value("EMPTY_CART"));
    }
}

# src/test/resources/application-test.yml
spring:
  datasource:
    url: jdbc:h2:mem:testdb
    driver-class-name: org.h2.Driver
    username: sa
    password:
  jpa:
    hibernate:
      ddl-auto: create-drop
    show-sql: true
  kafka:
    bootstrap-servers: ${spring.embedded.kafka.brokers:localhost:9092}

logging:
  level:
    com.tutorial: DEBUG
    org.springframework.test: INFO

/**
 * 訂單服務呼叫庫存服務的整合測試。
 * 使用 WireMock 模擬庫存服務。
 */
@SpringBootTest
@AutoConfigureWireMock(port = 0)
class OrderStockIntegrationTest {

    @Autowired
    private CheckoutService checkoutService;

    @Test
    @DisplayName("庫存服務不可用時應回傳友善錯誤")
    void shouldHandleStockServiceUnavailable() {
        // Given: 庫存服務回傳 503
        stubFor(post(urlEqualTo("/api/stock/lock"))
            .willReturn(aResponse()
                .withStatus(503)
                .withBody("{\"error\":\"Service Unavailable\"}")));

        // When
        OrderResult result = checkoutService.createOrder("USR-001");

        // Then
        assertFalse(result.isSuccess());
        assertEquals("STOCK_SERVICE_UNAVAILABLE", result.getErrorCode());
    }

    @Test
    @DisplayName("庫存服務超時應觸發 Circuit Breaker")
    void shouldTriggerCircuitBreakerOnTimeout() {
        // Given: 庫存服務延遲 10 秒
        stubFor(post(urlEqualTo("/api/stock/lock"))
            .willReturn(aResponse()
                .withFixedDelay(10000)
                .withStatus(200)));

        // When
        OrderResult result = checkoutService.createOrder("USR-001");

        // Then
        assertFalse(result.isSuccess());
        assertEquals("STOCK_SERVICE_TIMEOUT", result.getErrorCode());
    }
}

@SpringBootTest
@Testcontainers
class OrderRepositoryTest {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine")
        .withDatabaseName("testdb")
        .withUsername("test")
        .withPassword("test");

    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
    }

    @Autowired
    private OrderRepository orderRepository;

    @Test
    @DisplayName("應正確儲存並查詢訂單")
    void shouldSaveAndFindOrder() {
        // Given
        Order order = new Order("USR-001", List.of(), 2200.0, OrderStatus.PENDING);

        // When
        Order saved = orderRepository.save(order);
        Order found = orderRepository.findById(saved.getId()).orElseThrow();

        // Then
        assertEquals(saved.getId(), found.getId());
        assertEquals("USR-001", found.getUserId());
        assertEquals(2200.0, found.getTotalAmount());
    }
}

@SpringBootTest
@EmbeddedKafka(partitions = 1, topics = {"order-events"})
class OrderEventPublisherTest {

    @Autowired
    private OrderEventPublisher publisher;

    @Autowired
    private KafkaTemplate<String, String> kafkaTemplate;

    @Autowired
    private EmbeddedKafkaBroker embeddedKafka;

    @Test
    @DisplayName("訂單建立時應發布 OrderCreated 事件")
    void shouldPublishOrderCreatedEvent() throws Exception {
        // Given
        Order order = new Order("ORD-001", "USR-001", 2200.0, OrderStatus.STOCK_LOCKED);

        // When
        publisher.publishOrderCreated(order);

        // Then
        ConsumerRecord<String, String> record = KafkaTestUtils.getSingleRecord(
            consumer, "order-events", Duration.ofSeconds(5));

        assertNotNull(record);
        assertTrue(record.value().contains("ORD-001"));
        assertTrue(record.value().contains("ORDER_CREATED"));
    }
}

# Kong / Spring Cloud Gateway 路由配置
spring:
  cloud:
    gateway:
      routes:
        - id: order-service
          uri: lb://order-service
          predicates:
            - Path=/api/orders/**
          filters:
            - name: CircuitBreaker
              args:
                name: orderService
                fallbackUri: forward:/fallback/orders
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 100
                redis-rate-limiter.burstCapacity: 200

# .github/workflows/ci.yml
name: Superpowers CI Pipeline

on:
  push:
    branches: [main, 'sp/**']
  pull_request:
    branches: [main]

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:16-alpine
        env:
          POSTGRES_DB: testdb
          POSTGRES_USER: test
          POSTGRES_PASSWORD: test
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 完整歷史（用於分析 commit）

      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
          cache: maven

      # Stage 1: Build
      - name: Build
        run: mvn compile -DskipTests

      # Stage 2: Unit Tests
      - name: Run Unit Tests
        run: mvn test -Dtest='!*IntegrationTest'

      # Stage 3: Integration Tests
      - name: Run Integration Tests
        run: mvn test -Dtest='*IntegrationTest'
        env:
          SPRING_DATASOURCE_URL: jdbc:postgresql://localhost:5432/testdb
          SPRING_DATASOURCE_USERNAME: test
          SPRING_DATASOURCE_PASSWORD: test

      # Stage 4: Coverage Check
      - name: Check Test Coverage
        run: |
          mvn jacoco:report jacoco:check \
            -Djacoco.line.coverage=0.80 \
            -Djacoco.branch.coverage=0.70

      # Stage 5: SonarQube Analysis
      - name: SonarQube Scan
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
        run: |
          mvn sonar:sonar \
            -Dsonar.projectKey=${{ github.repository }} \
            -Dsonar.qualitygate.wait=true

      # Stage 6: Architecture Test (ArchUnit)
      - name: Run Architecture Tests
        run: mvn test -Dtest='*ArchitectureTest'

      # Stage 7: Superpowers TDD Compliance Check
      - name: TDD Compliance Check
        run: |
          echo "🔍 檢查 Superpowers TDD 合規性..."

          # 檢查每個 src/main 下的類別是否有對應測試
          MISSING_TESTS=0
          for file in $(find src/main/java -name "*.java" -not -name "*Config*.java" -not -name "*Application.java"); do
            CLASS_NAME=$(basename "$file" .java)
            TEST_FILE=$(find src/test/java -name "${CLASS_NAME}Test.java" 2>/dev/null)
            if [ -z "$TEST_FILE" ]; then
              echo "⚠️ 缺少測試: $file"
              MISSING_TESTS=$((MISSING_TESTS + 1))
            fi
          done

          if [ $MISSING_TESTS -gt 0 ]; then
            echo "❌ 發現 $MISSING_TESTS 個類別缺少測試"
            exit 1
          else
            echo "✅ 所有類別都有對應測試"
          fi

  # Docker Build（僅 main 分支）
  docker-build:
    needs: build-and-test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build Docker Image
        run: |
          docker build -t ${{ github.repository }}:${{ github.sha }} .
          docker tag ${{ github.repository }}:${{ github.sha }} \
                     ${{ github.repository }}:latest

# .github/workflows/tdd-check.yml
name: Superpowers TDD Gate

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  tdd-compliance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: 檢查 PR 是否包含測試
        run: |
          echo "🧪 Superpowers TDD Gate: 檢查 PR 變更..."

          # 取得 PR 中新增/修改的 Java 檔案
          CHANGED_FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD \
            | grep 'src/main/java.*\.java$' || true)

          if [ -z "$CHANGED_FILES" ]; then
            echo "ℹ️ 沒有 Java 原始碼變更，跳過檢查"
            exit 0
          fi

          echo "📝 變更的原始碼檔案："
          echo "$CHANGED_FILES"

          # 檢查是否有對應的測試檔案變更
          CHANGED_TESTS=$(git diff --name-only origin/${{ github.base_ref }}...HEAD \
            | grep 'src/test/java.*\.java$' || true)

          if [ -z "$CHANGED_TESTS" ]; then
            echo "❌ Superpowers TDD 違規：修改了原始碼但沒有新增/修改任何測試！"
            echo ""
            echo "📋 Superpowers 規範要求："
            echo "   1. 每次程式碼變更必須包含對應的測試"
            echo "   2. 測試應先於實作（Red → Green → Refactor）"
            echo ""
            echo "💡 請使用 Superpowers TDD 技能重新開發此功能。"
            exit 1
          fi

          echo "✅ PR 包含測試檔案："
          echo "$CHANGED_TESTS"

      - name: 檢查 commit 訊息格式
        run: |
          echo "📝 檢查 commit 訊息是否符合 Superpowers 規範..."

          COMMITS=$(git log --oneline origin/${{ github.base_ref }}...HEAD)
          echo "$COMMITS"

          # 檢查是否有 feat/fix/refactor 前綴
          INVALID=$(echo "$COMMITS" | grep -v -E '^[a-f0-9]+ (feat|fix|refactor|test|docs|chore)\(' || true)
          if [ -n "$INVALID" ]; then
            echo "⚠️ 以下 commit 不符合格式規範："
            echo "$INVALID"
            echo ""
            echo "💡 建議格式：feat(module): 描述"
          fi

<!-- pom.xml -->
<properties>
    <sonar.projectKey>com.tutorial:ecommerce</sonar.projectKey>
    <sonar.organization>your-org</sonar.organization>
    <sonar.host.url>https://sonarcloud.io</sonar.host.url>
    <sonar.coverage.jacoco.xmlReportPaths>
        ${project.build.directory}/site/jacoco/jacoco.xml
    </sonar.coverage.jacoco.xmlReportPaths>
    <sonar.java.coveragePlugin>jacoco</sonar.java.coveragePlugin>
</properties>

package com.tutorial.ecommerce;

import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.*;
import static com.tngtech.archunit.library.Architectures.layeredArchitecture;

@AnalyzeClasses(
    packages = "com.tutorial.ecommerce",
    importOptions = ImportOption.DoNotIncludeTests.class
)
class ArchitectureTest {

    @ArchTest
    static final ArchRule layered_architecture = layeredArchitecture()
        .consideringOnlyDependenciesInLayers()
        .layer("Controller").definedBy("..controller..")
        .layer("Service").definedBy("..service..")
        .layer("Repository").definedBy("..repository..")
        .layer("Model").definedBy("..model..")

        .whereLayer("Controller").mayNotBeAccessedByAnyLayer()
        .whereLayer("Service").mayOnlyBeAccessedByLayers("Controller")
        .whereLayer("Repository").mayOnlyBeAccessedByLayers("Service")
        .whereLayer("Model").mayOnlyBeAccessedByLayers("Service", "Repository", "Controller");

    @ArchTest
    static final ArchRule services_should_not_depend_on_controllers =
        noClasses().that().resideInAPackage("..service..")
            .should().dependOnClassesThat().resideInAPackage("..controller..");

    @ArchTest
    static final ArchRule repositories_should_be_interfaces =
        classes().that().resideInAPackage("..repository..")
            .and().haveSimpleNameEndingWith("Repository")
            .should().beInterfaces();
}

## AI 程式碼審查 Checklist

### 功能性
- [ ] 所有測試通過
- [ ] 測試覆蓋率 ≥ 80%
- [ ] 邊界條件已處理
- [ ] 錯誤場景已覆蓋

### 可維護性
- [ ] 遵循 SOLID 原則
- [ ] 方法長度合理（≤ 30 行）
- [ ] 類別職責單一
- [ ] 命名清晰有意義
- [ ] JavaDoc 完整

### 安全性
- [ ] 無 SQL Injection 風險
- [ ] 無 XSS 風險
- [ ] 敏感資料已加密
- [ ] 輸入驗證完整

### Superpowers 合規
- [ ] 有 Brainstorming 記錄
- [ ] 有微步驟計畫
- [ ] 遵循 TDD 流程（Red → Green → Refactor）
- [ ] 在 Worktree 中開發
- [ ] commit 粒度適當

# 技術債管理流程（基於 Superpowers）

## 1. 識別（使用 Brainstorming）
- SonarQube 自動掃描
- ArchUnit 架構違規報告
- Code Review 中發現的問題
- 團隊成員主動回報

## 2. 評估（使用 Writing Plans）
- 分類：設計債 / 程式碼債 / 測試債 / 文件債
- 評估影響範圍（高/中/低）
- 評估修復成本（高/中/低）
- 排定優先級

## 3. 修復（使用 TDD + Git Worktrees）
- 為每個技術債修復項目建立 Worktree
- 先補測試，再修復
- 小步提交，確保每步都可驗證

## 4. 預防
- CI 中強制品質門檻
- 每個 Sprint 預留 20% 時間處理技術債
- 定期架構審查

# .superpowers/tech-debt/TD-001.yaml
id: TD-001
title: "OrderService 缺少單元測試"
category: test-debt
severity: high
impact: high
cost: low
created: 2026-03-15
reporter: "senior-dev"
status: open  # open | in-progress | resolved
description: |
  OrderService 有 12 個公開方法，但只有 3 個有單元測試。
  核心的 createOrder() 和 cancelOrder() 完全沒有測試。
resolution_plan: |
  1. 建立 Worktree: sp/tdd/fix-order-service-tests
  2. 為 createOrder() 寫 5 個測試案例
  3. 為 cancelOrder() 寫 3 個測試案例
  4. 為其餘方法補充基本測試
estimated_effort: "4 hours"

# Debug Report: [問題標題]

## 基本資訊
- **報告日期**: 2026-03-23
- **嚴重程度**: Critical / High / Medium / Low
- **環境**: Production / Staging / Dev
- **影響範圍**: 約 15% 使用者受影響
- **Worktree**: sp/debug/[issue-name]

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

## 重現步驟
1. [步驟 1]
2. [步驟 2]
3. [觀察到的錯誤]

## 證據收集
### 錯誤日誌

### 監控指標
- CPU: 正常 / 異常
- Memory: 正常 / 異常
- DB Connection: 正常 / 異常

## 假設與驗證

| # | 假設 | 可能性 | 驗證方法 | 結果 |
|---|------|--------|---------|------|
| H1 | [假設描述] | 高/中/低 | [驗證方法] | ✅/❌/⏳ |
| H2 | [假設描述] | 高/中/低 | [驗證方法] | ✅/❌/⏳ |
| H3 | [假設描述] | 高/中/低 | [驗證方法] | ✅/❌/⏳ |

## 根因分析
[確認的根因描述]

## 修復方案
[修復程式碼或配置變更描述]

## 回歸測試
- [ ] 測試名稱：[TestClassName#testMethodName]
- [ ] 測試通過確認

## 預防措施
[如何避免類似問題再次發生]

## 知識庫更新
- [ ] 已更新團隊知識庫

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.apache.logging.log4j.ThreadContext;

/**
 * 日誌工具類別，支援結構化日誌與追蹤。
 */
public class LogHelper {

    /**
     * 設定追蹤上下文（於每個請求開始時呼叫）。
     */
    public static void setTraceContext(String correlationId, String userId) {
        ThreadContext.put("correlationId", correlationId);
        ThreadContext.put("userId", userId);
        ThreadContext.put("timestamp", java.time.Instant.now().toString());
    }

    /**
     * 清理追蹤上下文（於每個請求結束時呼叫）。
     */
    public static void clearTraceContext() {
        ThreadContext.clearAll();
    }
}

<!-- log4j2.xml — 結構化 JSON 日誌格式 -->
<Configuration status="WARN">
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <JsonTemplateLayout eventTemplateUri="classpath:LogstashJsonEventLayoutV1.json">
                <EventTemplateAdditionalField
                    key="correlationId"
                    value="${ctx:correlationId:-unknown}" />
                <EventTemplateAdditionalField
                    key="userId"
                    value="${ctx:userId:-anonymous}" />
            </JsonTemplateLayout>
        </Console>
    </Appenders>
    <Loggers>
        <Root level="INFO">
            <AppenderRef ref="Console" />
        </Root>
    </Loggers>
</Configuration>

# 檢查目前安裝的版本（Claude Code）
/plugin list | grep superpowers

# 檢查可用的最新版本
/plugin search superpowers

# 升級到最新版
/plugin update superpowers

# 安裝指定版本（企業環境建議鎖定版本）
/plugin install superpowers@5.0.5

# 檢查目前版本
cd /path/to/superpowers-clone
git describe --tags

# 檢查遠端最新版本
git fetch origin --tags
git tag --sort=-v:refname | head -5

# 升級到最新穩定版
git checkout $(git describe --tags --abbrev=0 origin/main)

# CLAUDE.md — 技能覆寫範例

## Superpowers 技能調整

### brainstorming 技能補充
- 本專案為醫療系統，brainstorming 階段必須額外包含「法規合規性」提問
- 最少提問數從 5 個提升至 8 個

### test-driven-development 技能補充  
- 本專案覆蓋率門檻為 90%（高於預設 80%）
- Integration Test 必須使用 Testcontainers

# Claude Code — 查看 Plugin 內含的技能清單與版本
/plugin info superpowers

# 手動安裝 — 查看技能定義的 frontmatter
head -5 skills/test-driven-development.md
# ---
# skill: test-driven-development
# version: 5.0.5
# triggers: ["write code", "implement", "add feature"]
# ---

# 查看最近的版本變更
# Plugin 安裝
/plugin changelog superpowers

# 手動安裝
cat RELEASE-NOTES.md | head -100

# Plugin 架構：降級至指定版本
/plugin install superpowers@5.0.4

# 手動安裝：降級至指定 tag
git checkout v5.0.4

# 驗證降級後功能正常
# 執行所有測試
mvn test

## Superpowers 測試強制規則

1. CI Pipeline 中設定覆蓋率門檻（JaCoCo ≥ 80%）
2. PR 必須包含測試檔案的變更
3. Code Review 時優先檢查測試品質
4. Pre-commit hook 阻止無測試的 commit

## Git Hook 範例

#!/bin/bash
# .git/hooks/pre-commit
# Superpowers TDD Enforcement

# 檢查是否有 src/main 的變更
MAIN_CHANGES=$(git diff --cached --name-only | grep "src/main/java" || true)

if [ -n "$MAIN_CHANGES" ]; then
    # 檢查是否有對應 src/test 的變更
    TEST_CHANGES=$(git diff --cached --name-only | grep "src/test/java" || true)

    if [ -z "$TEST_CHANGES" ]; then
        echo "❌ Superpowers TDD Violation!"
        echo "   你修改了原始碼但沒有新增/修改測試。"
        echo "   請遵循 Red → Green → Refactor 流程。"
        echo ""
        echo "   修改的檔案："
        echo "   $MAIN_CHANGES"
        echo ""
        echo "   使用 --no-verify 跳過（不建議）"
        exit 1
    fi
fi

echo "✅ Superpowers TDD Check passed"

我剛完成了以下的功能計畫，請幫我審核：

[貼上計畫內容]

請檢查以下要點：
1. 每個任務是否 ≤ 5 分鐘可完成？
2. 任務是否可獨立驗證？
3. 是否包含所有必要的測試任務？
4. 依賴關係是否正確？
5. 是否有遺漏的邊界條件或錯誤處理？

<type>(<scope>): <description>

type:
  - feat:     新功能
  - fix:      Bug 修復
  - test:     新增/修改測試
  - refactor: 重構（不改變行為）
  - docs:     文件
  - chore:    雜項（設定、建構等）

scope: 模組名稱（order, auth, stock, ...）

範例：
  test(auth): add login failure test for locked account
  feat(auth): implement account lockout after 5 failed attempts
  refactor(auth): extract password validation to PasswordPolicy
  fix(stock): resolve concurrent update deadlock with optimistic lock
  docs(api): update checkout API documentation

@AnalyzeClasses(packages = "com.tutorial.ecommerce")
class CleanArchitectureTest {

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

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

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

    @ArchTest
    static final ArchRule use_cases_should_be_suffixed =
        classes().that().resideInAPackage("..application.usecase..")
            .should().haveSimpleNameEndingWith("UseCase");
}

在實作 [功能名稱] 時，請遵循 Clean Architecture：

1. Domain Layer（先做）：
   - 定義 Entity 和 Value Object
   - 定義 Repository Interface
   - 不依賴任何外部框架

2. Application Layer（再做）：
   - 實作 Use Case
   - 只依賴 Domain Layer
   - 使用 Repository Interface（不是實作）

3. Infrastructure Layer（最後做）：
   - 實作 Repository
   - 外部 API 整合
   - 框架配置

4. Presentation Layer：
   - Controller 和 DTO
   - 輸入驗證
   - 只呼叫 Application Layer

每層都要用 TDD 開發，並用 ArchUnit 驗證依賴方向。

## ✅ 好的 Subagent 任務拆分
- 每個 Subagent 任務有明確的 scope（一個 class/module）
- 任務之間無循環依賴
- 每個任務包含完整的 TDD 循環（測試 + 實作）
- Context Isolation：Subagent 不共享會話狀態

## ❌ 不好的 Subagent 任務拆分
- 一個 Subagent 負責寫測試，另一個負責寫實作（違反 TDD）
- Subagent A 的產出是 Subagent B 的輸入（有序列依賴）
- 單個 Subagent 任務過大（> 1 小時）

Round 1: 初始規格 → Reviewer 回饋
Round 2: 修訂規格 → Reviewer 回饋
Round 3: 最終修訂 → Reviewer 強制通過或升級至人類審查

Prompt: 「幫我寫一個用戶登入的 REST API，用 Spring Boot。」

AI 直接產出 500 行程式碼，包含 Controller、Service、Repository、Entity...
→ 沒有測試
→ 沒有釐清需求細節
→ 可能有安全漏洞
→ 不符合專案架構規範

Step 1 - Brainstorming:
Prompt: 「我需要實作用戶登入功能。請使用 Superpowers Brainstorming 技能，
        先提出至少 5 個問題來釐清需求。」

Step 2 - Writing Plans:
Prompt: 「需求已釐清。請使用 Writing Plans 技能，
        將登入功能拆解成 2-5 分鐘的微任務。」

Step 3 - TDD:
Prompt: 「計畫已核准。請從任務 1.1 開始，
        先寫一個會失敗的測試。」

// AI 直接產出實作，沒有測試
public class OrderService {
    public Order createOrder(String userId, List<CartItem> items) {
        // 200 行業務邏輯...沒有任何測試
    }
}

// Step 1: 先寫測試（Red）
@Test
void shouldCreateOrderWithValidItems() {
    // Given
    // When
    OrderResult result = orderService.createOrder("USR-001", validItems);
    // Then
    assertTrue(result.isSuccess());
}

// Step 2: 再寫最少程式碼通過測試（Green）
// Step 3: 重構（Refactor）

// 到處加 print 來找問題
System.out.println("=== DEBUG 1 ===");
System.out.println("order: " + order);
System.out.println("=== DEBUG 2 ===");
System.out.println("items: " + items);
// 試了 3 小時，隨機改了幾個地方，問題「好像」解決了

1. 問題重現：明確記錄重現步驟與頻率
2. 假設建立：
   - H1: 購物車金額計算有浮點數精度問題（可能性：高）
   - H2: 並發下單導致資料不一致（可能性：中）
   - H3: 第三方 API 偶發超時（可能性：低）
3. 驗證 H1：用 BigDecimal 替換 double，執行測試 → 問題解決 ✅
4. 撰寫回歸測試確認

計畫完成 → 直接開始 TDD → 做到一半發現需求理解錯誤 → 砍掉重來

計畫完成 → Document Review（最多 3 輪）→ 通過 → 開始 TDD

Subagent A: 寫所有測試
Subagent B: 寫所有實作
→ 違反 TDD（測試與實作分離）
→ Subagent B 不了解測試的意圖

Subagent A: Module A 的完整 TDD（測試 + 實作 + 重構）
Subagent B: Module B 的完整 TDD（測試 + 實作 + 重構）
→ 各自獨立、Context Isolation
→ Two-Stage Review 分別審查

1. Superpowers 概述（20 min）
   - 核心理念與價值（TDD first, Systematic over ad-hoc, Complexity reduction, Evidence over claims）
   - 14+ 技能簡介與 7-Step Basic Workflow

2. 實作示範（40 min）
   - 完整走過一個小功能的 Superpowers 流程
   - 展示 Brainstorming → Document Review → Planning → TDD → Two-Stage Review → Finish

3. 動手練習（40 min）
   - 每人用 Superpowers 實作一個小功能
   - 導師即時指導

4. Q&A + 規範說明（20 min）
   - 回答問題
   - 說明平台選擇（Claude Code / Cursor / Codex / OpenCode / Gemini CLI）
   - 說明接下來的試點計畫

## 試點專案執行計畫

### 週一：使用 Brainstorming 釐清試點功能需求
- 每位成員獨立使用 Brainstorming 提問
- 彙整所有問題，與 PM 確認

### 週二-週四：使用 Writing Plans + TDD 開發
- 每日站立會議回報 Superpowers 使用狀況
- Tech Lead 審核每個 PR 的 Superpowers 合規性

### 週五：回顧
- 收集團隊回饋
- 記錄問題與改善建議
- 更新 Superpowers 配置（如有需要）

# 團隊 AI 使用政策 v2.0（Superpowers v5.0.5）

## 1. 適用範圍
本政策適用於使用 AI 工具（Claude Code、Cursor、Codex CLI、OpenCode、Gemini CLI 等）進行開發的所有團隊成員。

## 2. 強制規則
- 2.1 所有 AI 輔助開發必須遵循 Superpowers 7-Step Basic Workflow
- 2.2 AI 產出的程式碼必須有完整的測試（TDD first）
- 2.3 AI 產出不得直接上生產環境，必須經過 Two-Stage Code Review
- 2.4 敏感資訊（密鑰、客戶資料）不得輸入 AI 工具
- 2.5 所有平台必須安裝 Superpowers Plugin 並鎖定統一版本

## 3. 品質標準
- 3.1 測試覆蓋率 ≥ 80%
- 3.2 SonarQube 品質門檻必須通過
- 3.3 ArchUnit 架構測試必須通過
- 3.4 每個 PR 必須通過 Two-Stage Review（Spec Compliance + Code Quality）
- 3.5 Document Review 不超過 3 輪

## 4. 安全規範
- 4.1 不得將公司內部程式碼上傳到公共 AI 服務
- 4.2 使用企業版 AI 工具（如有）
- 4.3 AI 產出的程式碼必須通過安全掃描
- 4.4 定期檢查 AI 工具的資料處理政策

## 5. 責任歸屬
- 5.1 最終程式碼品質由開發者負責，不是 AI
- 5.2 Code Reviewer 同樣需要對 AI 產出進行嚴格審查
- 5.3 違反政策將在績效回顧中記錄

## 6. 例外處理
- 6.1 緊急修復可跳過 Brainstorming（事後補文件）
- 6.2 PoC 專案可降低測試覆蓋率要求至 50%

## Superpowers Code Review Checklist（v5.0.5）

### 📋 流程合規（必查）
- [ ] 有 Brainstorming 記錄或需求文件參考
- [ ] 有微步驟計畫（Writing Plans）且通過 Document Review
- [ ] commit 歷史顯示 TDD 流程（test → impl → refactor）
- [ ] 在 Worktree 分支上開發（`sp/*` 前綴）

### 🧪 測試品質（必查）
- [ ] 新增測試覆蓋所有公開方法
- [ ] 包含正常路徑測試
- [ ] 包含錯誤路徑測試
- [ ] 包含邊界條件測試
- [ ] 測試命名清晰描述行為
- [ ] 使用 AAA（Arrange-Act-Assert）模式
- [ ] 無 `testing-anti-patterns.md` 中列舉的反模式

### 🏗️ 程式碼品質（必查）
- [ ] 遵循 SOLID 原則
- [ ] 方法長度合理（≤ 30 行）
- [ ] 類別職責單一
- [ ] 命名有意義且一致
- [ ] 無硬編碼的設定值

### 🔒 安全性（必查）
- [ ] 無 SQL Injection 風險
- [ ] 輸入驗證完整
- [ ] 敏感資料不在日誌中
- [ ] 權限檢查到位

### 📝 文件（建議）
- [ ] JavaDoc 完整
- [ ] API 文件已更新
- [ ] README 已更新（如有）

### 💡 Two-Stage Review 簽名
- Stage 1 Spec Compliance：[ ] 通過 — by @reviewer1
- Stage 2 Code Quality：[ ] 通過 — by @reviewer2

## Superpowers 培訓計畫

### 新人（第 1 週）
- 閱讀本教學手冊第 1-4 章
- 安裝 Superpowers Plugin（Plugin Marketplace 或手動）
- 完成 1 個小功能的 Superpowers 全流程（7-Step Basic Workflow）
- 由 Mentor 提供一對一指導

### 一般成員（每季）
- 回顧最佳實務與反模式（第 10-11 章）
- 分享個人的 Prompt 技巧與 Subagent 使用經驗
- 檢查是否有新版本可升級（RELEASE-NOTES.md）
- 更新團隊的 CLAUDE.md / .cursorrules 配置

### Tech Lead（每月）
- 審查品質指標趨勢
- 評估新版本功能（如 Visual Companion、Context Isolation 等）
- 更新 Superpowers Plugin 版本（鎖定版本策略）
- 撰寫改善提案

bank-transfer-service/
├── CLAUDE.md                          # Superpowers 專案配置（Plugin 自動讀取）
├── .cursorrules                       # Cursor 平台配置（如使用 Cursor）
├── .github/
│   ├── copilot-instructions.md        # GitHub Copilot 方法論注入
│   └── workflows/
│       ├── ci.yml
│       └── tdd-check.yml
├── docs/
│   └── plans/
│       └── transfer-feature-plan.md   # Document Review 通過的計畫
├── src/
│   ├── main/java/com/bank/transfer/
│   │   ├── TransferApplication.java
│   │   ├── domain/
│   │   │   ├── model/
│   │   │   │   ├── Account.java
│   │   │   │   ├── TransferRequest.java
│   │   │   │   └── TransferResult.java
│   │   │   ├── repository/
│   │   │   │   └── AccountRepository.java
│   │   │   └── service/
│   │   │       └── TransferDomainService.java
│   │   ├── application/
│   │   │   └── usecase/
│   │   │       └── TransferUseCase.java
│   │   ├── infrastructure/
│   │   │   ├── persistence/
│   │   │   │   └── JpaAccountRepository.java
│   │   │   └── config/
│   │   │       └── AppConfig.java
│   │   └── presentation/
│   │       ├── controller/
│   │       │   └── TransferController.java
│   │       └── dto/
│   │           ├── TransferRequestDto.java
│   │           └── TransferResponseDto.java
│   └── test/java/com/bank/transfer/
│       ├── domain/
│       │   ├── model/
│       │   │   └── AccountTest.java
│       │   └── service/
│       │       └── TransferDomainServiceTest.java
│       ├── application/
│       │   └── usecase/
│       │       └── TransferUseCaseTest.java
│       ├── infrastructure/
│       │   └── persistence/
│       │       └── JpaAccountRepositoryTest.java
│       ├── presentation/
│       │   └── controller/
│       │       └── TransferControllerTest.java
│       └── architecture/
│           └── ArchitectureTest.java
└── pom.xml

package com.bank.transfer.domain.model;

import java.math.BigDecimal;
import java.util.Objects;

/**
 * 銀行帳戶領域模型。
 * 封裝帳戶業務邏輯，不依賴任何外部框架。
 */
public class Account {

    private final String accountId;
    private BigDecimal balance;

    public Account(String accountId, BigDecimal balance) {
        Objects.requireNonNull(accountId, "帳戶 ID 不可為 null");
        Objects.requireNonNull(balance, "餘額不可為 null");
        if (balance.compareTo(BigDecimal.ZERO) < 0) {
            throw new IllegalArgumentException("初始餘額不可為負數");
        }
        this.accountId = accountId;
        this.balance = balance;
    }

    /**
     * 扣款。
     *
     * @param amount 扣款金額（必須 > 0）
     * @throws IllegalArgumentException 金額無效或餘額不足
     */
    public void debit(BigDecimal amount) {
        validatePositiveAmount(amount);
        if (this.balance.compareTo(amount) < 0) {
            throw new IllegalArgumentException(
                String.format("餘額不足：目前 %s，需要 %s", this.balance, amount));
        }
        this.balance = this.balance.subtract(amount);
    }

    /**
     * 入款。
     *
     * @param amount 入款金額（必須 > 0）
     */
    public void credit(BigDecimal amount) {
        validatePositiveAmount(amount);
        this.balance = this.balance.add(amount);
    }

    private void validatePositiveAmount(BigDecimal amount) {
        if (amount == null || amount.compareTo(BigDecimal.ZERO) <= 0) {
            throw new IllegalArgumentException("金額必須大於零");
        }
    }

    public String getAccountId() { return accountId; }
    public BigDecimal getBalance() { return balance; }
}

package com.bank.transfer.domain.repository;

import com.bank.transfer.domain.model.Account;
import java.util.Optional;

/**
 * 帳戶 Repository 介面（Domain Layer 定義，Infrastructure 實作）。
 */
public interface AccountRepository {
    Optional<Account> findById(String accountId);
    Account save(Account account);
}

package com.bank.transfer.domain.service;

import com.bank.transfer.domain.model.Account;
import com.bank.transfer.domain.model.TransferResult;

import java.math.BigDecimal;

/**
 * 轉帳領域服務。
 * 處理跨帳戶的業務邏輯。
 */
public class TransferDomainService {

    /**
     * 執行轉帳。
     */
    public TransferResult execute(Account source, Account target, BigDecimal amount) {
        if (source.getAccountId().equals(target.getAccountId())) {
            return TransferResult.failure("SELF_TRANSFER", "不可轉帳給自己");
        }

        try {
            source.debit(amount);
            target.credit(amount);
            return TransferResult.success(
                source.getAccountId(), target.getAccountId(), amount);
        } catch (IllegalArgumentException e) {
            return TransferResult.failure("TRANSFER_FAILED", e.getMessage());
        }
    }
}

package com.bank.transfer.application.usecase;

import com.bank.transfer.domain.model.Account;
import com.bank.transfer.domain.model.TransferResult;
import com.bank.transfer.domain.repository.AccountRepository;
import com.bank.transfer.domain.service.TransferDomainService;

import java.math.BigDecimal;

/**
 * 轉帳 Use Case。
 * 編排領域服務與 Repository 完成轉帳業務流程。
 */
public class TransferUseCase {

    private final AccountRepository accountRepository;
    private final TransferDomainService transferDomainService;

    public TransferUseCase(AccountRepository accountRepository,
                           TransferDomainService transferDomainService) {
        this.accountRepository = accountRepository;
        this.transferDomainService = transferDomainService;
    }

    /**
     * 執行帳戶間轉帳。
     *
     * @param sourceAccountId 來源帳戶 ID
     * @param targetAccountId 目標帳戶 ID
     * @param amount 轉帳金額
     * @return 轉帳結果
     */
    public TransferResult execute(String sourceAccountId, String targetAccountId,
                                  BigDecimal amount) {
        Account source = accountRepository.findById(sourceAccountId)
            .orElseThrow(() -> new IllegalArgumentException(
                "來源帳戶不存在：" + sourceAccountId));

        Account target = accountRepository.findById(targetAccountId)
            .orElseThrow(() -> new IllegalArgumentException(
                "目標帳戶不存在：" + targetAccountId));

        TransferResult result = transferDomainService.execute(source, target, amount);

        if (result.isSuccess()) {
            accountRepository.save(source);
            accountRepository.save(target);
        }

        return result;
    }
}

package com.bank.transfer.presentation.controller;

import com.bank.transfer.application.usecase.TransferUseCase;
import com.bank.transfer.domain.model.TransferResult;
import com.bank.transfer.presentation.dto.TransferRequestDto;
import com.bank.transfer.presentation.dto.TransferResponseDto;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import jakarta.validation.Valid;

/**
 * 轉帳 API Controller。
 */
@RestController
@RequestMapping("/api/transfers")
public class TransferController {

    private final TransferUseCase transferUseCase;

    public TransferController(TransferUseCase transferUseCase) {
        this.transferUseCase = transferUseCase;
    }

    @PostMapping
    public ResponseEntity<TransferResponseDto> transfer(
            @Valid @RequestBody TransferRequestDto request) {

        TransferResult result = transferUseCase.execute(
            request.getSourceAccountId(),
            request.getTargetAccountId(),
            request.getAmount()
        );

        TransferResponseDto response = TransferResponseDto.from(result);

        if (result.isSuccess()) {
            return ResponseEntity.ok(response);
        } else {
            return ResponseEntity.badRequest().body(response);
        }
    }
}

package com.bank.transfer.domain.model;

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.DisplayName;
import java.math.BigDecimal;

import static org.junit.jupiter.api.Assertions.*;

class AccountTest {

    @Test
    @DisplayName("建立帳戶：初始餘額正確")
    void shouldCreateAccountWithBalance() {
        Account account = new Account("ACC-001", new BigDecimal("10000.00"));
        assertEquals("ACC-001", account.getAccountId());
        assertEquals(new BigDecimal("10000.00"), account.getBalance());
    }

    @Test
    @DisplayName("扣款：餘額正確減少")
    void shouldDebitCorrectly() {
        Account account = new Account("ACC-001", new BigDecimal("10000.00"));
        account.debit(new BigDecimal("3000.00"));
        assertEquals(new BigDecimal("7000.00"), account.getBalance());
    }

    @Test
    @DisplayName("扣款：餘額不足應拋出例外")
    void shouldThrowWhenInsufficientBalance() {
        Account account = new Account("ACC-001", new BigDecimal("1000.00"));
        assertThrows(IllegalArgumentException.class,
            () -> account.debit(new BigDecimal("5000.00")));
    }

    @Test
    @DisplayName("入款：餘額正確增加")
    void shouldCreditCorrectly() {
        Account account = new Account("ACC-001", new BigDecimal("5000.00"));
        account.credit(new BigDecimal("2000.00"));
        assertEquals(new BigDecimal("7000.00"), account.getBalance());
    }

    @Test
    @DisplayName("金額為零或負數時應拋出例外")
    void shouldRejectNonPositiveAmount() {
        Account account = new Account("ACC-001", new BigDecimal("10000.00"));
        assertAll(
            () -> assertThrows(IllegalArgumentException.class,
                () -> account.debit(BigDecimal.ZERO)),
            () -> assertThrows(IllegalArgumentException.class,
                () -> account.debit(new BigDecimal("-100"))),
            () -> assertThrows(IllegalArgumentException.class,
                () -> account.credit(BigDecimal.ZERO))
        );
    }

    @Test
    @DisplayName("初始餘額不可為負數")
    void shouldRejectNegativeInitialBalance() {
        assertThrows(IllegalArgumentException.class,
            () -> new Account("ACC-001", new BigDecimal("-1000")));
    }
}

package com.bank.transfer.application.usecase;

import com.bank.transfer.domain.model.Account;
import com.bank.transfer.domain.model.TransferResult;
import com.bank.transfer.domain.repository.AccountRepository;
import com.bank.transfer.domain.service.TransferDomainService;

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.Spy;
import org.mockito.junit.jupiter.MockitoExtension;

import java.math.BigDecimal;
import java.util.Optional;

import static org.junit.jupiter.api.Assertions.*;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.*;

@ExtendWith(MockitoExtension.class)
class TransferUseCaseTest {

    @Mock
    private AccountRepository accountRepository;

    @Spy
    private TransferDomainService transferDomainService = new TransferDomainService();

    @InjectMocks
    private TransferUseCase transferUseCase;

    private Account sourceAccount;
    private Account targetAccount;

    @BeforeEach
    void setUp() {
        sourceAccount = new Account("ACC-001", new BigDecimal("10000.00"));
        targetAccount = new Account("ACC-002", new BigDecimal("5000.00"));
    }

    @Test
    @DisplayName("正常轉帳：雙方帳戶餘額正確更新")
    void shouldTransferSuccessfully() {
        // Given
        when(accountRepository.findById("ACC-001")).thenReturn(Optional.of(sourceAccount));
        when(accountRepository.findById("ACC-002")).thenReturn(Optional.of(targetAccount));
        when(accountRepository.save(any())).thenAnswer(i -> i.getArgument(0));

        // When
        TransferResult result = transferUseCase.execute(
            "ACC-001", "ACC-002", new BigDecimal("3000.00"));

        // Then
        assertTrue(result.isSuccess());
        assertEquals(new BigDecimal("7000.00"), sourceAccount.getBalance());
        assertEquals(new BigDecimal("8000.00"), targetAccount.getBalance());
        verify(accountRepository, times(2)).save(any());
    }

    @Test
    @DisplayName("來源帳戶不存在時應拋出例外")
    void shouldThrowWhenSourceNotFound() {
        when(accountRepository.findById("ACC-999")).thenReturn(Optional.empty());

        assertThrows(IllegalArgumentException.class,
            () -> transferUseCase.execute(
                "ACC-999", "ACC-002", new BigDecimal("1000.00")));
    }

    @Test
    @DisplayName("餘額不足時不應更新帳戶")
    void shouldNotSaveWhenTransferFails() {
        // Given
        when(accountRepository.findById("ACC-001")).thenReturn(Optional.of(sourceAccount));
        when(accountRepository.findById("ACC-002")).thenReturn(Optional.of(targetAccount));

        // When
        TransferResult result = transferUseCase.execute(
            "ACC-001", "ACC-002", new BigDecimal("50000.00"));

        // Then
        assertFalse(result.isSuccess());
        verify(accountRepository, never()).save(any());
    }
}

package com.bank.transfer.architecture;

import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;

@AnalyzeClasses(
    packages = "com.bank.transfer",
    importOptions = ImportOption.DoNotIncludeTests.class
)
class ArchitectureTest {

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

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

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

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

    @ArchTest
    static final ArchRule application_should_not_depend_on_presentation =
        noClasses().that().resideInAPackage("..application..")
            .should().dependOnClassesThat().resideInAPackage("..presentation..");

    @ArchTest
    static final ArchRule domain_should_not_use_spring_annotations =
        noClasses().that().resideInAPackage("..domain..")
            .should().dependOnClassesThat()
            .resideInAnyPackage("org.springframework..");
}

$ git log --oneline

f8a2c31 docs(api): update transfer API documentation
e92d4f0 chore(sp): finishing-a-development-branch — merge sp/tdd/transfer
d91b4e7 test(arch): add Clean Architecture compliance tests
c23e5f0 refactor(transfer): extract validation to domain service
b17d3a2 feat(transfer): implement TransferController
a09c8f4 test(transfer): add TransferController integration tests
9e8b7d6 feat(transfer): implement TransferUseCase
8d7c6b5 test(transfer): add TransferUseCase unit tests
7c6b5a4 feat(domain): implement TransferDomainService
6b5a493 test(domain): add TransferDomainService tests
5a49382 feat(domain): implement Account entity
4938271 test(domain): add Account unit tests (6 cases)
3827160 feat(domain): define AccountRepository interface
2716049 docs(plan): transfer feature plan (Document Review passed)
1604938 chore(project): initialize Spring Boot project + CLAUDE.md

# Planner Agent 設定

## 角色
你是專案規劃師，負責需求釐清與任務拆解。

## 使用的 Superpowers 技能
- Brainstorming（主要）
- Writing Plans（主要）

## 規則
1. 收到需求後，先執行 Brainstorming
2. 釐清需求後，產出微步驟計畫
3. 計畫必須包含 TDD 測試任務
4. 每個任務不超過 5 分鐘
5. 你不能寫任何程式碼

## 輸出格式
- 需求文件（Markdown）
- 微步驟計畫（含時間估算）

# Developer Agent 設定

## 角色
你是資深開發者，負責按照計畫使用 TDD 實作功能。

## 使用的 Superpowers 技能
- TDD（主要）
- Git Worktrees（主要）

## 規則
1. 嚴格按照計畫中的任務順序執行
2. 每個功能必須先寫失敗的測試
3. 每完成一個 Red-Green-Refactor 循環就 commit
4. 不能跳過任何計畫步驟
5. 遇到計畫不清楚的地方，請求 Planner Agent 釐清

## 輸出格式
- 程式碼 commit
- 測試報告

# Tester Agent 設定

## 角色
你是品質保證工程師，負責審查測試品質與設計額外測試。

## 使用的 Superpowers 技能
- TDD（主要 — 審查角度）

## 規則
1. 審查 Developer Agent 產出的測試是否充分
2. 識別遺漏的邊界條件與錯誤場景
3. 設計整合測試與效能測試
4. 確認覆蓋率達標（≥ 80%）
5. 發現品質問題時，寫 Bug Report 交回 Developer Agent

## 輸出格式
- 測試審查報告
- 額外測試案例
- 覆蓋率報告

// .mcp/superpowers-server.json
{
  "name": "superpowers",
  "version": "1.0.0",
  "description": "Superpowers Engineering Discipline MCP Server",
  "tools": [
    {
      "name": "brainstorming_start",
      "description": "啟動 Superpowers Brainstorming 技能，進行蘇格拉底式提問",
      "parameters": {
        "feature_description": {
          "type": "string",
          "description": "功能需求描述"
        },
        "min_questions": {
          "type": "integer",
          "default": 5,
          "description": "最少提問數量"
        }
      }
    },
    {
      "name": "tdd_start",
      "description": "啟動 Superpowers TDD 技能，開始 Red-Green-Refactor 循環",
      "parameters": {
        "feature_name": {
          "type": "string",
          "description": "功能名稱"
        },
        "language": {
          "type": "string",
          "enum": ["java", "python", "typescript"],
          "description": "程式語言"
        }
      }
    },
    {
      "name": "plan_create",
      "description": "建立 Superpowers 微步驟計畫",
      "parameters": {
        "feature_name": {
          "type": "string",
          "description": "功能名稱"
        },
        "max_task_duration": {
          "type": "string",
          "default": "5m",
          "description": "每個任務最長時間"
        }
      }
    },
    {
      "name": "debug_start",
      "description": "啟動 Superpowers Systematic Debugging",
      "parameters": {
        "issue_description": {
          "type": "string",
          "description": "問題描述"
        },
        "severity": {
          "type": "string",
          "enum": ["critical", "high", "medium", "low"]
        }
      }
    },
    {
      "name": "worktree_create",
      "description": "建立 Git Worktree",
      "parameters": {
        "skill": {
          "type": "string",
          "enum": ["tdd", "debug", "experiment", "refactor"]
        },
        "feature_name": {
          "type": "string",
          "description": "功能或修復名稱"
        }
      }
    }
  ],
  "resources": [
    {
      "name": "superpowers_config",
      "description": "讀取 Superpowers 項目配置",
      "uri": "file://.superpowers/config.yaml"
    },
    {
      "name": "active_plans",
      "description": "讀取目前有效的開發計畫",
      "uri": "file://.superpowers/plans/"
    }
  ]
}

在 Claude Code 中，Agent 透過 MCP 呼叫 Superpowers：

User: 「我需要實作密碼重設功能」

Agent 內部流程：
1. MCP call: brainstorming_start(feature_description="密碼重設功能")
   → 回傳 5 個提問
2. User 回答後
3. MCP call: plan_create(feature_name="password-reset")
   → 回傳微步驟計畫
4. User 核准後
5. MCP call: worktree_create(skill="tdd", feature_name="password-reset")
   → 建立 sp/tdd/password-reset Worktree
6. MCP call: tdd_start(feature_name="password-reset", language="java")
   → 開始 TDD 循環

## 🔧 環境建置（第一天完成）

### 基本工具
- [ ] 安裝 Git（≥ 2.20）並確認 `git worktree` 可用
- [ ] 安裝 Java JDK 21
- [ ] 安裝 Maven
- [ ] 安裝 VS Code + Java Extension Pack

### AI 平台（擇一或多選）
- [ ] Claude Code + Superpowers Plugin（`/plugin install superpowers@claude-plugins-official`）
- [ ] Cursor + Superpowers Plugin（`/add-plugin superpowers`）
- [ ] Codex CLI + AGENTS.md 配置
- [ ] OpenCode + Superpowers（`opencode plugin install superpowers`）
- [ ] Gemini CLI + Extension 安裝
- [ ] GitHub Copilot（方法論注入至 `copilot-instructions.md`）

### Superpowers 設定
- [ ] 確認 Superpowers Plugin 安裝成功（`/plugin list | grep superpowers`）
- [ ] 閱讀 `CLAUDE.md` 或 `.cursorrules`（專案配置）
- [ ] 閱讀 `.github/copilot-instructions.md`（如使用 Copilot）
- [ ] 確認 Superpowers Plugin 版本與團隊一致（鎖定版本）
- [ ] 測試 Git Worktree 建立/移除

### 驗證
- [ ] 執行 `mvn test` 確認所有測試通過
- [ ] 用 Superpowers 完成一個小練習（見 C.4）

## 📚 學習路徑（第一週完成）

### Day 1：概念理解
- [ ] 閱讀本手冊第 1 章（Superpowers 概述 — 定位、哲學、多平台支援）
- [ ] 閱讀本手冊第 2 章（系統架構 — Plugin 架構、Hooks 系統）
- [ ] 了解 14+ 技能與 7-Step Basic Workflow

### Day 2：環境與安裝
- [ ] 閱讀本手冊第 3 章（安裝與環境建置 — Plugin Marketplace）
- [ ] 完成 C.1 環境建置清單

### Day 3-4：核心技能
- [ ] 閱讀本手冊第 4 章（核心 Skills 詳解）
- [ ] 重點深入理解 TDD、Brainstorming、Subagent-Driven Development
- [ ] 用 TDD 完成一個小練習

### Day 5：實戰流程
- [ ] 閱讀本手冊第 5 章（實戰開發流程）
- [ ] 用 Superpowers 7-Step Workflow 完整開發一個小功能
- [ ] 與 Mentor 進行 Two-Stage Code Review

## 📋 日常開發 Checklist（每個功能必做）

### 開始前
- [ ] 需求是否清楚？（是否需要 Brainstorming？— Hard Gates 會強制）
- [ ] 計畫是否已制定並通過 Document Review？（Writing Plans + Review Loop）
- [ ] 計畫是否已被 Tech Lead 核准？
- [ ] 是否已建立 Git Worktree？（`sp/` 前綴，v4.2.0+ 強制）

### 開發中
- [ ] 是否遵循 TDD？（先寫測試→後寫實作→最後重構）
- [ ] 每個 Red-Green-Refactor 循環是否有 commit？
- [ ] commit 訊息是否符合規範？（type(scope): description）
- [ ] 遇到問題是否使用 Systematic Debugging？
- [ ] 大型功能是否使用 Subagent-Driven Development？

### 完成後
- [ ] 所有測試是否通過？
- [ ] 測試覆蓋率是否 ≥ 80%？
- [ ] ArchUnit 架構測試是否通過？
- [ ] Two-Stage Code Review 是否通過？（Spec Compliance + Code Quality）
- [ ] 是否使用 `finishing-a-development-branch` 技能完成合併？
- [ ] 是否清理了 Git Worktree？

需求：建立一個 Calculator 類別，支援加減乘除。

步驟（7-Step Basic Workflow）：
1. 使用 Brainstorming 提出 3 個問題（例：是否支援小數？溢位處理？）
2. 使用 Writing Plans 拆解成 4-6 個微任務
3. 通過 Document Review（至少 1 輪）
4. 建立 Git Worktree: sp/tdd/calculator
5. 用 TDD 完成每個任務
6. 使用 Two-Stage Review 審查
7. 使用 finishing-a-development-branch 合併回 main 並清理 Worktree

給定一段有 Bug 的程式碼（由 Mentor 準備），使用 Systematic Debugging 四階段：
1. 重現問題
2. 建立至少 2 個假設
3. 驗證假設
4. 修復並撰寫回歸測試