---
title: "GEMINI.md、記憶和專案上下文"
description: "用 GEMINI.md、settings.json、memory 和 .geminiignore 管理 Gemini CLI 的專案上下文。"
verifiedAt: "2026-05-09"
---

Gemini CLI 能不能穩定處理專案，關鍵不在 prompt 寫多長，而在專案上下文是否可重複。`GEMINI.md` 就是把一次性口頭說明沉澱成專案級規則的核心入口。

> [!IMPORTANT]
> 上下文檔案不是越多越好。真正有價值的是：真相源清楚、層級清楚、驗證命令清楚、禁止事項清楚。

> [!TIP]
> **第一次寫 `GEMINI.md` 不要從空白開始**：直接在專案根目錄跑 `/init`，Gemini CLI 會掃描專案結構、入口檔案、檢查命令，自動生成一份初稿。你只需補"禁止觸碰的檔案 / 提交規則 / 團隊協作邊界"這些人類才知道的部分，比從零寫省一半時間。

## GEMINI.md 應該寫什麼

`GEMINI.md` 適合寫穩定規則：

- 專案用途。
- 技術堆疊。
- 目錄職責。
- 常用檢查命令。
- 禁止觸碰的檔案。
- 提交、測試、釋出規則。
- 團隊協作邊界。

不適合寫：

- 臨時任務。
- 過期待辦事項。
- 金鑰。
- 大段原始碼解釋。
- 和真實程式碼不一致的歷史說明。

## settings.json 管什麼

`settings.json` 管 CLI 行為和工具配置，例如模型、MCP、hooks、sandbox、信任目錄、主題等。它更像執行配置，不是專案說明書。

可以這樣分：

```text
GEMINI.md       给 agent 读的项目规则
settings.json   给 CLI 执行的运行配置
.geminiignore   告诉 agent 哪些内容不应纳入上下文
memory          长期可复用偏好和经验
```

## .geminiignore 的價值

專案裡總有不該被讀入上下文的內容：

- 依賴目錄。
- 構建產物。
- 大檔案。
- 金鑰和私有資料。
- 自動生成檔案。

`.geminiignore` 可以減少噪音，也能降低敏感資訊被誤讀的風險。

## 好的上下文長什麼樣

好的上下文不是“大而全”，而是讓 agent 快速判斷：

- 這是什麼專案。
- 哪些檔案是真相源。
- 改動邊界在哪裡。
- 怎麼驗證。
- 哪些操作必須先確認。

## 多層上下文怎麼放

最穩的結構是三層：

- 全域性 `~/.gemini/GEMINI.md`：跨專案偏好，例如回答風格、預設驗證習慣。
- 專案根 `GEMINI.md`：專案結構、執行命令、編碼規範、禁止事項。
- 子目錄 `GEMINI.md`：只對某個模組成立的規則，例如 `packages/api/` 的資料庫約束。

不要把所有規則都寫到全域性。全域性規則太重，會汙染每個專案；子目錄規則太少，又會讓 agent 在區域性修改時缺少邊界。

## 排錯上下文

如果 Gemini CLI 沒遵守規則，先查三件事：

1. 當前會話是否過載了上下文。
2. `/memory show` 裡是否真的出現了那條規則。
3. 是否有更近層級的規則覆蓋了根規則。

改了 `GEMINI.md` 後要執行 `/memory reload` 或重啟會話。不要假設正在執行的 session 會自動感知你剛寫入的規則。

## 常見壞味道

| 壞味道 | 風險 | 修法 |
| --- | --- | --- |
| 全域性規則寫滿專案細節 | 汙染所有儲存庫 | 下沉到專案或子目錄 `GEMINI.md` |
| 專案規則沒有驗證命令 | agent 改完不知道怎麼收尾 | 寫清 build/test/typecheck/lint |
| ignore 只排依賴不排金鑰 | 可能誤讀私有資料 | 明確排除 secret、dump、artifact |
| memory 記錄臨時 bug | 未來任務被舊事實汙染 | 臨時資訊留在任務記錄，不進 memory |
| 多層規則互相矛盾 | agent 選擇困難 | 就近層級只寫本目錄真實約束 |

## 一個最小 GEMINI.md 模板

```md
# 项目说明

这是一个 Next.js 文档站。

## 工作规则

- 修改内容前先读相邻 meta.json。
- 新增页面必须更新导航。
- 不要修改其他产品栏目。
- 验证使用 pnpm run types:check。

## 目录

- content/docs/：文档内容。
- app/：Next.js 页面和布局。
- lib/：站点逻辑。
```

## 驗收標準

讓 Gemini CLI 回答三個問題：這個專案怎麼跑測試，哪些檔案不能改，改完怎麼驗證。如果它答不出來，說明 `GEMINI.md` 還不夠具體；如果它答錯，說明上下文載入或層級衝突要先修。

## 官方核驗點

官方配置裡 `context.fileName` 可以改變上下文檔名，`/memory show` 能看到最終載入結果，`.geminiignore` 和 `.gitignore` 會影響檔案進入上下文。遇到“規則沒生效”，先用這些機制核驗，不要繼續追加 prompt。

上下文檔案改完後還要驗證當前會話是否過載。很多“模型不聽話”的問題，其實是舊會話沒有讀到新規則。

每次規則改動都應能被複查。

複查記錄至少要包含規則檔案路徑、載入或重新整理命令、預期回答和實際回答。這樣後續換人、換終端或換 agent 時，能判斷問題是規則沒寫清，還是會話沒有載入到正確上下文。

## 官方資料

- 專案上下文 GEMINI.md：[docs/cli/gemini-md.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md)
- 配置 settings：[docs/cli/settings.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/settings.md)
- `.geminiignore`：[docs/cli/gemini-ignore.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-ignore.md)
- 記憶匯入處理（memport）：[docs/reference/memport.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/memport.md)

## 下一篇

<Cards>
  <Card title="工具、Shell 和許可權邊界" description="上下文穩定後，再討論哪些工具可以讓 Gemini CLI 執行。" href="/zh-Hant/docs/gemini-cli/understanding/05-tools-shell-permissions" />
  <Card title="GEMINI.md" description="需要查官方配置和專案上下文載入細節時，回到官方 GEMINI.md 頁。" href="/zh-Hant/docs/gemini-cli/official/02-context-config/21-gemini-md" />
  <Card title="Settings" description="執行配置、MCP、sandbox、hooks 和 trusted folders 回到 settings 頁面。" href="/zh-Hant/docs/gemini-cli/official/02-context-config/20-settings" />
</Cards>
