---
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="/docs/gemini-cli/official/01-cli-workflow/18-checkpointing-rewind" />
  <Card title="Todos / Planning 工具" description="继续看官方工具层面的 todos、planning 和任务状态语义。" href="/docs/gemini-cli/official/03-tools-mcp/34-todos-planning-tools" />
  <Card title="Plan mode" description="高风险任务先进入只读规划模式，再批准执行。" href="/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)
