.prompt.md 深度解說指南

使用者每次都要重新輸入:
"幫我檢查這個 API 的錯誤處理、參數驗證、回傳格式..."

使用者只需輸入:
#prompt:api-review

<!-- 檔案路徑: .github/prompts/your-template.prompt.md -->

[可選的模板說明區塊]

{主要提示內容}
- 使用 #file: 引用檔案
- 使用 #symbol: 引用程式符號
- 使用 #prompt: 組合其他模板

[可選的步驟或檢查清單]

#file:相對或絕對路徑

分析 #file:src/main/java/com/bpaas/creditcontrol/service/CreditService.java 的實作

比較以下檔案的差異:
- 主要實作: #file:src/service/UserService.java
- 基底類別: #file:src/service/BaseService.java
- 測試檔案: #file:src/test/java/UserServiceTest.java

#symbol:ClassName.methodName
#symbol:functionName

重構 #symbol:CreditService.calculateCredit 方法,遵循以下原則:
1. 單一職責
2. 依賴注入
3. 錯誤處理

#prompt:template-name

<!-- base-java-review.prompt.md -->
檢查 Java 程式碼的:
- 命名規範
- 例外處理
- 註解完整性

<!-- api-review.prompt.md -->
首先執行基本檢查:
#prompt:base-java-review

然後額外檢查 API 專屬項目:
- RESTful 設計原則
- HTTP 狀態碼使用
- 請求/回應格式

#selection

<!-- code-explain.prompt.md -->
請詳細說明 #selection 的邏輯:

## 分析項目:
1. 輸入參數的作用
2. 核心演算法步驟
3. 回傳值的意義
4. 潛在的邊界條件

請用中文回答,並附上流程圖。

通用層 (base-*.prompt.md)
    ↓ 被引用
領域層 (java-*, api-*, security-*)
    ↓ 被引用
專案層 (credit-service-review.prompt.md)

檢查 src/main/java/UserService.java 是否符合規範

檢查 #file:{USER_SPECIFIED_FILE} 是否符合:
- #file:docs/coding-standards.md
- #file:.github/instructions/java.instructions.md

<!-- 檔案: .github/prompts/code-review.prompt.md -->

# 程式碼審查檢查清單

請對 #selection 或 #file:{TARGET_FILE} 進行全面審查:

## 1. 程式碼品質
- [ ] 命名是否清晰且符合規範?
- [ ] 是否有重複的程式碼 (DRY 原則)?
- [ ] 函式長度是否合理 (建議 < 50 行)?
- [ ] 是否有過深的巢狀結構 (建議 < 4 層)?

## 2. 錯誤處理
- [ ] 是否捕獲所有可能的例外?
- [ ] 錯誤訊息是否足夠詳細?
- [ ] 是否有適當的日誌記錄?
- [ ] 是否避免吞掉例外 (empty catch block)?

## 3. 效能考量
- [ ] 是否有不必要的資料庫查詢?
- [ ] 迴圈內是否有昂貴的操作?
- [ ] 是否有記憶體洩漏風險?
- [ ] 是否適當使用快取?

## 4. 安全性
- [ ] 使用者輸入是否經過驗證?
- [ ] 是否有 SQL 注入風險?
- [ ] 敏感資訊是否加密?
- [ ] 是否有適當的權限檢查?

## 5. 測試性
- [ ] 是否容易進行單元測試?
- [ ] 依賴是否透過介面注入?
- [ ] 是否有測試涵蓋核心邏輯?

## 參考標準
- 專案規範: #file:docs/coding-standards.md
- 類似實作: #file:{REFERENCE_FILE}

請以表格形式列出發現的問題,並提供具體的改進建議。

1. 選取要審查的程式碼
2. 在 Chat 輸入: #prompt:code-review
3. (可選) 指定 {TARGET_FILE} 和 {REFERENCE_FILE}

<!-- 檔案: .github/prompts/api-design-review.prompt.md -->

# RESTful API 設計審查

審查 #selection 的 API 設計,確保符合 RESTful 最佳實踐。

## 1. HTTP 方法語意
檢查以下對應是否正確:

| 操作 | 正確方法 | 冪等性 |
|------|---------|-------|
| 查詢資源 | GET | 是 |
| 建立資源 | POST | 否 |
| 更新資源 (全部) | PUT | 是 |
| 更新資源 (部分) | PATCH | 否 |
| 刪除資源 | DELETE | 是 |

