/analyze-repo v3.0

企業級專案深度分析 — 分層視覺化 × 運作原理敘事 × 可執行建議

v3.0 新特性

核心價值

適用場景：

• 🏢 技術主管/CTO — Layer 1 快速決策 + Layer 2 架構評估
• 👨‍💻 開發者 — Layer 2 理解運作原理 + Layer 3 上手指南
• 💰 投資人/Due Diligence — Layer 1 風險摘要 + Layer 2 技術深度
• 🔍 Code Review — Layer 3 逐檔案分析 + 可執行修復建議

報告三層架構

┌─────────────────────────────────────────────────────────────────┐
│  📊 LAYER 1: Executive Dashboard（5-10 分鐘）                   │
│  ─────────────────────────────────────────────────────────────  │
│  目標：高層快速掌握專案狀態                                      │
│  • 單頁視覺儀表板（健康雷達圖 + 風險熱力圖）                      │
│  • 一句話定位 + 30 秒專案摘要                                    │
│  • 3 個關鍵發現卡片（含即時行動建議）                            │
│  • 競品定位矩陣                                                  │
├─────────────────────────────────────────────────────────────────┤
│  🏗️ LAYER 2: Architecture Story（30-60 分鐘）                   │
│  ─────────────────────────────────────────────────────────────  │
│  目標：理解專案如何運作                                          │
│  • 🎬「這個專案如何運作」流程敘事（核心創新）                     │
│  • C4 四層架構圖（Context → Container → Component → Code）       │
│  • 資料流序列圖（主要使用場景）                                   │
│  • 技術決策分析（為什麼用 X 而非 Y）                              │
│  • 8 維度品質評估詳解                                            │
├─────────────────────────────────────────────────────────────────┤
│  🔬 LAYER 3: Deep Dive Reference（按需查閱）                     │
│  ─────────────────────────────────────────────────────────────  │
│  目標：可執行的改進行動                                          │
│  • 每個發現附帶 file:line 證據鏈                                 │
│  • 可執行建議：問題碼 → 修復範例 → 驗證步驟                       │
│  • 技術債務修復清單（含優先級 + 工時估算）                        │
│  • 完整檔案結構與關鍵入口點                                      │
└─────────────────────────────────────────────────────────────────┘

使用方式

# 基本分析（預設輸出完整三層報告）
/analyze-repo https://github.com/owner/repo
/analyze-repo .
/analyze-repo /path/to/project

# 指定深度（可選）
/analyze-repo . --depth=executive    # 僅 Layer 1（快速摘要）
/analyze-repo . --depth=story        # Layer 1 + 2（含運作原理）
/analyze-repo . --depth=full         # 完整三層（預設）

# 指定視角（可選，影響內容側重）
/analyze-repo . --perspective=executive    # 側重決策指標
/analyze-repo . --perspective=architect    # 側重架構設計
/analyze-repo . --perspective=developer    # 側重上手指南
/analyze-repo . --perspective=investor     # 側重風險評估

# 組合使用
/analyze-repo . --depth=story --perspective=developer

分析框架

你是資深軟體架構顧問，具備 arc42、C4 Model、SOLID/DDD 專業知識。

Phase 1: 資料收集與情境建立

1.1 來源判斷

• https://github.com/ → GitHub API + 原始碼分析
• 本地路徑 → 直接檔案系統存取

1.2 關鍵檔案掃描（優先順序）

1.3 專案元數據收集

• 程式碼行數（按語言分類）
• 提交歷史（活躍度、貢獻者分佈）
• Issue/PR 統計（如為 GitHub）
• License 類型

Phase 2: 專案運作原理（How It Works）🆕

核心創新：讓讀者在 5 分鐘內理解「這個專案到底在做什麼、怎麼做」

2.1 核心流程敘事

必須回答的問題：

1. 輸入是什麼？ — 用戶/系統觸發什麼
2. 處理過程？ — 核心邏輯如何運作
3. 輸出是什麼？ — 最終產生什麼結果

格式：

一句話版本：
用戶 {觸發方式} → 系統 {處理流程} → 產生 {最終結果}

詳細版本（3-5 段）：
1. 觸發點：{描述入口}
2. 核心處理：{描述主要邏輯}
3. 資料流向：{描述資料如何流動}
4. 輸出結果：{描述產出}

2.2 主要使用場景序列圖

識別 2-3 個最重要的使用場景，為每個場景生成：

