# 多模型執行 (Multi-Model Execute)

結構化執行工作流：讀取計畫 → 檢索上下文 → 獲取原型 → 程式碼實作 → 稽核與交付。

## 執行流程

1. **識別輸入類型**：
   - 計畫檔案路徑 (例如：`.claude/plan/xxx.md`)
   - 直接的任務描述

2. **讀取計畫內容**：
   - 如果提供了計畫檔案路徑，則讀取並解析。
   - 擷取：任務類型、實作步驟、關鍵檔案、SESSION_ID。

3. **執行前確認**：
   - 如果輸入是「直接任務描述」或缺少 `SESSION_ID` / 關鍵檔案，則先向使用者確認。
   - 如果無法確認使用者對計畫回覆了 "Y"，則在繼續之前必須再次確認。

4. **任務類型路由**：

   | 任務類型 | 偵測指標 | 路由路徑 |
   |-----------|-----------|-------|
   | **前端 (Frontend)** | 頁面、元件、UI、樣式、佈局 | Gemini |
   | **後端 (Backend)** | API、介面、資料庫、邏輯、演算法 | Codex |
   | **全端 (Fullstack)** | 同時包含前端與後端行為 | Codex ∥ Gemini 平行處理 |

---

### 階段 1：快速上下文檢索 (Quick Context Retrieval)

`[Mode: Retrieval]`

**必須使用 MCP 工具進行快速上下文檢索，不得手動逐一讀取檔案。**

根據計畫中的「關鍵檔案」列表，呼叫 `mcp__ace-tool__search_context`：

```
mcp__ace-tool__search_context({
  query: "<基於計畫內容的語義查詢，包含關鍵檔案、模組、函式名稱>",
  project_root_path: "$PWD"
})
```

**檢索策略**：
- 從計畫的「關鍵檔案」表格中擷取目標路徑。
- 構建語義查詢，涵蓋：入口檔案、依賴模組、相關型別定義。
- 如果結果不足，則增加 1-2 次遞迴檢索。
- **絕對不要**使用 Bash + find/ls 手動探索專案結構。

**檢索之後**：
- 整理檢索到的程式碼片段。
- 確認實作所需的上下文已齊全。
- 進入階段 3。

---

### 階段 3：獲取原型 (Prototype Acquisition)

`[Mode: Prototype]`

**依據任務類型進行路由**：

#### 路徑 A：前端/UI/樣式 → Gemini

**限制**：上下文 < 32k tokens

1. 呼叫 Gemini (使用 `~/.claude/.ccg/prompts/gemini/frontend.md`)。
2. 輸入：計畫內容 + 檢索到的上下文 + 目標檔案。
3. 輸出：`僅限 Unified Diff Patch。嚴禁進行任何實際修改。`
4. **Gemini 是前端設計權威，其產出的 CSS/React/Vue 原型即為最終視覺基準。**
5. **警告**：忽略 Gemini 關於後端邏輯的建議。
6. 如果計畫包含 `GEMINI_SESSION`：優先使用 `resume <GEMINI_SESSION>`。

#### 路徑 B：後端/邏輯/演算法 → Codex

1. 呼叫 Codex (使用 `~/.claude/.ccg/prompts/codex/architect.md`)。
2. 輸入：計畫內容 + 檢索到的上下文 + 目標檔案。
3. 輸出：`僅限 Unified Diff Patch。嚴禁進行任何實際修改。`
4. **Codex 是後端邏輯權威，善用其邏輯推理與偵錯能力。**
5. 如果計畫包含 `CODEX_SESSION`：優先使用 `resume <CODEX_SESSION>`。

#### 路徑 C：全端 → 平行呼叫

1. **平行呼叫** (`run_in_background: true`)：
   - Gemini：處理前端部分。
   - Codex：處理後端部分。
2. 使用 `TaskOutput` 等待兩個模型的完整結果。
3. 各自使用計畫中對應的 `SESSION_ID` 進行 `resume` (若缺失則建立新會話)。

**請遵循上方「多模型呼叫規範」中的「重要」指令。**

---

