TTechSpecs

指令用途

/improve-codebase-architecture 是一個架構分析和改進工具。它會掃描整個程式碼庫，找出可以深化的模組和改進機會，產生視覺化的 HTML 報告，然後讓你選擇要進一步探討的項目。

這就像有一個資深架構師在幫你審查程式碼庫，找出潛在的改進空間。

運作流程

  1. 掃描程式碼庫：分析所有檔案和模組的結構。
  2. 識別深化機會：找出耦合度高、複雜度高、可維護性差的模組。
  3. 產生報告：生成視覺化的 HTML 報告，包含架構圖和改進建議。
  4. 選擇項目：你選擇要進一步探討的項目。
  5. 深入追問：針對選定項目進行更深入的分析和追問。

實戰對話範例

範例一：完整掃描

  • You: 
    /improve-codebase-architecture
  • AI:

    開始掃描程式碼庫…

    掃描完成：找到 3 個可能的改進項目

    報告已產生：docs/architecture/2026-08-02-report.html

    改進項目：

    1. 高耦合模組：UserService 和 OrderService 耦合度過高

      • 影響：難以維護、測試困難
      • 建議：提取共同邏輯到新的服務

    2. 過大模組：DataProcessor 超過 2000 行

      • 影響：難以理解、修改風險高
      • 建議：拆分為更小的模組

    3. 循環依賴：AuthService 和 UserService 互相依賴

      • 影響：無法獨立部署、測試困難
      • 建議：重新設計介面，打破循環依賴

    你想深入探討哪個項目？（輸入 1、2 或 3）

    • You:

    1

    AI: 讓我們深入探討 UserService 和 OrderService 的耦合問題。

    詳細分析：

    當前問題：

    • UserService 直接調用 OrderService 來獲取使用者的訂單
    • OrderService 直接調用 UserService 來獲取訂單的使用者資訊
    • 這造成雙向依賴，任何一個改動都可能影響另一個

    影響：

    • 無法獨立測試
    • 無法獨立部署
    • 修改一個服務可能需要同步修改另一個

    建議方案：

    方案 1：提取 OrderQueryService

    • 建立新的服務專門處理訂單查詢
    • UserService 和 OrderService 都依賴這個新服務
    • 打破直接依賴

    方案 2：使用事件驅動

    • 使用訂單創建事件
    • UserService 監聽事件來更新使用者統計
    • 移除直接調用

    你傾向哪個方案？或者有其他想法？

範例二：針對特定模組

  • You: 
    /improve-codebase-architecture --module=UserService
  • AI:

    針對 UserService 進行深入分析…

    分析結果：

    模組大小：1500 行

    • 警告：超過建議大小（1000 行）

    複雜度：

    • 圈複雜度：35
    • 警告：超過建議值（20）

    耦合度：

    • 依賴：15 個模組
    • 警告：超過建議值（10）

    可維護性：

    • 測試覆蓋率：60%
    • 警告：低於建議值（80%）

    改進建議：

    1. 拆分模組：

      • 提取使用者認證邏輯到 AuthService
      • 提取使用者資料庫操作到 UserRepository
      • 保持 UserService 只處理業務邏輯

    2. 減少複雜度：

      • 提取複雜的條件判斷到策略模式
      • 使用工廠模式簡化物件創建

    3. 提高測試覆蓋率：

      • 添加單元測試覆蓋所有公開方法
      • 添加集成測試驗證與資料庫的互動

    你想深入探討哪個建議？（輸入 1、2 或 3）

    • You:

    1

    AI: 讓我們深入探討拆分模組的方案。

    當前問題： UserService 處理了太多職責：

    • 使用者認證
    • 使用者資料存儲
    • 使用者資料查詢
    • 使用者權限檢查

    建議拆分：

    AuthService：

    • 負責使用者認證
    • 提供介面：authenticate(username, password)
    • 不處理資料庫操作

    UserRepository：

    • 負責使用者資料存儲和查詢
    • 提供介面：createUser(user), getUser(id)
    • 封裝所有資料庫操作

    UserService：

    • 負責使用者業務邏輯
    • 依賴 AuthService 和 UserRepository
    • 不直接處理認證和資料庫

    優點：

    • 每個模組職責單一
    • 容易測試
    • 容易維護

    挑戰：

    • 需要重構現有程式碼
    • 需要更新測試

    你想繼續探討哪個方面？

常見改進機會

高耦合

  • 模組之間依賴過多
  • 雙向依賴
  • 循環依賴

過大模組

  • 超過建議行數（1000-2000 行）
  • 職責過多
  • 複雜度過高

低可維護性

  • 測試覆蓋率低
  • 程式碼重複
  • 缺乏文件

低效能

  • 冗餘查詢
  • 過大的記憶體使用
  • 未優化的演算法

輸出檔案

檔案會自動建立到以下位置：

docs/
└── architecture/
    ├── 2026-08-02-report.html
    └── 2026-08-02-user-service-analysis.md

HTML 報告包含：

  • 架構圖（視覺化）
  • 改進項目列表
  • 影響分析
  • 建議方案

何時不應該使用

  • 小專案：程式碼庫很小，不需要掃描
  • 新專案：架構還在演進中
  • 穩定模組：已經充分測試和優化