# Amazon Q Developer Workshop - 提示詞工程

## 目錄

[1. 實驗環境準備](https://hackmd.io/@Zx9gc3B9R76nDuN1qqwwcA/HknuyDk--e)
[2. 基本功能介紹](https://hackmd.io/@Zx9gc3B9R76nDuN1qqwwcA/B1xH4Xeb-x)
[3. 提示詞工程](https://hackmd.io/@Zx9gc3B9R76nDuN1qqwwcA/B1v1v4l--e)
[4. 探索專案及文件生成](https://hackmd.io/@Zx9gc3B9R76nDuN1qqwwcA/SJ-sUOxWZx)
[5. 開發功能](https://hackmd.io/@Zx9gc3B9R76nDuN1qqwwcA/HyVLCOgZ-g)
[6. 生成測試](https://hackmd.io/@Zx9gc3B9R76nDuN1qqwwcA/rJROwse-Zl)
[7. 程式碼掃描](https://hackmd.io/@Zx9gc3B9R76nDuN1qqwwcA/SJzMislZbx)
[8. 轉換 SOAP 架構成 RESTFul 架構](https://hackmd.io/@Zx9gc3B9R76nDuN1qqwwcA/H1eag2l-Wl)

---

## Prompt Engineering 最佳實踐

### 具體且清晰 (Be specific and clear)

撰寫**具體且清晰**的提示詞對於獲得期望的回應至關重要，提示詞應該直接陳述任務並提供盡可能多的細節。

**清晰度**: 涉及提示詞的準確性和具體性。清晰的提示詞幾乎不留誤解的空間，引導 Amazon Q Developer 生成所需的特定類型回應或動作。缺乏清晰度可能導致不相關或偏離目標的回應。清晰的提示詞在程式碼生成輔助工具 (如 Amazon Q Developer) 中特別重要，因為需要精確的編碼解決方案。

**意圖**: 指提示詞背後的目的或目標。理解使用者的意圖使 Amazon Q Developer 能夠生成準確且與您的目標相關的回應。例如：如果意圖是生成一段程式碼來解決特定問題，提示詞應該清楚地反映該目標。當然，如果不希望 Amazon Q Developer 進行的操作，也可以透過明確提示來控制 Amazon Q Developer。

**上下文**: 涉及與提示詞相關的周圍資訊或環境。這包括檔案中程式碼的狀態等因素，可能是新檔案或包含現有程式碼的檔案，這會影響 Amazon Q Developer 如何處理任務。同樣，在同一聊天會話期間與 Amazon Q Developer 的過往互動也可以影響其回應。上下文使 Q 能夠提供更符合使用者當前需求的客製化回應。例如：Amazon Q Developer 對程式碼片段的回應會受到現有程式碼的影響，而在 Amazon Q Developer 的聊天介面中，對話歷史是關鍵的上下文元素。

### 使用範例 (Use examples)

透過包含相關範例來增強您的提示詞，因為這種策略透過提供額外的上下文來引導 Amazon Q Developer 產生更好的輸出。例如在生成程式碼段落時可以提供具體的撰寫方式，或是生成文件的樣版 (Template)，來讓 Amazon Q Developer 可以根據團隊內部的既有素材生成更符合預期的結果。

### 迭代方法 (Iterative approach)

根據回應來精煉和重新表述您的提示詞。這種迭代方法是實現期望結果的關鍵。這個過程的難易程度因使用的工具而異:例如：在 Amazon Q Developer 聊天視窗中，迭代很直接，因為您可以輕鬆地在聊天對話中提問。然而，Amazon Q Developer 的內嵌完成需要您返回並直接編輯原始提示詞/註解或程式碼。

### 拆解複雜查詢 (Breaking down complex queries)

對於複雜的工作任務，將提示詞拆解成更小、更易管理的部分可能很有效。這種方法有助於逐步引導 Amazon Q Developer 達到期望的輸出。

### 非確定性特性 (Non-deterministic nature)

生成式 AI 工具本質上是非確定性的。這意味著像 Amazon Q Developer 這樣的工具提供的回應或建議每次提出查詢時都可能不同，即使提示詞和上下文保持不變。因此，這些工具的輸出不是固定的而是動態的，反映了其訓練的最新狀態和提示詞的當前上下文。此外，隨著這些模型隨時間更新和改進，回應的性質也會改變。您應該為這種流動性做好準備，並理解生成的內容是指導性而非確定性答案。這種非確定性特質既是優勢 —提供了一系列可能性和新觀點，同時也是挑戰 —需要對每個回應進行評估和上下文考量。

## 實踐範例

現在我們已經探討了建立有效提示詞的關鍵原則，讓我們將這些概念付諸實踐。

### 範例一、開發 API

:::spoiler 範例說明
#### ❌ 不好的提示詞

寫一個 Spring API

#### ✅ 好的提示詞

建立一個 Spring Boot REST Controller
功能: 管理保險保單(Insurance Policy)
路徑: /api/policies
方法:
- GET /api/policies - 取得所有保單
- GET /api/policies/{id} - 取得單一保單
- POST /api/policies - 建立新保單
- PUT /api/policies/{id} - 更新保單
- DELETE /api/policies/{id} - 刪除保單

Policy 實體欄位:
- id: Long
- policyNumber: String (唯一)
- holderName: String
- coverageAmount: BigDecimal
- startDate: LocalDate
- endDate: LocalDate
- status: PolicyStatus (enum: ACTIVE, EXPIRED, CANCELLED)

要求:
- 使用 Spring Boot 3.x
- 使用 @RestController 和 @RequestMapping
- 使用 @Valid 驗證輸入
- 回傳適當的 HTTP 狀態碼
- 使用 ResponseEntity 包裝回應
- 加上 @Service 層處理業務邏輯
- 包含異常處理 (@ControllerAdvice)

**為什麼好?**
- 明確的 Spring Boot 版本
- 完整的 API 規格和路徑
- 清楚的實體結構和型別
- 指定 Spring 註解和最佳實踐
- 包含驗證和異常處理
:::

### 範例二、效能優化

:::spoiler 範例說明
#### ❌ 不好的提示詞

讓程式跑快一點

#### ✅ 好的提示詞

優化以下 Python 程式碼的效能:

def find_duplicates(data):
    duplicates = []
    for i in range(len(data)):
        for j in range(i + 1, len(data)):
            if data[i] == data[j] and data[i] not in duplicates:
                duplicates.append(data[i])
    return duplicates

問題: 處理 10 萬筆資料時執行時間過長

優化目標:
- 降低時間複雜度(目前 O(n²))
- 使用更有效率的資料結構
- 保持相同的功能(找出重複元素)
- 說明優化前後的時間複雜度差異
- 提供效能比較說明

**為什麼好?**
- 提供原始程式碼和問題描述
- 明確的效能問題(資料量、執行時間)
- 具體的優化目標
- 要求保持功能一致
- 要求說明和比較
:::

### 範例三、異常處理
:::spoiler 範例說明
Java 異常處理

#### ❌ 不好的提示詞

加上 try-catch

#### ✅ 好的提示詞

為以下 Java 方法建立完整的異常處理機制:

public Policy createPolicy(PolicyDTO policyDTO) {
    Policy policy = policyMapper.toEntity(policyDTO);
    return policyRepository.save(policy);
}

要求:
1. 建立自訂異常類別:
   - PolicyAlreadyExistsException (保單號碼重複)
   - InvalidPolicyDataException (資料驗證失敗)
   - PolicyServiceException (一般服務錯誤)

2. 建立全域異常處理器 (@ControllerAdvice):
   - 處理自訂異常
   - 處理 MethodArgumentNotValidException (驗證錯誤)
   - 處理 DataIntegrityViolationException (資料庫約束)
   - 處理一般 Exception

3. 錯誤回應格式:
   - timestamp: LocalDateTime
   - status: int
   - error: String
   - message: String
   - path: String

4. 在 service 方法中加上適當的異常處理和拋出
5. 使用 SLF4J 記錄錯誤日誌
6. 回傳適當的 HTTP 狀態碼

**為什麼好?**
- 提供原始程式碼上下文
- 明確的異常類別需求
- 完整的異常處理架構
- 指定錯誤回應格式
- 包含日誌記錄需求
:::

---

## 總結

> [!Tip]
> **「在限定的範圍，以明確的描述結合足夠的上下文，來迭代完成功能」。**

**有效提示詞的關鍵要素**:
1. ✅ **具體明確**: 指定語言、框架、版本
2. ✅ **提供上下文**: 資料結構、現有程式碼、專案需求
3. ✅ **詳細需求**: 功能、限制、邊界情況
4. ✅ **預期輸出**: 格式、型別、回傳值
5. ✅ **最佳實踐**: 錯誤處理、測試、文件
6. ✅ **迭代改善**: 逐步完善，持續優化