/analyze-java

description: 分析 Legacy Java Spring Boot 專案並生成教學文件
allowedTools:
  - Task
  - TodoWrite
  - Read
  - Write
  - Glob
  - Grep
  - Bash

Legacy Java Project Analyzer

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

要執行此操作，請精確遵循以下步驟：

準備工作

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

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

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

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

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

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

4. 使用 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"
     ]
   }

5. 將專案摘要寫入：`.legacy-analysis/session-{timestamp}/01-project-scan.json`

階段 2: 多視角並行分析

6. 啟動 **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 個

---

7. 等待所有 6 個代理完成，收集所有輸出

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

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

10. 統計總發現數量並報告（例如："收集到 102 個發現"）

階段 3: 獨立置信度評分

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

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

1. **這是整個插件的靈魂**

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

2. **防幻覺機制完全依賴此階段**

• 第二層防護：評分代理使用 Glob 驗證檔案存在