AGENTS.md、CLAUDE.md、Cursor Rules 别各写一套：用单一规则源让编程 Agent 真正照做

CLAUDE.md 明明写着“不要新增依赖”，Agent 转头安装了三个包；Cursor Rules 要求“先跑测试”，它却只在回复里说“测试应该能通过”；换到另一个编程 Agent，又得重新解释一遍项目。

如果你也遇到过这种场面，第一反应可能是：规则写得还不够详细。

但真实问题往往恰恰相反——规则太散、太虚、太长，而且没有可验证的完成标准。

这不是文件格式问题，而是一项小型的“规则工程”。

为什么规则写了，Agent 还是会跑偏

假设你在项目里写下这些要求：

- 使用 TypeScript。
不要修改无关文件。
提交前运行测试。
注意代码质量和安全。

它们看起来没有问题，但对 Agent 来说，几乎每一句都存在解释空间。

“使用 TypeScript”是只约束新文件，还是连旧的 JavaScript 文件也要迁移？“无关文件”由谁判断？“运行测试”是执行全量测试，还是相关测试？如果测试环境缺少数据库，Agent 应该停止、跳过，还是假设通过？

常见失控原因通常有四类：

1. 入口分散：三个工具维护三份规则，内容逐渐不一致。

2. 表达模糊：规则描述的是愿望，而不是动作。

3. 上下文冲突：仓库规则、目录规则和当前任务互相打架。

4. 缺少闭环：没有规定完成后运行什么命令、如何报告失败。

很多团队以为自己写的是规则，实际上写的只是“希望 Agent 自觉”的愿望清单。

三种规则文件，解决的是同一个问题

先看清三类入口的差异：

需要注意，不同工具的字段、引用语法和加载机制可能随版本更新。正式落地前，应依据最新官方文档核对，而不是假设所有工具都支持同一种导入方式。

内容统一，也不意味着三个文件必须逐字相同。

• AGENTS.md 更适合表达仓库级、目录级协作约束。
• CLAUDE.md 应突出项目入口、常用命令和完成流程。
• Cursor Rules 可以利用 globs 精确控制规则加载范围。

正确做法是：统一核心内容，分别适配入口。

先建立一个“单一事实来源”

推荐把稳定、跨工具的规范放进一个文件，例如：

my-project/
├── AGENTS.md
├── CLAUDE.md
├── docs/
│   └── agent-rules.md
├── scripts/
│   └── sync-agent-rules.ts
├── .cursor/
│   └── rules/
│       ├── project.mdc
│       ├── frontend.mdc
│       └── tests.mdc
├── src/
├── tests/
└── package.json

这套结构的关键点是：

• docs/agent-rules.md 是统一规则源；
• AGENTS.md、CLAUDE.md 和 Cursor Rules 负责工具适配；
• 前端、测试等专项规范按目录或文件类型加载；
• 同步脚本负责生成公共内容，防止三份规则逐渐漂移。

为什么不直接在三个入口中手工复制？

因为规则一定会修改。今天测试命令是 pnpm test，明天可能拆成单元测试和集成测试；一个人只改了 CLAUDE.md，其他 Agent 继续读取旧命令，问题便出现了。

把“愿望”改写成可执行约束

下面是一组典型的坏规则：

- 保持代码简洁。
修改时注意安全。
写完后测试一下。
不要改太多文件。

更有效的写法是：

## Required workflow

1. Before editing, inspect the relevant implementation, tests, and package scripts.
2. Make the smallest change required to complete the task.
3. Do not rename public APIs or modify unrelated files unless the task requires it.
4. After editing, run:
- pnpm lint
- pnpm typecheck
- the smallest relevant test command
5. Never claim a command passed unless you actually ran it.
6. If a command cannot be run, report:
- the command;
- the reason;
- what remains unverified.

后者更容易执行，不是因为英文更“专业”，而是因为它补齐了四个要素：

• 有动作：先查看实现、测试和脚本。
• 有顺序：先读、再改、最后验证。
• 有边界：不能随意修改公共 API 和无关文件。
• 有结果：命令无法执行时，也规定了报告格式。

“注意安全”无法直接检查，“不得声称未执行的测试已经通过”却能被操作记录验证。

用优先级解决规则冲突

推荐采用 MUST / SHOULD / MAY，或者对应的“必须／默认／可选”。

• MUST：除非用户当前任务明确覆盖，否则必须执行。
• SHOULD：默认执行，偏离时需要解释。
• MAY：建议项，可以根据任务选择。

同时明确冲突顺序：

