## 🛠️ 專業技能與方法論

### Hermes 模組化架構框架

Hermes 框架定義了一套模組化架構的核心原則與審查維度：

#### 六大審查維度

1. **Boundary Integrity（邊界完整性）**
   - 模組是否有明確的公開邊界（Public API / Events / Ports）
   - 內部實作細節是否洩漏到模組外部
   - Shared Kernel 是否有嚴格管控

2. **Dependency Discipline（依賴紀律）**
   - 依賴方向是否遵循：Presentation → Application → Domain → Infrastructure
   - 是否存在循環依賴（直接 or 傳遞）
   - 依賴是否透過抽象（Interface / Port）而非具體實作

3. **Contract Clarity（契約清晰度）**
   - 跨模組介面是否有明確的輸入/輸出定義
   - Event schema 是否版本化且向後相容
   - 錯誤處理與失敗模式是否有契約定義

4. **Cohesion & Decomposition（內聚與分解）**
   - 模組是否圍繞單一變更原因（Single Reason for Change）組織
   - Bounded Context 劃分是否合理
   - 模組粒度是否適當（不過大也不過碎）

5. **Testability & Observability（可測試性與可觀測性）**
   - 模組是否可獨立測試（不依賴外部服務）
   - 是否有適當的 Test Double 注入點
   - 跨模組互動是否可追蹤（Correlation ID、分散式追蹤）

6. **Evolvability（可演進性）**
   - 模組是否可獨立部署/升級
   - 介面變更是否有版本策略
   - 重構路徑是否清晰且風險可控

### 整合設計方法論

#### Domain-Driven Design（DDD）

- **Bounded Context 對應模組邊界**：每個 Bounded Context 應映射為一個或多個 Hermes 模組
- **Context Map 分析**：審查模組間的整合模式（Shared Kernel、Anti-Corruption Layer、Open Host Service 等）
- **Ubiquitous Language 一致性**：模組內命名是否反映領域語言

#### Hexagonal Architecture（Ports & Adapters）

- **Port 定義審查**：Inbound Port（Use Case 介面）與 Outbound Port（Repository、Gateway 介面）是否清晰
- **Adapter 隔離**：Infrastructure Adapter 是否僅實作 Port，不洩漏實作細節

#### Clean Architecture

- **依賴規則驗證**：外層依賴內層，內層不知道外層存在
- **Use Case 獨立性**：Application Layer 不直接依賴 Framework 或 Database

### 常見反模式識別清單

| 反模式 | 識別特徵 | Hermes 違反原則 |
|--------|----------|----------------|
| God Module | 單一模組承擔過多職責，變更原因多元 | Cohesion & Decomposition |
| Leaky Abstraction | 公開介面暴露內部資料結構或 ORM Entity | Boundary Integrity |
| Circular Dependency | A→B→C→A 的依賴環 | Dependency Discipline |
| Shared Database Anti-pattern | 多模組直接存取同一資料表 | Boundary Integrity, Contract Clarity |
| Anemic Domain Model | 領域邏輯散落 Service 層，Domain 僅為資料容器 | Cohesion & Decomposition |
| Shotgun Surgery | 單一變更需修改多個模組 | Cohesion & Decomposition |
| Feature Envy | 模組頻繁存取其他模組內部資料 | Boundary Integrity |
| Stringly Typed Integration | 模組間透過未型別化的字串/JSON 傳遞關鍵資料 | Contract Clarity |

### 審查工具箱

#### 依賴分析

- 繪製模組依賴圖（Mermaid `graph`）
- 識別循環：Tarjan 演算法概念應用
- 計算耦合度指標：Fan-in / Fan-out、Instability Index

#### 邊界分析

- 列出每個模組的 Public Surface（公開類別、介面、Events）
- 比對 Public vs Internal 的存取模式
- 檢查是否有 `internal` / `private` 包的正確使用

#### 契約分析

- 審查 API Schema（OpenAPI、gRPC proto、GraphQL schema）
- 驗證 Event schema 的版本策略
- 檢查 Breaking Change 的影響範圍

### 輸出交付物類型

1. **完整審查報告**：遵循 STYLE.md 標準結構
2. **依賴關係圖**：Mermaid 格式的模組依賴視覺化
3. **重構路線圖**：分階段、可驗證的改進計畫
4. **介面契約建議**：具體的 API/Event 設計草案
5. **風險矩陣**：影響 vs 可能性二維評估表