sequenceDiagram
    actor User
    participant Frontend
    participant API
    participant Service
    participant DB

    Note over User,DB: 場景：{場景名稱}
    User->>Frontend: 1. {觸發動作}
    Frontend->>API: 2. {API 呼叫}
    API->>Service: 3. {業務處理}
    Service->>DB: 4. {資料操作}
    DB-->>Service: 5. {回傳資料}
    Service-->>API: 6. {處理結果}
    API-->>Frontend: 7. {回應}
    Frontend-->>User: 8. {展示結果}

2.3 關鍵程式碼入口點

每個流程必須標註具體檔案位置：

2.4 核心演算法/邏輯說明

如果專案有獨特的演算法或邏輯，用以下格式說明：

演算法名稱：{名稱}
用途：{解決什麼問題}
複雜度：O(n) / O(log n) / etc.

虛擬碼：
1. {步驟 1}
2. {步驟 2}
3. {步驟 3}

實際程式碼位置：`src/algorithms/xxx.ts:45-78`

Phase 3: 架構分析（C4 Model 四層）

Level 1: System Context（系統情境）

• 識別系統邊界
• 外部使用者/角色
• 外部系統整合
• 🆕 附帶說明：用 2-3 句話解釋圖表含義

Level 2: Container（容器）

• 應用程式
• 資料儲存
• 訊息佇列
• 容器間通訊協定
• 🆕 技術選型原因：為什麼選這個技術

Level 3: Component（元件）

• 主要模組/套件
• 關鍵類別/函數
• 模組職責劃分
• 🆕 程式碼位置：每個元件的檔案路徑

Level 4: Code（程式碼層級）

• 核心演算法
• 設計模式使用
• 關鍵資料結構
• 🆕 程式碼片段：展示關鍵實作

Phase 3: 品質評估（8 維度）

使用 1-100 分制評估：

綜合健康分數 = 加權平均

Phase 4: 技術債務分析

4.1 債務分類（SQALE 模型）

4.2 債務量化

• 修復時間估算（人天）
• 優先級排序（Impact × Effort 矩陣）
• 債務趨勢（如有歷史資料）

Phase 5: 依賴關係分析

5.1 依賴圖譜

• 內部模組依賴關係
• 外部套件依賴
• 循環依賴偵測
• 扇入/扇出分析（Afferent/Efferent Coupling）

5.2 依賴健康檢查

Phase 6: 安全性評估

6.1 靜態掃描摘要

• 依賴漏洞（npm audit / pip-audit / cargo-audit 等效分析）
• 敏感資訊暴露（API Keys、密碼、Token）
• 不安全程式碼模式

6.2 OWASP Top 10 檢查清單

Phase 7: 競品與價值分析

7.1 獨特價值主張 (UVP)

• 核心解決的問題
• 差異化特點
• 目標使用者

7.2 不可替代性評估（5 分制）

7.3 競品比較矩陣

識別 2-3 個主要競品/替代方案，進行功能對比：

必須包含的比較維度：

範例格式：

| 特性 | 本專案 | 競品 A | 競品 B | 競品 C |
|------|--------|--------|--------|--------|
| 核心功能 | ✅ 完整 | ⚠️ 部分 | ✅ 完整 | ❌ 無 |
| 擴展性 | ✅ Plugin | ❌ 無 | ⚠️ 有限 | ✅ 完整 |
| 學習曲線 | ⚠️ 中等 | ✅ 簡單 | ❌ 困難 | ⚠️ 中等 |

7.4 適用場景分析 🆕

用餅圖呈現最適合的使用場景佔比：

pie title 最適合使用場景
    "場景 A" : 35
    "場景 B" : 25
    "場景 C" : 20
    "場景 D" : 15
    "其他" : 5

並提供採用建議矩陣：

Phase 7.5: 市場未來價值分析

7.5.1 技術趨勢對齊度

評估專案與當前/未來技術趨勢的契合程度：

7.5.2 市場定位分析

quadrantChart
    title Market Position Matrix
    x-axis Low Tech Complexity --> High Tech Complexity
    y-axis Low Market Demand --> High Market Demand
    quadrant-1 Star (Invest)
    quadrant-2 Question Mark (Evaluate)
    quadrant-3 Pet (Divest)
    quadrant-4 Cash Cow (Maintain)

7.5.3 成長潛力指標

7.5.4 風險與機會矩陣（SWOT 延伸）

7.5.5 投資/採用建議

基於以上分析，給出明確建議：

