傳統開發：Feature₁ → Debt₁ → Feature₂ → Debt₂ → ... → 越來越難
複利工程：Feature₁ → Learn₁ → Feature₂ → Learn₂ → ... → 越來越快

project-root/
├── CLAUDE.md              # 專案整體規範（Agent 自動讀取）
├── AGENTS.md              # Agent 行為規範
├── .claude/
│   ├── commands/          # 自訂斜線指令
│   └── settings.json      # Claude Code 設定
├── docs/
│   └── learnings/         # CE Compound 產出的知識
│       ├── 2026-04-01-api-pagination.md
│       ├── 2026-04-05-cache-invalidation.md
│       └── 2026-04-10-auth-jwt-refresh.md
└── .github/
    └── compound/          # 團隊級知識
        ├── patterns/      # 已驗證的設計模式
        ├── anti-patterns/  # 已知反模式
        └── decisions/      # 架構決策記錄

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

# Windows (PowerShell)
winget install Anthropic.ClaudeCode

# 驗證安裝
claude --version

# 在 Claude Code 中執行
/plugin marketplace add EveryInc/compound-engineering-plugin
/plugin install compound-engineering

# 使用 bunx（無需全域安裝）
bunx @every-env/compound-plugin install compound-engineering

# 在 Claude Code 中輸入
/ce-setup

# 在 Cursor 中執行
/add-plugin compound-engineering

# Codex
bunx @every-env/compound-plugin install compound-engineering --to codex

# GitHub Copilot
bunx @every-env/compound-plugin install compound-engineering --to copilot

# OpenCode
bunx @every-env/compound-plugin install compound-engineering --to opencode

# Factory Droid
bunx @every-env/compound-plugin install compound-engineering --to droid

# Pi
bunx @every-env/compound-plugin install compound-engineering --to pi

# Gemini CLI
bunx @every-env/compound-plugin install compound-engineering --to gemini

# Kiro CLI
bunx @every-env/compound-plugin install compound-engineering --to kiro

# Windsurf
bunx @every-env/compound-plugin install compound-engineering --to windsurf

# Windsurf（Workspace 範圍）
bunx @every-env/compound-plugin install compound-engineering --to windsurf --scope workspace

# OpenClaw
bunx @every-env/compound-plugin install compound-engineering --to openclaw

# Qwen Code
bunx @every-env/compound-plugin install compound-engineering --to qwen

# 自動偵測並安裝至所有已安裝工具
bunx @every-env/compound-plugin install compound-engineering --to all

/ce-setup

✅ Node.js v22.0.0
✅ Git v2.45.0
✅ gh v2.50.0
✅ jq v1.7
✅ Project config bootstrapped
✅ CLAUDE.md created with recommended defaults
🎉 Setup complete! Run /ce:brainstorm to get started.

# 1. 安裝 Bun（Windows）
powershell -c "irm bun.sh/install.ps1 | iex"

# 2. 安裝 GitHub CLI
winget install GitHub.cli

# 3. 安裝 jq
winget install jqlang.jq

# 4. 設定 PATH（將以下加入系統環境變數）
$env:PATH += ";$env:USERPROFILE\.bun\bin"

# 5. 安裝 Compound Engineering Plugin
bunx @every-env/compound-plugin install compound-engineering

# 6. Claude Code 中執行初始化
# /ce-setup

# .github/workflows/ce-review.yml
name: CE Auto Review
on:
  pull_request:
    types: [opened, synchronize]

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

      - uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install Bun
        uses: oven-sh/setup-bun@v2

      - name: Install CE Plugin
        run: bunx @every-env/compound-plugin install compound-engineering

      - name: Run CE Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude --plugin-dir ./plugins/compound-engineering \
            -m "Please review this PR using /ce:review"

# 同步到所有偵測到的工具（預設）
bunx @every-env/compound-plugin sync

