使用多個專門代理配合基於置信度的評分系統,分析 Legacy Java Spring Boot 專案並產生高品質教學文件

version
1.4.0
GitHub stars
29

Install

/plugin install legacy-analyzer@claude-plugin-marketplace-zh-tw

Run it inside Claude Code after adding the marketplace with /plugin marketplace add DennisLiuCk/claude-plugin-marketplace.

Contents

Discovered from source

Commands 3

Legacy Java Domain Flow Analyzer

專注於調用鏈追蹤與流程圖生成的高效領域分析工具。

使用方式:

/legacy-analyzer:analyze-java-domain-flow 商品建立
/legacy-analyzer:analyze-java-domain-flow 訂單取消
/legacy-analyzer:analyze-java-domain-flow 用戶登入

與 analyze-java-domain 的差異:

比較項目analyze-java-domainanalyze-java-domain-flow
輸出檔案6 個 Markdown 檔案 (~850行)單一檔案 (~300行)
執行時間4-6 分鐘2-3 分鐘
核心內容完整領域文件調用鏈 + 流程圖
資料模型詳細 DTO/Entity 說明僅列出涉及類別
業務規則完整規則文件不包含

搜尋範圍

只搜尋:.java、.xml(MyBatis Mapper) 排除:pom.xml、.yml、.properties


要執行此操作,請精確遵循以下步驟:

階段 1: 入口點發現(Haiku,~30秒)

  1. 解析使用者輸入,產生搜尋策略:

    {
      "domain": "商品建立",
      "keywords": {
        "chinese": ["商品", "產品", "建立", "新增"],
        "english": ["Product", "Item", "Create", "Add", "Save"],
        "patterns": ["create.*Product", "add.*Product", "Product.*Controller"]
      }
    }
    
  2. 使用 Haiku 代理快速定位入口點:

    搜尋策略(必須限制檔案類型):

    Grep: pattern="@(Post|Put|Get|Delete)Mapping.*{keyword}" glob="*.java"
    Grep: pattern="class.*{keyword}.*(Controller|Service)" glob="*.java"
    

    輸出入口點 JSON:

    {
      "entry_points": [
        {
          "file": "ProductController.java",
          "method": "createProduct",
          "http": "POST /api/products",
          "line": 67
        }
      ],
      "related_classes": ["ProductController", "ProductService", "ProductRepository"]
    }
    
  3. 如果找不到入口點,終止並建議:

    找不到與「{關鍵字}」相關的程式碼。
    建議:使用英文關鍵字如 "Product" 或 "Order"
    

階段 2: 調用鏈追蹤(Sonnet,~1-2分鐘)

  1. 對每個入口點(最多 3 個),啟動 Sonnet 代理並行追蹤。

    追蹤規則:

    • 從 Controller → Service → Repository → MyBatis XML
    • 最大深度:5 層
    • 只追蹤專案內程式碼(遇到框架類別標記為「框架內建」停止)

    追蹤步驟:

    a. 讀取 Controller 方法,找出調用的 Service b. 讀取 Service 實現類別,找出調用的 Repository/其他 Service c. 讀取 Repository,識別 JPA 方法或 MyBatis Mapper d. 如果是 MyBatis,讀取對應的 XML Mapper 檔案

    輸出調用鏈 JSON:

    {
      "chain_id": "chain-1",
      "entry": "POST /api/products → ProductController.createProduct",
      "nodes": [
        {
          "level": 0,
          "layer": "Controller",
          "class": "ProductController",
          "method": "createProduct(ProductDTO)",
          "file": "src/.../ProductController.java:67-85",
          "calls": ["productService.create"]
        },
        {
          "level": 1,
          "layer": "Service",
          "class": "ProductServiceImpl",
          "method": "create(ProductDTO)",
          "file": "src/.../ProductServiceImpl.java:45-78",
          "annotations": ["@Transactional"],
          "logic": "檢查名稱重複 → 轉換 DTO → 保存",
          "calls": ["productRepo.existsByName", "productRepo.save"]
        },
        {
          "level": 2,
          "layer": "Repository",
          "class": "ProductRepository",
          "method": "save(Product)",
          "file": "src/.../ProductRepository.java:12",
          "type": "JPA 內建方法"
        }
      ],
      "classes_involved": ["ProductController", "ProductServiceImpl", "ProductRepository", "Product", "ProductDTO"]
    }
    
  2. 收集所有調用鏈結果


階段 3: 流程驗證與評分(Haiku,~20秒)

  1. 對每條調用鏈啟動 Haiku 代理進行驗證評分:

    驗證維度:

    • 路徑完整性 (40%):調用鏈是否從入口到資料層完整
    • 證據準確性 (40%):檔案路徑和行號是否正確
    • 邏輯清晰度 (20%):流程描述是否清楚

    輸出評分 JSON:

    {
      "chain_id": "chain-1",
      "scores": {
        "completeness": 95,
        "accuracy": 90,
        "clarity": 85
      },
      "total": 91,
      "status": "verified"
    }
    

    狀態判定:

    • total >= 80:verified (已驗證)
    • total >= 60:partial (部分驗證)
    • total < 60:unverified (未驗證,標記警告)

