真實專案貫穿實戰
用一個真實專案流程串起 Gemini CLI：只讀掃描、上下文沉澱、計劃、修改、驗證、checkpoint、headless 和 GitHub Action。
這一篇把前面的概念串成一個真實專案流程。目標不是展示炫技，而是形成一套可重複、可驗證、低干擾的 Gemini CLI 工作方式。
真實專案裡，質量來自流程約束：只讀進入、明確歸屬、分批寫入、每批驗證、不中斷別人改動。
場景
假設你要給一個文件站補一個新產品欄目。儲存庫裡還有其他 agent 在改別的欄目，所以你必須互不干擾。
第一步：只讀進入專案
先進入專案目錄，再執行 gemini。
第一條 prompt：
請只讀掃描當前專案，不要修改檔案，不要執行寫入命令。請說明專案技術堆疊、文件目錄、導航機制、驗證命令，以及我應該只改哪些路徑。
輸出裡必須能看到：
- 專案技術堆疊。
- 內容目錄。
- 導航檔案。
- 檢查命令。
- 不應觸碰的併發改動區域。
第二步：確認上下文真相源
讓 Gemini CLI 查：
請讀取當前目錄和父目錄的規則檔案，確認本次任務應遵守哪些 CLAUDE.md、AGENTS.md 或 GEMINI.md 規則。
如果專案還沒有 GEMINI.md，可以先生成一個小範圍專案規則草案，但不要把它寫入儲存庫，除非團隊確認。
第三步：寫計劃，不直接改
我要新增 Gemini CLI 教程欄目。請先給執行計劃：目錄結構、頁面清單、官方來源、每批修改檔案、驗證方式和停止條件。不要改檔案。
計劃裡應該明確：
計劃裡要明確只改 content/docs/gemini-cli/，不碰其他產品欄目；每批前檢查 git status，每批後跑 types:check 或至少跑 MDX 檢查。
第四步：分批寫入
按批次推進：
- 建立根頁面和導航。
- 寫官方教程中文版。
- 寫從原理到實戰。
- 補美化元件和交叉連結。
- 跑驗證。
每批之間都檢查：
git status --short content/docs/gemini-cli
如果發現別人也改了 content/docs/gemini-cli/，暫停合併，不要覆蓋。
併發協作表
| 情況 | Gemini CLI 應該怎麼做 |
|---|---|
| 別人在改其他欄目 | 繼續，只檢查自己目錄和全域性驗證 |
| 別人在改同一欄目不同檔案 | 先確認檔案歸屬，批次更小 |
| 別人在改同一檔案 | 停止寫入，等待人工協調 |
| 全域性配置或導航被別人改 | 先讀 diff，再決定是否需要同步 |
| 測試失敗來自無關檔案 | 記錄失敗，不順手修別人改動 |
第五步：驗證
先做目標目錄檢查：
rg -n "[[:blank:]]+$" content/docs/gemini-cli
再跑專案檢查：
建議按順序跑 pnpm run types:check、pnpm run audit:content、pnpm run audit:quality、pnpm run build。
如果失敗，先判斷是不是本次目錄引起。併發儲存庫裡不要順手修別人改動造成的問題。
第六步：自動化沉澱
當這套流程跑通後，再考慮：
- 用 headless mode 定期對比官方 docs 變更。
- 用 GitHub Action 給 PR 自動檢查文件導航。
- 用 Skill 固化“教程欄目新增流程”。
- 用 hooks 阻止跨欄目誤改。
完整工作流
官方来源采集
-> 内容蓝图
-> 根页面和导航
-> 官方教程中文版
-> 从原理到实战
-> 美化和交叉链接
-> 类型检查和构建
-> 发布前复检結束標準
一個真實專案任務不是“檔案寫完”就結束。結束標準應該是：
- 頁面能被導航發現。
- 連結不指向不存在的 slug。
- 型別檢查透過。
- 構建透過。
- 併發改動未被覆蓋。
- 官方來源和驗證日期可追溯。
到這裡，Gemini CLI 欄目就從“工具介紹”變成了一套可維護的教程工作流。
交付摘要模板
最後交付時至少說清：
- 修改了哪些路徑。
- 每批驗證跑了什麼。
- 哪些官方來源已複核。
- 是否有併發改動被避開。
- 哪些構建或部署動作還沒做。
這能讓下一位 agent 或人工編輯直接接手，而不是重新猜當前進度。
覆盤標準
真實專案做完後，要覆盤三件事：官方來源是否還需要定期重新整理，驗證命令是否覆蓋內容和構建，是否留下了可複用的 Skill、command 或 checklist。只有把這些沉澱下來，下一次新增欄目才會更快，而不是重新靠口頭經驗。
覆盤還要看併發協作是否順暢：有沒有覆蓋別人檔案，有沒有全域性驗證失敗，有沒有因為導航或斷點遺漏導致上線後頁面不可用。真實專案的質量，最終體現在這些細節裡。
如果這些問題反覆出現，就應該把流程沉澱成 checklist 或 command，而不是繼續靠記憶提醒。
這份 checklist 應該進入儲存庫文件或團隊規則，而不是隻留在一次會話總結裡。能被後來者直接複用，才算真實專案流程完成。
官方資料
- 檔案管理教程：docs/cli/tutorials/file-management.md
- 自動化教程：docs/cli/tutorials/automation.md
- 任務規劃（todos）：docs/cli/tutorials/task-planning.md
- 會話管理：docs/cli/tutorials/session-management.md
- 上下文與記憶：docs/cli/tutorials/memory-management.md