
legacy-analyzer
使用多個專門代理配合基於置信度的評分系統,分析 Legacy Java Spring Boot 專案並產生高品質教學文件
- version
- 1.4.0
- GitHub stars
- 29
Install
/plugin install legacy-analyzer@claude-plugin-marketplace-zh-twRun it inside Claude Code after adding the marketplace with /plugin marketplace add DennisLiuCk/claude-plugin-marketplace.
Contents
Discovered from sourceCommands 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-domain | analyze-java-domain-flow |
|---|---|---|
| 輸出檔案 | 6 個 Markdown 檔案 (~850行) | 單一檔案 (~300行) |
| 執行時間 | 4-6 分鐘 | 2-3 分鐘 |
| 核心內容 | 完整領域文件 | 調用鏈 + 流程圖 |
| 資料模型 | 詳細 DTO/Entity 說明 | 僅列出涉及類別 |
| 業務規則 | 完整規則文件 | 不包含 |
搜尋範圍
只搜尋:.java、.xml(MyBatis Mapper)
排除:pom.xml、.yml、.properties
要執行此操作,請精確遵循以下步驟:
階段 1: 入口點發現(Haiku,~30秒)
-
解析使用者輸入,產生搜尋策略:
{ "domain": "商品建立", "keywords": { "chinese": ["商品", "產品", "建立", "新增"], "english": ["Product", "Item", "Create", "Add", "Save"], "patterns": ["create.*Product", "add.*Product", "Product.*Controller"] } } -
使用 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"] } -
如果找不到入口點,終止並建議:
找不到與「{關鍵字}」相關的程式碼。 建議:使用英文關鍵字如 "Product" 或 "Order"
階段 2: 調用鏈追蹤(Sonnet,~1-2分鐘)
-
對每個入口點(最多 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"] } -
收集所有調用鏈結果
階段 3: 流程驗證與評分(Haiku,~20秒)
-
對每條調用鏈啟動 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分鐘)
-
啟動 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調用層級
層級 類別.方法 檔案位置 說明 0 ProductController.createProduct ProductController.java:67 接收請求 1 ProductServiceImpl.create ProductServiceImpl.java:45 業務邏輯 2 ProductRepository.save ProductRepository.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
涉及類別清單
類別 類型 檔案位置 ProductController Controller src/.../ProductController.java ProductServiceImpl Service src/.../ProductServiceImpl.java ProductRepository Repository src/.../ProductRepository.java Product Entity src/.../Product.java ProductDTO DTO src/.../ProductDTO.java
驗證摘要
調用鏈 完整性 準確性 清晰度 總分 狀態 chain-1: 建立商品 95 90 85 91 verified **文件撰寫規則**: - 使用繁體中文 - 每條調用鏈必須有 **Mermaid sequenceDiagram** - 文件末尾必須有 **整體架構 flowchart** - 程式碼片段限制 5-10 行 - 所有檔案引用必須包含行號 - **禁止**:改善建議、效能優化、測試策略 -
將文件寫入:
.legacy-analysis/flow-{keyword}-{timestamp}/DOMAIN-FLOW.md
完成
-
顯示完成摘要:
╔═══════════════════════════════════════════════════════════╗ ║ 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="關鍵字" (會搜尋所有檔案)
要執行此操作,請精確遵循以下步驟:
準備工作
-
解析使用者輸入,識別:
- 領域關鍵字(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"] } } -
使用 TodoWrite 建立待辦事項清單
-
創建工作目錄:
.legacy-analysis/domain-{keyword}-{timestamp}/- keyword:領域關鍵字的英文簡寫(如 product-create)
階段 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 進行全專案掃描 -
將入口點資訊寫入:
.legacy-analysis/domain-{keyword}-{timestamp}/01-entry-points.json
階段 2: 深度調用鏈追蹤
-
對於每個入口點,啟動一個 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/或類似目錄
-
等待所有追蹤代理完成,收集結果
-
合併所有調用鏈並寫入:
.legacy-analysis/domain-{keyword}-{timestamp}/02-call-chains.json
階段 3: 發現提取與評分
-
從調用鏈中提取發現(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" } -
對每個發現啟動 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" } -
⚠️ MANDATORY: 等待所有評分完成,不可跳過
-
將評分結果寫入:
.legacy-analysis/domain-{keyword}-{timestamp}/03-scores.json
階段 4: 過濾與整理
-
應用過濾規則(與 analyze-java 相同):
- 保留 total_score >= 75
- evidence < 60 強制丟棄
- accuracy < 50 強制丟棄
- importance >= 90 且 evidence >= 70 例外保留
-
按調用鏈順序組織發現:
- 將發現按其在調用鏈中的位置排序
- 標記發現之間的關聯關係
-
寫入結構化資料:
.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
-
依章節分檔生成,每個章節由獨立的 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 |
撰寫風格(所有文件通用):
- 使用繁體中文
- 假設讀者不了解此專案
- 優先使用表格呈現結構化資訊
- 所有程式碼引用必須有
檔案名:行號 - 每個文件開頭包含返回索引的連結
- 每個資訊只出現在一個文件中(避免重複)
- 禁止使用「建議」「應該」「優化」「未來」等字眼
-
並行生成文件:
啟動 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%)
- 代理 A: 生成
-
將所有文件寫入:
.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 行)
完成
-
顯示完成摘要:
╔═══════════════════════════════════════════════════════════╗ ║ 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。
要執行此操作,請精確遵循以下步驟:
準備工作
-
首先使用 TodoWrite 建立待辦事項清單,包含所有階段
-
創建工作目錄:
.legacy-analysis/session-{timestamp}/
階段 1: 資格預檢與快速掃描
-
使用 Haiku 代理檢查專案是否適合分析。代理應檢查:
- 專案根目錄是否存在
pom.xml或build.gradle? - 是否包含 Spring Boot 依賴?(檢查 spring-boot-starter)
- Java 檔案數量是否適中?(使用 Glob 統計 **/*.java,應 < 1000)
如果不符合任一條件,說明原因並終止。
- 專案根目錄是否存在
-
使用 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" ] } -
將專案摘要寫入:
.legacy-analysis/session-{timestamp}/01-project-scan.json
階段 2: 多視角並行分析
-
啟動 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 個
-
等待所有 6 個代理完成,收集所有輸出
-
合併所有發現清單為一個 JSON 陣列
-
將合併的發現清單寫入:
.legacy-analysis/session-{timestamp}/02-findings-raw.json -
統計總發現數量並報告(例如:"收集到 102 個發現")
階段 3: 獨立置信度評分
⚠️⚠️⚠️ CRITICAL - THIS STAGE IS MANDATORY AND CANNOT BE SKIPPED ⚠️⚠️⚠️
為什麼這個階段是核心且不可跳過的:
-
這是整個插件的靈魂
- 置信度評分系統是本插件與其他分析工具的根本差異
- 沒有評分 = 沒有質量保證 = 無法區分真實發現與幻覺
- 跳過此階段違反了插件的核心設計原則
-
防幻覺機制完全依賴此階段
- 第二層防護:評分代理使用 Glob 驗證檔案存在
- 第三層防護:閾值過濾(score >= 75, evidence >= 60)
- 沒有評分 = 防幻覺機制失效 = 可能產生錯誤文件
-
成本和時間都非常合理
- Haiku 模型速度極快(每個評分 < 1 秒)
- 100 個評分代理並行執行只需 10-20 秒
- Haiku 成本極低(相比 Sonnet 便宜 50-100 倍)
- 即使 200 個發現,總時間也只增加 10-15 秒
-
不評分的嚴重後果
- 最終文件會包含所有未驗證的發現(包括幻覺、錯誤、瑣碎內容)
- 過濾率 0%(承諾是 40-60%)
- 無法信任檔案路徑和行號
- 用戶體驗極差,失去插件價值
明確的執行要求:
❌ 絕對禁止以下行為:
- 以「發現數量太多」為理由跳過評分
- 以「節省時間」為理由跳過評分
- 以「成本考量」為理由跳過評分
- 直接使用未評分的發現生成文件
- 進入階段 4 而不先完成階段 3
✅ 你 MUST 執行以下操作:
- 對 每一個發現 啟動一個獨立的 Haiku 評分代理
- 等待 所有 評分代理完成
- 將所有評分結果寫入
03-scores.json - 只有在
03-scores.json存在後才能繼續下一階段
-
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
-
REQUIRED: 等待 所有 評分代理完成,收集所有評分結果。 不要只收集部分結果,必須等待全部完成。
-
REQUIRED: 將評分結果寫入:
.legacy-analysis/session-{timestamp}/03-scores.json -
統計評分分佈(例如:"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: 編碼實踐
-
每個類別內按 total_score 降序排序(最高質量在前)
-
識別發現之間的關聯關係(可選但推薦):
- 例如:API-001(創建訂單端點)→ BIZ-005(OrderService.createOrder)→ DATA-003(Order Entity)
- 建立關聯圖以幫助理解完整流程
-
生成結構化資料 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" } ] } -
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
- (可選)生成統計報告並寫入:
.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 } }
完成
-
顯示完成摘要,包含:
╔═══════════════════════════════════════════════════════╗ ║ 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- plugin-devv1.1.0
- pr-review-toolkitv1.0.0
- ralph-loopv1.0.0
- security-guidancev1.0.0
- skill-creatorv1.0.0
- sql-to-oscv1.0.0
- agent-sdk-devv1.0.0
- claude-opus-4-5-migrationv1.0.0
- code-reviewv1.0.0
- code-simplifierv1.0.0
- commit-commandsv1.0.0
- community-code-reviewv1.0.0
- explanatory-output-stylev1.0.0
- feature-devv1.0.0
- frontend-designv1.0.0
- hookifyv0.1.0
- issue-reviewv1.0.0
- java-code-simplifierv1.0.0
- learning-output-stylev1.0.0