---
title: "真實專案貫穿實戰"
description: "用一個真實專案流程串起 Gemini CLI：只讀掃描、上下文沉澱、計劃、修改、驗證、checkpoint、headless 和 GitHub Action。"
verifiedAt: "2026-05-09"
---

這一篇把前面的概念串成一個真實專案流程。目標不是展示炫技，而是形成一套可重複、可驗證、低干擾的 Gemini CLI 工作方式。

> [!IMPORTANT]
> 真實專案裡，質量來自流程約束：只讀進入、明確歸屬、分批寫入、每批驗證、不中斷別人改動。

## 場景

假設你要給一個文件站補一個新產品欄目。儲存庫裡還有其他 agent 在改別的欄目，所以你必須互不干擾。

## 第一步：只讀進入專案

先進入專案目錄，再執行 `gemini`。

第一條 prompt：

`請只讀掃描當前專案，不要修改檔案，不要執行寫入命令。請說明專案技術堆疊、文件目錄、導航機制、驗證命令，以及我應該只改哪些路徑。`

輸出裡必須能看到：

- 專案技術堆疊。
- 內容目錄。
- 導航檔案。
- 檢查命令。
- 不應觸碰的併發改動區域。

## 第二步：確認上下文真相源

讓 Gemini CLI 查：

`請讀取當前目錄和父目錄的規則檔案，確認本次任務應遵守哪些 CLAUDE.md、AGENTS.md 或 GEMINI.md 規則。`

如果專案還沒有 `GEMINI.md`，可以先生成一個小範圍專案規則草案，但不要把它寫入儲存庫，除非團隊確認。

## 第三步：寫計劃，不直接改

`我要新增 Gemini CLI 教程欄目。請先給執行計劃：目錄結構、頁面清單、官方來源、每批修改檔案、驗證方式和停止條件。不要改檔案。`

計劃裡應該明確：

計劃裡要明確只改 `content/docs/gemini-cli/`，不碰其他產品欄目；每批前檢查 `git status`，每批後跑 `types:check` 或至少跑 MDX 檢查。

## 第四步：分批寫入

按批次推進：

1. 建立根頁面和導航。
2. 寫官方教程中文版。
3. 寫從原理到實戰。
4. 補美化元件和交叉連結。
5. 跑驗證。

每批之間都檢查：

`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 阻止跨欄目誤改。

## 完整工作流

```text
官方来源采集
  -> 内容蓝图
  -> 根页面和导航
  -> 官方教程中文版
  -> 从原理到实战
  -> 美化和交叉链接
  -> 类型检查和构建
  -> 发布前复检
```

## 結束標準

一個真實專案任務不是“檔案寫完”就結束。結束標準應該是：

- 頁面能被導航發現。
- 連結不指向不存在的 slug。
- 型別檢查透過。
- 構建透過。
- 併發改動未被覆蓋。
- 官方來源和驗證日期可追溯。

到這裡，Gemini CLI 欄目就從“工具介紹”變成了一套可維護的教程工作流。

## 交付摘要模板

最後交付時至少說清：

- 修改了哪些路徑。
- 每批驗證跑了什麼。
- 哪些官方來源已複核。
- 是否有併發改動被避開。
- 哪些構建或部署動作還沒做。

這能讓下一位 agent 或人工編輯直接接手，而不是重新猜當前進度。

## 覆盤標準

真實專案做完後，要覆盤三件事：官方來源是否還需要定期重新整理，驗證命令是否覆蓋內容和構建，是否留下了可複用的 Skill、command 或 checklist。只有把這些沉澱下來，下一次新增欄目才會更快，而不是重新靠口頭經驗。

覆盤還要看併發協作是否順暢：有沒有覆蓋別人檔案，有沒有全域性驗證失敗，有沒有因為導航或斷點遺漏導致上線後頁面不可用。真實專案的質量，最終體現在這些細節裡。

如果這些問題反覆出現，就應該把流程沉澱成 checklist 或 command，而不是繼續靠記憶提醒。

這份 checklist 應該進入儲存庫文件或團隊規則，而不是隻留在一次會話總結裡。能被後來者直接複用，才算真實專案流程完成。

## 官方資料

- 檔案管理教程：[docs/cli/tutorials/file-management.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/file-management.md)
- 自動化教程：[docs/cli/tutorials/automation.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/automation.md)
- 任務規劃（todos）：[docs/cli/tutorials/task-planning.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/task-planning.md)
- 會話管理：[docs/cli/tutorials/session-management.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/session-management.md)
- 上下文與記憶：[docs/cli/tutorials/memory-management.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/memory-management.md)

## 回到入口

<Cards>
  <Card title="Gemini CLI 從原理到實戰" description="回到本系列入口，複查 12 篇的整體學習路徑。" href="/zh-Hant/docs/gemini-cli/understanding" />
  <Card title="官方教程中文版" description="需要繼續查命令、配置、MCP、模型、安全和自動化細節。" href="/zh-Hant/docs/gemini-cli/official" />
  <Card title="故障排查與參考" description="真實專案執行中遇到認證、PATH、sandbox、版本和 package 問題時進入。" href="/zh-Hant/docs/gemini-cli/official/08-troubleshooting-reference" />
</Cards>
