---
title: "Todos / Planning 工具"
description: "Gemini CLI todos 和 planning 工具的用途：拆解複雜任務、跟蹤進度、避免長任務失控。"
verifiedAt: "2026-05-09"
---

Todos 和 planning 工具適合長任務。它們讓 Gemini CLI 不只是一步一步猜，而是把任務拆開、標記狀態、按計劃執行。

> [!IMPORTANT]
> Todo 是執行透明度，Plan 是風險控制。不要用一串 todo 代替執行前方案審查。

這兩類能力不是同一件事：`write_todos` 是當前會話裡的進度清單；Plan Mode 是安全的只讀規劃階段。前者管理執行透明度，後者管理風險。

## 適合場景

- 多檔案重構。
- 修多個測試失敗。
- 遷移依賴。
- 寫一組文件。
- 接 MCP 或 GitHub Action。

## Todos 怎麼用

`write_todos` 維護完整 todo 陣列，每項有 `description` 和 `status`。狀態包括 `pending`、`in_progress`、`completed`、`cancelled`、`blocked`，同一時間只能有一個 `in_progress`。使用者可以用 `Ctrl+T` 檢視完整列表。

官方 todo 狀態只屬於當前會話，不是專案管理系統。它適合讓使用者看到 agent 現在做到了哪一步，但不能代替 GitHub issue、專案計劃文件或任務交接記錄。

## 好的 todo 應該具體

```text
读 package.json 和 tsconfig
定位 auth 相关文件
列出修改计划
只修改 login handler
跑 auth 单测
总结 diff 和风险
```

## 不好的 todo

```text
优化项目
修所有问题
让代码更好
```

## Planning 怎麼用

Plan Mode 透過 `enter_plan_mode` 進入，Gemini CLI 會切到只讀的 `PLAN` approval mode。適合先讀程式碼、理解風險、形成方案。完成方案後，`exit_plan_mode` 會提交一個 Markdown plan 給使用者正式稽核；使用者批准後才切回可執行模式。

`exit_plan_mode` 要求 plan 檔案在專案臨時 plans 目錄裡，並且檔案存在、有內容。它不是“隨便說我計劃好了”，而是把計劃變成可審閱產物。

`enter_plan_mode` 會把 approval mode 切到 `PLAN`，並限制 agent 使用只讀工具；它不適用於 YOLO 模式。`exit_plan_mode` 會把最終 Markdown plan 提交給使用者確認，使用者批准後才切回 `DEFAULT` 或 `AUTO_EDIT` 這類執行模式。

## 使用邊界

小任務不需要複雜 planning；直接執行更快。多檔案修改、高風險許可權、生產釋出、批次刪除、跨模組遷移則應該先計劃。計劃階段不要寫檔案或跑破壞性命令，除非使用者明確批准。

| 狀態 | 應該怎麼用 | 常見問題 |
| --- | --- | --- |
| `pending` | 等待執行的具體步驟 | 條目太大，無法判斷進度 |
| `in_progress` | 當前唯一正在做的步驟 | 同時多個進行中 |
| `completed` | 已完成且可驗證 | 沒跑驗證就標完成 |
| `blocked` | 需要外部輸入或環境修復 | 明明可繼續卻假裝阻塞 |
| `cancelled` | 明確不再執行 | 不說明取消原因 |

好的 todo 應該能讓旁觀者理解當前任務卡在哪一步。計劃則應該能讓使用者在執行前判斷是否批准。

## 商業專案用法

對教程站、文件批次補齊、跨目錄改版這類長任務，todo 必須覆蓋“盤點、補源、改文、驗證、提交”五個階段。每個階段完成後再更新狀態，不要最後一次性標完成。

Plan Mode 更適合高風險動作：批次刪除、公開發布、許可權調整、生產指令碼、跨儲存庫同步。計劃裡至少寫清影響檔案、命令、回復方式、斷點風險和驗收方式。沒有這些內容，使用者無法判斷是否應該批准執行。

## 驗收方式

長任務開始後檢查 todo 是否覆蓋“讀取、定位、修改、驗證、總結”五類動作。Plan Mode 結束前檢查方案是否包含影響檔案、風險、回復方式和測試命令；缺任何一項都不應進入實現。

## 接下來去哪

<Cards>
  <Card title="MCP 設定" description="規劃工具用穩後，繼續看如何接入外部 MCP server。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/35-mcp-setup" />
  <Card title="任務規劃" description="回看日常任務裡如何寫計劃、檢查 todo 和驗收。" href="/zh-Hant/docs/gemini-cli/official/01-cli-workflow/17-task-planning" />
  <Card title="Plan mode" description="高風險任務進入只讀規劃模式，再批准執行。" href="/zh-Hant/docs/gemini-cli/official/01-cli-workflow/19-plan-mode" />
</Cards>

## 官方來源

- [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)
- [Gemini CLI task planning tutorial](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/task-planning.md)
