zhongwei/gh-dennisliuck-claude-plugin-marketplace-plugins-legacy-analyzer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-dennisliuck-claude-plugi…/commands/analyze-java-domain.md
Zhongwei Li b8eff6f333 Initial commit
2025-11-29 18:18:29 +08:00

26 KiB
Raw Permalink Blame History

description, allowed-tools
description allowed-tools
分析 Legacy Java Spring Boot 專案中的特定領域邏輯與業務流程
Task
TodoWrite
Read
Write
Glob
Grep
Bash

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 分鐘
Reference in New Issue View Git Blame Copy Permalink