gh-vivalalova-claude-code-plugin-plugins-agent-ide/references/examples.md

# Agent IDE 使用範例

## 範例 1：重命名符號

### 使用者需求
「將 `getUserData` 重命名為 `fetchUserProfile` 並更新所有引用」

### 執行步驟

1. **預覽變更**：
```bash
npx agent-ide rename --from getUserData --to fetchUserProfile --preview
```

2. **確認並執行**：
```bash
npx agent-ide rename --from getUserData --to fetchUserProfile
```

### 預期結果
- 所有檔案中的 `getUserData` 都被重命名為 `fetchUserProfile`
- 所有 import 語句自動更新
- 所有函式呼叫自動更新
- 所有註解中的引用保持不變（需手動檢查）

## 範例 2：移動檔案並更新 Import

### 使用者需求
「將 `src/utils/helpers.ts` 移動到 `src/shared/utils/helpers.ts`」

### 執行步驟

1. **確保目標目錄存在**：
```bash
mkdir -p src/shared/utils
```

2. **預覽移動**：
```bash
npx agent-ide move src/utils/helpers.ts src/shared/utils/helpers.ts --preview
```

3. **執行移動**：
```bash
npx agent-ide move src/utils/helpers.ts src/shared/utils/helpers.ts
```

### 預期結果
- 檔案成功移動到新位置
- 所有 import 語句自動更新：
  - 舊：`import { helper } from '../utils/helpers'`
  - 新：`import { helper } from '../shared/utils/helpers'`

## 範例 3：分析專案品質

### 使用者需求
「分析專案中的循環依賴和程式碼品質問題」

### 執行步驟

1. **執行垃圾度評分**：
```bash
npx agent-ide shit --detailed --format json
```

2. **分析複雜度**：
```bash
npx agent-ide analyze complexity --format json --all
```

3. **檢查依賴關係**：
```bash
npx agent-ide deps --format json --all
```

4. **偵測死代碼**：
```bash
npx agent-ide analyze dead-code --format json --all
```

### 預期結果
- ShitScore 報告顯示整體品質評級
- 複雜度分析列出高複雜度函式
- 依賴關係圖顯示循環依賴
- 死代碼列表顯示未使用的程式碼

## 範例 4：重構長函式

### 使用者需求
「將 `src/app.ts` 中第 50-80 行的邏輯提取為 `processUserData` 函式」

### 執行步驟

1. **提取函式**：
```bash
npx agent-ide refactor extract-function \
  --file src/app.ts \
  --start-line 50 \
  --end-line 80 \
  --function-name processUserData
```

2. **驗證結果**：
- 檢查新函式是否正確建立
- 確認原位置已替換為函式呼叫
- 測試功能是否正常

### 預期結果
- 新函式 `processUserData` 建立在適當位置
- 原程式碼被函式呼叫取代
- 所有變數作用域正確處理

## 範例 5：搜尋符號並分析使用

### 使用者需求
「找出專案中所有使用 `UserService` 的地方」

### 執行步驟

1. **搜尋符號**：
```bash
npx agent-ide search "UserService" --format json
```

2. **分析特定檔案的依賴**：
```bash
npx agent-ide deps --file src/services/user-service.ts --format json
```

### 預期結果
- 列出所有引用 `UserService` 的檔案和位置
- 顯示 `UserService` 的依賴關係
- 幫助理解 `UserService` 的使用模式

## 範例 6：批量重構工作流程

### 使用者需求
「重構 `auth` 模組：重命名主類別、移動檔案、分析影響範圍」

### 執行步驟

1. **分析當前狀態**：
```bash
npx agent-ide deps --file src/auth/AuthService.ts --format json
npx agent-ide search "AuthService" --format json
```

2. **重命名類別**：
```bash
npx agent-ide rename --from AuthService --to AuthenticationService --preview
npx agent-ide rename --from AuthService --to AuthenticationService
```

3. **重組檔案結構**：
```bash
mkdir -p src/modules/authentication
npx agent-ide move src/auth/AuthenticationService.ts src/modules/authentication/service.ts
```

4. **驗證品質**：
```bash
npx agent-ide shit --detailed --format json
npx agent-ide analyze complexity --format json
```

### 預期結果
- 所有重命名正確執行
- Import 路徑全部更新
- 專案結構更清晰
- 品質評分改善

## 範例 7：處理循環依賴

### 使用者需求
「偵測並解決專案中的循環依賴問題」

### 執行步驟

1. **偵測循環依賴**：
```bash
npx agent-ide deps --format json --all
```

2. **分析問題檔案**：
```bash
npx agent-ide deps --file src/services/user.ts --format json
npx agent-ide deps --file src/services/auth.ts --format json
```

3. **重構解決方案**：
- 識別循環依賴的原因
- 提取共用介面到獨立檔案
- 使用依賴注入打破循環

4. **驗證修復**：
```bash
npx agent-ide deps --format json --all
npx agent-ide shit --format json
```

### 預期結果
- 循環依賴被識別
- 透過重構解決循環依賴
- ShitScore 中的「架構」評分降低

## 範例 8：使用 snapshot 快速診斷專案

### 使用者需求
「快速了解新接手的專案結構和品質狀況」

### 執行步驟

1. **生成完整快照**：
```bash
npx agent-ide snapshot --compression full --output project-snapshot.json
```

2. **查看快照結果**：
- 檔案數量和結構
- 程式碼行數統計
- 基本品質指標
- 主要問題區域