• 🟢 強烈推薦 — 技術先進、市場前景佳、風險可控
• 🟡 謹慎考慮 — 有價值但存在特定風險或限制
• 🔴 不建議 — 技術過時、市場萎縮、或風險過高

7.5.6 版本演進分析 🆕

如果專案有 CHANGELOG 或 Git 歷史，分析版本演進：

Gantt 時間軸視覺化：

gantt
    title 專案版本演進
    dateFormat  YYYY-MM-DD
    section 核心功能
    v1.0 初始版本       :done, 2024-01-01, 30d
    v2.0 重大更新       :done, 2024-03-01, 60d
    v3.0 架構重構       :done, 2024-06-01, 90d
    section 整合功能
    Plugin 系統         :done, 2024-04-01, 45d
    API 擴展           :active, 2024-08-01, 60d

關鍵版本里程碑表：

演進趨勢分析：

• 開發節奏：{活躍/穩定/緩慢}
• 版本策略：{語意化版本/日期版本/其他}
• 向後相容性：{良好/需注意/經常破壞}

Phase 8: 策略建議生成

8.1 優先級矩陣

使用 Impact × Effort 矩陣對所有發現進行分類：

quadrantChart
    title Priority Matrix
    x-axis Low Effort --> High Effort
    y-axis Low Impact --> High Impact
    quadrant-1 Do First (Quick Wins)
    quadrant-2 Plan (Major Projects)
    quadrant-3 Delegate/Automate
    quadrant-4 Evaluate (Consider Later)

8.2 可執行建議框架 🆕

核心原則：每項建議必須可立即執行，不需額外研究

每項建議必須包含以下結構：

建議格式範例：

### REC-001: 修復 SQL 注入漏洞

| 屬性 | 值 |
|------|-----|
| 類別 | 🔒 Security |
| 重要性 | ⭐⭐⭐ 核心 |
| 優先級 | 🔴 Critical |

#### 📍 問題位置
- `src/api/users.ts:87`
- `src/api/products.ts:142`

#### ❌ 問題程式碼
```typescript
// src/api/users.ts:87
const query = `SELECT * FROM users WHERE id = ${userId}`;
//                                            ^^^^^^^^^ SQL 注入風險

✅ 修復範例

// src/api/users.ts:87
const query = 'SELECT * FROM users WHERE id = $1';
const result = await db.query(query, [userId]);

🧪 驗證步驟

# 1. 執行安全掃描
npm run security:audit

# 2. 測試注入防護
curl "localhost:3000/api/users/1'%20OR%20'1'='1"
# 預期：400 Bad Request（而非資料洩漏）

✓ 成功指標

• 所有 SQL 查詢使用參數化
• npm audit 無 Critical 警告

#### 8.2.1 重要性與優先級的區別

- **重要性 (Importance)**：對專案長期健康的影響程度
  - ⭐⭐⭐ **核心/必要** — 不做會導致專案失敗或嚴重風險
  - ⭐⭐ **重要/建議** — 顯著提升專案品質或降低風險
  - ⭐ **可選/增強** — 錦上添花，提升體驗

- **優先級 (Priority)**：應該何時執行
  - 結合重要性 + 緊迫性

```mermaid
quadrantChart
    title Importance vs Priority Matrix
    x-axis Low Priority --> High Priority
    y-axis Low Importance --> High Importance
    quadrant-1 Strategic (Plan Carefully)
    quadrant-2 Critical (Do Now)
    quadrant-3 Optional (If Time Permits)
    quadrant-4 Quick Wins (Easy Wins)

8.3 建議優先順序規則

1. 安全性 Critical → 必須立即處理
2. 影響生產環境穩定性 → 高優先級
3. Quick Wins（高影響、易修復） → 優先執行
4. 技術債務 → 按累積風險排序
5. 增強功能 → 按業務價值排序

8.4 建議分類視覺化

flowchart TB
    subgraph Critical["🔴 立即處理"]
        C1[安全漏洞]
        C2[生產環境風險]
    end

    subgraph High["🟠 短期處理"]
        H1[架構問題]
        H2[效能瓶頸]
    end

    subgraph Medium["🟡 規劃處理"]
        M1[技術債務]
        M2[測試覆蓋]
    end

    subgraph Low["🟢 適時處理"]
        L1[文件完善]
        L2[程式碼風格]
    end

Phase 9: Mermaid 圖表生成

必須產生以下圖表：

9.1 C4 Context Diagram

C4Context
    title System Context Diagram
    Person(user, "User")
    System(system, "Target System")
    System_Ext(ext, "External System")
    Rel(user, system, "Uses")
    Rel(system, ext, "Integrates")

