---
title: "GEMINI.md"
description: "Gemini CLI GEMINI.md 项目上下文文件的用途：长期规则、项目结构、测试命令、代码风格、禁止事项和层级管理。"
verifiedAt: "2026-05-09"
---

`GEMINI.md` 是 Gemini CLI 的项目上下文文件。它的价值是把你反复提醒 AI 的东西变成每次启动都能读到的长期规则。

> [!NOTE]
> **一句话**：prompt 解决当前任务，`GEMINI.md` 解决长期协作。

## 加载机制

Gemini CLI 会把多个 `GEMINI.md` 拼接后随每次请求发给模型。官方加载顺序分三层：

1. 全局上下文：`~/.gemini/GEMINI.md`，适合放跨项目的个人默认规则。
2. 工作区上下文：当前项目及配置工作区里的 `GEMINI.md`，适合放项目结构、命令和协作边界。
3. Just-in-time 上下文：当工具访问某个目录或文件时，再扫描该位置及其祖先目录里的 `GEMINI.md`，适合给子模块提供更细规则。

CLI 底部会显示已加载的上下文文件数量。上下文异常时，先用这个数量判断是不是文件没被发现。

## 适合写进 GEMINI.md 的内容

- 项目结构。
- 常用启动、测试、构建命令。
- 代码风格。
- 不允许改的目录。
- 安全边界。
- 业务术语。
- 提交和验证要求。

## 不适合写进去的内容

- 密钥、token、账号。
- 临时任务细节。
- 过期的 debug 过程。
- 和当前项目无关的个人偏好。
- 需要频繁变化的状态。

## 推荐骨架

```markdown
# Project Rules

## Project Shape

## Commands

## Coding Rules

## Safety Boundaries

## Verification
```

这个骨架的重点不是格式，而是把“能不能动、怎么验证、哪些目录有风险”写清楚。一个有价值的 `GEMINI.md` 应该让新会话不用再问：项目怎么跑、测试怎么跑、哪些文件不能改、什么才算完成。

## 管理和拆分

常用命令：

- `/memory show`：查看当前拼接后的完整上下文。
- `/memory refresh`：修改 `GEMINI.md` 后强制重载；部分旧文档和社区文章也会写成 reload，实际操作以当前 CLI 帮助为准。
- `/memory list`：列出被发现的 memory 文件。
- `/memory add <text>`：把内容追加到全局 `~/.gemini/GEMINI.md`。

大型项目不要把所有规则塞进一个巨大的根文件。官方支持在 `GEMINI.md` 里用 `@file.md` 导入其他 Markdown 文件，可以把代码风格、安全边界、发布流程拆成独立文档。

```markdown
# Project Rules

@./docs/coding-style.md
@./docs/security-boundaries.md
@./docs/release-checklist.md
```

如果团队同时使用 Claude Code、Codex、Gemini CLI，可以在 `settings.json` 的 `context.fileName` 里配置多个文件名。但这只解决读取问题，不解决规则冲突。真正可靠的做法是保留一个主规则文件，再让其他入口引用或同步同一套内容。

## 官方配置项

`GEMINI.md` 不是写死的文件名。官方配置里 `context.fileName` 可以改成单个或多个文件名，例如团队同时维护 `GEMINI.md`、`AGENTS.md`、`CLAUDE.md` 时，让 Gemini CLI 读取同一套规则入口。

和上下文加载相关的常用配置还有：

- `context.discoveryMaxDirs`：限制向上发现上下文目录的深度，避免 monorepo 根层扫描过宽。
- `context.importFormat`：控制 `@file.md` 导入后的展示格式。
- `context.includeDirectories`：把额外目录纳入工作区上下文。
- `context.loadFromIncludeDirectories`：决定 include 目录里的上下文文件是否也参与加载。
- `context.fileFiltering.respectGitIgnore`：是否尊重 `.gitignore`。
- `context.fileFiltering.respectGeminiIgnore`：是否尊重 `.geminiignore`。

教程里建议显式写出“修改了哪个配置项、在哪里生效、如何检查”。只写“Gemini 会自动读取项目规则”不够，因为一旦项目里同时存在多套 agent 规则，读者很难判断到底哪份文件被加载。

## 和其他工具的关系

Gemini CLI 用 `GEMINI.md`；Claude Code 常用 `CLAUDE.md`；Codex 常用 `AGENTS.md`。同一个项目多工具共存时，不要让三份规则互相冲突。

## 验收方式

修改后执行 `/memory refresh`，再执行 `/memory show` 检查关键规则是否出现且顺序合理。然后让 Gemini CLI 回答“这个项目应该怎么运行测试、哪些目录不能改”，如果回答不出来，说明上下文写得不够具体或没有被加载。

团队项目还要额外验证三件事：根目录规则、子目录规则、`@file.md` 导入文件都能在 `/memory show` 中看到；敏感文件没有因为导入链进入上下文；多个入口文件之间没有互相否定的规则。

## 官方来源

- [Gemini CLI GEMINI.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md)
- [Memory Import Processor](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/memport.md)

## 接下来去哪

<Cards>
  <Card title="Memory 管理" href="/docs/gemini-cli/official/02-context-config/22-memory-management" description="深入 /memory 命令族与上下文生命周期" />
  <Card title="基础设置" href="/docs/gemini-cli/official/02-context-config/20-settings" description="settings.json 里 context.fileName / discoveryMaxDirs 等" />
  <Card title="自定义命令" href="/docs/gemini-cli/official/02-context-config/24-custom-commands" description="把高频规则用法升级成命令" />
  <Card title=".geminiignore" href="/docs/gemini-cli/official/02-context-config/23-gemini-ignore" description="规则之外，把敏感路径排除掉" />
  <Card title="生成参数" href="/docs/gemini-cli/official/02-context-config/25-generation-settings" description="规则配齐后再调温度等推理参数" />
  <Card title="System Prompt" href="/docs/gemini-cli/official/02-context-config/26-system-prompt" description="另一类长期上下文的注入位置" />
</Cards>
