AI 编程 · 规则文件

我的 AI 工具到底读哪个规则文件？
AGENTS.md、CLAUDE.md、.cursorrules、copilot-instructions

每个 AI 编程工具都长出了自己的「规则文件」:一个丢在仓库里的纯 .md,告诉 agent 怎么干活。麻烦在于它们各取了不同的名字。Claude Code 要 CLAUDE.md,Copilot 要 copilot-instructions.md,Cursor 要 .cursor/rules,还有一个叫 AGENTS.md 的通用标准正在铺向所有工具。

这篇就是那张地图:哪个工具真正读哪个文件、各自放在哪,以及把它们串起来的那一个共同点(它们全都只是 markdown)。

快速对照：按工具

工具 它读的规则文件 放在哪
Claude Code CLAUDE.md（也读 AGENTS.md） 仓库根目录，或全局放 ~/.claude/
Cursor .cursor/rules/*.mdc（旧版：.cursorrules） .cursor/rules/ 文件夹，旧版放仓库根
GitHub Copilot .github/copilot-instructions.md（也读 AGENTS.md） 仓库根目录下的 .github 文件夹
OpenAI Codex AGENTS.md 仓库根目录，或全局放 ~/.codex/
Windsurf .windsurf/rules/（旧版：.windsurfrules） .windsurf/rules/ 文件夹，旧版放仓库根
Gemini CLI GEMINI.md（也读 AGENTS.md） 仓库根目录

各工具的支持会随版本变化(尤其是对通用标准的兼容),拿不准时查你工具的最新文档。但趋势很清楚:越来越多工具也开始读 AGENTS.md。

AGENTS.md：跨工具的标准

如果说有个赢家在冒头,那就是 AGENTS.md。它是开放格式、由 Linux 基金会托管,被越来越多 agent 读取,包括 Cursor、Codex、Claude Code、Copilot、Windsurf、Gemini。把它想成一份写给 agent 而非人看的 README:AI 需要的构建步骤、测试、约定,从你给人看的 README.md 里挪出来单放。

里面具体写什么,看 AGENTS.md / CLAUDE.md 是什么？

各工具专属的那些

  • CLAUDE.md 是 Claude Code 的。和 AGENTS.md 一个思路,只是 Claude 专属的名字。Claude Code 从仓库根读它,也从 ~/.claude/ 读一个全局的。
  • .cursorrules 和 .cursor/rules/*.mdc 是 Cursor 的。老格式是仓库根一个 .cursorrules 文件;新格式是 .cursor/rules/ 里一个或多个 .mdc 文件(.mdc 就是带一小段作用域头信息的 markdown)。
  • copilot-instructions.md 是 GitHub Copilot 的,放在 .github/ 里。细节看 copilot-instructions.md 是什么？

它们的共同点：全都是 markdown

抛开不同的文件名,这些每一个都是纯 markdown 文件。标题、列表、代码块,没别的了。下面是一份小小的 AGENTS.md,而 CLAUDE.md 或 .cursorrules 长得一模一样:

# AGENTS.md

## Commands
- Build: npm run build
- Test: npm test

## Code style
- TypeScript, 2-space indent
- No default exports

## Boundaries
- Never edit files under /vendor

正因为全是 markdown,你用同一种方式打开、读、改任何一个,不用每种格式配专门工具、不用插件。还没搞懂语法,先看 Markdown 怎么写。

当你手上同时有好几个

真实仓库常常不止一个:一个 AGENTS.md、一个 CLAUDE.md、一个 .cursor/rules/ 文件夹,可能还有 .github/copilot-instructions.md。让它们保持一致(并搞清哪个是唯一真相源)是另一桩小活。这个看 AI 编程规则文件怎么管理,那篇讲的是整理一整堆、而不是选一个。

用 NoteLoom 读、对照这些文件

要把这些文件并排读(或者把那个因为放错位置被工具忽略的清理一下),你需要一个能打开仓库文件夹、渲染 markdown 的编辑器。NoteLoom 就干这个,直接在浏览器里:挂载文件夹,reading 视图把 AGENTS.md、CLAUDE.md 等 .md 规则文件显示成干净排版,source 视图让你改、存回本地。

先说清边界:NoteLoom 没有任何 AI。它不会让 Cursor 或 Claude 听你的规则,也不连接任何编程工具。它只打开、显示、存回 markdown 文件本身。规则、以及 agent 到底听不听,完全在你和你的工具之间。

用起来:用 Chrome / Edge / Arc 打开 app.noteloom.cc,挂载你的项目文件夹,打开任意 .md 规则文件(如 AGENTS.md、CLAUDE.md)读或改。直接存回本地,不上云、不用账号。

相关阅读

AGENTS.md / CLAUDE.md 是什么？ 规则文件里写什么、怎么写一份。 copilot-instructions.md 是什么？ GitHub Copilot 的规则文件：放哪、写什么。 AI 编程规则文件怎么管理？ 一堆 AGENTS.md、CLAUDE.md、.cursorrules 怎么整理。 README.md 是什么？ 给人看的那个文件，以及 AGENTS.md 和它的区别。 网页版 Markdown 编辑器 打开仓库文件夹，浏览器里读写任意 .md。

FAQ

AI 编程工具的规则文件是什么？
一个放在仓库里的纯 markdown 文件，告诉 AI agent 怎么在你的项目上干活：技术栈、要跑的命令、约定、边界。工具在会话开始时读它。不同工具找的文件名不同，混乱就来自这里。
AGENTS.md 和 CLAUDE.md 有什么区别？
CLAUDE.md 是 Claude Code 自己的规则文件。AGENTS.md 是跨工具的开放格式，很多 agent 现在都读（Cursor、Codex、Copilot 等）。Claude Code 读 CLAUDE.md，也越来越多地识别 AGENTS.md。想要一个大多数工具都认的文件，AGENTS.md 更保险；CLAUDE.md 是 Claude 专属的那个。
Cursor 读哪个规则文件？
新版 Cursor 读 .cursor/rules/ 文件夹里的 .mdc（markdown）文件。老的单个 .cursorrules（放仓库根目录）仍然有效，但 Cursor 现在推荐 .cursor/rules/ 格式。Cursor 也认 AGENTS.md。
copilot-instructions.md 放在哪？
GitHub Copilot 读 .github/copilot-instructions.md，所以它在仓库根目录的 .github 文件夹里。具体写什么，看专门那篇 copilot-instructions.md 指南。
这些文件都只是 markdown 吗？
是。AGENTS.md、CLAUDE.md、.cursorrules、copilot-instructions.md、Cursor 的 .mdc 全都是纯 markdown（.mdc 就是顶部带一小段头信息的 markdown）。所以你能用同一个 markdown 编辑器打开、读、改任何一个，不用每种格式配专门工具。
NoteLoom 能帮我读、对照这些文件吗？
NoteLoom 打开你的仓库文件夹，把任何这些 .md 在 reading 视图渲染成干净排版，在 source 视图里改、存回本地。它没有任何 AI：不会让你的编程工具听话，只帮你读写文件本身。
手机或 Safari 能用 NoteLoom 弄吗？
目前不行。NoteLoom 依赖浏览器的 File System Access API，当前支持 Chrome、Edge、Arc 这类 Chromium 系桌面浏览器；Firefox、Safari 和手机端暂不支持。

打开你的规则文件，好好读一遍

用 Chrome / Edge / Arc 打开 NoteLoom,挂载你的项目文件夹,在干净视图里读或改任意 AGENTS.md、CLAUDE.md 等 .md 规则文件。直接存回本地,不用装软件,也不用注册账号。

打开 NoteLoom 试试