GEMINI.md配置指南：三级作用域定制你的AI编码助手

在上一篇教程中，我们完成了 Gemini CLI 的安装与项目初始化。现在，在正式让 AI 帮我们写代码之前，有一个关键步骤不容忽视——创建 GEMINI.md 文件。这个文件相当于给 AI 模型下达的「项目说明书」，它能让 Gemini 理解你的项目架构、技术栈选择以及个人编码偏好，从而生成更符合预期的代码。

什么是 GEMINI.md 文件？

GEMINI.md 是一个 Markdown 格式的指令文件，其内容会在每次 Gemini CLI 会话中自动作为上下文注入给模型。选择 Markdown 作为指令文件格式并非偶然——在 AI 编码工具生态中，这种「以文档驱动 AI 行为」的模式正在成为行业标准。Cursor 使用 .cursorrules 文件，GitHub Copilot 使用 .github/copilot-instructions.md，Claude Code 使用 CLAUDE.md。Markdown 的优势在于它既是人类可读的文档格式，又能被大语言模型高效解析为结构化指令。这种设计本质上是 System Prompt（系统提示词）的工程化延伸：将原本需要在每次对话中反复声明的上下文信息，固化为版本可控的项目文件。

你可以在其中定义：

• 项目架构：使用的框架、目录结构、关键依赖
• 开发规范：CSS 方案、测试框架、构建工具
• 编码偏好：是否使用分号、组件拆分粒度、导入路径风格等

举个例子，如果你不喜欢在模板文件中堆满 Tailwind 类名，或者偏好不使用 JavaScript 分号，这些都可以写进 GEMINI.md，AI 在生成代码时就会自动遵循这些规则。

值得注意的是，GEMINI.md 的内容会占用模型的上下文窗口（Context Window）容量。虽然 Gemini 2.5 Pro 拥有高达 100 万 token 的上下文窗口，为注入大量项目信息提供了充裕的空间，但文件内容仍应保持精炼和高信息密度。冗余的描述不仅浪费 token 预算，还可能稀释关键指令的权重，导致模型在生成代码时对某些规则的遵循度下降。这也是为什么自动生成的内容往往是结构化的要点列表，而非冗长的散文描述。

自动生成 GEMINI.md 文件

对于已有代码的项目，Gemini CLI 提供了一个非常便捷的方式来自动生成这个配置文件。

使用 /init 命令扫描代码库

在 Gemini CLI 的聊天窗口中，输入 /init 命令并回车。这是一个特殊的斜杠命令（slash command），它会指示 Gemini 扫描整个代码库，识别其中的模式和信息——包括使用的框架、CSS 库、应用结构、数据流等——然后将这些信息汇总写入 GEMINI.md 文件。

斜杠命令是一种源自 IRC 和 Slack 等即时通讯工具的交互范式，以 / 开头表示这是一条系统指令而非普通对话内容。在 Gemini CLI 中，斜杠命令直接触发 CLI 内部的预定义工作流，而不是将文本发送给 LLM 进行自由推理。这意味着 /init 的代码库扫描逻辑是确定性的程序行为，而非模型的概率性输出，从而保证了分析结果的可靠性和一致性。

执行命令后，Gemini 会首先在项目根目录创建一个空的 GEMINI.md 文件，然后开始分析代码库。分析完成后，它并不会直接写入内容，而是先展示一个 diff（差异对比），显示它打算写入的内容，并请求你的许可。

权限控制机制

这里涉及 Gemini CLI 一个重要的安全设计：每当 CLI 要修改文件或执行命令时，都会先征求你的同意。Gemini CLI 采用的「先展示 diff 再请求许可」的交互模式，借鉴了 Git 版本控制中的差异对比理念——diff 以红绿色标注删除和新增的内容，让开发者在任何文件变更生效前都能完整审查。

这种 Human-in-the-Loop（人在回路中）的设计是当前 AI Agent 安全框架的核心原则之一：AI 可以提出建议和生成方案，但最终的执行权始终保留在人类手中。这在 AI 编码工具中尤为重要，因为不受控的文件写入可能破坏现有代码、引入安全漏洞，甚至执行危险的系统命令。

你通常有三个选项：

1. Yes, allow once（允许一次）：仅允许本次操作，下次修改时仍会询问
2. Yes, always allow（始终允许）：在当前会话中不再询问写入权限
3. 拒绝并建议修改：你可以对内容提出修改意见

选择第二个选项后，聊天输入框上方会出现 "accepting edits" 的提示，表示当前会话中 Gemini 将自动执行代码变更。如果需要切换回手动确认模式，按 Shift + Tab 即可。

查看自动生成的内容

打开生成的 GEMINI.md 文件，可以看到 Gemini 自动识别出的项目信息：

在本教程的示例项目（一个 Nuxt 3 应用）中，Gemini 识别出了以下内容：

