---
date: 2025-10-14T22:30:00+08:00
planner: Claude (via Claude Code)
git_commit: 5c35b7b
branch: main
repository: fwauto
topic: "/feat 功能實施計劃"
tags: [plan, implementation, feat-codegen, langgraph, claude-code-sdk]
status: draft
priority: high
estimated_days: 4-5
last_updated: 2025-10-14
last_updated_by: Claude
---

# Implementation Plan: /feat 功能實施

**Date**: 2025-10-14T22:30:00+08:00
**Planner**: Claude (via Claude Code)
**Git Commit**: 5c35b7b
**Branch**: main
**Repository**: fwauto

---

## Executive Summary

### 目標

實作 `/feat` 命令，提供 **AI 協助的韌體功能開發**，實現從需求描述到自動燒錄的完整閉環。

### 核心價值

**差異化優勢**: AI 生成代碼 → 自動編譯 → 失敗自動修復 → 再編譯 → 自動燒錄

**vs Copilot/Cursor**: 市面工具只能寫代碼，後續需手動編譯、改錯、燒錄。我們提供完整閉環，深度整合 Keil + LangGraph + 韌體專業知識。

### 技術方案

```
用戶命令: fwauto feat "實作摩斯密碼編碼功能"
  ↓
CLI 初始化 State (execution_mode="feat")
  ↓
Graph 路由: route_from_start → ai_brain
  ↓
AI Brain: analyze_task_type() → "implement_feature"
  ↓
載入 prompts/implement_feature.md → 執行 Claude Code SDK
  ↓
route_after_ai_brain → build (自動編譯驗證)
  ↓
build 失敗? → ai_brain (fix_build_errors) → build (自動修復閉環)
  ↓
build 成功 → flash (自動燒錄)
```

**關鍵設計**:
- ✅ 無需建立新 node，完全複用現有 `ai_brain`
- ✅ 自動接入 `build → ai_brain → build` 修復閉環
- ✅ 低風險，無破壞性變更

### 預估

- **工作量**: 4-5 天
- **程式碼變更**: ~85 行新程式碼 + 1 個 prompt 檔案
- **測試案例**: Morse Code Demo (多周邊協調 + 時序控制)
- **風險等級**: 低

### 成功標準 (優先順序)

1. ✅ **功能完整性** - `feat → build → fix → flash` 完整流程無人工介入
2. ✅ **自動修復閉環** - 編譯錯誤能自動修復並重新編譯
3. ✅ **測試案例成功** - Morse Code 功能能成功生成並燒錄

---

## Phase 1: Core Infrastructure

**目標**: 建立 `/feat` 的核心架構支援
**預估時間**: 1 天
**風險**: 低 (修改點明確且獨立)

### 1.1 State 擴展

**檔案**: `src/fwauto/state.py`
**修改位置**: Line 15-19 (execution_mode 定義)

**Current**:
```python
execution_mode: Annotated[
    Literal["build", "flash", "run", "log", "error"] | None,
    "Workflow execution mode set by Typer CLI",
]
```

**Change to**:
```python
execution_mode: Annotated[
    Literal["build", "flash", "run", "log", "feat", "error"] | None,  # ← 新增 "feat"
    "Workflow execution mode set by Typer CLI",
]
```

**驗證**:
- [ ] Type checker 無錯誤 (執行 `mypy src/fwauto/state.py`)
- [ ] 不影響現有命令 (執行 `fwauto build` 測試)

**Rationale**:
- `execution_mode` 是主要的路由控制欄位
- 使用 Literal type 確保 type safety
- 不新增其他 State 欄位，遵守「State 屬性保持最小化」原則

---

### 1.2 Graph Routing 擴展

**檔案**: `src/fwauto/graph.py`
**修改位置**: Line 53-58 (routing_map 定義)

**Current**:
```python
routing_map = {
    "build": "build",
    "run": "build",
    "flash": "flash",
    "log": "log",
}
```

