先说明一下我做 CLAUDE.md 这件事前后折腾了快一个月。最开始只是随手在项目根目录丢了一个说明文件后来发现这个东西用好了真的能改变和 AI 协作的方式。这篇内容算是我把这段时间的实践、踩坑、还有最终沉淀下来的写法做个系统整理希望对正在用或者准备用 CLAUDE.md 的人有点参考价值。CLAUDE.md 简单说就是给 Claude Code 这个命令行 AI 编程工具看的项目说明文件。你把它放在项目根目录Claude 每次启动时都会自动读取里面写的是你这个项目的背景、技术栈、代码规范、常见的坑、偏好用法等等。它的本质是让 AI 在动手写代码前就理解你的项目上下文而不是靠每次对话里反复交代。我用下来的感觉是如果你的项目只是临时跑个脚本那 CLAUDE.md 可有可无但只要项目稍微复杂一点比如有多人协作、有固定架构、有历史包袱一个好用的 CLAUDE.md 能让你少说几百句废话而且 AI 生成的代码质量会上一个台阶。这篇文章主要面向两类人一类是刚开始接触 CLAUDE.md想知道这东西到底怎么用、值不值得花时间写另一类是已经写了但觉得效果一般想看看别人是怎么组织和优化的。我会把从零到一的过程、我自己反复调整后的版本、还有实际工作中遇到的典型问题都讲清楚。1. 整体理解CLAUDE.md 到底是什么解决什么问题1.1 它的工作机理以及和普通注释的区别先用大白话解释一下它为什么有用。你平时在代码里写注释是给路过的程序员看的AI 当然也能读到但那是它自己翻文件翻到的信息是被动的。CLAUDE.md 不一样它相当于你主动递给 AI 一份项目使用说明书而且是在 AI 每次开工前就塞到它手里的那种。Claude 在处理任务时会先读这个文件来建立对整个项目的基本认知。你在这个文件里写本项目使用 React 18 TypeScript状态管理用 Zustand后端 API 走的是 REST 风格禁止在组件里直接操作 DOM那么接下来它生成的代码、给的方案建议天然就会往这个方向上靠。这不是临时的口头叮嘱而是一种持续生效的项目级约束。很多人问这和 README 有什么区别区别太大了。README 是给人看的讲究的是讲清楚项目怎么跑起来、怎么用语气往往是中性的介绍。CLAUDE.md 是给 AI 看的干活手册它不需要解释什么是依赖怎么安装它要写的是这里我们约定怎么干活、有什么禁忌、有哪些痛点和历史包袱。一个是导航一个是操作规范。1.2 我为什么开始写 CLAUDE.md一次糟糕的协作体验我决定认真写这个东西是因为一次非常失败的协作。当时我给一个老项目加新功能这个项目是几年前写的技术栈比较老还是 JavaScript 写的目录结构也乱里面各种历史遗留代码。我懒得跟 AI 解释太多直接甩给它一个需求结果它给我生成的新代码风格和旧代码完全不一致用了一堆项目里根本没有的库还往老模块里塞了新架构的东西。我当时就意识到问题不在 AI 的能力而在于它对项目的理解是从零开始的。它不知道这个项目的技术选型为什么是这样不知道哪些地方是雷区也不清楚代码风格和历史约定。我如果花十分钟把这些内容写成一份文档后面能省一个小时甚至更多。CLAUDE.md 就是干这个的。1.3 适用场景和边界要说清楚这个东西的边界我的感受是CLAUDE.md 不是万能药它也解决不了所有沟通问题。它最适合的场景有这么几类项目有明确的技术栈和架构约定希望 AI 的代码风格和项目保持一致项目里有复杂的业务逻辑、历史遗留代码或者模块之间的隐晦依赖需要 AI 了解这些背景团队有固定的代码规范、命名规则、提交规范希望 AI 在生成代码时自动遵守你经常在同一个项目里反复和 AI 协作希望它的输出保持稳定和一致。不适合的场景也有一次性脚本、demo 项目、临时测试代码写了反而浪费时间项目还在快速原型阶段每天的架构和命名都在变文档很快就过时了你的项目本身是全新的、没有历史包袱AI 直接生成也不会太走样。一句话总结我的经验CLAUDE.md 的价值和项目的复杂度成正比项目越复杂、历史包袱越重这东西的收益就越大。2. 内容设计CLAUDE.md 里该写什么、不写什么2.1 我最终沉淀下来的信息架构经过几轮摸索我把一份好用的 CLAUDE.md 拆成了几个固定的部分每个部分管一个方向。这个架构不是网上的模板是我自己根据实际项目中频繁遇到的问题总结出来的基本已经稳定下来。我的 CLAUDE.md 包含以下几个板块项目概况与约束项目是干什么的技术栈是什么有没有硬性的环境约束比如必须兼容某个 Node 版本、不能使用某个依赖等。代码风格与结构化约定命名规范、目录组织方式、组件/模块的组织约定、代码注释的风格等。常用命令与开发流程启动命令、测试命令、构建命令、代码检查命令以及日常开发的工作流比如是否用 rebase 还是 merge、提交信息的格式等。架构与模块关系核心模块有哪些它们之间是怎么通信的有没有单向依赖的约束哪些模块是不能随意改动的底层模块。历史遗留与雷区提示这个项目里不能碰的地方、已知的坑、某个复杂函数为什么那么写、改动某处会导致什么连锁反应。AI 协作偏好你希望 AI 在回答问题时用什么风格比如是直接给代码还是先给方案、生成代码时是否要附带注释、遇到不确定的问题时是询问还是自行判断。2.2 每个板块写什么的思考项目概况这块我觉得不用写太长但是技术栈必须写清楚。尤其是有多个相似技术的时候比如项目里同时用了 Vue 2 和 Vue 3你必须在文件里明确说核心代码是 Vue 3legacy 目录下的老模块是 Vue 2新增代码一律使用 Vue 3 API。这种信息你不写AI 很容易在混用的代码库中帮你写出风格不一致的东西。代码风格和结构化约定这部分要写得具体不要只写代码风格保持一致这种话对 AI 没有约束力。要写明组件文件使用 PascalCase 命名工具函数使用 camelCase样式文件与组件文件放在同一目录下。关键是要让 AI 能够照做而不是让它在模糊中猜。常用命令这部分我建议写清楚。因为 AI 在帮你改代码时可能需要跑测试或者构建来验证它的改动如果你在 CLAUDE.md 里明确写了测试命令是npm run test:unit它就不会傻乎乎地跑完整套测试甚至不会试图用一些奇怪的命令。这里有个细节就是命令要写到可以直接复制运行的程度包括参数。架构与模块关系这部分是最难写但也最值钱的。因为这属于项目里只有老人才知道的知识AI 是不知道的。你把它写下来AI 相当于瞬间获得了一个老开发者的经验。比如目前项目的主要模块有 threea 模块负责用户认证b 模块负责订单处理a 模块通过 event bus 通知 b 模块不允许 b 模块反向引用 a 模块的内部方法。这种信息一旦写清楚AI 在生成跨模块代码时就会格外小心不会乱引依赖。历史遗留与雷区这部分是我的最爱。因为一个项目里总有那么几段代码看起来写得丑陋、不合理但其实是当时各种条件限制下的产物是不能随意优化的。如果没有在 CLAUDE.md 里标注AI 很容易把这个当成代码坏味道自动帮你重构一番结果把系统搞挂。我见过太多次 AI 自作主张改掉看似不合理但实际上是核心逻辑的代码。这块一定得写。AI 协作偏好这一节一开始我没写。但后来发现每个人的工作习惯不一样写进去反而能提升体验。比如我习惯让 AI 先给出方案再动手改代码遇到对业务影响较大的改动时先停下来问确认。这些我都可以在 CLAUDE.md 里约定好不用每次对话都重申。2.3 内容的长度和写作粒度关于写多长我的建议是不要把它变成一本百科全书。太长的 CLAUDE.mdAI 读取和处理的时间会增加而且信息密度降低核心约束反而不突出。我自己用的版本大概在三到四百行左右控制在 AI 能一次性快速读完的范围。太短了起不到约束作用太长了就是灾难。而且我后来发现一个重要的经验CLAUDE.md 是活的要经常更新。我一开始把它当成一个一次性文档写完就不管了。后来发现项目在演化CLAUDE.md 里的内容如果不跟着更新AI 就会拿着过时的事实去写代码比没有更糟糕。现在我的习惯是每当项目里出现一个新的重要约定、踩到一个新的大坑就顺手把它补充进去。3. 实操要点怎么写、怎么调、怎么让 AI 真正听你的3.1 写作时的一个核心原则具体、具体、再具体这是我最想强调的一点。写 CLAUDE.md 最大的忌讳就是写抽象的话。比如你写注意代码质量这就等于没写AI 不知道怎么执行。你要写的是所有工具函数必须写 JSDoc类型定义必须使用 TypeScript 的 interface 而不是 type这种可以直接检查的规则。我在实践中总结了一个判断标准如果你写的内容可以让一个不知道项目背景的新程序员读完就照做而且做出来的结果符合预期那这个描述就是合格的如果你读完还是不知道怎么操作那这个描述就是无效的。比如我在 CLAUDE.md 里写错误处理 - 所有 async 函数必须 try/catch 包裹禁止裸抛 error - 错误信息使用统一的中文文案格式操作失败xxx - 用户可见的错误统一抛出 BizError内部错误直接 console.error 并返回默认值。这种写法AI 拿到任何一段代码都知道该怎么处理错误不用你每次交代。3.2 用正向指令 反向禁令组合表达写 CLAUDE.md 有一个很实用的技巧既写该怎么做也写不能怎么做。这种组合往往比单独一种效果更好。正向指令给 AI 一条明确的路径比如列表页使用 Table 组件渲染。反向禁令则用来划定禁区比如禁止在业务代码中直接使用 document.querySelector 操作 DOM一律通过 ref 获取元素。为什么组合有效因为 AI 在生成代码时存在多种可能的方案正向指令压缩了选择空间反向禁令排除了错误选项两者配合输出的代码基本就在你设定的范围内了。一个只有禁令的文件会显得很负面AI 可能不知道正确路径一个只有正向指令的文件AI 会在你没覆盖到的地方自由发挥。我还喜欢在 CLAUDE.md 里使用一些优先级词汇比如优先不要必须除非。这些词能被 AI 很好的理解。比如优先使用函数组件不要使用 class 组件除非现有文件已经大量使用 class 组件且改动成本极高。3.3 接地气的例子一份简化版的 CLAUDE.md 片段为了让内容更有参照性我贴一段我自己某个项目里 CLAUDE.md 的实际内容去掉敏感信息后结构大概是这样的# 项目背景 本项目是公司内部数据中台的前端部分使用 Vue 3 TypeScript Vite。 负责数据源的配置、数据任务的编排以及运行日志的查看。 # 技术约束 - Vue 3 使用 Composition API script setup 语法禁止使用 Options API - 状态管理使用 Pinia禁止引入 Vuex - 样式使用 less遵循 BEM 命名规范 - 图表统一使用 ECharts 5.x版本锁定禁止自行升级到 6.x - 所有 API 请求必须通过 src/api 目录下的统一封装函数发起禁止在组件内直接调 axios # 目录说明 - src/api: 与后端接口的封装层一个后端模块对应一个文件 - src/views: 页面组件每个路由对应一个文件夹 - src/components: 可复用的业务组件 - src/utils: 纯工具函数 - src/stores: Pinia 状态定义 # 代码规范 - 组件命名使用 PascalCase文件名与组件名保持一致 - props 定义必须使用类型声明的方式并给出默认值 - 禁止在组件内写超过 300 行的逻辑超出的部分拆分到 composables - 日志打印统一使用 src/utils/logger.ts 里的方法禁止直接用 console.log # 常见任务 - 启动开发环境: npm run dev - 运行单测: npm run test:unit - 构建产物: npm run build - 代码检查: npm run lint # 注意事项 - 数据任务编排的逻辑在 src/views/task/pipeline.ts 里非常复杂修改前必须读懂其中 workflow 的构建过程 - service 层与 view 层之间通过 qiankun 微前端通信不要随意修改消息的格式 - src/utils/date.ts 里的 formatDate 使用了自己实现的日期解析不要用 dayjs 替换因为依赖它做特殊解析的地方太多这样的 CLAUDE.mdAI 拿到手之后做出来的东西基本就在框架内很少出格。我一般不会写太长点到为止但是关键约束全部锁死。3.4 写作、迭代和更新的工作流我现在的流程基本稳定成了四步第一步先扫描项目里有没有明显的技术栈文件比如 package.json、tsconfig.json、现有的 README把可用的信息提炼出来第二步结合自己对项目的理解把脑中那些我知道但没写下来的信息补进去。这个步骤最重要因为 AI 缺少的就是这些隐性知识第三步把文件放回项目根目录跑几个真实任务测试看 AI 的输出是否符合预期。如果不合预期回头去修改 CLAUDE.md 的表述而不是在对话里反复纠正第四步项目演进过程中不断补充。比如发现 AI 在某类任务上反复犯错那就去 CLAUDE.md 里加一条对应的约束。这个在对话中暴露问题 → 优化文档 → 再验证的循环就是我对 CLAUDE.md 的核心工作方式。它本质上是在把和 AI 的一次性沟通沉淀成可复用的长期记忆。4. 实操过程从零搭建一份可用的 CLAUDE.md 全流程记录4.1 第一步先写雷区还是先写规范很多人问我是先写哪一部分。我的习惯是先写雷区再写规范。原因很简单雷区是那些一旦踩中就会出大问题的事优先级最高。比如禁止修改 a 模块的对外接口这条如果漏掉AI 改坏了你可能半天才发现。而代码风格这种就算 AI 写得不太对后面也可以靠格式化工具或者人工 review 兜底。刚开始写的时候不要追求完美先把那些最让你担心的、最容易出错的事情写进去。比如这个项目里最核心的、绝不能改坏的模块是哪个现有的第三方库版本有没有锁定升级会有什么后果是否存在某些代码是实现特定业务逻辑的魔法代码不能按常规逻辑去优化。这些内容优先级最高先写进去是在给 AI 划一个安全区。4.2 第二步把AI 反复问的问题变成文件内容第二个实操技巧可能比第一个更有效把你在和 AI 对话中反复说的内容写进文件。我统计过自己使用 AI 协作的过程发现很多问题是反复出现的比如这个项目的测试命令是什么这里的 API 是在哪里封装的为什么这个模块不能直接 import 那个模块。这些问题在有 CLAUDE.md 之前我需要每次对话时都给 AI 解释有了文件之后AI 自己就懂了不用我问。所以在搭建 CLAUDE.md 的时候建议你回溯一下和 AI 的对话记录把反复出现的那些解释性内容提取出来写进文件。这比凭空想象内容要高效得多也更贴合项目的实际需求。这里给一个具体的操作建议你在 AI 对话中如果发现自己说了我不是这个意思这个项目里...那这句话基本上就应该进 CLAUDE.md。4.3 第三步验证效果的方法论写完之后怎么知道写得好不好我有一套验证方法第一给 AI 一个不需要太多背景信息的小任务比如给 utils/format.ts 增加一个千分位格式化函数。如果 AI 生成的代码在命名风格、类型定义、注释方式上都符合你的要求说明基本规范已经起作用了。第二给 AI 一个跨模块的修改任务比如在用户列表页增加一个导出按钮导出当前筛选条件下的所有用户数据。这个任务涉及组件、API、工具函数、类型定义等AI 如果能在不询问的情况下自己找到正确的目录和调用方式说明项目背景和目录说明已经生效。第三故意设置一个雷区相关的询问比如问 AI修改 src/components/pipeline.ts 的 xxx 方法会影响哪些模块。如果 AI 能正确识别出这个文件是敏感文件并给出谨慎的回答说明雷区部分生效了。一般我验证三轮左右就能判断这份 CLAUDE.md 是否达标。4.4 第四步持续维护与团队共享我把 CLAUDE.md 纳入了项目的版本控制和代码一起提交。这样团队成员拉下来代码之后也能获得同样的 AI 协作体验。而且提交历史里可以看到 CLAUDE.md 的修改记录方便追踪内容变化。现在的维护频率大概是项目发生大的架构变动时比如引入新的状态管理库、切换构建工具必然更新遇到 AI 反复犯同一个错误时主动加一条约束每隔一两周我会整体扫一遍文件把过时的信息清理掉把不准确的描述修正。5. 常见问题与排查技巧实录5.1 问题一AI 好像完全无视 CLAUDE.md 里的规则这个是大家反映最多的一个问题。我自己的排查思路是这样的先确认 CLAUDE.md 确实放在项目根目录而且文件名、大小写都对。Claude Code 对文件名的要求比较严格如果文件名写成了 claude.md 或者 Claude.md有可能不会被正确识别。文件位置没问题的话再看看文件内容是不是有语法或格式问题。Markdown 格式一般来说都兼容但有些特殊的嵌套列表或者过于复杂的表格可能会导致 AI 解析出错。我后来习惯把 CLAUDE.md 写得尽量平少用多层嵌套列表多用简单的短句和标题解析成功率明显提高。还有一种情况是CLAUDE.md 里写的规则和代码里明显的事实冲突。比如你写项目使用 Vue 3但 AI 在 package.json 里看到 Vue 2 的依赖它会更相信代码里的实证。所以要保持文档和代码一致一旦代码变了文档没跟上AI 就会困惑甚至选择性地忽略文档。5.2 问题二同样的规则在不同任务里效果不稳定这个现象我也遇到过。同一份 CLAUDE.md有些任务 AI 执行得很完美有些任务好像完全没受文档影响。我的理解是AI 在决策时的信息优先级不完全由文档决定。当任务本身很清晰、规则明确时文档的作用就大当任务非常泛、需要大量推理时文档的影响会被稀释。举个例子如果你让 AI优化一下代码它会做很多判断此时 CLAUDE.md 里的风格规范只能约束一部分但如果你让 AI把 utils 里的 format 函数重构一遍要求符合项目代码规范那它的注意力就会集中在格式、命名、错误处理这些方面文档的约束力就会强很多。所以我现在写 AI 任务提示词时有意识地让任务描述更具体配合 CLAUDE.md 一起用效果比单纯依赖文档好很多。5.3 问题三文件越写越长AI 反而不听话了有一段时间我陷入了一个误区觉得规则写得越多越好把项目里所有细节都塞进去结果文件超过一千行。这时候我发现 AI 的行为反而变得不稳定了可能是因为信息太多核心约束被淹没在大量细节里。后来我做了一次减法把文件压缩到只保留关键信息。我的策略是同一个类型的规则只保留最核心的一到两句话把冗余的细节删掉不重要的背景信息直接删除把命令清单压缩到只保留高频命令。这次瘦身之后效果回升了。所以我现在一直提醒自己CLAUDE.md 不是文档库是约束集贵精不贵多。5.4 问题四项目里同时有多套代码怎么写才能不互相干扰在某些 monorepo 或者多端共存的工程里一份根目录的 CLAUDE.md 很难照顾到所有子项目的差异。我的做法是分级根目录放一份适用于全局的说明然后在各个子项目里放各自的 CLAUDE.md内容指向子项目特有的约定。如果 Claude Code 支持读取多个层级的配置文件那这种全局 局部的组合方式是最好用的。我在 monorepo 的实践下来判断标准是全局文件只写全仓通用的事子项目文件写这个子项目独有的事不要交叉混淆否则 AI 会在处理子项目任务时被无关信息干扰。6. 我踩过的一些坑以及最终留下的几条个人经验写到这里我想把自己最真实的几个感受分享出来这些经验不是从文档里学的是真金白银试出来的。第一CLAUDE.md 是拿来用的不是拿来写的。我曾经花两天时间精心打磨一份完美的文档结果项目里真正用到的频率没那么高投入产出比很低。后来我改成边用边写遇到问题就往里加反而效率更高。你不需要一开始就写一份完美的 CLAUDE.md先从一个小而实用的版本开始然后在真实使用中打磨。第二CLAUDE.md 的质量取决于你对项目的理解深度。它其实像一面镜子你越了解自己的项目越能把那些隐性知识写清楚AI 的协作效果就越好。反过来说如果你对项目本身也一知半解那这个文件大概率写不到位。第三不要把 CLAUDE.md 当成约束 AI 的枷锁。它更像是一种思维方式——把模糊的需求变成清晰的规则把隐性的知识变成显性的文本。这个过程本身就是一次很好的项目知识梳理即使抛开 AI 协作单纯做这件事也能让你对项目的理解更深一层。第四具体场景下要有耐心。不是每次写完就立刻见效有些规则可能需要两三次调整才能达到理想状态。我在实际使用中发现针对 AI 最容易犯错的那一两类问题单独花几次迭代去完善对应的规则描述远比一开始就追求大而全更有用。总的规律是你先明确最在乎的是什么然后把那部分写成最具体的规则其他部分慢慢补。CLAUDE.md 这个文件名每次看到其实都在提醒我一个朴素的经验好工具的价值不是看你装了多少功能而是看你把最重要的规则写得有多清楚。