# 規劃 (Plan) - 多模型協作規劃

多模型協作規劃 - 上下文檢索 + 雙模型分析 → 生成逐步實作計畫。

$ARGUMENTS

---

## 核心協議 (Core Protocols)

- **語言協議**：與工具/模型互動時使用 **英文 (English)**，與使用者溝通時使用使用者的語言。
- **強制平行**：對 Codex/Gemini 的呼叫 **必須** 使用 `run_in_background: true` (包括單一模型呼叫，以避免阻塞主執行緒)。
- **程式碼主權 (Code Sovereignty)**：外部模型 **完全沒有檔案系統寫入權限**，所有修改均由 Claude 執行。
- **止損機制**：在驗證當前階段輸出之前，不要進入下一階段。
- **僅限規劃**：此指令允許讀取上下文並寫入 `.claude/plan/*` 計畫檔案，但 **絕對禁止修改生產程式碼**。

---

## 多模型呼叫規範

**呼叫語法** (平行處理：使用 `run_in_background: true`)：

```
Bash({
  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF'
ROLE_FILE: <角色提示詞路徑>
<TASK>
需求：<增強後的需求>
上下文：<檢索到的專案上下文>
</TASK>
輸出：包含偽代碼的逐步實作計畫。請勿修改任何檔案。
EOF",
  run_in_background: true,
  timeout: 3600000,
  description: "簡短描述"
})
```

**模型參數說明**：
- `{{GEMINI_MODEL_FLAG}}`：當使用 `--backend gemini` 時，請替換為 `--gemini-model gemini-3-pro-preview` (注意後方空格)；對於 codex 請使用空字串。

**角色提示詞 (Role Prompts)**：

| 階段 | Codex | Gemini |
|-------|-------|--------|
| 分析 (Analysis) | `~/.claude/.ccg/prompts/codex/analyzer.md` | `~/.claude/.ccg/prompts/gemini/analyzer.md` |
| 規劃 (Planning) | `~/.claude/.ccg/prompts/codex/architect.md` | `~/.claude/.ccg/prompts/gemini/architect.md` |

**會話重用**：每次呼叫都會返回 `SESSION_ID: xxx`（通常由 wrapper 輸出），**必須儲存** 以供後續 `/ccg:execute` 使用。

**等待背景任務** (最大逾時 600000ms = 10 分鐘)：

```
TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
```

**重要 (IMPORTANT)**：
- 必須指定 `timeout: 600000`，否則預設的 30 秒會導致提前逾時。
- 若 10 分鐘後仍未完成，請使用 `TaskOutput` 繼續輪詢，**絕對不要殺死進程 (Kill the process)**。
- 若因逾時跳過等待，**必須呼叫 `AskUserQuestion` 詢問使用者是否繼續等待或殺死任務。**

---

## 執行工作流

**規劃任務**：$ARGUMENTS

### 階段 1：完整上下文檢索 (Full Context Retrieval)

`[Mode: Research]`

#### 1.1 提示詞增強 (必須首先執行)

**必須呼叫 `mcp__ace-tool__enhance_prompt` 工具**：

```
mcp__ace-tool__enhance_prompt({
  prompt: "$ARGUMENTS",
  conversation_history: "<最近 5-10 輪對話>",
  project_root_path: "$PWD"
})
```

等待增強後的提示詞，並在後續所有階段中 **將原始 $ARGUMENTS 替換為增強後的結果**。

#### 1.2 上下文檢索

**呼叫 `mcp__ace-tool__search_context` 工具**：

```
mcp__ace-tool__search_context({
  query: "<基於增強後需求的語義查詢>",
  project_root_path: "$PWD"
})
```

- 使用自然語言構建語義查詢 (Where/What/How)。
- **絕對不要基於假設進行回答。**
- 若 MCP 不可用：回退到使用 Glob + Grep 進行檔案發現與關鍵符號定位。

#### 1.3 完整性檢查

