写这篇文章之前我先说个真实场景。某天我打开一个几周前还在迭代的项目准备让 Claude 帮忙把某个模块的重构方案落地。结果新会话里它问我这个项目的技术栈是什么消息队列用的是哪种目录结构能不能发我一份我当时就沉默了——不是它笨是我从来没给过它一本项目说明书。后来我开始认真对待 CLAUDE.md这个问题基本消失了。CLAUDE.md 不是玄学也不是什么新鲜功能。它就是放在项目里的一个 Markdown 文件用固定的格式把项目的背景、技术栈、编码规范、常用命令、架构决策、甚至哪些事千万别做写清楚。Claude 在开始处理任务前会自动读取这个文件把它当成项目记忆来用。无论你隔多久重新打开项目它都能快速恢复到上次的状态不会一问三不知。这篇内容就是想把我在实际项目里写 CLAUDE.md 的方法、模板和踩过的坑完整梳理一遍给同样被AI 失忆折磨的人一份能直接抄作业的参考。1. 为什么 AI 会失忆跨会话记忆的底层短板1.1 会话是无状态的文件才是记忆很多人第一次用 Claude 时都会有一种错觉它能写代码能解释概念看起来挺聪明。但用着用着就会发现它每一次新会话都像初次见面。你把同一个项目的问题分别开五个对话框问它它会给出五种风格完全不同的答案因为它根本不记得上一个会话里你们已经敲定过什么。这不是模型的 bug而是工作方式决定的。Claude 的理解能力建立在当前上下文之上你把它放进一个空会话里它唯一的输入就是你的提问和系统预设。它没有硬盘无法自动记住你三个月前说过的某一个偏好。所有长期记忆必须由外部文件来承担。CLAUDE.md 做的就是这个事把项目里那些不该每次重复解释的内容固化下来让模型在每次对话开始前先读一遍相当于给它开了个快速回忆通道。1.2 CLAUDE.md 解决的其实不是编码问题是共识问题前端后端一起开发、一个人维护十几个脚本、接手别人的遗留仓库……这些场景下的痛点往往不是代码写得差而是约定散落在各处。数据库命名规则写在哪错误处理用 try-catch 还是返回 Result提交信息用英文还是中文测试命令是 make test 还是 npm run test如果这些信息只存在于某个老同事的脑子里那么 AI 自然也无从得知。CLAUDE.md 的第一个价值就是把这些隐性的共识变成显性文本。它不是给编译器看的而是给协作方看的。当 Claude 读到了本项目所有接口错误统一返回 { code, message, data } 结构这句话它生成的代码就会自动遵守这个约定。你会发现一个很明显的转变AI 的输出不再是你每次都要改一遍的半成品而是风格统一、符合团队习惯的可用代码。这才是所谓记住项目的本质——记住的不是代码本身而是代码背后那一整套规则。1.3 和其他记忆方案的区别有人会说我直接在代码注释里写清楚不就行了或者写个超详细的 README这些做法都有用但都不够定向。README 是给人类看的会花大量篇幅介绍项目背景、截图、安装步骤AI 虽然也能读但那些信息对代码生成任务帮助有限。而代码注释只能覆盖局部函数无法表达全局层面的决策。CLAUDE.md 的特殊之处在于它是专门为模型设计的操作手册。它的读者只有一个那就是 AI。所以你可以用更直白的指令句、更结构化的清单、更明确的禁止项完全不用考虑人类读者会不会觉得语气太生硬。我现在的做法是README 放给人看CLAUDE.md 放给 AI 看两个文件分工明确互不替代。2. CLAUDE.md 的加载机制与目录放置规则2.1 文件放哪路径本身就是一种优先级CLAUDE.md 默认的读取位置是项目根目录这是最简单也最不容易出错的放法。根目录意味着无论你在项目的哪个子目录下发起对话模型都能自然感知到这份文件的存在。就像你走进一家公司前台永远在最显眼的位置CLAUDE.md 就是 AI 的前台。我见过有人把它放在 src 文件夹里或者用一堆子目录的 CLAUDE.md 把信息拆得稀碎。这样不是不行但容易出问题模型未必会在处理任务前主动去翻深层目录的文件。如果你只有一个文件请毫不犹豫放进根目录。文件命名严格使用 CLAUDE.md不要自创成 claude.md、project_info.md 之类——模型对特定文件名的识别是有约定逻辑的你换个名字等于把记忆文件变成了普通文档。2.2 多个 CLAUDE.md 的分级与协同项目一大你会发现根目录一份文件写不下所有内容。比如一个 monorepo 里既有前端又有后端还有一组独立的数据处理脚本它们的技术栈、命令、规范都不同。这时候一份记忆文件走天下就不现实了。实际项目里我推荐根目录总纲 子目录细则的分层结构。根目录的 CLAUDE.md 只写整个仓库的公共信息架构总览、目录规划、通用的提交规范、以及一份子目录速查表——明确告诉 AI 哪些子目录里还有更详细的规则文件。子目录各自的 CLAUDE.md 则写这个模块自己的事情。这样模型在某个子目录内工作时会优先读取当前目录的 CLAUDE.md找不到才回退到根目录的总纲信息不会互相覆盖也不会一锅乱炖。2.3 和系统提示词、项目说明文档的配合Claude 的上下文里其实有多个信息来源系统预设、CLAUDE.md、你粘贴的附件、当前对话内容。CLAUDE.md 不是要取代系统预设它管的是这个项目长什么样系统预设管的是你以什么身份和语气回答问题后者更像人格前者更像记忆两者不该混淆。有一个容易被忽略的细节如果把 CLAUDE.md 放在项目根目录的同时你又手动上传了一份一模一样的文件作为附件会不会重复实践中我发现重复内容并不会显著损失效果但会浪费本就宝贵的上下文空间。正确做法是上传附件优先选和当前任务强相关的具体文档CLAUDE.md 靠自动加载就够了不要手动重复投喂。3. 写一份真正能被 AI 执行的 CLAUDE.md内容维度3.1 浓缩项目事实技术栈、目录结构、脚本入口我写 CLAUDE.md 的第一版时会习惯性写一大段项目愿景和产品介绍后来发现 AI 根本不关心这些。它真正需要的是事实型数据。技术栈清单要具体到版本Python 3.11、React 18、pnpm 而不是 npm。目录结构不要粘贴整个 tree 输出只标出几个关键路径比如 src/components 是业务组件、scripts/deploy 是发布脚本。还有项目里各个入口命令——启动、测试、构建、格式化的完整命令写清楚AI 就不需要每次猜测或翻 package.json 了。举个小例子我某个数据分析项目里CLAUDE.md 写了这样一条本项目所有 Python 脚本使用 uv 管理依赖禁止在项目里创建新的 requirements.txt运行测试使用 uv run pytest tests/数据库连接串一律从 .env 读取不许硬编码。就这几句之后 Claude 生成的所有代码都没有跑偏过。3.2 建立决策准则风格、规范、禁止事项事实信息能帮助 AI做对但真正拉开差距的是决策准则——也就是遇到模糊选择时它应该怎么选。这类内容要写成规则而不是描述用明确的祈使句。比如所有 API 返回结构统一为 { code: 0, data: ..., message: ok }code 非 0 表示错误。组件命名使用 PascalCase文件命名使用 kebab-case测试文件加 .test 后缀。新增依赖必须说明理由优先选择已有的依赖库不轻易引入新包。日志统一使用 loguru不要用 print。这些条目单独看都很简单但合在一起它们构成了 AI 的行为准则。你会发现一个有意思的现象当你把规则写明确之后AI 会主动遵守甚至在你忘记提要求的时候也按照这个标准输出。它不再是每次都要你纠正而是变成了自带规范的协作者。3.3 工作流与顺序让 AI 按你的节奏来除了做什么CLAUDE.md 还应该写清楚按什么顺序做。这一点很多人会漏掉。比如我希望 Claude 改完代码之后先运行项目里已有的测试再自己补充新的测试最后输出一段简要的变更说明。如果不在文件里写它可能会直接给你贴出完整代码就结束。我把这类内容概括为收尾工作流在 CLAUDE.md 里用一个固定小节写代码完成后必须执行哪些检查、产出格式是什么。更好用的做法是把常见任务的完成清单也写进去像新增一个数据接口时必须同步更新 docs/api.md并在 CHANGELOG 中追加记录。这类基于任务类型的规则能让模型的输出直接对接你的现有流程而不是给你留下一堆后续还要自己补的活。3.4 格式与语法技巧结构、语气、长度CLAUDE.md 本质上是一份给模型读的文本它的编写方式有一些实用技巧。结构上我建议用清晰的分节 短条目不要写成长篇散文。模型偏好易于扫描的结构化信息一个信息点对应一条清单比一大段话效果更可靠。语气上面用必须禁止推荐这类强指令词比最好建议考虑一下这种委婉表达有效得多。在本地测试过几次之后我把所有模棱两可的词全替换掉了AI 的执行稳定性明显提升。长度上我的经验是不要追求大而全文件超过几百行时模型执行重点可能被稀释。每一个字都应该问一句删掉它会影响 AI 的行为吗不会就删。CLAUDE.md 是操作手册不是知识库。4. 不同规模项目的文档拆分策略4.1 小型个人项目一份文件搞定对于个人维护的小项目比如一个爬虫脚本、一个博客生成器、一组自动化工具CLAUDE.md 不需要太大几十行就够。我通常会包含五块项目一句话简介、技术栈与版本、核心命令、目录里的关键文件、以及 3~5 条最关键的行为准则。这里有一个容易犯的过度设计问题个人项目也要写得很复杂。我见过有人在 cli 工具项目里写了四十多条规范一半根本用不上。CLAUDE.md 的粒度要匹配项目的复杂度能在一份文件里说清楚的事强行拆成多份只会给 AI 增加检索负担。个人项目就老老实实集中写宁可精简不要冗余。4.2 中型项目主文件加引用索引当一个仓库开始有多个模块、多人协作时单份文件就不够用了。我的做法是保持根目录 CLAUDE.md 为主体同时在文件末尾维护一个子文档索引指向 docs/ai/ 下面更详细的专题文件比如 coding-style.md、architecture.md、deployment.md。这样做的收益是根目录的文件保持精简AI 每次读到的核心指令不会变而当某个任务真的涉及部署细节时模型可以在索引中找到线索、再去打开对应文档信息获取路径是动态的、按需的。注意这里要写明子文档里有什么让 AI 知道什么时候值得去翻而不是给它一堆没头没尾的路径。4.3 大型 monorepo根目录总纲加分仓细则大型 monorepo 是最难处理、也最值得写好 CLAUDE.md 的场景。因为一个仓库里有多个独立应用、多套技术栈如果你把前端的规范和后端的规范全部塞进同一个文件AI 在生成前端代码时会看到一堆与它无关的后端规则干扰很大反之亦然。我的模板是根目录 CLAUDE.md 只包含仓库公共信息脚手架命令、commit 规则、目录地图然后分别在 packages/web、packages/api、packages/shared 各自放一份独立的 CLAUDE.md专注写各自的规范和命令。这里要特别提醒如果你改了某个子目录的 CLAUDE.md别忘记在根目录的地图里同步更新哪个目录有哪些规则文件的信息否则模型的检索入口会过期。4.4 我目前最常用的模板直接给一个可以在小型仓库里改着用的模板这段我经常当作初始骨架复制到新项目# Project Overview 一句话说明这个项目做什么、服务谁、当前处于什么阶段。 # Tech Stack - Language: Python 3.12 / Node.js 20 ... - Framework: FastAPI / Next.js 14 ... - Package Manager: uv / pnpm ... - Infra: Docker / Vercel ... # Directory Map - src/app: 业务主应用 - src/services: 对外接口 - scripts/: 运维脚本 - docs/: 文档 # Commands - dev: pnpm dev - test: pnpm test - lint: pnpm lint - build: pnpm build # Coding Rules - 接口返回统一 { code, data, message }。 - 模块内禁止循环依赖公共逻辑抽到 src/shared。 - 异常统一用 AppError 子类禁止裸抛 Error。 - 每个新 API 必须同步补充测试。 # Workflow 1. 修改代码前先查看相关目录的现有实现。 2. 完成后运行 lint 和 test。 3. 输出变更摘要格式变动文件、影响范围、测试结果。 # Avoid - 不要新增全局单例。 - 不要直接改数据库表结构必须先写迁移脚本。这个模板的每一项背后都有明确的目的后面我会逐个解释为什么这么设计、改的时候哪里容易翻车。5. 维护 CLAUDE.md 的日常节奏5.1 什么时候该更新规则变、结构变、命令变很多人的 CLAUDE.md 从创建那天起就没更新过过了半年文件里的命令早改了目录结构也重组了AI 还在按旧规则工作。维护这个文件的关键是抓住几个节点引入新依赖、目录迁移、命令变更、编码规范调整、新成员加入。我自己的习惯是每次项目发生结构性变化时顺手更新 CLAUDE.md而不是等下一次对话时发现问题再补。某些场景我会直接让 Claude 根据最近几轮对话的修改痕迹帮我合并一份更新稿但前提是让它基于 git diff 来归纳而不是凭空改写。5.2 把记忆文件当成代码来管CLAUDE.md 虽然有文档两个字但它和 README 不一样它直接影响 AI 的行为所以更应该被当成代码来管理。我会把 CLAUDE.md 纳入 code review 的范围谁改了技术栈、调整了命令都必须同步更新这个文件否则评审不通过。这对团队协作尤其关键。如果只有你一个人知道最近项目换了包管理器CLAUDE.md 里那句 npm 早废了其他同事用 AI 处理任务时就会得到明显过时的指导。把 CLAUDE.md 变动和业务变动绑定到同一套流程里它才不会腐化成一堆没用的遗迹。5.3 变更记录与 git 管理有人问CLAUDE.md 要不要提交到 git 仓库我的答案是要而且非常应该。提交到仓库意味着变更可以被追踪、回溯新成员 clone 下来就能继承同一套规则。作为对照我会把含有本地私有路径、个人 token 之类的信息排除在外保持文件的可分享性和通用性。实际操作中我还会在仓库里单独记录 CLAUDE.md 的修改历史注释比如v2.1统一错误码格式移除旧版 xxx 命令。这个变更历史和代码 CHANGELOG 放一起方便未来的自己快速理解为什么这个规则会存在而不会在某天看到饭团般费解的一行禁止项时一头雾水。6. 我实测里踩过的坑和进阶用法6.1 大忌把 README 整段复制进 CLAUDE.md我第一次写 CLAUDE.md 时犯的最大错误就是把 README 里的项目介绍、架构图说明、甚至安装步骤原封不动复制了过来。结果模型被一堆宣传性内容淹没真正重要的行为规则反而权重被稀释。后面我做了一个清理把所有描述性文字压缩成一句或者直接删掉CLAUDE.md 的可执行性立刻变高。建议的检验方法是你写完 CLAUDE.md 之后大声读一遍每一句都必须回答一个那又怎样的问题——这句话删掉AI 的工作会受影响吗如果不会直接删。6.2 大忌写得像散文而不是规则第二个坑是把规则写成了我们倾向于使用函数式风格避免可变状态这种泛泛而谈。模型确实能理解这句话但执行时容易走样。你写避免可变状态它可能连一个局部变量都不用你写模块内禁止循环依赖公共逻辑抽到 src/shared它就能明确执行。CLAUDE.md 里不要留任何主管式模糊指导每条规则都要具体到可以直接落进代码的程度。6.3 大忌反复让 AI 重写这个文件我见到一种很流行的做法让 Claude帮我整理思路生成一份系统化的 CLAUDE.md。这个流程很方便但风险很高。如果让模型自己去总结一个项目它会生成很多看起来合理但其实并不存在的约定甚至把个人编码风格替换成网上的流行模板。我更建议由人起草骨架、把事实信息填进文档再由 Claude 帮你检查和补漏而不是完全授权它重写整份文件。记忆文件里的每一条规则都应当来自真实项目事实而不是模型的想象力。6.4 进阶把 CLAUDE.md 从操作手册升级为判断框架对已经熟悉基本写法的读者可以尝试再往前一步不只是在 CLAUDE.md 里写命令和规则还要写出项目里那些非显性决策的判断依据。比如为什么这个模块当初选择用 Redis 而不是 Postgres 做缓存为什么允许在测试里用 mock 但在核心模块禁止这些理由一旦写进去模型在帮你做新决策时会沿着同样的思路推演而不是只机械地遵守表面规则。我用过一个很有意思的写法在 CLAUDE.md 里加了一个设计原则小节写的是幼稚的代码优先于聪明的代码优先选择直观命名而不是代码行数最少。这之后Claude 给出的代码确实变得更可读、更保守了比我在几十条具体规范里反复强调效果都好。判断框架类的内容比单点规则更能影响 AI 的长期输出风格。还有一个进阶技巧是给 CLAUDE.md 配置多角色视角。在文件里区分当你要解释代码时和当你要写代码时的不同表现方式可以让 AI 在同一项目里扮演讲师或结对搭档两种角色。我一般会写一段类似当用户询问原理时先给结论再给实现细节当用户请求实现时直接给代码并附简要注释。这一小段就能让日常使用的体验发生不小的变化。我在多个项目里用下来的体会是CLAUDE.md 确实是个慢功夫文件。刚开始写的时候可能要花一两个小时整理之后每次项目变化还要顺手维护但它带来的收益是持续的——无论是自己隔几个月回头看这段代码还是带着 AI 加入一个新仓库都不需要从头解释一遍我们是什么项目、用什么技术、注意哪些规矩了。如果你也被 AI 的金鱼记忆搞得反复重申上下文与其自己生气不如花一个下午把这份记忆文件写好一次投入长期受益。