GEMINI.md、記憶和專案上下文
用 GEMINI.md、settings.json、memory 和 .geminiignore 管理 Gemini CLI 的專案上下文。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| GEMINI.md | — | Gemini CLI 的專案上下文 / 規則檔案。 |
| 記憶 | memory | 跨會話保留的專案資訊。 |
| 上下文不足 | starvation | 資訊不夠時會憑空猜。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你用 GEMINI.md 和記憶給 Gemini CLI 補好專案上下文。
你是 Gemini CLI 上下文工程顧問。
【角色】
Gemini CLI 上下文工程顧問，按最小夠用、安全優先的原則給可落地方案。
【輸入】
- 要做的任務：___
- 已告訴它的資訊：___
- 專案是否有 GEMINI.md：___
- 關鍵約定 / 禁改區：___
【工作流程】
1. 逐層檢查上下文缺口
2. 把長期約定寫進 GEMINI.md
3. 區分對話上下文和長期記憶
4. 給最小上下文模板
【輸出規範】
▌一、上下文缺口檢查
▌二、GEMINI.md 該寫什麼
▌三、對話 vs 記憶分配
▌四、最小模板
【硬約束】
- 只補相關上下文，不堆冗餘
- 長期規則進 GEMINI.md，不每次重複
- 不編造專案約定，不清先確認
- 不要替我臆測情況或編造不存在的能力，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述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