项目手册是什么
在开启一个项目的时候，必须有一份给 AI 看的“项目说明书”。
主要告诉 AI：这个项目是干嘛的、代码应该怎么写、哪些东西不要乱动、遵循什么规范，以及改完以后要做哪些检查。
这样你就不用每开一个新对话，都重新跟 AI 解释一遍你的项目是干嘛的，也可以避免AI写代码乱飞
Claude Code、Codex 这类编程 Agent，在开始工作的时候，本身就会主动加载这些项目级说明文件，把它们作为这一轮工作的长期上下文。
不过这里有一个很容易误解的地方：“项目手册”并没有一个所有 AI 都统一使用的名字。
你可能会见到：CLAUDE.md、AGENTS.md、GEMINI.md、Cursor Rules、.mdc ……
是的他们都是项目手册，只是不同 AI 编程工具读取的格式不一样（这个项目手册是有标准的名字的哦，可不能你自己创建一个xxx手册，然后就让AI读取是行不通的）
比如：
- Claude Code → CLAUDE.md
- Codex → AGENTS.md
- Gemini CLI → GEMINI.md
- Cursor → .cursor/rules/.mdc，同时也支持 AGENTS.md
- GitHub Copilot → 也已经支持 AGENTS.md
所以严格来讲，并不是“这个项目是用谁创建的，就必须用谁的文件”。
而是：你准备用哪个 AI 来写代码，就要看这个 AI 认哪一种项目说明书。
为了方便小白理解，我大概把它们分成三种。
常见项目手册
CLAUDE.md
CLAUDE.md 是 Claude Code 自己的一套项目说明文件。
Claude Code 每次开启新的会话，本身并不会自动记得你上一次聊过什么，所以 CLAUDE.md的作用，就是给它提供一份长期存在的项目背景和开发规则。Anthropic 官方也直接把它定义成给 Claude 提供“持久指令”的文件
所以你可以把 CLAUDE.md 理解成：“Claude 接手这个项目之前必须先看的员工手册。”
而且大型项目还可以继续往下拆。
比如整个项目有一套总规则，前端目录、后端目录又可以有各自更具体的规则。Claude Code 现在也支持通过 .claude/rules/ 做更细的规则管理。
不过需要特别提醒一点：
CLAUDE.md 并不是真正意义上的“硬约束”,官方给的解释是
它本质上还是给 AI 的指令和上下文，AI 应该遵守，但不代表技术上绝对无法违反。Anthropic 官方也明确说明，它属于上下文，而不是强制配置；如果真的要禁止某个操作，就应该使用 Hook、权限之类真正的执行层限制。
详细的介绍推荐看官网：Anthropic Claude Code Memory 官方文档
AGENTS.md
AGENTS（A simple, open format for guiding coding agents）
翻译过来就是：“个简单的、开放格式、给编程 AI 用的说明书”
AGENTS.md 官网自己给出的比喻就是：README for agents
也就是：“给 AI Agent 看的 README”
它和 CLAUDE.md最大的区别并不是里面写的内容有什么不同。
实际上里面都可以写：项目结构、安装命令、开发规范、测试方法、注意事项……
和 Claude.md 的区别是CLAUDE.md 是 Claude Code 约定的名字，而 AGENTS.md 想做的是一个大家都能认的通用名字。
像OpenAI 官方要求 Codex 用的就是AGENTS.md 的方案，所以在开始工作之前codex会默认读取 AGENTS.md，而且还支持：全局 → 项目根目录 → 子目录，一层一层往下覆盖。
比如：
项目/
├── AGENTS.md
├── frontend/
│ └── AGENTS.md
└── backend/
└── AGENTS.md
最上面的告诉 AI 整个项目怎么玩；
进入 frontend，再追加前端自己的规则；
进入 backend，则换成后端自己的规则。
更重要的是，现在 AGENTS.md 不单单只是Codex 自己在用，Cursor 已经原生支持项目根目录和子目录里的 AGENTS.md，GitHub Copilot 也支持它，因为AGENTS.md是一个开源项目，大家都认可，并且都在参与维护，所以AGENTS.md 正在变成 AI 编程工具之间的一种通用约定。
更加具体的介绍可以进其官方了解：https://agents.md/
专属格式
还有一类就是 Cursor 、TREA 这类 AI IDE 会更加“工程化”的规则系统。
Cursor 自己的 Project Rules 放在：.cursor/rules/
里面通常是一个个 .mdc 文件，那为什么都是写文字，Cursor 不直接全部用普通 .md，还要搞一个 .mdc 呢？
因为 Cursor 想解决的不只是：“规则里面写什么？”
它还要解决：“这条规则什么时候应该给 AI 看？”
比如你可以规定：这条规则只在修改 React 文件的时候生效；
那条规则只负责数据库，还有一条规则每次都必须加载。
所以 .mdc 除了里面可以正常写 Markdown，还可以附带一些额外信息，比如：这条规则适用于哪些文件、什么时候加载、是否始终启用， .mdc 看起来比普通 Markdown 更复杂
Cursor 官方的 Project Rules 就支持按照文件路径、相关性或者手动调用来决定一条规则什么时候进入 AI 的上下文。
所以你可以简单理解成：AGENTS.md / CLAUDE.md 更像一本完整的员工手册，而 Cursor Rules 更像：把员工手册拆成很多张规则卡，然后系统根据你现在在干什么，决定抽哪几张给 AI 看。
当然 Cursor 现在也支持 AGENTS.md，如果你的项目很简单，一份 AGENTS.md 就够了；
如果项目越来越大，需要针对不同目录、不同文件、不同任务精细控制规则，再考虑 .cursor/rules/*.mdc。
这张图我是当前这个网站的规则，对于我这种看不懂代码的小白，不进行详细的规则限制，很容易就是写出屎山代码
以及也是为啥我项目开发会用 cursor 的原因，对于长期项目，使用 cursor 的规则控制更加的精准。
项目手册写什么
从上面了解我们可得知，这个项目手册十分重要，就是AI每次运行都要读的，所以项目手册必须要写什么呢？
其实没有必须写的，AGENTS.md 官方甚至明确说：没有任何必填字段，也没有规定标题怎么写，就是普通 Markdown，所以还是具体项目具体分析。
但是比较大的方向就是下面这6个
| 写什么 | 大白话理解 |
|---|---|
| ① 项目是什么 | 告诉 AI 它现在在做什么 |
| ② 项目怎么组成 | 哪些文件夹分别干嘛 |
| ③ 用什么技术 | 不要自己突然换框架 |
| ④ 修改原则 | 改东西时有哪些规矩 |
| ⑤ 怎么检查 | 改完怎么证明没搞坏 |
| ⑥ 禁止事项 | 哪些危险操作别自己干 |
小白不用专门学习怎么手写一份专业 AGENTS.md。最简单的办法，是让 AI 先读取整个项目帮你生成，下面这个提示词你就可以直接发给你用来做项目的AI。
请阅读当前整个项目，帮我创建或完善根目录的 AGENTS.md。
我是一个不会编程的 Vibe Coding 用户。
请你自己从项目中判断：
1. 这个项目是做什么的
2. 当前使用的技术栈
3. 重要目录和文件分别负责什么
4. 正确的启动、构建和测试方式
5. 当前项目已经形成的代码和设计规范
除此之外，请加入适合 Vibe Coding 的保护规则：
- 修改前先阅读相关代码
- 优先复用已有实现
- 尽量最小范围修改
- 不要随意重构无关代码
- 不要随意更换技术栈
- 不要创建重复功能和重复文件
- 重大架构、数据库或高风险修改前先说明
- 修改后进行必要验证
不要写成冗长的技术文档。
只保留真正会影响 AI 后续开发行为的信息。
如果有无法从项目中确定的信息，请直接问我，不要自己猜。原则1：保持精简
AGENTS.md 的目的不是把整个项目的所有信息都塞进去，而是告诉 AI：这个项目是什么，以及开发时有哪些最重要的规则。
所以它反而应该尽量精简。像项目定位、技术栈、重要目录、修改原则、测试方式、禁止事项，这些真正会影响 AI 每次工作的内容写进去就够了。需求细节、完整设计文档、数据库说明、各种历史记录，没有必要全部堆在这里，否则文件越来越长，AI 每次都要读取一大堆不一定有用的信息，真正重要的规则反而容易被淹没。
原则2：按目录分层
如果项目越来越复杂，也不建议继续把根目录的 AGENTS.md 无限加长。更好的做法是分层管理：根目录只放整个项目通用的规则，某个模块有特殊要求，就在对应目录下再放一个更具体的 AGENTS.md。这样 AI 进入不同模块时读取离它最近的规则。
可以把它理解成：项目手册不是项目百科全书，而是一张给 AI 开工前看的注意事项。越重要的信息越应该留下，越具体、越局部的信息越应该放到对应的位置。
我这是以AGENTS.md举例，如果你是用claude写，也是同理，claude.md的官方介绍文档是真强烈推荐看看，因为逻辑基本都是一样的，就只是叫的名字不同而已。
再了解了项目手册的重要性后，下一章我来分享一下，我自己在做30aitool这个网站总结出来的一些更具体的实战经验。