# 同步到特定工具
bunx @every-env/compound-plugin sync --target opencode
bunx @every-env/compound-plugin sync --target codex
bunx @every-env/compound-plugin sync --target copilot
bunx @every-env/compound-plugin sync --target gemini
bunx @every-env/compound-plugin sync --target windsurf
bunx @every-env/compound-plugin sync --target kiro
bunx @every-env/compound-plugin sync --target qwen
bunx @every-env/compound-plugin sync --target pi
bunx @every-env/compound-plugin sync --target droid
bunx @every-env/compound-plugin sync --target openclaw

# 同步到所有工具（明確指定）
bunx @every-env/compound-plugin sync --target all

# 基本用法
/ce:ideate

# 帶方向的探索
/ce:ideate "效能優化方向"
/ce:ideate "安全性改善"

# 開始腦力激盪
/ce:brainstorm "客戶需要一個帳戶管理功能"

# 帶更多上下文
/ce:brainstorm "需要支援 JWT 認證的 REST API，包含登入、登出、Token 更新"

/ce:brainstorm "我們的銀行帳戶系統需要新增轉帳功能。
需求：
- 支援即時轉帳與預約轉帳
- 需要雙因素驗證（2FA）
- 單日轉帳上限為 500 萬
- 需要與現有的 Spring Boot 帳戶服務整合
- 前端使用 Vue 3
技術約束：
- 必須通過安全審查
- 需要完整的審計日誌
- 效能要求：< 3秒完成轉帳"

# 接續 brainstorm 的結果
/ce:plan

# 直接給定詳細想法
/ce:plan "實作 Spring Boot REST API，支援 CRUD 操作
- Controller: TransferController
- Service: TransferService
- Repository: TransferRepository
- 使用 JPA + Oracle
- 需要 input validation
- 需要 integration test"

# 實作計畫：轉帳功能 API

## 目標
實作銀行轉帳 REST API，支援即時與預約轉帳

## 架構設計
- Controller Layer: TransferController (REST endpoints)
- Service Layer: TransferService (業務邏輯 + 2FA 驗證)
- Repository Layer: TransferRepository (JPA + Oracle)
- Event Layer: TransferEventPublisher (審計日誌)

## 任務清單
1. [ ] 建立 Transfer entity 與 DB migration
2. [ ] 實作 TransferRepository
3. [ ] 實作 TransferService（含 2FA 驗證邏輯）
4. [ ] 實作 TransferController（含 input validation）
5. [ ] 實作 TransferEventPublisher（審計日誌）
6. [ ] 撰寫 Unit Tests
7. [ ] 撰寫 Integration Tests
8. [ ] 更新 API 文件

## 參考來源
- 現有 AccountService 的分層架構
- learnings/2026-03-15-oracle-jpa-performance.md
- Spring Security 2FA best practices

## 成功標準
- 所有測試通過
- API 回應時間 < 3 秒
- 通過 security-reviewer 審查

# 執行 Plan 中的任務
/ce:work

# 指定特定任務
/ce:work "開始執行任務 1-3"

# 1. 先確保 Plan 已完成
/ce:plan "實作用戶管理 CRUD API"

# 2. 開始執行
/ce:work

# Agent 會自動：
# - 建立 Git worktree (feature/user-crud-api)
# - 依序建立 Entity → Repository → Service → Controller
# - 每步驟後自動編譯確認
# - 產出對應的測試

# 管理 Git worktree
git-worktree

# 清理已合併的分支
git-clean-gone-branches

# 審查當前變更
/ce:review

# 審查特定 PR
/ce:review "review PR #42"

# 記錄本次學習
/ce:compound

# 指定重點
/ce:compound "記錄 Oracle JPA 批次操作的效能最佳化方法"

# Learning: Oracle JPA 批次操作效能最佳化

## 問題
使用 `saveAll()` 批次寫入 1000 筆轉帳記錄時，耗時超過 30 秒。

## 根因
JPA 預設逐筆 INSERT，未啟用 JDBC batch。

