最近跟几个做工程的朋友聊起 Claude Code大家反馈出奇一致新开一个会话它表现得像个聪明但完全不了解你项目的实习生你问它问题之前得先把项目背景、技术栈、目录结构、常用命令重新讲一遍。讲完它倒是懂了但只要换一个会话一切又从头开始。这显然不是模型本身的问题而是缺少一样东西——CLAUDE.md。这篇要聊的就是怎么通过 CLAUDE.md 配置文件给 Claude Code 设定一份真正“专属”的项目上下文。CLAUDE.md 本质上是放在项目根目录的一份 Markdown 文档Claude Code 启动时会自动读取把里面的内容作为对话的“预加载背景”。项目是什么、技术栈有哪些、命令怎么跑、代码风格如何、有哪些雷区都写清楚AI 就不需要你每次重新交代。配置得好不好直接决定 Claude Code 是“懂你的结对编程搭档”还是“每次都重新自我介绍的路人”。这篇文章我会从 CLAUDE.md 的工作机制、最小可用模板、内容组织策略、进阶最佳实践以及常见坑的排查方法五个角度展开结合我自己在不同项目里反复迭代配置的实际经验把能直接抄作业的部分都给你。这篇内容适合两类人一类是已经在用 Claude Code、但觉得它“不够懂你项目”的人看完可以立刻动手把配置补齐另一类是刚接触 Claude Code、想从一开始就把项目上下文管好的人照着模板搭一份基础配置后续随时可以迭代。1. 先搞清楚 CLAUDE.md 到底解决什么问题1.1 项目上下文的“失忆症”是怎么回事Claude Code 的工作方式和传统 IDE 插件最大的区别在于它是一套以“对话 工具调用”为核心的工作流。你给它一段任务描述它会根据当前会话里能看到的信息——包括你的提问、项目文件内容、命令执行结果——来生成回复。问题是一旦会话结束或者你新开一个会话之前聊过的约束、约定、背景信息它一概不记得。用行话讲它的每次会话都是一个“无状态”的起点。这个“失忆”在简单项目里问题不大但到了真实工程里就会很别扭。我手头有两个项目一个是用 Java Spring Boot 写的后端服务一个是 React TypeScript 的前端仓库。如果我不做任何配置每次让 Claude Code 帮我改后端代码我得先告诉它 Maven 是构建工具、Java 版本是 17、项目用了哪些常见库切到前端项目又得重新说一遍“包管理器是 pnpm、UI 库用的是 Ant Design、组件目录约定是按页面划分”。这种开场白式的重复说明一次两次还能忍受次数多了你会怀疑用 AI 写代码到底是提效还是添乱。CLAUDE.md 就是来根治这个问题的。它相当于一个常驻的“项目速记卡”AI 每次启动对话时都会先读到这份文件把你的技术栈、构建命令、代码习惯、业务背景一次性装进脑子里。配置好之后你再也不需要做上面那些重复解释直接说“帮我把登录接口的超时时间调一下”它就能自己定位到对应模块用你项目里约定好的模式去改。1.2 CLAUDE.md 的加载机制它什么时候生效理解加载机制能帮你避免很多“明明写了却不生效”的困惑。根据我的使用经验CLAUDE.md 的加载路径主要有两条一是项目级配置放在项目根目录下二是全局配置放在用户主目录的配置目录里具体路径取决于你的安装方式。引擎在每次启动新会话时会先去这些位置查找 CLAUDE.md找到就把内容注入当前的上下文窗口当作系统提示词的一部分。这里有几个值得注意的细节。第一配置读取发生在会话启动时所以如果你开了一个会话、然后临时去改 CLAUDE.md当前会话不会自动感知必须新开会话或者重载之后才生效。这一点我在初期经常踩坑以为配置不生效其实是这个原因。第二项目级配置和全局配置不是互斥关系两边都可以写但主题要分清楚全局配置放你个人的通用偏好比如“默认使用中文回复”“优先给出可运行的代码片段”项目配置放这个仓库特有的信息比如“后端模块在 server/ 目录下”“测试环境地址是 xxx”。两者各管一摊不要把事情混在一起写。还有一点需要说明CLAUDE.md 本身是明文的 Markdown所以不需要什么特殊的编译流程。它生效的唯一条件是文件路径正确、内容语法正常、会话能读到它。这也意味着你可以放心地把 CLAUDE.md 提交到 Git 仓库里让整个团队共享同一份项目上下文新成员接手项目时也能借助它快速了解仓库的全貌。2. 配置文件怎么写从零搭建能用的最小结构2.1 文件位置与命名规则先解决最基础的问题CLAUDE.md 应该放在哪里。我的习惯是放在项目根目录和 README.md、.gitignore 放在同一层级这样最直观Claude Code 启动时也能找到。命名就按默认规则用 CLAUDE.md注意大小写保持一致的写法不要随手改成 claude.md 或者 CLAUDE.MD虽然有些系统不区分大小写但为了跨平台可靠统一用全大写的 CLAUDE.md 最稳妥。如果你用的是 monorepo 或者多模块仓库情况会复杂一点。一种做法是在仓库根目录放一份总纲写清楚各模块的位置和关系然后在各个子模块目录里各自放一份 CLAUDE.md写该模块自己的约定。AI 在读取时通常会优先读当前工作目录附近的配置所以子模块级别的配置对具体任务的指导更精准。我个人的习惯是根目录配置控制“全局观”子模块配置控制“细节观”两级配合用效果比只放一份要好。2.2 最小可用模板记录什么才有效很多人的误区是一上来就把 CLAUDE.md 写成一片一百行的大作文结果 AI 反而抓不住重点。其实一份能用的配置不需要太长把最核心的五类信息写清楚就够了。我现在的模板大概长这样# 项目名称 ## 项目简介 一句话说清楚这个项目是做什么的面向什么用户。 ## 技术栈 - 后端Java 17, Spring Boot 3.2, Maven - 前端React 18, TypeScript 5, Vite, pnpm - 数据库MySQL 8, Redis 7 ## 常用命令 - 本地启动后端mvn spring-boot:run - 安装前端依赖pnpm install - 启动前端开发服务器pnpm dev - 运行全部测试pnpm test ## 代码风格 - 后端遵循阿里规约禁止使用 System.out.println 调试 - 前端使用 ESLint Prettier缩进 2 空格 - 变量命名后端驼峰前端组件大驼峰 ## 注意事项 - 不要修改 database/migration/ 下的历史迁移脚本 - 调用第三方支付接口前需要先走沙箱环境验证 - 接口返回格式统一为 { code, message, data }这个模板的核心逻辑是让 AI 在拿到任务时能准确回答四个问题——这个项目是干嘛的简介、用什么技术写的技术栈、怎么跑起来命令、写代码时要注意什么风格 注意事项。有了这四块绝大多数日常编码任务它就能独立开工了。有读者可能会问为什么我不建议一开始就写一堆非常细节的业务规则因为 CLAUDE.md 的目标是“够用就好”。配置太长AI 的注意力会被稀释反而可能忽略你最看重的几条约束。先把骨架搭起来之后发现哪块缺失再针对性补齐比一开始追求“大而全”更高效。2.3 全局配置与项目配置的取舍前面提到全局配置和项目配置可以并存但很多人纠结的是哪些内容该放到全局哪些该放到项目我的判断标准很简单——换一个仓库这条规则还成立吗如果成立就放全局如果只有当前仓库适用就放项目配置。比如“所有代码都需要考虑边界条件”这种属于通用准则放全局而“这个项目的鉴权 token 通过请求头 X-Auth 传递”就明显是项目专属放项目配置。如果全局配置和项目配置在某些点上发生了冲突我更倾向于让项目配置优先因为项目配置描述的是更具体的真实状况AI 在面对矛盾时也更容易采纳更具体、更贴近当前工作目录的信息。不过最好还是避免产生冲突一旦发现全局规则和项目规则打架优先修改其中一处别让 AI 去猜。3. 内容组织策略让 AI 一眼看懂你的项目3.1 用“给新同事看的 README”心态写我写 CLAUDE.md 时一直有个心态参考把它当成一份“给新同事看的快速上手说明”只不过这个“新同事”是 AI。新同事拿到项目先看到什么项目是做什么的、技术栈是什么、怎么跑起来、代码放哪里、要注意什么。这些恰恰就是 CLAUDE.md 应该承载的内容。但注意CLAUDE.md 和 README 是有区别的。README 面对的是人可以写很多背景故事、架构图示、人员链接而 CLAUDE.md 面对的是 AI需要的是可操作的信息。写的时候你要不断问自己如果 AI 读了这一句它真能据此做对事吗比如 README 里写“项目采用微服务架构”是背景介绍但 CLAUDE.md 里你还应该补充“服务间通过 HTTP 调用服务发现走 Nacos”这样 AI 才知道调试某个功能时应该去哪儿看。3.2 技术栈与命令规范怎么写才不啰嗦技术栈这一块最容易犯的错误是只写技术名词不写版本和用法。比如只写“Java Spring Boot”AI 就不知道你的项目是 Java 8 还是 Java 17是 Maven 还是 Gradle是用 Lombok 还是不用。正确做法是把版本、构建工具、常用库一并写清楚能给出命令就更好了。下面是我在某个项目里的写法## 技术栈与命令 - 运行环境Node.js 20.10, pnpm 9 - 主要框架Vue 3.4 TypeScript 5.3 Vite 5 - 状态管理Pinia禁止直接引入 vuex - 样式方案Less CSS Modules避免全局样式污染 - 接口请求统一通过 src/api/ 下封装的 request 方法禁止直接使用 axios ## 常用命令 - 安装依赖pnpm install - 启动开发pnpm dev - 类型检查pnpm type-check - 代码检查pnpm lint - 单元测试pnpm test -- --coverage把版本号和常用命令写清楚后AI 在生成代码、安装依赖、跑测试时就不会自作主张地用 npm 去装包也不会生成跟项目版本不兼容的语法。这一块花十分钟写清楚后面能给你省下大量来回纠错的时间。还有一个细节值得注意命令尽量给出“项目实际在用的命令”不要给“理论上可以用的命令”。比如你的项目里明明用的是 vitest你在配置里写 jestAI 就会严格按照配置去跑 jest结果全都报错。配置写的是约定但 AI 不知道你写错了它只会照着执行。3.3 代码风格与架构约束的表达技巧代码风格部分关键是“少写价值观多写可判定的规则”。什么叫价值观“代码要写得优雅”——AI 无法准确判断“优雅”的边界。什么叫可判定规则“每个函数必须有类型标注”“禁止使用 any 类型”“组件文件使用大驼峰命名”。这些规则 AI 能直接用来检查自己的输出。架构约束也同理。如果你的项目有明确的目录职责一定要写进去比如“业务逻辑统一放在 src/services/不要在组件里直接写数据请求”“数据库查询走 repository 层禁止在 controller 里拼 SQL”。这类约束能显著减少 AI 生成代码时的“乱放”问题。我在一个老项目里试过没写目录约束前AI 经常把工具函数塞进组件文件里写完配置之后基本就收敛了。4. 最佳实践让专属上下文真正发挥作用4.1 把项目“潜规则”显性化每个项目都有一些不写进文档、但团队成员心照不宣的“潜规则”。这些东西对真人同事来说靠口头传对 AI 来说就只能靠 CLAUDE.md 传递。如果你不给它它很可能在一个不合适的时机踩中雷区。我经历过最典型的例子是改数据库迁移脚本项目里已经有一批迁移脚本被线上执行过了团队约定绝不能再改只能新建迁移来修改表结构。AI 刚开始并不懂这个约定有一次直接帮我改了历史迁移文件差点引发线上问题。后来我在 CLAUDE.md 里加了一行“历史迁移脚本不可修改新增变更必须新建迁移文件”这个问题再没出现过。类似的“潜规则”还可以包括某个目录是从别处同步来的改动会被覆盖某个接口必须带特定请求头才能通过网关测试数据不要写入真实生产表接口返回的日期格式统一为时间戳而不是字符串。把这些写进配置AI 才真正拥有了“团队常识”。4.2 结合工作流的进阶配置测试、构建、部署基础配置解决的是“怎么干活”进阶配置解决的是“怎么把活干完”。也就是把项目的工作流规范也写进去比如测试怎么跑、分支怎么提、部署注意什么。下面是我在某个中大型项目里用到的进阶配置片段## 测试约定 - 新增业务逻辑必须补单元测试覆盖率不能低于 80% - 测试文件命名xxx.test.ts与被测文件放在同一目录 - 跑单个测试文件pnpm test src/components/xxx.test.ts ## 提交规范 - commit message 遵循 Conventional Commitsfeat/fix/docs/style/refactor/test - 提交前必须执行 pnpm lint 和 pnpm type-check确保无错误 ## 部署相关 - 生产环境部署通过 CI 流水线触发禁止手动 ssh 到服务器操作 - 环境变量通过部署平台配置不要写入代码仓库 - 发布前需要更新 CHANGELOG.md加了这些内容后AI 在协助你写测试、整理提交信息、准备发布时就会主动按照项目规范执行而不是给出泛泛的建议。有些团队可能还会把 CI 的产物路径、包发布的 npm 账号信息等写进去但我的建议是凡是涉及敏感凭据的内容一律不要写CLAUDE.md 是要进 Git 仓库的凭据信息应该走密钥管理而不是写进给 AI 看的上下文。4.3 配置迭代跟着项目演进CLAUDE.md 不是写一次就完事的静态文件它需要跟着项目的演进持续迭代。我的维护节奏是这样的每次发现 AI 在某个点上做错了而且这个错误是因为它不了解某条项目信息导致的我就会把这条信息补进配置。换句话说把配置当成一个“AI 踩坑记录”日积月累它的“专属感”才会越来越强。比如有一次 AI 帮我生成的代码里用了console.log做调试而项目约定是用debug库我就把这条补进去。又比如有一次它新增了依赖但没更新 lockfile我也把这个要求写进配置。坚持一段时间后你会发现 AI 犯错的频率越来越低因为绝大多数“它不知道但我以为它知道”的信息都被你沉淀进 CLAUDE.md 了。5. 常见问题与排查技巧实录5.1 配置不生效的排查思路配置不生效是我被问得最多的问题。排查思路基本可以按顺序走一遍第一确认文件位置和命名是否正确必须叫 CLAUDE.md 且放在预期目录第二确认会话是不是在修改配置之前启动的如果是新开一个会话再测试第三确认内容格式正常尤其是 Markdown 中嵌套了代码块时有没有出现遗漏的闭合符号第四检查配置是否被某些版本管理或忽略规则排除在外比如 .gitignore 把 CLAUDE.md 忽略了那团队成员或者 CI 环境里就读不到。5.2 上下文被忽略或理解偏移有时候配置写得没错但 AI 的行为还是偏离了配置里的要求。我遇到过两个比较典型的原因一个是配置内容太长关键规则被淹没在大量文字中AI 的注意力是有限的你需要把最重要的约束放在文件靠前位置或者单独加粗强调另一个是规则之间有冲突比如既写着“禁止修改迁移脚本”又写着“请灵活处理所有文件”AI 面对冲突时可能偏向更泛化的指令这时候就需要你统一规则口径明确优先级。还有一点是表达的精确度尽量用“必须、禁止、统一”这类强约束词而不是“建议、尽量”这类弱约束词。5.3 长项目下的维护策略当项目积累到一定规模单份 CLAUDE.md 会越来越长维护成本也随之上升。我的策略是CLAUDE.md 保持精简只放最核心、最稳定、最容易被违反的信息把那些详尽的、说明性的文档放到 docs/ 目录里在 CLAUDE.md 中用链接指向它们。这样 AI 既能在启动时快速读取到关键的约束又能在需要深挖细节时通过链接去查阅详细文档。日常维护时也可以做一些小动作把 CLAUDE.md 纳入代码评审范围改动时写清楚原因定期清理已经过时或不再适用的规则避免配置里留下误导信息如果团队有多人维护可以在文件里用注释段落标明每块内容的负责人方便追责和沟通。常见问题典型原因处理建议配置完全不生效文件名或位置不对或会话未重载检查命名与路径重开会话部分规则没被遵守配置过长、规则冲突精简配置明确优先级和强约束词修改后行为没变化当前会话仍用旧上下文新开会话不要在当前会话中测试团队其他人看不到效果配置未提交到仓库提交 Git并在评审流程中维护配置与全局规则冲突项目级和全局级规则矛盾统一口径项目级优先最后按照惯例说点我在实际使用中的体会。CLAUDE.md 这个配置文件的价值不在于它有多长的篇幅而在于它是否准确地传达了你对项目的理解。我见过一些把模板抄得漂亮但内容空洞的配置AI 读完依然一头雾水也见过有些团队在配置里只写了一句“这是一个电商项目”效果聊胜于无。真正好用的配置往往是在项目实战中一点点打磨出来的它记录的不是文档而是你和 AI 协作过程中总结出的“项目常识”。如果你打算现在开始动手我的建议是先用最小模板搭起来跑一个简单的任务验证效果然后带着“AI 还会在哪些地方犯错”这个问题持续迭代。用不了一周你就会发现 Claude Code 越来越像你的老朋友而不是每次都问“你的项目是什么结构”的陌生人。