先说结论CLAUDE.md是 Claude Code 里最值得认真维护的一份文件没有之一。我见过太多人装好 Claude Code 之后第一反应是去调模型参数、折腾各种模型切换工具却几乎不动CLAUDE.md。结果就是每次开新会话都要重新解释一遍项目背景、技术栈、代码规范同一个问题反复踩坑Agent 的发挥全看现场心情。这不是工具不好用而是你没给它“入职培训”。CLAUDE.md就是 Claude Code 的“入职手册 项目脑图 操作规范”三合一。写好了等于给你的 Agent 提前装上了项目记忆它能准确理解你仓库里每个目录在干什么、遇到什么场景该用什么方案、哪些命令绝对不能碰。今天这篇文章不聊虚的我把这套文件从原理到写法、从模板到踩坑完整拆一遍照着改就能用。1. 先搞清楚CLAUDE.md 到底在解决什么问题1.1 它像一份“入职手册”而不是普通的说明文档很多人的第一反应是这不就是一个 Markdown 文件吗项目里写 README 不就成了还真不是一回事。README 面向的是人类开发者你会在里面写“如何安装依赖”“如何启动服务”但不会写“修改数据库结构前必须确认迁移脚本”“这个模块的异常只能往消息队列里抛不能直接写日志文件”——这些约定只有团队里的“老员工”才知道。CLAUDE.md的作用恰恰就是把这些“老员工才知道的事”固定下来让 Claude Code 在第一次进入仓库时就像一个已经入职半年的工程师而不是一个两眼一抹黑的新人。你在日常对话里不断重复的背景说明、约束条件、代码风格偏好本质上都是在临时教会它这些约定。与其每次说不如一次性写进CLAUDE.md。1.2 Claude Code 是怎么读这份文件的机制与优先级我实测下来的体感是CLAUDE.md会被自动加载进每次会话的上下文相当于它在对话开始前就已经“读过”这份文件了。所以你不需要在每次提问时手动说“请先看一下CLAUDE.md”只要文件放在正确的位置它就会生效。读取的优先级从高到低大概是当前目录下的CLAUDE.md→ 项目根目录的CLAUDE.md→ 用户级全局配置。这意味着你可以在不同层级分别放置配置文件实现“全局习惯 项目个性”的组合。另外如果同一份内容在项目级和全局级都定义了项目级会覆盖全局级这一点在团队协作时特别重要——项目里的规范永远优先于个人习惯。1.3 值得投入时间吗前后差异对比我拿自己一个实际项目做过对比。没写CLAUDE.md的时候让 Claude Code 改一个 API 接口它经常会把错误处理的风格写偏比如项目里约定错误统一返回{ code, message, data }结构它偏给你写一个throw new Error()然后让前端硬解释写了CLAUDE.md之后这类风格漂移明显减少指令一次到位几乎没有反复。换句话说写一份CLAUDE.md的时间成本大约在半小时到一小时但它省下的是后面每一次对话里反复解释和纠错的时间。这个投入产出比在我所有项目里都是正向的尤其是中大型仓库收益会越来越明显。2. 内容规划什么该写什么不该写2.1 项目身份信息让 Agent 一眼知道自己在哪一份合格的CLAUDE.md开头必须是“自我介绍”。Claude Code 虽然能扫描目录结构但目录结构不等于业务背景。你需要明确告诉它这个项目是什么、服务谁、核心业务链路是什么、代码仓库里哪几个目录是真的核心哪几个只是边缘工具。我习惯写这样一段开场白# 项目简介 - 这是一个面向中小商家的小程序电商后端核心业务是商品管理、订单流转和优惠券核销 - 技术栈Node.js 18 TypeScript PostgreSQL Redis RabbitMQ - 核心目录说明 - src/modules/业务模块按领域划分新功能优先在这里增加模块 - src/common/公共组件与工具函数改动前必须检查引用方 - src/infra/数据库、Redis、消息队列等基础服务封装这段信息看起来简单但价值非常大。它相当于给 Agent 画了一张“仓库地图”后面你让它去改订单模块它知道应该去src/modules/order/找代码而不是在src/common/里瞎翻。2.2 技术栈与工程约定固定变量的价值第二层是技术约定这是最容易被人忽略的部分。很多项目的代码风格和架构约定不是写在 README 里的而是口口相传的。比如你们的数据库表名统一小写蛇形、接口返回包一层data、错误码前三位代表模块编号。这些细节恰恰是 Claude Code 写出“不像项目里该有代码”的主要原因。我通常会把这部分拆成两块。一块是硬性规范必须遵守、不可违背比如用 pnpm 而不是 npm、提交信息必须按 Conventional Commits 格式、禁止直接修改数据库表结构而是通过迁移脚本。另一块是软性偏好建议遵守比如优先复用src/common/下的工具函数而不是重新造轮子、组件命名用 PascalCase 还是 kebab-case。硬性规范和软性偏好在CLAUDE.md里要区分清楚我建议用“必须/禁止”和“优先/推荐”这类词做明显的语义区分Claude Code 对这类指令词的敏感度比我预想的高。2.3 工作流与安全边界比所有提示词都管用这一块才是CLAUDE.md真正的核心价值所在。你不仅要告诉 Agent“项目里有什么”还要告诉它“什么能做什么不能做”。比如绝对不要在未询问用户的情况下执行git push到 main 分支绝对不要运行rm -rf类的危险命令即使你确认目录里有生成文件修改src/infra/下的数据库代码前必须先列出影响范围执行测试时只跑相关模块的测试不要全量跑这些约束写在提示词里会显得很啰嗦但写进CLAUDE.md就变成了一条条“公司制度”。实测下来Claude Code 在行动前会参考这些约束来约束自己的行为尤其是涉及危险操作时它会主动停下来问一句“确认要执行吗”。这个行为在没写约束时基本不会出现它会更倾向于直接执行你下达的命令。2.4 分层配置的边界与适用场景全局配置和项目配置要分开切不可混在一个文件里。全局CLAUDE.md放个人习惯和通用规范比如“代码中用中文写注释”“API 设计优先 RESTful 风格”“不要解释代码直接给修改后的完整代码”。项目级CLAUDE.md放仓库特有信息比如模块结构、部署方式、环境变量清单。有人会觉得这样麻烦只写一个项目级配置不就行了我试过的问题在于你会不自觉地在项目级配置里塞入通用偏好换一个项目时就得重新复制粘贴一遍而且容易漏。分层的本质是把“稳定的个人习惯”和“可变的项目事实”隔离维护成本反而更低。目录级配置则适合 monorepo 仓库在子包目录里单独放一份针对该子包的CLAUDE.md这样 Agent 进入不同子包时会自动加载不同约定。3. 从零到一配置一份可用的 CLAUDE.md3.1 动手前先做信息盘点不要上来就写先花几分钟盘点一下项目里的“隐性知识”。我的做法是打开仓库把下面几个问题过一遍这个项目最核心的业务链路是什么登录 → 下单 → 支付 → 出票 → 退款哪些命令是必须通过特定工具执行的比如pnpm db:migrate而不是直接改表项目里有没有特殊的设计约定比如所有接口必须做幂等处理哪些目录改动风险最高比如src/infra/、src/shared/测试、构建、部署分别用什么命令这几个问题答案不需要写得很长每一条一两句话就够了但一定要具体。宁可写“支付回调必须做验签验签失败返回 401”也不要写“注意安全”。3.2 一份可直接改的模板与逐段解析下面是我最近在项目里验证过的一份模板结构清晰、覆盖完整你可以直接复制改造成自己的。# 项目名称工单服务 - 定位面向客服团队的工单管理系统核心链路是工单创建 → 分派 → 处理 → 归档 - 技术栈Node.js 22 Fastify TypeScript MySQL 8.0 Redis - 包管理使用 pnpm禁止使用 npm/yarn ## 目录结构 - src/api/路由与控制层只处理参数解析和响应格式不写业务逻辑 - src/service/业务服务层核心业务逻辑都在这里 - src/repository/数据访问层所有 SQL 操作集中在这里 - src/shared/全局共享类型、枚举、常量 ## 关键约定必须遵守 - 所有接口响应格式统一为 { code: number, message: string, data: T }code 为 0 表示成功 - 数据库访问必须走 src/repository/禁止在 service 层直接写 SQL - 所有金额字段用整数单位分禁止使用浮点数 - 新增表结构必须通过迁移脚本脚本放 db/migrations/禁止直接修改线上表结构 ## 工作流必须遵守 - 改动代码后先编译pnpm build - 涉及接口改动时必须同步更新 src/api/docs/ 下的 OpenAPI 文档 - 禁止直接推送 main 分支所有改动通过 PR 合并 - 删除文件或重构公共模块前先列出影响范围并等待确认 ## 测试推荐 - 单个模块测试pnpm test -- 模块名 - 全量测试pnpm test - 新增功能建议补一个最小用例不要追求覆盖率但核心链路必须覆盖 ## 本地环境 - 需要 MySQL 8.0默认连接信息在 .env.local 中 - 启动命令pnpm dev - 迁移命令pnpm db:migrate这份模板最核心的一点是它把“必须”和“推荐”分开了。Claude Code在执行任务时对“必须”级别的内容违规率明显低于“推荐”级别的内容这个用词差异在真实使用中非常关键。3.3 首次运行后的迭代方法写完CLAUDE.md不意味着结束而是开始。第一次运行 Claude Code 时建议先问它几个验证性问题比如“按照这份文档修改工单状态需要哪些步骤”看它的回答是否和你预期一致。如果答偏了说明CLAUDE.md里对应的描述有歧义或缺失需要调整措辞。我的经验是第一周每天都会微调CLAUDE.md。今天发现它在改数据库代码时没有先看迁移脚本就补一句“数据库结构变更必须使用迁移脚本”明天发现它在写接口文档时漏了错误码定义就再补一段错误码规则。两周之后这个文件会基本稳定下来后面就是偶尔增补了。3.4 迭代时的三个删除原则会写还要会删。随着项目演进CLAUDE.md里容易堆砌一些已经过时的约束比如“服务部署到 PM2不要用 Docker”这条在项目已经迁移到 Kubernetes 之后还留着就会误导 Agent。我给自己定了三个删除原则项目事实变了比如换了包管理器、改了目录结构第一时间清理旧描述同一件事写了超过三句话的简化成一句话信息密度优先已经变成代码层面天然约束的比如 eslint 强制规则不需要再写在CLAUDE.md里省上下文空间文件短一点Agent 读取和遵守的效果反而更好这一点后面细说。4. 环境准备与常用工具链配合4.1 安装与基础环境要点虽然标题是配置但很多人实际上卡在环境上。装 Claude Code 之前建议先确认本机 Node.js 版本我踩过的坑是 Node 16 以下直接装不了或者装上后运行报各种奇怪的模块错误。推荐用 nvm 管理 Node 版本稳定在 Node 18 LTS 或更高版本。Git 也是必须的装好之后要检查一下用户信息是否配置完整。我第一次在 Windows 上装完 Claude Code运行时因为 Git 用户名为空导致提交操作失败排查了半天最后发现是.gitconfig里没有配user.name和user.email。Windows 上还有一个高频坑PowerShell 执行策略。直接运行 Claude Code 的命令被拦下来提示“此系统上禁止运行脚本”。解决方式是在管理员权限的 PowerShell 里设置Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这个设置只影响当前用户风险可控。4.2 本地模型场景Claude Code cc-switch Ollama 的配置差异很多人在本地环境玩 Claude Code 时会搭配模型切换工具比如 cc-switch再挂上 Ollama 拉本地模型。这个组合的吸引力在于不依赖云端 API本地跑数据不出机器。但这里有一个很现实的问题本地模型的能力边界和云端模型完全不同。我实测下来云端 Claude 模型对CLAUDE.md的长上下文理解能力很好即使你写了很多条目它也能在任务中动态引用对应的规则。但本地模型参数量小、指令跟随能力弱CLAUDE.md里堆太多条目之后它反而不知道怎么执行了经常顾此失彼。所以在切换到本地模型的场景下我会专门准备一份精简版的CLAUDE.md只保留硬性安全约束和核心命令把长篇规范注释掉或者用目录级配置隔离。另一个建议是在 cc-switch 里切换不同模型环境时优先确认CLAUDE.md的格式对目标模型友好。有些本地模型对 Markdown 标题结构的解析不如云端模型稳那就改成更扁平的列表式表达。这个细节很多人忽略但实际效果差异非常大。4.3 团队协作把 CLAUDE.md 当团队代码资产管理如果是一个团队在用 Claude Code建议把CLAUDE.md纳入版本管理并且像代码评审一样对待它的变更。团队里任何成员发现 Agent 反复踩同一个坑就把对应的规则补进CLAUDE.md然后横向同步到所有成员。这个流程跑起来之后团队里关于代码规范的很多争论反而被沉淀成了“代码事实”而不是停留在口头约定层面。另外需要注意全局CLAUDE.md在团队场景里不要写个人偏好而是写团队共识项目级CLAUDE.md才是写模块边界和部署流程的地方。层级混乱Agent 读取到的会是一堆互相冲突的指令表现还不如不配。4.4 与 VSCode、桌面端的配合热词里频繁出现 VSCode 配置我实测下来 Claude Code 在 VSCode 集成终端里运行最顺滑。不需要额外装插件直接打开项目目录、启动终端、运行claude命令就能用。需要注意的是如果你在 VSCode 的配置里设置了默认 shell 为 PowerShell记得用nvm use确认 Node 版本已切换否则可能跑起来时用了系统的旧版本 Node。桌面端则更偏可视化操作适合不习惯命令行场景的人。实测下来桌面对项目目录的权限控制会更严格打开项目时必须手动授权。这种情况反而不容易发生 Claude Code 误改文件的问题算是一个意外的好处。5. 高频问题与排查实录5.1 CLAUDE.md 完全没生效先查这四件事我在不同机器上配过多次最常见的“配置了但没生效”其实原因都出在几个特别基础的地方。第一个是文件名大小写系统要求的是全大写CLAUDE.md手滑写成claude.md就不被识别第二个是位置不对文件只在启动命令所在目录或上级目录找放到其他任意目录都不会被加载第三个是文件里全是被注释掉的内容或者整个文件是空模板Agent 加载了等同于没加载第四个是缓存问题如果改了文件但开了很久的会话需要在会话里重开或者重新加载项目它才会读取新的内容。这四个问题我用表格整理一下方便排查现象常见原因快速验证方法完全不生效文件名小写或拼写错误执行ls查看实际文件名只对部分目录生效文件位置和启动目录不一致把文件移动到项目根目录提示词反复跑偏文件内容被注释框包裹检查是否有!-- --包住正文改完没变化当前会话缓存未刷新重启 Claude Code 新开会话5.2 权限、limit 限制提示该怎么理解实际使用过程中偶尔会看到类似 “your limits are temporarily boosted” 或 “weekly limit” 的提示。这个提示本质上是账号额度的管理机制和CLAUDE.md的配置没有直接关系但很多人会误以为是配置坏了开始反复改文件。我的建议是看到这种提示先别动配置检查账号的订阅状态和使用量。如果是额度周期到了等周期结束会自动恢复配置文件不需要做任何调整。另外如果用的是自己的 Key 接入额度计算会按用量走到对应限制这时候CLAUDE.md的内容越长越容易在长时间对话中占用更多 token 量。为了省额度不少人的做法是把文件尽量精简只保留高价值信息这也是我把“删减原则”单独列出来的原因。5.3 上下文被占满指令“漂移”了怎么办长会话里最容易出现的一个问题是聊到后面Claude Code 好像忘了CLAUDE.md里的某个关键约束开始自由发挥。这不一定是它“故意”违反更多是因为长对话的上下文窗口里塞满了最新的代码和问答记录早期的文件约束被冲掉了。这种场景下我常用的办法是先把长对话“瘦身”。把已经完成、不再相关的任务用一条指令收尾掉然后重新开一段新会话继续当前任务。新会话重新加载CLAUDE.md约束就回来了。另一个办法是直接把关键约束内容复制到当前对话里追加一句“请严格遵守以下要求”不过这属于临时手段真正长久的解法还是保持会话的单次任务粒度。5.4 报错速查表把我在多个环境里遇到过的真实报错整理成一张速查表。这里的意义不只是记录问题更重要的是让你遇到类似报错时不需要再花时间反复搜索。报错特征常见原因解决方式... not recognizedNode 版本过旧或未安装用 nvm 安装 LTS 版本后重试执行安全策略报错WindowsPowerShell 限制脚本设置当前用户 RemoteSigned 执行策略Git 操作报错或权限校验失败未配置用户信息配置user.name和user.emailAPI 限流或额度提示账号额度用尽或超限检查订阅额度等周期恢复模型输出内容不符合约定CLAUDE.md规则不够具体把泛泛的“注意安全”改成具体禁止项排查报错的顺序也很关键。我会先看是不是环境问题Node/Git/PowerShell再看是不是网络请求问题最后才看是不是CLAUDE.md写得不清晰。很多人一上来就改配置反而把问题带偏了。6. 最后再分享几个实际维护心得CLAUDE.md不是写一次就一劳永逸的文件它更像一个持续维护的“配置资产”。我自己的习惯是每两周花个小十分钟把本周对话里反复出现的纠错点回看一遍然后把最高频的那几个沉淀进文件里反过来如果某个规则连续两三个星期都没有被触发过一次我就会考虑删掉它给文件瘦身。关于篇幅我的体感是项目级CLAUDE.md控制在 100 到 150 行以内效果最好。超过 200 行之后Agent 读取和遵守的稳定性明显下降尤其是一些次要规则容易被忽略。所以优先级很重要安全边界第一工作流第二技术约束第三项目背景第四。明确优先级之后哪怕以后要压缩篇幅也知道先删哪部分。还有一个实用技巧在CLAUDE.md里给规则加“示例”。比如写“所有接口响应格式统一为{ code, message, data }”时顺手附上一个真实的返回 JSON 示例。这个细节能让 Agent 的模仿准确率高一大截。原理很简单大模型本质上是在做概率预测给它一个清晰的正例比给它十条抽象说明更有效。配置CLAUDE.md这件事本质上是在人和 AI 之间建立一套稳定协作的接口协议。你愿意花多少时间认真整理这份文件Claude Code 就能省下多少倍时间来理解你的项目。按上面的模板和迭代方法跑两三周你会明显感觉到对话质量的变化。