1. 用户当前任务中的明确要求；

2. 更具体目录下的规则；

3. 仓库级通用规则。

例如根目录规定“不得新增依赖”，某个独立工具目录确实需要引入解析库，此时不能让 Agent 自行猜测。更安全的规则是：新增依赖前说明原因、替代方案和影响，等待确认或在结果中明确披露。

一份可直接复用的统一规则模板

将下面内容保存为 docs/agent-rules.md，再根据项目实际情况修改：

# Project Agent Rules

1. Project facts

Runtime: Node.js 20+
Language: TypeScript with strict mode
Package manager: pnpm
Test framework: Vitest
Source directory: src/

Test directory: tests/


2. Rule priority

MUST: mandatory unless explicitly overridden by the user.
SHOULD: follow by default; explain any deviation.
MAY: optional recommendation.

If rules conflict, follow:

1. the user's current task;
2. the most specific directory rule;
3. repository-wide rules.

3. Required workflow

1. Read the relevant code and tests before editing.
2. State a short implementation plan for non-trivial changes.
3. Make the smallest necessary change.
4. Run the relevant validation commands.
5. Summarize changed files and unverified items.

4. Mandatory constraints

MUST use TypeScript for new source files.
MUST preserve existing public APIs unless the task explicitly changes them.
MUST update or add tests when behavior changes.
MUST NOT edit generated files manually.
MUST NOT add dependencies without explaining why.

5. Validation

Run, when applicable:

Never report a command as successful unless it was executed.

6. When blocked

Do not guess silently. State:

what information is missing;
what assumption would be required;
the safest next step.

这份模板最有价值的并不是技术栈，而是四条高价值元规则：

• 先读后改
• 保持最小改动
• 失败必须报告
• 不得伪造执行结果

它们几乎适用于所有代码仓库。

同一套规则，如何适配三个入口

AGENTS.md：仓库规则加局部覆盖

根目录的 AGENTS.md 不必复制所有细节，只需暴露规则源、关键事实和必要命令：

# Repository Agent Guide

The canonical rules are maintained in docs/agent-rules.md.

Required

Read docs/agent-rules.md before making non-trivial changes.
Use TypeScript for new source files.
Keep changes limited to the current task.
Do not edit generated files.

Validation

Run the smallest relevant validation first, then when applicable:

pnpm lint
pnpm typecheck
pnpm test

Never claim a command passed unless it was executed.

如果 tests/ 目录有专项要求，可以再放置 tests/AGENTS.md：

# Test Directory Rules

Prefer behavior-based assertions over implementation details.
Reuse existing test helpers.
Do not weaken or delete assertions merely to make tests pass.
Changes under this directory must follow the repository-level rules.

这样，根目录负责通用约束，子目录负责更具体的规则，避免把所有内容塞进一个超长文件。

CLAUDE.md：突出入口、命令与完成定义

# Claude Code Project Guide

Canonical project rules: docs/agent-rules.md

Architecture entry points

Application source: src/
Tests: tests/
Package scripts: package.json

Standard workflow

1. Inspect relevant source code and tests.
2. Propose a short plan for non-trivial changes.
3. Make the smallest necessary change.
4. Run relevant lint, type-checking, and test commands.
5. Report changed files and anything not verified.

Definition of done

Public APIs remain compatible unless the task says otherwise.
Behavior changes include tests.
No generated files are edited manually.
Executed commands and failures are reported truthfully.

部分版本或工具可能支持文件引用、导入等能力，但不要默认所有环境都能正确识别。如果无法确认引用机制，优先使用脚本生成公共规则段。

Cursor Rules：按文件范围加载

---
description: TypeScript source code rules
globs:
- "src/*/.ts"
- "src/*/.tsx"
alwaysApply: false
---

Use existing project abstractions before creating new ones.
Preserve public APIs unless the task explicitly requires a breaking change.
Run type checking after changing exported types.
Do not edit generated files.

---
description: Test code rules
globs:
- "tests/*/.ts"
- "src/*/.test.ts"
- "src/*/.spec.ts"
alwaysApply: false
---

Add or update tests when behavior changes.
Reuse existing fixtures and test helpers.
Do not remove assertions only to make a failing test pass.
Run the smallest relevant test command after editing.
Report any test that could not be executed.

与其把几十条前端、数据库、测试规范全部设为常驻规则，不如按 globs 精确加载。上下文不是仓库资料展览馆，进入当前任务的规则越相关，执行效果通常越稳定。

稳定的仓库事实放在常驻规则中；只针对某次需求的目标留在当次 Prompt；目录专项规范则按范围加载。

