Plan and Tech Debt

計畫與技術債

追蹤已知的技術債與對應的處理計畫。原則:先記錄、再排序、有空就還;不阻塞日常使用。

技術債清單

1. 舊版 neovim/ 目錄(高確定性、低風險)

• 現況:NvChad 2.5 之前的舊設定,已不再被連結,僅供參考;live 設定在 config.symlink/nvim/。
• 計畫:比對兩份設定,確認自訂片段(keymaps、plugins)都已遷移後,刪除或移到 archive branch。

2. Brewfile 膨脹

• 現況:約 370 formulae + 250 casks,必然包含已不使用的套件,拖慢 brew bundle 與新機安裝。
• 計畫:用 brew bundle cleanup --file=Brewfile(dry-run)盤點,分批確認移除;考慮拆成 core / optional 兩份。

3. 腳本群缺乏統一品質基準

• 現況:shellscripts/ 約 70 支 bash、pyscripts.symlink/ 約 47 支 Python,風格與錯誤處理不一,部分缺少用途說明。
• 計畫:
  • 新增/修改腳本一律過 shellcheck(bash)與 ruff(Python)。
  • 逐步在每支腳本開頭補一行用途註解;清單化後淘汰重複或死掉的腳本。

4. claude.symlink gitignore 白名單維護成本

• 現況:採「預設忽略、白名單追蹤」(.gitignore 58–67 行),新增檔案時容易忘記加白名單,導致變更默默不被追蹤。
• 計畫:在 pre-commit 或 dp 流程加一個檢查:提醒 claude.symlink/ 下有未追蹤且不在白名單的新檔案。

5. Bash 3.2 相容性限制只靠慣例維持

• 現況:start/ 要求 Bash 3.2 相容,但沒有自動驗證,只靠人記得。
• 計畫:CI 或 pre-commit 加 shellcheck --shell=bash 加上針對 Bash 4+ 語法(assoc array、${var,,})的 grep 檢查。

6. 文件雙軌:CLAUDE.md 與 docs/ Quarto book

• 現況:模組導覽在各 CLAUDE.md,較完整的說明在 docs/,兩邊可能漂移。
• 計畫:明確分工 —— CLAUDE.md 只放「給 AI 的操作指引 + 最小地圖」,人類文件集中在 docs/;定期(每季)對照一次。

排序原則

1. 安全相關優先(機密、憑證掃描)——已由 gitleaks + husky 覆蓋,維持即可。
2. 會默默壞掉的其次(gitignore 白名單、Bash 相容性)→ 用自動檢查取代人腦。
3. 只是佔空間的最後(舊 neovim/、Brewfile 瘦身)→ 有空再清。

記錄方式

• 新發現的技術債:直接在本頁加一節,寫清楚「現況 / 計畫」。
• 完成後不刪除,移到頁尾「已清償」區,留下處理紀錄。

已清償

• ✅ 外洩憑證清理 + gitleaks pre-commit(commit ad7eefb)。
• ✅ npm package-lock.json 移除,統一 pnpm(commit c1e4fd6)。
• ✅ zsh compdump 檔名錯誤 + 背景自我修復(commit 697a00f)。