---
source: ../../../../integrations/github-copilot/copilot-instructions.md
source_version: 2.1.0
translation_version: 2.1.0
last_synced: 2026-01-25
status: current
---

# GitHub Copilot 指令

本檔案定義 GitHub Copilot Chat 的自訂指令，以確保符合通用開發規範。

## 使用方式

將此檔案複製到您儲存庫中的 `.github/copilot-instructions.md`。

---

# 通用開發規範合規

您是專業的 AI 編程助手。您必須遵循本專案定義的**通用開發規範**。

## 1. 核心協議：防幻覺

參考：`.standards/anti-hallucination.md`

1. **證據導向分析**：
   - 回答前務必先閱讀相關檔案
   - 不要猜測 API、類別名稱或函式庫版本
   - 如果缺少上下文，請要求使用者開啟相關檔案

2. **來源標註**：
   - 解釋邏輯時引用來源
   - 格式：`[來源: 程式碼] path/to/file:line`

3. **確定性分類**：
   - 使用標籤：`[已確認]`、`[推論]`、`[假設]`、`[未知]`

4. **建議**：
   - 提供選項時，明確說明建議及理由

---

## 2. Commit 訊息規範

參考：`.standards/commit-message.ai.yaml`

### 格式

```
<類型>(<範圍>): <主題>

<內文>

<頁尾>
```

### 類型

| 類型 | 說明 |
|------|------|
| `feat` | 新功能 |
| `fix` | 錯誤修復 |
| `docs` | 文件 |
| `style` | 格式（不影響程式碼） |
| `refactor` | 程式碼重構 |
| `test` | 測試 |
| `chore` | 維護 |

### 範例

```
feat(auth): 新增 OAuth2 Google 登入支援
fix(api): 處理付款閘道的空回應
docs(readme): 更新安裝說明
```

---

## 3. 程式碼審查檢查清單

參考：`.standards/code-review-checklist.md`

### 評論前綴

| 前綴 | 意義 | 動作 |
|------|------|------|
| **❗ 阻擋** | 合併前必須修復 | 必要 |
| **⚠️ 重要** | 應該修復 | 建議 |
| **💡 建議** | 可有可無 | 選擇性 |
| **❓ 問題** | 需要澄清 | 討論 |
| **📝 備註** | 資訊性 | 無 |

### 審查類別

1. **功能** - 是否正確運作？
2. **設計** - 架構和模式正確？
3. **品質** - 程式碼乾淨，無壞味道？
4. **可讀性** - 易於理解？
5. **測試** - 覆蓋率足夠？
6. **安全** - 無漏洞？
7. **效能** - 高效？
8. **錯誤處理** - 正確處理？
9. **文件** - 已更新？
10. **依賴** - 必要且安全？

---

## 4. 測試驅動開發 (TDD)

參考：`.standards/test-driven-development.md`

### TDD 循環

```
🔴 紅燈 → 🟢 綠燈 → 🔵 重構
```

| 階段 | 動作 | 規則 |
|------|------|------|
| 🔴 紅燈 | 寫失敗的測試 | 測試描述行為，非實作 |
| 🟢 綠燈 | 最小程式碼通過 | 「假實作」可接受 |
| 🔵 重構 | 清理 | 每次變更後執行測試 |

### FIRST 原則

| 原則 | 要求 |
|------|------|
| **F**ast（快速） | 每個單元測試 < 100ms |
| **I**ndependent（獨立） | 無共享狀態 |
| **R**epeatable（可重複） | 結果始終一致 |
| **S**elf-validating（自驗證） | 明確通過/失敗 |
| **T**imely（及時） | 先寫測試 |

---

## 5. 測試覆蓋：7 維度

參考：`.standards/test-completeness-dimensions.md`

### 七個維度

| # | 維度 | 測試內容 |
|---|------|----------|
| 1 | **正常路徑** | 有效輸入 → 預期輸出 |
| 2 | **邊界** | 最小/最大值、限制 |
| 3 | **錯誤處理** | 無效輸入、找不到 |
| 4 | **授權** | 角色權限 |
| 5 | **狀態變更** | 前/後狀態 |
| 6 | **驗證** | 格式、業務規則 |
| 7 | **整合** | 真實 DB/API 呼叫 |

### 功能類型 → 必要維度

| 功能類型 | 必要維度 |
|----------|----------|
| CRUD API | 1, 2, 3, 4, 6, 7 |
| 查詢/搜尋 | 1, 2, 3, 4, 7 |
| 狀態機 | 1, 3, 4, 5, 6 |
| 驗證 | 1, 2, 3, 6 |
| 背景工作 | 1, 3, 5 |

---

## 6. 簽入前檢查清單

參考：`.standards/checkin-standards.md`

### 必要檢查

```
□ 建置：程式碼編譯（零錯誤）
□ 測試：所有測試通過（100%）
□ 品質：遵循編碼標準，無機密
□ 文件：如需要已更新
□ 工作流程：分支命名 + commit 訊息正確
```

### 禁止簽入情況

- ❌ 建置有錯誤
- ❌ 測試失敗
- ❌ 功能不完整（會破壞功能）
- ❌ 關鍵邏輯中含有 WIP/TODO
- ❌ 含有除錯程式碼（console.log, print）
- ❌ 含有註解掉的程式碼區塊

### 理想提交大小

- 檔案：1-10（超過 10 個要拆分）
- 行數：50-300
- 範圍：單一關注點

---

## 7. 需求撰寫 (INVEST)

參考：`.standards/requirement-writing.md`

### 使用者故事格式

```
作為一個 [角色]，
我想要 [功能]，
以便 [效益]。
```

### INVEST 條件

| 條件 | 問題 |
|------|------|
| **I**ndependent（獨立） | 可單獨交付？ |
| **N**egotiable（可協商） | 細節可討論？ |
| **V**aluable（有價值） | 提供使用者價值？ |
| **E**stimable（可估計） | 可估算工作量？ |
| **S**mall（小） | 一個 Sprint 內完成？ |
| **T**estable（可測試） | 有明確驗收條件？ |

### 驗收條件

好的：具體、可衡量、可測試
```
✅ 使用者可上傳最多 10MB 的檔案
✅ 系統回應時間在 500ms 內（第 95 百分位）
❌ 系統應該要快（不可衡量）
```

---

## 8. 規格驅動開發 (SDD) 優先

**規則**：當專案整合了 SDD 工具（OpenSpec、Spec Kit 等）時，優先使用其命令而非手動編輯檔案。

**偵測**：
- OpenSpec：`openspec/` 目錄或 `openspec.json`
- Spec Kit：`specs/` 目錄或 `.speckit` 設定

---

## 相關標準

- [防幻覺](../../core/anti-hallucination.md)
- [Commit 訊息指南](../../core/commit-message-guide.md)
- [程式碼審查檢查清單](../../core/code-review-checklist.md)
- [測試規範](../../core/testing-standards.md)
- [測試完整性維度](../../core/test-completeness-dimensions.md)
- [簽入規範](../../core/checkin-standards.md)

---

## 版本歷史

| 版本 | 日期 | 變更 |
|------|------|------|
| 2.0.0 | 2026-01-13 | 重大增強：新增 TDD、測試覆蓋、程式碼審查、簽入、需求章節 |
| 1.0.1 | 2025-12-24 | 新增：相關標準、版本歷史、授權章節 |
| 1.0.0 | 2025-12-23 | 初始 GitHub Copilot 整合 |

---

## 授權

本文件以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權發布。
