ARES 專案初始化：建立專案骨架、技術規格與協作架構¶

---

背景¶

ARES（災難現場高韌性電子檢傷系統）需在無網際網路、無 GPS、無預先佈建 Beacon 的災難現場提供即時電子傷票管理。專案採用多 Agent 協作開發模式（共 10 個 Agent），需在開發啟動前完成以下初始化工作：專案根設定檔、Agent 角色定義、核心技術規格、調研工作流目錄、架構決策記錄目錄、工程開發目錄佔位。

---

一、專案根設定檔與 Agent 角色定義¶

1-1. 建立專案根設定檔 CLAUDE.md ¶

定義以下項目：

• 專案目標：在無網際網路、無 GPS、無預先佈建 Beacon 的災難現場提供即時電子傷票管理系統
• 目錄結構規範：12 個頂層目錄/檔案的用途說明
• 規格文件使用規則：
  • docs/specs/ 為唯一可信技術決策來源
  • 三級狀態標籤定義：✅ 已確認（可據此開發）、⏳ 待驗證（需透過抽象層保留替換彈性）、❓ 待決定（禁止據此實作）
  • 規格變更流程：research-synthesizer → system-architect 審核 → 更新 docs/specs/ → Agent 自動讀取
  • 規格變更權限：僅 system-architect 可執行
• 人工資料輸入規則：
  • 存放路徑：docs/research/human-input/
  • 命名格式：YYYY-MM-DD_[主題].md
  • research agent 開始工作前必須先讀取此目錄
  • 人工資料不直接修改 docs/specs/，需經 research 流程確認
• 10 條協作規則：涵蓋溝通語言（繁中/英文程式碼）、規格讀取義務、❓ 禁止實作、⏳ 抽象層要求、ADR 記錄義務、QA 通知義務、devil-advocate 挑戰流程等

1-2. 建立 10 個 Agent 角色定義（.claude/agents/）¶

Agent	層級	模型	核心職責
project-manager	管理層	sonnet	任務分解與分配、跨子系統依賴追蹤、觸發 QA 驗證與 devil-advocate 挑戰
system-architect	架構層	opus	維護 docs/specs/ 規格文件、定義子系統介面、審核跨系統設計變更、管理 ADR
firmware-engineer	工程層	sonnet	ESP32 韌體開發（4 個 FreeRTOS Task：Triage/Network/Sensor/Localization）、HAL 抽象層、Doxygen 文件
rf-specialist	工程層	sonnet	Mesh 路由設計、RSSI 定位模型、DTN Store-and-Forward、極端場景評估
android-developer	工程層	sonnet	指揮平板 App（傷患列表、拓撲視覺化、雷達視圖、衝突解決介面）、Repository Pattern 隔離
qa-engineer	品質層	sonnet	測試計畫設計（正常/異常/邊界/BLOCKED）、4 個必測場景（網路分區合併、斷電保持、併發衝突、Mesh 自癒合）
devil-advocate	挑戰層	sonnet	挑戰技術假設（格式：具體失敗場景 + 替代方案 + 補充驗證需求）、優先挑戰 ❓ 項目
research-primary	調研層	sonnet	技術文獻搜尋（IEEE/ACM/datasheet/實測報告）、結構化調研報告、優先處理 ❓ 項目
research-verifier	調研層	sonnet	獨立查證（不同關鍵字切入、搜尋反例、驗證測試條件是否匹配廢墟環境）
research-synthesizer	調研層	opus	可信度判斷（4 級：✅ 建議升級 / ⏳ 維持待驗證 / ⚠️ 有爭議 / ❌ 建議放棄）、整合人工資料與網路文獻

---

二、核心技術規格文件（docs/specs/）¶

2-1. docs/specs/constraints.md — 不可違反的設計約束¶

10 條跨所有技術選型的硬性約束，分四大類：

• 系統層級（3 條）：
  • 離線優先：系統在無網際網路、無 GPS 環境下必須完整運作
  • 自組網：通訊網路必須具備 Self-Forming 與 Self-Healing 能力
  • 無需預佈建基礎設施：不依賴預先安裝的 Beacon 或 AP
• 硬體層級（3 條）：
  • 斷電保持：e-Tag 斷電後顯示器必須維持最後的檢傷狀態
  • 夜間可見：黑暗環境下傷患位置必須可被發現
  • 極端環境生存：泥水、撞擊環境下連續工作 48 小時以上
• 資料層級（3 條）：
  • 嚴重度優先：衝突解決 RED > YELLOW > GREEN，不可逆轉
  • 資料不丟失：所有狀態變更進入 append-only log，禁止直接覆蓋
  • 最終一致性：網路分區後重新連線時資料必須能正確合併
