AI 编程规则文件越来越乱：AGENTS.md、CLAUDE.md、GEMINI.md 到底留哪个？

同一个项目，换一种 AI 编程工具，就要重新交代一遍规矩。

用 Codex 时写了AGENTS.md，换到 Claude Code 又要准备CLAUDE.md；Cursor 有自己的 Rules，Gemini CLI 还认GEMINI.md。工具用得越多，项目根目录里的规则文件也越多。

最麻烦的还不是文件多，而是内容容易打架：这份要求 Java 17，那份还写着 Java 8；这份让它先跑测试，那份压根没提。

一个项目，真要维护四五份规则吗？

先说结论

• 只用一种工具：直接使用它原生支持的规则文件。
• 同时使用多种工具：选一份公共规则作为主文件，其余文件只做适配。
• 不要复制多份完整内容，否则后面一定会改漏。

目前来看，AGENTS.md的跨工具兼容性比较好，适合作为公共规则的主文件。但它还不是所有工具都原生支持的统一标准，必要时仍要给 Claude Code、Gemini CLI、Cursor 等工具留一个简短入口。

先分清模型和工具

很多人会问：DeepSeek、Qwen、GLM 到底认哪个规则文件？

这个问题其实混淆了模型和工具。

DeepSeek、Qwen、GLM、Gemini 首先是底层模型；Codex、Claude Code、Cursor、OpenCode、Cline 才是负责扫描项目、读取文件和调用模型的编程工具。

模型不会自己跑进项目目录寻找AGENTS.md。真正决定读取哪个文件的，是承载模型的工具。

例如，同样使用 DeepSeek 模型：

• 放在 Cursor 中，主要遵循 Cursor Rules。
• 放在 OpenCode 中，会读取AGENTS.md。
• 放在 Cline 中，则按照 Cline 支持的规则入口加载。

可以把模型理解成发动机，把编程工具理解成整辆车。发动机负责输出动力，车载系统负责读取路线和驾驶规则。

Qwen Code 和 Gemini CLI 虽然分别使用 Qwen、Gemini 模型，但它们本身已经是完整工具，所以又定义了QWEN.md和GEMINI.md。

主流工具分别读取什么

下面这张表不用死记，知道“规则文件跟着工具走”就够了。

因此，DEEPSEEK.md、GLM.md、CLINE.md并不是这些工具当前通用的官方格式。产品更新很快，具体加载顺序仍要以所用版本的官方文档为准。

为什么越来越多项目使用 AGENTS.md

AGENTS.md的优势不是功能更多，而是名字相对中立。

Codex、OpenCode 原生使用它，Cline、Windsurf、Qwen Code 也支持它；Gemini CLI 可以通过配置读取，Claude Code 则可以从CLAUDE.md导入。

所以，多工具协作时，可以把它当成一份“项目入职手册”：无论开发者使用哪种 AI 工具，公共的技术栈、目录边界、构建命令和测试要求都来自同一个地方。

更准确地说，AGENTS.md目前是一个兼容性较好的公共入口，而不是已经一统江湖的行业标准。

多工具项目，推荐这样维护

不要把同一篇规则全文复制到四个文件里。更省心的方式是“一主多适配”：

project/ |-- AGENTS.md |-- CLAUDE.md |-- GEMINI.md |-- QWEN.md `-- .cursor/ `-- rules/ `-- project.mdc

其中：

• AGENTS.md保存所有工具都要遵守的公共规则。
• CLAUDE.md导入主文件，只补充 Claude Code 的特殊要求。
• GEMINI.md导入主文件，或者配置 Gemini CLI 直接读取它。
• QWEN.md只在确实存在 Qwen Code 专属要求时保留。
• Cursor Rules 只放路径匹配、触发范围等 Cursor 专属配置。

例如，CLAUDE.md可以非常短：

@AGENTS.md ## Claude Code 补充规则 - 涉及多个模块的改动，先进入 Plan Mode 梳理影响范围。

GEMINI.md也可以导入同一份公共规则：

@AGENTS.md ## Gemini CLI 补充规则 - 执行可能改变本地环境的命令前，先说明影响。

这样，公共规则只改一次。某个工具有特殊能力或限制，再到对应文件里单独补充。

AGENTS.md 应该写什么

规则文件不是项目百科，更不是越长越好。真正值得写进去的，是 AI 每次动手前都需要知道的内容。

一份实用的AGENTS.md通常包括：

• 项目技术栈和主要目录。
• 构建、测试、格式化命令。
• 团队特有的代码约定。
• 不允许修改的范围。
• 完成任务后的验证要求。

可以直接从下面这个简版开始：

# Project Overview这是一个基于 Java17和 Spring Boot3的订单服务。## Commands- 构建：`mvn clean package-DskipTests`- 测试：`mvntest`## Coding Rules- Controller 不直接访问 Mapper，业务逻辑放在 Service。 - 新增接口必须补充参数校验。 - 不修改与当前任务无关的模块。## Verification- 修改后运行相关单元测试。 - 提交前确认项目能够正常编译。

写规则时记住三个词：简短、具体、可验证。

“请写高质量代码”“遵循最佳实践”这类话几乎没有约束力。相比之下，“Controller 不直接访问 Mapper”“改完运行mvn test”才是工具真正能执行和检查的要求。

规则文件不是强制执行器

这一点很容易被忽略：规则文件本质上是上下文和提示，不是门禁系统。

你可以在文件里要求“提交前必须运行测试”，但遇到上下文过长、任务中断或工具行为变化时，它仍有可能漏掉。

真正不能违反的要求，应该交给自动化机制：

• 用 Git Hooks 或工具自带 Hooks 执行格式化、静态检查。
• 用 CI 强制运行测试和构建。
• 用权限控制保护生产配置、密钥和关键目录。

规则文件负责告诉 AI 应该怎么做，Hooks 和 CI 负责在它没做到时拦下来。两者配合，才比单纯写一大堆“必须”可靠。

到底该怎么选

如果项目只使用 Claude Code，就维护CLAUDE.md；只使用 Cursor，就维护.cursor/rules/。没有必要为了看起来完整，把所有格式都建一遍。

如果团队会混用 Codex、Claude Code、Cursor、Cline 等工具，可以采用下面的方案：

1. 用AGENTS.md保存公共项目规则。
2. 为不能直接读取它的工具建立简短适配文件。
3. 工具专属要求放回各自的规则目录。
4. 强制要求交给 Hooks、测试和 CI。

真正需要统一的不是文件名，而是规则内容的唯一来源。

一句话总结：

模型负责思考，工具负责读取规则；公共规则维护一份，其他文件只做适配。

参考资料

• OpenAI Codex：AGENTS.md：https://developers.openai.com/codex/guides/agents-md
• Claude Code：CLAUDE.md：https://code.claude.com/docs/en/memory
• OpenCode：Rules：https://opencode.ai/docs/rules/
• Gemini CLI：GEMINI.md：https://geminicli.com/docs/cli/gemini-md/
• Qwen Code：Memory 与 QWEN.md：https://qwenlm.github.io/qwen-code-docs/en/users/features/memory/
• Cline：Rules：https://docs.cline.bot/features/cline-rules
• Windsurf / Devin Desktop：Memories 与 Rules：https://docs.windsurf.com/windsurf/cascade/memories

欢迎关注我的公众号【兮动人】，每天分享一些技术文章和实战经验。