每个用Claude Code干活的人迟早都会遇到同一个问题明明上一轮已经把项目背景、技术栈、目录结构交代得清清楚楚结果新开一个会话它又回到了“失忆”状态连你刚说过的话都要重新解释一遍。如果只是个人折腾还好一旦项目稍微复杂一点比如多模块、多技术栈、多人协作这种重复沟通的成本足以让你怀疑人生。CLAUDE.md就是用来根治这个问题的项目记忆文件。简单说它是放在项目根目录下的一份Markdown文档Claude Code在启动时会自动读取并加载其中的内容作为整个会话的长期记忆和项目上下文。你可以把项目里那些“每次都要交代一遍”的信息全部写进去项目是干什么的、用的什么框架、目录怎么组织的、代码规范是什么、哪些坑不能踩、测试怎么跑、打包脚本是什么。之后每一个Claude Code会话都会自动带上这份上下文不需要你再费口舌。这篇内容适合正在用Claude Code做实际开发的人不管你是个人开发者、团队技术负责人还是刚开始接触AI辅助编程的新手看完之后都能直接上手把CLAUDE.md用好用透。我会从它解决的问题、文件结构设计、实操步骤、常见坑和团队协作几个角度展开把我自己踩出来的经验一并写清楚。1. 内容整体设计与思路拆解1.1 它是怎么解决“AI失忆”问题的先搞清楚一个核心原理Claude Code每次会话默认只能看到当前对话里的内容加上一些基本的系统提示词。你在这个会话里上传的代码、贴的报错、说的需求它当然记得住但那是“短期记忆”。一旦你关闭终端、开启新会话所有这些上下文就清空了它对你的项目一无所知。这很像团队里来了一个非常聪明的实习生。你上午给他讲了一遍项目的背景、技术选型、目录结构、注意事项他理解得很快干得也很利索。但第二天他来上班如果不把同样的话再说一遍他又回到白纸状态。CLAUDE.md就是那个“新员工入职手册”把项目的关键信息固化下来让每一轮会话的AI都能“上岗即懂”。我实测下来有没有CLAUDE.md的差距非常明显。没有它的时候我在一个老项目里让Claude Code帮我改一个模块它经常问一些“这个项目的入口在哪里”“用的什么版本管理”“日志格式有没有规范”这类我已经答过八百遍的问题。有了CLAUDE.md之后这些问题它会自己从文件里找答案沟通成本直接降了一个量级。1.2 为什么要单独建一个“记忆文件”而不是写在README里经常有人问项目里已经有README.md了为什么还要再搞一个CLAUDE.md这两个文件定位完全不同。README是给人类看的重点是“项目是什么、怎么安装、怎么使用”它的读者是新人、用户、协作同事强调的是易读性和上手引导。CLAUDE.md是给AI“看”的重点是“代码怎么组织、约定什么、避免什么、任务怎么执行”它的读者是Claude Code这个AI助手强调的是指令性和约束力。最直观的区别是README不会因为你贴了一段报错就修改自己的内容但CLAUDE.md可以被AI在实操中主动建议更新。比如它发现你项目里其实用的pnpm而不是npm但CLAUDE.md里写的是npm它可能会在任务完成后提醒你同步修改记忆文件。这是一种“让AI自己维护记忆”的机制README做不到。还有一个原因CLAUDE.md的加载机制和README不一样。Claude Code在启动时会自动读取项目根目录下的CLAUDE.md不需要任何手动命令也不需要你在每次对话里反复贴。它就像一个背景知识包悄悄塞进会话的上下文里。你写不写它Claude Code都在但写了它你的项目体验会从一个“反复解释的新人”变成一个“什么都懂的熟手”。1.3 CLAUDE.md适合什么规模的项目这件事不少人有误解以为只有大型项目才需要CLAUDE.md。我个人的实际感受是但凡一个项目你打算让Claude Code介入干活哪怕是个简单的个人小脚本都值得写一份。区别只在内容的详略程度。个人小项目CLAUDE.md写两三行就够了项目的用途、用什么语言跑、有没有特定的目录约定。这样Claude Code一进来就知道自己在做什么项目不会把你的Python脚本当JavaScript去盘。真正发挥巨大作用的是中大型项目。我最近帮朋友梳理一个微服务仓库里面光服务模块就有十几个每个模块的启动方式还不一样有的用Go有的用Java有的还有定时任务。以前让Claude Code改一个服务它经常把上下文搞混改A服务的代码时参考了B服务的约定。后来我在CLAUDE.md里给每个服务模块列了一节写明技术栈、入口路径、测试命令、专属注意点这个问题基本绝迹。所以我的结论是CLAUDE.md不是大项目的标配而是所有用Claude Code的项目都应该有的基础设施只是大项目收益更明显。2. 核心细节解析与实操要点2.1 文件放哪儿、叫什么名字CLAUDE.md的默认生效方式是放在项目根目录Claude Code每次启动时都会自动读取它。这是最基础、最常用的情况大多数个人项目到这里就够了。但它的加载机制比你想的灵活。如果你在子目录里也放了CLAUDE.md那么当Claude Code读取那个子目录里的文件、或者你的任务和那个子目录强相关时它会额外加载对应的子目录CLAUDE.md。这个机制非常适合做模块级约束。比如我有一个项目根目录的CLAUDE.md写着整体架构和全局规范然后src/api/目录下单独放一份CLAUDE.md专门描述接口层的编写约定、鉴权方式、错误码规范。Claude Code在处理接口模块时会自动带上这份局部记忆更精准。还有一种更常用的做法把CLAUDE.md放在~/.claude/目录里作为全局记忆。这里适合放那些跨项目的通用偏好比如你希望AI默认用中文回答、代码注释写中文还是英文、格式化工具倾向、提交信息风格等等。全局记忆和项目记忆是叠加生效的两者互补不冲突。关于命名注意一个细节文件名是固定的必须叫CLAUDE.md全大写不能是claude.md、Claude.md更不能用README代替。大小写在这个工具里是敏感的。我犯过这个错把文件命名为claude.md结果Claude Code完全不读我折腾了半天排查才发现是文件名的大小写问题。2.2 内容结构要包含哪些关键块一份好用的CLAUDE.md没有强制模板但根据我这么多项目的实践以下这几块内容最值得写进去第一块是项目定位。用三两句话介绍这个项目是解决什么问题的大致的业务背景是什么。不要小看这段描述它决定了AI在处理具体任务时的全局判断。比如你的项目是个低代码平台AI看到“核心价值是让非技术人员通过拖拽生成应用”那么在给你设计功能时它会更注重易用性和配置化而不是纯代码效率。第二块是技术栈清单。把项目用到的主要语言、框架、关键库、构建工具、包管理工具全部列出来最好带上版本号。Claude Code的知识库更新再快也有滞后性它不一定知道你项目用的这个框架在某个特定版本上有坑。写出技术栈它就不会给你推荐一个版本不兼容的API。第三块是命令集。开发启动命令、构建命令、测试命令、Lint命令、部署命令这些是出现频率最高的。用途有两个一个是你让Claude Code干活时它需要用这些命令进行验证比如改完代码它要跑测试如果不知道测试命令它就会瞎猜可能猜一个根本不存在的脚本另一个是当它自己需要安装依赖、跑服务时能按照项目约定来操作不破坏环境。第四块是目录结构说明。不需要事无巨细地列每一个文件但关键目录的职责必须写清楚。比如src/core是核心业务逻辑不要乱动src/plugins是插件扩展区scripts里是一些自动化脚本。AI知道这些边界之后在改动代码时会更有分寸感不会轻易去重构一个不该碰的核心模块。第五块是代码规范与约定。这包括命名风格、组件写法、状态管理方案、接口错误码规范、提交信息格式等等。这块内容是CLAUDE.md的精华因为人类读代码风格文档经常不耐烦但AI会严格执行。你只要把规范写清楚生成的代码天然符合你的预期。我自己在实践中感触最深的就是这一点以前让Claude Code写前端组件它写出来的代码功能没问题但风格和我团队里其他人写的完全不一致要么用class写要么用function写要么组件文件命名是驼峰还是短横线每次都要人工调整。CLAUDE.md里写清楚之后这个问题直接消失。第六块是约束与禁忌。这块专门写“在这个项目里不要做的事”。比如不要修改某个自动生成文件的区域、不要在业务代码里直接操作数据库、不要用全局样式覆盖主题变量。AI对负面指令的执行往往比正面指令更坚决建议把禁忌事项单独列出来甚至在文件里用比较醒目的表述让AI在做决策时一眼看到“不可为”。2.3 写作技巧怎么让AI真正“读进去”CLAUDE.md本质上是一份给AI读的文档所以要遵循一些和人类文档不同的写作法则。最大的经验是用祈使句不用陈述句。你写“项目使用pnpm作为包管理器”AI知道有这个事实你写“所有依赖安装必须使用pnpm不要使用npm或yarn”AI就知道这是一个明确的行为指令。虽然AI不是绝对按字面执行但约束性强的表达方式确实能提升它的遵循率。还有一个技巧是明确优先级。CLAUDE.md里不可能每条规则都一样重要你需要显式告诉AI哪些是硬性约束哪些是软性建议。比如“本文件中的所有规则除非与用户明确指令冲突否则均需遵守”“以下规则优先级最高若与其他说明冲突以本节为准”。这样AI在决策时遇到矛盾规则知道应该听谁的。信息密度要克制。CLAUDE.md不是越详细越好。我见过有人把项目的完整Wiki、设计文档、API文档全塞进去结果文件达到几万字AI每次加载都会消耗大量上下文token反应变慢不说关键规则反而容易被淹没。合理做法是CLAUDE.md只放“高频、稳定、有约束力”的信息那些低频、易变、需要时再查的内容留到更详细的文档里用链接或路径标注AI有需要时再去读对应文件。要定期审视文件内容删除过时信息。比如你项目已经切换到pnpm但CLAUDE.md里还写着npmAI就会一直按错误的方式执行。我通常在每次比较大的技术栈调整或架构调整之后都会顺手过一遍CLAUDE.md保持内容与项目现状对齐。3. 实操过程与核心环节实现3.1 从零写一份CLAUDE.md的完整流程我先用一份真实的个人Web项目做例子带大家走一遍完整的创建流程。这是我最常用的一个手段先把大框架放上去不追求完美不追求一步到位然后在实际使用中不断迭代。首先在项目根目录创建一个空白文件命名为CLAUDE.md。打开后用Markdown写基本信息# 项目记忆文件 ## 项目定位 一个面向个人用户的极简记账工具支持多账本、Tag标签、月度报表导出。移动端优先桌面端适配。 ## 技术栈 - 前端React 18 TypeScript - 状态管理Zustand - 构建工具Vite 6 - UITailwind CSS Headless UI - 后端Node.js Express - 数据库SQLite (better-sqlite3) - 包管理器pnpm - 测试Vitest ## 常用命令 - 安装依赖pnpm install - 启动开发服务pnpm dev - 执行测试pnpm test - 类型检查pnpm typecheck - 构建生产包pnpm build ## 目录结构 - src/main: 应用入口和路由配置 - src/features/ledger: 账本核心功能 - src/features/tags: 标签管理体系 - src/features/reports: 报表生成与导出 - src/components: 通用UI组件 - src/lib: 工具函数与数据库连接 ## 编码约定 - 组件使用函数式写法命名采用 PascalCase - 所有样式使用 Tailwind 原子类不写单独的 CSS 文件 - 类型定义放在同目录的 types.ts 中 - 涉及金额计算必须使用 Decimal禁止直接使用浮点运算 - 数据库查询统一放在 src/lib/db 中业务代码中禁止出现 SQL ## 必须遵守的规则 - 修改核心账本逻辑时必须先执行 pnpm test 确保现有功能不回归 - 不要改动 src/lib/db/schema.sql这个文件是唯一的数据库结构来源 - UI设计保持简约不要引入重型组件库 - 提交信息使用 type(scope): subject 格式这样一份文件写完之后保存即可。下一次你在这个项目目录里启动Claude Code它就能自动读取这些内容。你可以先简单测试一下启动会话后直接问“这个项目用的什么包管理器”“测试命令是什么”如果它能用CLAUDE.md里的内容准确回答说明加载成功了。需要注意的是这份文件不用等所有信息都写全了才启用写好核心部分就可以先用起来后面缺什么补什么。很多内容只有在实际干活时才会想起来这很正常。3.2 实操中让AI“记性变好”的小技巧单纯写文件还不够我在实际使用中发现有几个小技巧能让CLAUDE.md的效果发挥到最大。第一个技巧是在CLAUDE.md里给AI布置“开场动作”。比如在文件末尾写## 开场动作 每次会话开始时先查看项目根目录下的 TODO.md确认当前待办事项如果有未提交的改动先执行 git status 查看工作区状态。这么做的价值在于让AI每次会话启动时不是被动等待指令而是主动进入项目状态。我用了这个技巧之后感受特别明显Claude Code不再问我“今天想让我做什么”而是一上来就汇报当前有哪些变更、哪些任务还没完成很像我带过的某个特别自觉的实习生。第二个技巧是给AI提供“读懂别人代码”的入口。很多老项目没有完善的文档代码又复杂AI第一次接触很容易被绕晕。我处理这类情况时会在CLAUDE.md里专门加一节“代码地图”写明核心流程的入口文件和调用链路。比如## 代码地图 - 应用入口src/main/index.ts - 路由注册src/main/router.ts - 登录流程src/features/auth/login.ts - src/lib/auth/session.ts - src/lib/db/user.ts - 报表生成链路src/features/reports/service.ts - src/features/reports/exporter.ts这几行信息对AI的价值有时比整个CLAUDE.md的其余部分都大。因为AI在代码里迷路时通常就是需要有一个“为什么这个文件要这样连接”的全局视角。第三个技巧是善用“会话中的补充记忆”。CLAUDE.md是静态文件但你在对话过程中会发现一些只有在实际任务里才知道的项目细节。比如让Claude Code排查一个构建报错最后发现是老版本Node导致的或者某个本地端口被系统占用导致服务起不来。这些经验值得在任务结束时顺手追加到CLAUDE.md里。我会直接和Claude Code说“把这个问题和解决方案写进CLAUDE.md的项目注意事项里”它能自己修改文件。这就是前面提过的“AI自己维护记忆”。3.3 CLAUDE.md在团队协作里的用法CLAUDE.md完全可以提交进Git仓库这样整个团队共享同一份AI记忆。这个做法对团队协作的价值比个人使用还要高。最立竿见影的作用是消除“新人提问”。团队里每个用Claude Code的成员哪怕之前完全没接触过某个模块只要项目里有一份质量在线的CLAUDE.mdAI就能带着完整的项目上下文帮他把活干了不用不停地去找老同事问“这个模块怎么跑起来”“这个接口在哪里定义的”“出错怎么办”。我观察过团队里几个不同的开发者用Claude Code他们遇到的最大的问题不是AI能力不够而是AI对项目不熟。CLAUDE.md就是那个让AI快速“变熟”的开关。团队使用时要特别约定CLAUDE.md的维护责任。我建议项目负责人或维护者来把关主文件的结构和内容因为这份文件本质上就是项目“技术判断力的结晶”写得好不好直接决定了AI在这件事上“聪明不聪明”。其他成员可以有权限提补充内容但最终合并前最好有人评审一下别让互相冲突的规范混进同一个文件里。再有就是注意隐私信息。CLAUDE.md如果准备提交到公开仓库里面千万不要写数据库密码、API密钥、内部服务器地址这些敏感信息。Claude Code和AI模型可能会在生成任务时参考这些内容一不小心就会随着代码生成被带出来。真要涉及敏感信息放在本地不提交或者用环境变量的方式引用。4. 常见问题与排查技巧实录4.1 高频问题速查表我用了一段时间也帮周围不少人排查过CLAUDE.md相关的问题整理几个最高频的故障和解决办法直接照方抓药就行。问题可能原因解决办法CLAUDE.md不生效AI完全不提项目内容文件名大小写不对确认文件名叫CLAUDE.md全部大写文件生效了但AI经常忽略规则内容中约束性表达太弱改成祈使句增加“必须”“禁止”等明确指令AI回答问题时引用了过时的技术栈文件内容没有及时更新每次依赖或架构调整后同步更新CLAUDE.md文件太长AI每次响应都变慢信息太冗余token消耗过大精简内容只留高频约束详细文档外链或路径自动生成的代码风格还是和团队不一致风格规范没写进CLAUDE.md把命名风格、组件写法、提交格式等逐条列出子目录里有独立规范但总失效子目录CLAUDE.md被根目录覆盖或冲突在根目录CLAUDE.md用优先级说明让AI明确处理全局CLAUDE.md和项目CLAUDE.md冲突全局设置写了过强的偏好项目级规则标明优先级高于全局规则我特别想强调第一个问题。CLAUDE.md、claude.md、Claude.md这三个文件在Linux和macOS下是完全不同的文件Claude Code只会读取全大写的CLAUDE.md。这里没有任何模糊空间。我见过不止一个人在这个问题上反复确认最后才发现是命名差异。还有一个很容易被忽略的场景是你的项目可能本身在用类似工具比如Cursor或Codex它们各自有自己记忆文件的命名方式.cursorrules、AGENTS.md等。如果你想同一份记忆在多工具间共用可以考虑在多个文件名中各放一份相同内容或者软链接过去。不过我没试过在三个工具间共享同一个文件内容N倍地放大因为不同工具的加载逻辑和优先级有差异最好还是各自维护。4.2 我踩过的坑和独家避坑技巧第一个坑是“写太满”。我最初给一个项目写的CLAUDE.md里连每个函数的职责都写进去结果整个文件巨大AI每次会话虽然能读完但真正面向任务时反而抓不住重点。后来我痛下决心瘦身把CLAUDE.md砍到只剩2000字左右的“高权重指令”把详细设计文档单独放一个docs目录在CLAUDE.md里给AI指明“遇到设计细节时请查阅docs/design.md”。效果好很多AI每次决策用的信息更聚焦了。第二个坑是“自相矛盾”。CLAUDE.md里写着“前端组件全部用React函数组件”后来加需求又说“某些页面要保持旧代码的Class组件风格”两条规则并存AI在执行时经常摇摆不定。解决办法是给规则加明确的适用范围和优先级。比如“新代码组件一律使用函数组件已有Class组件只做维护性修改不主动重写”。第三个坑是忘了把“AI已经学会的东西”沉淀回文件。很多时候Claude Code在一个会话里经过一番折腾终于解决了某个部署问题这个“折腾过程”本身非常有价值。但如果你不把它写回CLAUDE.md下一次又得重新折腾一遍。我现在要求自己也会提醒AI在任务收尾时主动反思“有哪些经验可以沉淀到项目记忆里”把“这一次的探索”变成“下一次的常识”。还有一个体验上的技巧CLAUDE.md里可以写一点“AI的性格偏好”。比如“回答我时默认使用中文”“代码注释写清楚——为什么这么写而不是写重新描述了这段代码在干什么”“涉及改动建议时先给方案再动手不要直接改”。这些看似和项目无关的散碎偏好反而比技术规范更能决定你日常使用Claude Code的愉悦程度。毕竟AI在绝大多数时候是在和你配合工作而不是在执行一条条冰冷的规则互动的默契和相互理解非常重要。5. 个人经验与扩展建议如果只看一个结论我希望你能记住这句话CLAUDE.md的维护成本和收益是非线性的。你只需要花一点点时间在最开始把项目的基本背景、技术栈、命令、规范写清楚之后每一次Claude Code会话都能享受到这份记忆红利而且越用越值因为文件会随项目一起进化。我个人在实操中的体会是写CLAUDE.md这件事不能拖。很多人的习惯是项目已经用Claude Code干了好几轮活之后才发现每次对话都要重复交代背景这才想起要建记忆文件。但其实最合适的写入时机就是项目刚开始的时候甚至比你写README都早。因为项目初始阶段技术选型、目录结构、约束规则这些东西刚刚敲定正是信息密度最高、最容易写清楚的时候。这时候顺手写一份CLAUDE.md后面所有的AI协作都会在一个清晰的框架下展开积累下来的经验也更有章法。最后再分享一个小技巧。别把CLAUDE.md当成一次性的静态文件可以给它做定期体检。我通常半个月左右会快速扫一遍里面的命令是否还能用技术栈是否有升级目录结构有没有大改哪些规则在实际使用中被AI频繁打破值得特别标注。保持CLAUDE.md和项目同步你的AI助手就会一直以最佳状态参与项目这个投入一定值。