GEMINI.md 與專案記憶

5.1 GEMINI.md 是什麼

Gemini CLI 會把找到的 GEMINI.md 當成每次對話的 instructional context。它適合放這些內容：

概念上，它和 Codex 常見的 AGENTS.md、Claude Code 的 CLAUDE.md 同一類：都是把專案慣例變成 AI 工具會讀到的長期上下文。檔名、載入規則與支援細節各工具不同，不要直接假設完全相容。

5.2 context 階層：全域、workspace、子目錄、JIT

官方文件把 GEMINI.md 的來源分成幾層。你可以用「越共通放越上層，越細節放越靠近程式碼」來記。

1. 全域：~/.gemini/GEMINI.md，放你個人跨專案偏好。
2. workspace：目前工作區與父層中的 GEMINI.md，放專案規則。
3. 子目錄：元件或模組資料夾內的 GEMINI.md，放局部規則。
4. JIT context：當工具存取某個檔案或資料夾時，Gemini CLI 會在相關路徑附近即時找更精準的 GEMINI.md。

這代表大型 monorepo 可以把前端、後端、infra 的規則拆開，不必把所有規則塞在根目錄一份巨大的記憶檔。

實際掃描時，Gemini CLI 從你目前所在的資料夾開始往「上」找：一路走訪父層資料夾，直到遇到專案邊界（預設看到 .git 資料夾就停）為止，沿路每一層只要有 GEMINI.md 就收進來。找完之後，CLI 還會往「下」掃描子目錄——例如你人在專案根目錄，src/GEMINI.md 一樣可能被抓到。這一點跟 Claude Code 的 CLAUDE.md「只往上找」是不同的行為，如果你同時維護兩套 CLI 的規則檔，這個差異值得留意。

所有找到的 GEMINI.md，Gemini CLI 是把它們「串接」（concatenate）成一份長 context 一起送給模型，不是後找到的蓋掉先找到的。啟動後，CLI 底部狀態列會顯示目前載入了幾個 context 檔；這個數字只告訴你「找到幾份」，不保證「內容有沒有照你要的方式生效」，下一節會示範更可靠的驗證方式。

「越靠近目前目錄越優先」是慣例，不是強制覆蓋

官方文件與不少整理都會說，串接順序是「全域 → 專案／祖先 → 子目錄」，且「較貼近目前目錄的內容應該優先」。這句話很容易被理解成程式碼層級的強制覆蓋機制，但它比較接近排版順序上的暗示——最終要不要真的照做，仍是模型自己判斷的結果，不是系統幫你鎖死的保證。

排查「模型好像沒在聽指令」時，別只看狀態列「找到 N 個檔案」這個數字——那只證明檔案有被發現，不保證內容真的送進去、也不保證模型真的照做。優先跑 /memory show，直接看「實際、串接後」送進模型的完整內容，是比較可靠的第一步，下一節會細講。

5.3 建立第一份 GEMINI.md

先在 gemini-cli-lab 建一份短檔。以下內容可以直接當作第一版：

# GEMINI.md

## 回答風格
- 回答使用繁體中文，台灣用語。
- 新手說明要先講結論，再補必要背景。

## 專案工作流
- 改檔前先說明你打算改哪些檔案。
- 改完後列出修改摘要與建議驗收指令。
- 不要修改 .env、secrets、node_modules、dist。

## 驗收
- 如果專案有測試指令，優先跑最相關的測試。
- 如果不能跑測試，請明確說明原因。

內容越短，模型越容易穩定遵守。把「永遠都要做」的規則放這裡，把「這次任務才需要」的資料放 prompt 或 @。

5.4 用 /memory 檢查目前載入了什麼

/memory 是檢查 context 的關鍵指令。官方文件目前有頁面使用 /memory reload，command reference 則列出 show、list、add、refresh 等子命令；這類指令會隨版本調整，請以你本機 /help、/memory 選單或官方 command reference 為準。

/memory show
/memory list
/memory refresh

# 如果你的版本文件或選單使用 reload：
/memory reload

把常見子命令實際在做什麼、什麼時候該用整理成一張表，比死背指令名稱更有用：

順帶一提，/memory refresh 只重新載入 GEMINI.md 檔案，不會動到對話歷史本身。如果你要的是清空或壓縮對話紀錄，那是 /clear（整個清空）或 /compress（壓縮成結構化摘要、省 token，可在 settings.json 用 chatCompression.contextPercentageThreshold 設定自動觸發的門檻）的工作。三個指令動的是完全不同的東西，別搞混。

/memory add 到底寫進哪一個檔案？

