Skip to content

Commit 07d6b2c

Browse files
yulin0629yulin0629
committed
feat: 完成場景4-8的完整重新設計和教學分支管理系統
重新設計核心功能： - 場景4 (Agent 30%): 智能偵錯助手 - 含10個Bug的購物車系統，展示Agent系統性診斷能力 - 場景5 (Agent 50%): 測試策略師 - 20+函數的數據分析工具，Agent自主設計測試架構 - 場景6 (Agent 60%): 重構架構師 - 300+行遺留系統，Agent主導完整重構和現代化 - 場景7 (Agent 80%): 文檔大師 - API系統文檔生成，Agent創建完整技術文檔體系 - 場景8 (Agent 90%): 專案總監 - 端到端SaaS開發，Agent完全主導專案開發流程 教學基礎設施： - 建立完整的分支管理系統 (scripts/setup-lesson.sh, TEACHING.md) - 新增GitHub Actions工作流程 (.github/workflows/deploy-pages.yml) - 建立教學指令和提示檔案系統 (.github/instructions/, .github/prompts/) - 優化VS Code工作區配置 (.vscode/settings.json) 視覺化學習體驗： - 每個場景都包含完整的HTML/CSS/JS展示頁面 - 可在瀏覽器直接體驗Agent修復/改進的效果 - 漸進式Agent能力展示 (30% → 90%) - 統一的教學劇本和最佳實踐指導 這完成了GitHub Copilot教學專案的核心架構，提供完整的Agent模式學習體驗。
1 parent 1cf6668 commit 07d6b2c

36 files changed

Lines changed: 5422 additions & 1051 deletions

‎.github/instructions/agent-mode.instructions.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Agent 模式專用指令
2+
3+
## Agent 模式工作原則
4+
- Agent 應該**自主規劃**多步驟任務
5+
- 能夠**分析問題**並制定執行策略
6+
- 自動**選擇合適的檔案**進行修改
7+
- 主動**執行必要的終端命令**
8+
- 具備**自我修正**能力，發現錯誤時自動改進
9+
10+
## 任務分解要求
11+
### Agent 收到任務時應該：
12+
1. **分析需求**：理解使用者的完整意圖
13+
2. **制定計劃**：將複雜任務分解為可執行步驟
14+
3. **評估影響**：考慮修改對其他檔案的影響
15+
4. **執行順序**：按邏輯順序執行各個步驟
16+
5. **驗證結果**：確保每個步驟正確完成
17+
18+
## 自主決策能力
19+
### Agent 應該能夠自主決定：
20+
- 需要創建哪些新檔案
21+
- 需要修改哪些現有檔案
22+
- 需要安裝哪些依賴套件
23+
- 需要執行哪些測試指令
24+
- 需要進行哪些配置變更
25+
26+
## 程式碼品質標準
27+
### Agent 生成的程式碼必須：
28+
- 遵循專案的所有程式碼風格規範
29+
- 包含適當的錯誤處理機制
30+
- 具備完整的單元測試
31+
- 包含清楚的註解說明
32+
- 符合安全性最佳實踐
33+
34+
## 協作模式
35+
### Agent 與使用者的互動：
36+
- **主動報告**：說明正在執行的步驟
37+
- **尋求確認**：在關鍵決策點請求確認
38+
- **提供選擇**：當有多種解決方案時提供選項
39+
- **解釋原因**：說明為什麼做出特定決策
40+
41+
## 錯誤處理和自我修正
42+
### 當遇到問題時，Agent 應該：
43+
- **自動診斷**：識別錯誤的根本原因
44+
- **提出解決方案**：主動嘗試修復問題
45+
- **學習改進**：從錯誤中學習避免重複問題
46+
- **回報狀況**：向使用者說明問題和解決過程
47+
48+
## 專案理解能力
49+
### Agent 需要理解：
50+
- 專案的整體架構和設計模式
51+
- 現有程式碼的業務邏輯
52+
- 檔案間的依賴關係
53+
- 資料流和控制流
54+
- 測試策略和部署流程
55+
56+
## 效率最佳化
57+
### Agent 應該：
58+
- 最小化不必要的檔案修改
59+
- 批次執行相關的變更
60+
- 避免重複的計算和操作
61+
- 優先處理關鍵路徑任務
62+
- 保持工作記錄以供參考
63+
64+
## 安全性考量
65+
### Agent 執行任務時必須：
66+
- 避免執行可能有害的指令
67+
- 不修改系統關鍵檔案
68+
- 保護敏感資料和設定
69+
- 遵循最小權限原則
70+
- 記錄所有重要操作
71+
72+
## 成果交付標準
73+
### Agent 完成任務時應該提供：
74+
- **完整的程式碼**：所有必要的檔案和修改
75+
- **測試驗證**：證明功能正常運作
76+
- **文件說明**：解釋實作的選擇和考量
77+
- **使用指南**：如何使用新功能
78+
- **後續建議**：可能的改進方向