階段 4: 流程圖與文件生成(Sonnet,~1分鐘)

  1. 啟動 Sonnet 代理生成單一 Markdown 文件。

    文件結構(目標 ~300 行):

    # {領域名稱} 調用鏈分析
    
    > 自動生成於 {timestamp} | 驗證狀態: {N} 條已驗證
    
    ## 快速概覽
    
    | 項目 | 數值 |
    |------|------|
    | 入口點 | {N} 個 |
    | 調用鏈 | {M} 條 |
    | 涉及類別 | {K} 個 |
    | 平均深度 | {D} 層 |
    
    ## 入口點總覽
    
    | HTTP 方法 | 路徑 | Controller.方法 | 驗證狀態 |
    |-----------|------|-----------------|----------|
    | POST | /api/products | ProductController.createProduct | verified |
    
    ---
    
    ## 調用鏈 1: {簡短描述}
    
    **入口**: `POST /api/products` → `ProductController.createProduct`
    **狀態**: verified (91分)
    
    ### 流程圖
    
    ```mermaid
    sequenceDiagram
        participant C as Controller
        participant S as Service
        participant R as Repository
        participant DB as Database
    
        C->>S: productService.create(dto)
        S->>S: 檢查名稱重複
        S->>R: productRepo.existsByName(name)
        R->>DB: SELECT EXISTS
        DB-->>R: boolean
        R-->>S: false
        S->>R: productRepo.save(product)
        R->>DB: INSERT
        DB-->>R: Product
        R-->>S: Product
        S-->>C: ProductDTO
    

    調用層級

    層級類別.方法檔案位置說明
    0ProductController.createProductProductController.java:67接收請求
    1ProductServiceImpl.createProductServiceImpl.java:45業務邏輯
    2ProductRepository.saveProductRepository.java:12資料存取

    關鍵邏輯 (ProductServiceImpl.java:50-55)

    if (productRepo.existsByName(dto.getName())) {
        throw new ProductExistsException();
    }
    Product product = mapper.toEntity(dto);
    return productRepo.save(product);
    

    整體架構圖

    flowchart TD
        subgraph Controller Layer
            A[ProductController]
        end
        subgraph Service Layer
            B[ProductServiceImpl]
        end
        subgraph Repository Layer
            C[ProductRepository]
        end
        subgraph Database
            D[(products)]
        end
    
        A -->|createProduct| B
        B -->|existsByName| C
        B -->|save| C
        C --> D
    

    涉及類別清單

    類別類型檔案位置
    ProductControllerControllersrc/.../ProductController.java
    ProductServiceImplServicesrc/.../ProductServiceImpl.java
    ProductRepositoryRepositorysrc/.../ProductRepository.java
    ProductEntitysrc/.../Product.java
    ProductDTODTOsrc/.../ProductDTO.java

    驗證摘要

    調用鏈完整性準確性清晰度總分狀態
    chain-1: 建立商品95908591verified
    
    **文件撰寫規則**:
    - 使用繁體中文
    - 每條調用鏈必須有 **Mermaid sequenceDiagram**
    - 文件末尾必須有 **整體架構 flowchart**
    - 程式碼片段限制 5-10 行
    - 所有檔案引用必須包含行號
    - **禁止**:改善建議、效能優化、測試策略
    
    
  2. 將文件寫入:.legacy-analysis/flow-{keyword}-{timestamp}/DOMAIN-FLOW.md


完成

  1. 顯示完成摘要:

    ╔═══════════════════════════════════════════════════════════╗
    ║     Domain Flow Analyzer - 分析完成                        ║
    ╚═══════════════════════════════════════════════════════════╝
    
    🎯 分析領域: {領域關鍵字}
    
    📁 輸出位置: .legacy-analysis/flow-{keyword}-{timestamp}/DOMAIN-FLOW.md
    
    📊 分析結果:
      - 入口點: {N} 個
      - 調用鏈: {M} 條 (已驗證: {V} 條)
      - 涉及類別: {K} 個
      - 平均驗證分數: {score}
    
    📈 調用鏈概覽:
      1. POST /api/products → ProductController.createProduct [91分]
      2. ...
    
    🔗 快速導覽:
      - 整體架構圖: DOMAIN-FLOW.md#整體架構圖
      - 調用鏈詳解: DOMAIN-FLOW.md#調用鏈-1-{描述}
    
    💡 特色:
      - 單一檔案輸出(約 300 行)
      - 包含 Mermaid 序列圖與架構圖
      - 所有調用鏈經過驗證評分
    

執行時間估算

階段時間模型
入口點發現~30秒Haiku
調用鏈追蹤~1-2分鐘Sonnet (並行)
流程驗證~20秒Haiku (並行)
文件生成~1分鐘Sonnet
總計~2-3分鐘

與 analyze-java-domain 的配合使用

場景 1: 快速了解流程
  → 使用 analyze-java-domain-flow(2-3分鐘)
  → 獲得調用鏈圖表

場景 2: 深度了解領域
  → 先用 analyze-java-domain-flow 掌握流程
  → 再用 analyze-java-domain 獲得完整文件

重要注意事項

  • 核心輸出:調用鏈 + Mermaid 流程圖(不包含資料模型、業務規則詳解)
  • 單一檔案:所有內容整合到一個 Markdown 檔案
  • 驗證機制:每條調用鏈都有驗證評分,確保準確性
  • 效率優先:比 analyze-java-domain 快約 50%

Legacy Java Domain Analyzer

針對使用者指定的領域/功能關鍵字,深度分析 Java Spring Boot 專案中的相關邏輯與完整調用鏈。

使用方式:

/legacy-analyzer:analyze-java-domain 請分析商品建立的流程
/legacy-analyzer:analyze-java-domain 分析訂單取消邏輯
/legacy-analyzer:analyze-java-domain 整理用戶註冊流程

與 analyze-java 的差異:

  • analyze-java:掃描全專案,生成完整文件(7-9 分鐘)
  • analyze-java-domain:定向搜尋特定領域,深度追蹤調用鏈(3-5 分鐘)

搜尋範圍限制

只搜尋以下檔案類型:

  • .java - Java 原始碼(Controller, Service, Repository, Entity 等)
  • .xml - MyBatis Mapper 檔案(SQL 查詢邏輯)

排除的檔案:

  • pom.xml - Maven 依賴定義
  • build.gradle - Gradle 依賴定義
  • .yml / .yaml / .properties - 配置檔(與領域邏輯無關)

Grep 搜尋時必須使用 glob 參數限制範圍:

# 正確方式
Grep: pattern="關鍵字" glob="*.java"
Grep: pattern="關鍵字" glob="*.xml" (排除 pom.xml 的結果)

# 錯誤方式(不要這樣做)
Grep: pattern="關鍵字" (會搜尋所有檔案)

要執行此操作,請精確遵循以下步驟:

準備工作

  1. 解析使用者輸入,識別:

    • 領域關鍵字(Domain Keywords):如「商品建立」、「訂單取消」、「用戶註冊」
    • 搜尋關鍵字(Search Keywords):從領域關鍵字推導出可能的:
      • 中文詞彙:商品、產品、建立、新增、創建
      • 英文詞彙:Product, Item, Goods, Create, Add, Insert
      • 方法名:createProduct, addProduct, insertProduct, saveProduct
      • 類別名:ProductController, ProductService, ProductRepository
      • API 路徑:/product, /products, /api/product

    輸出搜尋策略 JSON:

    {
      "user_query": "商品建立的流程",
      "domain": "商品建立",
      "search_keywords": {
        "chinese": ["商品", "產品", "建立", "新增", "創建"],
        "english": ["Product", "Item", "Goods", "Create", "Add", "Save"],
        "method_patterns": ["create.*Product", "add.*Product", "save.*Product", "insert.*Product"],
        "class_patterns": ["Product.*Controller", "Product.*Service", "Product.*Repository"],
        "api_patterns": ["/product", "/products", "POST.*product"]
      }
    }
    
  2. 使用 TodoWrite 建立待辦事項清單

  3. 創建工作目錄:.legacy-analysis/domain-{keyword}-{timestamp}/

    • keyword:領域關鍵字的英文簡寫(如 product-create)

階段 1: 快速資格檢查與入口點發現

  1. 使用 Haiku 代理快速檢查專案並找出入口點:

    代理任務:

    • 確認是 Spring Boot 專案(檢查 pom.xml 或 build.gradle)
    • 使用 Grep 搜尋所有搜尋關鍵字,統計匹配數量
    • 識別最可能的入口點(Entry Points):
      • Controller 類別中包含關鍵字的方法
      • API 端點(@RequestMapping, @PostMapping, @GetMapping)

    搜尋策略(必須限制檔案類型):

    # 搜尋 Controller 中的相關端點(只搜尋 .java)
    Grep: pattern="@(Post|Put|Get|Delete)Mapping.*product" glob="*.java"
    Grep: pattern="@RequestMapping.*product" glob="*.java"
    
    # 搜尋 Service 中的相關方法(只搜尋 .java)
    Grep: pattern="(create|add|save|insert).*Product" glob="*.java"
    
    # 搜尋類別定義(只搜尋 .java)
    Grep: pattern="class.*Product.*(Controller|Service|Repository)" glob="*.java"
    
    # 搜尋 MyBatis Mapper 中的相關 SQL(只搜尋 .xml,排除 pom.xml)
    Grep: pattern="<(select|insert|update|delete).*product" glob="*.xml"
    # 注意:過濾結果時排除 pom.xml
    

    輸出入口點 JSON:

    {
      "project_valid": true,
      "total_matches": 45,
      "entry_points": [
        {
          "type": "controller",
          "file": "src/main/java/com/example/controller/ProductController.java",
          "method": "createProduct",
          "http_method": "POST",
          "path": "/api/products",
          "line": 67
        },
        {
          "type": "controller",
          "file": "src/main/java/com/example/controller/ProductController.java",
          "method": "addProduct",
          "http_method": "POST",
          "path": "/api/products/add",
          "line": 112
        }
      ],
      "related_classes": [
        "ProductController",
        "ProductService",
        "ProductServiceImpl",
        "ProductRepository",
        "Product",
        "ProductDTO"
      ]
    }
    

    如果匹配數量 = 0,輸出建議並終止:

    ❌ 找不到與「{領域關鍵字}」相關的程式碼
    
    建議嘗試:
    1. 使用不同的關鍵字(如「商品」改為「Product」或「Item」)
    2. 確認專案中是否有此功能
    3. 使用 /legacy-analyzer:analyze-java 進行全專案掃描
    
  2. 將入口點資訊寫入:.legacy-analysis/domain-{keyword}-{timestamp}/01-entry-points.json


階段 2: 深度調用鏈追蹤

  1. 對於每個入口點,啟動一個 Sonnet 代理進行深度追蹤。

    如果入口點 <= 3 個:全部並行啟動 如果入口點 > 3 個:只追蹤最重要的 3 個(根據 HTTP 方法優先級:POST > PUT > DELETE > GET)

    每個追蹤代理的任務:

    從入口點開始,遞歸追蹤完整的調用鏈:

    Controller.method()
      ↓ 調用
    Service.method()
      ↓ 調用
    Repository.method()
      ↓ 操作
    Entity
    

    追蹤步驟:

    a. 讀取入口 Controller 方法:

    • 使用 Read 讀取 Controller 檔案(.java)
    • 找到目標方法
    • 識別方法內調用的 Service

    b. 追蹤 Service 層:

    • 讀取 Service 介面和實現類別(.java)
    • 分析業務邏輯
    • 識別調用的 Repository 和其他 Service

    c. 追蹤 Repository 層:

    • 讀取 Repository 介面(.java)
    • 識別自定義查詢方法
    • 如果使用 MyBatis:搜尋對應的 Mapper XML 檔案
      # 根據 Repository/Mapper 介面名稱搜尋對應的 XML
      Glob: pattern="**/ProductMapper.xml"
      # 或搜尋 XML 中的 namespace
      Grep: pattern="namespace.*ProductMapper" glob="*.xml"
      

    d. 追蹤 MyBatis Mapper XML(如果存在):

    • 讀取 Mapper XML 檔案
    • 分析 SQL 語句(select, insert, update, delete)
    • 識別動態 SQL(if, choose, foreach)
    • 記錄 resultMap 和參數映射

    e. 分析相關 Entity:

    • 讀取涉及的 Entity 類別(.java)
    • 分析欄位和關聯關係

    f. 識別橫切關注點:

    • @Transactional 事務邊界
    • 異常處理
    • 驗證邏輯(@Valid)
    • 日誌記錄

    輸出調用鏈 JSON:

    {
      "entry_point": {
        "file": "ProductController.java",
        "method": "createProduct",
        "line": 67
      },
      "call_chain": [
        {
          "level": 0,
          "type": "controller",
          "class": "ProductController",
          "method": "createProduct(ProductDTO)",
          "file": "src/.../ProductController.java",
          "lines": "67-85",
          "annotations": ["@PostMapping", "@Valid"],
          "description": "接收商品建立請求,驗證輸入",
          "calls": ["productService.createProduct"]
        },
        {
          "level": 1,
          "type": "service",
          "class": "ProductServiceImpl",
          "method": "createProduct(ProductDTO)",
          "file": "src/.../ProductServiceImpl.java",
          "lines": "45-78",
          "annotations": ["@Transactional"],
          "description": "核心業務邏輯:檢查商品名稱重複、設定預設值、保存商品",
          "calls": ["productRepository.existsByName", "productRepository.save"],
          "business_rules": [
            "商品名稱不可重複",
            "價格必須大於 0",
            "庫存預設為 0"
          ]
        },
        {
          "level": 2,
          "type": "repository",
          "class": "ProductRepository",
          "method": "save(Product)",
          "file": "src/.../ProductRepository.java",
          "lines": "12",
          "description": "JPA 內建方法,保存 Entity 到資料庫",
          "calls": []
        },
        {
          "level": 2,
          "type": "mybatis-mapper",
          "class": "ProductMapper",
          "method": "insertProduct",
          "file": "src/main/resources/mapper/ProductMapper.xml",
          "lines": "25-35",
          "sql_type": "insert",
          "description": "MyBatis INSERT 語句,將商品資料插入 products 表",
          "sql_snippet": "INSERT INTO products (name, price, stock) VALUES (#{name}, #{price}, #{stock})",
          "dynamic_sql": false,
          "calls": []
        }
      ],
      "mybatis_mappers": [
        {
          "interface": "ProductMapper.java",
          "xml": "src/main/resources/mapper/ProductMapper.xml",
          "statements": [
            {"id": "insertProduct", "type": "insert", "line": 25},
            {"id": "selectByName", "type": "select", "line": 40}
          ]
        }
      ],
      "entities_involved": [
        {
          "class": "Product",
          "file": "src/.../entity/Product.java",
          "table": "products",
          "key_fields": ["id", "name", "price", "stock", "categoryId"]
        },
        {
          "class": "ProductDTO",
          "file": "src/.../dto/ProductDTO.java",
          "purpose": "請求/響應資料傳輸物件"
        }
      ],
      "cross_cutting": {
        "transaction": "@Transactional on ProductServiceImpl.createProduct",
        "validation": "@Valid on request body",
        "exception_handling": "throws ProductAlreadyExistsException"
      }
    }
    

    重要規則:

    • ❗ 每個方法引用必須有實際檔案路徑和行號
    • ❗ 使用 Read 驗證每個檔案內容
    • ❗ 如果追蹤到第三方庫(如 JpaRepository),標記為「框架內建」不再深入
    • ❗ 最大追蹤深度:5 層(防止無限遞歸)
    • ❗ 只返回 JSON,不執行 Write 操作
    • ❗ 只讀取 .java 和 .xml 檔案(排除 pom.xml)
    • ❗ MyBatis Mapper XML 通常位於 src/main/resources/mapper/ 或類似目錄
  2. 等待所有追蹤代理完成,收集結果

  3. 合併所有調用鏈並寫入:.legacy-analysis/domain-{keyword}-{timestamp}/02-call-chains.json


階段 3: 發現提取與評分

  1. 從調用鏈中提取發現(Findings):

    將調用鏈轉換為結構化發現,每個發現代表一個重要的知識點:

    發現類型:

    • entry-point:API 入口點
    • business-logic:業務邏輯
    • data-operation:資料操作
    • validation:驗證規則
    • transaction:事務管理
    • exception:異常處理
    • entity:資料模型
    • mybatis-sql:MyBatis SQL 語句(來自 .xml mapper)
    • mybatis-dynamic:MyBatis 動態 SQL(if, choose, foreach)

    發現格式(與 analyze-java 相容):

    {
      "finding_id": "DOMAIN-001",
      "type": "entry-point",
      "title": "商品建立 API 端點",
      "description": "POST /api/products 端點接收商品建立請求,使用 @Valid 驗證輸入的 ProductDTO",
      "evidence": [
        {
          "file": "src/main/java/com/example/controller/ProductController.java",
          "lines": "67-85",
          "snippet": "@PostMapping\npublic ResponseEntity<Product> createProduct(@Valid @RequestBody ProductDTO dto)"
        }
      ],
      "importance": "high",
      "call_chain_ref": "chain-1"
    }
    
  2. 對每個發現啟動 Haiku 代理進行評分(與 analyze-java 相同的評分機制):

    評分維度:

    • 證據強度 (40%):檔案路徑驗證、行號準確性
    • 重要性 (30%):對理解領域邏輯的重要程度
    • 完整性 (15%):描述是否清晰完整
    • 準確性 (15%):技術描述是否正確

    輸出格式:

    {
      "finding_id": "DOMAIN-001",
      "scores": {
        "evidence": 95,
        "importance": 90,
        "completeness": 85,
        "accuracy": 95
      },
      "total_score": 92.25,
      "confidence_level": "very_high"
    }
    
  3. ⚠️ MANDATORY: 等待所有評分完成,不可跳過

  4. 將評分結果寫入:.legacy-analysis/domain-{keyword}-{timestamp}/03-scores.json


階段 4: 過濾與整理

  1. 應用過濾規則(與 analyze-java 相同):

    • 保留 total_score >= 75
    • evidence < 60 強制丟棄
    • accuracy < 50 強制丟棄
    • importance >= 90 且 evidence >= 70 例外保留
  2. 按調用鏈順序組織發現:

    • 將發現按其在調用鏈中的位置排序
    • 標記發現之間的關聯關係
  3. 寫入結構化資料:.legacy-analysis/domain-{keyword}-{timestamp}/04-structured.json


階段 5: 領域文件生成(分檔策略)

⚠️ 重要:為避免單一文件過大導致 token 限制問題,採用分檔策略

文件撰寫原則(核心守則)

文件目的:幫助工程師/開發者/新人理解現有專案的 domain know-how 與 project design。

必須刪除的內容類型:

  • ❌ 改善建議、優化建議(如「建議實作快取」、「未來可以加入 A/B Testing」)
  • ❌ 效能優化策略(如「平行處理」、「批次查詢」建議)
  • ❌ 測試代碼範例(測試應該在測試檔案本身查看)
  • ❌ 假設性/範例性程式碼(只保留實際程式碼引用)
  • ❌ 「應該」「建議」「優化」「未來」字眼的段落
  • ❌ 監控與告警建議(如「應該實作的監控指標」)

必須保留的內容類型:

  • ✅ 現有程式碼的結構與邏輯說明
  • ✅ 實際的業務規則(從程式碼中提取)
  • ✅ 資料模型與關聯關係
  • ✅ 調用鏈與流程圖
  • ✅ 錯誤訊息對照表(現有的)
  • ✅ 檔案位置速查

程式碼引用原則:

  • 只保留 5-15 行的關鍵邏輯片段
  • 必須標註檔案路徑和行號(如 ProductService.java:45-60)
  • 完整代碼應引導讀者查看原始檔案
  • 禁止假設性或簡化範例程式碼

避免重複原則:

  • API 端點列表只在 00-INDEX.md
  • DTO 欄位說明只在 03-data-model.md
  • 業務規則只在 04-business-rules.md
  • 錯誤碼對照只在 04-business-rules.md
  • 常數定義只在 03-data-model.md

  1. 依章節分檔生成,每個章節由獨立的 Sonnet 代理生成:

    輸入(所有代理共用):

    • 結構化發現 JSON(04-structured.json)
    • 調用鏈 JSON(02-call-chains.json)
    • 入口點 JSON(01-entry-points.json)
    • 使用者原始查詢

    文件 1: 索引頁 (00-INDEX.md) - 目標 ~50 行

    由主 session 直接生成,內容:

    • 領域名稱和簡介(2-3 句話)
    • 文件清單與連結
    • API 端點總覽表格(唯一出現位置)
    • 快速統計
    # {領域名稱} 領域分析
    
    > 本文件幫助你理解 {領域名稱} 的現有實作,不包含改善建議。
    
    ## API 端點總覽
    
    | HTTP 方法 | 路徑 | Controller 方法 | 用途 |
    |-----------|------|----------------|------|
    | POST | /api/products | createProduct | 建立商品 |
    | GET | /api/products/{id} | getProduct | 查詢商品 |
    
    ## 文件索引
    
    | 文件 | 說明 | 目標讀者 |
    |------|------|----------|
    | [01-概述](./01-overview.md) | 領域概念、架構全貌 | 新人、PM |
    | [02-調用鏈](./02-call-chains.md) | 程式碼導覽、呼叫路徑 | 開發者 |
    | [03-資料模型](./03-data-model.md) | DTO/Entity/Enum 參考 | 開發者 |
    | [04-業務規則](./04-business-rules.md) | 業務邏輯、錯誤碼 | 開發者、QA |
    | [05-檔案索引](./05-guide.md) | 檔案位置速查 | 開發者 |
    
    ## 快速統計
    
    - 入口點: {N} 個
    - 調用鏈: {M} 條
    - 涉及類別: {K} 個
    

    文件 2: 概述 (01-overview.md) - 目標 ~150 行

    代理任務:生成領域概述和架構圖

    保留內容:

    • 簡介(3-5 句話)
    • 核心功能列表(bullet points)
    • 技術特色(使用了什麼框架/模式)
    • 系統架構圖(單一 Mermaid flowchart)
    • 核心類別說明表格(類別名、檔案路徑、職責)

    刪除內容:

    • ❌ 效能考量/優化策略
    • ❌ 未來擴展方向
    • ❌ 測試策略
    • ❌ 詳細 DTO 設計(移到 03-data-model.md)
    • ❌ API 端點列表(已在 00-INDEX.md)
    • ❌ 多個序列圖(只保留一個最重要的)

    Mermaid 圖表限制:

    • 只使用一個整體架構 flowchart
    • 只保留一個最重要 API 的序列圖
    • 序列圖不超過 15 行

    文件 3: 調用鏈詳解 (02-call-chains.md) - 目標 ~200 行

    代理任務:說明程式碼呼叫路徑

    保留內容:

    • 調用鏈概覽表格(入口點、涉及類別、主要功能)
    • 架構分層說明(Controller → Service → Repository)
    • 每條調用鏈的層級結構(精簡版):
      • 類別和方法名稱
      • 檔案路徑:行號
      • 3-5 句功能說明
      • 重要註解(@Transactional, @Valid)
    • 共用元件說明

    刪除內容:

    • ❌ 效能瓶頸分析
    • ❌ 優化策略建議
    • ❌ 冗長的程式碼區塊(每個不超過 10 行)
    • ❌ 重複的 Kutt API 整合說明(整合至此文件一次)

    程式碼片段限制:

    • 每個方法只保留關鍵 5-10 行
    • 必須標註 檔案名:行號
    • 以 // ... 完整實作請見原始檔案 結尾

    調用鏈呈現格式(精簡版):

    ### 調用鏈 1: 建立商品
    
    | 層級 | 類別.方法 | 檔案位置 | 說明 |
    |------|----------|----------|------|
    | 0 | ProductController.createProduct | ProductController.java:67 | 接收請求 |
    | 1 | ProductService.createProduct | ProductServiceImpl.java:45 | 業務邏輯 |
    | 2 | ProductRepository.save | ProductRepository.java:12 | 資料存取 |
    
    **關鍵邏輯** (`ProductServiceImpl.java:50-55`):
    ```java
    if (productRepository.existsByName(dto.getName())) {
        throw new ProductAlreadyExistsException();
    }
    return productRepository.save(product);
    // ... 完整實作請見原始檔案
    
    
    ---
    
    ### 文件 4: 資料模型 (03-data-model.md) - 目標 ~200 行
    
    **代理任務**:說明資料結構(唯一來源)
    
    **保留內容**:
    - DTO/Entity 關係圖(Mermaid erDiagram)
    - Entity 欄位說明表格(類別、欄位、型別、說明)
    - DTO 欄位說明表格
    - Enum 定義表格
    - 常數定義表格(唯一位置)
    - 資料流轉說明(簡短)
    
    **刪除內容**:
    - ❌ 效能考量
    - ❌ 測試資料範例
    - ❌ 假設性的表結構
    - ❌ 簡化範例 DTO 程式碼
    
    **表格格式範例**:
    ```markdown
    ## Entity: Product (`ProductEntity.java:15`)
    
    | 欄位 | 型別 | 對應資料表欄位 | 說明 |
    |------|------|---------------|------|
    | id | Long | product_id | 主鍵 |
    | name | String | product_name | 商品名稱 |
    

    文件 5: 業務規則與異常 (04-business-rules.md) - 目標 ~150 行

    代理任務:整理現有業務規則(唯一來源)

    保留內容:

    • 業務規則清單表格(規則、程式碼位置、說明)
    • 錯誤碼/錯誤訊息對照表(唯一位置)
    • 異常類別列表(類別名、觸發條件、HTTP 狀態碼)
    • 驗證邏輯摘要(@Valid 欄位、自定義驗證)

    刪除內容:

    • ❌ 測試覆蓋建議
    • ❌ 效能考量
    • ❌ 修改指南
    • ❌ 測試 SQL 範例

    表格格式範例:

    ## 業務規則
    
    | 規則 | 程式碼位置 | 說明 |
    |------|-----------|------|
    | 商品名稱不可重複 | ProductServiceImpl.java:48 | 建立前檢查 |
    | 價格必須大於 0 | ProductDTO.java:23 | @Min(1) 驗證 |
    
    ## 錯誤碼對照
    
    | 錯誤碼 | HTTP 狀態 | 訊息 | 觸發條件 |
    |--------|----------|------|----------|
    | PRODUCT_001 | 409 | 商品名稱已存在 | 名稱重複 |
    

    文件 6: 檔案索引 (05-guide.md) - 目標 ~100 行

    代理任務:提供檔案位置速查(最有價值的參考)

    保留內容:

    • 相關檔案清單(按類型分類)
      • Controllers
      • Services
      • Repositories
      • Entities
      • DTOs
      • Mappers (MyBatis XML)
      • 測試檔案位置(僅列出路徑,不詳述)
    • 常見問題列表(僅標題和 1 句說明,不詳述解法)

    刪除內容:

    • ❌ 如何修改此流程(改善建議)
    • ❌ 效能優化建議
    • ❌ 測試策略詳述
    • ❌ 部署與配置詳述
    • ❌ API 測試範例(curl/Postman)
    • ❌ 除錯技巧詳述

    檔案清單格式:

    ## 相關檔案
    
    ### Controllers
    - `src/main/java/.../ProductController.java` - 商品 API 入口
    
    ### Services
    - `src/main/java/.../ProductService.java` - 介面
    - `src/main/java/.../ProductServiceImpl.java` - 實作
    
    ### Tests
    - `src/test/java/.../ProductServiceTest.java`
    - `src/test/java/.../ProductControllerTest.java`
    
    ## 常見問題
    
    | 問題 | 相關檔案 |
    |------|----------|
    | 商品建立失敗 | ProductServiceImpl.java:48 |
    | 價格驗證錯誤 | ProductDTO.java:23 |
    

    撰寫風格(所有文件通用):

    • 使用繁體中文
    • 假設讀者不了解此專案
    • 優先使用表格呈現結構化資訊
    • 所有程式碼引用必須有 檔案名:行號
    • 每個文件開頭包含返回索引的連結
    • 每個資訊只出現在一個文件中(避免重複)
    • 禁止使用「建議」「應該」「優化」「未來」等字眼
  2. 並行生成文件:

    啟動 4 個 Sonnet 代理並行生成文件 2-5:

    • 代理 A: 生成 01-overview.md(目標 ~150 行)
    • 代理 B: 生成 02-call-chains.md(目標 ~200 行)
    • 代理 C: 生成 03-data-model.md(目標 ~200 行)
    • 代理 D: 生成 04-business-rules.md(~150 行)+ 05-guide.md(~100 行)

    主 session 同時生成 00-INDEX.md(目標 ~50 行)

    預期總行數:約 850 行(相比原本 4000+ 行減少約 80%)

  3. 將所有文件寫入:.legacy-analysis/domain-{keyword}-{timestamp}/docs/

    docs/
    ├── 00-INDEX.md           # 索引頁 (~50 行)
    ├── 01-overview.md        # 概述 (~150 行)
    ├── 02-call-chains.md     # 調用鏈 (~200 行)
    ├── 03-data-model.md      # 資料模型 (~200 行)
    ├── 04-business-rules.md  # 業務規則 (~150 行)
    └── 05-guide.md           # 檔案索引 (~100 行)
    

完成

  1. 顯示完成摘要:

    ╔═══════════════════════════════════════════════════════════╗
    ║     Legacy Domain Analyzer - 領域分析完成                   ║
    ╚═══════════════════════════════════════════════════════════╝
    
    🎯 分析領域: {領域關鍵字}
    
    📁 工作目錄: .legacy-analysis/domain-{keyword}-{timestamp}/
    
    📄 生成的文件:
      ├─ 01-entry-points.json      (入口點 {N} 個)
      ├─ 02-call-chains.json       (調用鏈 {M} 條)
      ├─ 03-scores.json            (評分結果)
      ├─ 04-structured.json        (結構化發現 {K} 個)
      └─ docs/                     (領域分析文件 - 精簡版) ⭐
          ├─ 00-INDEX.md           (~50 行) 索引與 API 總覽
          ├─ 01-overview.md        (~150 行) 概述與架構圖
          ├─ 02-call-chains.md     (~200 行) 調用鏈詳解
          ├─ 03-data-model.md      (~200 行) 資料模型
          ├─ 04-business-rules.md  (~150 行) 業務規則
          └─ 05-guide.md           (~100 行) 檔案索引
    
    📊 分析統計:
      - 總執行時間: {X} 分 {Y} 秒
      - 追蹤的調用鏈: {M} 條
      - 文件總行數: ~850 行(精簡版)
      - 平均置信度: {score}
    
    🔗 主要入口點:
      1. POST /api/products → ProductController.createProduct
      2. ...
    
    📖 閱讀指南:
      - 新人/PM: 從 00-INDEX.md → 01-overview.md
      - 開發者: 02-call-chains.md → 03-data-model.md
      - QA: 04-business-rules.md
    
    💡 文件特色:
      - 專注於「理解現有專案」,不含改善建議
      - 每個資訊只出現一次,無重複內容
      - 所有程式碼引用包含檔案路徑和行號
      - 總計約 850 行(相比完整版減少 80%)
    

重要注意事項

  • 並行執行:

    • 階段 2 的追蹤代理(最多 3 個)並行啟動
    • 階段 3 的評分代理全部並行啟動
    • 階段 5 的文件生成代理(4 個)並行啟動
  • 精簡文件策略:

    • 採用 6 個精簡文件(總計 ~850 行)
    • 每個文件有明確的目標行數限制
    • 禁止「建議」「應該」「優化」「未來」字眼
    • 每個資訊只出現在一個文件中(避免重複)
    • 程式碼片段限制 5-15 行,引導讀者看原始檔案
  • 與 analyze-java 的互補性:

    • 先用 analyze-java-domain 理解特定功能
    • 如需全局視角,再用 analyze-java
    • 兩者輸出格式相容,可以合併
  • 搜尋策略優化:

    • 使用多種關鍵字變體(中英文、駝峰、下劃線)
    • 使用正則表達式匹配方法名模式
    • 從 Controller 開始追蹤,確保找到完整流程
  • 深度優先 vs 廣度優先:

    • 此命令採用深度優先策略
    • 完整追蹤一條調用鏈後再追蹤下一條
    • 最大深度 5 層,避免過度追蹤
  • 時間估算:

    • 階段 1: 約 30 秒(Haiku 快速掃描)
    • 階段 2: 約 2-3 分鐘(Sonnet 深度追蹤,最多 3 條鏈)
    • 階段 3: 約 10-20 秒(Haiku 評分)
    • 階段 4: 約 10 秒(主 session 處理)
    • 階段 5: 約 1-2 分鐘(4 個 Sonnet 並行生成精簡文件)
    • 總計: 約 4-6 分鐘

Legacy Java Project Analyzer

為給定的 Java Spring Boot 專案生成詳細的分析文件,using multiple specialized agents with confidence-based scoring。

要執行此操作,請精確遵循以下步驟:

準備工作

  1. 首先使用 TodoWrite 建立待辦事項清單,包含所有階段

  2. 創建工作目錄:.legacy-analysis/session-{timestamp}/

階段 1: 資格預檢與快速掃描

  1. 使用 Haiku 代理檢查專案是否適合分析。代理應檢查:

    • 專案根目錄是否存在 pom.xml 或 build.gradle?
    • 是否包含 Spring Boot 依賴?(檢查 spring-boot-starter)
    • Java 檔案數量是否適中?(使用 Glob 統計 **/*.java,應 < 1000)

    如果不符合任一條件,說明原因並終止。

  2. 使用 Haiku 代理快速掃描專案結構。代理應:

    • 使用 Glob 找出所有 .java 檔案並統計數量
    • 使用 Grep 搜尋以下註解並統計數量:
      • @RestController 或 @Controller
      • @Service
      • @Repository
      • @Entity
    • 讀取 pom.xml 或 build.gradle 獲取:
      • Spring Boot 版本
      • 前 10 個主要依賴
    • 使用 Glob 列出主要 package(src/main/java 下的第一層目錄)

    返回專案摘要 JSON:

    {
      "projectType": "Spring Boot",
      "springBootVersion": "2.7.12",
      "buildTool": "Maven",
      "totalJavaFiles": 245,
      "componentCounts": {
        "controllers": 15,
        "services": 20,
        "repositories": 12,
        "entities": 10
      },
      "mainPackages": [
        "com.example.order.controller",
        "com.example.order.service",
        "com.example.order.repository"
      ],
      "keyDependencies": [
        "spring-boot-starter-web",
        "spring-boot-starter-data-jpa",
        "mysql-connector-java"
      ]
    }
    
  3. 將專案摘要寫入:.legacy-analysis/session-{timestamp}/01-project-scan.json

階段 2: 多視角並行分析

  1. 啟動 6 個並行 Sonnet 代理來獨立分析專案。

    所有代理的共同輸入:

    • 專案摘要 JSON(來自步驟 4)
    • 專案根目錄路徑

    所有代理的共同輸出格式(JSON):

    {
      "analyst": "代理名稱",
      "findings": [
        {
          "finding_id": "分類前綴-編號",
          "type": "發現類型",
          "title": "簡短標題",
          "description": "詳細描述(2-3 句話)",
          "evidence": [
            {
              "file": "檔案相對路徑",
              "lines": "起始行-結束行",
              "snippet": "關鍵程式碼片段(可選)"
            }
          ],
          "importance": "high/medium/low",
          "notes": "額外說明(可選)"
        }
      ],
      "total_findings": 數量
    }
    

    所有代理的重要規則:

    • ❗ 每個發現必須有實際的檔案路徑和行號作為證據
    • ❗ 使用 Read 工具驗證檔案內容,確保引用正確
    • ❗ 使用 Glob/Grep 輔助搜尋,不要猜測
    • ❗ 如果無法確認,不要包含該發現
    • ❗ 只返回 JSON,不執行 Write 操作
    • ❗ 專注於自己的分析領域,不要越界

代理 #1:架構分析代理

職責:分析專案的整體架構和分層設計

應分析:

  • Package 組織結構(使用 Glob 掃描目錄)
  • 分層架構識別:
    • Controller 層:處理 HTTP 請求
    • Service 層:業務邏輯
    • Repository 層:資料存取
    • Entity 層:資料模型
  • 識別架構模式(MVC、三層架構、DDD 等)
  • 層與層之間的依賴關係(通過讀取代表性類別)

應使用工具:

  • Glob: 掃描 package 結構
  • Grep: 搜尋 @RestController, @Service, @Repository, @Entity
  • Read: 讀取 2-3 個代表性類別(每層一個)

發現類型前綴:ARCH-

發現類型:architecture

預期發現數量:8-15 個


代理 #2:API 端點分析代理

職責:分析所有 REST API 端點和請求處理流程

應分析:

  • 所有 @RestController 或 @Controller 類別(使用 Grep 找出)
  • 主要 API 端點:
    • HTTP 方法(GET/POST/PUT/DELETE)
    • 路徑和路徑參數
    • 請求/響應格式
  • 主要業務流程:
    • Controller → Service → Repository 的調用鏈
    • 事務管理(@Transactional)
  • 認證授權機制(如果有 Spring Security)
  • 異常處理(@ExceptionHandler, @ControllerAdvice)

應使用工具:

  • Grep: 搜尋 @RestController, @RequestMapping, @GetMapping, @PostMapping
  • Read: 讀取所有 Controller 類別(或前 10 個如果太多)
  • Grep: 搜尋 @Transactional, @ExceptionHandler

發現類型前綴:API-

發現類型:endpoint

預期發現數量:15-25 個(視 Controller 數量)


代理 #3:資料流分析代理

職責:分析資料模型和資料流轉

應分析:

  • 所有 JPA Entity 類別(使用 Grep 找出 @Entity)
  • Entity 之間的關聯關係:
    • @OneToOne, @OneToMany, @ManyToOne, @ManyToMany
    • 關聯的方向和級聯設定
  • 資料流轉路徑:
    • DTO → Entity(轉換邏輯)
    • Entity → Database(Repository 操作)
  • Repository 介面和自定義查詢
  • 資料驗證邏輯(@Valid, @NotNull 等)

應使用工具:

  • Grep: 搜尋 @Entity, @OneToMany, @ManyToOne
  • Read: 讀取所有 Entity 類別
  • Grep: 搜尋 @Repository, extends JpaRepository
  • Read: 讀取主要 Repository 介面

發現類型前綴:DATA-

發現類型:entity 或 dataflow

預期發現數量:10-20 個


代理 #4:業務邏輯分析代理

職責:分析核心業務邏輯和 Service 層

應分析:

  • 所有 @Service 類別(使用 Grep 找出)
  • 主要業務方法:
    • 方法簽名和參數
    • 業務規則和驗證
    • 複雜的業務邏輯
  • Service 之間的調用關係(依賴注入)
  • 事務管理:
    • @Transactional 的使用
    • 事務邊界
  • 業務異常處理

應使用工具:

  • Grep: 搜尋 @Service, @Transactional
  • Read: 讀取所有 Service 類別(或主要的 5-10 個)
  • 分析依賴注入(@Autowired, 建構子注入)

發現類型前綴:BIZ-

發現類型:service 或 business-logic

預期發現數量:15-25 個


代理 #5:配置分析代理

職責:分析專案配置和第三方整合

應分析:

  • application.yml 或 application.properties:
    • 資料庫配置
    • Server 配置
    • 環境變數
  • Spring Boot 配置類別(@Configuration):
    • Bean 定義
    • 第三方服務整合
  • Spring Security 配置(如果有)
  • 依賴管理(pom.xml 或 build.gradle):
    • 主要依賴及版本
    • 第三方庫的用途

應使用工具:

  • Read: 讀取 application.yml/properties
  • Grep: 搜尋 @Configuration, @Bean
  • Read: 讀取配置類別
  • Read: 讀取 pom.xml 或 build.gradle

發現類型前綴:CONF-

發現類型:configuration 或 dependency

預期發現數量:8-15 個


代理 #6:模式識別代理

職責:識別設計模式和編碼最佳實踐

應分析:

  • 設計模式的應用:
    • Factory Pattern(工廠模式)
    • Strategy Pattern(策略模式)
    • Builder Pattern(建造者模式)
    • Singleton Pattern(單例模式)
  • Spring 特定模式:
    • Dependency Injection(依賴注入)
    • AOP(面向切面編程,如果有 @Aspect)
  • 異常處理模式:
    • 全域異常處理器(@ControllerAdvice)
    • 自定義異常類別
  • 日誌記錄實踐(Logger 使用)
  • DTO 模式的使用

應使用工具:

  • Grep: 搜尋常見模式關鍵字(Factory, Strategy, Builder, Singleton)
  • Read: 讀取包含模式的類別
  • Grep: 搜尋 @ControllerAdvice, @Aspect, @Pointcut
  • 分析代碼風格和命名慣例

發現類型前綴:PATTERN-

發現類型:pattern 或 practice

預期發現數量:5-15 個


  1. 等待所有 6 個代理完成,收集所有輸出

  2. 合併所有發現清單為一個 JSON 陣列

  3. 將合併的發現清單寫入:.legacy-analysis/session-{timestamp}/02-findings-raw.json

  4. 統計總發現數量並報告(例如:"收集到 102 個發現")

階段 3: 獨立置信度評分

⚠️⚠️⚠️ CRITICAL - THIS STAGE IS MANDATORY AND CANNOT BE SKIPPED ⚠️⚠️⚠️

為什麼這個階段是核心且不可跳過的:

  1. 這是整個插件的靈魂

    • 置信度評分系統是本插件與其他分析工具的根本差異
    • 沒有評分 = 沒有質量保證 = 無法區分真實發現與幻覺
    • 跳過此階段違反了插件的核心設計原則
  2. 防幻覺機制完全依賴此階段

    • 第二層防護:評分代理使用 Glob 驗證檔案存在
    • 第三層防護:閾值過濾(score >= 75, evidence >= 60)
    • 沒有評分 = 防幻覺機制失效 = 可能產生錯誤文件
  3. 成本和時間都非常合理

    • Haiku 模型速度極快(每個評分 < 1 秒)
    • 100 個評分代理並行執行只需 10-20 秒
    • Haiku 成本極低(相比 Sonnet 便宜 50-100 倍)
    • 即使 200 個發現,總時間也只增加 10-15 秒
  4. 不評分的嚴重後果

    • 最終文件會包含所有未驗證的發現(包括幻覺、錯誤、瑣碎內容)
    • 過濾率 0%(承諾是 40-60%)
    • 無法信任檔案路徑和行號
    • 用戶體驗極差,失去插件價值

明確的執行要求:

❌ 絕對禁止以下行為:

  • 以「發現數量太多」為理由跳過評分
  • 以「節省時間」為理由跳過評分
  • 以「成本考量」為理由跳過評分
  • 直接使用未評分的發現生成文件
  • 進入階段 4 而不先完成階段 3

✅ 你 MUST 執行以下操作:

  • 對 每一個發現 啟動一個獨立的 Haiku 評分代理
  • 等待 所有 評分代理完成
  • 將所有評分結果寫入 03-scores.json
  • 只有在 03-scores.json 存在後才能繼續下一階段
  1. REQUIRED: 對於步驟 8 中的 每一個發現,啟動一個並行 Haiku 代理進行評分。 DO NOT SKIP ANY FINDINGS, regardless of the total count.

    每個評分代理的輸入:

    • 單個發現 JSON(包含 finding_id, type, title, description, evidence, importance)
    • 專案摘要 JSON(作為上下文)

    評分任務:

    從四個維度對發現進行評分(0-100):

    a. 證據強度 (Evidence Strength) - 權重 40%

    評分標準:

    • 90-100 分:完美證據

      • 有精確的檔案路徑和行號
      • 使用 Read 工具驗證檔案存在且內容匹配
      • 代碼片段準確無誤
    • 70-89 分:良好證據

      • 有檔案路徑和行號
      • 使用 Glob 確認檔案存在
      • 描述與代碼基本匹配
    • 50-69 分:基本證據

      • 有檔案路徑但行號範圍過大(> 50 行)
      • 通過推理得出,未直接驗證
      • 可能需要額外確認
    • 30-49 分:弱證據

      • 只有檔案路徑,沒有行號
      • 基於間接證據(如依賴推測)
      • 不確定性較高
    • 0-29 分:無效證據

      • 沒有檔案路徑或檔案不存在
      • 明顯的猜測或假設
      • 幻覺(fabrication)

    評分方法:使用 Glob 驗證檔案路徑是否存在。如果時間允許,使用 Read 讀取檔案驗證行號範圍和內容。


    b. 重要性 (Importance) - 權重 30%

    評分標準:

    • 90-100 分:極其重要

      • 核心業務邏輯(如訂單處理、支付流程)
      • 主要架構決策(如分層設計、依賴管理)
      • 新手必須理解的概念
      • 影響整個系統的設計
    • 70-89 分:很重要

      • 重要的業務流程
      • 關鍵的設計模式應用
      • 常見的 CRUD 操作
      • 第三方服務整合
    • 50-69 分:中等重要

      • 輔助功能
      • 一般的配置項目
      • 可選的理解點
      • 工具方法
    • 30-49 分:次要

      • 邊緣功能
      • 細節實現
      • 進階理解點
    • 0-29 分:不重要

      • 瑣碎細節
      • 與業務無關的內容
      • 可以忽略的資訊

    c. 完整性 (Completeness) - 權重 15%

    評分標準:

    • 90-100 分:非常完整

      • 描述清晰易懂
      • 包含完整的流程或調用鏈
      • 有充足的上下文
      • 提供了代碼範例
    • 70-89 分:基本完整

      • 描述清晰
      • 主要流程完整
      • 上下文充足
    • 50-69 分:部分完整

      • 描述較簡略
      • 流程不完整或片段化
      • 缺少部分上下文
    • 30-49 分:不完整

      • 描述模糊
      • 只有流程片段
      • 上下文不足
    • 0-29 分:非常不完整

      • 描述不清
      • 沒有流程資訊
      • 完全缺乏上下文

    d. 準確性 (Accuracy) - 權重 15%

    評分標準:

    • 90-100 分:完全準確

      • 技術描述正確無誤
      • 沒有錯誤或幻覺
      • 可以直接使用
    • 70-89 分:基本準確

      • 主要描述正確
      • 有小的不精確(如版本差異)
      • 需要微調
    • 50-69 分:部分準確

      • 有明顯錯誤
      • 需要修正才能使用
      • 部分資訊可能誤導
    • 30-49 分:不準確

      • 多處錯誤
      • 包含幻覺或猜測
      • 不可信
    • 0-29 分:完全錯誤

      • 完全不正確
      • 大量幻覺
      • 必須丟棄

    計算最終分數:

    total_score = evidence * 0.4 + importance * 0.3 + completeness * 0.15 + accuracy * 0.15
    

    輸出格式(JSON):

    {
      "finding_id": "ARCH-001",
      "scores": {
        "evidence": 95,
        "importance": 85,
        "completeness": 90,
        "accuracy": 95
      },
      "total_score": 91.25,
      "confidence_level": "very_high",
      "reasoning": "發現有明確的檔案路徑證據(已用 Glob 驗證存在),描述準確且清晰,對理解三層架構非常重要,新手必須知道。",
      "verified_files": [
        "src/main/java/com/example/order/controller/OrderController.java (verified)"
      ],
      "issues": []
    }
    

    confidence_level 對應:

    • very_high: total_score >= 85
    • high: 75 <= total_score < 85
    • medium: 60 <= total_score < 75
    • low: 45 <= total_score < 60
    • very_low: total_score < 45
  2. REQUIRED: 等待 所有 評分代理完成,收集所有評分結果。 不要只收集部分結果,必須等待全部完成。

  3. REQUIRED: 將評分結果寫入:.legacy-analysis/session-{timestamp}/03-scores.json

  4. 統計評分分佈(例如:"58 個 >= 75, 44 個 < 75")

階段 4: 過濾與結構化整合

🔒 VALIDATION CHECKPOINT - 在繼續之前必須驗證 🔒

14.5. MANDATORY PRE-CHECK: 在執行任何過濾操作前,你 MUST 先驗證以下條件:

**檢查 1: 確認評分文件存在**
```
使用 Read 工具檢查文件是否存在:
.legacy-analysis/session-{timestamp}/03-scores.json
```

**如果文件不存在**,你 MUST:
- 立即停止執行
- 輸出錯誤訊息:
  ```
  ❌❌❌ 致命錯誤:階段 3 評分被跳過 ❌❌❌

  檢測到缺少文件:03-scores.json

  這表示階段 3(獨立置信度評分)沒有被執行。
  沒有評分數據,無法進行質量過濾,無法保證最終文件質量。

  請檢查階段 3 的執行日誌,或重新執行完整流程。

  插件設計要求:所有階段必須依序完成,不可跳過。
  ```
- **DO NOT PROCEED** 到步驟 15

**檢查 2: 驗證評分數量一致性**

使用 Read 工具讀取以下兩個文件:
- `02-findings-raw.json` (原始發現數量)
- `03-scores.json` (評分數量)

驗證:評分數量 == 原始發現數量

**如果數量不一致**,你 MUST:
- 輸出警告訊息:
  ```
  ⚠️ 警告:評分數量與發現數量不一致

  原始發現: {N} 個
  評分結果: {M} 個
  差異: {N-M} 個發現未被評分

  可能原因:部分評分代理失敗

  將繼續執行,但請注意未評分的發現將被自動過濾。
  ```
- 對於未評分的發現,自動賦予 total_score = 0(將被過濾)

**只有在通過所有檢查後**,才能繼續執行步驟 15。

15. REQUIRED: 過濾發現,應用以下規則:

**主要規則**:
- 保留 total_score >= 75 的發現

**額外規則**(強制):
- 如果 evidence < 60:強制丟棄(即使總分 >= 75)
  理由:沒有足夠證據,可能是幻覺

- 如果 accuracy < 50:強制丟棄(即使總分 >= 75)
  理由:準確性太低,可能誤導讀者

**例外規則**(保留):
- 如果 importance >= 90 且 evidence >= 70:保留(即使總分 < 75)
  理由:極其重要的發現,證據也足夠

統計並報告過濾結果(例如:"保留 58 個高質量發現,過濾掉 44 個低質量發現,過濾率 43.1%")

16. 將保留的發現按類別分組: - architecture: 架構發現 - endpoint: API 端點 - entity: 資料模型 - dataflow: 資料流轉 - service: 業務邏輯 - business-logic: 業務邏輯(同義詞) - configuration: 配置 - dependency: 依賴 - pattern: 設計模式 - practice: 編碼實踐

  1. 每個類別內按 total_score 降序排序(最高質量在前)

  2. 識別發現之間的關聯關係(可選但推薦):

    • 例如:API-001(創建訂單端點)→ BIZ-005(OrderService.createOrder)→ DATA-003(Order Entity)
    • 建立關聯圖以幫助理解完整流程
  3. 生成結構化資料 JSON:

    {
      "summary": {
        "total_findings_raw": 102,
        "total_findings_filtered": 58,
        "filter_rate": 0.431,
        "by_category": {
          "architecture": 8,
          "endpoint": 15,
          "entity": 7,
          "dataflow": 3,
          "service": 12,
          "configuration": 7,
          "pattern": 6
        },
        "average_score": 82.5
      },
      "findings_by_category": {
        "architecture": [ /* 發現陣列 */ ],
        "endpoint": [ /* 發現陣列 */ ],
        ...
      },
      "relationships": [
        {
          "from": "API-001",
          "to": ["BIZ-005", "DATA-003"],
          "type": "invokes"
        }
      ]
    }
    
  4. REQUIRED: 將結構化資料寫入:.legacy-analysis/session-{timestamp}/04-findings-structured.json

階段 5: 教學文件生成

🔒 FINAL VALIDATION CHECKPOINT - 文件生成前的最後檢查 🔒

20.5. MANDATORY FINAL CHECK: 在啟動文件生成代理前,你 MUST 驗證所有必需文件已就緒:

**檢查 1: 驗證所有階段的輸出文件存在**

使用 Read 工具確認以下文件全部存在:
- `01-project-scan.json` (階段 1 輸出)
- `02-findings-raw.json` (階段 2 輸出)
- `03-scores.json` (階段 3 輸出) ← **關鍵文件**
- `04-findings-structured.json` (階段 4 輸出)

**如果任何文件缺失**,你 MUST:
- 立即停止執行
- 輸出錯誤訊息:
  ```
  ❌❌❌ 致命錯誤:無法生成教學文件 ❌❌❌

  缺少必需的文件:{缺失的文件名}

  這表示前置階段沒有正確完成。
  無法在沒有完整數據的情況下生成教學文件。

  請重新執行完整的分析流程,確保所有階段依序完成。
  ```
- **DO NOT START** 文件生成代理

**檢查 2: 驗證結構化發現的質量**

使用 Read 工具讀取 `04-findings-structured.json`,確認:
- `summary.total_findings_filtered` > 0(至少有一些高質量發現)
- `summary.filter_rate` 在 0.2-0.8 之間(過濾率正常)

**如果過濾後發現數量 = 0**,你 MUST:
- 輸出警告訊息:
  ```
  ⚠️ 警告:沒有任何發現通過質量過濾

  原始發現: {N} 個
  通過過濾: 0 個

  可能原因:
  1. 分析代理的發現質量極低(證據不足)
  2. 評分標準過於嚴格
  3. 專案過於簡單,沒有足夠的內容可分析

  建議:
  - 檢查 02-findings-raw.json 和 03-scores.json
  - 考慮手動調整過濾閾值(從 75 降至 65)
  - 或手動補充文件內容
  ```
- 繼續生成文件,但文件內容會很少

**檢查 3: 禁止使用未評分的發現**

你 MUST 確認:
- 文件生成代理的輸入 **只能** 是 `04-findings-structured.json`
- **絕對禁止** 直接使用 `02-findings-raw.json`
- **絕對禁止** 添加任何未在結構化發現中的資訊

**只有在通過所有檢查後**,才能啟動文件生成代理。

21. REQUIRED: 使用 Sonnet 代理生成教學文件。

**輸入**:
- 結構化發現 JSON(來自步驟 20 的 `04-findings-structured.json`)← **唯一允許的輸入來源**
- 專案摘要 JSON(來自步驟 5 的 `01-project-scan.json`)

**任務**:

生成完整的 Markdown 教學文件,假設讀者是完全不了解此專案的新進工程師。

**文件結構**(必須包含):

### 1. 專案概述
- 專案基本資訊(名稱、類型、Spring Boot 版本、建構工具)
- 專案規模(檔案數量、元件統計)
- 專案結構(主要 package)
- 核心模組列表

### 2. 快速開始
- 如何運行專案(從 git clone 到 spring-boot:run)
- 重要端點列表(健康檢查、API 文件)
- 開發環境要求(JDK、Maven/Gradle、資料庫)

### 3. 架構說明
- 整體架構圖(使用 Mermaid flowchart)
- 分層設計說明(Controller/Service/Repository/Entity)
- Package 組織結構
- 架構優點

範例 Mermaid 圖:
```mermaid
graph TB
    Client[客戶端請求]
    Controller[Controller 層<br/>處理 HTTP 請求]
    Service[Service 層<br/>業務邏輯處理]
    Repository[Repository 層<br/>資料存取]
    DB[(MySQL 資料庫)]

    Client --> Controller
    Controller --> Service
    Service --> Repository
    Repository --> DB
