Tbye.
返回手记
AI 工具··7 min read

Google 的 design.md，其实是 GEMINI.md

很多人把给 AI Agent 的项目说明文件笼统叫成 design.md，但在 Gemini CLI 里，官方方案其实是 GEMINI.md。本文讲清它是什么、为什么有用，以及怎么写才不会把上下文变成噪音。

Google 的 design.md，其实是 GEMINI.md

这两个月，越来越多人开始给 Agent 配“项目说明书”：告诉它代码风格、测试要求、目录约定、你讨厌什么、它该先做什么。很多人随手把这种文件叫成 design.md，但如果你看的对象是 Google 的 Gemini CLI，官方名字其实不是这个，而是 GEMINI.md。

这不是文件名抠字眼，而是一个很实际的工作流问题：你到底是在写文档给人看，还是在写上下文给 Agent 用？ 如果没分清，最后很容易变成 README 越写越长，Agent 却还是抓不到重点。

GEMINI.md 到底是什么？

Gemini CLI 官方文档对它的定义很直接：这是给模型提供“instructional context”的上下文文件。你可以把项目规则、角色设定、代码规范、执行偏好放进去，CLI 会在对话时自动把这些内容送给模型。

换句话说，GEMINI.md 更像是 “给 Agent 的操作手册”，不是产品文档，也不是架构白皮书。它解决的是一个很朴素的问题：别让我每次都重新教 AI 一遍。

为什么它比一长串 prompt 更重要？

因为 prompt 是一次性的，GEMINI.md 是持续生效的。

Google 的文档里提到，Gemini CLI 会按层级加载上下文：先读全局的 ~/.gemini/GEMINI.md，再读项目目录里的 GEMINI.md，必要时还会在工具访问某个子目录时，按路径继续查找更细粒度的上下文文件。这个设计非常关键，它意味着：

  • 全局习惯 可以写一次，到处复用
  • 项目规范 可以跟着仓库走，不用粘在聊天里
  • 局部规则 可以只在需要时生效，不必把所有细节都塞进主 prompt

我的理解是：GEMINI.md 真正值钱的地方，不是“它能让模型更聪明”，而是它能让模型少犯那些本来不该反复犯的低级错误。

怎么写，才是真的好用？

我更建议把它当成一份可执行约束来写，而不是情绪化许愿单。

一个好用的 GEMINI.md，通常至少应该包含四类信息：

  1. 项目目标：这个仓库是干什么的，什么结果算完成。
  2. 工程约束：技术栈、命令、测试方式、禁止事项。
  3. 输出偏好：回答简洁一点、先给 diff、不要随意改接口、改完必须跑测试。
  4. 目录级规则：哪些目录有特殊规范，哪些文件不能碰。

Gemini CLI 文档还给了两个很有用的能力。

第一是 imports。你可以在 GEMINI.md 里用 @file.md 引入别的说明文件，把规则模块化，而不是把所有东西糊成一个大杂烩。

第二是 自定义文件名。官方说明里明确写到，你可以在 settings.json 里通过 context.fileName 指定别的名字，甚至同时支持多个名字，比如 AGENTS.md、CONTEXT.md、GEMINI.md。这点很妙：Google 实际上并不执着于“GEMINI”这个品牌名本身，它更在乎的是上下文加载机制。

真正容易踩的坑

最大的坑不是不会写，而是写太多、写太虚、写太像公司价值观。

如果你的文件里全是“请高质量完成任务”“注意代码优雅”“保持最佳实践”这种正确废话，Agent 当然会点头，但它还是不知道：

  • 新增功能要不要补测试？
  • 失败后是重试还是停下？
  • 提交前要不要跑 lint 和 build？
  • 遇到大改动时，是先出计划还是直接改？

GEMINI.md 最怕的不是短，而是没有操作性。它应该尽量写成能触发具体行为的规则，而不是写成让人心情很好的口号。

另外，Gemini CLI 还把“记忆”拆成了两层：GEMINI.md 更像长期规则，save_memory//memory 更适合保存事实，而 Auto Memory 则尝试把反复出现的流程抽成技能。这个分层我很认同，因为很多团队的问题并不是“没有记忆”，而是把规则、事实、流程全堆进同一个地方，最后谁都不好维护。

我的结论

如果你最近在研究所谓的 design.md 工作流，我会给一个更直接的判断：在 Gemini CLI 语境里，最值得学的不是那个名字，而是它背后的上下文工程。 官方给你的核心武器其实是 GEMINI.md。

别把它写成第二份 README，也别把它写成老板致辞。把它写成一份真正能约束 Agent 的项目操作手册，你会立刻感觉到差别：废话变少了，返工变少了，很多本来要靠你手动纠正的细节，终于能在系统层提前发生。

说白了，GEMINI.md 不是什么神秘黑科技，它只是把一句很朴素的话落成了文件：“这些事，你以后别再让我重复说第二遍。”

参考资料

  1. Gemini CLI Docs, Provide context with GEMINI.md files. https://www.geminicli.com/docs/cli/gemini-md/
  2. Gemini CLI Docs, Manage context and memory. https://www.geminicli.com/docs/cli/tutorials/memory-management
  3. Gemini CLI Docs, Auto Memory. https://www.geminicli.com/docs/cli/auto-memory
  4. Google, Gemini CLI: your open-source AI agent. https://blog.google/innovation-and-ai/technology/developers-tools/introducing-gemini-cli-open-source-ai-agent/
  5. google-gemini/gemini-cli, README.md. https://github.com/google-gemini/gemini-cli