常見開發工作流

8.1 互動模式 vs headless 模式

用法先分兩類：

gemini

gemini -p "用三點說明這個專案的架構"

git diff | gemini -p "為這個 diff 寫一段 PR 摘要，繁體中文，列風險與測試"

8.2 修 bug：先重現，再改最小範圍

修 bug 的 prompt 不要只說「幫我修」。要給錯誤訊息、重現步驟、完成條件，並要求它先找根因。

@src/ @package.json
登入後導向首頁失敗，錯誤訊息如下：
貼上錯誤訊息...

請先做根因分析和修改計畫，不要改檔。計畫要包含：
1. 你會讀哪些檔案。
2. 最可能的根因。
3. 最小修改範圍。
4. 驗收指令。

批准改檔時，一次只讓它做最小修補。修完請它跑相關測試，不能跑就說明原因。

實務上「先改一個小範圍、立刻驗收」這個循環，最順手的做法是把 @ 檔案脈絡和 ! shell 驗收接在同一段對話裡：先用 @ 指定要看的檔案定位問題，工具核准改檔後，緊接著在同一個 session 用 !npm test（或專案對應的測試指令）現場驗收，不必切出去另開一個終端機視窗。這樣做的好處是，如果測試還是紅的，Gemini 已經看得到剛才改了什麼、測試又是怎麼失敗的，可以直接接著修，不用你重新複製貼上一次錯誤訊息。

@src/auth/session.ts 修正 token 過期時沒有正確導回登入頁的問題，只改這個檔案。

!npm test -- tests/auth/session.test.ts

8.3 補測試：用失敗案例定義完成

補測試時，先讓 Gemini 找應該覆蓋的行為，再建立或修改測試。高風險功能請先要求測試失敗，再實作到綠。

@src/cart/ @tests/
請為購物車折扣邏輯補測試。先列出應覆蓋的案例，不要改檔。
我確認後，先只新增測試，不要修改正式程式碼。

8.4 文件生成：讓它讀程式，不要自由發揮

文件任務適合 headless，也適合互動模式。關鍵是要求它根據檔案內容，不確定就標註。

gemini -p "閱讀 @src/api/users.ts，產生繁體中文 API 文件。只根據檔案內容，不確定的地方標成 TODO。"

若要批次產文件，先在一兩個檔案試跑，確認輸出格式穩定，再用迴圈擴大範圍。下面這種寫法一次處理一個檔案，把結果導向同名的 Markdown，方便你事後用 git diff 或直接開資料夾逐一檢查：