### 階段 4：程式碼實作 (Code Implementation)

`[Mode: Implement]`

**Claude 作為程式碼主權者 (Code Sovereign) 執行以下步驟**：

1. **讀取 Diff**：解析 Codex/Gemini 返回的 Unified Diff Patch。

2. **心智沙盒**：
   - 模擬將 Diff 應用到目標檔案。
   - 檢查邏輯一致性。
   - 識別潛在衝突或副作用。

3. **重構與清理**：
   - 將「髒原型 (dirty prototype)」重構為**高可讀性、具維護性、企業級的程式碼**。
   - 移除冗餘程式碼。
   - 確保符合專案現有的程式碼規範。
   - **除非必要，否則不要生成註釋/文件**，程式碼應能自我解釋 (Self-explanatory)。

4. **最小範圍**：
   - 修改僅限於需求範圍。
   - **強制審查**副作用。
   - 進行針對性的修正。

5. **套用變更**：
   - 使用 Edit/Write 工具執行實際修改。
   - **僅修改必要程式碼**，絕對不影響使用者現有的其他功能。

6. **自我驗證** (強烈建議)：
   - 執行專案現有的 lint / 型別檢查 / 測試 (優先針對最小相關範圍)。
   - 若失敗：先修復迴歸問題 (Regressions)，再進入階段 5。

---

### 階段 5：稽核與交付 (Audit and Delivery)

`[Mode: Audit]`

#### 5.1 自動稽核

**變更生效後，必須立即平行呼叫** Codex 與 Gemini 進行程式碼審查 (Code Review)：

1. **Codex 審查** (`run_in_background: true`)：
   - ROLE_FILE: `~/.claude/.ccg/prompts/codex/reviewer.md`
   - 輸入：變更後的 Diff + 目標檔案
   - 關注點：安全性、性能、錯誤處理、邏輯正確性

2. **Gemini 審查** (`run_in_background: true`)：
   - ROLE_FILE: `~/.claude/.ccg/prompts/gemini/reviewer.md`
   - 輸入：變更後的 Diff + 目標檔案
   - 關注點：無障礙性、設計一致性、使用者體驗

使用 `TaskOutput` 等待兩個模型的完整審查結果。優先重用階段 3 的工作階段 (`resume <SESSION_ID>`) 以保持上下文一致性。

#### 5.2 整合與修復

1. 綜合 Codex + Gemini 的審查回饋。
2. 根據信任規則進行權衡：後端以 Codex 為準，前端以 Gemini 為準。
3. 執行必要的修復。
4. 視需要重複階段 5.1 (直到風險降至可接受範圍)。

#### 5.3 交付確認

稽核通過後，向使用者報告：

```markdown
## 執行完成

### 變更摘要
| 檔案 | 操作 | 描述 |
|------|-----------|-------------|
| path/to/file.ts | 已修改 | 說明 |

### 稽核結果
- Codex: <通過 / 發現 N 個問題>
- Gemini: <通過 / 發現 N 個問題>

### 後續建議
1. [ ] <建議的測試步驟>
2. [ ] <建議的驗證步驟>
```

---

## 關鍵規則

1. **程式碼主權 (Code Sovereignty)** – 所有檔案修改均由 Claude 執行，外部模型無寫入權限。
2. **重構原始原型** – Codex/Gemini 的輸出被視為草稿，必須經過重構。
3. **信任規則** – 後端信任 Codex，前端信任 Gemini。
4. **最小變更** – 僅修改必要程式碼，無副作用。
5. **強制稽核** – 變更後必須進行多模型程式碼審查。

---

## 使用方式

```bash
# 執行計畫檔案
/ccg:execute claude/plan/feature-name.md

# 直接執行任務 (針對已在上下文中討論過的計畫)
/ccg:execute 根據之前的計畫實作用戶身分驗證
```

---

## 與 /ccg:plan 的關係

1. `/ccg:plan` 生成計畫 + SESSION_ID。
2. 使用者以 "Y" 確認。
3. `/ccg:execute` 讀取計畫，重用 SESSION_ID，並執行實作。