我第一次意识到 CLAUDE.md 是个必须认真对待的文件是在一次接手遗留项目的夜晚。那个项目没有 README没有架构文档全靠同事口头交代各种“别动这里”“这里要走特殊流程”。我在对话里反复把规则粘贴给 AI得到的代码却总在几个关键节点上“失忆”。后来我把这些潜规则整理成一份 CLAUDE.md放在项目根目录效果立竿见影。CLAUDE.md 是 AI 编程工具 Claude Code 约定俗成的项目级记忆文件。每次启动会话工具会自动把这份文件读进上下文相当于在开工前先给 AI 念一遍项目工作手册。它解决的核心痛点是让 AI 不再靠你口头重复也能知道技术栈、代码规范、常用命令和那些没写进代码的“潜规则”。适合正在用 Claude Code 等 AI 编程工具的开发者也适合负责多个项目、不想每次重新交代背景的团队技术负责人。1. CLAUDE.md 是什么AI 编程工具里的“项目记忆卡”先确认一个很多人忽略的事实Claude Code 这类工具本质上不是“记得你的项目”而是“每次现场读一遍你的项目”。你打开的每个会话都从零开始唯一能跨越会话保存的就是显式写在配置文件里的内容。CLAUDE.md 正是其中最关键的一份放在项目根目录启动时自动加载不依赖你手动上传或复制。我习惯把它理解成“给 AI 看的入职手册”。新同事入职第一天你得告诉他团队用什么语言、代码放在哪、发布要走什么流程、哪些文件轻易不要动。CLAUDE.md 做的就是这件事区别在于读这份手册的不是人而是 AI 大模型。写得好AI 一开始就自带项目背景写不好AI 就在一次次试错中靠你补充上下文既费 token 又费耐心。1.1 AI 为什么总是“失忆”CLAUDE.md 又是怎么解决的很多人的第一反应是我在对话里已经说过了啊为什么它还是忘原因有两个。第一上下文窗口有限长对话里早期的说明会被后续内容挤掉或者被模型自身的注意力机制弱化第二每次新建会话都是完全独立的上一条会话里你千叮万嘱的规则换一个会话就彻底归零。这两个问题靠“反复口头交代”是治不好的。CLAUDE.md 的解决思路很直接把规则放到每次会话都会自动读取的位置。Claude Code 在启动时会扫描项目根目录把 CLAUDE.md 的内容注入到本次会话的上下文里。也就是说你不需要再做一次“自我介绍”AI 打开项目的第一刻就带着这些前置信息开始工作。这正是它和对话内临时说明的本质区别对话里的内容像便利贴随手就丢CLAUDE.md 像墙上刻的规矩每次进门都能看见。另外还有一个用户级文件路径放在用户主目录下比如常见的位置是 ~/.claude/CLAUDE.md。它可以存放你个人的通用偏好比如“所有提交信息用中文写”“默认使用 pnpm”这类与具体项目无关的习惯。项目根目录的 CLAUDE.md 优先级更高会叠加在用户级文件之上。这点在团队协作时特别有用个人习惯放用户级团队约定放项目级互不干扰。1.2 CLAUDE.md 与 README、.cursorrules 的区别做过技术选型的人都知道最难的不是写代码而是选哪个方案最合适。CLAUDE.md 也不是唯一一种“给 AI 看的说明文件”和它有血缘关系的还有 README、.cursorrules、AGENTS.md 等。它们各有侧重别混用。我整理过一个对比表方便你判断自己该维护哪一种文件主要消费者加载方式定位README.md人类开发者不会被自动加载AI 需要主动搜索阅读项目介绍、快速开始、使用说明CLAUDE.mdClaude Code 等工具启动会话时自动注入项目根目录文件项目级规则、技术栈、约束、工作流.cursorrulesCursor 编辑器Cursor 会话自动参考与 CLAUDE.md 类似但面向 CursorAGENTS.md多种 AI 编程工具部分工具支持自动加载开放式的多智能体协作约定copilot-instructions.mdGitHub Copilot仓库级说明Copilot 会自动参考代码补全与拉取请求说明关键结论是README 是给人读的CLAUDE.md 是给 AI 读的二者不能互相替代。很多人以为把项目说明写进 README 就够了实际上 Claude Code 不会因为你 README 写得好就自动遵守里面的规范它需要的是一个专门的、放在约定位置的规则文件。如果你同时使用 Cursor 和 Claude Code也可以让两者共用一份内容再分别放到对应位置避免维护两套文案。2. 一份高价值 CLAUDE.md 怎么写从技术栈到潜规则内容设计是实战的核心也是最容易踩坑的部分。我见过不少 CLAUDE.md打开后全是空话比如“请遵循良好的编码风格”“请保证代码质量”这种话 AI 根本没法执行。想要让 AI 真正听话文件里的每一条规则都得是具体的、可执行的、最好能直接验证的。一个合格的 CLAUDE.md我建议按四个模块来组织项目身份、常用命令、架构约定、禁止事项。其中前两个模块负责让 AI 快速上手后两个模块负责让 AI 不踩坑。下面逐个拆解我自己的写法。2.1 项目身份与技术栈声明让 AI 不用猜AI 编程工具面对陌生项目时最大的问题是“猜”。它会猜你用的是 npm 还是 pnpm猜你的 Python 版本是 3.9 还是 3.11猜你的后端返回结构是裸数据还是包裹结构。猜错一次后面整个链路都是错的。所以 CLAUDE.md 的第一段就要把项目身份钉死。我通常会在文件开头写这几样项目名称与一句话简介、主要技术栈及关键版本、目录结构说明。版本号尤其不能含糊Python 3.9 和 3.11 在类型语法上就有差异Node 16 和 20 对某些 API 的支持也不同。AI 一旦不知道确切版本就会倾向于选择它“见过最多”的写法而不是最适合你项目的写法。举个例子如果项目是 FastAPI 后端加 React 前端我会在技术栈里明确写“后端使用 FastAPI SQLAlchemy 2.x前端使用 React 18 Vite TypeScript包管理器统一使用 pnpm”。这里的关键词是“明确”。你越具体AI 的搜索空间就越小代码就越可能一次写对。生活化一点理解你让一个帮手去超市买东西说“买点吃的”和“买一袋 500g 的东北大米”完全是两个结果。2.2 代码规范与潜规则表述命令式优于建议式写规范时最容易犯的错是语气太软。比如“建议使用函数组件”“可以尝试把类型补全”这种表达对 AI 来说太模糊了它很难判断哪些情况算例外哪些情况必须遵守。我实测下来用“必须”“统一”“禁止”这类强约束词执行率明显更高。还有一点规则要让 AI 能自我验证。所谓“可验证”就是 AI 写出代码后能对照规则检查自己有没有违规。比如“新增接口必须返回 { code, data, msg } 包裹结构”AI 写完接口就能自查“禁止修改 public/ 目录下的任何静态资源”AI 在编辑文件前就能判断自己是不是越界。相比之下“注重代码可读性”这种话就完全不可验证等于没写。另外一定要把团队里那些“心照不宣”的潜规则写进去。比如“这个项目不接外部用户的登录需求”“兼容老接口时保留 v1 路由”“所有涉及金额的计算统一用 Decimal禁止用 float”。这类规则往往没什么文档记录但只要 AI 踩一次产生的连锁修复成本就足够让人崩溃。2.3 一份可直接抄的 CLAUDE.md 模板以 FastAPI React 项目为例理论讲完给一份可以改改就用的模板。真实项目里我会在上线前再迭代几轮但第一版这个体量就够用了。注意这份模板不是标准答案而是给你参考的组织方式。# 项目名 ## 项目简介 这是一个内部数据分析平台提供报表查询与导出功能。面向对象是运营团队不需要考虑外部用户注册登录。 ## 技术栈 - 后端Python 3.11 FastAPI SQLAlchemy 2.x Alembic - 前端React 18 Vite TypeScript Ant Design 5 - 数据库PostgreSQL 15 - 包管理器统一使用 pnpm禁止使用 npm ## 常用命令 - 启动后端uvicorn app.main:app --reload - 运行后端测试pytest app/tests - 生成迁移脚本alembic revision --autogenerate -m 描述 - 应用迁移alembic upgrade head - 前端安装依赖pnpm install - 前端构建pnpm build - 前端开发服务器pnpm dev ## 目录结构 - app/ 后端代码按业务模块划分禁止在 app/main.py 里堆积路由 - app/api/ 路由定义统一通过 APIRouter 注册 - app/models/ 数据库模型 - app/services/ 业务逻辑层禁止在路由文件里直接操作数据库 - web/ 前端代码基于 Vite 脚手架 - docs/ 项目文档AI 涉及架构决策时先查阅这里 ## 接口规范 - 所有接口响应统一包裹为 {code: 0, data: ..., msg: ok}错误时 code 为非 0msg 为错误描述 - 分页接口统一接收 page 和 page_size 参数返回 data 中带 total 字段 - 新增接口必须补充 Pydantic 入参校验模型禁止直接使用 Request 对象手动解析 ## 代码规范 - 后端所有函数必须完整标注类型注解 - 新建数据库表必须通过 Alembic 生成迁移脚本禁止手动改库表结构 - 前端组件一律使用函数组件 hooks禁止使用 class 组件 - 前端请求统一走 src/api/ 下封装好的请求函数禁止在组件里直接 fetch - 提交信息统一格式type(scope): subjecttype 使用 feat/fix/refactor/docs/test/chore ## 禁忌 - 禁止修改 web/public/ 目录下的静态资源 - 禁止在业务代码里输出任何调试用 print 或 console.log - 禁止删除或重命名数据库字段而不更新对应迁移脚本 - 不要为了兼容旧浏览器使用 React 16 的 API这份模板的核心是“条目化”。每条规则都能被对号验证AI 在处理具体任务时能快速检索出相关约束。我自己的经验是文件控制在 600 到 1500 字之间最合适太长会占据上下文太短则覆盖不到关键场景。第一次写不追求全先把最容易踩的坑列进去后续再迭代。3. 实操流程创建、验证、迭代一套走完有了内容设计接下来是把它真正落到项目里。很多人以为把文件一放就算完了其实后面还有验证和迭代两个关键步骤。我自己每次在新项目里启用 CLAUDE.md都会按“创建 → 验证 → 迭代”的节奏走一遍这样能确保它真的在发挥作用而不是躺在根目录里当摆设。下面这段流程基于我在多个项目里的实际操作经验你可以直接照着抄。3.1 创建基础文件放对位置比内容更重要第一步是创建文件。位置固定放在项目根目录文件名必须是 CLAUDE.md注意大小写因为工具是按固定文件名去扫描的。如果你把它放在 src 目录或者命名成 claude.md大概率不会被自动加载。创建时我习惯先手写一个极简版本只包含项目简介、技术栈和常用命令。这样做的原因是第一版越简单越好先让 AI 有基本认知后面再逐步增加规范。如果你一上来就想写一份完整规则很容易陷入“不知道 AI 需要什么”的纠结反而拖慢进度。有些版本的 Claude Code 也提供初始化命令或类似机制会自动生成一个模板文件。遇到这种情况我不会完全依赖它而是把它当作起点把模板里没有的团队约定补进去。尤其是“依赖包管理器”“禁止事项”这类项目特有信息自动化模板往往给不出来。另外还有一个容易被忽略的点CLAUDE.md 应该纳入版本控制。它是团队知识的一部分不是个人备忘。放进 Git 之后每次修改都有记录新人拉下代码也能直接看到。如果有人改了规则代码评审里也能一并讨论避免出现“AI 遵守的规则和团队实际约定不一致”的情况。3.2 验证文件是否生效用几个刁钻问题测一遍创建完文件后不要急着写业务代码先做一轮验证。我常用的方法很简单新开一个会话直接向 AI 提问看它是否掌握文件里的内容。比如你可以问“这个项目的包管理器是什么”如果它回答 pnpm说明技术栈部分被正确读取再问“新增接口要返回什么样的结构”如果它答出{ code, data, msg }说明规范部分也生效了。这类问题成本极低但能快速定位文件是否被加载、有没有解析错误。验证完“知道规则”再测“遵守规则”。我一般会让 AI 生成一个小任务比如“帮我写一个新增用户的分页查询接口”故意不重复任何规范看它生成的代码是否自动套用了接口返回结构和类型注解。这一步最有用因为很多文件虽然被读了但规则写得太笼统AI 根本不知道在什么时候用。如果生成结果不符合预期我会回去检查对应规则是不是写得太模糊。这里有个小技巧验证时故意制造一点冲突。比如问“我想用 npm 装一个新依赖可以吗”如果 CLAUDE.md 里写了“统一使用 pnpm禁止使用 npm”AI 应该会给出否定或提醒。如果它没反对说明你对规则的约束语气还不够强试着把“不要用 npm”改成“禁止使用 npm”这类更强的表述。3.3 迭代原则每踩一次坑就补一条规则验证通过不是终点CLAUDE.md 的价值在于持续迭代。我的习惯是每次发现 AI 在项目里做了什么不符合预期的事先不急着生气而是反问一句这是不是规则里没有写清楚然后把它补充成一条新的规则。举个例子有次我让 AI 重构一个数据导出功能结果它直接修改了数据库表结构还是在没有生成迁移脚本的情况下。那次问题发生后我就在 CLAUDE.md 的“禁忌”里加了一条“禁止直接修改数据库表结构所有变更必须通过 Alembic 迁移脚本”。从那以后这个错误再没出现过。迭代时要控制文件增长的节奏。规则越多上下文占用越大AI 在具体任务里的“注意力”也会被分散。我通常会在文件超过 1500 字时做一次精简把明显过时的规则删掉把相似条目合并确保每一句话都有明确用途。记住CLAUDE.md 是活文档不是存档文档它应该随项目一起演进。4. 踩坑实录常见问题排查与团队协作经验写 CLAUDE.md 这件事听起来简单做起来全是细节。我在这上面踩过不少坑也帮团队解决过类似问题。下面把这些高频问题和排查思路整理出来基本上你遇到的 90% 情况都能在其中找到答案。4.1 高频问题速查表问题现象可能原因处理建议修改 CLAUDE.md 后 AI 行为没变化当前会话仍是旧上下文新开一个会话再测试或确认文件路径是否在项目根目录AI 总是不遵守“禁止”规则规则表述太软用了“建议”“尽量”换成“禁止”“必须”并给出违反后的替代方案上下文被 CLAUDE.md 占满文件太长或把大量示例代码塞进去精简到千字以内把详细文档放到 docs/ 并让 AI 按需读取与同事的 CLAUDE.md 冲突多人各自维护了一份内容不一致纳入版本控制并通过代码评审确认规则变更AI 执行规则时无端扩大范围规则没有定义边界在规则里补充“不做什么”和“允许例外的情况”CLAUDE.md 被当成普通说明文档缺少可执行条目全是概述型描述改成“新增接口必须返回……”“禁止手动修改……”这类条目表格里最容易忽略的是“文件太长”的问题。CLAUDE.md 不是越详细越好它每次都会完整进入上下文吃掉的是你用来处理业务逻辑的 token 空间。文件太长的直接后果是AI 虽然“知道”规则但执行时不能把注意力集中在当前任务上。我的判断标准是如果一个规则不能在三行内说清楚就把它拆成“CLAUDE.md 里写结论 docs/ 里写原因”的结构。4.2 让规则真正被执行从语气到结构的关键细节很多人问我为什么明明写了“不要用 npm”AI 还是用 npm我排查后发现多数情况下不是 AI 不看文件而是规则表达得不够“强”。语言模型对命令式和描述式的响应差异很大当你写“项目使用 pnpm”它可能理解为一种背景介绍当你写“统一使用 pnpm禁止使用 npm”它才会把这条当成强约束。另一个关键细节是“例外条款”。AI 在处理复杂任务时会倾向于寻找规则的漏洞。比如你写了“禁止修改 public/ 目录”但没说明如果必须改怎么办它可能在某个边缘场景下认为“这次任务是例外”。为了避免这种情况我会在禁忌条款里补一句“如果确有需要先停下来询问用户确认”。这等于给 AI 装了一个“刹车”让它不确定时就停下来而不是自作主张。结构上还有一个小技巧把最重要的规则放在文件靠前的位置。虽然 Claude Code 会加载整个文件但模型对越靠前的内容注意力权重通常越高。技术栈、禁忌这两类信息优先级最高我会放在文件前三分之一架构说明等辅助信息放后面。这个顺序不是绝对标准但实测下来的执行率确实有差异。4.3 团队协作中的 CLAUDE.md 管理经验CLAUDE.md 在个人项目里是“记事本”在团队项目里就是“契约”。契约就要有版本、有评审、有共识。我建议团队把 CLAUDE.md 的变更纳入常规代码评审范围任何规则增删都应该在 PR 里像代码一样被 review。这样既能让规则保持权威也能避免某个成员的私人偏好悄悄混进团队规范。还有一个容易被忽略的场景新人入职。给新同学分配一个 AI 编程任务前先让他读一遍 CLAUDE.md。这不是形式主义而是让他了解团队约定最快的方式。我见过不少新人刚上手时写出的代码风格和团队格格不入原因就是没人告诉他这些潜规则而 CLAUDE.md 恰好补上了这个信息差。在多人协作时我还会区分“用户级”和“项目级”文件的使用边界。个人习惯比如编辑器偏好、提交信息里想用中文还是英文放到用户级文件团队共识比如统一包管理器、接口返回结构、目录划分原则放项目级文件。这样分完之后即使团队成员各自有自己的用户级配置项目级的核心约束也不会被覆盖。4.4 进阶玩法多级文件与动态规则最后分享两个进阶用法适合项目结构比较复杂、或者你已经在 CLAUDE.md 上尝到甜头的情况。第一个是多级文件。部分工具支持子目录级别的 CLAUDE.md放在某个子目录下的规则文件会在处理该目录内文件时生效。比如你的 monorepo 项目里有packages/web和packages/server可以在每个子包里分别写一份更细的规则比如前端专属的组件规范、后端专属的 API 规范。这样项目根目录保持精简子目录内的精确规则也不会互相干扰。第二个是引用外部文档。不要把大段架构说明直接堆进 CLAUDE.md而是写一句“涉及数据库设计请先阅读 docs/database.md”。AI 在需要时会主动去读这些文档既满足了信息完整性又减轻了上下文负担。这个方法非常适合老项目架构细节特别多但真正影响编码的规则往往就那几条。我自己的实践体会是CLAUDE.md 的价值不是从写出来那一刻实现的而是在一次次“AI 犯错 → 补规则 → 错误消失”的循环里滚出来的。第一次写它花不了半小时但它帮你省下的重复沟通时间远不止这半小时。如果你手头正好有一个项目在用 AI 编程建议今晚就试试先写一个二三十行的极简版本跑通验证然后从第一个坑开始迭代。