analyze-repo

/analyze-repo v3.0

Enterprise-Grade Project Deep Analysis — Layered Visualization × How-It-Works Narrative × Actionable Recommendations

v3.0 New Features

Feature	Description
🎯 Three-Layer Analysis Architecture	Executive (5 minutes) → Architecture Story (30 minutes) → Deep Dive (on demand)
🎬 How It Works	Added a "How the Project Works" narrative section for quickly understanding the core flow
📊 Visual-First	Each layer begins with a diagram, with text as supporting explanation
🔗 Evidence Chain	All findings include `file:line` code references
🛠️ Actionable Recommendations	Each recommendation includes: problematic code → fix example → verification steps

Core Value

Input	Output
GitHub URL or local path	Three-layer professional analysis report — visual dashboard + how-it-works narrative + actionable recommendations

Use Cases：

🏢 Technical Lead/CTO — Layer 1 quick decision-making + Layer 2 architecture assessment
👨‍💻 Developers — Layer 2 understanding how it works + Layer 3 getting-started guide
💰 Investors/Due Diligence — Layer 1 risk summary + Layer 2 technical depth
🔍 Code Review — Layer 3 file-by-file analysis + actionable fix recommendations

Three-Layer Report Architecture

┌─────────────────────────────────────────────────────────────────┐
│  📊 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 證據鏈                                 │
│  • 可執行建議：問題碼 → 修復範例 → 驗證步驟                       │
│  • 技術債務修復清單（含優先級 + 工時估算）                        │
│  • 完整檔案結構與關鍵入口點                                      │
└─────────────────────────────────────────────────────────────────┘

How to Use

# 基本分析（預設輸出完整三層報告）
/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

Analysis Framework

You are a senior software architecture consultant with expertise in arc42, C4 Model, and SOLID/DDD.

Phase 1: Data Collection and Context Building

1.1 Source Determination

https://github.com/ → GitHub API + source code analysis
Local path → direct file system access

1.2 Key File Scan (Priority Order)