• 安全層級（1 條）：
  • 充電孔禁令：禁用實體 USB 充電孔，防止泥水進入

2-2. docs/specs/hardware.md — 硬體規格¶

組件	候選方案	狀態	待確認事項
MCU	ESP32-S3（雙核 240MHz，ULP 協處理器）	⏳ 待驗證	EKF 矩陣運算實際負載效能
無線通訊（主要）	Newracom NRC7292 / Morse Micro MM6108（Wi-Fi HaLow）	❓ 待決定	市場可取得性、交期、單價、SPI 整合難度
無線通訊（備援）	BLE 5.0	✅ 已確認	—
顯示器	E-Ink Spectra 6（紅黃黑白四色）	⏳ 待驗證	-10°C~60°C 穩定性、實際刷新時間
夜間發光	WS2812B RGB LED	⏳ 待驗證	IP67 外殼整合方式
電池	18650 LiFePO4 3500mAh	⏳ 待驗證	反覆充放電容量衰退曲線
電池（替代）	18650 Li-Ion 3500mAh	（備選）	安全性較低但取得性較高
防護等級	IP67	⏳ 待驗證	—
充電方式	磁吸式 Pogo Pin 或 Qi 無線充電	⏳ 待驗證	禁用實體 USB 孔（constraints #10）

2-3. docs/specs/network.md — 網路與通訊規格¶

• 主要通訊協議：IEEE 802.11ah（Wi-Fi HaLow），Sub-1GHz（900/868MHz），目標覆蓋 1km 視距 ⏳、多層混凝土穿透 ❓
• Mesh 路由：候選 802.11s 或樹狀路由 ❓、功耗路由策略（依剩餘電量動態決定中繼資格）⏳、DTN Store-and-Forward ⏳
• 定位系統：RSSI 三角測量 ⏳、路徑損耗指數 n（廢墟估計 2.5–4.0）❓、目標精度 3–5 米 ❓、EKF 濾波 ⏳、錨點不足降級行為 ❓
• 電源管理：休眠電流 < 50µA ⏳、峰值 TX ~300mA、續航 48h+ ⏳

2-4. docs/specs/software-stack.md — 軟體技術棧¶

• 韌體層：ESP-IDF + FreeRTOS ⏳（依 MCU 最終選型）、C 語言 ✅、RSSI + EKF 定位 ⏳
• Android 應用層：Kotlin ✅、MVVM + Repository Pattern ✅、離線 DB（RxDB vs Room + 自訂同步）❓、MapLibre Native 離線圖資 ⏳、自訂 Canvas View ✅
• 資料同步層：CouchDB 相容複製協議 ⏳、衝突解決（CRDTs vs Vector Clocks）❓、嚴重度優先規則 ✅、Append-Only Log ✅

---

三、Research 工作流目錄與待調研問題清單¶

3-1. 建立 Research 工作流目錄¶

目錄	用途	產出者
docs/research/reports/	技術文獻調研報告	research-primary
docs/research/verifications/	獨立查證報告	research-verifier
docs/research/conclusions/	最終技術結論與規格建議	research-synthesizer
docs/research/human-input/	專案負責人手動提供的參考資料	專案負責人（人類）

3-2. 建立人工輸入 README（docs/research/human-input/README.md）¶

內容包含：

• 使用方式：每份資料建立獨立 .md 檔案，命名 YYYY-MM-DD_[主題].md
• 可信度分級說明：
  • 廠商 datasheet / 官方規格書：高可信度
  • 個人實測紀錄：中高可信度（注意測試條件）
  • 網路文章 / 論壇討論：中低可信度（需交叉確認）
• 當前檔案列表區塊（供手動維護）

3-3. 建立待調研問題清單（docs/research/open-questions.md）¶

從四份 specs 文件中彙整所有 ❓ 待決定項目，共 8 題，分三大類：

• 硬體相關（1 題）：
  • Wi-Fi HaLow 模組選型：NRC7292 vs MM6108 的市場可取得性、交期、單價、SPI 整合難度（來源：hardware.md）
• 網路與通訊相關（5 題）：
  • Mesh 路由協議：802.11s vs 樹狀路由（來源：network.md）
  • Wi-Fi HaLow 穿透能力：多層混凝土環境實測數據（來源：network.md）
  • RSSI 路徑損耗指數 n：廢墟環境實測值，估計範圍 2.5–4.0（來源：network.md）
  • 定位目標精度：3–5 米（區域級）可達成性（來源：network.md）
  • 錨點不足降級行為：定位系統在錨點數量不足時的處理策略（來源：network.md）
