Plan mode、Checkpoint、Headless

你是 Gemini CLI 模式與自動化顧問。

【角色】
Gemini CLI 模式與自動化顧問，按最小夠用、安全優先的原則給可落地方案。

【輸入】
- 任務性質（複雜規劃 / 需可回退 / 自動化）：___
- 目標和約束：___
- 執行環境：___
- 風險偏好：___

【工作流程】
1. 判斷該用 Plan / Checkpoint / Headless 哪個
2. 說明怎麼用
3. 結合 Checkpoint 做可回退
4. 給安全和驗證

【輸出規範】
▌一、該用哪個
▌二、使用方式
▌三、Checkpoint 可回退
▌四、安全 + 驗證

【硬約束】
- 複雜任務先 Plan
- 用 Checkpoint 保留回退點
- Headless 任務設計成不需越界
- 不要替我臆測情況或編造不存在的能力，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法

Plan mode（計劃模式 🔬，Gemini CLI 目前為實驗功能）、checkpoint（檢查點）、headless mode（無頭 / 指令碼模式）分別解決三個問題：先想清楚、改壞能回退、自動化能呼叫。

Plan mode

Plan mode 適合複雜任務。它讓 agent 先產出計劃，再進入執行。

適合：

• 多檔案改動。
• 需要理解架構。
• 要接外部系統。
• 有併發修改。
• 涉及釋出、部署、遷移。

一個好計劃應該包含：

• 目標。
• 檔案範圍。
• 分階段動作。
• 驗證命令。
• 風險和停止條件。

Checkpoint

Checkpoint 解決“改了一半發現方向錯了”的問題。它讓你在關鍵節點保留回退點。

建議在這些節點建 checkpoint：

• 大改前。
• 自動化生成檔案前。
• 跑遷移指令碼前。
• 進入不熟悉程式碼路徑前。
• 批次替換前。

Headless mode

Headless mode 適合指令碼和 CI：

git diff | gemini -p "Summarize this change"
gemini --output-format json -p "Classify this issue"

它適合“一次輸入、一次輸出”的任務，不適合需要複雜互動確認的高風險任務。

三者怎麼組合

人工複雜任務    Plan mode -> 分批執行 -> checkpoint -> 驗證
批次低風險任務  headless -> JSON 輸出 -> 指令碼校驗 -> 人工抽查
高風險任務      Plan mode -> 人工確認 -> checkpoint -> 最小寫入 -> 驗證

實用原則

如果任務可能產生不可逆影響，就不要 headless 自動跑。先讓 Gemini CLI 輸出計劃和風險，再由人決定是否執行。

典型錯誤

• 把 Plan mode 當成“慢一點的聊天”，但沒有要求影響檔案、驗證命令和停止條件。
• 把 checkpoint 當成 git 分支，結果長期修改沒有 commit 記錄。
• 把 headless 用在需要多輪確認的任務，例如批次刪除、釋出、部署。
• 讓 headless 直接寫正式檔案，沒有臨時檔案、JSON 校驗和失敗分支。

一個可靠流程

複雜改動先進入 Plan mode，只讀掃描程式碼和設定。使用者確認後，只執行第一小步，並在關鍵改動前建立 checkpoint。每一步跑最小驗證，失敗就停下來回到計劃，而不是繼續擴大修改。

自動化場景則相反：prompt 固定、輸入可控、輸出結構化。headless 更適合分類、摘要、生成草稿，不適合讓模型在 CI 裡自主修復生產問題。

驗收標準

人工任務看四項：是否有計劃，是否有回退點，是否有驗證命令，是否有人確認高風險動作。指令碼任務看四項：退出碼、JSON 解析、空輸出處理、配額失敗處理。

最小落地模板

可以把複雜任務拆成三句話：

先只讀分析並給計劃，不要改檔案。
我確認計劃後，只執行第一批檔案，並在改前說明驗證方式。
每批結束後輸出 diff 範圍、檢查結果和下一批是否繼續。

這不是模板化提示詞，而是控制權設計：先讓 Gemini CLI 暴露計劃，再讓它小步執行，最後用驗證結果決定是否繼續。

何時不用

簡單單檔案解釋不需要 Plan mode；已經有清晰 Git 分支和小 diff 時，checkpoint 不是必須；需要人工多輪確認的任務不要 headless。控制手段要匹配風險，過度上工具會增加排障成本。

商業教學裡要寫出“什麼時候不用”，否則讀者會把所有功能都疊上，反而不知道問題出在哪裡。

組合示例

真實任務可以這樣組合：先 Plan mode 只讀產出方案；使用者批准後做第一批小改；改前建 checkpoint；改後跑最小驗證；需要批次重複時，再把穩定部分改成 headless 指令碼。順序反過來就容易失控。

最重要的是每一步都能停。不能停的自動化，不適合處理真實專案。

不可逆動作不要交給 headless 自主執行，包括刪除遠端資源、釋出正式版本、改生產設定和寫入賬號後臺。即使輸出是 JSON，也不代表這個動作已經可自動批准。

Checkpoint、Plan 和 headless 都是控制權工具。它們的價值不是顯得專業，而是讓人知道什麼時候批准、什麼時候回退、什麼時候停止。

官方資料

• Plan mode 🔬：docs/cli/plan-mode.md
• Checkpointing：docs/cli/checkpointing.md
• Headless mode：docs/cli/headless.md
• Rewind（回放）：docs/cli/rewind.md

下一篇