多數官方頁面的說法是：/memory add 固定寫進「全域」的 ~/.gemini/GEMINI.md，不管你現在人在哪個專案裡。這件事乍看方便，其實藏著一個容易忽略的陷阱：如果你隨手記下的其實是「這個專案才有」的細節，像是資料庫名稱、CORS 設定、某個服務用的技術棧，這些內容就會被寫進全域檔，之後你打開任何其他專案，Gemini CLI 都會帶著這些不相干的細節一起讀。GitHub 上有一則真實回報（issue #6371）描述了幾乎一樣的狀況：agent 把某個專案特有的設定寫進了全域記憶，污染了後續其他專案的 context。

模型也能透過一個叫 save_memory 的內建工具自己記東西，觸發方式很直覺，就是你直接用自然語言請它記住某件事，例如「Remember that I prefer using const over let」。傳統行為是把這段文字附加進全域 GEMINI.md，歸在一個類似「Gemini Added Memories」的標題底下——這個標題名稱來自二手資料整理，實際文字請以你版本產出的檔案內容為準。至於這套機制在最新版本裡是否還是這樣運作，5.9 節會再談到它正在往更細緻的方向演進。

用 /init 生出第一版草稿

如果專案已經存在、只是還沒有 GEMINI.md，不必從零手打。/init 會分析目前資料夾（或整個程式碼庫）的結構與慣例，自動生成一份量身打造的 GEMINI.md 草稿。實際跑起來的介面細節——例如是否會先建一個空檔案、分析完是用 diff 形式列出變更讓你確認、還是直接寫入——在不同版本之間有落差，建議動手前先用你當下的版本實測一次確認流程。

/init

不管介面怎麼呈現，養成的習慣應該一致：/init 產出的內容是起點、不是終點。它幫你抓出專案實際使用的框架、目錄慣例、常用指令，省下從零盤點的時間，但草稿裡哪些規則要留、要刪、要改得更精準，還是要靠你自己過一遍再定案。

5.5 用 @ import 拆小記憶檔

如果根目錄 GEMINI.md 變長，可以把細節拆到其他 Markdown，再用 @./path.md 匯入。這是官方支援的 memory import processor。

# GEMINI.md

你是這個專案的程式協作助理。請遵守根目錄規則。

@./docs/gemini-style.md
@./docs/gemini-testing.md

拆分的原則是「一份檔案一種規則」。例如風格、測試、部署、資料庫各自一份。不要把大量範例資料或完整 log import 進長期記憶。

