---
date: 2025-10-22T17:07:21+08:00
author: kent
git_commit: b85ef7694e97be904f3a8eb88f6c0ae8daf18c7c
branch: main
problem_id: makefile-management-system
tags: [architecture, makefile, template, extensibility]
status: defined
method: socratic-inquiry-v4
---

# Problem Definition: Makefile Management System

## Problem Statement

**核心問題**：FWAuto 需要設計一套 makefile 管理機制，能夠同時支援「已知 SDK/開發板的組織」和「未知 SDK/開發板的使用者定製」，但目前不確定該如何定義管理結構（命名、metadata、識別機制）來支撐這些需求。

**具體困境**：
1. 目前的 makefile template（`Makefile.minimal`）沒有辨識性，系統無法知道如何選擇匹配的 makefile
2. 即將加入第二個 SDK（AM62x），不知道該如何命名和組織這些 makefile
3. 未來會有未知數量的 SDK/開發板需要支援，數量可能很大
4. 需要讓使用者能在「預期範圍內」定製 makefile（空白 template / AI 生成 / 引導式生成）
5. 團隊已考慮過多種方案，但因為「缺少具體實作細節」和「不知道先定義什麼管理結構」而無法推進

---

## Discovery Process

### 初始描述

> "這個專案要能使用在各種 SDK 跟開發環境，我目前已經整合了 STM32，使用 makefile 驅動 Keil 進行編譯，現在需要支援另一個 SDK + 開發板 am62x，它提供的 cross compile toolchain 在 ubuntu 22.04 裡面。我不知道如何來讓這些 makefile 有秩序、直覺地被管理，讓我可以在不同的 SDK、不同的開發板下都能選擇到合適的 makefile。"

### 關鍵洞察時刻

1. **「解決方案偽裝成需求」的識別**
   - 初始描述：「需要管理 makefile」
   - 深入挖掘：真正的問題是「如何識別和選擇」+ 「如何支援使用者定製」

2. **「我不是韌體工程師」的揭露**
   - 這個專案的維護者不是韌體領域專家
   - 需要依賴韌體工程師提供 makefile
   - 無法判斷「哪些 makefile 可以共用、哪些需要獨立」

3. **「使用者定製」的核心需求**
   - 從「如何組織已有的 makefile」→「如何讓使用者加入新的 makefile」
   - 這是信心從 7 分提升到 8 分的關鍵洞察

4. **「數量未知」的規模不確定性**
   - 不知道未來會有多少 SDK/開發板
   - 這影響了方案的選擇（過度設計 vs 不夠彈性）

5. **「Flash makefile 可能共用」的假設挑戰**
   - 初始假設：不同板子可能共用 flash makefile（因為燒錄工具標準化）
   - 實際情況：STM32 用 ST-LINK，AM62x 用 SD Card，完全不同
   - 揭露了「基於推測而非證據」的設計風險

### 信心歷程

| 階段 | 信心分數 | 說明 |
|------|----------|------|
| 初期探索 | ~4-5 分 | 停留在「不知道如何命名和組織」的表面問題 |
| 深度挖掘 | ~6 分 | 理解到需要「識別機制」和「metadata」|
| 魔鬼代言人前 | 7 分 | 確定了執行計畫：工程師提供 makefile，init 時複製 |
| 魔鬼代言人後 | 8 分 | 挖掘出「使用者定製」的核心需求 |

### 魔鬼代言人挑戰記錄

**挑戰 1：反向假設測試**
- 問題：如果真正的問題是「讓工程師自己加入新板子」而非「管理 makefile」？
- 回應：確認了「使用者定製」的重要性

**挑戰 2：證據質疑**
- 問題：AM62x 的 makefile 是已經寫好，還是承諾會寫？
- 回應：b) 工程師承諾會寫，但還沒看到 → 揭露了「基於承諾而非證據」

**挑戰 3：替代解釋**
- 列出的 3 個根本原因：
  1. 目前的 makefile 沒有辨識性
  2. （工程師承諾提供 makefile）
  3. **對於未知的 SDK/開發板，需要讓使用者能定製** ← 核心洞察

**挑戰 4：影響測試**
- 問題：如果用最簡單粗暴的方式（手動加資料夾 + 手動改選單），會怎樣？
- 回應：「無法支援其他我們還沒提供 makefile 的 SDK 跟開發板，而且這個數量很大」
- 揭露：規模的不確定性是設計猶豫的核心