**Change to**:
```python
routing_map = {
    "build": "build",
    "run": "build",
    "flash": "flash",
    "log": "log",
    "feat": "ai_brain",  # ← 新增：feat 直接進入 ai_brain
}
```

**驗證**:
- [ ] Graph 能正確路由 (測試時會驗證)
- [ ] 其他 mode 不受影響

**Rationale**:
- `feat` mode 不需要先 build，直接進入 ai_brain 讓 AI 生成代碼
- 生成後自動進入 build 驗證 (由 `route_after_ai_brain` 控制)
- 無需建立獨立的 `feat_node`，降低複雜度

---

### 1.3 AI Brain Task Type 整合

**檔案**: `src/fwauto/nodes/ai_brain.py`
**修改位置**: Line 83-106 (analyze_task_type 函數)

**Current**:
```python
def analyze_task_type(state: FirmwareState) -> str:
    """Analyze state and determine the appropriate task type."""
    if state.get("build_errors") and state.get("build_status") == "error":
        return "fix_build_errors"

    # Default to general purpose
    return "general_purpose"
```

**Change to**:
```python
def analyze_task_type(state: FirmwareState) -> str:
    """Analyze state and determine the appropriate task type."""
    # Priority 1: Build errors (highest priority)
    if state.get("build_errors") and state.get("build_status") == "error":
        return "fix_build_errors"

    # Priority 2: Feature implementation
    if state.get("execution_mode") == "feat":
        return "implement_feature"  # ← 新增

    # Default to general purpose
    return "general_purpose"
```

**驗證**:
- [ ] `execution_mode="feat"` 時返回 `"implement_feature"`
- [ ] Build errors 優先級高於 feat (修復閉環正確運作)
- [ ] 單元測試:
  ```python
  state = {"execution_mode": "feat"}
  assert analyze_task_type(state) == "implement_feature"
  ```

**Rationale**:
- Build errors 保持最高優先級，確保修復閉環正常
- `feat` mode 只在無 build errors 時才執行功能開發
- 使用 Strategy Pattern，新增任務類型無需修改 Node 邏輯

---

### 1.4 CLI 命令註冊

**檔案**: `src/fwauto/cli.py`
**新增位置**: 建議在 `def log()` 命令之後 (Line 195 附近)

**Add new command**:
```python
@app.command()
def feat(
    prompt: str = typer.Argument(
        ...,
        help="Feature description in natural language"
    ),
):
    """
    🚀 AI-assisted firmware feature implementation.

    Automatically implements new firmware features with AI assistance,
    including code generation, compilation, auto-fix, and flashing.

    Example:
        fwauto feat "實作摩斯密碼編碼，支援字符 A-Z"
        fwauto feat "加入蜂鳴器控制，發出 100ms 短音和 300ms 長音"
    """
    console.print(f"[cyan]🚀 AI Feature Implementation[/cyan]")
    console.print(f"[yellow]Feature: {prompt}[/yellow]\n")

    state: FirmwareState = {
        "user_prompt": prompt,
        "project_root": "",
        "project_initialized": False,
        "build_status": "pending",
        "build_errors": [],
        "build_log": "",
        "flash_status": "pending",
        "flash_errors": [],
        "flash_log": "",
        "iteration": 0,
        "max_retries": 3,
        "execution_mode": "feat",  # ← 關鍵
        "command": "feat",
        "command_args": {"feature_prompt": prompt},
        "mode_metadata": {"flash_after_build": True},  # ← 自動驗證並燒錄
        "command_error": None,
        "log_file_path": None,
        "log_analysis_result": None,
        "firmware_path": None,
        "platform": "stm32_keil",
    }

    run_workflow(state)
```

**驗證**:
- [ ] `fwauto feat --help` 顯示說明
- [ ] `fwauto feat "test"` 能執行 (即使 prompt 未實作也能路由到 ai_brain)
- [ ] State 正確初始化

