# Codebase Cleanup

> 清理整個專案裡冗長反覆的註解與過時的文件，並找出繞路、多餘的程式碼設計提出改進方案。當使用者要求整理註解、清理專案、檢查註解是否過時或囉唆、更新 README 或 spec、或想知道專案裡有哪些繞圈的設計時，使用這個 skill。註解與文件直接修改，程式碼本身不動、只回報建議。

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

---


# 專案清理

**直接修改**：註解、README、spec 與其他文件。
**不修改、只回報**：程式碼本身的結構問題。

這條界線不要跨過。使用者要的是能安心執行的整理，不是夾帶重構的大改。即使某段程式碼的問題很明顯、改起來也很小，仍然只寫進報告。

## 開始之前

先看 `git status`。工作區若有未提交的變更，提醒使用者先 commit —— 這樣清理結果可以用 diff 逐條檢查。若不是 git 專案，先說明「這次會直接改檔案」再開始。

接著列出處理範圍。排除 `.git/`、`node_modules/`、`vendor/`、`dist/`、`build/`、lock 檔、程式碼產生器的輸出（檔頭通常有 DO NOT EDIT 或 auto-generated）、第三方原始碼、測試用的固定資料檔。

專案大的時候依目錄分批處理，邊做邊維護一份發現清單，不要全部讀進來再一次處理。

## 註解：刪、留、還是改寫

### 刪掉

- 過程記錄：「原本用 A，後來改成 B」「2024/3 修正：…」「這段從舊版搬過來」
- 覆述程式碼在做什麼：`// i 加一` 配 `i++`
- 常識可推斷的：`// 建構子`、`// getter`、`// 匯入套件`
- 被註解掉的舊程式碼 —— 版本控制已經保存了
- 已經完成的 TODO
- 開發中的自言自語：「先這樣」「之後再處理」而後面沒有下文
- 同一個警語在鄰近位置重複第三次

### 保留

- 說明**為什麼**、而且理由從程式碼本身讀不出來的。「這裡不能用 X，某情況下會死鎖」是前人踩過的坑，刪掉之後下一個人會再踩一次 —— 這類註解是整個清理過程中最容易誤傷、也最不該誤傷的東西。
- 外部系統的怪癖、API 的非直覺行為、平台相容性處理
- 帶 issue 編號、ticket 或外部連結的
- 授權標頭、法規與安全性相關
- 演算法出處、公式推導、效能取捨的理由
- 還沒解決的 TODO / FIXME

### 改寫

保留類的註解若寫得冗長，留住理由、砍掉贅述。三段話能壓成一句就壓成一句。

### 判斷不出來就留著

寫進報告的「需要你確認」區，讓使用者決定。誤刪一條關鍵註解的代價，遠大於多留一條廢話。

## 文件

README、spec、設計文件、`docs/` 底下的內容：

- 提到已不存在的檔案、指令、參數、API → 修正成現況
- 安裝或執行步驟跟實際依賴對不上 → 修正
- 寫著「未來會做」但其實已經做完 → 更新為現況
- 寫著「未來會做」而確實還沒做 → **這不是過時，保留**。目標尚未實現不等於文件錯了。
- 文件描述的設計與實作不一致 → **不要自動改文件去配合程式碼**。有可能是實作偏離了設計，而使用者想修的是實作那一邊。寫進報告讓他決定方向。

## 程式碼：只找不改

掃過程式碼時記下這些，但一行都不要動：

- 同樣的邏輯在多處重複
- 繞路的控制流：多層巢狀可以早退出、條件可以合併、拆成兩半又立刻合回去
- 死程式碼：沒人呼叫的函式、永遠成立的條件、到不了的分支
- 為了早已消失的需求留下的相容處理與旗標
- 只有一個實作的抽象層、只被呼叫一次的包裝函式
- 過度防禦：對不可能為 null 的東西反覆檢查
- 跟專案其他地方明顯不一致的寫法

每一項要寫清楚：位置、問題是什麼、建議怎麼改、改了的風險在哪。使用者看完要能直接決定做或不做。

## 改完之後

跑一次 build 或測試。註解改動理論上安全，但多行註解的起訖符號很容易弄錯，確認一下比較保險。

**不要自動 commit。** 讓使用者檢查後自己決定。

## 報告格式

```
## 已修改

### 註解（N 處）
- path/to/file.ts:42 — 刪除 — 記錄了 2023 年一次改版的經過
- path/to/other.py:88 — 改寫 — 保留死鎖的原因，壓縮成一行

### 文件（N 處）
- README.md — 更新安裝步驟，原本寫的套件版本已經不是現在用的
- docs/spec.md — 移除已完成的「待實作」段落

## 發現但未修改的程式碼問題（N 項）

### 1. [src/handler.go:120-180] 三層巢狀可以攤平
問題：…
建議：…
風險：…

## 需要你確認（N 項）
- src/legacy.js:30 有一段警語說不要改成非同步，但沒寫原因，也找不到相關 issue。
  我保留了 —— 你知道背景嗎？

## 文件與實作分歧（N 項）
- docs/api.md 說會回傳排序後的結果，實作沒有排序。要改哪一邊？
```

最後用兩三句話講整體印象：專案的註解習慣如何、文件跟不跟得上實作、最值得優先處理的結構問題是哪一個。