---
title: "任務規劃"
description: "Gemini CLI 任務規劃：todos、planning 工具、複雜任務拆分、執行前計劃、執行中檢查和完成標準。"
verifiedAt: "2026-05-09"
---

Gemini CLI 的任務規劃能力適合處理多步驟任務。官方文件把 todos / planning 作為工具能力和 tutorial 主題列出。

> [!IMPORTANT]
> **複雜任務先計劃**：跨檔案修改、重構、遷移、測試修復、CI 自動化，都應該先讓 Gemini CLI 列計劃，再進入執行。

## 什麼時候需要計劃

- 需要改多個檔案。
- 需要先讀專案結構。
- 需要跑測試並根據結果迭代。
- 涉及資料庫、構建、部署、許可權。
- 你不確定它會改哪裡。

## 推薦 prompt

第一句先限定邊界：`先不要修改檔案。請先閱讀相關程式碼，列出執行計劃、會影響哪些檔案、需要跑哪些驗證。`

確認計劃後再說：

執行時再縮小範圍：`按計劃執行第一步，只改一個檔案，改完展示 diff。`

更完整的版本可以直接要求它輸出邊界：

```text
先不要修改文件。请只读分析这个问题，输出：
1. 你需要检查哪些文件；
2. 你预计会修改哪些文件；
3. 哪些文件明确不会碰；
4. 每一步的验证命令；
5. 失败时停止条件；
6. 需要我确认的风险点。
```

這類 prompt 的價值不是形式感，而是把 agent 的行動範圍提前暴露出來。計劃越具體，後續 diff 越容易稽核。

## 一個穩定任務迴圈

```mermaid
flowchart TD
    A["讀專案"] --> B["列計劃"]
    B --> C["使用者確認"]
    C --> D["執行一小步"]
    D --> E["跑驗證"]
    E --> F{"透過?"}
    F -->|是| G["繼續下一步"]
    F -->|否| H["分析失敗原因"]
    H --> B
```

## 完成標準

每個任務至少要明確：

- 改哪些檔案。
- 不改哪些邊界。
- 用什麼命令驗證。
- 失敗時如何回復。
- 什麼狀態算完成。

## 計劃和 todo 的分工

計劃回答“為什麼這樣做、影響什麼、風險在哪”；todo 回答“當前執行到哪一步”。計劃可以寫得更完整，todo 應該短而可執行。長任務裡，兩者都需要：先有方案，再用 todo 跟蹤執行。

| 專案 | 計劃 | Todo |
| --- | --- | --- |
| 主要作用 | 解釋方案和風險 | 跟蹤當前進度 |
| 粒度 | 可以包含背景、取捨、驗證 | 每項應該短、可執行 |
| 更新時間 | 任務邊界變化時更新 | 每完成一步就更新 |
| 使用者審查點 | 執行前審查 | 執行中看狀態 |

一個常見錯誤是把 todo 寫成“最佳化文件、修復問題、跑測試”。這種條目太大，無法判斷進度。更好的拆法是“讀取相關文件”“補導航卡”“跑 MDX 型別檢查”“記錄未覆蓋風險”。

官方 todo 工具要求同一時間只有一個 `in_progress`，狀態只屬於當前會話。它適合執行透明度，不適合替代專案管理。需要交接給另一個人或另一個 agent 時，要把計劃和完成狀態寫進檔案或 issue，而不是隻依賴會話內 todo。

Plan Mode 的邊界也要寫清：進入後是隻讀 `PLAN` approval mode，不適合 YOLO；退出時需要一個真實存在且有內容的 Markdown plan，使用者批准後才回到執行模式。

## 計劃質量檢查

執行前可以用這張錶快速判斷計劃是不是合格：

| 檢查項 | 合格表現 | 不合格表現 |
| --- | --- | --- |
| 檔案範圍 | 列出會改和不會改的路徑 | 只說“相關檔案” |
| 風險邊界 | 標明許可權、資料、部署、相容性風險 | 只說“風險較低” |
| 驗證命令 | 給出具體命令和預期結果 | 只說“執行測試” |
| 中止條件 | 說明失敗後停在哪一步 | 失敗後繼續試錯 |
| 人工確認 | 高風險節點等使用者確認 | 自己連續執行高風險步驟 |

計劃不合格時，不要讓它直接開改。先要求 Gemini CLI 把計劃改到可審查，再批准第一步。

## 驗收方式

執行前檢查計劃是否覆蓋影響檔案、驗證命令、回復方式和人工確認點。執行中檢查 todo 是否只保留一個 `in_progress`。完成後要求 Gemini CLI 總結已改檔案、未覆蓋風險和實際跑過的驗證，不接受只說“完成了”。

## 接下來去哪

<Cards>
  <Card title="Checkpoint 與 rewind" description="計劃進入執行前，繼續看如何給檔案修改增加恢復點。" href="/zh-Hant/docs/gemini-cli/official/01-cli-workflow/18-checkpointing-rewind" />
  <Card title="Todos / Planning 工具" description="繼續看官方工具層面的 todos、planning 和任務狀態語義。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/34-todos-planning-tools" />
  <Card title="Plan mode" description="高風險任務先進入只讀規劃模式，再批准執行。" href="/zh-Hant/docs/gemini-cli/official/01-cli-workflow/19-plan-mode" />
</Cards>

## 官方來源

- [Gemini CLI task planning tutorial](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/task-planning.md)
- [Gemini CLI todo tool](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/todos.md)
- [Gemini CLI planning tools](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/planning.md)
