GEMINI.md
Gemini CLI GEMINI.md 项目上下文文件的用途：长期规则、项目结构、测试命令、代码风格、禁止事项和层级管理。
GEMINI.md 是 Gemini CLI 的项目上下文文件。它的价值是把你反复提醒 AI 的东西变成每次启动都能读到的长期规则。
一句话：prompt 解决当前任务，GEMINI.md 解决长期协作。
加载机制
Gemini CLI 会把多个 GEMINI.md 拼接后随每次请求发给模型。官方加载顺序分三层：
- 全局上下文：
~/.gemini/GEMINI.md，适合放跨项目的个人默认规则。 - 工作区上下文：当前项目及配置工作区里的
GEMINI.md，适合放项目结构、命令和协作边界。 - Just-in-time 上下文：当工具访问某个目录或文件时，再扫描该位置及其祖先目录里的
GEMINI.md，适合给子模块提供更细规则。
CLI 底部会显示已加载的上下文文件数量。上下文异常时，先用这个数量判断是不是文件没被发现。
适合写进 GEMINI.md 的内容
- 项目结构。
- 常用启动、测试、构建命令。
- 代码风格。
- 不允许改的目录。
- 安全边界。
- 业务术语。
- 提交和验证要求。
不适合写进去的内容
- 密钥、token、账号。
- 临时任务细节。
- 过期的 debug 过程。
- 和当前项目无关的个人偏好。
- 需要频繁变化的状态。
推荐骨架
# 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 文件，可以把代码风格、安全边界、发布流程拆成独立文档。
# 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 中看到；敏感文件没有因为导入链进入上下文；多个入口文件之间没有互相否定的规则。