organic-san 專案清理
直接修改：註解、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 說會回傳排序後的結果，實作沒有排序。要改哪一邊？
最後用兩三句話講整體印象：專案的註解習慣如何、文件跟不跟得上實作、最值得優先處理的結構問題是哪一個。