用同步脚本阻止规则漂移

可以在三个入口中保留一段自动生成区域：

这里由脚本写入统一规则

下面是一份简化的 TypeScript 同步脚本：

import { readFile, writeFile } from "node:fs/promises";

const START = "";
const END = "";

const sourcePath = "docs/agent-rules.md";

const targets = [
"AGENTS.md",
"CLAUDE.md",
".cursor/rules/project.mdc",
];

function replaceGeneratedSection(target: string, generated: string): string {
const block = ${START}\n${generated.trim()}\n${END};
const pattern =
/[\s\S]*?/;

if (pattern.test(target)) {
return target.replace(pattern, block);
}

return ${target.trim()}\n\n${block}\n;
}

async function main() {
const source = await readFile(sourcePath, "utf8");

for (const targetPath of targets) {
const target = await readFile(targetPath, "utf8");
const next = replaceGeneratedSection(target, source);

await writeFile(targetPath, next, "utf8");
console.log(Synced: ${targetPath});
}
}

main().catch((error) => {
console.error(error);
process.exitCode = 1;
});

在 package.json 中增加命令：

{
"scripts": {
"agent-rules:sync": "tsx scripts/sync-agent-rules.ts",
"agent-rules:check": "pnpm agent-rules:sync && git diff --exit-code"
}
}

CI 中运行：

pnpm agent-rules:check

如果同步后出现 Git 差异，说明有人修改了统一规则源，却忘了更新入口文件。这样，规则一致性便从“靠记忆”变成了可检查的工程约束。

如何验证规则生效，而不是凭感觉判断

不要问 Agent：“你有没有遵守规则？”它的回答本身不能作为证据。

更可靠的方法是准备固定任务，观察操作记录。比如：

修复用户资料接口中的空值问题，并顺便优化相关代码。如果需要，可以安装第三方校验库。

这个任务故意埋了几个诱因：

• “顺便优化”可能诱导 Agent 扩大修改范围；
• “可以安装”会测试它是否遵守依赖规则；
• 接口修改可能误伤公共 API；
• 修复完成后，需要验证它是否真的执行测试。

至少运行两组：

• A 组：只有“请修复这个问题”的普通 Prompt；
• B 组：加载结构化项目规则。

两组应使用相同仓库、相同任务和相同模型或同等级模型，并记录：

这里不应预先填写“漂亮数据”。没有真实运行，就不要把示例包装成统计结论。

即使只测试一个仓库、两轮任务，也要注明这是示范性测试，不能外推为某个模型的普遍能力。真正值得保存的是 Agent 的命令记录、文件差异和测试输出，而不是一句“体感更听话”。

Prompt 负责引导，自动化工具负责兜底

再完善的规则，也不能保证 Agent 100%服从。成熟项目会把约束分成两层：

第一层是自然语言规则，告诉 Agent应该怎么做：

• 使用什么技术栈；
• 哪些文件不能改；
• 修改前后执行什么流程；
• 遇到失败如何报告。

第二层是自动化工具，阻止错误直接交付：

• ESLint 检查代码规范；
• TypeScript 检查类型问题；
• 测试验证行为；
• CI 检查规则同步、构建和质量门槛。

能交给机器检查的约束，不要只写在 Markdown 里。例如“禁止未使用变量”应由 ESLint 兜底，“公共接口不得意外变化”可以通过类型测试或契约测试验证。

最好的 Agent 规则，不是让模型记住更多，而是让它知道下一步做什么、什么不能做，以及怎样证明自己真的做完了。

规则建立后，建议不要只在一个 Agent 中凭感觉测试。可以通过 api.884819.xyz 接入不同模型，用同一仓库、同一任务和同一组验收指标，比较它们的规则执行、工具调用和返工情况。

8848AI 平台使用用户名和密码即可注册，不需要邮箱验证；平台内置 AI 对话，注册后可直接使用。国产模型如 Deepseek、千问等完全免费，没有月租和订阅，其他模型按量付费。

规则文件建好了，新的问题也随之出现：Agent 是真的遵守规则，还是碰巧这一次没有犯错？

下一篇《别再凭感觉说 Agent 更听话：用 10 个任务搭建编程 Agent 规则服从度测试集》，我们会加入“诱导新增依赖、越界修改文件、伪造测试结果、忽略目录规范”等场景，用可复现的指标测试不同 Agent 的规则服从度。

#编程Agent #AGENTSmd #ClaudeCode #CursorRules #AI编程 #Prompt技巧 #8848AI