// 不好的 Prompt
寫一個 API

// 好的 Prompt
請使用 Java 17 + Spring Boot 3.2 撰寫一個符合 RESTful 規範的
帳戶查詢 API（GET /api/v1/accounts/{accountId}），
回傳 JSON 格式，包含帳號、餘額、幣別欄位，
需包含 @Valid 驗證與全域例外處理。

情境工程的作用：
├── 專案架構文件（README.md, ADR）
├── 命名規範（coding standards）
├── 相關模組的介面定義（Interface）
├── 資料庫 Schema
├── 歷史決策記錄
└── 領域知識（Domain Knowledge）

Harness（系統環境）：
├── 開發框架（Spring Boot Starter）
├── 測試工具（JUnit, Mockito, ArchUnit）
├── CI/CD Pipeline（GitHub Actions）
├── 靜態分析（SonarQube, SpotBugs）
├── AI Agent / MCP Server
├── 安全護欄（Guardrails）
└── 監控與回饋（Logging, Metrics）

Prompt Engineering  → 你怎麼「問」AI（Interface Layer）
Context Engineering → AI「知道」什麼（Data Layer）
Harness Engineering → AI 在什麼「系統」裡工作（System Layer）

使用 Spring Boot 3.2 + Java 17 撰寫一個 RESTful API：
- Endpoint: GET /api/v1/accounts/{accountId}
- 回傳 JSON：{ accountId, balance, currency, status }
- 使用 @RestController, @GetMapping
- 加入 @Valid 參數驗證
- 使用 ResponseEntity 包裝回傳
- 加入 Swagger/OpenAPI 3.0 註解

專案結構（AI 需知道的情境）：
├── .github/copilot-instructions.md    ← 專案開發規範
├── docs/adr/                          ← 架構決策記錄
│   ├── ADR-001-clean-architecture.md
│   └── ADR-005-error-handling.md
├── src/main/java/com/bank/
│   ├── controller/                    ← Presentation Layer
│   ├── usecase/                       ← Application Layer（Use Case）
│   ├── domain/                        ← Domain Layer
│   └── infrastructure/                ← Infrastructure Layer
└── docs/api-spec/
    └── account-api.yaml               ← OpenAPI Spec

## 架構規範
- 採用 Clean Architecture：Controller → UseCase → Domain → Infrastructure
- Controller 只做 HTTP 映射，不含商業邏輯
- UseCase 透過介面與 Infrastructure 解耦

## 命名規範
- Controller: XxxController
- UseCase: XxxUseCase / XxxUseCaseImpl
- Domain Entity: 放在 domain/model/
- Repository Interface: 放在 domain/repository/

## 例外處理
- 使用 @ControllerAdvice 全域處理
- 自定義 BusinessException, NotFoundException
- 錯誤回傳格式：{ code, message, timestamp }

依照 Clean Architecture 規範，建立帳戶查詢功能的所有分層程式碼，
包含 Controller、UseCase Interface/Impl、Domain Entity、Repository Interface。

@AnalyzeClasses(packages = "com.bank")
public class ArchitectureTest {

    @ArchTest
    static final ArchRule controller_should_not_access_infrastructure =
        noClasses().that().resideInAPackage("..controller..")
            .should().accessClassesThat().resideInAPackage("..infrastructure..");

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

    @ArchTest
    static final ArchRule domain_should_not_depend_on_outer_layers =
        noClasses().that().resideInAPackage("..domain..")
            .should().dependOnClassesThat()
            .resideInAnyPackage("..controller..", "..usecase..", "..infrastructure..");
}

# .github/workflows/ai-code-validation.yml
name: AI Code Validation

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'
      
      - name: Run Architecture Tests
        run: mvn test -Dtest=ArchitectureTest
      
      - name: Run SonarQube Scan
        run: mvn sonar:sonar -Dsonar.qualitygate.wait=true
      
      - name: Run Security Scan (OWASP)
        run: mvn dependency-check:check
      
      - name: Validate API Spec Compliance
        run: |
          # 驗證實作與 OpenAPI Spec 一致
          mvn verify -P api-spec-validation

{
  "mcpServers": {
    "sonarqube": {
      "command": "sonarqube-mcp-server",
      "args": ["--project-key", "bank-core"]
    },
    "database-schema": {
      "command": "db-schema-mcp-server",
      "args": ["--connection", "jdbc:postgresql://localhost:5432/bank"]
    }
  }
}

寫一個 Spring Batch Job，每日計算帳戶利息：
- 讀取所有活躍帳戶
- 依據年利率計算日息
- 更新帳戶餘額
- 記錄異動日誌

## 利息計算規則（domain-rules/interest-calculation.md）
- 日息公式：餘額 × 年利率 ÷ 365（平年）或 366（閏年）
- 幣別：TWD 四捨五入至整數、USD 四捨五入至小數第二位
- 帳戶狀態：僅「ACTIVE」帳戶計息
- 凍結帳戶不計息但需記錄
- 利率來源：利率主檔（rate_master 表）
- 異動日誌需記錄：帳號、計息前餘額、利息金額、計息後餘額、利率、日期

// 框架層自動驗證
@SpringBatchTest
@SpringBootTest
class InterestBatchJobTest {

    @Autowired
    private JobLauncherTestUtils jobLauncherTestUtils;

    @Test
    void shouldCalculateInterestCorrectly() {
        // Given: 測試資料
        insertTestAccount("ACC001", new BigDecimal("1000000"), "TWD");
        insertTestRate("TWD", new BigDecimal("0.015")); // 1.5%

        // When: 執行批次
        JobExecution execution = jobLauncherTestUtils.launchJob();

        // Then: 驗證
        assertThat(execution.getStatus()).isEqualTo(BatchStatus.COMPLETED);
        assertThat(getBalance("ACC001")).isEqualTo(new BigDecimal("1000041")); // 四捨五入
        assertThat(getAuditLog("ACC001")).isNotEmpty();
    }