**檢查項目:**
- [ ] GET 請求不應修改資源
- [ ] POST 用於建立而非更新
- [ ] PUT 是否提供完整資源
- [ ] DELETE 是否需要請求主體

## 2. URL 設計
**正確範例:**

**檢查項目:**
- [ ] 使用複數名詞 (users 而非 user)
- [ ] 避免動詞 (❌ /getUser, ✅ /users)
- [ ] 使用階層結構 (/users/{id}/orders)
- [ ] 保持 URL 簡潔 (避免過深巢狀)

## 3. HTTP 狀態碼
檢查回應是否使用正確的狀態碼:

| 情境 | 狀態碼 | 說明 |
|------|--------|------|
| 成功查詢 | 200 OK | 回傳資源 |
| 成功建立 | 201 Created | 回傳新資源和 Location header |
| 成功更新 | 200 OK | 回傳更新後的資源 |
| 成功刪除 | 204 No Content | 不回傳內容 |
| 參數錯誤 | 400 Bad Request | 回傳錯誤詳情 |
| 未授權 | 401 Unauthorized | 需要認證 |
| 禁止存取 | 403 Forbidden | 已認證但無權限 |
| 資源不存在 | 404 Not Found | 找不到資源 |
| 伺服器錯誤 | 500 Internal Server Error | 系統錯誤 |

## 4. 請求/回應格式
檢查資料結構:

**請求範例:**
```json
POST /api/users
Content-Type: application/json

{
  "username": "john_doe",
  "email": "john@example.com",
  "role": "admin"
}

201 Created
Location: /api/users/123

{
  "id": 123,
  "username": "john_doe",
  "email": "john@example.com",
  "role": "admin",
  "createdAt": "2025-11-26T10:30:00Z"
}

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Email format is invalid",
    "details": [
      {
        "field": "email",
        "issue": "Must be a valid email address"
      }
    ],
    "timestamp": "2025-11-26T10:30:00Z",
    "path": "/api/users"
  }
}

---

### 範例 3: 重構建議模板

```markdown
<!-- 檔案: .github/prompts/refactor-suggestion.prompt.md -->

# 程式碼重構建議

針對 #selection 提供重構建議,目標是提升程式碼的可維護性、可讀性和效能。

## 重構前分析

### 1. 識別 Code Smells
檢查以下常見問題:
- [ ] **Long Method** - 方法過長 (> 50 行)
- [ ] **Large Class** - 類別過大 (> 500 行)
- [ ] **Long Parameter List** - 參數過多 (> 5 個)
- [ ] **Duplicated Code** - 重複的程式碼
- [ ] **Dead Code** - 未使用的程式碼
- [ ] **Speculative Generality** - 過度設計
- [ ] **Feature Envy** - 過度依賴其他類別
- [ ] **Data Clumps** - 總是一起出現的資料群

### 2. 設計原則檢查
評估是否違反以下原則:
- [ ] **SOLID 原則**
  - Single Responsibility (單一職責)
  - Open/Closed (開放封閉)
  - Liskov Substitution (里氏替換)
  - Interface Segregation (介面隔離)
  - Dependency Inversion (依賴反轉)
- [ ] **DRY** - Don't Repeat Yourself
- [ ] **KISS** - Keep It Simple, Stupid
- [ ] **YAGNI** - You Aren't Gonna Need It

## 重構策略

### 步驟 1: 優先級排序
根據以下標準排序:
1. **影響範圍** - 影響多少其他程式碼
2. **風險程度** - 重構的風險高低
3. **效益評估** - 改善的程度

### 步驟 2: 選擇重構技巧
常用技巧:

| 技巧 | 適用情境 | 範例 |
|------|---------|------|
| Extract Method | 方法過長 | 將重複邏輯抽出為獨立方法 |
| Extract Class | 類別職責過多 | 將部分職責移至新類別 |
| Introduce Parameter Object | 參數過多 | 用物件封裝參數 |
| Replace Magic Number | 硬編碼常數 | 使用命名常數 |
| Replace Conditional with Polymorphism | 複雜條件判斷 | 用策略模式替換 |

### 步驟 3: 確保測試涵蓋
- [ ] 重構前執行所有測試
- [ ] 小步重構,每步執行測試
- [ ] 重構後測試應全數通過