**Rationale**:
- 使用 `typer.Argument` 強制提供功能描述
- `mode_metadata.flash_after_build=True` 確保成功編譯後自動燒錄
- `max_retries=3` 提供 4 次嘗試機會 (初始 + 3 次重試)
- 所有 State 欄位初始化為預設值，符合現有模式

---

### 1.5 Phase 1 完整驗證

**驗證清單**:
- [ ] Type checking 通過: `mypy src/fwauto/`
- [ ] 現有命令不受影響: `fwauto build`, `fwauto run`, `fwauto log`
- [ ] 新命令可執行: `fwauto feat "test"` (會因 prompt 缺失而失敗，但路由正確)
- [ ] Git commit: `git commit -m "feat: add core infrastructure for /feat command"`

**預期結果**:
- ✅ `feat` 命令能被識別
- ✅ 路由到 `ai_brain` node
- ❌ 因 `prompts/implement_feature.md` 缺失而報錯 (預期行為)

**錯誤訊息範例**:
```
TemplateNotFound: implement_feature.md
```

這確認 Phase 1 完成，進入 Phase 2 建立 Prompt。

---

## Phase 2: Prompt Template Design & Testing

**目標**: 建立高質量的 `implement_feature.md` prompt
**預估時間**: 2-3 天
**風險**: 中 (Prompt 質量直接影響 AI 生成代碼品質)

### 2.1 Prompt Template 結構設計

**檔案**: `prompts/implement_feature.md` (新建)
**參考**: `prompts/fix_build_errors.md` (成功的 template 範例)

**設計原則**:
1. **角色定義明確** - 韌體開發專家，專注功能實作
2. **上下文完整** - 專案路徑、平台、現有代碼結構
3. **約束清楚** - Platform Config 驅動的禁止/允許目錄
4. **步驟具體** - 分析 → 設計 → 實作 → 驗證
5. **SDK 執行模式** - 命令式語氣，立即執行

---

### 2.2 Prompt Template 初版

**檔案**: `prompts/implement_feature.md`

```markdown
# STM32 韌體功能實作

你是 **{{platform_config.name}}** 韌體開發專家。

## 任務

根據需求描述實作新的韌體功能，產出可編譯的代碼。

---

## 專案環境

- **專案路徑**: `{{project_root}}`
- **平台**: {{platform}}
- **開發環境**: Keil MDK (uVision)
- **工作目錄**: {{cwd}}

---

## 功能需求

{{user_prompt}}

---

## 允許修改的目錄

以下目錄可以新增或修改檔案：

{% for dir in platform_config.allowed_dirs -%}
- ✅ `{{dir}}/`
{% endfor %}

**建議實作位置**:
- 新增硬體驅動: `HARDWARE/{MODULE_NAME}/` (例如: `HARDWARE/MORSE/`)
- 修改主程式: `USER/main.c`
- 修改頭檔: 對應的 `.h` 檔案

---

## 絕對禁止

以下目錄**不可修改**，包含系統核心和第三方庫：

{% for dir in platform_config.forbidden_dirs -%}
- 🚫 **{{dir}}/**
{% endfor %}

---

## 實作步驟

### 1. 分析需求
- 理解功能目標和預期行為
- 識別涉及的硬體資源 (GPIO, Timer, UART 等)
- 檢查現有代碼結構

### 2. 設計方案
- 決定是否需要新增驅動模組
- 規劃檔案結構 (`.c` 和 `.h` 檔案)
- 設計函數介面

### 3. 實作代碼
- 使用 **Edit** 工具修改現有檔案
- 使用 **Write** 工具建立新檔案
- 確保符合 {{platform_config.name}} 編碼規範
- 加入必要的註釋

### 4. 整合驗證
- 確保 `#include` 正確
- 檢查函數調用位置 (通常在 `main.c`)
- 確保初始化順序正確

---

## 技術要求