for file in src/utils/*.py; do
  gemini -p "閱讀 @$file，用繁體中文產生一段 Markdown 文件摘要，只根據檔案內容，不確定的地方標成 TODO。只印出 Markdown 內容，不要加任何額外說明。" > "${file%.py}.md"
done

迴圈裡有兩個容易忽略的細節。第一，prompt 明確要求「只印出 Markdown 內容」，否則模型偶爾會在正文前後加一句「好的，以下是文件」，混進你要存檔的內容裡。第二，檔案一多，連續呼叫可能撞到 quota 或 rate limit，出現速度忽然變慢或個別請求失敗；這屬於第 12 章討論的退出碼與重試範圍，先用小批次測過行為，再放大到整個資料夾。大量自動寫檔前，也請先看第 7 章的安全設定。

8.5 解釋 codebase：先地圖，再細節

讓 Gemini 解釋陌生專案時，先要架構地圖，不要直接叫它逐檔講。你需要的是入口、資料流、測試、風險。

@README.md @package.json @src/
請用新進工程師 onboarding 角度說明：
1. 這個專案解決什麼問題。
2. 主要入口與資料流。
3. 常用開發與測試指令。
4. 哪些檔案最值得先讀。
5. 你不確定的地方。

如果專案是前後端分開兩個 repo，或是 monorepo 底下的服務彼此放在不同資料夾，單一 @ 路徑只能看到你目前所在的這個 repo，Gemini 不會自己跳出去看隔壁資料夾。這種情況可以在啟動時加上 --include-directories，把要一起分析的資料夾一次納進同一個 session：

cd ~/projects/frontend
gemini --include-directories "../backend"

啟動後，@ 一樣可以同時指定兩邊的檔案，例如 @../backend/src/routes/users.ts 對照 @src/api/users.ts，請它一次講清楚前端呼叫的介面和後端實際回傳的欄位是否一致。這比開兩個瀏覽器分頁自己比對，或把兩份程式碼暫時複製到同一個資料夾，乾淨也不容易漏看。

8.6 PR review 準備：從 diff 產生摘要與風險

PR 前可以請 Gemini 幫你整理 diff，但不要讓它取代 review。它適合產摘要、列測試、找明顯風險。

git diff --stat
git diff | gemini -p "請用繁體中文整理這個 diff：摘要、主要檔案、可能風險、建議 reviewer 特別看的地方、已跑/應跑測試。"

若 diff 可能含 secret 或客戶資料，不要 pipe 給 AI。先清理或改用本地人工 review。

如果你發現自己每次送 PR 前都在重打類似的整理 diff 指令，值得把它變成一個固定動作，而不是每次現想 prompt。最簡單的做法是在 shell 設定檔（~/.zshrc 或 ~/.bashrc）裡包一個小 function，用 headless 一行完成「讀 staged diff、生成 commit 訊息」：

function gcommit() {
  diff=$(git diff --staged)
  if [ -z "$diff" ]; then
    echo "沒有已 staged 的變更可以提交。"
    return 1
  fi
  msg=$(echo "$diff" | gemini -p "根據這份 diff 寫一則簡潔的 Conventional Commit 訊息，繁體中文說明，只輸出訊息本身。")
  git commit -m "$msg"
}

這個 function 完全在終端機層級運作，不需要開 Gemini CLI 的互動畫面。想送 commit 就打 gcommit，訊息會先印出來，你也能事後用 git log -1 檢查它寫了什麼；不滿意的話，git commit --amend 照樣可以手動改。如果團隊想要更正式、能進版控分享給所有人的版本，可以把同一個 prompt 包成第 10 章介紹的 /git:commit 自訂指令，兩者思路一樣，差別只在一個是你個人 shell 的小工具，一個是團隊共用、可審查的專案資產。

8.7 log triage：讓它分類，不要直接下結論

log 分析很適合 headless。給它時間範圍、系統背景、你想要的輸出格式，並要求保留證據行。

cat error.log | gemini -p "請分析這份 log。輸出：最可能根因、佐證、受影響模組、下一步排查命令。不要編造 log 中不存在的資訊。"

正式事故處理時，log 可能含個資、token、內網 host。先遮蔽敏感欄位，再交給 CLI。

8.8 資料與報告生成：固定格式最重要

請 Gemini 產報告時，最常失敗的是格式漂移。先定欄位、排序、資料來源與禁止推測。

@metrics.csv
請根據這份 CSV 產生週報，格式固定為：
1. 三個重點數字。
2. 異常變化與可能原因。
3. 下週建議行動。
4. 不足資料。

只能根據 CSV 內容，不要自行補數字。

如果要把輸出寫入檔案，先讓它印到 stdout 或互動畫面，確認格式後再自動化。

8.9 研究任務：要求來源與引用

Gemini CLI 有 web search/fetch 工具時，可以做研究型任務。請明確要求官方來源、日期、引用連結與不確定性，不要只要一篇順口的摘要。

請研究 Gemini CLI checkpointing 的最新官方文件。
要求：
1. 優先使用官方 docs 與 GitHub repo。
2. 每個重要結論附來源連結。
3. 標出文件日期或版本線索。
4. 如果文件互相矛盾，請列出矛盾點，不要自行裁決。

這類研究能力背後通常對應兩個獨立工具：一個負責搜尋、跨多個來源整理結果（一般稱為 google_web_search 這類 web search 工具），另一個負責把單一網址的完整內容整篇抓回來（web_fetch 工具）。實務上最穩的順序是「先搜尋、再抓詳細內容、最後才動手寫程式或下結論」：先讓它搜尋找出候選來源，挑出看起來最權威的一兩篇，再明確要求把該網址整篇抓回來讀完，不要只憑搜尋結果的摘要片段就下判斷。這個順序特別適合查訓練資料涵蓋不到的新版 API、套件變更或不常見的錯誤訊息——純靠模型記憶用猜的，很容易講出聽起來合理但版本已經過時的答案。

如果你沒有明確要求它搜尋，模型在某些情況下會傾向直接憑訓練時記得的知識回答，尤其當問題聽起來很眼熟的時候。遇到你懷疑答案可能已經過時（例如某個套件的最新版行為、官方剛調整過的設定欄位），在 prompt 裡直接寫明「請先搜尋官方文件，不要只憑你原本知道的資訊回答」，會比放著讓它自由判斷更可靠。

涉及法律、醫療、金融、安全或採購決策時，不要只靠模型摘要。把來源打開自己看，必要時找專業審核。

8.10 用 shell 整合處理背景任務

第 4 章介紹過 !command 可以在互動模式裡直接跑一次性的 shell 指令。日常工作流裡還有一種更常見的情境：你想先在背景啟動一個長駐服務（例如開發伺服器），然後讓 Gemini 邊看這個服務的即時輸出邊幫你除錯或驗證改動，而不是每次都手動切換視窗、複製貼上一段 log。

單獨打一個 !（後面不接指令）會把輸入切換成「持續 shell 模式」：接下來你打的每一行都直接送進終端機執行，直到按 Esc 或輸入 exit 離開，才會回到跟 Gemini 對話的狀態。這比每次都在指令前面加驚嘆號方便，適合你需要連續下好幾個 shell 指令的時候。

真正要管理長駐服務，可以用 /shells 打開背景行程儀表板，列出目前由這個 session 管理的行程，能在裡面看即時輸出，行程卡住或跑飛了也能直接終止，不必自己回頭查 PID。

/shells

長駐指令要怎麼啟動才會被 /shells 抓到——是工具自動偵測，還是你得自己在指令後面背景執行，這部分版本間可能有差異，請以你當下的實際行為與 /help 為準。概念上只要記得：長時間跑的服務不必再手動開第二個終端機視窗盯著，先問 /shells。

8.11 跨日跨任務接續：session 續接與回溯

前面幾節的任務大多假設你一次坐下來就能做完。實際除錯常常沒這麼順利：查到一半要去開會，或是一個問題拖了兩三天才抓到根因。第 6 章提過 todo 清單是 session-scoped、不會跨對話保留；這種時候真正需要的不是重講一次前情提要，而是把上次的對話原封不動接回來。

最直接的方式是啟動時帶 -r 或 --resume，接續最近一次的對話：

gemini -r
gemini --resume

如果你同時在追好幾條任務，記不清楚哪個是哪個，互動式的 /resume 會列出所有歷史 session，通常包含時間、第一則訊息內容和對話輪數，方便你用內容認出正確的那一個；清單裡按 x 可以刪掉不要的紀錄。要在腳本或其他地方管理，也可以用 gemini --list-sessions 列出所有 session ID，配合 gemini --delete-session 加上該 ID 永久刪除。

/resume

如果不是「想接續」而是「剛才那步走錯了，想倒回去」，可以用 /rewind，或連按兩下 Esc 觸發。它會讓你選擇只回溯對話內容、只還原程式碼，或兩者一起復原到你選的時間點。這跟第 7 章介紹的 checkpointing／/restore 概念上有點像，都是「讓你反悔」的機制，但操作方式不同：checkpointing 是列出個別的檔案寫入快照，/rewind 則是連對話一起往回走。兩者是否共用同一套底層機制、實際在你的版本上如何運作，請以當下 /help 與官方文件為準。

這裡的 session 續接，解決的是「同一個任務，隔了一段時間回來接著做」；如果是「好幾個任務要同時平行進行」，那是第 14 章 git worktree 處理的問題。兩者不衝突，甚至常常一起用：每個 worktree 一個獨立資料夾與 branch，資料夾裡的 Gemini session 各自累積自己的歷史，需要接續哪一條，就在對應的資料夾用 -r 或 /resume 接回去。

8.12 進階組合：把常見任務包成三段式規格開發

這章前面示範的都是單次任務：修一個 bug、補一批測試、產一份文件。當任務大到「這是一個完整功能」的規模，單次 prompt 常常撐不住，規劃、實作、驗收會混在一起讓人失去掌控感。社群裡有一套常見的組合打法，把本章與前面幾章已經教過的元件串起來，分成三個階段，各自有明確產出物。

三個階段各自可以包成第 10 章介紹的自訂指令，例如 /techspec、/create-plan、/build，讓整個流程變成三個固定指令，而不是每次重打三段長 prompt。這套三段式本身不是 Gemini CLI 的內建功能，是社群摸索出來的用法🌐社群，重點在那份「帶 checkbox 的計畫檔」這個中繼產出：它讓你隨時看得到做到哪裡，任務跨了好幾天、或換一個 session 接續（見上一節），也不必重新回想進度到哪。你不需要照抄這三個指令的名字，理解「規格 → 帶 checkbox 的計畫 → 逐步實作」這個節奏，自己按專案習慣命名即可。

本章小結

Gemini CLI 的日常價值在於把重複但需要判斷的工作變快：修 bug 前先找根因、補測試先定案例、產文件先讀程式、PR 前先整理 diff、log 先分類、研究要附來源。互動模式用於高風險與多輪任務；headless 用於單次、可管線化、輸出可檢查的任務。除了單次任務，日常工作流也少不了背景服務（! 與 /shells）、跨日接續（session 續接與 /rewind），以及把重複流程升級成可重用元件（shell function、自訂指令、三段式規格開發）——這些技巧不會讓你少寫 prompt，但會讓同一套判斷力重複被用到，而不是每次從零想起。

動手試試

1. 選一個小任務，用互動模式先請 Gemini 產計畫，確認後只執行一步。
2. 把一份短 log 或 README pipe 給 gemini -p，要求固定格式摘要。
3. 用 git diff | gemini -p 產一份 PR 摘要，再人工檢查是否漏掉風險。
4. 做一個研究 prompt，要求官方來源與引用連結，並試著先要求搜尋、再要求抓完整內容。
5. 在背景啟動一個會持續輸出的指令，用 /shells 確認它還活著，再請 Gemini 針對它的輸出做一件事。
6. 結束一段對話前記下大概進度，關掉終端機，再用 gemini -r 或 /resume 接回同一個 session，確認它還記得剛才在做什麼。
7. 把 8.6 節的 gcommit shell function 存進你的 shell 設定檔，對一個有 staged 變更的練習 repo 跑一次，檢查它寫出來的 commit 訊息是否合理。