• 项目概述：这是一个 Nuxt 3 Web 应用，用于用户分享和发现有趣的食物搭配
• 开发环境：包括安装指南（npm install）、开发服务器启动方式
• 技术栈：框架为 Nuxt 3，测试使用 VTest
• 项目结构：组件位于 app/components，页面位于对应的 pages 目录
• 样式方案：当前使用单一 CSS 文件

由于示例项目本身比较简单（只有两个页面，没有额外组件），生成的内容也相对精简。

添加个人编码偏好

自动生成的内容只是起点，你完全可以手动编辑 GEMINI.md 文件，补充更多指令。例如，在文件底部添加「额外编码偏好」：

常见的偏好设置包括：

• 不使用分号：JavaScript/TypeScript 代码中省略行尾分号
• 不在模板中使用 Tailwind 类名：即使项目使用了 Tailwind CSS，也倾向于将样式抽离
• 保持组件小而模块化：遵循单一职责原则
• 使用相对导入路径：而非路径别名（path alias）
• 最小化项目依赖：避免引入不必要的包

这些偏好因人而异，关键是将你的编码习惯明确告知 AI，让它生成的代码风格与你保持一致。

刷新内存：让 Gemini 识别文件变更

编辑保存 GEMINI.md 后，还需要执行一个关键步骤：在 Gemini CLI 中运行 /memory refresh 命令。这个命令会告诉 CLI 重新扫描所有 GEMINI.md 文件，确保最新的指令被加载到当前会话中。

执行后，你会看到 "memory was refreshed" 的确认消息，以及 "using 1 Gemini md file" 的提示，说明文件已被成功识别并作为上下文使用。

GEMINI.md 的三级作用域

GEMINI.md 文件支持三个层级的作用域，这是一个非常灵活的设计，能满足不同粒度的配置需求。这种多级作用域遵循了软件工程中经典的「配置继承」模式，类似于 .gitignore、.eslintrc 等工具的多级配置机制。当多个层级的 GEMINI.md 同时存在时，它们的内容会被合并注入上下文，子目录级的指令可以对全局或项目级的规则进行补充或细化。

1. 项目级（根目录）

放在项目根目录的 GEMINI.md 对整个项目生效，这是最常用的方式。适合定义全局的技术栈、架构规范和通用编码风格。

2. 目录级（子目录）

你可以在子目录中创建额外的 GEMINI.md 文件，提供针对特定模块的指令。例如：

• 在 pages/ 目录下创建，专门指导页面组件的生成规范
• 在 tests/ 目录下创建，提供测试编写的具体要求和断言风格

这种设计在 Monorepo（单仓多项目）架构中尤其有价值——根目录定义通用的 TypeScript 规范和 Git 提交约定，而各子包目录则分别声明自己的框架特性（如前端包使用 React、后端包使用 Express）和测试策略。

3. 全局级（用户目录）

在用户主目录的隐藏文件夹 .gemini 中（Mac 在 Home 目录，Windows 在用户配置文件目录），可以创建一个全局的 GEMINI.md 文件。这个文件夹是 Gemini CLI 安装时自动创建的，用于管理全局设置、MCP 服务器、扩展和聊天会话等。

其中，MCP（Model Context Protocol，模型上下文协议）是由 Anthropic 提出并逐渐被行业采纳的开放协议，它定义了 AI 模型与外部工具、数据源之间的标准化通信方式。通过 MCP，Gemini CLI 可以连接数据库查询工具、API 测试服务、文档检索系统等外部能力，将 AI 的作用范围从单纯的代码生成扩展到完整的开发工作流。全局 .gemini 文件夹作为这些配置的统一管理入口，体现了 Gemini CLI 作为开发者 AI 中枢的产品定位。

全局文件中的指令会应用于你所有的项目，适合放置跨项目通用的编码风格和交互偏好。需要注意的是，你需要开启显示隐藏文件才能看到 .gemini 文件夹。

无论在哪个层级添加了新的 GEMINI.md 文件，都建议执行 /memory refresh 确保 CLI 能正确识别。

持续维护的重要性

GEMINI.md 不是一个「创建后就忘记」的文件。随着项目的演进——引入新的服务、调整架构、更换技术栈或改变编码风格——你应该同步更新这个文件。否则，AI 模型将基于过时的信息做出决策，生成的代码可能与当前项目状态不匹配。

对于全新项目，虽然没有现有代码供 Gemini 分析，但你仍然可以先手动写入基本偏好和预期的技术栈，然后在开发过程中逐步完善。

总结

GEMINI.md 是 Gemini CLI 工作流中的核心配置文件，它建立了你与 AI 之间的「编码契约」。通过 /init 命令自动生成基础配置，再手动补充个人编码偏好，配合项目级、目录级、全局级三级作用域的灵活设计，你可以显著提升 AI 生成代码的质量和一致性，减少后续的手动调整工作。在下一篇教程中，我们将正式开始利用配置好的 Gemini CLI 进行代码变更和功能开发。