你有没有遇到过这种情况:昨天开会刚跟 AI 编程助手交代清楚项目的目录结构、命名规范和不能碰的模块,今天打开新会话,它又一脸茫然地问“这个项目是做什么的”,甚至敢直接在核心模块里乱改代码。我刚开始用 AI 编程工具那阵,几乎每天都在重复解释同一件事,气得我一度以为这玩意儿就是个“金鱼脑”。后来试了 CLAUDE.md,整个体验彻底变了——它就相当于在项目根目录下放了一张“入职员工手册”,AI 每次开工前先读一遍,自然就记住你定下的所有“潜规则”。
CLAUDE.md 是 Anthropic 为 Claude Code 这类编程智能体设计的项目级指令文件,也是当前 AI 编程实践里最值得推广的一个工程化手段。它本身就是一个普通的 Markdown 文件,但位置固定在项目根目录,AI 在每次会话开始时都会默认读取它,相当于给大模型注入了“项目记忆”。这篇文章不打算讲太多虚的,我会把实际使用中总结出来的内容规划、编写套路、避坑技巧全部整理出来,适合所有在项目里用 AI 编程工具、受够了反复交代背景的人参考。
1. 为什么 AI 总是“转头就忘”:CLAUDE.md 要解决的问题
我第一次接触 CLAUDE.md 的时候,其实挺困惑的:项目里不是已经有 README.md 了吗,为什么还要搞一个专门给 AI 看的文件?后来踩了几次坑才明白,这俩东西服务的对象完全不同,解决的是 AI 编程落地时最要命的问题——跨会话记忆。
1.1 AI 编程工具的“金鱼记忆”困境
大模型处理任务依赖上下文窗口,哪怕是最新的模型,上下文长度也是有限的。更关键的是,上下文是跟着会话走的,只要会话一关、窗口一清,AI 对这个项目的所有理解就会归零。我之前做过一个小型 Web 应用,前后端加起来几十个文件,有一次跟 AI 连续聊了四个小时,把业务逻辑交代得清清楚楚,AI 也把数据模型设计得有模有样。结果第二天打开新会话,让它加一个接口,它居然按自己想象的表结构去写,跟数据库里实际的字段对不上,白费了半天功夫。
这种痛苦用过 AI 编程的人应该都有体会。AI 不是不聪明,它是真的“记不住”。你可以在每次对话开头重新贴一遍项目背景,但项目稍微复杂一点,那段背景文字就长得吓人,既浪费 token 又影响 AI 的理解质量。CLAUDE.md 的出现,就是为了解决这个问题:把项目里那些“长期有效、默认适用、不太变化”的信息,单独抽出来做成一个持久化文件,让 AI 每次开机先读一遍。打个比方,它就像是公司给新员工准备的入职手册,而不是某个项目组成员临时写的工作说明。
1.2 CLAUDE.md 的工作方式与定位
从功能定位上看,CLAUDE.md 不是给人看的文档,而是给 AI 看的“工作规范”。它通常放在项目根目录,Claude Code 在启动时会自动识别并读取,文件里的内容会作为系统提示词的一部分注入到每一次会话的上下文中。也就是说,只要 AI 开始工作,它就会默认知道你在文件里写的那些规则,不需要你反复强调。
这个定位跟 README.md 有本质区别。README 主要是给开发者看的,介绍项目是什么、怎么安装、怎么使用,用词可以轻松随意,甚至可以带点个人风格。但 CLAUDE.md 是给 AI 看的操作手册,需要更精确、更结构化、更偏向“可执行指令”。我在维护老项目的时候,经常看到有人把 CLAUDE.md 写成了一篇散文,AI 读完还是不知道该干什么,那就是把定位搞混了。
另外,现在市面上很多 AI 编程工具也都有类似机制,比如一些编辑器插件会读取 .cursorrules 之类的文件,宗旨是一样的:把项目的“潜规则”沉淀成文件,让 AI 照着执行。原理都有相似之处,掌握了