@ 語法支援三種路徑寫法：相對路徑用 @./a.md（同一層）或 @../b.md（上一層），也可以用 @/完整/絕對/路徑.md 直接指到系統上的任何位置——拆分子檔案時多數情況相對路徑就夠用，絕對路徑比較適合「規則放在專案外、多個 repo 共用」的情境。你可能會擔心，如果 GEMINI.md 裡要示範 @ 語法本身該怎麼寫（就像上面這句一樣），CLI 會不會把範例裡的 @./a.md 誤當成「真的要匯入」？負責解析匯入的元件（官方稱它 Memory Import Processor，簡稱 memport）用 marked 這套 Markdown 函式庫辨識 fenced code block 與 inline code，確保出現在程式碼範例裡的 @ 不會被誤判成真正的匯入指令——只要你的範例確實包在反引號或 ``` 裡，就是安全的。

巢狀深度與循環引用：文件說法不一致，保守設計成樹狀

兩件關於 @ 匯入的細節，目前查到的文件彼此有出入，這裡誠實列出來，不硬湊成一個乾淨答案：

• 最大匯入深度：官方說明有「可設定的最大匯入深度以防止無限遞迴」，但不同頁面給出的預設數字不一致，有的寫 5 層、有的寫 10 層。確切數字請以官方頁面或你當下版本的說明為準，不要把單一數字當鐵律記下來。
• 循環引用的處理：官方 Memory Import Processor 頁面說系統會「自動偵測並阻擋循環引用」；但至少一份第三方技術文章的說法相反，認為 @ 匯入不做循環偵測，如果 A 匯入 B、B 又匯入 A，內容可能被靜默截斷或重複。這兩種說法互相矛盾，可能對應到不同版本的實際行為。

5.6 用 .geminiignore 控制不要讀什麼

.geminiignore 類似 .gitignore，可讓支援該功能的工具排除特定檔案或資料夾，特別是 @ 分享目錄時。它不是安全萬靈丹，但能減少雜訊與誤讀敏感資料。

# .geminiignore
.env
*.pem
secrets/
dist/
node_modules/
coverage/
tmp/

# 文件很多時，保留 README 當入口
docs/archive/
!README.md

官方文件提醒，更新 .geminiignore 後通常要重新啟動 Gemini CLI session 才會套用。敏感資料仍應用真正的權限、secret manager 與 Git hygiene 保護。

5.7 用 context.fileName 讓記憶檔跨工具共用

預設檔名是 GEMINI.md，但這其實可以改。在 settings.json 裡設定 context.fileName，可以把它換成別的字串，也可以給一個陣列，讓 Gemini CLI 同時認得好幾種檔名：

{
  "context": {
    "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]
  }
}

這個設定跟 5.1 節提到的「Gemini CLI、Codex 的 AGENTS.md、Claude Code 的 CLAUDE.md 概念相通但檔名各自不同」直接相關。如果你的團隊同時用好幾套 AI CLI，又不想維護三份幾乎一樣的規則檔，context.fileName 設成陣列後，Gemini CLI 也能讀取正在成形的跨工具標準 AGENTS.md——一份共用指令檔就能同時服務原生支援 AGENTS.md 的 Codex 與 Gemini CLI。三套 CLI 之中，目前只有 Gemini CLI 原生支援這種「可設定陣列、同時認得多個檔名」的寫法；Claude Code 要接上同一份共用檔案，通常要另外用一個指向性的小檔案銜接（例如在 CLAUDE.md 裡寫 @AGENTS.md，或直接建 symlink）。

5.8 大型專案怎麼調：掃描範圍、額外目錄與資料夾信任

小型專案通常不需要碰這節的設定，預設值就夠用。但如果你的專案是 monorepo，或者資料夾層數特別深，settings.json 裡還有幾個 context.* 選項可以調：

大多數 context.* 欄位改完要重新啟動 CLI 才會生效，不是即時套用；更早的版本可能用比較扁平的鍵名（例如 memoryDiscoveryMaxDirs）而不是巢狀的 context.discoveryMaxDirs，鍵名結構隨版本演進過，動手改之前先確認你目前版本實際吃哪一種寫法。

還有一種「資料夾好像沒被掃到」的情況，跟前面這些設定都無關，而是第 1 章資料夾信任機制在起作用。如果一個資料夾還沒被信任，官方文件列出的限制之一就是「自動記憶載入會被停用」——不只是掃描範圍變小，是整個自動載入直接關掉。你可能 clone 一個新專案、跳出信任提示卻沒特別留意選了「不信任」，之後發現這個專案的 GEMINI.md 和設定好像完全沒作用，根因其實是資料夾信任狀態，不是 GEMINI.md 本身寫錯。在 CI 或其他沒有人能回應提示的環境裡，記得加 --skip-trust 旗標，或設定環境變數 GEMINI_CLI_TRUST_WORKSPACE=true，避免流程卡在一個沒人能回答的信任詢問上：

# CI／無互動環境跳過信任詢問
gemini --skip-trust -p "run the test suite"

# 或用環境變數
GEMINI_CLI_TRUST_WORKSPACE=true gemini -p "run the test suite"

5.9 進階與正在演進中的機制

接下來三個機制不是每天都會用到，但知道它們存在，能幫你看懂官方文件或社群討論裡比較進階的段落，也能在踩到相關狀況時知道自己在面對什麼。這幾項在 2026 年都還在快速變動，內容請當作方向性介紹，實際行為以你當下版本的官方文件為準。

分層記憶（Tiered Memory）：記憶體系正在往更細的方向走

🧪研究預覽 官方在一則 GitHub Discussion 裡揭露了一套更細緻的分層記憶設計，把記憶分成四層：Project（./GEMINI.md，會進版本控制，團隊共用的規則與架構）、Subdirectory（如 ./src/GEMINI.md，特定模組的局部覆寫）、Private（一份不進版本控制的私有 MEMORY.md 索引，放個人筆記與機器本地設定）、Global（~/.gemini/GEMINI.md，跨專案的個人偏好）。這跟 5.4 節講的 /memory add 固定寫全域檔案的傳統說法不完全一樣——這份文件描述的方向是「依內容性質自動路由」：共用規則進專案 GEMINI.md、私人筆記進專案的私有記憶層、跨專案偏好才進全域檔。

兩種說法（固定寫全域 vs. 依性質自動路由）可能分別對應到不同版本的實際行為。想確認自己目前版本是哪一種，最直接的辦法是實測：跑一次 /memory add 接著馬上 /memory show，看內容具體落在哪個檔案裡，而不是憑文件說法猜測。

別搞混：GEMINI_SYSTEM_MD 不是 GEMINI.md

設定方式：把環境變數設成 true 或 1，CLI 會去讀專案根目錄的 .gemini/system.md；設成其他字串則視為自訂檔案路徑（支援 ~ 展開與相對路徑）；設成 false、0 或乾脆不設，就維持停用、CLI 用回內建的系統提示。啟用時，CLI 介面會顯示一個 |⌐■_■| 的視覺指示符提醒你目前吃的是自訂系統提示；如果指定的路徑找不到檔案，會直接報錯，錯誤訊息類似 missing system prompt file '<path>'。

export GEMINI_SYSTEM_MD=~/my-system.md
gemini

因為是整個換掉系統提示，如果你自訂的 system.md 沒處理好，CLI 內建的技能與子代理清單也會一起憑空消失。要接回來，官方提供了兩個可以放進自訂 system.md 裡的動態變數：${AgentSkills} 與 ${SubAgents}，讓你的自訂系統提示重新注入內建的技能／子代理區塊。這是一個進階、風險相對高的功能，只有在你真的想移除或重寫 Gemini CLI 內建的代理人設與預設行為時才需要碰；日常的規則沉澱，GEMINI.md 才是該用的工具。

實驗性功能：Auto Memory 背景記憶服務

🧪實驗性 Auto Memory 需要在 settings.json 手動開啟，存檔後還要重新啟動 CLI，背景擷取服務才會真的跑起來。啟動後，它會掃描你本機的 session 逐字稿（存放在 ~/.gemini/tmp/<project>/chats/），只處理「閒置 3 小時以上」且「使用者訊息數至少 10 則」的 session（排除進行中、太瑣碎、或子代理跑的 session）。它會把偵測到的固定事實、偏好、流程模式，草擬成一份 .patch（unified diff 格式，針對既有 skill 或記憶的更新提案）或一份全新的 SKILL.md 草稿，全部丟進一個審核收件匣，用 /memory inbox 查看，可以逐一核准或拒絕，核准前能看完整內容再決定。

{
  "experimental": { "autoMemory": true }
}

官方文件特別強調，Auto Memory 不能直接編輯正在使用中的記憶檔案、settings.json、憑證或專案 GEMINI.md——所有變更都要經人工從收件匣核准，而且它產出的 patch 在呈現給你之前，會先被解析、做過 dry-run、限定在允許的目標範圍內。即便如此，把 /memory inbox 當成「一定要人工複核」的步驟，不要當成全自動化：讀完完整的 SKILL.md 內容或 patch diff 再核准，因為它終究是從逐字稿裡「猜」出來的固定模式，一樣可能誤判「這是專案專屬細節」為「這是通用偏好」，重演 5.4 節提過的、/memory add 洩漏專案細節到全域的同一種問題。

5.10 GEMINI.md 沒作用時，怎麼排查

把本章前面幾節的踩雷案例集中整理成一份排查表。遇到「怎麼感覺沒照著規則做」，可以由上而下對一遍：

倒數第二個狀況值得多說一句：Google 自家的 Antigravity IDE 跟 Gemini CLI 都預設讀寫同一個 ~/.gemini/GEMINI.md 當全域規則檔（相關回報是 issue #16058，官方已標記「not planned」，短期內不會改）。如果你的電腦同時裝了這兩套工具，又觀察到全域行為怪怪的，這是值得排除的一個方向。

本章小結

GEMINI.md 是專案記憶，不是資料垃圾桶。把穩定、短、可執行的規則放進去，用 /memory show／/memory list 檢查實際載入結果，用 @ import 拆模組，用 .geminiignore 排除低訊號或敏感內容。再進一步，現在你也知道：串接順序寫的「優先」只是慣例、不是保證，真正不可逆的規則要靠權限機制把關；context.fileName 可以讓記憶檔跨工具共用；大型專案有 discoveryMaxDirs、memoryBoundaryMarkers 這類選項可以調；而分層記憶、GEMINI_SYSTEM_MD、Auto Memory 這幾個更前沿的機制，代表整套記憶系統還在持續演進——動手前多留意官方文件的最新說法，別把版本相關的細節當成永久事實。

動手試試

1. 在 gemini-cli-lab 建立 GEMINI.md，只放 5 到 10 條規則。
2. 啟動 gemini 後用 /memory show 或本機支援的等價指令確認有載入。
3. 建立 .geminiignore，至少排除 .env、node_modules/、dist/。
4. 請 Gemini 說明它目前讀到的專案規則，檢查是否符合你的預期。
5. 在 gemini-cli-lab 底下建一個子資料夾，放一份局部的 GEMINI.md，用 /memory list 確認它有被抓到。
6. 用自然語言請它「記住」一件事（例如你偏好的程式風格），接著跑 /memory show，確認這句話實際被寫進哪個檔案。
7. 跑一次 /init，比較它生出的草稿跟你自己手寫的第一版差在哪裡。