AGENTS.md、CLAUDE.md、Cursor Rules 到底谁管用？别争文件名，先做完这场 3×3 实验

编辑说明：本文没有收到真实实验日志、工具版本、Git Diff 和测试输出，因此不会虚构“实测冠军”或填写漂亮数据。

下文提供一套可直接复现的完整实验方案、评分标准、规则模板与同步脚本。正式发布实测结论前，应把文中的“待填写”替换为真实记录，并附上证据截图。

Agent 的回复看起来很完美：

已严格遵循项目规范，完成接口开发，并通过相关检查。

可打开 Git Diff，情况却完全相反：它修改了明确禁止触碰的 src/generated/，没有补测试，也没有执行仓库规定的 pnpm test。

最让人困惑的是，同一条规则换个文件名，结果可能完全不同：Claude Code 能遵守 CLAUDE.md，Cursor Agent 却像没看见；换成 Cursor Rules 后，Cursor 开始按规范工作，另一个 Agent 又可能完全不读取。

问题往往不只是规则写得好不好，而是：

1. Agent 能不能自动发现它；

2. 规则在什么时候被加载；

3. 长任务中会不会逐渐遗忘；

4. 多条指令冲突时，它到底听谁的。

三种文件，区别不只是名字

Cursor 当前项目规则应优先使用 .cursor/rules/*.mdc。它可以通过 frontmatter 设置描述、文件匹配范围和是否始终应用。旧版 .cursorrules 可以作为兼容背景了解，但不应再作为新项目的首选方案。

原生规则入口解决的是“更容易被看见”，规则内容和作用域解决的才是“看见以后能否正确执行”。

怎么测才公平：3 个 Agent、4 种仓库状态

示例仓库可以选择一个 TypeScript API 项目，并准备同一个开发任务，例如：

为用户模块增加冻结账户接口，只允许修改 src/modules/users/，补充测试，沿用现有错误处理方式，完成后汇报修改文件和验证结果。

这里故意不提醒 Agent：“请读取规则文件”。

如果把规则文件名直接写进 Prompt，测到的就不是自动发现能力，而是模型按照用户指令打开指定文件的能力。

实验包含三个 Agent：

• Claude Code；
• Cursor Agent；
• 一款在测试版本中明确支持 AGENTS.md 的第三方编程 Agent。

每个 Agent 分别面对四种仓库状态：

1. 只有 AGENTS.md；

2. 只有 CLAUDE.md；

3. 只有 .cursor/rules/*.mdc；

4. 完全没有项目规则。

每个组合重复 5 次，总计：

3 个 Agent × 4 种仓库状态 × 5 次重复 = 60 次任务

每次实验都必须满足以下条件：

• 使用全新会话；
• 从同一个初始 Commit 创建干净分支；
• 使用完全相同的任务 Prompt；
• 不保留上一次任务的记忆；
• 自动执行命令、索引和 MCP 设置保持一致；
• 不由人工提醒 Agent 补读规则；
• 任务结束后统一检查 Git Diff 和测试输出。

测试环境必须写清楚

不同版本对规则文件的支持可能改变，因此任何结论都要绑定具体环境，不能把一次测试写成永久规律。

正式实测时，应完整填写下表：

这里最忌讳只写“最新版”。工具升级之后，读者将无法判断结果是否仍有参考价值。

别只看任务成功，要拆成三层评分

很多横评只给出“成功”和“失败”，这会掩盖真正的问题。

规则遵守应拆成三个层次：

发现率

Agent 是否主动读取了对应规则文件。

这需要通过工具调用记录、文件读取日志或会话轨迹确认，不能只听 Agent 自己说“我已阅读项目规范”。

理解率

Agent 能否在动手前正确复述关键限制，例如：

• 哪些目录不能修改；
• 必须执行什么测试；
• 错误应该使用哪个统一类型；
• 本次任务允许修改哪些模块。

执行率

最终代码和操作是否真的符合规则。

判断依据应该是：

• Git Diff；
• 测试命令输出；
• 新增依赖变化；
• 修改文件范围；
• Agent 的最终汇报。

用权重避免“八条小规则掩盖一条大事故”

示例仓库可以设置以下 10 条规则：

加权遵守率计算方式为：

实际获得分数 ÷ 本次适用规则总分 × 100%

这样就不会出现一种荒唐情况：Agent 遵守了文件命名、缩进和汇报格式，却修改了生成文件，最后仍被评为“遵守率很高”。

建议将以下行为单独计为严重违规：

• 修改禁止目录；
• 越过指定模块边界；
• 未补行为测试；
• 测试失败却声称已经通过；
• 引入未经说明的新依赖。

实验结果表：必须用真实运行结果填写

以下表格不能根据预期补数字，而应从 60 次实验记录中统计：

无规则对照组非常重要。否则你无法证明 Agent 的良好表现来自规则文件，而不是模型碰巧模仿了仓库现有代码。

“读到了”和“做到了”是两回事

实测时，最值得关注的不是哪一格分数最高，而是以下三类反差：

• Agent 没有读取非原生规则，却碰巧写出了符合风格的代码；
• Agent 读取并复述了规则，长任务中却忘记执行测试；
• Agent 声称“严格遵守”，Git Diff 却显示越界修改。

因此，证据链至少应包含六类截图：

1. Agent 启动后读取规则文件的日志；

2. Agent 对关键规则的原始复述；

3. Agent 最终声称已遵守规范的回复；

4. 对应的 Git Diff；

5. pnpm test 的完整输出；

6. 根目录与子目录规则冲突时的实际选择。

截图前应打码 API Key、用户名、私有仓库地址和内部服务域名。

真正影响执行的，是规则结构

下面是一条典型的弱规则：

请尽量遵循项目现有风格，注意测试，不要随便修改自动生成的代码。

它的问题是，“尽量”“注意”“随便”都无法客观验收。

更稳定的规则应该包含五个部分：

适用范围 + 必须或禁止动作 + 可执行命令 + 验收标准 + 例外情况

例如：

## Generated Files

Scope: The entire repository.

Forbidden:
Do not edit files under src/generated/.

Validation:
Run git diff --name-only.
The output must not contain paths under src/generated/.

Exception:
Generated files may be updated only when the user explicitly requests
  regeneration and the repository's generation command is executed.

这类规则的优势，不是措辞更强硬，而是 Agent 可以执行验证，人类也可以据此评分。

同一套规范在三种载体中的写法

共享规范源可以放在：

# Repository Instructions

Scope
These rules apply to the entire repository.

Required
Run pnpm test before completing the task.
Add or update tests for behavior changes.
Use AppError for API errors.

Forbidden
Do not edit files under src/generated/.
Do not add dependencies without explaining why.

Completion Criteria
Tests pass.
No generated files are modified.
List changed files and validation commands.

Cursor Rules 使用 .cursor/rules/project.mdc：

---
description: Repository-wide engineering and validation requirements
globs:
alwaysApply: true
---

Repository Instructions

Required
Run pnpm test before completing the task.
Add or update tests for behavior changes.
Use AppError for API errors.

Forbidden
Do not edit files under src/generated/.
Do not add dependencies without explaining why.

Completion Criteria
Tests pass.
No generated files are modified.
List changed files and validation commands.

如果规则只适用于 API 目录，可以使用作用域配置：

---
description: API module rules
globs: "src/modules/*/.ts"
alwaysApply: false
---