**挑戰 5：最簡方案**
- 問題：空白 template / AI 生成 / 引導式生成，哪個最簡單？
- 回應：「都是我們團隊考慮過的 solutions」
- 追問：為什麼沒選？
- 回應：c) 缺少具體實作細節 + d) 不知道先定義什麼管理結構

### 5 Whys 分析

**Why 1**: 為什麼不知道如何管理 makefile？
→ 因為不知道該如何命名和組織 am62x 的 makefile

**Why 2**: 為什麼命名和組織很困難？
→ 因為擔心未來會有很多 SDK/開發板，需要一套可擴展的結構

**Why 3**: 為什麼需要可擴展的結構？
→ 因為無法預先為所有板子撰寫 makefile，需要讓使用者能定製

**Why 4**: 為什麼無法預先撰寫？
→ 因為維護者不是韌體工程師，且未來的板子種類和數量未知

**Why 5**: 為什麼不確定數量會影響設計決策？
→ 因為團隊考慮過多種方案（空白 template / AI 生成 / 引導式），但不知道該選哪個，且缺少「管理結構的定義」作為這些方案的基礎

**根本原因**：需要先定義一套「makefile 管理結構」（識別機制 + metadata schema + 擴展機制），才能實作「使用者定製」功能，但因為缺乏韌體領域知識和未來規模的不確定性，導致設計決策困難。

---

## Real Requirement (真實需求 vs 解決方案)

### 需求 A：Template 識別與選擇

**需求描述**：
- init 時，系統能列出可用的 makefile template
- 使用者能根據描述性資訊，選擇最接近的 template
- 系統能將選中的 template 複製到 `.fwauto/build/` 和 `.fwauto/flash/`

**不是解決方案**：
- ❌ 使用資料夾結構（這是實作方式，不是需求）
- ❌ 使用 metadata 檔案（這是實作方式，不是需求）

### 需求 B：使用者定製能力

**需求描述**：
- 使用者能基於現有 template，填寫資訊來定製（SDK 位置、開發板型號、編譯指令）
- 定製的資訊存在 `.fwauto/config.toml`，讓 makefile 能讀取
- 當沒有合適的 template 時，使用者能自行建立新的

**不是解決方案**：
- ❌ 空白 template（這是實作方式之一）
- ❌ AI 生成（這是實作方式之一）
- ❌ 引導式生成（這是實作方式之一）

### 需求 C：管理結構的可擴展性

**需求描述**：
- 韌體工程師能輕鬆加入新的 template（10 分鐘內完成整合）
- Template 數量增加時，系統保持清晰易懂
- 團隊成員（包含非韌體專家）能一眼看懂 templates/ 目錄結構

**不是解決方案**：
- ❌ 命名規則（這是實作方式，不是需求）
- ❌ 資料夾層級（這是實作方式，不是需求）

---

## Success Criteria (成功標準)

### 可衡量的標準

1. **整合速度**
   - ✅ 韌體工程師提供新板子的 makefile 時，維護者能在 **10 分鐘內**整合進系統
   - 測試方式：實際計時加入 AM62x 的過程

2. **使用者體驗**
   - ✅ `fwauto init` 時，使用者能在 **3 次點擊/輸入內**完成 template 選擇和定製
   - 測試方式：觀察真實使用者的操作流程

3. **可理解性**
   - ✅ 新加入的團隊成員在 **不看文件的情況下**，能理解 templates/ 目錄結構
   - 測試方式：請新成員描述結構，看是否符合設計意圖

4. **擴展性驗證**
   - ✅ 加入 20 個 template 後，init 流程仍然清晰，不需要重構
   - 測試方式：模擬 20 個 template 的情境，檢查選單和流程是否混亂

### 定性標準

- 使用者不需要理解「makefile 管理的實作細節」就能使用
- 維護者能自信地向韌體工程師解釋「如何加入新板子」
- 系統架構能支援未來的「AI 生成」或「引導式生成」功能

---

## Context & Impact

### 影響範圍

**直接影響**：
- FWAuto 的 init 流程設計
- Templates 目錄的組織結構
- `config.toml` 的 schema 設計