## 輸出格式

### 1. 問題總結

### 2. 詳細建議
對每個問題提供:

**問題 1: [問題名稱]**
- **位置**: 第 X-Y 行
- **類型**: [Code Smell 類型]
- **影響**: [說明影響]
- **重構技巧**: [使用的技巧]
- **重構前程式碼**:
  ```java
  // 原始程式碼
  ```
- **重構後程式碼**:
  ```java
  // 改進後程式碼
  ```
- **改善點**:
  - 降低複雜度
  - 提升可讀性
  - 更容易測試

### 3. 執行計畫
```markdown
## Phase 1: 低風險重構 (建議先做)
1. [ ] 重構項目 A
2. [ ] 重構項目 B

## Phase 2: 中風險重構
1. [ ] 重構項目 C

## Phase 3: 高風險重構 (需要充分測試)
1. [ ] 重構項目 D

---

### 範例 4: 測試生成模板

```markdown
<!-- 檔案: .github/prompts/generate-tests.prompt.md -->

# 單元測試生成

為 #selection 生成完整的單元測試,確保測試品質和覆蓋率。

## 測試框架
- **Java**: JUnit 5 + Mockito
- **JavaScript**: Jest
- **Python**: pytest
- **C#**: xUnit

## 測試結構

### 1. 測試類別命名
```java
// 被測試類別: UserService.java
// 測試類別: UserServiceTest.java

public class UserServiceTest {
    // 測試方法
}

@Test
void givenValidUser_whenCreateUser_thenReturnsCreatedUser() {
    // Arrange (Given)
    // Act (When)
    // Assert (Then)
}

@Test
void shouldThrowExceptionWhenEmailIsInvalid() {
    // ...
}

@Test
void shouldReturnUserWhenIdExists() {
    // Given
    Long userId = 1L;
    User expectedUser = new User(userId, "John");
    when(userRepository.findById(userId)).thenReturn(Optional.of(expectedUser));

    // When
    User actualUser = userService.getUserById(userId);

    // Then
    assertThat(actualUser).isEqualTo(expectedUser);
    verify(userRepository).findById(userId);
}

@Test
void shouldHandleEmptyEmailGracefully() {
    assertThrows(ValidationException.class, 
        () -> userService.createUser("", "password"));
}

@Test
void shouldThrowNotFoundExceptionWhenUserDoesNotExist() {
    // Given
    Long userId = 999L;
    when(userRepository.findById(userId)).thenReturn(Optional.empty());

    // When & Then
    assertThrows(NotFoundException.class, 
        () -> userService.getUserById(userId));
}

@ExtendWith(MockitoExtension.class)
class UserServiceTest {

    @Mock
    private UserRepository userRepository;

    @Mock
    private EmailService emailService;

    @InjectMocks
    private UserService userService;

    // 測試方法...
}

package com.example.service;

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

@ExtendWith(MockitoExtension.class)
class {ClassName}Test {

    @Mock
    private {Dependency1} dependency1;

    @InjectMocks
    private {ClassName} target;

    @BeforeEach
    void setUp() {
        // 初始化
    }

    @Nested
    @DisplayName("{Method1} 測試")
    class Method1Tests {
        // 相關測試方法分組
    }

    // 其他測試...
}

## 測試覆蓋率總結
- 行覆蓋率: 85%
- 分支覆蓋率: 78%
- 方法覆蓋率: 100%

## 生成的測試案例
1. ✅ {測試名稱 1} - 測試 {功能描述}
2. ✅ {測試名稱 2} - 測試 {邊界條件}
3. ✅ {測試名稱 3} - 測試 {異常處理}

## 未覆蓋的部分
- 第 45-50 行: {原因說明}

---

### 範例 5: 效能優化模板

```markdown
<!-- 檔案: .github/prompts/performance-optimization.prompt.md -->

# 效能優化分析

分析 #selection 的效能瓶頸並提供優化建議。

## 分析維度

### 1. 時間複雜度分析
識別演算法複雜度:

| 複雜度 | 說明 | 範例 |
|--------|------|------|
| O(1) | 常數時間 | HashMap.get() |
| O(log n) | 對數時間 | 二元搜尋 |
| O(n) | 線性時間 | 陣列遍歷 |
| O(n log n) | 線性對數 | 快速排序 |
| O(n²) | 平方時間 | 雙層迴圈 |
| O(2ⁿ) | 指數時間 | 遞迴費氏數列 |

