GEMINI.md、記憶和專案上下文
用 GEMINI.md、settings.json、memory 和 .geminiignore 管理 Gemini CLI 的專案上下文。
Gemini CLI 能不能穩定處理專案，關鍵不在 prompt 寫多長，而在專案上下文是否可重複。GEMINI.md 就是把一次性口頭說明沉澱成專案級規則的核心入口。
上下文檔案不是越多越好。真正有價值的是：真相源清楚、層級清楚、驗證命令清楚、禁止事項清楚。
第一次寫 GEMINI.md 不要從空白開始：直接在專案根目錄跑 /init，Gemini CLI 會掃描專案結構、入口檔案、檢查命令，自動生成一份初稿。你只需補"禁止觸碰的檔案 / 提交規則 / 團隊協作邊界"這些人類才知道的部分，比從零寫省一半時間。
GEMINI.md 應該寫什麼
GEMINI.md 適合寫穩定規則：
- 專案用途。
- 技術堆疊。
- 目錄職責。
- 常用檢查命令。
- 禁止觸碰的檔案。
- 提交、測試、釋出規則。
- 團隊協作邊界。
不適合寫：
- 臨時任務。
- 過期待辦事項。
- 金鑰。
- 大段原始碼解釋。
- 和真實程式碼不一致的歷史說明。
settings.json 管什麼
settings.json 管 CLI 行為和工具配置，例如模型、MCP、hooks、sandbox、信任目錄、主題等。它更像執行配置，不是專案說明書。
可以這樣分：
GEMINI.md 给 agent 读的项目规则
settings.json 给 CLI 执行的运行配置
.geminiignore 告诉 agent 哪些内容不应纳入上下文
memory 长期可复用偏好和经验.geminiignore 的價值
專案裡總有不該被讀入上下文的內容：
- 依賴目錄。
- 構建產物。
- 大檔案。
- 金鑰和私有資料。
- 自動生成檔案。
.geminiignore 可以減少噪音，也能降低敏感資訊被誤讀的風險。
好的上下文長什麼樣
好的上下文不是“大而全”，而是讓 agent 快速判斷：
- 這是什麼專案。
- 哪些檔案是真相源。
- 改動邊界在哪裡。
- 怎麼驗證。
- 哪些操作必須先確認。
多層上下文怎麼放
最穩的結構是三層：
- 全域性
~/.gemini/GEMINI.md：跨專案偏好，例如回答風格、預設驗證習慣。 - 專案根
GEMINI.md：專案結構、執行命令、編碼規範、禁止事項。 - 子目錄
GEMINI.md：只對某個模組成立的規則，例如packages/api/的資料庫約束。
不要把所有規則都寫到全域性。全域性規則太重，會汙染每個專案；子目錄規則太少，又會讓 agent 在區域性修改時缺少邊界。
排錯上下文
如果 Gemini CLI 沒遵守規則，先查三件事：
- 當前會話是否過載了上下文。
/memory show裡是否真的出現了那條規則。- 是否有更近層級的規則覆蓋了根規則。
改了 GEMINI.md 後要執行 /memory reload 或重啟會話。不要假設正在執行的 session 會自動感知你剛寫入的規則。
常見壞味道
| 壞味道 | 風險 | 修法 |
|---|---|---|
| 全域性規則寫滿專案細節 | 汙染所有儲存庫 | 下沉到專案或子目錄 GEMINI.md |
| 專案規則沒有驗證命令 | agent 改完不知道怎麼收尾 | 寫清 build/test/typecheck/lint |
| ignore 只排依賴不排金鑰 | 可能誤讀私有資料 | 明確排除 secret、dump、artifact |
| memory 記錄臨時 bug | 未來任務被舊事實汙染 | 臨時資訊留在任務記錄，不進 memory |
| 多層規則互相矛盾 | agent 選擇困難 | 就近層級只寫本目錄真實約束 |
一個最小 GEMINI.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
- 配置 settings：docs/cli/settings.md
.geminiignore：docs/cli/gemini-ignore.md- 記憶匯入處理（memport）：docs/reference/memport.md