‎.github/instructions/javascript.instructions.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# JavaScript 程式碼風格指令
2+
3+
## 基本語法規範
4+
- 使用 **雙引號** 包裹字串，不使用單引號
5+
- 使用 **2 個空格** 縮排，絕對不使用 Tab
6+
- 行尾不加分號 (除非必要時)
7+
- 使用 **camelCase** 命名變數和函數
8+
- 使用 **PascalCase** 命名類別和構造函數
9+
10+
## 變數宣告規範
11+
- 優先使用 `const`，需要重新賦值時使用 `let`
12+
- **絕對避免使用 `var`**
13+
- 每個變數都要有明確的宣告
14+
- 使用具有描述性的變數名稱
15+
16+
## 函數撰寫規範
17+
- 優先使用箭頭函數 `() => {}` 除非需要 `this` 綁定
18+
- 函數名稱要清楚表達功能：`getUserData()`, `calculateTotal()`
19+
- 單一職責原則：每個函數只做一件事
20+
- 函數長度不超過 20 行
21+
22+
## ES6+ 現代語法要求
23+
- 使用**解構賦值**提取物件和陣列元素
24+
- 使用**樣板字面值**進行字串插值
25+
- 使用**展開運算子**處理陣列和物件
26+
- 使用 `async/await` 而非 Promise.then()
27+
28+
## 錯誤處理
29+
- 所有 async 函數都要使用 try-catch
30+
- 提供有意義的錯誤訊息
31+
- 避免靜默忽略錯誤
32+
- 使用適當的錯誤類型
33+
34+
## 註解規範
35+
- 所有函數都要有 JSDoc 註解
36+
- 複雜邏輯需要行內註解說明
37+
- **使用繁體中文撰寫註解**，方便台灣學員理解
38+
- 註解要解釋「為什麼」而不只是「做什麼」
39+
40+
## 程式碼組織
41+
- 相關功能要放在同一個模組
42+
- 使用 ES6 模組語法 import/export
43+
- 避免全域變數
44+
- 保持檔案簡潔，單一檔案不超過 200 行

