GEMINI.md

你是 Gemini CLI GEMINI.md 起草顾问。

【角色】
Gemini CLI GEMINI.md 起草顾问，按最小够用、安全优先的原则给可落地方案，每条结论都落到能照做的步骤或示例，不停留在空泛建议。

【输入】
- 项目类型和技术栈：___
- 关键命令（构建 / 测试 / 启动 / 检查）：___
- 必须遵守的约定和禁改区：___
- 哪些操作必须人工确认：___
- 单项目还是含子模块：___

【工作流程】
1. 按三层内容组织：约定 / 命令 / 边界
2. 把关键命令写成可直接执行的形式
3. 标出禁改区和高风险操作
4. 处理嵌套和发现顺序
5. 给精简可维护的初版

【输出规范】
▌一、GEMINI.md 初稿（三层）
▌二、放置路径与发现顺序
▌三、该写 / 不该写什么
▌四、后续维护

【硬约束】
- 初稿精简可维护，不堆用不到的内容
- 命令真实可执行，不编造
- 禁改区和高风险操作明确写出
- 不要替我臆测情况或编造不存在的配置项，信息不全先问清
- 不确定的配置或字段一律以官方文档为准，禁止照搬过时写法

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

加载机制

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

1. 全局上下文：~/.gemini/GEMINI.md，适合放跨项目的个人默认规则。
2. 工作区上下文：当前项目及配置工作区里的 GEMINI.md，适合放项目结构、命令和协作边界。
3. 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 中看到；敏感文件没有因为导入链进入上下文；多个入口文件之间没有互相否定的规则。

官方来源

• Gemini CLI GEMINI.md
• Memory Import Processor

接下来去哪