## 解決方案
1. 在 `application.yml` 設定 `spring.jpa.properties.hibernate.jdbc.batch_size=50`
2. 使用 `@Modifying` + native query 進行批次操作
3. 關閉 `hibernate.order_inserts=true` 讓 Hibernate 重排 INSERT 順序

## 驗證
- 批次寫入 1000 筆：30s → 2s
- 使用 `p6spy` 確認只產生 20 個 batch INSERT

## 適用場景
所有需要批次寫入 Oracle 的 Service

# 刷新過時的知識
/ce:compound-refresh

# 系統性除錯
/ce-debug "TransferService.execute() 在高併發下回傳 500 錯誤"

# 執行最佳化迴圈
/ce-optimize "API 回應時間最佳化"

# 執行 iOS 模擬器測試
/test-xcode

# 啟動全自動工作流
/lfg "實作用戶管理 CRUD API"

# ❌ 錯誤：描述太模糊
/ce:plan "做一個 API"

# ✅ 正確：提供足夠上下文
/ce:plan "實作 RESTful 轉帳 API
- POST /api/v1/transfers（即時轉帳）
- POST /api/v1/transfers/scheduled（預約轉帳）
- 使用現有的 AccountService 查詢餘額
- 需要 JWT 認證 + 2FA 驗證
- Oracle DB 寫入需要 XA Transaction"

# ❌ 問題：所有 agent 都報告大量低優先級問題
# ✅ 解法：在 CLAUDE.md 中設定審查規則

# CLAUDE.md 中新增
## Review 規則
- security-reviewer: 只報告 CRITICAL 和 HIGH
- performance-reviewer: 只報告回應時間 > 1s 的問題
- maintainability-reviewer: 忽略生成的程式碼

# ❌ 問題：/ce:plan 未引用過去的 learnings
# ✅ 解法：確認 learnings 目錄路徑在 CLAUDE.md 中正確設定

# CLAUDE.md
## Knowledge Base
- 專案知識：docs/learnings/
- 團隊知識：.github/compound/
- 在 Plan 階段一定考慮過去的 learnings

# 建立 commit 並推送
git-commit-push-pr

# 管理 worktree（並行開發）
git-worktree

# 清理已合併的分支
git-clean-gone-branches

# 產出 changelog
/changelog

# .github/workflows/compound-engineering.yml
name: Compound Engineering Pipeline
on:
  pull_request:
    types: [opened, synchronize]
  push:
    branches: [main, develop]

jobs:
  # 階段 1：自動審查
  ce-review:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4
      - name: CE Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          bunx @every-env/compound-plugin install compound-engineering
          # 觸發自動化審查

  # 階段 2：標準 CI
  build-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
      - name: Build & Test
        run: mvn clean verify

  # 階段 3：合併後 Compound
  compound:
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: build-test
    steps:
      - uses: actions/checkout@v4
      - name: Auto Compound
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # 自動提取並記錄本次合併的學習
          echo "Extracting learnings from merged PR..."

# 自動解決 PR 審查意見
/resolve-pr-feedback

# 執行瀏覽器測試
/test-browser

# Testing 相關 Review Agent 檢查覆蓋率
# testing-reviewer 會自動檢查：
# - 測試覆蓋缺口
# - 弱斷言（weak assertions）
# - 缺少的邊界測試

Level 1（必備）：What — 要做什麼
Level 2（重要）：Why — 為什麼要做
Level 3（建議）：How — 技術約束與偏好
Level 4（加分）：Context — 參考資料與過去經驗

# ❌ 差的 Prompt
/ce:plan "做登入功能"

# ⚠️ 普通的 Prompt
/ce:plan "實作 JWT 登入 API，使用 Spring Security"

# ✅ 好的 Prompt
/ce:plan "實作銀行客戶登入功能
## What
- POST /api/v1/auth/login（帳號密碼登入）
- POST /api/v1/auth/refresh（Token 更新）
- POST /api/v1/auth/logout（登出並作廢 Token）

## Why
- 替換現有的 Session-based 認證
- 支援 Micro-Frontend 的跨域需求