‎.github/instructions/testing.instructions.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# 測試撰寫指令
2+
3+
## 測試框架規範
4+
- 使用 **Jest** 作為主要測試框架
5+
- 測試檔案命名格式：`*.test.js` 或 `*.spec.js`
6+
- 測試檔案放在 `tests/` 目錄或與源碼同目錄
7+
8+
## 測試結構要求
9+
```javascript
10+
describe('模組或功能名稱', () => {
11+
beforeEach(() => {
12+
// 每個測試前的設定
13+
})
14+
15+
afterEach(() => {
16+
// 每個測試後的清理
17+
})
18+
19+
describe('特定功能群組', () => {
20+
it('應該要有明確的測試描述', () => {
21+
// 測試實作
22+
})
23+
})
24+
})
25+
```
26+
27+
## 測試命名規範
28+
- 使用 **繁體中文** 描述測試案例
29+
- 格式：「應該 + 預期行為 + 在特定條件下」
30+
- 範例：`it('應該回傳使用者資料當提供有效的 ID 時', () => {})`
31+
32+
## 測試覆蓋要求
33+
### 必須測試的情境：
34+
- ✅ **正常情況**：有效輸入的正確輸出
35+
- ✅ **邊界條件**：空值、null、undefined、空字串
36+
- ✅ **錯誤處理**：無效輸入的錯誤回應
37+
- ✅ **異常情境**：網路錯誤、超時等
38+
39+
### 測試類型：
40+
- **單元測試**：測試單一函數或方法
41+
- **整合測試**：測試模組間的互動
42+
- **端對端測試**：測試完整的用戶流程
43+
44+
## 斷言風格
45+
- 使用 Jest 的 `expect()` 語法
46+
- 優先使用語義化的 matcher：
47+
- `toBe()` - 嚴格相等
48+
- `toEqual()` - 深度比較
49+
- `toContain()` - 包含檢查
50+
- `toThrow()` - 異常檢查
51+
52+
## Mock 和 Stub 規範
53+
- 外部依賴必須 mock
54+
- 使用 `jest.fn()` 創建 mock 函數
55+
- 使用 `jest.mock()` mock 整個模組
56+
- 測試後要清理 mock：`jest.clearAllMocks()`
57+
58+
## 非同步測試
59+
- 使用 `async/await` 語法
60+
- 適當設定 timeout
61+
- 測試 Promise 的 resolve 和 reject 情況
62+
63+
## 測試資料管理
64+
- 使用 factory 函數生成測試資料
65+
- 避免硬編碼的測試資料
66+
- 每個測試要獨立，不依賴其他測試的結果
67+
68+
## 效能和品質
69+
- 測試應該快速執行（單個測試 < 100ms）
70+
- 避免不必要的複雜設定
71+
- 測試碼也要保持可讀性和可維護性
72+
- 目標測試覆蓋率：80% 以上

‎.github/prompts/README.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# GitHub Copilot Prompt Files 使用指南
2+
3+
這個目錄包含了可重複使用的 GitHub Copilot prompt files，用於常見的開發任務。
4+
5+
## 📋 **Prompt Files vs Instructions 差異**
6+
7+
### Instructions Files (`.github/copilot-instructions.md`)
8+
- **用途**：全專案的通用設定，自動套用到每個 Chat 請求
9+
- **格式**：可使用 `applyTo` 來指定檔案匹配模式
10+
- **範圍**：整個專案的全域設定
11+
12+
### Prompt Files (`.github/prompts/*.prompt.md`)
13+
- **用途**：特定任務的可重複使用提示
14+
- **格式**：**不能使用** `applyTo`，只能使用 `mode` 和 `description`
15+
- **使用**：手動附加到 Chat 或透過指令呼叫
16+
17+
## 🛠️ **Prompt Files 格式規範**
18+
19+
### 正確的 YAML Frontmatter
20+
```yaml
21+
---
22+
mode: "ask" | "edit" | "agent"
23+
description: "提示的描述"
24+
---
25+
```
26+
27+
### Mode 說明
28+
- **`ask`**: 詢問和討論模式，適合需要更多資訊的場景
29+
- **`edit`**: 編輯模式，適合修改現有程式碼
30+
- **`agent`**: Agent 模式，適合複雜的自主任務
31+
32+
## 📁 **可用的 Prompt Files**
33+
34+
### 1. `react-component.prompt.md`
35+
- **模式**: Agent
36+
- **用途**: 生成符合專案規範的 React 元件
37+
- **適用**: React/TypeScript 專案
38+
39+
### 2. `api-testing.prompt.md`
40+
- **模式**: Agent
41+
- **用途**: 生成完整的 API 測試套件
42+
- **適用**: Jest + Supertest 測試
43+
44+
### 3. `security-review.prompt.md`
45+
- **模式**: Edit
46+
- **用途**: 執行程式碼安全性檢查
47+
- **適用**: 所有程式碼類型
48+
49+
### 4. `refactoring.prompt.md`
50+
- **模式**: Edit
51+
- **用途**: 程式碼重構最佳實踐
52+
- **適用**: JavaScript/TypeScript
53+
54+
## 🚀 **使用方式**
55+
56+
### 在 VS Code 中使用
57+
1. **開啟 Copilot Chat** (`Ctrl+Alt+I`)
58+
2. **附加 Prompt File**:
59+
- 點擊 Chat 輸入框的 `+` 按鈕
60+
- 選擇想要的 prompt file
61+
- 或直接拖拽檔案到 Chat 視窗
62+
63+
### 使用指令
64+
```bash
65+
# 建立新的 prompt file
66+
Chat: New Prompt File
67+
```
68+
69+
## ⚙️ **啟用設定**
70+
71+
確保在 VS Code 設定中啟用：
72+
```json
73+
{
74+
"github.copilot.chat.codeGeneration.useInstructionFiles": true,
75+
"chat.promptFiles": true
76+
}
77+
```
78+
79+
## 💡 **最佳實踐**
80+
81+
### 撰寫 Prompt Files
82+
1. **明確的描述**: 在 frontmatter 中提供清楚的 description
83+
2. **結構化內容**: 使用 Markdown 標題組織內容
84+
3. **具體要求**: 提供明確的程式碼風格和結構要求
85+
4. **範例和模板**: 包含預期的輸出格式
86+
87+
### 團隊協作
88+
1. **版本控制**: 將 prompt files 加入 git 版本控制
89+
2. **文件說明**: 為每個 prompt file 提供使用說明
90+
3. **定期更新**: 根據專案需求更新 prompt 內容
91+
4. **分類管理**: 按功能或技術分類組織 prompt files
92+
93+
## 🔄 **與 Agent 模式整合**
94+
95+
這些 prompt files 特別適合與 GitHub Copilot 的 Agent 模式搭配使用：
96+
97+
- **Agent 模式 prompt files**: 讓 AI 自主完成複雜任務
98+
- **Edit 模式 prompt files**: 針對特定程式碼進行分析和改進
99+
- **Ask 模式 prompt files**: 獲取特定領域的專業建議
100+
101+
使用這些 prompt files 可以大幅提升開發效率，確保團隊間的一致性，並充分發揮 GitHub Copilot 的潛力。