    @Test
    void shouldSkipFrozenAccount() {
        insertTestAccount("ACC002", new BigDecimal("500000"), "TWD");
        setAccountStatus("ACC002", "FROZEN");
        
        JobExecution execution = jobLauncherTestUtils.launchJob();
        
        assertThat(execution.getStatus()).isEqualTo(BatchStatus.COMPLETED);
        assertThat(getBalance("ACC002")).isEqualTo(new BigDecimal("500000")); // 未變動
        assertThat(getSkipLog("ACC002")).contains("FROZEN");
    }
}

## 設計系統規範（design-system.md）
- 主色：#1A365D（深藍），輔色：#2B6CB0
- 表格元件：使用 <BankTable>，支援排序、分頁
- 搜尋：使用 <SearchBar>，debounce 300ms
- 載入狀態：使用 <Skeleton> 骨架屏
- 錯誤狀態：使用 <ErrorBanner>

## API 介面（account-api.yaml）
GET /api/v1/accounts?keyword={keyword}&page={page}&size={size}
Response: { content: Account[], totalElements: number, totalPages: number }

// Playwright E2E 測試（自動驗證 AI 產出的 UI）
test('帳戶查詢頁面功能驗證', async ({ page }) => {
  await page.goto('/accounts');
  
  // 搜尋功能
  await page.fill('[data-testid="search-input"]', 'ACC001');
  await page.waitForResponse('**/api/v1/accounts**');
  
  // 列表顯示
  const rows = page.locator('[data-testid="account-row"]');
  await expect(rows).toHaveCount(1);
  
  // 分頁功能
  await page.click('[data-testid="next-page"]');
  await expect(page.locator('[data-testid="page-indicator"]')).toContainText('2');
});

下面這段轉帳程式碼在高併發時會出現金額不一致的問題，請幫我找出原因並修正：
[貼上程式碼]

# 提供完整情境
## 系統架構
- Spring Boot 3.2 + PostgreSQL 15
- 使用 JPA / Hibernate
- 部署 3 個 Pod（Kubernetes）

## 問題現象
- 同一帳戶同時收到兩筆轉入時，最終餘額只增加一筆的金額
- 發生頻率約 0.1%（高峰時段）

## 相關程式碼
[TransferService.java + AccountRepository.java + 資料庫隔離級別設定]

## 已嘗試的方案
- 加了 @Transactional(isolation = Isolation.SERIALIZABLE) → 效能大幅下降
- 加了 synchronized → 多 Pod 環境無效

# 自動化壓力測試（Harness 的一部分）
# locust 或 JMeter 測試自動執行
stress-test:
  scenario: concurrent-transfer
  config:
    users: 100
    duration: 60s
    target-account: ACC001
  assertions:
    - final-balance-equals: expected-sum
    - no-lost-updates: true
  alerts:
    - type: slack
      channel: "#bank-core-team"
      when: assertion-failed

// 透過 Optimistic Locking 解決（Harness 中的設計模式內建方案）
@Entity
public class Account {
    @Id
    private String accountId;
    
    @Version  // Optimistic Locking
    private Long version;
    
    private BigDecimal balance;
}

// Service 層自動重試
@Retryable(value = OptimisticLockingFailureException.class, maxAttempts = 3)
@Transactional
public TransferResult transfer(TransferCommand command) {
    Account from = accountRepository.findByIdForUpdate(command.getFromAccountId());
    Account to = accountRepository.findByIdForUpdate(command.getToAccountId());
    
    from.debit(command.getAmount());
    to.credit(command.getAmount());
    
    auditLogService.log(command, from, to);
    return TransferResult.success();
}

設計帳戶服務呼叫通知服務的 API，
當帳戶餘額低於門檻時發送通知。
用 Spring Boot + RestTemplate。

## 微服務通訊規範（docs/adr/ADR-012-service-communication.md）

### 決策
- 服務間通訊採用「Event-Driven」模式（非同步）
- 使用 Apache Kafka 作為事件匯流排
- 事件格式遵循 CloudEvents 規範 (v1.0.2)
- 事件名稱慣例：{aggregate}.{action}.{version}
  例：account.balance-low.v1

### 事件契約（Event Schema）
```json
{
  "specversion": "1.0",
  "type": "com.bank.account.balance-low.v1",
  "source": "/account-service",
  "subject": "ACC001",
  "data": {
    "accountId": "ACC001",
    "currentBalance": 5000,
    "threshold": 10000,
    "currency": "TWD"
  }
}

#### Harness Engineering 範例

```java
// Contract Test — 驗證事件生產者與消費者契約一致
@SpringBootTest
@EmbeddedKafka(partitions = 1, topics = "account.balance-low.v1")
class BalanceLowEventContractTest {

    @Autowired
    private KafkaTemplate<String, CloudEvent> kafkaTemplate;

    @Test
    void shouldProduceValidCloudEvent() {
        // Given
        BalanceLowEvent event = new BalanceLowEvent("ACC001", 
            new BigDecimal("5000"), new BigDecimal("10000"), "TWD");
        
        // When
        CloudEvent cloudEvent = eventPublisher.publish(event);
        
        // Then: 驗證事件結構符合契約
        assertThat(cloudEvent.getType())
            .isEqualTo("com.bank.account.balance-low.v1");
        assertThat(cloudEvent.getSpecVersion())
            .isEqualTo(SpecVersion.V1);
        assertThat(cloudEvent.getSource().toString())
            .isEqualTo("/account-service");
        
        // 驗證 JSON Schema
        JsonSchemaValidator.validate(cloudEvent.getData(), 
            "schemas/balance-low-event-v1.json");
    }
}

# 監控與斷路器配置（application.yml）
resilience4j:
  circuitbreaker:
    instances:
      notificationService:
        slidingWindowSize: 10
        failureRateThreshold: 50
        waitDurationInOpenState: 30s
        
management:
  endpoints:
    web:
      exposure:
        include: health,metrics,circuitbreakers
  metrics:
    tags:
      application: account-service
    export:
      prometheus:
        enabled: true

我的帳戶查詢 API 有 IDOR 漏洞，
用戶可以查詢任何帳戶的資料。
請問如何修復？

