---
title: "GEMINI.md、记忆和项目上下文"
description: "用 GEMINI.md、settings.json、memory 和 .geminiignore 管理 Gemini CLI 的项目上下文。"
verifiedAt: "2026-05-09"
---

Gemini CLI 能不能稳定处理项目，关键不在 prompt 写多长，而在项目上下文是否可重复。`GEMINI.md` 就是把一次性口头说明沉淀成项目级规则的核心入口。

> [!IMPORTANT]
> 上下文文件不是越多越好。真正有价值的是：真相源清楚、层级清楚、验证命令清楚、禁止事项清楚。

> [!TIP]
> **第一次写 `GEMINI.md` 不要从空白开始**：直接在项目根目录跑 `/init`，Gemini CLI 会扫描项目结构、入口文件、检查命令，自动生成一份初稿。你只需补"禁止触碰的文件 / 提交规则 / 团队协作边界"这些人类才知道的部分，比从零写省一半时间。

## GEMINI.md 应该写什么

`GEMINI.md` 适合写稳定规则：

- 项目用途。
- 技术栈。
- 目录职责。
- 常用检查命令。
- 禁止触碰的文件。
- 提交、测试、发布规则。
- 团队协作边界。

不适合写：

- 临时任务。
- 过期待办事项。
- 密钥。
- 大段源码解释。
- 和真实代码不一致的历史说明。

## settings.json 管什么

`settings.json` 管 CLI 行为和工具配置，例如模型、MCP、hooks、sandbox、信任目录、主题等。它更像运行配置，不是项目说明书。

可以这样分：

```text
GEMINI.md       给 agent 读的项目规则
settings.json   给 CLI 执行的运行配置
.geminiignore   告诉 agent 哪些内容不应纳入上下文
memory          长期可复用偏好和经验
```

## .geminiignore 的价值

项目里总有不该被读入上下文的内容：

- 依赖目录。
- 构建产物。
- 大文件。
- 密钥和私有数据。
- 自动生成文件。

`.geminiignore` 可以减少噪音，也能降低敏感信息被误读的风险。

## 好的上下文长什么样

好的上下文不是“大而全”，而是让 agent 快速判断：

- 这是什么项目。
- 哪些文件是真相源。
- 改动边界在哪里。
- 怎么验证。
- 哪些操作必须先确认。

## 多层上下文怎么放

最稳的结构是三层：

- 全局 `~/.gemini/GEMINI.md`：跨项目偏好，例如回答风格、默认验证习惯。
- 项目根 `GEMINI.md`：项目结构、运行命令、编码规范、禁止事项。
- 子目录 `GEMINI.md`：只对某个模块成立的规则，例如 `packages/api/` 的数据库约束。

不要把所有规则都写到全局。全局规则太重，会污染每个项目；子目录规则太少，又会让 agent 在局部修改时缺少边界。

## 排错上下文

如果 Gemini CLI 没遵守规则，先查三件事：

1. 当前会话是否重载了上下文。
2. `/memory show` 里是否真的出现了那条规则。
3. 是否有更近层级的规则覆盖了根规则。

改了 `GEMINI.md` 后要运行 `/memory reload` 或重启会话。不要假设正在运行的 session 会自动感知你刚写入的规则。

## 常见坏味道

| 坏味道 | 风险 | 修法 |
| --- | --- | --- |
| 全局规则写满项目细节 | 污染所有仓库 | 下沉到项目或子目录 `GEMINI.md` |
| 项目规则没有验证命令 | agent 改完不知道怎么收尾 | 写清 build/test/typecheck/lint |
| ignore 只排依赖不排密钥 | 可能误读私有数据 | 明确排除 secret、dump、artifact |
| memory 记录临时 bug | 未来任务被旧事实污染 | 临时信息留在任务记录，不进 memory |
| 多层规则互相矛盾 | agent 选择困难 | 就近层级只写本目录真实约束 |

## 一个最小 GEMINI.md 模板

```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](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md)
- 配置 settings：[docs/cli/settings.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/settings.md)
- `.geminiignore`：[docs/cli/gemini-ignore.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-ignore.md)
- 记忆导入处理（memport）：[docs/reference/memport.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/memport.md)

## 下一篇

<Cards>
  <Card title="工具、Shell 和权限边界" description="上下文稳定后，再讨论哪些工具可以让 Gemini CLI 执行。" href="/docs/gemini-cli/understanding/05-tools-shell-permissions" />
  <Card title="GEMINI.md" description="需要查官方配置和项目上下文加载细节时，回到官方 GEMINI.md 页。" href="/docs/gemini-cli/official/02-context-config/21-gemini-md" />
  <Card title="Settings" description="运行配置、MCP、sandbox、hooks 和 trusted folders 回到 settings 页面。" href="/docs/gemini-cli/official/02-context-config/20-settings" />
</Cards>
