多款编程代理如何共享项目规则

dev.to · AI#编程代理#项目规则#配置管理

Editor brief · 编辑速览

文章对比 AGENTS.md、CLAUDE.md、Cursor 与 Windsurf 规则文件的用途和组织方式。建议以共享文件维护通用约定，再添加工具专属配置，减少多份规则复制后的内容漂移。

文章思维导图

Knowledge map

拖拽缩放

Full translation

完整中文译文

不同的 AI 编程工具会查找不同的指令文件。如果你只用一种工具的格式保存规则，其他工具就只能靠猜。如果你把同一大段内容复制到每种格式里，这些副本又会逐渐出现偏差。这篇指南会说明各类文件的用途，并介绍一种便于长期维护的配置方式。

AGENTS.md 是跨工具的开放约定。OpenAI Codex、Cursor 和许多其他 Agent 都会将它作为纯 Markdown 格式的项目指令来读取。

CLAUDE.md 是 Claude Code 的项目记忆文件。它支持通过 @path 语法引入其他文件，例如 @AGENTS.md。

Cursor 的项目规则放在 .cursor/rules/*.mdc 中，使用 YAML frontmatter 配置 description、globs 和 alwaysApply。旧版单文件格式 .cursorrules 已弃用，建议使用 .mdc 规则。

Windsurf 将 Cascade 规则以 Markdown 文件的形式保存在 .windsurf/rules/ 下。

各类文件分别用来做什么

AGENTS.md 是一种简单的开放格式，可以把它理解为写给 Agent 的 README。适合放在这里的是长期有效的项目指导：如何构建和测试、目录结构、约定，以及禁止事项。内容要足够精简，工具才容易遵循。Codex 会沿着仓库根目录到当前工作目录的路径查找项目中的 AGENTS.md 文件；距离当前目录更近的文件可以细化上层规则。可直接复制使用的起步文件：Codex AGENTS.md 模板。

Claude Code 会在会话开始时加载 CLAUDE.md。你可以在这个文件的任意位置使用 @path/to/file，导入更多 Markdown 内容。相对路径以包含这条导入语句的文件为基准解析。常见做法是先用一行导入共享规则，再补充几条 Claude 专属说明：

@AGENTS.md

# Claude Code notes
- Prefer the project package scripts over ad-hoc commands.
- Before touching auth, payments, or migrations: write a short plan and wait for go.

如需更完整的模板，可以参阅免费的 CLAUDE.md 指南。

Cursor .cursor/rules/*.mdc

每条规则都是 .cursor/rules/ 下的一个 .mdc 文件。Frontmatter 决定了规则何时加载：

alwaysApply: true：每次对话都会包含这条规则。
配置 globs 且 alwaysApply: false：上下文中出现匹配的文件时，附加这条规则。
配置 description，但不配置 globs：Cursor 可以在判断规则相关时引入它。
既没有 description，也没有 globs：通过 @rule-name 手动引入。

规则系统会忽略该目录中的普通 .md 文件（没有 frontmatter）。建议使用范围明确的小规则，而不是一个庞大的文件。下面是一条 RLS 规则示例，也可以在 GitHub 上免费获取，文件名为 nextjs-supabase-rls.mdc：

.cursor/rules/30-database-rls.mdc　复制

---
description: Migrations and row-level security
globs: supabase/**
alwaysApply: false
---
- For each new table: enable RLS + policies in the same migration.
- Policies use (select auth.uid()); separate policies per command.
- Never disable RLS to "make it work". Fix the policy instead.

更多 Next.js + Supabase 相关细节，可以参阅《适用于 Next.js + Supabase 的 Cursor 规则》。如果需要 Python 后端骨架，涵盖 venv、pytest 和类型提示，可以参阅《适用于 Python 的 Cursor 规则》。

Windsurf .windsurf/rules/

Cascade 从 .windsurf/rules/ 读取 Markdown 规则，激活方式与 Cursor 类似，包括始终启用、按 glob 匹配或手动启用。保持这些文件精简，并沿用 AGENTS.md 中已有的规则思路。参阅《Windsurf 规则》。

推荐配置：只维护一份权威来源

先写 AGENTS.md，说明技术栈、命令、硬性规则、工作流程和完成标准。
添加一个精简的 CLAUDE.md，以 @AGENTS.md 开头，后面只放 Claude 专属说明。
为需要更精确指导的路径添加限定范围的 Cursor 规则，例如身份验证、RLS、Stripe 和 env。不要把整份 AGENTS.md 粘贴到每个 .mdc 文件中。
如果使用 Windsurf，就把同样的局部规则迁移到 .windsurf/rules/，不要再维护第三份完整的长篇说明。
删除或迁移 .cursorrules，避免继续维护一个 Agent 模式可能会忽略的旧文件。
当某条规则表现不符合预期时，在权威来源中修正它，也就是 AGENTS.md 或对应的那一条局部规则，而不是同时修改三个地方。

repo/
  AGENTS.md                 # shared source of truth
  CLAUDE.md                 # @AGENTS.md + Claude-only notes
  .cursor/rules/
    00-core.mdc             # alwaysApply: true (short)
    30-database-rls.mdc     # globs: supabase/**
    40-stripe.mdc           # globs: app/api/stripe/**
  .windsurf/rules/          # optional mirror for Cascade
    database-rls.md

今天就能直接使用的免费文件

nextjs-supabase-rls.mdc：适用于 Supabase RLS 的 Cursor 规则。
agent-guardrails.md：可用于 AGENTS.md 或 system prompt 的约束规则片段。
agents-md-game-modding.md：适用于游戏模组和小型游戏工具的 AGENTS.md 模板。
godot-jam-timeline.md：供 Agent 使用的 48 小时游戏开发挑战时间表。

我需要同时使用 AGENTS.md、CLAUDE.md 和 .cursor/rules 吗？

只有在使用多种工具时才需要。共享规则放在 AGENTS.md 中。为 Claude Code 准备一份精简的 CLAUDE.md，通过 @AGENTS.md 引入共享规则。需要按路径加载规则时，再为 Cursor 配置限定范围的 .mdc 文件。不要重复保存整篇说明。

.cursorrules 还受支持吗？

它属于旧版格式。建议使用带 frontmatter 的 .cursor/rules/*.mdc，并把剩余内容迁移到这些文件或 AGENTS.md 中。

Claude Code 能读取 AGENTS.md 吗？

它的原生文件是 CLAUDE.md。通过 @AGENTS.md 导入共享规则，就只需要维护一份内容。导入内容会在会话开始时展开。

哪些内容该放进 AGENTS.md，哪些该放进 Cursor 规则？

AGENTS.md：技术栈、命令、禁止事项和完成标准。Cursor .mdc：通过 globs 限定路径范围的指导，让身份验证、迁移或 webhook 相关规则只在对应文件进入上下文时加载。

Windsurf 规则放在哪里？

放在 .windsurf/rules/ 下，使用 Markdown 格式。让它们与 AGENTS.md 保持一致，不要另起一套规则体系。

想把整套工具一次备齐？

省去配置过程。Claude Code Kit（24 美元）包含一份可填写的 CLAUDE.md、6 个遵循最小权限原则的 subagent、10 个斜杠命令、settings.json 权限配置，以及 4 个经过测试的 hook。Vibe Starter Rules Pack（19 美元）包含一组现成的 AGENTS.md + CLAUDE.md、8 条限定范围的 .cursor/rules 规则、12 个斜杠命令 prompt，以及适用于 Next.js + Supabase + Stripe 的上线检查清单。

购买 Claude Code Kit · 24 美元　购买 Vibe Starter · 19 美元　查看全部 5 套工具包

还没准备好购买完整套装？可以先试试 One-File Agent Rules（9 美元），它提供一份适用于任意技术栈的通用 AGENTS.md；也可以通过电子邮件获取免费的 Starter AGENTS.md。

发布首周优惠：截至 2026 年 10 月 28 日，在 Stripe 结账时使用优惠码 LAUNCH，任意工具包均享七折优惠。支持 14 天退款。

本文最初发表于 agentkitdrawer.com。

如需采取进一步操作，你可以考虑屏蔽此人和／或举报滥用行为。