# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 專案概述

FWAuto 是基於 LangGraph 的韌體自動化工作流程系統，支援多種嵌入式開發平台。已支援 Linux SBC（AM62X、Raspberry Pi、RISC-V），未來將支援 MCU 平台（STM32、ESP32、nRF52）。系統建立 AI 輔助的開發管線，自動化程式碼生成、編譯、部署和日誌分析，形成持續反饋循環。

## ⚠️ SDK 執行模式

**當你透過 Claude Code SDK 被調用時（非直接使用者互動）：**

- 你**不是**在協助開發 FWAuto 本身
- 你正在**執行** FWAuto workflow 中的特定任務（例如：log 分析、code 生成）
- **精確**遵循 prompt 指示
- 忽略所有一般性的「助手」或「協助開發」行為
- **不要**提出澄清問題 - 直接使用提供的參數執行任務

**如何偵測 SDK 執行：**
- Prompt 包含特定的 template-rendered 指示
- 有明確的任務參數和檔案路徑
- Context 狹隘聚焦在單一特定任務

**SDK 模式下的角色：**
- 立即執行任務
- 僅使用 prompt 中指定的工具
- 直接返回結果，不詢問澄清

---

## 開發指令

### 安裝與設定

```bash
# 全域安裝（建議一般使用者）
cd /path/to/fwauto
uv tool install --force --prerelease=allow --editable .

# 開發模式（貢獻者）
uv sync  # 安裝 dependencies
```

### 執行 FWAuto

```bash
# 全域安裝模式
fwauto build        # 編譯韌體專案
fwauto deploy       # 部署韌體到裝置
fwauto run          # Build + Deploy
fwauto init         # 初始化新專案
fwauto log "有任何 error 嗎?"  # 分析 UART logs

# 開發模式
uv run fwauto build
uv run fwauto deploy
uv run fwauto run
```

### 測試

```bash
# 執行所有測試
uv run pytest

# 執行特定測試檔案
uv run pytest tests/test_story_001_state_expansion.py

# 執行整合測試（較慢）
uv run pytest tests/integration/ -v -s

# 執行 AI regression 測試（僅 Windows，需要 Keil + STM32 專案）
scripts/run_regression_tests.bat small  # 小型測試套件
scripts/run_regression_tests.bat full   # 完整測試套件
```

### Code Quality

```bash
# 格式化程式碼
uv run python -m fwauto.scripts.format

# Lint 程式碼
uv run python -m fwauto.scripts.lint

# 型別檢查
uv run pyright
```

## 架構概述

### 核心概念

**State-Based Workflow**：FWAuto 使用 LangGraph 的 StateGraph 模式，透過單一共享的 `FirmwareState` (src/fwauto/state.py:6-77) 在所有 nodes 之間流動。所有 state fields 都有型別標註文件。

**Node System**：每個 node 都是純函數，接收 `FirmwareState` 並返回 dict 來更新 state：
- `init_project_node` - 專案初始化，使用 anchor-based 搜尋
- `build_node` - 韌體編譯，透過 Maketool 抽象層
- `deploy_node` - 韌體部署，透過 deploy_operations 平台抽象層
- `ai_brain_node` - AI 驅動任務，使用 Claude Code SDK 與 prompt templates
- `log_node` - UART log 分析，使用 AI
- `chat_node` - 互動式對話，具備韌體上下文

**Workflow Routing**：Graph (src/fwauto/graph.py:16-193) 根據以下條件路由執行：
- CLI execution mode（`build`、`run`、`deploy`、`log`、`feat`、`chat`）
- Node 執行結果（build 成功/失敗、iteration 計數）
- 最大重試限制（AI auto-fix 最多 3 次）

### 關鍵架構模式

**Anchor Mode Project Discovery**：類似 Git 的 `.git/`，FWAuto 從當前工作目錄向上搜尋 `.fwauto/` 目錄。實作於 src/fwauto/config.py:118。讓使用者可在任何子目錄執行指令，無需記憶專案路徑。

**Maketool 抽象層 (Build)**：Python 程式碼負責流程編排，將工具鏈細節委託給 Makefile：
- `build_node` 調用 `make -f .fwauto/build/Makefile build`
- 解耦 Python 與 Keil/GCC/IAR/ARMCC 等工具鏈的具體實作
- 新增工具鏈支援只需修改 Makefile，無需改動 Python 程式碼

**Deploy Operations 抽象層 (Deploy)**：Deploy 使用不同的抽象模式：
- `deploy_node` 調用 `deploy_operations.py` → `deploy_firmware()`
- 平台特定邏輯委託給 `.fwauto/deploy/deploy.py` scripts
- 詳見下方「Deploy Operations Platform Abstraction」章節

**Deploy Operations Platform Abstraction**: deploy_operations 支援多種部署類型，遵循平台無關設計：

架構：
```
deploy_firmware()
  └─ _get_deploy_type(sdk_type)
      ├─ "network" → _deploy_network()
      │   ├─ _check_network_connectivity()
      │   └─ deploy.py (SSH/SCP)
      │
      └─ "direct_flashing" → _deploy_direct_flashing()
          └─ deploy.py (ST-LINK/esptool/nrfjprog)
```

