任务规划
Gemini CLI 任务规划：todos、planning 工具、复杂任务拆分、执行前计划、执行中检查和完成标准。
Gemini CLI 的任务规划能力适合处理多步骤任务。官方文档把 todos / planning 作为工具能力和 tutorial 主题列出。
复杂任务先计划：跨文件修改、重构、迁移、测试修复、CI 自动化，都应该先让 Gemini CLI 列计划，再进入执行。
什么时候需要计划
- 需要改多个文件。
- 需要先读项目结构。
- 需要跑测试并根据结果迭代。
- 涉及数据库、构建、部署、权限。
- 你不确定它会改哪里。
推荐 prompt
第一句先限定边界：先不要修改文件。请先阅读相关代码，列出执行计划、会影响哪些文件、需要跑哪些验证。
确认计划后再说：
执行时再缩小范围：按计划执行第一步，只改一个文件，改完展示 diff。
更完整的版本可以直接要求它输出边界：
先不要修改文件。请只读分析这个问题，输出：
1. 你需要检查哪些文件；
2. 你预计会修改哪些文件；
3. 哪些文件明确不会碰；
4. 每一步的验证命令；
5. 失败时停止条件；
6. 需要我确认的风险点。这类 prompt 的价值不是形式感，而是把 agent 的行动范围提前暴露出来。计划越具体，后续 diff 越容易审核。
一个稳定任务循环
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 总结已改文件、未覆盖风险和实际跑过的验证，不接受只说“完成了”。
接下来去哪
Checkpoint 与 rewind
计划进入执行前，继续看如何给文件修改增加恢复点。
Todos / Planning 工具
继续看官方工具层面的 todos、planning 和任务状态语义。
Plan mode
高风险任务先进入只读规划模式，再批准执行。