## How
- 使用 Spring Security 6 + JWT
- Access Token 有效期 15 分鐘
- Refresh Token 有效期 7 天，存入 Redis
- 密碼使用 BCrypt 加密
- 失敗 5 次鎖定帳號 30 分鐘

## Context
- 參考 docs/learnings/2026-03-20-jwt-best-practices.md
- 現有的 UserService 已有查詢用戶方法
- 需通過 security-reviewer 審查"

# CLAUDE.md — 範例

## 專案概述
這是銀行核心帳務系統的轉帳模組，使用 Spring Boot 3.2 + JPA + Oracle 19c。

## 架構規範
- 使用 Clean Architecture（Controller → Service → Repository）
- 所有 Service 方法需有 @Transactional
- 所有 Controller 需有 @PreAuthorize
- API 格式遵循 RESTful 規範

## 編碼規範
- 使用 Java 21 + Record 替代傳統 DTO
- 使用 Optional 替代 null 回傳
- 命名：PascalCase（類別）、camelCase（方法）、UPPER_SNAKE_CASE（常數）

## 安全規範
- 所有 API 需要 JWT 認證
- SQL 參數必須使用 PreparedStatement
- 禁止在日誌中輸出敏感資訊（密碼、Token、身份證號）

## 知識庫
- 專案知識：docs/learnings/
- 在 Plan 階段必須查閱相關 learnings

# 刷新知識庫（檢查過時內容）
/ce:compound-refresh

# 查詢歷史會話
/ce-sessions "過去關於 Oracle 效能的討論"

# 搜尋 Slack 中的組織上下文
/ce-slack-research "轉帳模組的架構討論"

## 建議追蹤的指標
- Plan 產出時間（目標：< 5 分鐘）
- Review 完成時間（目標：< 10 分鐘）
- Token 使用量 / 每次循環
- 知識庫引用率（被 Plan 引用的學習百分比）
- Hallucination 率（被人工修正的比例）

# 查詢歷史會話
/ce-sessions "最近的錯誤和問題"

# 查看 Plugin 更新狀態
/ce-update

# Claude Code 中更新
/ce-update

# CLI 更新
bunx @every-env/compound-plugin install compound-engineering

# 指定版本
bunx @every-env/compound-plugin install compound-engineering@2.65.0

# 驗證版本
/ce-setup

# 知識庫與程式碼一同管理
git add docs/learnings/
git commit -m "compound: 新增 Oracle 批次效能最佳化學習"

# 透過 PR 審查知識品質
git-commit-push-pr

# CLAUDE.md
<!-- CE Plugin >= v2.60.0 -->

# 切換至特定穩定版本
claude --plugin-dir "$(bunx @every-env/compound-plugin plugin-path \
  compound-engineering --branch v2.60.0)"

# 回滾知識庫
git revert HEAD~3..HEAD -- docs/learnings/

/ce:brainstorm "銀行轉帳模組開發
需要支援：
1. 即時轉帳（同行/跨行）
2. 預約轉帳（指定日期）
3. 轉帳交易查詢
4. 雙因素驗證（OTP）
5. 單日轉帳限額控制
技術環境：Spring Boot 3.2 + Vue 3 + Oracle 19c"

CE: 跨行轉帳是否需要對接外部金資中心 API？
Dev: 是的，需要透過內部 Gateway 轉發

CE: OTP 驗證使用什麼方式？SMS 或 App Push？
Dev: 使用 TOTP（Time-based OTP），整合現有的 OTP Service

CE: 預約轉帳的排程機制？
Dev: 使用 Spring Scheduler + Quartz，每日 00:00 批次處理

CE: 單日限額是全行統一還是客戶等級不同？
Dev: 依客戶等級：一般戶 50萬、VIP 200萬、企業戶 500萬

/ce:plan

# 實作計畫：銀行轉帳模組

## Phase 1: 資料層（Day 1-2）
1. Transfer Entity + Enum (TransferType, TransferStatus)
2. Oracle migration scripts (Flyway)
3. TransferRepository (JPA + Custom Query)