**檢查項目:**
- [ ] 是否有巢狀迴圈?
- [ ] 是否可用更高效的資料結構?
- [ ] 是否可用快取減少重複計算?

### 2. 空間複雜度分析
評估記憶體使用:
- [ ] 是否有不必要的物件建立?
- [ ] 是否可重用現有物件?
- [ ] 是否有記憶體洩漏風險?
- [ ] 集合大小是否預先指定?

### 3. 資料庫查詢優化
SQL 效能檢查:

**N+1 查詢問題:**
```java
❌ 效能差:
List<User> users = userRepository.findAll();
for (User user : users) {
    List<Order> orders = orderRepository.findByUserId(user.getId()); // N 次查詢
}

✅ 優化:
List<User> users = userRepository.findAllWithOrders(); // 1 次查詢 (JOIN FETCH)

應用層快取 (Caffeine, Guava Cache)
    ↓ 未命中
分散式快取 (Redis, Memcached)
    ↓ 未命中
資料庫查詢

❌ 效能差: 使用 List 查找
List<String> items = new ArrayList<>();
boolean exists = items.contains("target"); // O(n)

✅ 優化: 使用 Set
Set<String> items = new HashSet<>();
boolean exists = items.contains("target"); // O(1)

❌ 提前載入所有資料:
class Report {
    private List<BigData> data = loadAllData(); // 不管是否使用都載入
}

✅ 延遲載入:
class Report {
    private Supplier<List<BigData>> dataSupplier = this::loadAllData;

    public List<BigData> getData() {
        return dataSupplier.get(); // 使用時才載入
    }
}

❌ 循序處理:
List<Result> results = new ArrayList<>();
for (Task task : tasks) {
    results.add(process(task)); // 循序執行
}

✅ 平行處理:
List<Result> results = tasks.parallelStream()
    .map(this::process)
    .collect(Collectors.toList());

❌ 逐筆插入:
for (User user : users) {
    userRepository.save(user); // N 次資料庫往返
}

✅ 批次插入:
userRepository.saveAll(users); // 1 次批次操作

@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.MICROSECONDS)
public class PerformanceBenchmark {

    @Benchmark
    public void testOriginalMethod() {
        // 原始實作
    }

    @Benchmark
    public void testOptimizedMethod() {
        // 優化後實作
    }
}

## 發現 {N} 個效能問題

### 嚴重問題 (P0)
- [ ] **問題 1**: {描述}
  - 位置: 第 X 行
  - 當前複雜度: O(n²)
  - 影響: 大資料量下回應時間超過 10 秒

### 中等問題 (P1)
- [ ] **問題 2**: {描述}

### 輕微問題 (P2)
- [ ] **問題 3**: {描述}

// 效能差的程式碼

// 優化後的程式碼

// 效能測試程式碼

## 優化優先級

### 立即執行 (本週)
1. [ ] 修復 N+1 查詢問題 (預估改善 5x)
2. [ ] 新增資料庫索引 (預估改善 3x)

### 短期執行 (本月)
3. [ ] 實作快取機制
4. [ ] 優化演算法複雜度

### 長期規劃 (本季)
5. [ ] 考慮使用非同步處理
6. [ ] 評估微服務拆分

---

## 進階技巧

### 1. 組合式模板 (Compositional Templates)

**基礎模板:**
```markdown
<!-- base-checks.prompt.md -->
檢查基本程式碼品質:
- 命名規範
- 註解完整性
- 例外處理

<!-- comprehensive-review.prompt.md -->
執行全面審查:

## 步驟 1: 基本檢查
#prompt:base-checks

## 步驟 2: 安全性檢查
#prompt:security-audit

## 步驟 3: 效能檢查
#prompt:performance-check

## 最終報告
綜合以上所有檢查結果,提供優先級排序的改進清單。

<!-- smart-review.prompt.md -->
根據檔案類型執行不同檢查:

**如果是 Controller:**
- 執行 #prompt:api-design-review

**如果是 Service:**
- 執行 #prompt:business-logic-review

**如果是 Repository:**
- 執行 #prompt:database-query-review

**如果是 Entity:**
- 執行 #prompt:data-model-review