- 必須獲取相關類別、函式、變數的 **完整定義與簽名**。
- 若上下文不足，觸發 **遞迴檢索**。
- 優先輸出：入口檔案 + 行號 + 關鍵符號名稱；僅在消除歧義必要時加入最小代碼片段。

#### 1.4 需求對齊

- 若需求仍有歧義，**必須** 輸出引導性問題供使用者回答。
- 直到需求邊界清晰 (無遺漏、無冗餘)。

### 階段 2：多模型協作分析 (Multi-Model Collaborative Analysis)

`[Mode: Analysis]`

#### 2.1 分派輸入

**平行呼叫** Codex 與 Gemini (`run_in_background: true`)：

將 **原始需求** (不帶預設意見) 分派給兩個模型：

1. **Codex 後端分析**：
   - ROLE_FILE: `~/.claude/.ccg/prompts/codex/analyzer.md`
   - 關注點：技術可行性、架構影響、效能考量、潛在風險。
   - 輸出：多維度解決方案 + 優缺點分析。

2. **Gemini 前端分析**：
   - ROLE_FILE: `~/.claude/.ccg/prompts/gemini/analyzer.md`
   - 關注點：UI/UX 影響、使用者體驗、視覺設計。
   - 輸出：多維度解決方案 + 優缺點分析。

使用 `TaskOutput` 等待兩個模型的完整結果。**儲存 SESSION_ID** (`CODEX_SESSION` 與 `GEMINI_SESSION`)。

#### 2.2 交叉驗證

整合觀點並進行優化迭代：

1. **識別共識** (強力信號)。
2. **識別分歧** (需要權衡)。
3. **優勢互補**：後端邏輯以 Codex 為準，前端設計以 Gemini 為準。
4. **邏輯推理**：消除方案中的邏輯漏洞。

#### 2.3 (選擇性但建議執行) 雙模型計畫草案

為了減少 Claude 綜合計畫中的遺漏風險，可以平行要求兩個模型輸出「計畫草案」 (依然 **不允許** 修改檔案)：

1. **Codex 計畫草案** (後端權威)：
   - ROLE_FILE: `~/.claude/.ccg/prompts/codex/architect.md`
   - 輸出：逐步計畫 + 偽代碼 (關注點：資料流/邊緣情況/錯誤處理/測試策略)。

2. **Gemini 計畫草案** (前端權威)：
   - ROLE_FILE: `~/.claude/.ccg/prompts/gemini/architect.md`
   - 輸出：逐步計畫 + 偽代碼 (關注點：資訊架構/互動/無障礙/視覺一致性)。

使用 `TaskOutput` 等待結果，記錄建議中的關鍵差異。

#### 2.4 生成實作計畫 (Claude 最終版本)

綜合雙方分析，生成 **逐步實作計畫**：

```markdown
## 實作計畫：<任務名稱>

### 任務類型
- [ ] 前端 (→ Gemini)
- [ ] 後端 (→ Codex)
- [ ] 全端 (→ 平行處理)

### 技術方案
<從 Codex + Gemini 分析中綜合出的最佳方案>

### 實作步驟
1. <步驟 1> - 預期交付物
2. <步驟 2> - 預期交付物
...

### 關鍵檔案
| 檔案 | 操作 | 描述 |
|------|-----------|-------------|
| path/to/file.ts:L10-L50 | 修改 | 描述 |

### 風險與修補建議
| 風險 | 修補建議 |
|------|------------|

### SESSION_ID (供 /ccg:execute 使用)
- CODEX_SESSION: <session_id>
- GEMINI_SESSION: <session_id>
```

### 階段 2 結束：計畫交付 (而非執行)

**`/ccg:plan` 的職責到此結束，必須執行以下動作**：

1. 向使用者展示完整的實作計畫 (包含偽代碼)。
2. 將計畫儲存至 `.claude/plan/<功能名稱>.md` (從需求中擷取功能名稱，例如：`user-auth`, `payment-module`)。
3. 以 **粗體文字** 輸出提示訊息 (必須使用實際儲存的檔案路徑)：

   ---
   **計畫已生成並儲存至 `.claude/plan/實際功能名稱.md`**