## Phase 2: 業務邏輯（Day 3-5）
4. TransferService — 即時轉帳邏輯
5. TransferService — 預約轉帳邏輯
6. TransferLimitService — 限額檢查
7. OtpVerificationService — TOTP 驗證整合
8. TransferScheduler — Quartz 排程設定

## Phase 3: API 層（Day 6-7）
9. TransferController — REST endpoints
10. TransferQueryController — 查詢 endpoints
11. Input Validation（@Valid + custom validator）
12. Exception Handler（GlobalExceptionHandler）

## Phase 4: 前端（Day 8-10）
13. TransferForm.vue — 轉帳表單元件
14. TransferHistory.vue — 交易查詢元件
15. OtpDialog.vue — OTP 驗證彈窗

## Phase 5: 測試（Day 11-12）
16. Unit Tests (Service + Repository)
17. Integration Tests (Controller + Oracle)
18. E2E Tests (Playwright)

## 參考 Learnings
- docs/learnings/2026-03-15-oracle-jpa-performance.md
- docs/learnings/2026-03-20-jwt-best-practices.md

/ce:work

// 自動產出 Transfer Entity
@Entity
@Table(name = "T_TRANSFER")
public class Transfer {
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "transfer_seq")
    @SequenceGenerator(name = "transfer_seq", sequenceName = "SEQ_TRANSFER", allocationSize = 1)
    private Long id;

    @Column(name = "FROM_ACCOUNT", nullable = false, length = 16)
    private String fromAccount;

    @Column(name = "TO_ACCOUNT", nullable = false, length = 16)
    private String toAccount;

    @Column(name = "AMOUNT", nullable = false, precision = 18, scale = 2)
    private BigDecimal amount;

    @Enumerated(EnumType.STRING)
    @Column(name = "TRANSFER_TYPE", nullable = false)
    private TransferType transferType;

    @Enumerated(EnumType.STRING)
    @Column(name = "STATUS", nullable = false)
    private TransferStatus status;

    @Column(name = "SCHEDULED_DATE")
    private LocalDate scheduledDate;

    @Column(name = "CREATED_AT", nullable = false)
    private LocalDateTime createdAt;

    @Column(name = "EXECUTED_AT")
    private LocalDateTime executedAt;

    // constructors, getters, audit fields...
}

// 自動產出 TransferService
@Service
@Transactional
@RequiredArgsConstructor
public class TransferService {

    private final TransferRepository transferRepository;
    private final AccountService accountService;
    private final TransferLimitService limitService;
    private final OtpVerificationService otpService;
    private final TransferEventPublisher eventPublisher;

    public TransferResponse executeTransfer(TransferRequest request, String otpCode) {
        // 1. 驗證 OTP
        otpService.verify(request.getUserId(), otpCode);

        // 2. 檢查限額
        limitService.checkDailyLimit(request.getUserId(), request.getAmount());

        // 3. 檢查餘額
        accountService.validateSufficientBalance(
            request.getFromAccount(), request.getAmount()
        );

        // 4. 執行轉帳
        Transfer transfer = Transfer.builder()
            .fromAccount(request.getFromAccount())
            .toAccount(request.getToAccount())
            .amount(request.getAmount())
            .transferType(TransferType.IMMEDIATE)
            .status(TransferStatus.PROCESSING)
            .createdAt(LocalDateTime.now())
            .build();

        transfer = transferRepository.save(transfer);

        // 5. 呼叫帳務核心（扣款 + 入帳）
        accountService.debit(request.getFromAccount(), request.getAmount());
        accountService.credit(request.getToAccount(), request.getAmount());

        transfer.setStatus(TransferStatus.COMPLETED);
        transfer.setExecutedAt(LocalDateTime.now());
        transferRepository.save(transfer);

        // 6. 發送審計事件
        eventPublisher.publishTransferCompleted(transfer);

        return TransferResponse.from(transfer);
    }
}

/ce:review