3. **針對性分析**：
```bash
# 查看詳細品質報告
npx agent-ide shit --detailed --top=20

# 分析高複雜度檔案
npx agent-ide analyze complexity --all
```

### 預期結果
- 8.7 秒內完成 62 檔案專案分析
- 消耗約 59,138 tokens
- 快速識別問題而無需手動檢查檔案
- 建立改善路線圖

### 實際案例

**專案規模**：62 檔案，4,740 行程式碼

**快照發現**：
- 46 個 `any` 型別使用
- ShitScore 22.02
- 3 個循環依賴
- 12 個高複雜度函式

**改善成效**：
- 消除所有 `any` 型別
- ShitScore 降至 19.56（-11%）
- 型別安全提升 35%

## 範例 9：CI/CD 整合與質量閘門

### 使用者需求
「在 CI/CD 流程中設定程式碼品質閘門，確保品質不降低」

### GitHub Actions 整合

建立 `.github/workflows/quality-check.yml`：

```yaml
name: Code Quality Check

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  quality:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install agent-ide
        run: npm install -g agent-ide

      - name: Generate snapshot
        run: npx agent-ide snapshot --output reports/snapshot.json

      - name: Check ShitScore (質量閘門)
        run: npx agent-ide shit --max-allowed=70

      - name: Analyze complexity
        run: npx agent-ide analyze complexity --all --format json

      - name: Detect circular dependencies
        run: npx agent-ide deps --detect-circular

      - name: Upload reports
        uses: actions/upload-artifact@v3
        with:
          name: quality-reports
          path: reports/
```

### 執行步驟

1. **設定質量閘門**：
   - 嚴格專案：`--max-allowed=50`（B 級或更好）
   - 一般專案：`--max-allowed=70`（C 級或更好）
   - 遺留專案：`--max-allowed=85`（避免 F 級）

2. **定期品質追蹤**：
```bash
#!/bin/bash
# 每日執行
DATE=$(date +%Y%m%d)
npx agent-ide snapshot --output "snapshots/$DATE.json"
npx agent-ide shit --format json > "quality/$DATE.json"
```

3. **品質趨勢分析**：
- 比對每日 ShitScore 變化
- 追蹤複雜度趨勢
- 監控依賴關係變化

### 預期結果
- CI/CD 自動檢查程式碼品質
- 品質不符標準時阻止合併
- 長期追蹤品質趨勢
- 團隊品質意識提升

## 範例 10：批量重構整個模組

### 使用者需求
「重構整個 `legacy` 模組，包含批量重命名、檔案重組和品質改善」

### 執行步驟

#### Phase 1：診斷分析

```bash
# 生成快照
npx agent-ide snapshot --compression full

# 評估當前品質
npx agent-ide shit --detailed --top=20

# 分析 legacy 模組依賴
npx agent-ide deps --file src/legacy/ --format json
```

**診斷結果範例**：
- ShitScore: 67.3（D 級）
- 直接影響 23 個檔案
- 間接影響 45 個檔案
- 3 個循環依賴

#### Phase 2：批量重命名

建立 `rename-config.json`：
```json
{
  "renames": [
    { "from": "getLegacyData", "to": "fetchData" },
    { "from": "oldProcessor", "to": "dataProcessor" },
    { "from": "legacyHandler", "to": "requestHandler" }
  ]
}
```

執行批量重命名：
```bash
npx agent-ide rename --config rename-config.json --preview
npx agent-ide rename --config rename-config.json
```

#### Phase 3：檔案重組

```bash
# 建立新結構
mkdir -p src/modules/data-processing

# 批量移動檔案
npx agent-ide move src/legacy/processor src/modules/data-processing --recursive --preview
npx agent-ide move src/legacy/processor src/modules/data-processing --recursive
```

#### Phase 4：降低複雜度

```bash
# 找出高複雜度函式
npx agent-ide analyze complexity --all

# 提取複雜邏輯
npx agent-ide refactor extract-function \
  --file src/modules/data-processing/processor.ts \
  --start-line 45 \
  --end-line 120 \
  --function-name processData
```

#### Phase 5：驗證改善

```bash
# 執行測試
npm test

# 驗證品質改善
npx agent-ide shit --detailed

# 檢查循環依賴
npx agent-ide deps --detect-circular
```

### 預期結果

**品質改善**：
- ShitScore 從 67.3 降到 35.8（-47%）
- 複雜度從 45 降到 5
- 消除所有循環依賴
- 檔案結構更清晰

**影響範圍**：
- 直接修改 23 個檔案
- 自動更新 45 個檔案的 import
- 零 TypeScript 編譯錯誤
- 所有測試通過

**團隊收益**：
- 維護成本降低 40%
- 新功能開發速度提升 25%
- Bug 率降低 30%

## 最佳實踐

### 重構前必做
1. 執行 `--preview` 檢查影響範圍
2. 確保有版本控制（git commit）
3. 執行測試確保功能正常

### 重構後必做
1. 執行 `npx agent-ide shit` 確認品質改善
2. 執行專案的 build 和 lint
3. 執行測試套件
4. Commit 變更

### 效率技巧
1. 使用 `--format json` 方便程式化處理
2. 善用 `--preview` 避免錯誤
3. 搭配 `code_deps` 和 `code_search` 理解影響範圍
4. 定期執行 `code_shit` 追蹤品質趨勢