Refactor Cleaner (重構清理)
When to Use
在以下情況使用此 Skill：
- 定期程式碼健康檢查
- 專案清理與整合
- 移除已廢棄功能
- 減少套件大小
- 整合重複程式碼
When NOT to Use
- 正在開發新功能時
- 生產部署前夕
- 程式碼庫不穩定時
- 測試覆蓋率不足時
核心職責
- 死代碼檢測 - 找出未使用的程式碼、exports、依賴
- 重複消除 - 識別並整合重複程式碼
- 依賴清理 - 移除未使用的套件和 imports
- 安全重構 - 確保變更不破壞功能
- 文件記錄 - 在 DELETION_LOG.md 追蹤所有刪除
檢測工具
# knip - 找出未使用的檔案、exports、依賴
npx knip
# depcheck - 識別未使用的 npm 依賴
npx depcheck
# ts-prune - 找出未使用的 TypeScript exports
npx ts-prune
# eslint - 檢查未使用的變數
npx eslint . --report-unused-disable-directives
重構流程
1. 分析階段
a) 平行執行檢測工具
b) 收集所有發現
c) 依風險分類:
- 安全: 未使用的 exports、依賴
- 小心: 可能透過動態 import 使用
- 風險: 公開 API、共用工具
2. 風險評估
對每個要移除的項目：
- 搜尋所有引用 (grep)
- 確認無動態 imports
- 檢查是否為公開 API
- 審視 git 歷史了解原因
- 測試對建構/測試的影響
3. 安全移除流程
a) 只從「安全」項目開始
b) 一次移除一個類別:
1. 未使用的 npm 依賴
2. 未使用的內部 exports
3. 未使用的檔案
4. 重複程式碼
c) 每批次後執行測試
d) 每批次建立 git commit
4. 重複整合
a) 找出重複的元件/工具
b) 選擇最佳實作:
- 功能最完整
- 測試最完善
- 最近使用的
c) 更新所有 imports 使用選定版本
d) 刪除重複
e) 驗證測試仍通過
刪除日誌格式
建立/更新 docs/DELETION_LOG.md：
# 程式碼刪除日誌
## [YYYY-MM-DD] 重構作業
### 移除的依賴
- package-name@version - 最後使用: 從未, 大小: XX KB
- another-package@version - 已被取代: better-package
### 刪除的檔案
- src/old-component.tsx - 取代為: src/new-component.tsx
- lib/deprecated-util.ts - 功能移至: lib/utils.ts
### 整合的重複程式碼
- src/components/Button1.tsx + Button2.tsx -> Button.tsx
- 原因: 兩個實作完全相同
### 移除的 Exports
- src/utils/helpers.ts - 函數: foo(), bar()
- 原因: 程式碼庫中無引用
### 影響
- 刪除檔案: 15
- 移除依賴: 5
- 移除程式碼行數: 2,300
- 套件大小減少: ~45 KB
### 測試
- 所有單元測試通過
- 所有整合測試通過
- 手動測試完成
安全檢查清單
移除任何東西前：
- 執行檢測工具
- Grep 搜尋所有引用
- 檢查動態 imports
- 審視 git 歷史
- 確認非公開 API
- 執行所有測試
- 建立備份分支
- 記錄於 DELETION_LOG.md
每次移除後：
- 建構成功
- 測試通過
- 無 console 錯誤
- 提交變更
- 更新 DELETION_LOG.md
常見移除模式
1. 未使用的 Imports
// 移除未使用的 imports
import { useState, useEffect, useMemo } from 'react' // 只用到 useState
// 只保留使用的
import { useState } from 'react'
2. 死代碼分支
// 移除不可達程式碼
if (false) {
// 永遠不會執行
doSomething()
}
// 移除未使用的函數
export function unusedHelper() {
// 程式碼庫中無引用
}
3. 重複元件
// 多個相似元件
components/Button.tsx
components/PrimaryButton.tsx
components/NewButton.tsx
// 整合為一個
components/Button.tsx (使用 variant prop)
4. 未使用的依賴
// 已安裝但未 import 的套件
{
"dependencies": {
"lodash": "^4.17.21", // 無處使用
"moment": "^2.29.4" // 已被 date-fns 取代
}
}
緊急恢復
如果移除後出錯：
# 1. 立即回滾
git revert HEAD
npm install
npm run build
npm test
# 2. 調查原因
# - 什麼失敗了?
# - 是動態 import?
# - 檢測工具遺漏了什麼?
# 3. 修正向前
# - 標記為「禁止移除」
# - 記錄為何檢測工具遺漏
# - 加上明確類型註解
最佳實踐
- 從小處著手 - 一次移除一個類別
- 頻繁測試 - 每批次後執行測試
- 完整記錄 - 更新 DELETION_LOG.md
- 保守行事 - 有疑慮就不移除
- Git Commits - 每個邏輯移除批次一個 commit
- 分支保護 - 總是在 feature branch 工作
- 同儕審查 - 合併前讓刪除被審查
- 監控生產 - 部署後觀察錯誤
Pull Request 範本
## 重構: 程式碼清理
### 摘要
死代碼清理，移除未使用的 exports、依賴和重複。
### 變更
- 移除 X 個未使用的檔案
- 移除 Y 個未使用的依賴
- 整合 Z 個重複元件
- 詳見 docs/DELETION_LOG.md
### 測試
- [x] 建構通過
- [x] 所有測試通過
- [x] 手動測試完成
- [x] 無 console 錯誤
### 影響
- 套件大小: -XX KB
- 程式碼行數: -XXXX
- 依賴: -X 套件
### 風險等級
低 - 僅移除可驗證的未使用程式碼
詳見 DELETION_LOG.md。
成功標準
清理作業後：
- 所有測試通過
- 建構成功
- 無 console 錯誤
- DELETION_LOG.md 已更新
- 套件大小已減少
- 生產環境無回歸