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