项目记忆文件不是”给 AI 看的项目简介”，而是一份每次会话都会被塞进上下文的操作规程：写得好不好，直接决定 AI 第一次就能写对，还是每天都要重复纠正同一件事。它的正确写法只有一条——只写 AI 不看就会做错的内容。
为什么需要项目记忆文件
AI 编程助手最大的问题不是不会写代码，而是每次打开项目都像第一天上班：不知道你用 pnpm 还是 npm，不知道测试命令是 make test-integration，不知道这个项目禁止默认导出。这些纠正只存在于当次会话，关掉窗口就烟消云散。
项目记忆文件（Claude Code 的 CLAUDE.md 、通用标准的 AGENTS.md）就是把这个”每天重复三遍的口头交底”固化成文件。它会被自动加载，不需要你粘贴任何提示词。
CLAUDE.md 与 AGENTS.md 怎么选
| 维度 | CLAUDE.md | AGENTS.md |
|---|---|---|
| 来源 | Claude Code 专用 | 跨工具行业标准（Linux 基金会下的 Agentic AI Foundation 维护） |
| 读取者 | Claude Code | Codex 、 Cursor 、 Copilot 、 Gemini CLI 、 Windsurf 、 Aider 等 |
| 目录层级 | 项目根 / .claude/ / 用户级 / 子目录，按层级覆盖 | 仓库根 + 子目录，离被编辑文件最近的那份优先 |
| 适合场景 | 只用 Claude Code 的团队 | 团队里同时存在多种编码工具 |
两个文件不是二选一。主流做法是维护一份 AGENTS.md 作为唯一事实源，再把 CLAUDE.md 做成符号链接指向它（Windows 上用复制或同步脚本代替软链），保证不同工具读到的规则一致。
一份合格的项目记忆文件写什么
长度控制在 300 行以内，内容分四块，每一块都必须是”可执行”的：
- 项目背景一句话：Next.js 电商前台 + Postgres + Stripe 支付，一段话讲清技术栈和业务边界。
- 不能犯的错：不要引入新依赖、不要改动认证逻辑、不要碰生产配置文件。这类”硬约束”是文件里最有价值的部分。
- 完整命令：安装、开发、构建、类型检查、 lint 、测试，要精确到可直接复制的字符串。
- 架构约定：路由放哪个目录、数据访问用什么模式、提交前跑哪些检查。
这些内容千万别往里塞
四类最常见的「无效记忆」
- 肉眼可见的事实：”这是一个 TypeScript 项目”——模型读 package.json 就知道，占的是白花花的上下文额度。
- 无法执行的口号：”写出高质量代码””注意代码规范”，没有判定标准就等于没写。
- 密钥与隐私数据：记忆文件通常随仓库提交，任何 token 、密码、客户数据都不能出现。
- 过长的政策文档：超过一屏的规范应该拆到独立文件，用
@路径/文件的方式引入，保持主文件精炼。
五步把项目记忆文件落地
- 用工具的初始化命令（如
/init）自动生成一份草稿，作为素材池而不是终稿。 - 通读草稿，删掉所有”看代码就知道”的描述，只留下会真正踩坑的部分。
- 补齐四条硬信息：不可触碰区域、精确命令、架构约定、完成前必跑的校验。
- 把长规范拆成子文件，在主文件里用引入语法指向它们，控制主文件行数。
- 像 review 代码一样 review 它：改 CI 命令后同步更新，删掉已经失效的规则。
和规则文件、钩子怎么配合
记忆文件负责”这个项目是什么样”，规则文件负责”某类任务怎么做”，钩子负责”某个动作发生时自动执行什么”。三者分工明确，别指望一个文件解决所有问题。如果你已经在用工具自带的 rules 目录，记忆文件只需要保留跨场景的公共约定，把按主题拆分的细则留给规则文件。更多可组合的做法可以参考多工具环境下的规则配置实践和用钩子把重复校验自动化。
怎么验证它真的有用
换个干净的会话窗口，直接下一个你平时需要口头解释三轮才能做对的任务。如果 AI 一次做对，说明记忆文件写到位了；如果它还在问”用什么包管理器”，说明关键命令没写进去。想从更系统的角度理解上下文该给多少，可以看规格驱动开发的做法——记忆文件本质上是规格的最小可用版本。
查看项目规则配置的完整实践项目记忆文件应该放在哪个目录？
放在仓库根目录最通用。 CLAUDE.md 也可以放在 .claude/ 下保持根目录整洁，个人或本机专属的规则放 CLAUDE.local.md 并加入 .gitignore 。
文件太长会不会影响效果？
会。每一行都在和真正的工作内容竞争注意力，也消耗上下文预算。超过 300 行就该拆分，用引入语法指向子文件。
团队里有人用 Cursor 、有人用 Claude Code 怎么办？
以 AGENTS.md 为唯一事实源，其他工具的文件保持同步即可，两份文件的命令与禁令必须完全一致，否则不同工具会给出风格冲突的代码。
写出来之后还要维护吗？
必须维护。构建命令改了、架构约定变了却没同步，记忆文件就会变成误导源，比没有更糟。建议把它纳入代码评审范围。
评论 (0)