GEMINI.md 多文件使用方法

技术

发布日期: 2025-07-04

　　本文档旨在详细说明在 Gemini CLI Agent 中如何有效利用多个 GEMINI.md 文件来管理项目配置和行为。通过理解其层级读取和指令覆盖机制，您可以为项目的不同部分提供精细化的指令。

1. GEMINI.md 文件的作用

　　GEMINI.md 文件是为 Gemini CLI Agent 提供项目特定上下文和指令的关键。它允许您定义：

项目约定: 编码风格、命名规范、文件结构等。
工具使用: 特定工具的调用方式、参数配置。
工作流程: 自动化任务的步骤、验证流程。
安全指南: 敏感操作的注意事项、权限要求。

2. 多个 GEMINI.md 文件的读取机制

　　当项目中存在多个 GEMINI.md 文件时，Gemini CLI Agent 会遵循以下规则进行读取和应用：

层级读取: Agent 会从当前工作目录开始，向上遍历所有父级目录，直到文件系统的根目录。在此路径上找到的所有 GEMINI.md 文件都将被读取。
指令合并与覆盖:
- 所有读取到的 GEMINI.md 文件中的指令会被合并。
- 如果低层级（即更接近当前工作目录）的 GEMINI.md 文件中的指令与高层级（即更接近文件系统根目录）的指令发生冲突，低层级的指令将覆盖高层级的指令。

　　这一机制允许您在项目的特定子模块或任务中定义更具体、更优先的行为，同时保留一个通用的基础规则集。

3. 设计多个 GEMINI.md 的策略

　　为了最大化 GEMINI.md 文件的效用，建议采用以下设计策略：

项目根目录的通用配置:
- 在项目的根目录（例如 /my_project/GEMINI.md）放置一个通用的 GEMINI.md 文件。
- 此文件应包含适用于整个项目的通用规则、编码风格、默认测试命令、通用构建流程、以及任何全局性的安全或性能指导。
子项目/模块的特定配置:
- 在项目��特定子项目或模块目录中（例如 /my_project/src/backend/GEMINI.md 或 /my_project/src/frontend/GEMINI.md）放置额外的 GEMINI.md 文件。
- 这些文件可以包含：
  - 该子模块特有的构建或测试命令（例如，后端可能使用 Maven，前端可能使用 npm）。
  - 该模块的特定编码约定或设计模式（例如，前端可能遵循 React Hooks 规范，后端可能遵循 RESTful API 设计）。
  - 针对该模块的特定安全或性能考量。
  - 该模块的特定依赖管理说明。
特定任务/工作流的配置:
- 如果存在非常特定的任务或自动化工作流，可以在其对应的目录中放置一个 GEMINI.md 文件。
- 例如，一个 /my_project/docs/GEMINI.md 文件可以定义文档生成或部署的特定步骤和工具。
- 一个 /my_project/tests/GEMINI.md 文件可以详细说明如何运行集成测试或端到端测试。

4. 示例场景

　　考虑以下项目结构：

/my_project
├── GEMINI.md             # 通用项目规则 (例如：所有文件使用 Prettier ��式化)
├── src/
│   ├── backend/
│   │   ├── GEMINI.md     # 后端特定规则 (例如：Java 代码使用 Checkstyle 检查)
│   │   └── ...
│   ├── frontend/
│   │   ├── GEMINI.md     # 前端特定规则 (例如：TypeScript 代码使用 ESLint 检查)
│   │   └── ...
├── docs/
│   └── GEMINI.md         # 文档生成规则 (例如：使用 Sphinx 生成文档)
└── tests/
    └── GEMINI.md         # 测试运行规则 (例如：运行 Jest 测试)

在 /my_project/src/backend/ 目录下工作时: Agent 会读取 /my_project/GEMINI.md 和 /my_project/src/backend/GEMINI.md。如果 /my_project/GEMINI.md 定义了通用的代码格式化规则，而 /my_project/src/backend/GEMINI.md 定义了 Java 代码的特定格式化规则，则后者将优先。
在 /my_project/ 目录下工作时: Agent 只会读取 /my_project/GEMINI.md，并应用其中定义的通用规则。