• 軟體相關（2 題）：
  • 離線資料庫選型：RxDB vs Room + 自訂同步邏輯，需確認 RxDB 在低階 Android 設備（2GB RAM）效能（來源：software-stack.md）
  • 衝突解決機制：CRDTs vs Vector Clocks（來源：software-stack.md）

---

四、架構決策記錄與子系統介面目錄¶

4-1. 建立 docs/decisions/ 目錄¶

用途：存放所有架構決策記錄（Architecture Decision Records, ADR）

ADR 格式規範（定義於 system-architect.md）：

## ADR-[編號]：[決策標題]
- 狀態：[提議 / 已確認 / 已廢棄]
- 背景：[為何需要做此決策]
- 決策：[選擇了什麼]
- 被否決的替代方案：[其他選項與否決理由]
- 已知弱點：[此決策的侷限性]

預期的首批 ADR 主題（待 research 團隊完成調研後產出）：

• 無線通訊模組最終選型（NRC7292 vs MM6108 vs 其他）
• Mesh 路由協議選型（802.11s vs 樹狀路由）
• 離線資料庫選型（RxDB vs Room + 自訂同步）
• 衝突解決機制選型（CRDTs vs Vector Clocks）

4-2. 建立 docs/interfaces/ 目錄¶

用途：存放子系統間的介面規格，由 system-architect 定義與維護

預期的介面定義：

• e-Tag 韌體 ↔ Mesh 網路（rf-specialist 與 firmware-engineer 的邊界）
• Mesh 網路 ↔ Android 指揮平板（rf-specialist 與 android-developer 的邊界）
• 資料同步層介面（跨 firmware 與 android 的 append-only log 格式）

---

五、工程開發目錄佈建¶

目錄	用途	主要負責 Agent	進入開發的前置條件
firmware/	ESP32 韌體程式碼	firmware-engineer	MCU 選型確認（hardware.md ESP32-S3 ⏳→✅）、通訊模組選型確認（❓→✅）
android/	指揮平板 Android App	android-developer	離線資料庫選型確認（software-stack.md ❓→✅）、衝突解決機制確認（❓→✅）
tests/	測試計畫與測試腳本	qa-engineer	可隨各功能完成逐步新增測試

---

驗收條件¶

專案根設定檔與 Agent¶

1. CLAUDE.md 包含完整的專案目標、目錄結構、規格使用規則、人工資料輸入規則、Agent 團隊組成、10 條協作規則
2. .claude/agents/ 目錄含 10 個 .md 檔案，每個包含 frontmatter（name、description、tools、model、color）與完整的行為指令
3. 每個 Agent 定義檔皆包含「開始工作前必讀」的規格文件清單
4. firmware-engineer 定義含 4 個 FreeRTOS Task 職責與程式碼規範（Doxygen、ISR 限制、HAL 隔離）
5. qa-engineer 定義含測試計畫格式與 4 個必測關鍵場景
6. research-synthesizer 定義含完整的可信度判斷原則（含人工資料交叉比對邏輯）

技術規格¶

1. 四份規格文件皆包含狀態標籤說明區塊
2. 每個規格項目皆明確標註 ✅ / ⏳ / ❓ 狀態及待確認事項
3. constraints.md 的 10 條約束涵蓋系統、硬體、資料、安全四個層級
4. 所有 ❓ 項目已同步至 docs/research/open-questions.md
5. hardware.md 中充電方式明確引用 constraints #10（禁用 USB 孔）

Research 工作流¶

1. 四個 research 子目錄皆已建立且可被 Git 追蹤
2. human-input/README.md 包含命名格式、可信度分級、檔案列表區塊
3. open-questions.md 包含 8 個 ❓ 項目，每題標註來源規格文件
4. 8 個問題與四份 specs 的 ❓ 項目完全對應（無遺漏、無多餘）
5. research-primary 可直接以此清單作為工作輸入啟動調研

架構決策與介面¶

1. docs/decisions/ 目錄已建立且可被 Git 追蹤
2. docs/interfaces/ 目錄已建立且可被 Git 追蹤
3. 兩個目錄目前為空（以 .gitkeep 保留），待後續 ADR 與介面定義產出後填入

工程目錄¶

1. firmware/、android/、tests/ 三個目錄皆已建立且可被 Git 追蹤（以 .gitkeep 保留）
2. 目錄命名與 CLAUDE.md 目錄結構章節一致