Category	File	Analysis Purpose
Package Management	`package.json`, `requirements.txt`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`	Dependency analysis, version checks
Containerization	`Dockerfile`, `docker-compose.yml`, `k8s/`	Deployment architecture
Documentation	`README.md`, `CLAUDE.md`, `docs/`, `ARCHITECTURE.md`	Project intent
Configuration	`tsconfig.json`, `next.config.*`, `.env.example`, `config/`	Technical decisions
CI/CD	`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`	Automation maturity
Testing	`tests/`, `__tests__/`, `spec/`, `_test.go`, `.spec.ts`	Test coverage
Entry Points	`main.`, `index.`, `app.*`, `src/`	Code structure
Security	`.env`, `secrets/`, `credentials`, `.pem`, `*.key`	Sensitive information check

1.3 Project Metadata Collection

Lines of code (by language)
Commit history (activity level, contributor distribution)
Issue/PR statistics (if GitHub)
License type

Phase 2: How the Project Works (How It Works) 🆕

Core Innovation: Enable readers to understand "what this project actually does and how" within 5 minutes

2.1 Core Flow Narrative

Questions that must be answered:

What is the input? — What the user/system triggers
What is the process? — How the core logic works
What is the output? — What final result is produced

Format：

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

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

2.2 Main Use Case Sequence Diagram

Identify the 2-3 most important use cases, and generate for each scenario:

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 Key Code Entry Points

Each flow must be annotated with specific file locations:

Stage	File Location	Function/Class	Description
Entry	`src/main.ts:15`	`bootstrap()`	Application Startup
Routing	`src/routes/index.ts:42`	`router.get()`	Request Dispatch
Logic	`src/services/core.ts:128`	`processRequest()`	Core Processing
Data	`src/models/data.ts:23`	`DataModel`	Data Structures

2.4 Core Algorithm/Logic Description

If the project has unique algorithms or logic, describe them in the following format:

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

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

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

Phase 3: Architecture Analysis (C4 Model Four Levels)

Level 1: System Context

Identify System Boundaries
External Users/Roles
External System Integrations
🆕 Additional Notes: Explain the meaning of the diagram in 2-3 sentences

Level 2: Container

Applications
Data Storage
Message Queues
Inter-Container Communication Protocols
🆕 Reasons for Technology Selection: Why this technology was chosen

Level 3: Component

Main Modules/Packages
Key Classes/Functions
Module Responsibility Division
🆕 Code Location: File path for each component

Level 4: Code

Core Algorithms
Design Pattern Usage
Key Data Structures
🆕 Code Snippets: Show key implementations

Phase 3: Quality Assessment (8 Dimensions)

Assess using a 1-100 point scale:

Dimension	Assessment Criteria	Weight
Maintainability	Code complexity, naming conventions, modularity, Maintainability Index	15%
Testability	Test coverage, test quality, Mock/Stub usage	12%
Scalability	Architectural flexibility, horizontal/vertical scaling capability, design patterns	12%
Security	Dependency vulnerabilities, sensitive information exposure, OWASP Top 10	15%
Documentation Completeness	README, API documentation, architecture documentation, comment quality	10%
Architecture Health	SOLID compliance, separation of concerns, clear layering	15%
Dependency Health	Number of dependencies, degree of outdated versions, circular dependencies	11%
Developer Experience	Onboarding difficulty, development tool configuration, error message quality	10%

Overall Health Score = Weighted Average

Phase 4: Technical Debt Analysis

4.1 Debt Classification (SQALE Model)

Category	Detection Indicators
Reliability Debt	Unhandled exceptions, null pointer risks, resource leaks
Security Debt	Known vulnerabilities, hardcoded secrets, SQL injection risks
Maintainability Debt	Duplicate code, overly long functions, excessively deep nesting
Performance debt	N+1 queries, no caching strategy, synchronous blocking
Testing debt	Low coverage, no integration tests, fragile tests

4.2 Debt Quantification

Repair time estimate(person-days)
Priority ranking(Impact × Effort matrix)
Debt trend(if historical data is available)

Phase 5: Dependency Analysis

5.1 Dependency Graph

Internal module dependencies
External package dependencies
Circular dependency detection
Fan-in/fan-out analysis（Afferent/Efferent Coupling）

5.2 Dependency Health Check

Check item	Risk level
Known CVE vulnerabilities	🔴 Critical
Major version lag (>2 versions)	🟠 High
Unmaintained packages (>2 years without updates)	🟠 High
Minor version lag	🟡 Medium
License compliance risk	🟡 Medium

Phase 6: Security Assessment

6.1 Static Scan Summary

Dependency vulnerabilities (npm audit / pip-audit / cargo-audit equivalent analysis)
Sensitive information exposure (API Keys, passwords, Tokens)
Insecure code patterns

6.2 OWASP Top 10 Checklist

Risk	Check item
A01 Broken Access Control	Authorization checks, route protection
A02 Cryptographic Failures	Encryption algorithms, key management
A03 Injection	Input validation, parameterized queries
A07 Authentication	Authentication mechanisms, Session management
A09 Logging & Monitoring	Logging, exception tracking

Phase 7: Competitor and Value Analysis

7.1 Unique Value Proposition (UVP)

Core problem solved
Differentiating features
Target users

7.2 Irreplaceability Assessment (5-point scale)

Dimension	Assessment
Technical uniqueness	Core algorithms, patents, unique implementation
Depth of ecosystem integration	Degree of integration with other systems
Migration cost	Cost of switching to an alternative
Learning curve	Difficulty for the team to get up to speed
Community activity	Maintainers, contributors, Issue responses

7.3 Competitor Comparison Matrix

Identify 2-3 main competitors/alternatives and perform a feature comparison:

Comparison dimensions that must be included：

Dimension	Description
Core functionality	Main problem solved
Technical architecture	Differences in technology choices
Extensibility	Whether plugins/extensions are supported
Learning curve	Difficulty to get started
Community activity	Maintenance status, Issue responses
Licensing method	Open source/commercial/hybrid

Example format：

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

7.4 Applicable Scenario Analysis 🆕

Use a pie chart to show the proportion of the most suitable usage scenarios:

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

Also provide a recommendation matrix:

Scenario	Recommendation	Explanation
Scenario A	✅ Strongly recommended	{Why it is suitable}
Scenario B	✅ Recommended	{Why it is suitable}
Scenario C	⚠️ Possibly too heavy	{Why it may not be suitable}
Scenario D	❌ Not applicable	{Why it is not suitable}

Phase 7.5: Market Future Value Analysis

7.5.1 Technology Trend Alignment

Evaluate the degree of fit between the project and current/future technology trends:

Trend Area	Assessment Item
AI/ML integration capability	Whether there are AI integration points, LLM-friendly APIs, vector database support
Cloud-native maturity	Containerization, K8s support, Serverless adaptability
Edge computing readiness	Lightweight potential, offline capability, low-latency design
Web3/decentralization	Blockchain integration potential, decentralized architecture possibilities
Sustainability/green computing	Resource efficiency, energy consumption optimization potential

7.5.2 Market Positioning Analysis

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 Growth Potential Indicators

Indicator	Assessment Method
TAM/SAM/SOM estimation	Total addressable market, serviceable available market, serviceable obtainable market
Growth momentum	GitHub Stars trend, npm download volume, community activity growth rate
Network effect potential	The characteristic that the more users there are, the higher the value
Platformization potential	Whether it can develop into an ecosystem platform
Business model flexibility	Diverse monetization paths such as open source/SaaS/enterprise edition

7.5.4 Risk and Opportunity Matrix (SWOT Extension)

Category	Internal	External
Positive	Strengths	Opportunities
Negative	Weaknesses	Threats

7.5.5 Investment/Adoption Recommendation

Based on the above analysis, provide a clear recommendation:

🟢 Strongly recommended — Advanced technology, good market prospects, controllable risks
🟡 Consider cautiously — Valuable but with specific risks or limitations
🔴 Not recommended — Outdated technology, shrinking market, or excessively high risk

7.5.6 Version Evolution Analysis 🆕

If the project has a CHANGELOG or Git history, analyze the version evolution:

Gantt timeline visualization：

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

Key version milestone table：

Version	Date	Key Features	Impact
v1.0	YYYY-MM-DD	Initial release	Establish foundation
v2.0	YYYY-MM-DD	{Major feature}	{Change brought about}
v3.0	YYYY-MM-DD	{Major Features}	{Changes Introduced}

Evolution Trend Analysis：

Development Pace: {Active/Stable/Slow}
Versioning Strategy: {Semantic Versioning/Date Versioning/Other}
Backward Compatibility: {Good/Needs Attention/Frequently Broken}

Phase 8: Strategy Recommendation Generation

8.1 Priority Matrix

Use the Impact × Effort matrix to classify all findings:

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 Actionable Recommendation Framework 🆕

Core Principle: Each recommendation must be immediately actionable without additional research

Each recommendation must include the following structure:

Field	Description	Required
ID	Unique identifier (e.g., REC-001)	✅
Category	Architecture / Security / Performance / Quality / Documentation / DevOps	✅
Title	Concise description (< 10 characters)	✅
Importance	⭐⭐⭐ Core/Essential / ⭐⭐ Important/Recommended / ⭐ Optional/Enhancement	✅
Priority	🔴 Critical / 🟠 High / 🟡 Medium / 🟢 Low	✅
Problem Location	🆕 `file:line` Specific code location	✅
Problematic Code	🆕 Show the actual problematic code snippet	✅
Fix Example	🆕 Show the fixed code example	✅
Verification Steps	🆕 How to verify the fix succeeded (command or test)	✅
Success Metrics	Measurable acceptance criteria	✅

Recommendation Format Example：

### 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 注入風險

✅ Fix Example

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

🧪 Verification Steps

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

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

✓ Success Metrics

All SQL queries use parameterization
npm audit No Critical warnings


#### 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 Recommendation Priority Rules

Security Critical → Must be handled immediately
Affects production environment stability → High priority
Quick Wins (high impact, easy fix) → Execute first
Technical Debt → Sort by accumulated risk
Enhancements → Sort by business value

8.4 Recommendation Category Visualization

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 Diagram Generation

The following diagrams must be generated:

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 Module Dependency Diagram

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

9.4 Technology Stack Overview

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

Output Structure (Three-Layer Architecture)

Generate a complete Markdown report (see 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（附錄）
    - 完整目錄結構
    - 關鍵檔案清單與說明
    - 術語表
    - 分析方法說明

Execution Guidelines

✅ Must Follow

Complete Reading — Ensure sufficient files for accurate analysis
Objective Assessment — Score based on actual quality, avoid excessive optimism or pessimism
Specific Quantification — Provide numbers rather than vague descriptions whenever possible
Correct Diagrams — Ensure Mermaid syntax is correct and renderable
Actionable Recommendations — Each recommendation must be specific and executable

❌ Things to Avoid

Unfounded speculation
Excessive technical jargon (adjust according to perspective)
Vague comments (e.g., "pretty good", "needs improvement")
Missing key risks

Reference Resources

arc42 Template — Software Architecture Documentation Standard
C4 Model — Architecture Visualization Methods
SQALE Method — Technical Debt Assessment
OWASP Top 10 — Web Security Risks

Related Skills

/evolve — Autonomously accomplish complex goals
/commit — Submit code changes
/code-review — In-depth code review

ARGUMENTS: $ARGUMENTS