```

### 4. API 端點清單

對於每個重要的 API 端點(從 endpoint 類別的發現):
- HTTP 方法和路徑
- 描述和用途
- 請求範例(JSON)
- 響應範例(JSON)
- 業務流程序列圖(使用 Mermaid sequenceDiagram)
- 關鍵程式碼片段(含檔案路徑連結)
- 重要提示(如事務管理、異常處理)

範例序列圖:
```mermaid
sequenceDiagram
    participant Client
    participant Controller
    participant Service
    participant Repository
    participant DB

    Client->>Controller: POST /api/orders
    Controller->>Service: createOrder(OrderDTO)
    Service->>Service: 驗證庫存
    Service->>Repository: save(Order)
    Repository->>DB: INSERT
    DB-->>Repository: 成功
    Repository-->>Service: Order Entity
    Service-->>Controller: OrderResponseDTO
    Controller-->>Client: 201 Created
```

### 5. 核心業務流程

選擇 2-3 個最重要的業務流程(基於 importance 分數):
- 流程整體說明
- 詳細步驟分解
- 完整序列圖
- 涉及的類別和方法列表(含檔案路徑連結)
- 程式碼片段和註解
- 新手提示

### 6. 資料模型

- Entity 關係圖(使用 Mermaid erDiagram)
- 對於每個主要 Entity:
  - 資料表名稱
  - 主要欄位說明
  - 關聯關係說明
  - JPA 註解解釋(@Entity, @Table, @OneToMany 等)
  - 程式碼範例

範例 ER 圖:
```mermaid
erDiagram
    Order ||--o{ OrderItem : contains
    Order {
        Long id PK
        Long customerId
        String status
        Timestamp createdAt
    }
    OrderItem {
        Long id PK
        Long orderId FK
        Long productId
        int quantity
        decimal price
    }

    Customer ||--o{ Order : places
    Customer {
        Long id PK
        String name
        String email
    }
```

### 7. 關鍵配置

- 資料庫配置(含 YAML/properties 範例)
- Spring Security 配置(如果有)
- 重要的 Bean 配置
- 環境變數說明

### 8. 設計模式與最佳實踐

對於每個識別出的設計模式:
- 模式名稱和類型
- 應用位置(檔案路徑)
- 程式碼範例
- 使用此模式的優點
- 相關的最佳實踐

### 9. 新手入門指南

- **我該從哪裡開始?**
  - 建議的學習順序(10 分鐘理解架構 → 30 分鐘追蹤一個流程 → ...)
  - 推薦先看哪些類別

- **常見任務指南**
  - 如何添加新的 API 端點
  - 如何修改業務邏輯
  - 如何添加新的 Entity

- **開發環境設置**
  - 所需工具清單
  - 資料庫設置步驟
  - 環境變數配置
  - 如何運行測試

- **推薦的學習資源**
  - Spring Boot 官方文件連結
  - Spring Data JPA 文件連結
  - 相關教學資源

### 10. 附錄

- **高質量發現清單**
  - 按類別列出所有發現(含 finding_id 和 score)

- **文件變更歷史**
  - 初始版本生成時間
  - 後續手動更新記錄區

- **檔案路徑索引**
  - 所有引用的檔案路徑清單(方便快速導航)

---

**撰寫風格要求**:

✅ **假設讀者是新手**
- 不假設任何先備知識
- 解釋所有技術術語(如 JPA、DTO、依賴注入)
- 提供充足的上下文

✅ **使用繁體中文**
- 自然流暢的中文
- 技術術語保留英文(如 Controller, Service, @Transactional)
- 適當加入英文原文(如「依賴注入 (Dependency Injection)」)

✅ **大量使用圖表**
- 每個複雜流程都應該有 Mermaid 圖
- 圖表類型:flowchart(架構圖)、sequenceDiagram(序列圖)、erDiagram(ER 圖)
- 圖表要清晰、標註完整

✅ **包含程式碼範例**
- 關鍵程式碼片段(使用 ```java 語法高亮)
- 適當的註解(特別是複雜邏輯)
- 檔案路徑和行號(格式:`src/.../OrderController.java:67-85`)

✅ **可點擊的連結**
- 所有檔案路徑都使用 Markdown 連結格式(如 `[OrderController.java](src/.../OrderController.java)`)
- 使用相對路徑

✅ **結構清晰**
- 使用 Markdown 標題階層(#, ##, ###)
- 使用清單和表格組織資訊
- 每個章節之間用 `---` 分隔

---

**重要規則**:

❗ **CRITICAL RULE: 只使用高質量發現**
- **MUST** 只能使用 total_score >= 75 的發現(來自 `04-findings-structured.json`)
- **MUST NOT** 添加任何未在發現清單中的資訊
- **MUST NOT** 直接使用 `02-findings-raw.json` 中的未評分發現
- 如果某個面向沒有足夠的發現,明確說明「此部分資訊不足,建議手動補充」

❗ **CRITICAL RULE: 所有引用必須可驗證**
- **MUST**: 每個程式碼範例都必須有檔案路徑
- **MUST**: 每個流程圖都必須基於實際的發現
- **MUST NOT**: 編造任何檔案路徑或類別名稱
- **MUST NOT**: 添加未經驗證的代碼片段

❗ **保持客觀**
- 如實描述專案現況
- 不過度美化或批評
- 基於事實陳述

❗ **Mermaid 語法正確**
- 確保所有 Mermaid 圖表語法正確
- 測試常見的 Mermaid 語法錯誤(如缺少引號、箭頭錯誤)

---

**輸出**:

返回完整的 Markdown 文件內容(純文本,不需要 JSON 包裝)

22. REQUIRED: 將生成的文件寫入:.legacy-analysis/session-{timestamp}/05-PROJECT-ANALYSIS.md

  1. (可選)生成統計報告並寫入:.legacy-analysis/session-{timestamp}/session-stats.json
    {
      "session_id": "session-20250125-143022",
      "start_time": "2025-01-25T14:30:22Z",
      "end_time": "2025-01-25T14:36:45Z",
      "duration_seconds": 383,
      "project_info": {
        "name": "Order Management System",
        "type": "Spring Boot",
        "total_java_files": 245
      },
      "analysis_stats": {
        "total_findings_raw": 102,
        "total_findings_filtered": 58,
        "filter_rate": 0.431,
        "average_score": 82.5,
        "by_category": { ... }
      },
      "agent_calls": {
        "qualification_check": 1,
        "quick_scan": 1,
        "analysis_agents": 6,
        "scoring_agents": 102,
        "documentation_generator": 1,
        "total": 111
      },
      "quality_metrics": {
        "file_path_verified_rate": 1.0,
        "average_evidence_score": 87.3,
        "average_importance_score": 78.5
      }
    }
    

完成

  1. 顯示完成摘要,包含:

    ╔═══════════════════════════════════════════════════════╗
    ║       Legacy Project Analyzer - 分析完成               ║
    ╚═══════════════════════════════════════════════════════╝
    
    ✅ 所有階段已完成
    
    📁 工作目錄: .legacy-analysis/session-{timestamp}/
    
    📄 生成的文件:
      ├─ 01-project-scan.json          (專案掃描摘要)
      ├─ 02-findings-raw.json          (原始發現 102 個)
      ├─ 03-scores.json                (評分結果)
      ├─ 04-findings-structured.json   (結構化發現 58 個)
      ├─ 05-PROJECT-ANALYSIS.md        (最終教學文件) ⭐
      └─ session-stats.json            (統計資訊)
    
    📊 分析統計:
      - 總執行時間: 6 分 23 秒
      - 代理調用: 111 次 (2 Haiku + 6 Sonnet + 102 Haiku + 1 Sonnet)
      - 發現總數: 102 個
      - 高質量發現: 58 個 (56.9%)
      - 檔案路徑驗證率: 100%
      - 平均置信度分數: 82.5
    
    🎯 下一步建議:
      1. 閱讀最終文件: 05-PROJECT-ANALYSIS.md
      2. 根據文件理解專案架構和核心流程
      3. 動手運行專案並對照文件調試
      4. 如需深入特定模組,可補充手動分析
    
    💡 提示:
      - 本文件由 AI 自動生成,基於 58 個高質量發現
      - 所有引用的檔案路徑都已驗證存在
      - 如發現任何錯誤或遺漏,歡迎手動補充
    
    祝學習順利! 🚀
    

重要注意事項

  • 使用 TodoWrite 追蹤進度:在步驟 1 建立待辦清單,並在完成每個階段時更新狀態

  • 並行執行代理(CRITICAL for performance):

    • 階段 2 的 6 個分析代理 MUST 並行啟動(在單個回應中使用多個 Task 工具)
    • 階段 3 的 N 個評分代理 MUST 並行啟動(全部一次性啟動)
    • DO NOT 等待單個代理完成才啟動下一個
    • DO NOT 序列執行(會導致總時間從 7 分鐘變成 30+ 分鐘)
  • 錯誤處理:

    • 如果某個分析代理失敗,記錄錯誤但繼續其他代理
    • 如果某個評分代理失敗,該發現使用預設低分(0)並標記
    • 如果文件生成失敗,嘗試重試一次
  • 檔案路徑格式:

    • 使用相對路徑(相對於專案根目錄)
    • 格式:src/main/java/com/example/order/controller/OrderController.java
    • 不要使用絕對路徑或 Windows 路徑格式
  • 時間估算(所有階段都是必須的):

    • 階段 1: 約 1 分鐘(Haiku)
    • 階段 2: 約 3-4 分鐘(6 個 Sonnet 並行)
    • 階段 3: 約 10-20 秒(N 個 Haiku 並行)← 不可跳過,時間極短
    • 階段 4: 約 30 秒(主 session 處理)
    • 階段 5: 約 2-3 分鐘(1 個 Sonnet)
    • 總計: 約 7-9 分鐘(中型專案,100 個發現)

    關鍵時間說明:

    • 階段 3 雖然處理 100+ 個發現,但因為 Haiku 極快且並行執行,只需 10-20 秒
    • 跳過階段 3 只能「節省」10-20 秒,但會失去整個插件的核心價值
    • 即使 200 個發現,階段 3 也只需 15-25 秒
  • 成本優化(設計已優化,無需手動調整):

    • 階段 1: Haiku(快速、便宜)
    • 階段 2: Sonnet(推理能力強,用於深度分析)
    • 階段 3: Haiku(任務簡單、數量多、成本極低)← 100 個 Haiku 調用成本 < 1 個 Sonnet
    • 階段 4: 無模型調用(主 session 處理)
    • 階段 5: Sonnet(需要創造力和結構化能力)

    總成本分析:

    • 中型專案(245 檔案):約 2 Haiku + 6 Sonnet + 100 Haiku + 1 Sonnet
    • 等價成本:約 10-12 個 Sonnet 調用
    • 相比全用 Sonnet 的簡單方案:節省 60-70% 成本
  • 質量保證:

    • 所有發現都必須有檔案路徑證據
    • 評分代理會驗證檔案存在性
    • 閾值過濾確保只有高質量發現進入最終文件
    • 多層防護機制防止幻覺

Sponsors

Details

Marketplace
DennisLiuCk/claude-plugin-marketplace
Source
plugins/legacy-analyzer
Author
Dennis Liu (繁體中文版)
Category
Development

More from DennisLiuCk/claude-plugin-marketplace

All 20