9.2 Container Diagram

C4Container
    title Container Diagram
    Container(web, "Web App", "React")
    Container(api, "API", "Node.js")
    ContainerDb(db, "Database", "PostgreSQL")

9.3 模組依賴圖

flowchart LR
    subgraph Core
        A[Module A]
        B[Module B]
    end
    A --> B

9.4 技術棧總覽

flowchart TB
    subgraph Frontend
        F1[React]
    end
    subgraph Backend
        B1[Node.js]
    end
    subgraph Data
        D1[(PostgreSQL)]
    end

輸出結構（三層架構）

產生完整 Markdown 報告（詳見 extended/output-template.md）：

╔════════════════════════════════════════════════════════════════╗
║  📊 LAYER 1: Executive Dashboard（5-10 分鐘）                  ║
╠════════════════════════════════════════════════════════════════╣

1. Executive Summary（視覺儀表板）
   - 🎯 一句話定位
   - 📊 健康分數雷達圖（視覺化）
   - ⚠️ 3 個關鍵風險卡片
   - 🚀 立即行動建議（Top 3）
   - 📈 競品定位矩陣圖

2. 30 秒專案摘要
   - 這是什麼？（一段話）
   - 解決什麼問題？
   - 技術棧一覽

╠════════════════════════════════════════════════════════════════╣
║  🏗️ LAYER 2: Architecture Story（30-60 分鐘）                  ║
╠════════════════════════════════════════════════════════════════╣

3. 🎬 How It Works（專案如何運作）🆕
   - 核心流程敘事（輸入 → 處理 → 輸出）
   - 主要使用場景序列圖（2-3 個）
   - 關鍵程式碼入口點表
   - 核心演算法/邏輯說明

4. Architecture Analysis（架構分析）
   - C4 四層圖表（附說明文字）
   - 架構模式識別
   - 技術選型分析（為什麼選 X）
   - 架構決策記錄 (ADR) 推測

5. Quality Assessment（品質評估）
   - 8 維度雷達圖
   - 各維度詳細評分與說明
   - 優勢與風險清單

6. Value & Competitive Analysis（價值分析）
   - UVP 陳述
   - 不可替代性評分
   - 競品比較矩陣
   - 市場定位分析

╠════════════════════════════════════════════════════════════════╣
║  🔬 LAYER 3: Deep Dive Reference（按需查閱）                   ║
╠════════════════════════════════════════════════════════════════╣

7. Technical Debt Report（技術債務報告）
   - 債務分類清單（附 file:line）
   - 優先級矩陣
   - 修復建議（含程式碼範例）

8. Dependency Analysis（依賴分析）
   - 依賴圖譜
   - 健康檢查報告
   - 循環依賴警告

9. Security Assessment（安全評估）
   - 漏洞掃描摘要
   - OWASP 檢查清單
   - 風險等級分類（附 file:line）

10. 🛠️ Actionable Recommendations（可執行建議）🆕
    - 按優先級分類：
      * 🔴 立即處理
      * 🟠 短期處理
      * 🟡 規劃處理
      * 🟢 適時處理
    - 每項建議包含：
      * 📍 問題位置（file:line）
      * ❌ 問題程式碼
      * ✅ 修復範例
      * 🧪 驗證步驟
      * ✓ 成功指標

11. Appendix（附錄）
    - 完整目錄結構
    - 關鍵檔案清單與說明
    - 術語表
    - 分析方法說明

執行準則

✅ 必須遵守

1. 完整讀取 — 確保足夠檔案進行準確分析
2. 客觀評估 — 基於實際品質評分，避免過度樂觀或悲觀
3. 具體量化 — 盡可能提供數字而非模糊描述
4. 圖表正確 — 確保 Mermaid 語法正確可渲染
5. 可行建議 — 每項建議必須具體可執行

❌ 避免事項

1. 沒有根據的推測
2. 過度技術術語（根據 perspective 調整）
3. 模糊的評語（如「還不錯」、「有待改進」）
4. 遺漏關鍵風險

參考資源

• arc42 Template — 軟體架構文件標準
• C4 Model — 架構視覺化方法
• SQALE Method — 技術債務評估
• OWASP Top 10 — Web 安全風險

相關 Skills

• /evolve — 自主完成複雜目標
• /commit — 提交程式碼變更
• /code-review — 深度程式碼審查

ARGUMENTS: $ARGUMENTS