## 安全架構（docs/adr/ADR-003-authorization.md）
- 使用 Spring Security + JWT
- 角色：CUSTOMER, TELLER, MANAGER, ADMIN
- 權限模型：RBAC + ABAC（Attribute-Based Access Control）
- 帳戶存取規則：
  - CUSTOMER 只能存取名下帳戶
  - TELLER 可存取所屬分行的帳戶
  - MANAGER 可存取所屬區域的帳戶
  - ADMIN 可存取所有帳戶
- 安全檢查統一在 UseCase 層（非 Controller）
- 使用自定義 @PreAuthorize + SpEL 表達式

// 自動化安全測試 — 驗證 IDOR 修復
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
@AutoConfigureMockMvc
class AccountApiSecurityTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    @WithMockUser(username = "customer_A", roles = {"CUSTOMER"})
    void customerShouldAccessOwnAccount() throws Exception {
        mockMvc.perform(get("/api/v1/accounts/ACC_A001"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.accountId").value("ACC_A001"));
    }

    @Test
    @WithMockUser(username = "customer_A", roles = {"CUSTOMER"})
    void customerShouldNotAccessOtherAccount() throws Exception {
        // IDOR 測試：客戶 A 嘗試存取客戶 B 的帳戶
        mockMvc.perform(get("/api/v1/accounts/ACC_B001"))
            .andExpect(status().isForbidden())
            .andExpect(jsonPath("$.errorCode").value("AUTH_003"));
    }

    @Test
    @WithMockUser(username = "teller_branch_01", roles = {"TELLER"})
    void tellerShouldAccessSameBranchAccount() throws Exception {
        mockMvc.perform(get("/api/v1/accounts/ACC_BRANCH01_001"))
            .andExpect(status().isOk());
    }

    @Test
    @WithMockUser(username = "teller_branch_01", roles = {"TELLER"})
    void tellerShouldNotAccessOtherBranchAccount() throws Exception {
        mockMvc.perform(get("/api/v1/accounts/ACC_BRANCH02_001"))
            .andExpect(status().isForbidden());
    }
}

# DAST 自動掃描（GitHub Actions）
security-scan:
  runs-on: ubuntu-latest
  steps:
    - name: OWASP ZAP DAST Scan
      uses: zaproxy/action-full-scan@v0.10.0
      with:
        target: 'http://localhost:8080'
        rules_file_name: '.zap/rules.tsv'
        
    - name: Validate No IDOR Issues
      run: |
        # 解析 ZAP 報告，確認無 IDOR 相關 Alert
        python scripts/parse_zap_report.py --check IDOR

/**
 * 執行帳戶間轉帳作業。
 * 
 * <p>業務規則：
 * <ul>
 *   <li>轉出帳戶餘額必須大於等於轉帳金額</li>
 *   <li>同幣別帳戶直接轉帳，跨幣別需匯率轉換</li>
 *   <li>單筆轉帳上限：TWD 3,000,000 / USD 100,000</li>
 *   <li>需記錄完整異動日誌（含轉出/轉入雙方）</li>
 * </ul>
 * 
 * @param command 轉帳指令（含來源帳號、目標帳號、金額、幣別）
 * @return TransferResult 轉帳結果（含交易序號、狀態）
 * @throws InsufficientBalanceException 餘額不足
 * @throws TransferLimitExceededException 超過轉帳限額
 * @throws AccountNotFoundException 帳戶不存在
 */
public TransferResult executeTransfer(TransferCommand command) {
    // Copilot 會根據上方 JavaDoc 產生符合規則的實作
}

# 模板：API 開發
角色：你是銀行核心系統的 Java 資深工程師
技術棧：Java 17 + Spring Boot 3.2 + JPA + PostgreSQL
架構：Clean Architecture（Controller → UseCase → Domain → Infrastructure）
要求：
1. [具體功能描述]
2. 包含完整的例外處理
3. 包含 JavaDoc 註解
4. 包含對應的單元測試
5. 符合 OWASP 安全規範

# 模板：Code Review
請審查以下程式碼，從這些面向提供建議：
1. 安全性（SQL Injection, XSS, CSRF）
2. 效能（N+1 Query, 記憶體洩漏）
3. 可維護性（SOLID 原則）
4. 銀行業合規性（交易一致性、稽核日誌）

請逐步分析並實作跨幣別轉帳的匯率轉換邏輯：

步驟 1：確認來源帳戶幣別和目標帳戶幣別
步驟 2：從匯率主檔查詢即時匯率
步驟 3：計算轉出金額（考慮手續費）
步驟 4：計算轉入金額（依匯率轉換，TWD 四捨五入至整數）
步驟 5：驗證轉出帳戶餘額是否足夠（含手續費）
步驟 6：執行轉帳（在同一交易中完成扣款、入帳、手續費）
步驟 7：記錄異動日誌（含匯率、手續費明細）

請依照上述步驟，使用 Java 17 + Spring Boot 3.2 撰寫完整實作。

請依照以下範例風格，為帳戶凍結 UseCase 撰寫實作：

### 範例：帳戶查詢 UseCase
```java
public interface GetAccountUseCase {
    AccountResponse execute(GetAccountCommand command);
}

@RequiredArgsConstructor
@Service
public class GetAccountUseCaseImpl implements GetAccountUseCase {
    private final AccountRepository accountRepository;
    private final AccountMapper mapper;
    
    @Override
    @Transactional(readOnly = true)
    public AccountResponse execute(GetAccountCommand command) {
        Account account = accountRepository.findById(command.getAccountId())
            .orElseThrow(() -> new NotFoundException("ACC_001", "帳戶不存在"));
        return mapper.toResponse(account);
    }
}

**技巧 3：Constraint-based Prompting（約束導向）**

明確列出硬性約束，防止 AI 產出違規程式碼：

```text
## 硬性約束（違反即不合格）
❌ 禁止使用 float/double 處理金額（必須 BigDecimal）
❌ 禁止在 Controller 層寫商業邏輯
❌ 禁止硬編碼密碼、連線字串
❌ 禁止使用 String concatenation 組 SQL
❌ 禁止在日誌中輸出身分證字號、密碼

## 軟性約束（建議遵循）
⚠️ 方法長度建議不超過 30 行
⚠️ 類別職責應單一（SRP）
⚠️ 使用 Optional 而非 null 檢查

你現在扮演兩個角色：

角色 1 — 資深 Java 工程師：
請設計帳戶解鎖的 API。

角色 2 — 資安滲透測試工程師：
請檢查角色 1 的設計，找出潛在安全漏洞，
包括但不限於：暴力破解、權限提升、資訊洩漏。

最後，請結合兩個角色的觀點，產出安全且完整的實作。

# 銀行核心系統 — Copilot 開發規範

## 架構
- 採用 Clean Architecture
- 分層：Presentation → Application → Domain → Infrastructure
- Domain Layer 不依賴任何外部框架

## 技術棧
- Java 17, Spring Boot 3.2, Spring Data JPA
- PostgreSQL 15, Redis 7
- JUnit 5 + Mockito + ArchUnit

## 命名規範
- Controller: `XxxController`
- UseCase: `XxxUseCase` (Interface) / `XxxUseCaseImpl` (Implementation)
- Entity: `XxxEntity`（JPA）/ `Xxx`（Domain Model）
- Repository: `XxxRepository` (Interface in Domain) / `XxxRepositoryImpl` (Infrastructure)
- DTO: `XxxRequest`, `XxxResponse`

## 例外處理
- 自定義 `BusinessException(ErrorCode, message)`
- 使用 `@ControllerAdvice` 全域攔截
- 錯誤回傳：`{ "errorCode": "ACC_001", "message": "...", "timestamp": "..." }`

## 安全規範
- 所有 API 需 JWT 認證（除 /api/v1/auth/**）
- 敏感欄位（身分證字號、帳號）需脫敏處理
- SQL 操作一律使用 Parameterized Query
- 禁止在日誌中輸出密碼、Token 等機密資訊

## 交易規範
- 涉及金額的操作必須使用 BigDecimal
- 帳務異動需寫入 audit_log 表
- 轉帳操作需使用 Pessimistic/Optimistic Locking

在開發「轉帳功能」時，確保以下檔案已開啟：
├── TransferController.java     ← AI 知道 HTTP 入口點
├── TransferUseCase.java        ← AI 知道介面定義
├── Account.java                ← AI 知道 Domain Model
├── AccountRepository.java      ← AI 知道資料存取介面
└── TransferRequest.java        ← AI 知道輸入格式

# ADR-007: 帳務交易一致性策略

## 狀態
已採納（2025-06-15）

## 決策
帳務相關交易全部使用 Pessimistic Locking（SELECT FOR UPDATE），
非帳務交易使用 Optimistic Locking（@Version）。

## 原因
- 銀行帳務不允許任何金額不一致
- Pessimistic Locking 在帳務場景中可確保強一致性
- 效能影響可接受（帳務 TPS < 1000）

## 影響
- 所有涉及餘額變動的 Repository 方法需加 @Lock(LockModeType.PESSIMISTIC_WRITE)
- 超時設定：5 秒

專案中的 Prompt Files 結構：
.github/
├── copilot-instructions.md          ← 全域 Context
└── prompts/                         ← 可重用 Prompt 集合
    ├── create-api.prompt.md         ← API 開發 Prompt
    ├── create-test.prompt.md        ← 測試生成 Prompt
    ├── code-review.prompt.md        ← Code Review Prompt
    ├── refactor.prompt.md           ← 重構 Prompt
    └── security-check.prompt.md     ← 安全審查 Prompt

---
mode: 'agent'
description: '依照 Clean Architecture 建立新的 REST API'
tools: ['file_search', 'terminal', 'sonarqube']
---

# 建立新 REST API

## 前置作業
1. 讀取 `.github/copilot-instructions.md` 了解架構規範
2. 讀取 `docs/adr/` 了解相關架構決策
3. 搜尋現有類似 API 作為參考

## 產出要求
依照 Clean Architecture 產出以下檔案：
- `src/main/java/.../controller/{Name}Controller.java`
- `src/main/java/.../usecase/{Name}UseCase.java`
- `src/main/java/.../usecase/impl/{Name}UseCaseImpl.java`
- `src/main/java/.../domain/model/{Name}.java`
- `src/main/java/.../domain/repository/{Name}Repository.java`
- `src/test/java/.../usecase/impl/{Name}UseCaseImplTest.java`

## 品質標準
- 所有公開方法必須有 JavaDoc
- 金額處理使用 BigDecimal
- 包含 @Valid 驗證
- 包含完整的例外處理

// .vscode/agents.json — 建立銀行系統專用 Agent
{
  "bank-api-agent": {
    "description": "銀行 API 開發專用 Agent",
    "instructions": "你是銀行核心系統的 API 開發專家...",
    "tools": ["file_search", "terminal", "sonarqube", "db-schema"]
  },
  "bank-security-agent": {
    "description": "銀行安全審查 Agent",
    "instructions": "你是資安審查專家，專注於 OWASP Top 10...",
    "tools": ["sonarqube", "owasp-check", "code-review"]
  }
}

// .vscode/mcp.json
{
  "servers": {
    "sonarqube": {
      "type": "stdio",
      "command": "npx",
      "args": ["sonarqube-mcp-server", "--project-key", "bank-core"]
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["postgres-mcp-server", "--connection-string", "${DB_URL}"]
    }
  }
}

# .github/workflows/copilot-guardrails.yml
name: AI Code Guardrails

on:
  pull_request:
    paths: ['src/**']

jobs:
  architecture-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: ArchUnit Tests
        run: mvn test -Dtest="*ArchitectureTest"

  security-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: OWASP Dependency Check
        run: mvn dependency-check:check
      - name: SpotBugs Security
        run: mvn spotbugs:check

  code-quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: SonarQube Analysis
        run: mvn sonar:sonar
      - name: Quality Gate
        run: |
          # 若品質門檻未通過，阻擋合併
          curl -s "$SONAR_URL/api/qualitygates/project_status?projectKey=bank-core" \
            | jq -e '.projectStatus.status == "OK"'

# .github/copilot-coding-agent.yml
agent:
  enabled: true
  auto-assign-labels: ["copilot-task"]
  
  context:
    files:
      - ".github/copilot-instructions.md"
      - "docs/adr/*.md"
      - "docs/domain-rules/*.md"
    
  guardrails:
    require-ci-pass: true
    require-review: true
    max-files-changed: 20
    blocked-paths:
      - "src/main/resources/application-prod.yml"
      - "*.key"
      - "*.pem"

#!/bin/bash
# ai-dev-workflow.sh — 標準 AI 輔助開發流程

echo "=== Step 1: 確認 Context 就緒 ==="
# 檢查必要 Context 檔案是否存在
test -f .github/copilot-instructions.md || echo "❌ 缺少 copilot-instructions.md"
test -d docs/adr/ || echo "⚠️ 缺少 ADR 目錄"

echo "=== Step 2: 開發（使用 AI）==="
echo "請在 VS Code 中使用 Copilot 開發功能..."

echo "=== Step 3: 本地 Harness 驗證 ==="
mvn compile                           # 編譯檢查
mvn test                              # 單元測試
mvn test -Dtest="*ArchitectureTest"   # 架構驗證
mvn spotbugs:check                     # 程式碼品質

echo "=== Step 4: 提交 PR ==="
git add -A
git commit -m "feat: [功能描述]"
git push origin feature/xxx

echo "=== CI/CD 將自動執行完整 Harness 驗證 ==="

## AI 輔助開發成熟度自我評估

### Prompt Engineering（每題 0-3 分）
1. 團隊是否有共用的 Prompt 模板？
2. 團隊成員是否接受過 Prompt 培訓？
3. 是否有 Prompt 效果評估機制？
4. 是否有禁止使用敏感資料的規範？

### Context Engineering（每題 0-3 分）
5. 是否有 copilot-instructions.md？
6. 是否有 ADR 文件機制？
7. 命名規範是否明確且統一？
8. Context 文件是否定期更新？
9. 是否使用 MCP Server 或 RAG？

### Harness Engineering（每題 0-3 分）
10. CI/CD 是否包含自動化測試？
11. 是否有架構驗證（如 ArchUnit）？
12. 是否有程式碼品質掃描？
13. 是否有安全性掃描？
14. 是否有 AI 使用治理政策？
15. 是否有監控與回饋機制？

### 評分標準
- 0-12 分：Level 1（臨時）
- 13-21 分：Level 2（可重複）
- 22-30 分：Level 3（已定義）
- 31-38 分：Level 4（已管理）
- 39-45 分：Level 5（最佳化）

跨系統 Context 繼承關係：
公司標準（company-standards/copilot-instructions.md）
  └── 產品線規範（banking-platform/copilot-instructions.md）
      ├── 核心銀行系統（core-banking/copilot-instructions.md）
      ├── CRM 系統（crm-system/copilot-instructions.md）
      └── 報表系統（reporting/copilot-instructions.md）

# 共用 CI/CD Template（.github/workflows/共用模板）
# reusable-ai-validation.yml
name: Reusable AI Code Validation

on:
  workflow_call:
    inputs:
      risk-level:
        required: true
        type: string  # core | business | utility
      java-version:
        required: false
        type: string
        default: '17'

jobs:
  basic-validation:
    # 所有系統都執行
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Compile
        run: mvn compile
      - name: Unit Tests
        run: mvn test

  architecture-validation:
    # core 和 business 系統執行
    if: inputs.risk-level == 'core' || inputs.risk-level == 'business'
    runs-on: ubuntu-latest
    steps:
      - name: ArchUnit Tests
        run: mvn test -Dtest="*ArchitectureTest"
      - name: SonarQube
        run: mvn sonar:sonar

  security-validation:
    # 僅 core 系統執行
    if: inputs.risk-level == 'core'
    runs-on: ubuntu-latest
    steps:
      - name: OWASP Check
        run: mvn dependency-check:check
      - name: SpotBugs Security
        run: mvn spotbugs:check
      - name: DAST Scan
        run: ./scripts/run-zap-scan.sh

標準開發流程：

1. 確認需求 → 更新 TASK.md
2. 開啟相關 Context 檔案（copilot-instructions.md、ADR、Interface）
3. 使用 Prompt Template 引導 AI 開發
4. AI 產出 → 自行初步 Review
5. 提交 PR → 自動化 Harness 驗證（ArchUnit + SonarQube + Test）
6. 通過驗證 → 人工 Code Review
7. 合併 → 部署

## 文件撰寫原則（供 AI 理解的文件格式）

1. **結構化**：使用清楚的標題層級和條列
2. **具體化**：要寫「使用 BigDecimal」而非「使用適當型別」
3. **範例化**：每條規則附上 Good/Bad 範例
4. **可機器讀取**：避免純敘述，多用表格、列表、程式碼區塊
5. **保持精簡**：Context Window 有限，文件要精準不冗贅

# [功能名稱] Prompt 模板

## 角色
你是 [角色描述]

## 技術棧
- [技術 1]
- [技術 2]

## 架構規範
- [規範 1]
- [規範 2]

## 任務
[具體任務描述]

## 輸出要求
- [要求 1]
- [要求 2]

## 範例
[參考範例]

## 角色
你是銀行核心系統資深 Java 工程師，熟悉 Clean Architecture。

## 任務
依照 Clean Architecture 開發 [功能名稱] API：
- Endpoint: [METHOD] [PATH]
- 功能：[描述]
- 商業規則：[規則列表]

## 輸出
請產出以下檔案：
1. Controller（Presentation Layer）
2. UseCase Interface + Implementation（Application Layer）
3. Domain Entity / Value Object（Domain Layer）
4. Repository Interface（Domain Layer）
5. 對應的 JUnit 測試

## 約束
- 使用 BigDecimal 處理金額
- 包含 @Valid 驗證
- 包含 JavaDoc
- 遵循 copilot-instructions.md 中的命名規範

## 角色
你是銀行系統資深架構師，專注於安全與效能。

## 任務
審查以下程式碼，檢查：
1. 安全性：SQL Injection, XSS, 敏感資訊洩漏
2. 效能：N+1 Query, 不必要的記憶體分配
3. 架構：是否符合 Clean Architecture 分層規範
4. 業務邏輯：金額計算是否使用 BigDecimal
5. 可維護性：命名是否清楚、職責是否單一

## 輸出格式
| 行號 | 嚴重度 | 類別 | 問題描述 | 建議修正 |

## 角色
你是 QA 工程師，擅長設計邊界測試案例。

## 任務
為 [類別名稱] 生成完整的 JUnit 5 測試，需涵蓋：
1. Happy Path（正常流程）
2. Edge Case（邊界值：null、空值、最大值、最小值）
3. Error Path（例外情境：餘額不足、帳戶不存在、超過限額）
4. Concurrent（併發情境，若適用）

## 技術要求
- 使用 @ExtendWith(MockitoExtension.class)
- Mock 外部依賴（Repository, 第三方 API）
- 使用 AssertJ 斷言
- 測試方法命名：should_[預期結果]_when_[條件]

## AI 產出審查 Checklist

### 安全性
- [ ] 無 SQL Injection 風險（使用 Parameterized Query）
- [ ] 無 XSS 風險（輸入已驗證、輸出已編碼）
- [ ] 無敏感資訊硬編碼（密碼、金鑰）
- [ ] 日誌中無敏感資料

### 架構合規
- [ ] 符合 Clean Architecture 分層
- [ ] Domain Layer 無外部依賴
- [ ] Controller 無商業邏輯

### 業務邏輯
- [ ] 金額使用 BigDecimal
- [ ] 涉及帳務的操作有交易控制
- [ ] 有完整的異動日誌

### 測試
- [ ] 有對應的單元測試
- [ ] 覆蓋率 ≥ 80%
- [ ] 包含邊界案例

### 效能
- [ ] 無 N+1 Query
- [ ] 批次操作使用 Batch Processing
- [ ] 大量資料使用分頁查詢

# AI 輔助開發月報 — [YYYY-MM]

## 📊 關鍵指標摘要

| 指標 | 本月 | 上月 | 變化 | 目標 |
|------|------|------|------|------|
| PR 合併平均時間 | 2.3 天 | 3.1 天 | ↓ 25.8% | < 3 天 |
| AI Acceptance Rate | 35% | 28% | ↑ 7% | ≥ 30% |
| Bug Rate (per KLOC) | 1.2 | 1.8 | ↓ 33.3% | < 2.0 |
| Code Coverage | 82% | 78% | ↑ 4% | ≥ 80% |
| Architecture Violations | 0 | 2 | ↓ 100% | 0 |
| Security Critical Issues | 0 | 0 | — | 0 |

## 📈 趨勢圖（建議使用 Grafana Dashboard）

## 💡 改善行動
- [行動 1]
- [行動 2]

## ⚠️ 待解決問題
- [問題 1]

// 錯誤
幫我寫一個 API

// 正確
使用 Java 17 + Spring Boot 3.2，依照 Clean Architecture 撰寫
帳戶查詢 API（GET /api/v1/accounts/{accountId}），
Controller 只做 HTTP 映射，商業邏輯放在 UseCase，
回傳 AccountResponse（含 accountId, balance, currency, status）。

// 錯誤 ⚠️
幫我連接資料庫，連線字串是 jdbc:postgresql://prod-db:5432/bank?user=admin&password=P@ssw0rd123

// 正確
幫我撰寫 Spring Boot 的資料庫連線設定，
使用環境變數 ${DB_URL}, ${DB_USERNAME}, ${DB_PASSWORD}

// 錯誤（直接複製貼上 AI 產出，不審查）
AI 說什麼就用什麼

// 正確
1. AI 產出 → 2. 理解程式碼邏輯 → 3. 對照規範檢查 → 4. 修正不合規之處 → 5. 提交

// 錯誤：將整個專案所有文件都塞進 Context
把所有 100+ 個 Java 檔案全部打開讓 Copilot 讀

// 正確：只提供與當前任務相關的 Context
開發轉帳 API 時，只開啟：
- TransferController.java
- TransferUseCase.java
- Account.java (Domain Model)
- copilot-instructions.md

// 錯誤
copilot-instructions.md 半年沒更新，
但團隊已從 Java 11 升到 Java 17，
AI 仍按照 Java 11 風格產出程式碼。

// 正確
設定定期（每月/每季）Review copilot-instructions.md
指定專人負責維護

// 錯誤
copilot-instructions.md 說用 UUID 當主鍵，
但 ADR-003 說用 BIGINT 自增主鍵。
AI 產出的程式碼時而 UUID 時而 BIGINT。

// 正確
維護單一事實來源（Single Source of Truth），
文件之間不能有矛盾。定期執行一致性 Review。

// 錯誤
AI 產出的程式碼直接 push，沒有 CI、沒有測試、沒有掃描。

// 正確
至少有：
1. 編譯檢查（mvn compile）
2. 單元測試（mvn test）
3. 架構測試（ArchUnit）
4. 程式碼品質（SonarQube）

// 錯誤
每次 PR 要跑 45 分鐘的完整掃描（含壓力測試、E2E、安全掃描），
導致開發效率極低。

// 正確
分層驗證：
- PR 階段：快速檢查（編譯 + 單元測試 + ArchUnit）< 5 分鐘
- Merge 後：完整掃描（SonarQube + 安全掃描）< 15 分鐘
- 部署前：E2E + 壓力測試 < 30 分鐘

// 錯誤
CI 失敗了，只顯示 "BUILD FAILED"，
開發者不知道哪裡違規，也不知道如何修正。

// 正確
失敗訊息應清楚指出：
- 哪條規則被違反
- 違規的程式碼位置
- 如何修正（提供修正建議或參考文件連結）

// 錯誤
copilot-instructions.md 要求使用 Clean Architecture，
但 CI/CD 中沒有 ArchUnit 測試來驗證。
AI 產出的程式碼可能違反分層規則，卻順利通過 CI。

// 正確
Context 中定義的每條架構規則，Harness 中都有對應的自動驗證：
- Context: "Controller 不做商業邏輯" → Harness: ArchUnit rule
- Context: "金額用 BigDecimal" → Harness: SpotBugs custom rule
- Context: "API 需 JWT 認證" → Harness: Security integration test

// 錯誤
半年前建立了 10 個 Prompt Template，但：
- 技術棧已從 Java 11 升到 Java 17
- 架構從 MVC 改為 Clean Architecture
- 模板仍然是舊版內容
團隊繼續使用舊模板，AI 產出的程式碼風格混亂

// 正確
建立 Template 維護機制：
1. 指定 Template Owner
2. 每次架構變更同步更新 Template
3. Template 版本控制（放在 Git 中）
4. 定期（每季）Review 所有 Template

// 錯誤
花了大量資源建立完整的 Context + Harness：
- copilot-instructions.md ✅
- ADR 文件 ✅
- ArchUnit + SonarQube + CI/CD ✅
但團隊成員不知道如何使用：
- 不知道有 Prompt Template
- 不知道有 copilot-instructions.md
- 不知道 CI 失敗該怎麼修
結果：工具利用率 < 20%

// 正確
1. 導入前：培訓計畫（至少 2 小時 Workshop）
2. 導入後：定期 Office Hour（每週 30 分鐘 Q&A）
3. 持續：建立內部 FAQ + Troubleshooting 文件
4. 量化：追蹤 Copilot Acceptance Rate 和模板使用率

// 錯誤（最危險的跨層 Anti-pattern）
1. 使用 Prompt 讓 AI 生成一段程式碼
2. 通過了 Context 規範的檢查（命名正確、結構正確）
3. 通過了 Harness 驗證（CI 綠燈）
4. Code Reviewer 因為「AI 寫的應該沒問題」而快速 Approve
5. 結果：程式碼中存在邏輯錯誤（如匯率計算方向反轉）

// 正確
三層驗證都通過後，人工 Review 仍然是必要的：
- 理解程式碼邏輯（不只看風格）
- 對照需求驗證業務邏輯
- 特別檢查 AI 常犯的邏輯反轉、邊界遺漏

目標：全員具備基本 AI 使用能力

✅ 完成 Copilot Chat 基礎培訓
✅ 建立 3-5 個常用 Prompt 模板
✅ 制定「AI 產出必須 Review」規則
✅ 禁止在 Prompt 中輸入敏感資料

目標：團隊有統一的 AI 使用規範

✅ 撰寫 copilot-instructions.md
✅ 建立 ADR 文件機制
✅ 設計命名規範與程式模板
✅ 建立 Prompt 模板庫
✅ 定期 Review Context 文件一致性

目標：AI 輔助開發有完整的驗證與治理

✅ 導入 ArchUnit 架構測試
✅ 整合 SonarQube 品質分析
✅ 建立 CI/CD 自動化驗證流程
✅ 導入 OWASP 安全掃描
✅ 建立 AI 使用治理政策
✅ 設定 MCP Server（視需求）

目標：AI 能力持續演進

🔄 定期 Review 並優化 Prompt 模板
🔄 更新 Context 文件
🔄 增強 Harness 驗證範圍
🔄 收集團隊回饋並改善流程
🔄 追蹤 AI 工具新功能並評估導入

年度 ROI = ((年度效益總額 - 年度成本總額) / 年度成本總額) × 100%

範例估算（20人團隊）：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
成本：
  Copilot 授權：$19 × 20 × 12 = $4,560/年
  建置成本（攤提）：$15,000/年
  維護成本：$12,000/年
  培訓成本：$5,000/年
  合計：$36,560/年

效益：
  生產力提升（保守估計 20%）：
    20 人 × $80,000 年薪 × 20% = $320,000/年
  Bug 減少（保守估計 15%）：
    100 bugs/年 × $500/bug × 15% = $7,500/年
  新人加速（平均加速 1 週）：
    3 新人/年 × $2,000/週 = $6,000/年
  合計：$333,500/年

ROI = ($333,500 - $36,560) / $36,560 × 100% = 812%
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

請幫我實作銀行定存利息計算邏輯，請一步一步思考：

第一步：分析需求
- 定存金額（principal）
- 存期（months）
- 年利率（annualRate）
- 計息方式：單利 vs 複利
- 提前解約的利率折扣

第二步：設計類別結構
- DepositCalculator 作為策略介面
- SimpleInterestCalculator 實作單利
- CompoundInterestCalculator 實作複利
- EarlyTerminationCalculator 處理提前解約

第三步：實作計算公式
- 單利：interest = principal × rate × time
- 複利：amount = principal × (1 + rate/n)^(n×t)

第四步：加入邊界條件
- 金額不得為負數
- 存期至少 1 個月
- 利率在合理範圍（0% - 20%）

請使用 Java 17 + Spring Boot 3.2 實作，
遵循 Clean Architecture 分層。

請依照以下範例風格，為 LoanApplication 建立 DTO 轉換：

範例 1：Account → AccountDTO
public record AccountDTO(
    String accountId,
    String accountType,
    BigDecimal balance,
    LocalDateTime lastUpdated
) {
    public static AccountDTO from(Account entity) {
        return new AccountDTO(
            entity.getId().value(),
            entity.getType().name(),
            entity.getBalance().amount(),
            entity.getLastUpdated()
        );
    }
}

範例 2：Customer → CustomerDTO
public record CustomerDTO(
    String customerId,
    String fullName,
    String email,
    String tier
) {
    public static CustomerDTO from(Customer entity) {
        return new CustomerDTO(
            entity.getId().value(),
            entity.getFullName(),
            entity.getEmail().value(),
            entity.getTier().name()
        );
    }
}

現在請為 LoanApplication 實體建立 LoanApplicationDTO，
LoanApplication 包含：loanId, applicantId, amount, term, 
status, applicationDate, approvedDate（可為 null）

開發帳戶餘額查詢 API，必須遵守以下約束：

【安全約束】
- ❌ 禁止在日誌中記錄完整帳號，只顯示末 4 碼
- ❌ 禁止在 URL 路徑中暴露帳號
- ✅ 必須驗證請求者有權存取該帳戶（RBAC）
- ✅ 必須實作 Rate Limiting（每秒 100 次/用戶）

【架構約束】
- Controller → UseCase → Repository 三層分離
- 使用 Value Object 包裝帳號、金額
- 所有外部呼叫必須有 Circuit Breaker（Resilience4j）
- 回應時間 < 200ms（P99）

【測試約束】
- 單元測試覆蓋率 > 80%
- 必須包含：正常查詢、無權限、帳戶不存在、服務中斷 四種測試案例

【技術棧】
- Java 17, Spring Boot 3.2, Spring Security 6
- 資料庫：PostgreSQL + Spring Data JPA

你是一位擁有 15 年金融系統經驗的首席架構師。
你正在審查一個 Junior 工程師提交的帳戶轉帳 Service：

[貼上程式碼]

請從以下角度進行 Code Review：
1. ACID 事務一致性：轉帳的原子性是否保證？
2. 併發控制：多人同時轉出是否會造成超額？
3. 安全性：有無 IDOR 或 Race Condition 風險？
4. 可觀測性：Log/Metrics/Tracing 是否足夠？
5. 效能：是否有 N+1 查詢或不必要的鎖？

對每個問題，請給出：
- 嚴重度（Critical / Major / Minor）
- 具體問題描述
- 修復建議（含程式碼）

我們需要為即時交易通知系統選擇訊息佇列方案。

請用以下步驟分析：

方案 A：使用 Apache Kafka
- 分析優點（至少 3 點）
- 分析缺點（至少 3 點）
- 適合的場景
- 營運複雜度評估

方案 B：使用 RabbitMQ
- 分析優點（至少 3 點）
- 分析缺點（至少 3 點）
- 適合的場景
- 營運複雜度評估

方案 C：使用 AWS SQS + SNS
- 分析優點（至少 3 點）
- 分析缺點（至少 3 點）
- 適合的場景
- 營運複雜度評估

基於以下條件選擇最佳方案：
- 每日交易量 50 萬筆
- 延遲要求 < 500ms
- 團隊只有 3 人維運
- 必須支援訊息重試與死信佇列

Layer 0（Always loaded）
├── copilot-instructions.md     # 專案規範、架構原則
├── 技術棧版本資訊              # Java 17, Spring Boot 3.2 等
└── 安全性基本要求              # 金融合規底線

Layer 1（Task-triggered）
├── .prompt.md                  # 任務特定的 Prompt 模板
├── 相關的 Domain Model         # 當前修改涉及的領域模型
└── API 規格                    # OpenAPI spec 片段

Layer 2（On-demand）
├── 相似案例的歷史程式碼         # 參考實作
├── 測試案例範例                # 測試風格指引
└── 架構決策記錄（ADR）         # 歷史決策的背景原因

<!-- .github/copilot-instructions.md (Layer 0) -->
# 全域 Context

## 架構原則
- Clean Architecture: Controller → UseCase → Domain → Infrastructure
- 所有 Domain Entity 必須是 Immutable

## 技術棧
- Java 17, Spring Boot 3.2, Spring Security 6
- PostgreSQL 15, Redis 7
- JUnit 5, Mockito 5, ArchUnit 1.2

## 安全要求
- 所有 API 必須 JWT 認證
- PII 資料 AES-256 加密
- SQL 參數化查詢，禁止字串串接

# .github/workflows/context-refresh.yml
name: Context Refresh Check

on:
  pull_request:
    paths:
      - 'pom.xml'
      - 'src/main/java/**/domain/**'
      - 'src/main/java/**/config/**'

jobs:
  check-context:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Check context staleness
        run: |
          # 比對 copilot-instructions.md 中的版本與 pom.xml
          POM_JAVA=$(grep -oP '<java.version>\K[^<]+' pom.xml)
          CONTEXT_JAVA=$(grep -oP 'Java \K\d+' .github/copilot-instructions.md)
          
          if [ "$POM_JAVA" != "$CONTEXT_JAVA" ]; then
            echo "::warning::Context 中的 Java 版本 ($CONTEXT_JAVA) 與 pom.xml ($POM_JAVA) 不一致！"
          fi
      
      - name: Notify on staleness
        if: failure()
        run: echo "請更新 .github/copilot-instructions.md 以反映最新架構變更"

專案結構：
.github/
├── copilot-instructions.md           # 全域共用
├── prompts/
│   ├── new-api-endpoint.prompt.md    # 開發新 API 時觸發
│   ├── bug-fix.prompt.md             # 修 Bug 時觸發
│   ├── security-review.prompt.md     # 安全審查時觸發
│   ├── database-migration.prompt.md  # DB 變更時觸發
│   └── performance-tuning.prompt.md  # 效能調校時觸發

<!-- .github/prompts/new-api-endpoint.prompt.md -->
---
mode: agent
description: "建立新的 REST API 端點"
---

## 任務 Context

你正在為銀行核心系統建立新的 API 端點。

### 必須遵循的 API 規範
- RESTful 命名：`/api/v1/{resource}`
- 統一回應格式：`ApiResponse<T>`
- HTTP Status: 200(成功), 400(驗證失敗), 401(未認證), 403(無權限), 404(不存在), 500(系統錯誤)

### 必須產出的檔案
1. Controller (src/main/java/.../controller/)
2. UseCase (src/main/java/.../usecase/)
3. Request/Response DTO (src/main/java/.../dto/)
4. Unit Tests (src/test/java/...)
5. Integration Test (src/test/java/.../integration/)

### 參考現有 API
@workspace 參考 AccountController 的實作風格

/**
 * ArchUnit 規則：驗證 Context 文件中的架構約束是否一致
 */
@AnalyzeClasses(packages = "com.tutorial")
public class ContextConsistencyTest {

    @ArchTest
    static final ArchRule context_claims_clean_architecture =
        classes().that().resideInAPackage("..controller..")
            .should().onlyDependOnClassesThat()
            .resideInAnyPackage(
                "..controller..", "..usecase..", "..dto..",
                "org.springframework..", "java.."
            )
            .as("copilot-instructions.md 宣稱 Clean Architecture，" +
                "Controller 不應直接依賴 Repository");

    @ArchTest
    static final ArchRule context_claims_immutable_domain =
        classes().that().resideInAPackage("..domain..")
            .should().haveOnlyFinalFields()
            .as("copilot-instructions.md 宣稱 Domain Entity 為 Immutable，" +
                "所有欄位應為 final");
}