**間接影響**：
- 未來的「AI 生成 makefile」功能（需要有清楚的 template 結構作為基礎）
- 韌體工程師的工作流程（如何提供 makefile 給維護者）
- 使用者定製的彈性（能否支援非標準的板子）

### 頻率與嚴重程度

- **頻率**：每次加入新 SDK/開發板時觸發（預期頻率：未知，但可能很高）
- **嚴重程度**：高（如果結構設計不當，會導致系統難以維護，需要大規模重構）

### 使用場景

**場景 1：已知板子（STM32F407）**
1. 使用者執行 `fwauto init`
2. 系統顯示選單：「STM32 系列 (Keil + Windows)」
3. 使用者選擇後，輸入 SDK 位置、開發板型號
4. 系統複製 STM32 template，並寫入 config.toml

**場景 2：已知板子（AM62x）**
1. 使用者執行 `fwauto init`
2. 系統顯示選單：「AM62x (Linux + build.sh)」
3. 使用者選擇後，輸入 SDK 位置（廠商 VM 路徑）
4. 系統複製 AM62x template，並寫入 config.toml

**場景 3：未知板子（使用者定製）**
1. 使用者執行 `fwauto init`
2. 系統顯示選單，包含「其他 / 自訂」選項
3. 使用者選擇「最接近」的 template（或空白 template）
4. 系統引導使用者填寫詳細資訊（編譯指令、燒錄方式等）
5. 系統生成定製化的 makefile

---

## Assumptions & Constraints

### 關鍵假設

1. **假設 1：韌體工程師能提供符合 fwauto 結構的 makefile**
   - 信心：中等
   - 風險：如果工程師不理解結構，提供的 makefile 可能不符合預期
   - 緩解措施：提供清楚的 makefile 撰寫指南和範例

2. **假設 2：大部分板子可以歸類到少數幾個「template 類型」**
   - 信心：低（維護者不是韌體專家，無法驗證）
   - 風險：如果每個板子都是獨特的，template 機制可能不適用
   - 緩解措施：優先設計「使用者定製」機制，而非依賴預定義 template

3. **假設 3：使用者在 init 時知道自己的板子「最接近」哪個 template**
   - 信心：中等
   - 風險：如果使用者不清楚，可能選錯 template
   - 緩解措施：提供詳細的描述（工具鏈、作業系統、廠商）或 AI 輔助選擇

4. **假設 4：「SDK 位置 + 開發板型號 + 編譯指令」足以描述一個板子**
   - 信心：低（基於初步討論，尚未驗證）
   - 風險：可能缺少其他關鍵資訊（燒錄方式、環境變數、依賴工具）
   - 緩解措施：在實作 AM62x 時驗證這個假設，必要時擴展 metadata schema

### 技術限制

- **跨平台支援**：STM32 在 Windows（PowerShell），AM62x 在 Linux，未來可能有 macOS
- **現有架構**：makefile 作為 wrapper，實際工作由 script 或廠商工具完成
- **LangGraph 整合**：makefile 的選擇和執行需要整合到現有的 workflow

### 業務限制

- **維護者非韌體專家**：無法判斷 makefile 的正確性，依賴韌體工程師
- **規模不確定性**：未來 SDK/開發板的數量未知，難以評估設計是否過度或不足

---

## Scope & Boundaries

### In Scope（要解決）

1. ✅ **Template 的組織方式**
   - 資料夾結構或命名規則
   - 如何區分 build 和 flash template
   - 如何處理配套的 script（build.ps1、flash.sh 等）

2. ✅ **Template 的 metadata schema**
   - 如何描述 template 的適用範圍（廠商、型號、工具鏈、作業系統）
   - 如何讓 init 流程讀取並顯示這些資訊

3. ✅ **Init 流程的 template 選擇機制**
   - 使用者如何選擇 template（選單、搜尋、AI 輔助）
   - 如何引導使用者填寫定製資訊
   - 如何處理「沒有合適 template」的情況

4. ✅ **使用者定製 makefile 的機制**
   - 如何讓使用者基於 template 進行定製
   - 定製資訊如何存儲（config.toml）
   - 如何支援未來的「空白 template / AI 生成 / 引導式生成」

### Out of Scope（不解決）

1. ❌ **Makefile 內部的實作細節**
   - 如何撰寫 makefile（由韌體工程師負責）
   - 如何呼叫具體的編譯/燒錄工具

