Initial commit

commands/analyze-java-domain-flow.md

@@ -0,0 +1,374 @@
+---
+description: 高效分析 Java Spring Boot 專案的調用鏈與流程圖（單一檔案輸出）
+allowed-tools:
+  - Task
+  - TodoWrite
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Bash
+---
+
+# 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秒）
+
+1. **解析使用者輸入**，產生搜尋策略：
+
+   ```json
+   {
+     "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**：
+   ```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分鐘）
+
+4. 對每個入口點（最多 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**：
+   ```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"]
+   }
+   ```
+
+5. 收集所有調用鏈結果
+
+---
+
+## 階段 3: 流程驗證與評分（Haiku，~20秒）
+
+6. 對每條調用鏈啟動 **Haiku 代理**進行驗證評分：
+
+   **驗證維度**：
+   - **路徑完整性 (40%)**：調用鏈是否從入口到資料層完整
+   - **證據準確性 (40%)**：檔案路徑和行號是否正確
+   - **邏輯清晰度 (20%)**：流程描述是否清楚
+
+   **輸出評分 JSON**：
+   ```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分鐘）
+
+7. 啟動 **Sonnet 代理**生成單一 Markdown 文件。
+
+   **文件結構**（目標 ~300 行）：
+
+   ```markdown
+   # {領域名稱} 調用鏈分析
+
+   > 自動生成於 {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`)
+
+   ```java
+   if (productRepo.existsByName(dto.getName())) {
+       throw new ProductExistsException();
+   }
+   Product product = mapper.toEntity(dto);
+   return productRepo.save(product);
+   ```
+
+   ---
+
+   ## 整體架構圖
+
+   ```mermaid
+   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 行
+   - 所有檔案引用必須包含行號
+   - **禁止**：改善建議、效能優化、測試策略
+
+8. 將文件寫入：`.legacy-analysis/flow-{keyword}-{timestamp}/DOMAIN-FLOW.md`
+
+---
+
+## 完成
+
+9. 顯示完成摘要：
+
+   ```
+   ╔═══════════════════════════════════════════════════════════╗
+   ║     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%

commands/analyze-java-domain.md

@@ -0,0 +1,804 @@
+---
+description: 分析 Legacy Java Spring Boot 專案中的特定領域邏輯與業務流程
+allowed-tools:
+  - 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**：
+   ```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: 快速資格檢查與入口點發現
+
+4. 使用 **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**：
+   ```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 進行全專案掃描
+   ```
+
+5. 將入口點資訊寫入：`.legacy-analysis/domain-{keyword}-{timestamp}/01-entry-points.json`
+
+---
+
+## 階段 2: 深度調用鏈追蹤
+
+6. 對於每個入口點，啟動一個 **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**：
+   ```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/` 或類似目錄
+
+7. 等待所有追蹤代理完成，收集結果
+
+8. 合併所有調用鏈並寫入：`.legacy-analysis/domain-{keyword}-{timestamp}/02-call-chains.json`
+
+---
+
+## 階段 3: 發現提取與評分
+
+9. 從調用鏈中提取**發現（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 相容）：
+   ```json
+   {
+     "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"
+   }
+   ```
+
+10. 對每個發現啟動 **Haiku 代理**進行評分（與 analyze-java 相同的評分機制）：
+
+    **評分維度**：
+    - 證據強度 (40%)：檔案路徑驗證、行號準確性
+    - 重要性 (30%)：對理解領域邏輯的重要程度
+    - 完整性 (15%)：描述是否清晰完整
+    - 準確性 (15%)：技術描述是否正確
+
+    **輸出格式**：
+    ```json
+    {
+      "finding_id": "DOMAIN-001",
+      "scores": {
+        "evidence": 95,
+        "importance": 90,
+        "completeness": 85,
+        "accuracy": 95
+      },
+      "total_score": 92.25,
+      "confidence_level": "very_high"
+    }
+    ```
+
+11. ⚠️ **MANDATORY**: 等待所有評分完成，不可跳過
+
+12. 將評分結果寫入：`.legacy-analysis/domain-{keyword}-{timestamp}/03-scores.json`
+
+---
+
+## 階段 4: 過濾與整理
+
+13. 應用過濾規則（與 analyze-java 相同）：
+    - 保留 total_score >= 75
+    - evidence < 60 強制丟棄
+    - accuracy < 50 強制丟棄
+    - importance >= 90 且 evidence >= 70 例外保留
+
+14. 按調用鏈順序組織發現：
+    - 將發現按其在調用鏈中的位置排序
+    - 標記發現之間的關聯關係
+
+15. 寫入結構化資料：`.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
+
+---
+
+16. **依章節分檔生成**，每個章節由獨立的 **Sonnet 代理**生成：
+
+    **輸入**（所有代理共用）：
+    - 結構化發現 JSON（04-structured.json）
+    - 調用鏈 JSON（02-call-chains.json）
+    - 入口點 JSON（01-entry-points.json）
+    - 使用者原始查詢
+
+    ---
+
+    ### 文件 1: 索引頁 (00-INDEX.md) - 目標 ~50 行
+
+    由主 session 直接生成，內容：
+    - 領域名稱和簡介（2-3 句話）
+    - 文件清單與連結
+    - API 端點總覽表格（唯一出現位置）
+    - 快速統計
+
+    ```markdown
+    # {領域名稱} 領域分析
+
+    > 本文件幫助你理解 {領域名稱} 的現有實作，不包含改善建議。
+
+    ## 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 行
+    - 必須標註 `檔案名:行號`
+    - 以 `// ... 完整實作請見原始檔案` 結尾
+
+    **調用鏈呈現格式**（精簡版）：
+    ```markdown
+    ### 調用鏈 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 範例
+
+    **表格格式範例**：
+    ```markdown
+    ## 業務規則
+
+    | 規則 | 程式碼位置 | 說明 |
+    |------|-----------|------|
+    | 商品名稱不可重複 | 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）
+    - ❌ 除錯技巧詳述
+
+    **檔案清單格式**：
+    ```markdown
+    ## 相關檔案
+
+    ### 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 |
+    ```
+
+    ---
+
+    **撰寫風格**（所有文件通用）：
+    - 使用繁體中文
+    - 假設讀者不了解此專案
+    - 優先使用表格呈現結構化資訊
+    - 所有程式碼引用必須有 `檔案名:行號`
+    - 每個文件開頭包含返回索引的連結
+    - 每個資訊只出現在一個文件中（避免重複）
+    - **禁止使用「建議」「應該」「優化」「未來」等字眼**
+
+17. **並行生成文件**：
+
+    啟動 **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%）
+
+18. 將所有文件寫入：`.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 行)
+    ```
+
+---
+
+## 完成
+
+19. 顯示完成摘要：
+
+    ```
+    ╔═══════════════════════════════════════════════════════════╗
+    ║     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 分鐘**