🔴 CRITICAL (security-reviewer):
- TransferService.executeTransfer() 缺少 @PreAuthorize 註解
- 轉帳金額未檢查是否為正數

🟡 WARNING (performance-oracle):
- TransferRepository 缺少 fromAccount + createdAt 的複合索引
- 建議使用 @BatchSize 優化交易查詢的 N+1 問題

🟡 WARNING (reliability-reviewer):
- 扣款和入帳不在同一個 DB Transaction 中
- 建議使用 Saga Pattern 或 XA Transaction

🟢 INFO (maintainability-reviewer):
- TransferService 方法過長（45行），建議拆分為 private method
- 建議將帳務操作抽取為 AccountTransactionService

🟢 INFO (testing-reviewer):
- 缺少 OTP 驗證失敗的測試案例
- 缺少轉帳限額超過的邊界測試

# 修復完成後
/ce:review
# ✅ All reviewers passed with no CRITICAL issues

/ce:compound

# Learning: 銀行轉帳模組開發最佳實務

## 日期
2026-04-13

## 關鍵學習

### 1. 安全性
- 所有金融交易 API 必須加上 @PreAuthorize
- 金額參數必須驗證為正數且有上限
- OTP 驗證必須在業務邏輯之前執行

### 2. 效能
- Oracle 複合索引：(from_account, created_at) 用於交易查詢
- 使用 @BatchSize(size = 50) 避免 N+1 查詢

### 3. 可靠性
- 跨帳戶金融操作必須使用 XA Transaction 或 Saga Pattern
- 不可在不同 DB Transaction 中分別處理扣款和入帳

### 4. 測試
- 金融功能必須覆蓋：成功路徑、餘額不足、限額超過、OTP 失敗、併發操作
- 使用 @Sql 載入測試資料，避免測試間相互影響

## 適用範圍
所有金融交易相關的 Service 開發

# === 安裝與設定 ===
/plugin marketplace add EveryInc/compound-engineering-plugin
/plugin install compound-engineering
/ce-setup                           # 環境診斷 + 初始化
/ce-update                          # 檢查更新

# === 核心工作流 ===
/ce:ideate                          # 創意探索
/ce:brainstorm "需求描述"            # 需求發散（主要入口）
/ce:plan                            # 計畫制定
/ce:work                            # 開發執行
/ce:review                          # 多代理審查
/ce:compound                        # 知識沉澱
/ce:compound-refresh                # 刷新過時知識

# === 除錯與最佳化 ===
/ce-debug "問題描述"                 # 系統性除錯
/ce-optimize "最佳化目標"            # 迭代最佳化

# === Git 操作 ===
git-commit                          # 建立 commit
git-commit-push-pr                  # commit + push + PR
git-worktree                        # 管理 worktree
git-clean-gone-branches             # 清理已合併分支

# === 輔助工具 ===
/changelog                          # 產出 changelog
/ce-demo-reel                       # 擷取展示素材
/resolve-pr-feedback                # 解決 PR 意見
/test-browser                       # 瀏覽器測試
/onboarding                         # 產出新手文件
/ce-sessions "查詢主題"              # 查詢歷史會話

# === 跨平台安裝與同步 ===
bunx @every-env/compound-plugin install compound-engineering --to codex
bunx @every-env/compound-plugin install compound-engineering --to copilot
bunx @every-env/compound-plugin install compound-engineering --to opencode
bunx @every-env/compound-plugin install compound-engineering --to droid
bunx @every-env/compound-plugin install compound-engineering --to pi
bunx @every-env/compound-plugin install compound-engineering --to gemini
bunx @every-env/compound-plugin install compound-engineering --to kiro
bunx @every-env/compound-plugin install compound-engineering --to windsurf
bunx @every-env/compound-plugin install compound-engineering --to openclaw
bunx @every-env/compound-plugin install compound-engineering --to qwen
bunx @every-env/compound-plugin install compound-engineering --to all
bunx @every-env/compound-plugin sync                    # 同步個人設定
bunx @every-env/compound-plugin sync --target copilot    # 同步至特定平台