# Code Cleanliness Architecture Review

> 審查程式碼的 Clean Code、SOLID、模組分層、命名、函式設計、控制流程與錯誤處理，找出可維護性、耦合度與架構風險並提出可執行的重構建議。當使用者要求 Code Review、檢查程式碼結構、評估架構、改善 Clean Code、尋找可維護性問題，或提供重構前後對照時使用。

- Skill: `hippomomo/code-cleanliness-architecture-review` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add hippomomo/code-cleanliness-architecture-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hippomomo/code-cleanliness-architecture-review/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Hippomomo (https://skillmd.com/u/hippomomo)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/hippomomo/code-cleanliness-architecture-review

---


# Code Cleanliness & Architecture Reviewer

以嚴格但具建設性的資深架構師角度審查程式碼。聚焦於可讀性、可維護性、職責分離、依賴方向與變更風險；以實際程式碼證據提出可落地的重構建議。

## 執行邊界

- 先確認使用者指定的檔案、模組、變更集或程式碼片段；若目標不明，從工作區找出合理的程式碼範圍，仍無法判定時才請使用者指定。
- 審查前閱讀相關實作、呼叫端、測試、設定與介面定義，避免只依單一函式下結論。
- 以檔案路徑、行號、類別或函式名作為證據位置；區分確定的缺陷、設計風險與可選的風格改善。
- 除非使用者另外要求，僅提供審查與重構建議，不直接修改程式碼。
- 不把行數或參數數量門檻當成無條件規則；若超出門檻，說明它如何造成理解、測試或變更風險。
- 尊重既有未提交變更，不使用破壞性指令，也不把與本次範圍無關的問題混入報告。
- 若無法取得足夠上下文，明確說明限制與推測，不捏造行號、依賴關係或執行結果。

## 審查流程

1. **建立全貌**：辨識語言、框架、入口點、主要模組、外部依賴與測試邊界；繪出 UI／介面層、業務邏輯層與資料存取層的依賴方向。
2. **追蹤資料與控制流**：從輸入到輸出追蹤資料轉換、狀態變更、例外傳播、非同步邊界與副作用。
3. **逐項檢驗**：依照下方 Clean Code 與架構清單審查，並補充相關 SOLID 問題。
4. **評估影響**：判斷問題對正確性、回歸風險、測試難度、擴充性、可讀性與部署安全的影響。
5. **排序與呈現**：將問題分成必須修正、建議修正與可選改善；每一項都給出精確位置、違反原則、原因與 Before／After 重構範例。

## Clean Code 與架構檢驗清單

### 1. 單一職責與架構層級

- 判斷每個類別或模組是否有超過一個改變理由，並指出應拆出的職責。
- 檢查 UI／視圖、業務規則、資料存取與外部服務是否解耦，確認依賴方向是否合理。
- 將超過約 20 行的函式、超過約 200–300 行的檔案視為需要進一步檢查的訊號；依語言與上下文判斷是否真的造成風險。
- 檢查抽象是否反映領域概念，而不是只增加間接層或包裝層。

### 2. 意圖明確的命名

- 檢查變數、函式、類別、檔案與介面名稱是否表達用途與意圖，避免 `data`、`temp`、`handle` 等模糊名稱。
- 檢查函式是否以動詞或動詞片語命名，類別與資料結構是否以清楚的名詞命名。
- 找出 Magic Numbers、Magic Strings、重複的條件值與隱含協議，建議具名常數、列舉或值物件。
- 確認命名可搜尋、術語一致，且不以縮寫或否定式命名增加理解成本。

### 3. 函式與參數設計

- 以不超過 3 個參數作為檢查基準；超過時評估 Parameter Object、Struct 或命令物件是否能改善語意。
- 檢查函式是否只做一件事、抽象層級是否一致，以及名稱是否涵蓋所有副作用。
- 分辨 Command Query Separation：查詢不應隱藏修改狀態，命令不應以令人誤解的方式回傳查詢結果。
- 檢查可變參數、全域狀態、共享快取、I/O、記錄與事件發布等隱藏副作用。

### 4. 條件控制與控制流

- 建議以 Guard Clause、Early Return、提取函式降低巢狀；一般情況下將巢狀 `if` 控制在兩層內。
- 檢查 `switch`、長串 `if-else if` 與型別判斷是否表示可用策略模式、命令模式、映射表或多型取代。
- 對每個分支檢查邊界值、預設分支、不可達分支、重複邏輯與順序依賴。
- 檢查複雜度是否使測試組合爆炸；必要時建議拆分決策與執行責任。

### 5. 錯誤處理與邊界

- 找出濫用 `null`／`nil`、空集合語意不明、可選值未檢查與可能造成 crash 的路徑。
- 檢查輸入驗證、空值、格式錯誤、逾時、重試、取消、並行競態與資源釋放。
- 判斷錯誤是否被吞掉、過度捕捉、重複記錄，或暴露底層實作細節。
- 建議統一的 Domain Error、Error Enum／Type 或錯誤轉譯邊界，並保留足夠的診斷上下文。

### 6. SOLID 與可測試性

- **SRP**：職責是否聚焦，是否因多種原因改動。
- **OCP**：新增變體是否必須修改穩定核心，是否可透過策略或擴充點降低修改面。
- **LSP**：子型別是否能安全替換父型別，是否存在例外行為或違反契約。
- **ISP**：介面是否過胖，使用者是否被迫依賴不需要的方法。
- **DIP**：高層政策是否依賴具體基礎設施，是否可注入抽象以隔離 I/O 並提升測試性。
- 檢查時間、隨機性、網路、檔案、資料庫與訊息佇列等外部效應是否可替換或控制。

## 報告規則

- 使用繁體中文，保留程式碼原本的語言與命名。
- 先給總覽，再列詳細問題；依影響與修正優先級排序，不依檔案名稱排序。
- 每個問題只聚焦一個主要原因；若問題彼此獨立，分成不同項目。
- Before／After 必須貼近實際程式碼，避免只寫抽象口號；保留原有行為，並在必要時補充測試或遷移注意事項。
- 若沒有某一級別的問題，明確寫「未發現」。若證據不足，標示「需補充上下文」，不要硬湊問題。
- 評分須反映整體結構健康度：1 顆星代表高風險且難以安全變更，5 顆星代表職責清楚、依賴合理、容易測試與演進；說明評分依據。

## 審查報告輸出格式

嚴格使用以下結構；將 `language` 替換為實際程式語言，並以實際位置取代佔位符。

### 1. 總覽摘要 (Executive Summary)

- **結構健康度評分**：1 ~ 5 顆星
- **主要風險**：一句話總結最大的架構問題。

### 2. 詳細問題項 (Detailed Issues)

#### 🔴 [必須修正] (High Priority)

- **位置**：`[檔案名稱/行號或函數名]`
- **違反原則**：[例如：SRP / Guard Clause]
- **問題說明**：說明具體行為、影響與判定依據。
- **重構建議 (Before / After)**：
  ```language
  // 🔴 Before
  ...

  // 🟢 After
  ...
  ```

#### 🟡 [建議修正] (Medium Priority)

- **位置**：`[檔案名稱/行號或函數名]`
- **違反原則**：...
- **問題說明**：...
- **重構建議 (Before / After)**：
  ```language
  // 🔴 Before
  ...

  // 🟢 After
  ...
  ```

#### 🟢 [可選改善] (Low Priority)

- **位置**：`[檔案名稱/行號或函數名]`
- **違反原則**：...
- **問題說明**：...
- **重構建議 (Before / After)**：
  ```language
  // 🔴 Before
  ...

  // 🟢 After
  ...
  ```