2. ❌ **Makefile 正確性驗證**
   - 如何測試 makefile 是否能正常工作
   - 錯誤處理和 debug 流程

3. ❌ **跨平台相容性問題**
   - 已由現有的 makefile wrapper 處理（PowerShell on Windows, Shell on Linux）

4. ❌ **韌體工程師的培訓**
   - 如何教韌體工程師撰寫符合 fwauto 結構的 makefile
   - （但需要提供文件和範例）

### Edge Cases

1. **使用者選錯 template**
   - 例如：AM62x 專案選了 STM32 template
   - 處理方式：允許重新執行 init，或提供 `fwauto reinit` 命令

2. **同一專案支援多個開發板**
   - 例如：同時編譯 STM32 和 AM62x
   - 處理方式：超出目前範圍，未來可考慮「多 target 支援」

3. **廠商提供的工具路徑變更**
   - 例如：Keil 升級後路徑改變
   - 處理方式：使用者可手動修改 config.toml

4. **Template 之間的相依性**
   - 例如：某些 template 需要共用的 script
   - 處理方式：待設計（可能需要 shared/ 目錄）

---

## Next Steps

### 建議的後續步驟

1. **驗證假設（高優先級）**
   - 與韌體工程師確認：AM62x 的 makefile 需要哪些資訊？
   - 驗證：「SDK 位置 + 開發板型號 + 編譯指令」是否足夠？
   - 驗證：Flash 方式（SD Card）如何整合成 makefile？

2. **原型設計（高優先級）**
   - 設計 template 的 metadata schema（考慮使用 TOML 或 JSON）
   - 設計 templates/ 目錄結構（建議：`templates/{board-id}/build/` 和 `templates/{board-id}/flash/`）
   - 設計 init 流程的 UX（選單格式、引導問題）

3. **最簡實作（MVP）**
   - 先支援 2 個板子（STM32F407 + AM62x）
   - 實作基本的 template 選擇機制
   - 驗證結構是否清晰、易擴展

4. **迭代擴展**
   - 加入第 3、4 個板子，驗證擴展性
   - 實作「空白 template」或「引導式生成」
   - 收集使用者反饋，調整設計

### 可執行的 Research 方向

如果您希望進入 `/prpi:research` 階段，建議的研究主題：

- **研究 1**：現有的 build system 管理機制（例如：CMake presets, Cargo features, Docker multi-stage builds）
- **研究 2**：Metadata schema 的最佳實踐（TOML vs JSON vs YAML，如何設計可擴展的 schema）
- **研究 3**：引導式 CLI 的 UX 設計（如何設計問卷式的 init 流程）

---

## Reflection

### 信心程度

**當前信心：8/10**

**信心來源**：
- 透過蘇格拉底提問，挖掘出「使用者定製」的核心需求
- 魔鬼代言人挑戰揭露了多個隱藏假設
- 確認了真實需求 vs 解決方案的界線

**仍有不確定性的部分**：
- 未來 SDK/開發板的數量和特性（規模不確定性）
- 韌體工程師提供的 makefile 是否符合預期（尚未驗證）
- Metadata schema 是否足以描述所有情境（需要實作驗證）

### 開放問題

1. **AM62x 的 Flash 方式（SD Card）如何整合成 makefile？**
   - 需要與韌體工程師確認具體流程

2. **是否需要「驗證機制」來檢查 template 的完整性？**
   - 例如：必填欄位檢查、makefile 語法檢查

3. **如何處理「template 更新」的情境？**
   - 例如：STM32 template 有新版本，已初始化的專案是否需要更新？

4. **是否需要支援「template 繼承」或「組合」？**
   - 例如：多個板子共用相同的 flash template

### 建議的驗證方式

- **實作 AM62x 的整合**：用真實案例驗證設計是否可行
- **模擬 5-10 個板子**：測試擴展性和可維護性
- **邀請韌體工程師 review**：確認 makefile 結構符合實務需求

---

## 版本資訊

- **文件版本**：1.0
- **診斷方法**：Socratic Inquiry v4.0.3
- **診斷時間**：2025-10-22
- **Git Commit**：b85ef7694e97be904f3a8eb88f6c0ae8daf18c7c
- **Git Branch**：main
