# 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)

---

### 對話視窗 (Chat Tab)

對話視窗是 Amazon Q Developer 的核心互動介面,讓開發者可以用**自然語言**與 AI 助理進行對話,獲得程式碼建議、技術解答和開發協助。


#### VS Code
- **側邊欄**: 點擊左側的 Q 圖示
- **命令面板**: `Cmd/Ctrl + Shift + P` → 輸入 "Amazon Q: Open Chat"

#### CLI

q chat

#### 功能特性
:::spoiler 說明
##### 多輪對話
- 支援連續對話，保持上下文
- 可以追問、澄清或深入探討
- Amazon Q Developer 會記住對話歷史

##### 新增對話
- 點擊 "New Chat" 開始新的對話主題
- 每個對話獨立，不會互相干擾

##### 對話歷史
- 對話會自動儲存
- 可以回顧之前的對話內容
- 方便追蹤開發過程

##### 清除對話
- 需要重新開始時可以清除對話
- 清除後 Amazon Q Developer 不會記住之前的上下文
:::

> [!Tip] 對話管理
> - 基於 Foundation Model 的上下文限制，每個對話會有 Token 上限的問題。例如：Claude Sonnet 為 200K Tokens。但即便是未達到上下文限制，有時我們仍會觀察到回應的內容逐漸不精確，這是由於模型本身會有注意力的問題。
> - 因此經驗上我們在使用 Amazon Q Developer 時會將大任務拆分成小任務，並且在不同的對話視窗中進行。
> - 但不同對話視窗中的上下文是不會相互傳遞的，所以我們可以透過檔案的方式來進行上下文交換，以此來避免上下文限制同時又能完成整體任務。

---

### 規則文件 (Rules)

Rules 是 Amazon Q Developer 的一個強大功能，讓你可以設定 **持續性的指引和規範**，Amazon Q Developer 在每次回應時都會自動參考這些規則。

#### 主要用途
:::spoiler 說明
##### 1. 程式碼風格規範
- 統一團隊的程式碼撰寫風格
- 例如：縮排方式、命名規則、註解格式

#### 2. 專案特定需求
- 設定專案使用的技術堆疊
- 例如:使用 TypeScript、React 18、AWS CDK v2

#### 3. 最佳實踐
- 強制執行安全性規範
- 例如：不在程式碼中硬編碼密鑰、使用參數化查詢防止 SQL Injection

#### 4. 組織政策
- 遵循公司的開發標準
- 例如：必須包含錯誤處理、需要撰寫單元測試
:::

1. 點選對話視窗中的 **「Rules」** 後，點選 **「Create a new rule」**

2. 輸入規則名稱（此處以 **language** 舉例）後點選 **「Create」**

3. 編輯 **「規則內容」** 後儲存。

請在所有對話中以繁體中文進行對話，但在撰寫、修改程式時使用英文。


> [!Tip] 使用 Rules 的好處
>
> ✅ **一致性**: 確保整個專案的程式碼風格統一
> ✅ **效率**: 不需要每次都重複說明相同的要求
> ✅ **品質**: 自動遵循最佳實踐和安全規範
> ✅ **協作**: 團隊成員都遵循相同的開發標準
> ✅ **彈性**: 可以針對不同專案設定不同的規則
>
> ##### 實際應用場景
> - **場景 1: 新團隊成員加入**
新成員使用 Amazon Q Developer 時,會自動遵循團隊的程式碼規範,快速融入開發流程。
> - **場景 2: 多專案管理**
不同專案有不同的技術堆疊和規範,Rules 確保 Q Developer 在各專案中提供正確的建議。

---

### `/` 功能


#### `/transform`

- 可用來進行 Java 版本升級轉換，但相對功能較不彈性，建議以 Prompt 形式進行。
- 每月有 4,000 line-of-code (LOC) 額度，超過會以每行 $0.003 USD 計價。
- 同個 AWS Organization 下的席次可以分享每月 4,000 行的額度。

#### `/clear`

- 清除對話，同關閉對話視窗。

#### `/compact`

- 用於壓縮和精簡對話歷史,釋放 token 空間，讓你可以在同一個對話中繼續進行更多互動。
- **不可逆操作**: 壓縮後無法還原完整歷史
- **可能遺失細節**: 某些詳細說明可能被移除

> [!tip]
> **重要的程式碼、中介資訊或產出的文件，應該儲存到檔案中**

---

### `@` 關鍵字

`@` 關鍵字是 Amazon Q Developer 的**上下文參考功能**，讓你可以在對話中明確指定要參考的檔案、資料夾或工作區內容，使 Amazon Q Developer 提供更精準、更符合專案脈絡的建議。


#### 1. `@workspace` 參考整個工作區的內容

**用途**:
- 了解專案整體架構
- 跨檔案的重構建議
- 專案層級的問題分析

**範例**:

@workspace 請說明這個專案

#### 2. `@file` 參考特定檔案

**用途**:
- 分析特定檔案的程式碼
- 針對檔案提供優化建議
- 解釋檔案的功能

**範例**:

@pom.xml 請說明這個檔案的內容

#### 3. `@folder` 參考特定資料夾

**用途**:
- 分析模組或功能區塊
- 檢查資料夾內的一致性
- 重構整個模組

**範例**:

@gamecontroller.java 請說明這個檔案的內容

> [!Tip] 使用 @ 的好處
> ✅ 直接參考專案中的檔案
> ✅ Q Developer 理解專案上下文
> ✅ 獲得更精準、更相關的建議
> ✅ 節省複製貼上的時間

---

### Workspace Index


Amazon Q Developer 的 Workspace Index(工作區索引) 是一個強大的功能，其主要用途包括:

#### 核心功能

建立專案知識庫
- 自動掃描和索引整個工作區的程式碼
- 分析專案結構、檔案關係和程式碼模式
- 建立專案的語義理解模型

#### 主要用途

##### 1. 提升上下文理解
- Amazon Q Developer 能更準確理解專案的整體架構
- 提供更符合專案風格和慣例的建議
- 理解跨檔案的依賴關係和資料流

##### 2. 智慧程式碼建議
- 根據專案現有程式碼提供一致的命名和風格
- 參考專案中類似的實作模式
- 避免與現有程式碼衝突

##### 3. 快速導航和搜尋
- 使用 `@workspace` 快速查詢專案資訊
- 找出特定功能或模式在專案中的位置
- 分析程式碼使用情況和影響範圍

##### 4. 重構支援
- 理解修改對整個專案的影響
- 提供跨檔案的重構建議
- 確保重構的一致性

#### 運作方式

1. 自動索引: 開啟專案時自動在背景建立索引
2. 即時更新: 程式碼變更時增量更新索引
3. 智慧快取: 儲存索引以加快後續存取速度

#### 實際效益

✅ 1. 更精準的程式碼補全
✅ 2. 更相關的聊天回應
✅ 3. 更快的專案理解
✅ 4. 更好的重構建議
✅ 5. 減少手動搜尋時間