### HAL 庫使用
- 優先使用 STM32 HAL 庫函數
- GPIO: `HAL_GPIO_WritePin()`, `HAL_GPIO_ReadPin()`
- Delay: `HAL_Delay()`
- UART: `HAL_UART_Transmit()`

### 程式碼品質
- 函數命名: `{module}_{action}()` (例如: `morse_encode()`)
- 變數命名: 清晰描述用途
- 加入錯誤處理 (適當的 return codes)
- 適度註釋 (說明關鍵邏輯)

### 常見陷阱
- ⚠️ **時脈配置**: 不要修改系統時脈
- ⚠️ **中斷優先級**: 不要修改 NVIC 配置
- ⚠️ **記憶體管理**: 避免動態記憶體分配
- ⚠️ **延遲精度**: `HAL_Delay()` 為 ms 級，需高精度時使用 Timer

---

## 參考現有模組

使用 **Glob** 和 **Read** 工具參考現有實作：

- LED 驅動範例: `HARDWARE/LED/`
- 蜂鳴器範例: `HARDWARE/BEEP/`
- 主程式結構: `USER/main.c`

---

## 執行指示

**立即開始實作功能**。

1. 先使用 **Glob** 探索專案結構
2. 使用 **Read** 閱讀相關檔案
3. 使用 **Edit**/**Write** 實作功能
4. 確保所有修改在允許目錄內

完成後，代碼將自動進入編譯驗證流程。
```

---

### 2.3 Prompt 測試策略

**測試案例**: Morse Code Demo (分階段測試)

#### Test 1: 基礎編碼邏輯 (最簡單)
**命令**:
```bash
fwauto feat "建立 HARDWARE/MORSE/ 模組，實作 morse_encode() 函數，支援字符 A, H, E, L, O 的摩斯編碼"
```

**預期**:
- [ ] 建立 `HARDWARE/MORSE/morse.c`
- [ ] 建立 `HARDWARE/MORSE/morse.h`
- [ ] 實作 `char* morse_encode(char c)` 函數
- [ ] 編譯通過

**成功標準**:
- AI 能正確建立模組結構
- 函數介面合理
- 編譯無錯誤

---

#### Test 2: 時序控制整合 (中等)
**命令**:
```bash
fwauto feat "實作 morse_blink_led() 函數，根據摩斯編碼控制 LED 閃爍，點 100ms 劃 300ms"
```

**預期**:
- [ ] 在 `morse.c` 新增函數
- [ ] 使用 `HAL_GPIO_WritePin()` 控制 LED
- [ ] 使用 `HAL_Delay()` 實現時序
- [ ] 編譯通過

**成功標準**:
- AI 理解時序需求
- 正確使用 HAL 函數
- 邏輯清晰

---

#### Test 3: 多周邊協調 (困難)
**命令**:
```bash
fwauto feat "實作 morse_send_char() 函數，同步控制 LED 和蜂鳴器發送摩斯信號"
```

**預期**:
- [ ] 整合 LED 和 BEEP 驅動
- [ ] 同步控制兩個周邊
- [ ] 處理時序同步問題
- [ ] 編譯通過或自動修復後通過

**成功標準**:
- AI 能處理多周邊協調
- 自動修復閉環能處理編譯錯誤
- 最終代碼能成功編譯

---

### 2.4 Prompt 迭代優化

**優化方向** (根據測試結果調整):

| 問題                   | 症狀                     | 解決方案                               |
| ---------------------- | ------------------------ | -------------------------------------- |
| **代碼不符合規範**     | 編譯警告多               | 加強「技術要求」章節，提供更多範例     |
| **修改禁止目錄**       | Prompt 無視約束          | 強化「絕對禁止」章節，加入驗證步驟     |
| **缺少必要的 include** | 編譯錯誤 (undefined)     | 加入「整合驗證」檢查清單               |
| **函數介面設計不佳**   | 難以使用或不直觀         | 提供「設計方案」範例，要求先設計再實作 |
| **過度複雜**           | 實作超出需求             | 加強「分析需求」，要求最簡實作         |

**迭代流程**:
1. 執行測試案例
2. 分析失敗原因 (AI 生成問題 vs 編譯問題)
3. 調整 prompt 對應章節
4. 重新測試驗證

**目標**: 至少 **Test 1 和 Test 2** 能在自動修復閉環內成功完成

---

### 2.5 Phase 2 完整驗證

**驗證清單**:
- [ ] Test 1 (基礎編碼) 成功
- [ ] Test 2 (時序控制) 成功
- [ ] Test 3 (多周邊) 成功或自動修復後成功
- [ ] Prompt 迭代至少 2 輪
- [ ] Git commit: `git commit -m "feat: add implement_feature prompt template"`

**預期結果**:
- ✅ AI 能理解功能需求
- ✅ 生成的代碼結構合理
- ✅ 編譯錯誤能被自動修復閉環處理
- ⚠️ 可能需要 1-2 次修復迭代

**Acceptance Criteria**:
- 至少 2 個測試案例能在 `max_retries=3` 內成功完成

---

## Phase 3: Integration Testing & Demo Preparation

**目標**: 驗證完整流程並準備 Demo
**預估時間**: 1-2 天
**風險**: 低 (核心功能已驗證)

### 3.1 完整流程測試

**測試場景**: 完整的 Morse Code 功能實作

**命令**:
```bash
fwauto feat "實作完整的摩斯密碼功能：
1. 建立 HARDWARE/MORSE/ 模組
2. 實作字符編碼 (支援 A-Z)
3. 同步控制 LED 和蜂鳴器
4. 實作字串處理函數 morse_send_string()
5. 在 main.c 整合，發送 'HELLO'"
```

**驗證點**:
- [ ] **AI Brain 執行** - 成功載入 prompt 並執行 SDK
- [ ] **代碼生成** - 建立必要檔案並實作功能
- [ ] **首次編譯** - 可能失敗 (預期)
- [ ] **自動修復** - 進入 `build → ai_brain → build` 閉環
- [ ] **修復成功** - 在 `max_retries` 內編譯通過
- [ ] **自動燒錄** - Flash 成功
- [ ] **功能驗證** - 實際運行檢查 LED/蜂鳴器

**成功標準**:
- ✅ 完整流程無人工介入
- ✅ 最終代碼能成功編譯和燒錄
- ✅ 實際功能符合需求

---

### 3.2 自動修復閉環驗證

**測試目標**: 確認修復機制正常運作

**故意製造錯誤場景**:
1. **缺少 include** - 修改 prompt，移除參考現有模組的提示
2. **函數未定義** - 要求使用不存在的函數
3. **型別錯誤** - 要求複雜的資料結構操作

**驗證**:
- [ ] Build 失敗時正確進入 `ai_brain`
- [ ] `analyze_task_type()` 返回 `"fix_build_errors"`
- [ ] 載入 `fix_build_errors.md` prompt
- [ ] `iteration` 正確累加
- [ ] 達到 `max_retries` 時正確退出
- [ ] 修復後重新編譯成功

**Debug 工具**:
- 查看 LangGraph 執行日誌
- 檢查 State 變化 (`build_status`, `iteration`, `build_errors`)
- 分析 AI 修復策略

---

### 3.3 邊界條件測試

**Test Case 1: 空描述**
```bash
fwauto feat ""
```
**預期**: CLI 參數驗證錯誤 (Typer 自動處理)

---

**Test Case 2: 不可能的需求**
```bash
fwauto feat "實作量子加密演算法"
```
**預期**:
- AI 嘗試實作但編譯失敗
- 修復閉環嘗試修復
- 達到 `max_retries` 後退出並報錯

**驗證**: 系統能優雅失敗，不會無限循環

---

**Test Case 3: 修改禁止目錄**
```bash
fwauto feat "修改 CMSIS 核心函數"
```
**預期**:
- Prompt 約束阻止修改禁止目錄
- 如果 AI 違反約束，編譯可能失敗或成功但功能不符

**驗證**: Prompt 約束有效性

---

### 3.4 效能與日誌分析

**指標收集**:
- [ ] AI Brain 執行時間 (首次生成)
- [ ] 編譯時間
- [ ] 修復迭代次數
- [ ] 總端到端時間

**日誌檢查**:
- [ ] LangGraph routing 正確
- [ ] State 更新正確
- [ ] 錯誤訊息清晰
- [ ] Node 執行順序符合預期

**優化方向** (如果有時間):
- 減少 AI 生成時間 (調整 prompt)
- 減少修復迭代次數 (提升初次生成質量)

---

### 3.5 Demo 準備

**Demo 腳本** (2 週後內部經理 Demo)

#### 場景 1: 快速功能開發 (2 分鐘)
**目標**: 展示從需求到燒錄的完整閉環

```bash
# 展示命令
fwauto feat "實作蜂鳴器發出 SOS 摩斯信號：... --- ..."

# 旁白
「傳統方式需要：寫代碼 → 手動編譯 → 改錯 → 再編譯 → 手動燒錄，
 至少 30 分鐘。

 使用 FWAuto：一行命令，AI 自動完成所有步驟，2 分鐘搞定。」
```

**展示重點**:
- ✨ 自動編譯
- ✨ 自動修復錯誤
- ✨ 自動燒錄
- ✨ 實際運行驗證 (播放 SOS 聲音)

---

#### 場景 2: 差異化對比 (1 分鐘)
**投影片內容**:

| 功能             | Copilot/Cursor | FWAuto        |
| ---------------- | -------------- | ------------- |
| AI 寫代碼        | ✅             | ✅            |
| 自動編譯         | ❌             | ✅            |
| 自動修復編譯錯誤 | ❌             | ✅            |
| 自動燒錄到硬體   | ❌             | ✅            |
| 韌體專業知識     | ❌ (通用)      | ✅ (STM32 專精) |

**話術**:
「市面工具只能寫代碼，後續全靠手動。我們提供完整閉環，深度整合 Keil + 韌體知識，這是別人做不到的。」

---

#### 場景 3: 接下來的規劃 (30 秒)
**回應主管「接下來做什麼」**:

「Phase 1 (已完成): 完整閉環 - build → flash → log → AI fix
 Phase 2 (已完成): AI 功能開發 - /feat 命令
 Phase 3 (規劃中): 通用對話 - /chat 命令，支援更複雜的交互式開發
 Phase 4 (規劃中): 多平台支援 - 擴展到 ESP32, Arduino 等平台」

---

### 3.6 Phase 3 完整驗證

**驗證清單**:
- [ ] 完整流程測試通過
- [ ] 自動修復閉環正常運作
- [ ] 3 個邊界條件測試完成
- [ ] 效能指標收集完成
- [ ] Demo 腳本準備完成
- [ ] Git commit: `git commit -m "feat: complete /feat implementation and testing"`

**預期結果**:
- ✅ `/feat` 功能完整可用
- ✅ Demo 準備就緒
- ✅ 能清晰說明差異化價值

---

## Success Criteria

### 必須達成 (Must Have)

1. **功能完整性** ✅
   - `fwauto feat "..."` 命令能執行
   - 完整流程: CLI → ai_brain → build → (fix) → flash
   - 無人工介入

2. **自動修復閉環** ✅
   - Build 失敗時自動進入修復
   - `iteration` 和 `max_retries` 正確控制
   - 修復成功後重新編譯

3. **測試案例成功** ✅
   - Morse Code 基礎編碼成功
   - Morse Code 時序控制成功
   - 至少 2/3 測試案例成功

### 應該達成 (Should Have)

4. **代碼質量** 🎯
   - 首次生成編譯通過率 > 50%
   - 平均修復迭代次數 ≤ 2

5. **Prompt 穩定性** 🎯
   - 不同需求描述能正確解析
   - Platform Config 約束有效

### 可以達成 (Nice to Have)

6. **效能優化** 💡
   - 端到端時間 < 5 分鐘
   - AI 生成時間 < 2 分鐘

7. **文件完整** 💡
   - README 更新
   - 使用範例文件

---

## Risk Assessment

### 風險矩陣

| 風險                   | 機率 | 影響 | 等級 | 緩解措施                                      |
| ---------------------- | ---- | ---- | ---- | --------------------------------------------- |
| **Prompt 設計不當**    | 中   | 高   | 🟡 中 | 參考 `fix_build_errors.md`，分階段測試       |
| **AI 生成質量低**      | 中   | 中   | 🟡 中 | 依賴自動修復閉環，多輪迭代優化 prompt        |
| **無限循環**           | 低   | 高   | 🟢 低 | `max_retries` 機制已驗證，regression test 通過 |
| **修改禁止目錄**       | 低   | 中   | 🟢 低 | Platform Config 約束 + 人工 review            |
| **編譯環境問題**       | 低   | 中   | 🟢 低 | Keil 環境已驗證，build node 穩定              |
| **State 不相容**       | 極低 | 高   | 🟢 低 | 只新增 literal，不修改結構，向後相容          |
| **破壞現有功能**       | 極低 | 高   | 🟢 低 | 完全複用架構，無修改核心邏輯                  |
| **時間不足 (2 週)**    | 低   | 中   | 🟢 低 | 預估 4-5 天，有緩衝空間                       |

**總體風險**: 🟢 **低風險**

### 風險緩解計劃

#### 風險 1: Prompt 設計不當
**症狀**: AI 生成代碼不符合預期或違反約束

**緩解**:
- 參考成功的 `fix_build_errors.md` 結構
- 分階段測試 (簡單 → 中等 → 困難)
- 快速迭代，每次測試後調整 prompt
- 使用 Platform Config 動態約束

**應急方案**: 如果 prompt 質量持續不佳，簡化需求範圍，只支援特定類型功能 (如 GPIO 控制)

---

#### 風險 2: AI 生成質量低
**症狀**: 首次生成編譯失敗率高，需要多次修復迭代

**緩解**:
- 提升 prompt 質量 (提供更多範例和約束)
- 依賴自動修復閉環 (已驗證穩定)
- 調整 `max_retries` 參數 (必要時增加到 5)
- 收集失敗案例，持續優化 prompt

**接受標準**: 只要能在 `max_retries` 內成功，即視為可接受

---

#### 風險 3: 時間不足
**症狀**: Demo 前無法完成所有測試

**緩解**:
- 優先完成 Phase 1 和 Phase 2 核心功能
- Phase 3 測試可簡化 (只做完整流程測試)
- Demo 準備提前進行 (使用 Phase 2 測試案例)
- 邊界條件測試和效能優化可延後

**最小可 Demo 版本**: Phase 1 + Phase 2 Test 1 成功即可展示

---

## Timeline

### Week 1 (Day 1-5)

| 日期   | Phase              | 任務                                  | 產出                          |
| ------ | ------------------ | ------------------------------------- | ----------------------------- |
| Day 1  | Phase 1            | State + Graph + AI Brain + CLI        | Core infrastructure complete  |
| Day 2  | Phase 2            | Prompt 初版 + Test 1 (基礎編碼)      | `implement_feature.md` v1     |
| Day 3  | Phase 2            | Test 2 (時序控制) + Prompt 迭代 v2    | Prompt v2, 2 測試通過         |
| Day 4  | Phase 2            | Test 3 (多周邊) + Prompt 迭代 v3      | Prompt v3, 3 測試通過         |
| Day 5  | Phase 3            | 完整流程測試 + 自動修復閉環驗證      | Integration test complete     |

### Week 2 (Day 6+)

| 日期   | Phase              | 任務                                  | 產出                          |
| ------ | ------------------ | ------------------------------------- | ----------------------------- |
| Day 6  | Phase 3 (optional) | 邊界條件測試 + 效能分析               | Test report                   |
| Day 7+ | Demo Prep          | Demo 腳本 + 投影片 + 實際演練         | Demo ready                    |

**預留緩衝**: Day 6-7 為可選優化時間，確保 Demo 前有充足準備

---

## Code References

### 需要修改的檔案

| 檔案路徑                        | 修改位置   | 修改類型 | 說明                          |
| ------------------------------- | ---------- | -------- | ----------------------------- |
| `src/fwauto/state.py`           | Line 15-19 | 修改     | 新增 `"feat"` to Literal      |
| `src/fwauto/graph.py`           | Line 53-58 | 修改     | 新增 routing_map entry        |
| `src/fwauto/nodes/ai_brain.py`  | Line 83-106| 修改     | 新增 task type 判斷           |
| `src/fwauto/cli.py`             | Line 195+  | 新增     | 新增 `@app.command() def feat()` |
| `prompts/implement_feature.md`  | N/A        | 新增     | 建立完整 prompt template      |

### 參考檔案

| 檔案路徑                         | 用途                               |
| -------------------------------- | ---------------------------------- |
| `prompts/fix_build_errors.md`   | Prompt 設計參考                    |
| `src/fwauto/nodes/log.py`        | Claude Code SDK 配置參考           |
| `src/fwauto/platforms.py`        | Platform Config 結構               |
| `docs/morse-code-demo.md`        | 測試案例需求文件                   |

---

## Appendix

### A. 技術決策記錄

**Decision 1: 不建立獨立 feat_node**
**Rationale**:
- ai_brain 已支援多任務類型切換
- 減少程式碼重複和維護成本
- 自動接入修復閉環

**Alternative Considered**: 建立獨立 `feat_node`
**Rejected Because**: 增加複雜度，無額外價值

---

**Decision 2: feat 直接路由到 ai_brain**
**Rationale**:
- 功能開發不需要先編譯
- AI 先生成代碼，再由 build 驗證
- 符合開發流程邏輯

**Alternative Considered**: feat → build → ai_brain
**Rejected Because**: build 需要先有代碼變更

---

**Decision 3: 使用 Morse Code 作為測試案例**
**Rationale**:
- 多周邊協調 (LED + BEEP + LCD)
- 時序控制複雜度適中
- 易於驗證和 Demo
- 符合實際韌體開發場景

**Alternative Considered**: 簡單 GPIO 控制
**Rejected Because**: 太簡單，無法展示差異化

---

### B. 參考資料

- **LangGraph Doc**: https://docs.langchain.com/oss/python/langgraph/overview
- **Claude Code SDK**: https://docs.claude.com/en/docs/claude-code/sdk/sdk-python
- **STM32 HAL Doc**: STM32F4xx HAL Driver
- **Morse Code Standard**: ITU-R M.1677-1

---

### C. 問題追蹤

**Known Issues**:
- [ ] Prompt 首次版本可能需要多次迭代
- [ ] AI 生成的代碼風格可能不一致
- [ ] Platform Config 約束可能需要調整

**Future Improvements**:
- [ ] 支援多輪對話式功能開發 (`/chat`)
- [ ] 增加代碼 review 步驟
- [ ] 支援測試代碼自動生成
- [ ] 擴展到其他平台 (ESP32, Arduino)

---

**計劃完成時間**: 2025-10-14T22:30:00+08:00
**預估開始時間**: 2025-10-15
**預估完成時間**: 2025-10-21 (7 天，含緩衝)
**Demo 時間**: 2025-10-28 (2 週後)

---

**Status**: ✅ Draft Complete - Ready for Review and Implementation
