---
title: "GEMINI.md"
description: "Gemini CLI GEMINI.md 專案上下文檔案的用途：長期規則、專案結構、測試命令、程式碼風格、禁止事項和層級管理。"
verifiedAt: "2026-05-09"
---

`GEMINI.md` 是 Gemini CLI 的專案上下文檔案。它的價值是把你反覆提醒 AI 的東西變成每次啟動都能讀到的長期規則。

> [!NOTE]
> **一句話**：prompt 解決當前任務，`GEMINI.md` 解決長期協作。

## 載入機制

Gemini CLI 會把多個 `GEMINI.md` 拼接後隨每次請求發給模型。官方載入順序分三層：

1. 全域性上下文：`~/.gemini/GEMINI.md`，適合放跨專案的個人預設規則。
2. 工作區上下文：當前專案及配置工作區裡的 `GEMINI.md`，適合放專案結構、命令和協作邊界。
3. Just-in-time 上下文：當工具訪問某個目錄或檔案時，再掃描該位置及其祖先目錄裡的 `GEMINI.md`，適合給子模組提供更細規則。

CLI 底部會顯示已載入的上下文檔案數量。上下文異常時，先用這個數量判斷是不是檔案沒被發現。

## 適合寫進 GEMINI.md 的內容

- 專案結構。
- 常用啟動、測試、構建命令。
- 程式碼風格。
- 不允許改的目錄。
- 安全邊界。
- 業務術語。
- 提交和驗證要求。

## 不適合寫進去的內容

- 金鑰、token、賬號。
- 臨時任務細節。
- 過期的 debug 過程。
- 和當前專案無關的個人偏好。
- 需要頻繁變化的狀態。

## 推薦骨架

```markdown
# Project Rules

## Project Shape

## Commands

## Coding Rules

## Safety Boundaries

## Verification
```

這個骨架的重點不是格式，而是把“能不能動、怎麼驗證、哪些目錄有風險”寫清楚。一個有價值的 `GEMINI.md` 應該讓新會話不用再問：專案怎麼跑、測試怎麼跑、哪些檔案不能改、什麼才算完成。

## 管理和拆分

常用命令：

- `/memory show`：檢視當前拼接後的完整上下文。
- `/memory refresh`：修改 `GEMINI.md` 後強制過載；部分舊文件和社群文章也會寫成 reload，實際操作以當前 CLI 幫助為準。
- `/memory list`：列出被發現的 memory 檔案。
- `/memory add <text>`：把內容追加到全域性 `~/.gemini/GEMINI.md`。

大型專案不要把所有規則塞進一個巨大的根檔案。官方支援在 `GEMINI.md` 裡用 `@file.md` 匯入其他 Markdown 檔案，可以把程式碼風格、安全邊界、釋出流程拆成獨立文件。

```markdown
# Project Rules

@./docs/coding-style.md
@./docs/security-boundaries.md
@./docs/release-checklist.md
```

如果團隊同時使用 Claude Code、Codex、Gemini CLI，可以在 `settings.json` 的 `context.fileName` 裡配置多個檔名。但這隻解決讀取問題，不解決規則衝突。真正可靠的做法是保留一個主規則檔案，再讓其他入口引用或同步同一套內容。

## 官方配置項

`GEMINI.md` 不是寫死的檔名。官方配置裡 `context.fileName` 可以改成單個或多個檔名，例如團隊同時維護 `GEMINI.md`、`AGENTS.md`、`CLAUDE.md` 時，讓 Gemini CLI 讀取同一套規則入口。

和上下文載入相關的常用配置還有：

- `context.discoveryMaxDirs`：限制向上發現上下文目錄的深度，避免 monorepo 根層掃描過寬。
- `context.importFormat`：控制 `@file.md` 匯入後的展示格式。
- `context.includeDirectories`：把額外目錄納入工作區上下文。
- `context.loadFromIncludeDirectories`：決定 include 目錄裡的上下文檔案是否也參與載入。
- `context.fileFiltering.respectGitIgnore`：是否尊重 `.gitignore`。
- `context.fileFiltering.respectGeminiIgnore`：是否尊重 `.geminiignore`。

教程裡建議顯式寫出“修改了哪個配置項、在哪裡生效、如何檢查”。只寫“Gemini 會自動讀取專案規則”不夠，因為一旦專案裡同時存在多套 agent 規則，讀者很難判斷到底哪份檔案被載入。

## 和其他工具的關係

Gemini CLI 用 `GEMINI.md`；Claude Code 常用 `CLAUDE.md`；Codex 常用 `AGENTS.md`。同一個專案多工具共存時，不要讓三份規則互相沖突。

## 驗收方式

修改後執行 `/memory refresh`，再執行 `/memory show` 檢查關鍵規則是否出現且順序合理。然後讓 Gemini CLI 回答“這個專案應該怎麼執行測試、哪些目錄不能改”，如果回答不出來，說明上下文寫得不夠具體或沒有被載入。

團隊專案還要額外驗證三件事：根目錄規則、子目錄規則、`@file.md` 匯入檔案都能在 `/memory show` 中看到；敏感檔案沒有因為匯入鏈進入上下文；多個入口檔案之間沒有互相否定的規則。

## 官方來源

- [Gemini CLI GEMINI.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md)
- [Memory Import Processor](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/memport.md)

## 接下來去哪

<Cards>
  <Card title="Memory 管理" href="/zh-Hant/docs/gemini-cli/official/02-context-config/22-memory-management" description="深入 /memory 命令族與上下文生命週期" />
  <Card title="基礎設定" href="/zh-Hant/docs/gemini-cli/official/02-context-config/20-settings" description="settings.json 裡 context.fileName / discoveryMaxDirs 等" />
  <Card title="自定義命令" href="/zh-Hant/docs/gemini-cli/official/02-context-config/24-custom-commands" description="把高頻規則用法升級成命令" />
  <Card title=".geminiignore" href="/zh-Hant/docs/gemini-cli/official/02-context-config/23-gemini-ignore" description="規則之外，把敏感路徑排除掉" />
  <Card title="生成引數" href="/zh-Hant/docs/gemini-cli/official/02-context-config/25-generation-settings" description="規則配齊後再調溫度等推理引數" />
  <Card title="System Prompt" href="/zh-Hant/docs/gemini-cli/official/02-context-config/26-system-prompt" description="另一類長期上下文的注入位置" />
</Cards>
