GEMINI.md 是 Gemini CLI 的项目上下文文件，类似于 Claude Code 的 CLAUDE.md。放在项目根目录或 ~/.gemini/ 下，每次对话都会自动加载。支持三级层次结构（全局 → 工作区 → 即时），以及 @文件 语法进行模块化导入。

GEMINI.md 上下文文件

GEMINI.md 文件让你一次配置、每次对话自动生效，无需反复粘贴相同的背景说明。

文件加载顺序（三级层次）

Gemini CLI 按以下顺序加载 GEMINI.md，并将所有内容拼接后发送给模型：

1. 全局上下文：~/.gemini/GEMINI.md

   • 适合放个人偏好、通用编码规范
   • 对所有项目生效

2. 工作区上下文：项目目录及父目录中的 GEMINI.md

   • 适合放项目架构说明、团队规范
   • 越靠近根目录优先级越低（父目录先加载）

3. JIT（即时）上下文：当工具访问某个文件/目录时，自动扫描该目录及其父目录

   • 适合放模块级别的特定说明
   • 只在 AI 真正用到该目录的内容时才加载

CLI 底部会显示当前加载的上下文文件数量，方便确认。

示例 GEMINI.md

# 项目：古法编程文档站

## 通用规范

- 所有新增代码必须有 JSDoc 注释
- TypeScript 优先，避免使用 `any` 类型
- 优先函数式编程，避免可变状态

## 编码风格

- 缩进：2 个空格
- 接口命名不加 `I` 前缀
- 严格等于：始终用 `===` 和 `!==`

## 项目结构

- `docs/` — VitePress 文档源文件
- `.vitepress/` — 主题和配置
- 文档路径结构：`/ai/ai-tools/{tool-name}/`

与 Claude Code 的 CLAUDE.md 对比

特性	GEMINI.md	CLAUDE.md
配置 AI 上下文	✓	✓
全局 + 项目级	✓	✓
JIT 按需加载	✓	部分支持
模块化导入	@file.md 语法	不支持
自动内存追加	/memory add	记忆系统

/memory 命令

在 REPL 中管理上下文：

/memory show    # 查看当前所有加载的上下文内容
/memory reload  # 重新扫描并加载所有 GEMINI.md 文件
/memory add 我喜欢简洁的代码注释  # 追加到 ~/.gemini/GEMINI.md

模块化导入（@file.md 语法）

把大 GEMINI.md 拆成多个文件管理：

# 主 GEMINI.md

这是主要内容。

@./docs/coding-style.md

更多内容...

@../shared/team-guidelines.md

支持相对路径和绝对路径，文件会被内联展开。

自定义上下文文件名

如果项目里已有 AGENTS.md 或 CLAUDE.md，可以在 settings.json 中配置：

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

CLI 会按顺序查找并加载列表中存在的文件。

常见问题

Q: GEMINI.md 和 CLAUDE.md 能共用同一个文件吗？

A: 可以通过上方的 context.fileName 配置让 Gemini CLI 读取 CLAUDE.md，但建议分开维护——两个工具的偏好和约定不完全相同，混用容易造成混乱。

Q: GEMINI.md 放在哪里最合适？

A: 通用规范放 ~/.gemini/GEMINI.md（全局）；项目特定指令放项目根目录；针对某个子模块的特定说明放该子目录下。

Q: JIT 上下文什么时候会被加载？

A: 当 Gemini CLI 的工具（如读文件、列目录）访问某个目录时，会自动向上查找 GEMINI.md。例如 AI 读取 src/auth/login.ts 时，会依次检查 src/auth/、src/、项目根目录下有没有 GEMINI.md。