AGENTS.md / CLAUDE.md 是什么？
它是写给 AI 编程工具看的规则文件
AGENTS.md 是什么？它是一个写给 AI 编程工具看的规则文件。你用 Claude Code、Codex、Cursor 这类工具时，它们干活前会先读项目里的 AGENTS.md，把里面的话当成「这个项目要遵守的规矩」。
它就是个普通 Markdown 文件，放在项目根目录。Claude Code 读的那份习惯叫 CLAUDE.md，作用一样——告诉 AI：这个项目是什么、用什么技术、哪些事能做、哪些别碰。
所以你看到项目里多出一个 AGENTS.md 或 CLAUDE.md，不用慌。它不是代码，是一份用人话写的「项目须知」，只不过这次的读者是 AI 而已。
如果你连 md 这个格式本身都还没搞清，先看 Markdown 是什么，再回来读这篇会更顺。
AGENTS.md、CLAUDE.md 到底是什么
- 一句话：你提前写给 AI 编程工具的「常驻指令」。每次它开工，先把这个文件读一遍，照着办。
- 格式：纯文本 + Markdown 语法，扩展名
.md，和 README 一样的写法。 - 位置：约定俗成放在项目根目录，文件名通常全大写（
AGENTS.md/CLAUDE.md）。 - 和聊天框输入的区别：聊天框里的话只对这一次有效；写进
AGENTS.md的规则，是每次都生效的「长期记忆」，不用每次重复交代。
为什么最近到处冒出这个文件
这几年用 AI 写代码的人多了。Claude Code、Codex、Cursor 这类工具能直接读你的项目、改你的文件，但它一开始并不知道你的项目有什么讲究。
于是大家发现：与其每次开新对话都把「我们用 TypeScript、提交信息写中文、别动那个配置」重复一遍，不如写进一个固定文件，让工具自己去读。
AGENTS.md 和 CLAUDE.md 就是这么来的。它不是某个新发明的神秘格式，而是一份「我懒得每次都说一遍，干脆写下来」的备忘——只是这份备忘是给 AI 看的。
你会在哪里见到 AGENTS.md / CLAUDE.md
| 场景 | 你会看到什么 |
|---|---|
| 让 AI 编程工具帮你初始化项目 | 它可能顺手生成一个 AGENTS.md 或 CLAUDE.md，写上项目结构和约定 |
| clone 别人的开源仓库 | 根目录有 AGENTS.md，是作者留给 AI（和你）的项目规矩 |
| 工具提示你「建一个规则文件」 | 比如 Claude Code 会建议你写 CLAUDE.md，好让它更懂你的项目 |
| 团队里有人配好了 | 别人写好的规则文件，你接手项目时一起拿到 |
文件名对照：哪个工具读哪个
不同工具认的文件名不完全一样。下面是常见的几个，具体以你在用的那个工具的官方文档为准，这块更新很快。
| 文件名 | 大致是给谁看的 | 一句话 |
|---|---|---|
AGENTS.md | 一个较通用的约定，越来越多 AI 编程工具（如 Codex 等）支持 | 想写一份「大多数 agent 都能读」的说明时用它 |
CLAUDE.md | Claude Code | Claude Code 每次开工前会读的项目记忆 |
.cursorrules / .cursor/rules/ | Cursor | Cursor 的项目规则 |
.github/copilot-instructions.md | GitHub Copilot | Copilot 的项目级指令 |
不用全部都建。你用哪个工具，就照那个工具的约定写一份；有的工具也能读通用的 AGENTS.md。
里面通常写什么、怎么读懂
打开一份 AGENTS.md，内容一般围绕这几块。看的时候不用逐字读，对照下面这张表扫一遍，就知道作者在交代什么。
| 小节 | 通常写什么 | 你读它是为了知道 |
|---|---|---|
| 项目概览 | 这是什么项目、用什么技术栈 | 一句话搞清项目是干嘛的 |
| 怎么跑起来 | 安装、启动、构建、测试的命令 | 接手后怎么把它运行起来 |
| 代码约定 | 命名风格、目录结构、用哪些库 | 改东西时要顺着什么规矩 |
| 不要做的事 | 别动哪些文件、别用哪些写法 | 哪些是雷区，碰了会出问题 |
| 其他上下文 | 业务背景、历史决定、注意事项 | AI（和你）容易踩坑的地方 |
读懂它的诀窍：先看「项目概览」确认是不是你要的，再看「不要做的事」避开雷区，剩下的等真要动手时再细看。它是一份说明，不是非得一口气读完的文章。
它和 README.md、plan.md 不是一回事
这三个文件长得像，但用途不同，别混。
- README.md：项目的说明书，主要给人看——这是什么、怎么装、怎么用。详见 README.md 是什么。
- plan.md：AI 某一次帮你规划、生成的计划文档，记的是「这件事打算怎么做」。怎么读它见 Codex plan.md 怎么读。
- AGENTS.md / CLAUDE.md：你写给 AI 编程工具看的常驻规则，每次它干活都先读，约束它怎么做事。
简单分：README 给人看，plan 是一次性的计划，AGENTS.md 是长期生效的规矩。
用 NoteLoom 打开本地的 AGENTS.md
不管这个文件是 AI 生成的、还是你自己要写的，落到硬盘上它都只是一个本地 .md 文件。NoteLoom 就是个在浏览器里读写本地 md 文件的编辑器，拿来打开 AGENTS.md 正合适。
先说清楚边界：NoteLoom 没有任何 AI，也不和 Claude Code、Codex、Cursor 集成。它不替你写规则、不总结、不理解你的项目，更不会去执行 AGENTS.md 里的话。它只负责让你把这个文件打开、看清、改好、存回本地。
它给你三个视图来读同一个文件：
| 视图 | 对读 / 改 AGENTS.md 的帮助 |
|---|---|
reading（阅读） | 把规则文件渲染成排版后的样子，安静读完，看清有几节、各管什么（只读，改不了） |
live（编辑） | 边看排版边改，给某条规矩补一句、改个命令很顺手 |
source（源码） | 看原始 Markdown 符号，想确认列表、代码块写得对不对时用 |
用起来大致是这样：
- 用 Chrome、Edge 或 Arc 打开
app.noteloom.cc。 - 选中
AGENTS.md所在的那个本地文件夹（NoteLoom 必须先挂载文件夹才能读写）。 - 在文件树里点开
AGENTS.md或CLAUDE.md。 - 先用
reading视图看排版，要改就切到live或source。 - 改完直接写回本地原文件，不经过账号，也不上云。
AGENTS.md 怎么写：一个够用的例子
不用搞复杂。第一版能交代清楚「项目是什么、怎么跑、别碰什么」就够用了。一个够用的样子：
# AGENTS.md
## 项目是什么
一个用 Astro 写的个人博客，部署在 Cloudflare Pages。
## 怎么跑起来
- 装依赖：npm install
- 本地预览：npm run dev
- 构建：npm run build
## 写代码要守的规矩
- 用 TypeScript，不要用 any
- 组件放 src/components/，一个组件一个文件
- 提交信息用中文，一句话说清改了什么
## 不要做的事
- 不要改 src/config.ts 里的部署配置
- 不要把密钥写进代码几个要点：
- 用大白话，别堆术语。它是说给人和 AI 都能看懂的话。
- 写具体的、容易出错的约定，比如「提交信息用中文」「别动那个配置文件」，这些比泛泛的「代码要规范」有用得多。
- 短就行，一两屏内能读完最好；太长 AI 和你自己都容易跳过。
- 想把
#、-、代码块这些符号敲对，看 Markdown 怎么写。
写的时候在 live 视图边敲边看排版就好，要敲什么内容、定什么规矩还是你自己说了算——NoteLoom 不会替你生成，它没有 AI。
常见的坑
- 用记事本打开是一堆
#和-：那是没渲染，不是文件坏了。换一个能显示 Markdown 排版的编辑器就正常了。 - 以为只有程序员要管它：不写代码也会遇到——你让 AI 帮你做个小工具、整理个项目，它就可能给你建一个。把它当项目须知读就行。
- 写得太长太全：几百行的规则文件，AI 和你都懒得读。挑最关键、最容易踩坑的几条写。
- 以为工具一定会严格照做：
AGENTS.md是「强烈建议」，不是硬性锁。AI 大体会参考，但不保证每条都执行，关键改动还是自己复查一遍。 - 指望 NoteLoom 帮你理解或执行它：不会。NoteLoom 只打开、读、改、存这个本地文件，不连任何 AI 工具，也不跑里面的规则。
FAQ
AGENTS.md 和 CLAUDE.md 有什么区别？
AGENTS.md 必须放在项目根目录吗？
我不写代码，需要管 AGENTS.md 吗？
AGENTS.md 和 README.md 是一个东西吗？
AI 编程工具一定会严格按 AGENTS.md 执行吗？
NoteLoom 能帮我自动生成或总结 AGENTS.md 吗？
手机或 Safari 能用 NoteLoom 打开 AGENTS.md 吗？
打开你的 AGENTS.md 看看
把项目文件夹挂进 NoteLoom，用 reading 视图把 AGENTS.md 读清楚，要改就切 live 改完存回本地——不用装软件，也不用注册账号。