Gemini CLI 怎麼完成一個任務

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
任務管線	pipeline	從目標到驗證交付的流程。
上下文獲取	context	從專案和 GEMINI.md 取資訊。
驗證閉環	verify	改完看 diff、跑測試。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你把一個任務拆成 Gemini CLI 能穩妥跑完的步驟。

你是 Gemini CLI 任務管線規劃顧問。

【角色】
Gemini CLI 任務管線規劃顧問，按最小夠用、安全優先的原則給可落地方案。

【輸入】
- 要做的任務：___
- 目標（怎樣算成功）：___
- 涉及檔案 / 範圍：___
- 驗證方式：___

【工作流程】
1. 把任務收到可獨立驗證的範圍
2. 給該有的上下文和邊界
3. 讓它規劃執行、保護工作區
4. 設計對應目標的驗證

【輸出規範】
▌一、任務範圍
▌二、上下文與邊界
▌三、執行 + 保護
▌四、驗證

【硬約束】
- 任務太大先拆
- 不可逆操作人工確認
- 驗證對應目標，不只說跑通了
- 不要替我臆測情況或編造不存在的能力，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述
- 給的步驟要讓我能照著一步步做下去，不要跳過關鍵細節或假設我已經懂某個前提，必要時先幫我補

Gemini CLI 完成任務不是"一次回答結束"。更準確的模型是：它在一個 agent loop（代理迴圈：邊推理邊呼叫工具的迴圈）裡不斷讀取上下文、選擇工具、觀察結果，再決定下一步。

讀懂 agent loop 之後，你就能判斷什麼時候該讓 Gemini CLI 只讀、什麼時候該讓它規劃、什麼時候才允許它寫檔案或跑命令。

任務迴圈

flowchart LR
    A["使用者目標"] --> B["讀取上下文"]
    B --> C["形成計劃"]
    C --> D["選擇工具"]
    D --> E["執行或請求確認"]
    E --> F["觀察結果"]
    F --> G{"目標完成?"}
    G -- "否" --> C
    G -- "是" --> H["總結和交付"]

這個迴圈裡，模型不是唯一變數。工具許可權、上下文質量、專案設定和你的確認策略同樣重要。

上下文來自哪裡

Gemini CLI 可以從這些地方理解任務：

目前對話。
目前工作目錄。
GEMINI.md。
settings.json。
memory。
檔案系統工具讀取到的檔案。
MCP、extensions 或 web 工具返回的外部資訊。

上下文越雜，越需要明確“以哪個檔案為準”。否則 agent 容易把臨時討論、舊文件和真實原始碼混在一起。

工具呼叫意味著什麼

工具呼叫是 Gemini CLI 和普通聊天的核心差異。模型可以不只是“建議你執行命令”，而是請求執行讀檔案、寫檔案、shell、web fetch、MCP 等工具。

這帶來兩個結果：

它可以完成真實工作。
它也可能造成真實副作用。

所以要先區分只讀工具、寫入工具和外部副作用工具。

三類任務模式

模式	Gemini CLI 應該怎麼做	適合場景
只讀解釋	讀取檔案、梳理結構、指出風險，不寫入	新儲存庫、報錯定位前、併發協作
計劃優先	先給檔案範圍、步驟、驗證和停止條件	多檔案改動、遷移、釋出、安全任務
執行驗證	小批次修改、看 diff、跑檢查、總結影響	邊界清楚、可回退、能驗證的任務

這三種模式不要混用。你說“先分析”，它就不應該改檔案；你說“直接執行”，也要先確認任務邊界已經足夠清楚。

什麼時候讓它規劃

複雜任務先規劃，尤其是：

要改多個檔案。
要跑遷移或釋出。
涉及金鑰、賬號、賬單、遠端伺服器。
目前儲存庫有併發編輯。
你還不確定目錄職責。

規劃階段的輸出應該包括檔案範圍、驗證方式、風險邊界和回復點。

什麼時候讓它執行

執行適合邊界清楚、可驗證、失敗可恢復的任務：

補一頁文件。
改一個小 bug。
執行只讀檢查。
生成測試草案。
根據官方文件更新設定。

如果一個任務無法說明驗收標準，就不應該直接執行。

觀察結果為什麼重要

Agent loop 的關鍵不只是“會呼叫工具”，而是每次呼叫後會根據結果調整下一步。比如測試失敗時，它不應該繼續大改，而應該讀失敗資訊、縮小範圍、修最小問題，再重新驗證。

一個健康的迴圈通常長這樣：

提出假設 -> 讀取證據 -> 最小改動 -> 驗證 -> 根據結果繼續或停止

如果它開始在沒有證據的情況下連續改檔案，說明任務邊界或許可權策略需要收緊。

判斷迴圈是否健康

健康的 agent loop 會先拿證據，再做小動作，再驗證。異常迴圈通常有三個訊號：不讀檔案就下結論，測試失敗後連續大改，沒有說明下一步風險。遇到這三種情況，應該收回寫許可權，回到只讀分析或 Plan mode。

理解這點後，你就能把“模型回答不好”拆成具體問題：上下文不足、工具許可權過寬、計劃不清、驗證缺失，還是模型能力不夠。

觀察結果怎麼用

每次工具呼叫後，都應該把輸出變成下一步依據。read_file 的結果決定是否需要繼續讀上下文；shell 的 exit code 決定是否繼續修改；web fetch 的來源決定事實是否可引用；MCP resource 的內容決定是否允許後續寫工具。

如果 agent 忽略工具輸出，繼續按原計劃執行，說明迴圈已經失真。此時應要求它重新總結證據，再決定下一步，而不是繼續追加新需求。

這也是商業級教學必須寫驗證的原因：沒有觀察和驗證，agent loop 只是更長的聊天。

官方資料

官方 docs index：docs/index.md
Plan mode 🔬（計劃模式）：docs/cli/plan-mode.md
Checkpointing：docs/cli/checkpointing.md
Tools reference：docs/reference/tools.md

最小可控提示

可以用一句話把迴圈拉回可控狀態：

先說明你已經讀取了哪些證據，再給下一步計劃，不要在沒有證據時修改檔案。

這句話能逼 agent 把“觀察結果”顯式說出來。它答不上來，就說明還沒到執行階段。

如果它只能給結論，不能列出檔案路徑、命令輸出或官方來源，就先讓它回到只讀證據採集。真實專案裡，證據鏈比回答速度更重要。