tt-a1i/simplify-codebase

簡化程式碼庫 – 用於安全程式碼庫清理的 AI 代理技能

是什麼

• 一種 AI 程式碼代理（例如 Codex、基於 OpenAI 的機器人）的 技能（外掛程式），協助它們 審計 現有程式庫，證明 某段程式碼可安全移除，然後 應用 移除操作，同時保留完整的證據紀錄。
• 它不是通用的 linter 或無用程式碼移除工具；專注於 意外複雜性，例如過時的 API、孤立的狀態、重複的抽象或相容性適配層，僅在效益超過維護成本時才刪除。

如何運作

模式	範圍	功能
調查（唯讀）	聚焦 – 單一子系統，或 廣泛 – 整個程式庫	掃描檔案、執行時註冊、資料格式和外部消費者，產生附帶證明紀錄的「簡化候選」排名清單。
變更（授權編輯）	相同範圍	候選項目被證明安全後，執行刪除，執行最小驗證套件，並產生還原計畫。

每個候選項目都附帶一個 證明紀錄，列出：

• 所有權邊界、檔案和行號
• 引入的維護負擔
• 誰（測試、執行時、外部服務）在使用它
• 精確的刪除邊界（包含共用檔案成員）
• 將遺失的相容性或可觀測行為
• 捕捉錯誤刪除的最小測試
• 與遷移成本相比的淨複雜性降低量

關鍵防護機制

• 絕不觸碰公開 API、外掛程式註冊、資料遷移路徑、並行原語，或任何仍有已驗證消費者的工件。
• 若無法識別真實消費者，則建議 保留 程式碼，而非猜測。

安裝

# 推薦用於 Codex 相容代理
git clone https://github.com/tt-a1i/simplify-codebase.git ~/.codex/skills/simplify-codebase

• 任何尊重 SKILL.md 元資料的代理平台均可載入該技能。
• 內建輕量級 HTML 渲染器（Node ≥ 18，無需額外 npm 套件），支援可選的視覺化報告。

典型使用模式

# 1️⃣ 審計整個程式庫，不作變更
$simplify-codebase audit --scope broad --dry-run

# 2️⃣ 調查特定旗標或狀態
$simplify-codebase survey --focus readiness-flags

# 3️⃣ 應用已驗證的簡化
$simplify-codebase change --candidate 42 --apply

# 4️⃣ 合併來自 PR 的發現
$simplify-codebase integrate --pr 123

# 5️⃣ 產生互動式清理地圖（HTML）
$simplify-codebase report --visual

• 命令預設返回 文字證明報告；加入 --visual 會產生一個自包含的 HTML 地圖，展示已確認的元件及其關係。

輸出

• 調查報告 – 覆蓋範圍描述、排名證明紀錄、反例、未解決問題和下一步所需證據。
• 變更報告 – 實際檔案差異、分層驗證結果、殘餘風險評估、操作收據和可逆的「還原」指令碼。
• 可選視覺化報告 – 使用內建的 Archify 渲染器建構的互動式桌面友善 HTML 頁面；僅顯示已驗證發現，絕不展示推測的執行時影響。

成熟度

• 在一個包含 973 個檔案的混合 Python/TypeScript 專案中驗證，涵蓋變更、廣泛、整合和決策紀錄情境。
• 測試套件與契約檔案位於 visualization/test/ 和 docs/validation.md。

貢獻

• 歡迎提交問題與 PR，特別是揭露遺漏消費者、誤刪或驗證流程缺口的情況。

授權

• MIT（見 LICENSE）。

---

Simplify Codebase 是一種專用的 AI 代理擴充，為大型遺留程式碼庫引入形式化、基於證據的精簡，協助團隊在不冒隱藏破壞風險的前提下降低長期維護負擔。