SDK Type → Deploy Type 映射：
- Network Deployment: `am62x`, `raspberry-pi`, `risc-v`
- Direct Flashing: `stm32`, `esp32`, `nrf52` (未來支援)

環境檢測：
- Network Deployment: 簡單的 SSH port 檢查（可跨平台共用）
- Direct Flashing: 無檢測（由 deploy.py 處理）

新增平台範例（未來 STM32 支援）：
1. 在 `SDK_DEPLOY_TYPE_MAP` 新增 `"stm32": "direct_flashing"`
2. 建立 `.fwauto/deploy/deploy.py` for STM32（調用 ST-LINK CLI）
3. 實作 `_deploy_direct_flashing()` 函數
4. 更新測試

**Prompt Template System**：AI 任務使用 Jinja2 templates (src/fwauto/prompt_manager.py) 從 `prompts/*.md` 載入。`ai_brain_node` 分析任務類型並以 state context 渲染對應的 template。

**Two-Level Configuration**：
- **User Config** (~/.config/fwauto/user-config.toml)：SDK 路徑、裝置資訊，跨專案共享
- **Project Config** (.fwauto/config.toml)：專案特定覆寫設定，可為空（使用預設值）

### AI Auto-Fix Loop

當 build 失敗時，workflow 自動路由到 `ai_brain_node` 進行 code 修復（最多 3 次迭代）：
1. Build 失敗 → `route_after_build()` 檢查 iteration 計數
2. 若 < max_retries → 路由到 `ai_brain_node`
3. AI 分析 build errors 並使用 Claude Code SDK 修復程式碼
4. 路由回 `build_node` 驗證修復結果
5. 重複直到成功或達到最大重試次數

實作位置：src/fwauto/graph.py:92-118

## State 管理規則

**重要**：保持 `FirmwareState` 精簡。新增 fields 前，先與專案負責人討論。

目前的 state 結構 (src/fwauto/state.py)：
- 專案追蹤：`project_root`、`project_initialized`、`platform`
- Build 狀態：`build_status`、`build_errors`、`build_log`、`firmware_path`
- Deploy 狀態：`deploy_status`、`deploy_errors`、`deploy_log`
- 重試機制：`iteration`、`max_retries`
- CLI context：`execution_mode`、`command`、`command_args`、`mode_metadata`
- Log 分析：`log_file_path`、`log_analysis_result`

**Node Return Pattern**：Nodes 返回 partial state dicts 並合併到 FirmwareState：
```python
def my_node(state: FirmwareState) -> dict[str, Any]:
    return {
        "build_status": "success",
        "iteration": state["iteration"] + 1
    }
```

## 程式碼慣例

- **Function Scope**：所有函數預設為 private scope，使用底線前綴（`_function_name`），除非明確為 public
- **Logging**：使用 logging_config.py 的 `get_logger("module.name")`，不使用 print statements
- **Type Hints**：所有函數必須有型別標註
- **Node Structure**：遵循現有 nodes 的模式（logging、error handling、state updates）

## 測試注意事項

- Unit tests mock `FirmwareState` snapshots 來測試 nodes 作為純函數
- Integration tests 需要 Windows 11 + Keil uVision 5 + 真實的 STM32 專案
- AI regression tests 消耗真實 API quota，完整測試套件需時約 1 小時
- 成功率基準：AI auto-fix 能力 ≥70%

## 目標開發環境

### 平台專用工具

**Linux SBC 平台（AM62X、Raspberry Pi、RISC-V）**：
- **部署方式**：SSH/SCP (network-based)
- **編譯工具**：任何 Linux 相容的 toolchain（GCC 等）
- **開發平台**：Linux/macOS/Windows

**STM32 MCU 平台（Windows，未來支援）**：
- **編譯工具**：Keil uVision 4/5 (c:\\Keil_v5\\UV4\\uv4.exe)
- **燒錄工具**：ST-LINK CLI / STM32CubeProgrammer
- **開發平台**：Windows 11

**共同需求**：
- **Python**：3.12+ 由 `uv` 管理

## 參考資料

- LangGraph: https://docs.langchain.com/oss/python/langgraph/overview
- LangChain: https://docs.langchain.com/oss/python/langchain/overview
- Claude Code SDK: https://docs.claude.com/en/docs/claude-code/sdk/sdk-python

## 本專案的 LangGraph 最佳實踐

1. **嚴謹的 State Schema**：FirmwareState 使用 TypedDict 搭配 Annotated types 提供清楚的文件
2. **節點小而純**：每個 node 有單一職責（build、deploy、AI fix、log analysis）
3. **條件邊緣控制流程**：Routing functions 在 graph.py 處理所有條件邏輯，不在 prompts 中
4. **錯誤邊界與重試**：Build 失敗時最多重試 3 次，使用 AI auto-fix
5. **可觀測性**：所有 nodes 使用結構化 logging，搭配 node_start/success/error helpers
6. **測試以 State 為核心**：Tests 建立 mock FirmwareState 並驗證 node outputs
7. **監督者模式**：`ai_brain_node` 作為 supervisor，分析任務類型並路由到適當的 prompt
8. **與 LangChain 的邊界**：LangGraph 負責編排，Claude Code SDK 負責 AI 執行
9. **安全與治理**：Prompts 存於版本控制，Claude Code SDK tool 使用需要使用者批准