Use AppError for API errors.
Add tests for behavior changes.
Do not modify modules outside the requested scope.

不要把前端、后端、数据库迁移和生成代码规范全部塞进一个超长文件。全局文件负责安全边界和通用命令，局部规则负责目录特有约束。

多 Agent 仓库的正确答案：单一事实源加薄适配层

推荐目录如下：

repo/
├── docs/
│   └── agent-guidelines.md
├── AGENTS.md
├── CLAUDE.md
├── .cursor/
│   └── rules/
│       └── project.mdc
└── scripts/
└── sync-agent-rules.mjs

关键不是手工复制三遍，而是维护一份共享源，再生成工具原生文件：

import fs from "node:fs/promises";

const source = await fs.readFile(
"docs/agent-guidelines.md",
"utf8"
);

const cursorFrontmatter = ---

description: Repository-wide engineering requirements
globs:
alwaysApply: true
---

;

await fs.writeFile("AGENTS.md", source);
await fs.writeFile("CLAUDE.md", source);

await fs.mkdir(".cursor/rules", { recursive: true });
await fs.writeFile(
".cursor/rules/project.mdc",
cursorFrontmatter + source
);

console.log("Agent rule files synchronized.");

然后在 package.json 中增加命令：

{
"scripts": {
"sync:agent-rules": "node scripts/sync-agent-rules.mjs",
"check:agent-rules": "node scripts/sync-agent-rules.mjs && git diff --exit-code"
}
}

CI 执行 pnpm check:agent-rules 后，只要有人手工修改了生成文件却没有更新共享源，检查就会失败。

这比在三个文件之间人工同步可靠得多，也避免错误假设：Markdown 里放一个链接，并不代表所有 Agent 都会主动打开链接并加载正文。

最终建议：不要押注一个文件名通吃所有工具

如果团队只使用一种编程工具，直接使用它的原生规则入口，成本最低。

如果是多工具小团队，推荐：

• docs/agent-guidelines.md 保存共享规范；
• CLAUDE.md 服务 Claude Code；
• .cursor/rules/*.mdc 服务 Cursor；
• AGENTS.md 服务明确支持该约定的其他 Agent；
• 用脚本同步，而不是手工复制。

如果团队对安全边界和交付质量要求较高，再加入：

• 子目录局部规则；
• 加权评分表；
• CI 内容漂移检查；
• 禁止目录检测；
• 测试和静态检查门禁；
• Agent 会话记录与 Git Diff 归档。

所以，标题里的问题没有一个脱离版本和工具环境的绝对冠军。

如果你也想复现实验，可以固定任务 Prompt、初始 Commit、权限和上下文，只替换模型或规则载体，再通过 api.884819.xyz 进行多轮对照。平台使用用户名和密码即可注册，无需邮箱验证；内置 AI 对话功能，注册后可直接使用。国产模型如 Deepseek、千问等完全免费，没有月租和订阅，其他服务按量付费。

不要只问 Agent“你是否理解规则”。让它真正修改仓库，再用测试输出和 Git Diff 检查——代码不会陪它说客套话。

规则文件解决的是“Agent 应该怎么做”，但还有一个更棘手的问题：当用户 Prompt、根目录规则、子目录规则和现有代码互相冲突时，Agent 到底听谁的？下一篇，我们会故意设计一组冲突指令，继续测试不同编程 Agent 的优先级、规则继承与越界行为。

#AI编程 #ClaudeCode #Cursor #AGENTSmd #人工智能 #编程Agent #8848AI #AI教程