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


![image.png](https://developer.qcloudimg.com/http-save/yehe-2726701/ace16e3a0c2e6436fd3ae361faefad52.png)

同一个项目，换一种 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 等工具留一个简短入口。

## 先分清模型和工具

![image.png](https://developer.qcloudimg.com/http-save/yehe-2726701/dbba9b4d3154226db161e4feb6b414ef.png)



很多人会问：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`。

## 主流工具分别读取什么

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

| 编程工具 | 主要规则入口 | 补充说明 |
| --- | --- | --- |
| OpenAI Codex | `AGENTS.md` | 支持目录分层和 `AGENTS.override.md` |
| Claude Code | `CLAUDE.md`、`.claude/rules/*.md` | 可在 `CLAUDE.md` 中用 `@AGENTS.md` 导入公共规则 |
| OpenCode | `AGENTS.md` | 找不到时可回退读取 `CLAUDE.md` |
| Cursor | `.cursor/rules/*.mdc` | `.cursorrules` 是旧格式 |
| Gemini CLI | `GEMINI.md` | 可导入其他文件，也可配置上下文文件名 |
| Qwen Code | `QWEN.md`、`AGENTS.md` | 两种入口都能使用 |
| Cline | `.clinerules/` | 也兼容 `AGENTS.md` 等常见规则文件 |
| Windsurf / Devin Desktop | `AGENTS.md`、`.devin/rules/*.md` | 旧项目中也可能见到 `.windsurfrules` |

因此，`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` 目前是一个兼容性较好的公共入口，而不是已经一统江湖的行业标准。

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

![image.png](https://developer.qcloudimg.com/http-save/yehe-2726701/389ce36cad29bb70ca92dc5ce4d90216.png)


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

```text
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` 可以非常短：

```markdown
@AGENTS.md

## Claude Code 补充规则

- 涉及多个模块的改动，先进入 Plan Mode 梳理影响范围。
```

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

```markdown
@AGENTS.md

## Gemini CLI 补充规则

- 执行可能改变本地环境的命令前，先说明影响。
```

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

## AGENTS.md 应该写什么

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

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

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

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

```bash
# Project Overview

这是一个基于 Java 17 和 Spring Boot 3 的订单服务。

## Commands

- 构建：`mvn clean package -DskipTests`
- 测试：`mvn test`

## 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
```

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


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

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

人工智能

开发工具

后端

AI编程工具规则文件管理指南：推荐使用AGENTS.md作为主规则文件，其他工具通过简短适配文件补充特殊要求。避免内容重复，确保公共规则统一维护，提高多工具协作效率。技术栈、构建命令、代码规范等关键信息应简洁具体，配合自动化机制确保执行。

单元测试

代码解释

AI编程

DeepSeek

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

AI 编程规则文件越来越乱：AGENTS.md、CLAUDE.md、GEMINI.md 到底留哪个？-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