請根據 #file:{TARGET_FILE} 的類型選擇對應的檢查。

<!-- custom-review.prompt.md -->
# 客製化審查

請審查 #file:{TARGET_FILE} 並聚焦於以下方面:

## 檢查項目 (請填寫)
1. {FOCUS_AREA_1}
2. {FOCUS_AREA_2}
3. {FOCUS_AREA_3}

## 比較基準 (可選)
- 參考實作: #file:{REFERENCE_FILE}
- 專案規範: #file:{STANDARD_FILE}

## 輸出格式
- 詳細程度: {DETAIL_LEVEL} (簡要/詳細/非常詳細)
- 語言: {LANGUAGE} (中文/英文)
- 包含程式碼範例: {INCLUDE_CODE} (是/否)

執行審查並依照指定格式回答。

#prompt:custom-review

{TARGET_FILE} = src/service/PaymentService.java
{FOCUS_AREA_1} = 交易安全性
{FOCUS_AREA_2} = 錯誤回滾機制
{FOCUS_AREA_3} = 日誌完整性
{DETAIL_LEVEL} = 詳細
{LANGUAGE} = 中文
{INCLUDE_CODE} = 是

<!-- feature-implementation.prompt.md -->
# 功能實作流程

## 階段 1: 規劃 (Planning)
#prompt:feature-planning

**暫停點:** 請使用者確認規劃後再繼續

## 階段 2: 實作 (Implementation)
根據確認的計畫,實作以下檔案:
1. Entity: #file:src/entity/{ENTITY_NAME}.java
2. Repository: #file:src/repository/{ENTITY_NAME}Repository.java
3. Service: #file:src/service/{ENTITY_NAME}Service.java
4. Controller: #file:src/controller/{ENTITY_NAME}Controller.java

每個檔案遵循 #prompt:code-generation-standard

**暫停點:** 請使用者檢視生成的程式碼

## 階段 3: 測試 (Testing)
#prompt:generate-tests

針對所有生成的 Service 和 Controller 建立測試

**暫停點:** 執行測試並報告結果

## 階段 4: 文件 (Documentation)
更新以下文件:
- API 文件: #file:docs/api/
- 架構圖: #file:docs/architecture.md
- CHANGELOG: #file:CHANGELOG.md

## 完成檢查清單
- [ ] 所有程式碼已生成
- [ ] 測試全數通過
- [ ] 文件已更新
- [ ] Code Review 已完成

<!-- smart-code-explain.prompt.md -->
# 智慧程式碼說明

分析 #selection 並提供客製化說明:

## 自動偵測
1. **程式語言**: {自動偵測}
2. **程式碼類型**: {自動判斷: 函式/類別/配置/測試}
3. **複雜度**: {自動評估: 簡單/中等/複雜}

## 說明內容 (根據複雜度調整)

### 如果是簡單程式碼:
- 一句話總結功能
- 輸入/輸出說明
- 使用範例

### 如果是中等複雜度:
- 功能描述
- 邏輯流程圖
- 主要步驟分解
- 潛在問題提醒

### 如果是複雜程式碼:
- 詳細功能說明
- 完整流程圖 (Mermaid)
- 逐行邏輯說明
- 設計模式識別
- 優化建議
- 相關文件連結: #file:docs/

## 相關程式碼
自動搜尋並列出:
- 被此程式碼呼叫的方法
- 呼叫此程式碼的位置
- 類似的實作範例

請用{使用者偏好語言}回答。

# {專案名稱} 程式碼審查

## 專案特定檢查
- [ ] {專案規則 1}
- [ ] {專案規則 2}

## 通用檢查
#prompt:base-code-review

## 參考文件
- #file:{專案規範文件}
- #file:{架構設計文件}

<!-- feature-delivery-checklist.prompt.md -->

# 功能交付檢查清單

## 1. 程式碼品質
#prompt:code-review

## 2. 測試覆蓋
#prompt:test-coverage-check

## 3. 效能驗證
#prompt:performance-check

## 4. 安全性審核
#prompt:security-audit

## 5. 文件完整性
- [ ] API 文件已更新
- [ ] README 已更新
- [ ] CHANGELOG 已記錄

## 6. 部署準備
- [ ] 環境變數已設定
- [ ] 資料庫遷移腳本已準備
- [ ] 回滾計畫已確認

請逐項檢查並報告結果。