GEMINI.md
Gemini CLI GEMINI.md 專案上下文檔案的用途：長期規則、專案結構、測試命令、程式碼風格、禁止事項和層級管理。
GEMINI.md 是 Gemini CLI 的專案上下文檔案。它的價值是把你反覆提醒 AI 的東西變成每次啟動都能讀到的長期規則。
一句話：prompt 解決當前任務，GEMINI.md 解決長期協作。
載入機制
Gemini CLI 會把多個 GEMINI.md 拼接後隨每次請求發給模型。官方載入順序分三層：
- 全域性上下文：
~/.gemini/GEMINI.md，適合放跨專案的個人預設規則。 - 工作區上下文：當前專案及配置工作區裡的
GEMINI.md，適合放專案結構、命令和協作邊界。 - Just-in-time 上下文：當工具訪問某個目錄或檔案時，再掃描該位置及其祖先目錄裡的
GEMINI.md，適合給子模組提供更細規則。
CLI 底部會顯示已載入的上下文檔案數量。上下文異常時，先用這個數量判斷是不是檔案沒被發現。
適合寫進 GEMINI.md 的內容
- 專案結構。
- 常用啟動、測試、構建命令。
- 程式碼風格。
- 不允許改的目錄。
- 安全邊界。
- 業務術語。
- 提交和驗證要求。
不適合寫進去的內容
- 金鑰、token、賬號。
- 臨時任務細節。
- 過期的 debug 過程。
- 和當前專案無關的個人偏好。
- 需要頻繁變化的狀態。
推薦骨架
# 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 檔案，可以把程式碼風格、安全邊界、釋出流程拆成獨立文件。
# 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 中看到；敏感檔案沒有因為匯入鏈進入上下文；多個入口檔案之間沒有互相否定的規則。