create-technical-spike

建立技術探討文件

建立有時限的技術探討文件，用於研究在開發進行前必須解答的關鍵問題。每個探討聚焦於一個特定的技術決策，並有明確的交付成果與時程。

文件結構

在 ${input:FolderPath|docs/spikes} 目錄中建立個別檔案。使用以下模式命名每個檔案：[category]-[short-description]-spike.md（例如：api-copilot-integration-spike.md、performance-realtime-audio-spike.md）。

---
title: "${input:SpikeTitle}"
category: "${input:Category|Technical}"
status: "🔴 未開始"
priority: "${input:Priority|High}"
timebox: "${input:Timebox|1 week}"
created: [YYYY-MM-DD]
updated: [YYYY-MM-DD]
owner: "${input:Owner}"
tags: ["technical-spike", "${input:Category|technical}", "research"]
---

# ${input:SpikeTitle}

## 摘要

**探討目標：** [需要解決的明確、具體問題或決策]

**為何重要：** [對開發/架構決策的影響]

**時間限制：** [分配給此探討的時間]

**決策截止日：** [必須解決此問題以避免阻礙開發的日期]

## 研究問題

**主要問題：** [需要解答的主要技術問題]

**次要問題：**

- [相關問題 1]
- [相關問題 2]
- [相關問題 3]

## 調查計畫

### 研究任務

- [ ] [具體研究任務 1]
- [ ] [具體研究任務 2]
- [ ] [具體研究任務 3]
- [ ] [建立概念驗證/原型]
- [ ] [記錄發現與建議]

### 成功標準

**此探討完成條件：**

- [ ] [具體標準 1]
- [ ] [具體標準 2]
- [ ] [記錄明確建議]
- [ ] [完成概念驗證（如適用）]

## 技術背景

**相關元件：** [列出受此決策影響的系統元件]

**相依性：** [哪些其他探討或決策依賴於此問題的解決]

**限制條件：** [已知的限制或影響解決方案的需求]

## 研究發現

### 調查結果

[記錄研究發現、測試結果與收集到的證據]

### 原型/測試筆記

[任何原型、探討或技術實驗的結果]

### 外部資源

- [相關文件連結]
- [API 參考連結]
- [社群討論連結]
- [範例/教學連結]

## 決策

### 建議

[基於研究發現的明確建議]

### 理由

[為何選擇此方法而非其他替代方案]

### 實作注意事項

[實作時的關鍵考量]

### 後續行動

- [ ] [行動項目 1]
- [ ] [行動項目 2]
- [ ] [更新架構文件]
- [ ] [建立實作任務]

## 狀態歷史

| 日期   | 狀態         | 備註                      |
| ------ | -------------- | -------------------------- |
| [日期] | 🔴 未開始 | 探討已建立並界定範圍   |
| [日期] | 🟡 進行中 | 研究已開始         |
| [日期] | 🟢 完成    | [解決摘要]       |

---

_最後更新：[日期] 由 [姓名]_

技術探討分類

API 整合

• 第三方 API 功能與限制
• 整合模式與驗證
• 速率限制與效能特性

架構與設計

• 系統架構決策
• 設計模式適用性
• 元件互動模型

效能與可擴展性

• 效能需求與限制
• 可擴展性瓶頸與解決方案
• 資源使用模式

平台與基礎設施

• 平台功能與限制
• 基礎設施需求
• 部署與代管考量

安全性與合規性

• 安全需求與實作
• 合規限制
• 驗證與授權方法

使用者體驗

• 使用者互動模式
• 無障礙需求
• 介面設計決策

檔案命名慣例

使用描述性的 kebab-case 名稱，指出分類與具體未知事項：

API/整合範例：

• api-copilot-chat-integration-spike.md
• api-azure-speech-realtime-spike.md
• api-vscode-extension-capabilities-spike.md

效能範例：

• performance-audio-processing-latency-spike.md
• performance-extension-host-limitations-spike.md
• performance-webrtc-reliability-spike.md

架構範例：

• architecture-voice-pipeline-design-spike.md
• architecture-state-management-spike.md
• architecture-error-handling-strategy-spike.md

AI 代理最佳實踐

1. 每個探討一個問題： 每個文件專注於單一技術決策或研究問題

2. 有時限的研究： 為每個探討定義具體時間限制與交付成果

3. 基於證據的決策： 要求具體證據（測試、原型、文件）才能標記為完成

4. 明確建議： 記錄具體建議與實作理由

5. 相依性追蹤： 識別探討之間的關聯及其對專案決策的影響

6. 結果導向： 每個探討必須產出可行動的決策或建議

研究策略

第一階段：資訊收集

1. 搜尋現有文件 使用搜尋/擷取工具
2. 分析程式碼庫 了解現有模式與限制
3. 研究外部資源（API、函式庫、範例）

第二階段：驗證與測試

1. 建立聚焦原型 測試特定假設
2. 執行目標實驗 驗證假設
3. 記錄測試結果 附上佐證

第三階段：決策與文件化

1. 綜合發現 形成明確建議
2. 記錄實作指引 供開發團隊使用
3. 建立後續任務 用於實作

工具使用

• search/searchResults： 研究現有解決方案與文件
• fetch/githubRepo： 分析外部 API、函式庫與範例
• codebase： 了解現有系統限制與模式
• runTasks： 執行原型與驗證測試
• editFiles： 更新研究進度與發現
• vscodeAPI： 測試 VS Code 擴充功能能力與限制

專注於有時限的研究，以解決關鍵技術決策並解除開發進度的阻礙。