‎.github/prompts/api-testing.prompt.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
mode: "agent"
3+
description: "生成完整的 API 測試套件"
4+
---
5+
6+
# API 測試生成器
7+
8+
請為指定的 API 端點生成完整的測試套件，遵循以下測試標準：
9+
10+
## 測試框架要求
11+
- 使用 **Jest** 作為測試框架
12+
- 使用 **supertest** 進行 HTTP 請求測試
13+
- 包含 **setup** 和 **teardown** 邏輯
14+
15+
## 測試覆蓋範圍
16+
### 1. 成功情境測試
17+
- 有效請求的正確回應
18+
- 資料格式驗證
19+
- 狀態碼確認 (200, 201, 204 等)
20+
21+
### 2. 錯誤處理測試
22+
- 無效輸入的錯誤回應
23+
- 缺少必需參數
24+
- 無效的認證
25+
- 權限不足 (401, 403)
26+
- 資源不存在 (404)
27+
- 伺服器錯誤 (500)
28+
29+
### 3. 邊界條件測試
30+
- 空值和 null 處理
31+
- 超長字串輸入
32+
- 無效的資料型別
33+
- 極值測試
34+
35+
## 程式碼結構
36+
```javascript
37+
describe('API_ENDPOINT_NAME', () => {
38+
beforeEach(() => {
39+
// 設定測試資料
40+
});
41+
42+
afterEach(() => {
43+
// 清理測試資料
44+
});
45+
46+
describe('成功情境', () => {
47+
// 正常流程測試
48+
});
49+
50+
describe('錯誤處理', () => {
51+
// 錯誤情境測試
52+
});
53+
54+
describe('邊界條件', () => {
55+
// 邊界值測試
56+
});
57+
});
58+
```
59+
60+
## 測試資料管理
61+
- 使用 **測試用的假資料**
62+
- 避免依賴真實的外部服務
63+
- 包含 **mock** 和 **stub** 設定
64+
- 確保測試之間的獨立性
65+
66+
## 斷言要求
67+
- 驗證 **HTTP 狀態碼**
68+
- 檢查 **回應資料結構**
69+
- 確認 **資料型別正確性**
70+
- 測試 **業務邏輯正確性**
71+
72+
## 額外考量
73+
- 包含 **效能測試** (回應時間)
74+
- 加入 **並發請求測試**
75+
- 考慮 **資料庫狀態變化**
76+
- 包含 **日誌檢查**
77+
78+
請為指定的 API 端點生成全面的測試套件。

0 commit comments

Comments
 (0)