CLAUDE.md 配置详解：让 Claude Code 每次启动都“懂你”的秘密武器

1. 为什么你的 Claude Code 每次启动都像失忆先说一个我观察到的现象很多人装好 Claude Code 之后用了一周就放弃了理由高度一致——“它老是改我不让它改的文件”“每次都要重新解释项目结构”“同一个错误纠正三遍还是犯”。这不是模型能力问题而是你从来没有给它一份稳定的项目记忆。Claude Code 的默认行为是每次新会话上下文清零。它不知道你的项目用 pnpm 还是 npm不知道prisma/schema.prisma需要 DBA 审批不知道测试文件必须放在tests/下。你不在对话里说它就按通用最佳实践来——而通用最佳实践往往和你的项目约定冲突。CLAUDE.md 就是解决这件事的文件。一句话定义它是 Claude Code 在每次启动时自动读取并注入上下文的项目级说明书。注意“自动注入”这四个字——你写进去的内容不需要在对话里重复它会成为模型理解你项目的前置知识。它和 README 的区别值得说清楚。README 是给人看的看不看随意CLAUDE.md 是给模型看的每次会话强制加载。你可以把 README 理解成公司官网把 CLAUDE.md 理解成新员工入职手册——不读不让上岗。适合谁已经装好 Claude Code、正在多仓库或团队协作环境里使用、希望把“项目规范”从口头约定变成可执行约束的开发者。如果你只是偶尔跑个脚本这个文件的价值有限但只要你每天都要和同一个代码库打交道它就是投入产出比最高的一个配置文件。这篇会拆三件事CLAUDE.md 的层级加载与优先级、一份可以直接复制的模板、以及修改后如何重启会话验证加载顺序真的生效。最后附上我踩过的几个坑和对应报错。2. CLAUDE.md 层级加载机制与优先级详解理解加载机制比背模板重要得多。因为一旦你搞不清“哪份文件在什么时候生效”就会出现“我明明写了规则它却不遵守”的困惑。Claude Code 的 CLAUDE.md 是分层加载的从宽到窄大致是四层第一层是全局用户级路径在~/.claude/CLAUDE.md。这一层对所有项目生效适合放你个人的通用偏好比如“回答用中文”“提交信息用 Conventional Commits”“不要自动执行 git push”。它不随项目走换仓库依然生效。第二层是项目根级路径就是仓库根目录的./CLAUDE.md。这是团队共享的主战场应该提交到 Git。项目约定、构建命令、安全红线都放这里。第三层是本地项目级路径./CLAUDE.local.md。这一层是给你个人的比如你本地的调试端口、你私人的快捷命令。它通常会被自动加入.gitignore不会污染团队仓库。第四层是子目录级。在 monorepo 里apps/frontend/CLAUDE.md和apps/backend/CLAUDE.md会在你操作对应目录时按需加载。这一层是“就近生效”的关键。优先级怎么理解越靠近当前工作目录的规则越具体越应该覆盖上层。全局层说“用中文回答”项目层说“代码注释用英文”那在写注释这件事上以项目层为准。子目录层再进一步细化比如前端目录要求“组件用函数式写法”后端目录要求“service 层不直接返回 prisma 对象”。这里有个容易踩的坑很多人以为子目录的 CLAUDE.md 会无条件全部加载。实际上它是按需的——你在仓库根目录跑一个全局搜索前端子目录的规则未必进入上下文。所以不要把关键安全规则只写在子目录里核心红线要放在项目根级。另一个坑是命名。CLAUDE.md必须全大写claude.md在部分系统上不会被识别。CLAUDE.local.md同理。我见过有人写成Claude.md然后困惑为什么规则不生效。还有一个进阶机制.claude/rules/目录。有些规则不需要每次加载比如部署流程、API 设计规范。你可以把它们拆成testing.md、deployment.md、api-design.md放进.claude/rules/让 Claude Code 根据当前任务判断是否加载。这样主 CLAUDE.md 能保持精简特定场景的规则按需注入。关于长度社区有个共识控制在 200 行以内Anthropic 官方工程师甚至把自己的控制在 100 行以内。原因很直接——CLAUDE.md 是注入到上下文里的太长会稀释重要规则的权重模型反而会忽略关键约束。判断某一行该不该留用这个黄金法则删掉这一行Claude 会犯错吗如果不会就删掉。3. 可复制的 CLAUDE.md 模板与目录结构这一节给你可以直接落地的配置。先看目录结构再看文件内容。一个中等规模 Node.js 项目的推荐结构my-project/ ├── CLAUDE.md # 团队共享提交 Git ├── CLAUDE.local.md # 个人配置加入 .gitignore ├── .claude/ │ └── rules/ │ ├── testing.md # 写测试时按需加载 │ ├── deployment.md # 部署时按需加载 │ └── api-design.md # 设计 API 时按需加载 ├── apps/ │ ├── frontend/ │ │ └── CLAUDE.md # 前端特定规范 │ └── backend/ │ └── CLAUDE.md # 后端特定规范 └── packages/ └── shared/ └── CLAUDE.md # 共享包规范根目录CLAUDE.md的内容可以直接参考下面这份# 项目说明 Express Prisma PostgreSQL 后端 API 服务。 测试用 Jest包管理用 pnpmNode 版本 20。 # 常用命令 - 启动开发: pnpm dev - 运行测试: pnpm test - 数据库迁移: pnpm prisma migrate dev - 构建: pnpm build - 类型检查: pnpm tsc --noEmit # 代码规范 - 使用 TypeScript strict 模式 - 异步函数必须用 async/await不要用 .then() - 错误处理用自定义 AppError 类不要 throw 原始 Error - 数据库操作只在 service 层controller 层不直接调用 prisma # 安全规则 - 不要修改 prisma/schema.prisma结构变更需 DBA 审批 - 不要动 .env 文件 - 不要修改 migration 文件 - 不要执行 git push # 文件放置 - 新 API 路由: src/routes/ - 新 Service: src/services/ - 新 Middleware: src/middleware/ - 测试文件: tests/ 目录下文件名 *.test.ts大概 40 行覆盖了最关键的信息。注意它没有写“编写整洁的代码”“添加必要注释”这类不言自明的话——那些是噪音。如果你用 Claude Code 的第三方 API 接入方式配置里需要写全三件套Base URL、Key、Model ID。以 TaoToken 为例Base URL 填https://taotoken.net/apiKey 在控制台生成Model ID 按你选的模型填。这三项缺一不可只填 Base URL 不填 Model ID 是最常见的配置错误。CLAUDE.local.md可以放你个人的东西# 个人配置 - 本地调试端口: 3001 - 我的测试数据库: postgres://localhost:5432/dev_local - 回答尽量简短代码优先.claude/rules/testing.md示例# 测试规范 - 每个 service 方法至少一个单测 - 用 describe/it 结构不要用 test() - mock 统一放在 tests/__mocks__/ - 覆盖率低于 80% 不允许合并这样拆分之后主文件保持精简测试相关的细节只在写测试时注入。4. 修改后重启会话验证加载顺序与命中规则写完文件不代表生效。Claude Code 是在会话启动时读取 CLAUDE.md 的所以修改之后必须重启会话才能验证。这一节给你一套可操作的验证流程。第一步确认文件被识别。在项目根目录启动 Claude Code然后直接问它你现在加载了哪些 CLAUDE.md 文件请列出路径。如果配置正确它会列出全局层、项目根级以及你当前所在目录对应的子目录层。如果它说“没有加载任何 CLAUDE.md”那大概率是文件名大小写问题或者你不在项目根目录启动。第二步验证规则命中。在 CLAUDE.md 里写一条容易验证的规则比如“所有回答末尾加上 [RULES-OK]”。重启会话后随便问一个问题看它是否遵守。遵守说明注入成功不遵守说明文件没被读到。第三步验证层级优先级。在全局~/.claude/CLAUDE.md写“回答用英文”在项目./CLAUDE.md写“回答用中文”。重启后提问如果它用中文回答说明项目层覆盖了全局层优先级符合预期。第四步验证子目录按需加载。进入apps/frontend/目录再启动会话问它加载了哪些文件应该能看到前端子目录的 CLAUDE.md。回到根目录再问一次它就不应该再列出前端那份。第五步验证.claude/rules/的按需机制。这个稍微间接一点让 Claude 帮你写一个测试观察它是否引用了testing.md里的规范比如 describe/it 结构。如果引用了说明按需加载生效。一个实测细节Claude Code 对 CLAUDE.md 的读取发生在会话初始化阶段会话中途修改文件不会热更新。你必须退出当前会话重新进入。我试过在会话里改完文件直接追问它依然按旧规则回答重启后才生效。如果你用的是带配置文件的接入方式比如settings.json或auth.json修改这些文件同样需要重启。以 Codex 的auth.json为例里面存的是认证信息改完不重启不会重新读取。验证通过之后建议把“CLAUDE.md 是否被正确加载”做成一个团队 checklist新人入职第一件事就是跑一遍上面的验证流程。这样能避免“以为配了其实没生效”的隐性故障。5. 常见报错与排查401、local proxy failed、reading choices这一节对照真实会遇到的报错逐个给排查方向。401 Unauthorized。这个最常见出现在 API 接入场景。原因通常是 Key 没填、填错、或者过期。排查顺序先确认 Key 是否完整复制不要带空格再确认 Base URL 是否正确。如果你用的是 TaoTokenBase URL 应该是https://taotoken.net/apiKey 在控制台的 API Keys 页面生成。注意 Base URL 和 Key 必须配套用 A 平台的 Key 配 B 平台的 URL 一定 401。local proxy failed。这个报错通常和网络配置有关。先检查你的环境变量里有没有残留的代理设置比如HTTP_PROXY、HTTPS_PROXY。如果有且指向一个已经失效的地址请求就会失败。清掉这些变量再试。另外确认你的 Base URL 没有多写或少写路径/api后面不要再跟/v1之类的后缀除非文档明确要求。Error reading choices / reading choices 相关报错。这类报错一般出现在响应解析阶段说明请求发出去了、也收到了响应但响应格式不符合预期。常见原因是 Model ID 填错——比如填了一个该端点不支持的模型名返回的结构就不是标准的 choices 数组。排查方法确认 Model ID 拼写确认该模型在你使用的端点上可用。三件套Base URL Key Model ID里Model ID 是最容易被忽略的一项。OAuth 相关报错。如果你用的是需要 OAuth 的接入方式报错通常和 token 过期或回调地址不匹配有关。检查你的auth.json或对应配置文件里的 token 是否还有效回调地址是否和平台配置一致。改完记得重启会话。规则不生效但没有任何报错。这是最隐蔽的一类。没有报错但 Claude 就是不遵守你写的规则。排查方向文件名大小写、文件位置、是否重启了会话、规则是否被更上层的配置覆盖。用第 4 节的验证流程逐项排除。CLAUDE.md 太长导致规则被忽略。这个不会报错但表现是“部分规则生效、部分不生效”。如果你写了 500 行模型很可能只记住了前 100 行。解决办法是拆分把场景化的规则移到.claude/rules/下按需加载。一个通用排查原则先确认配置三件套齐全再确认文件被加载最后确认规则优先级。90% 的问题出在前两步。6. 把 CLAUDE.md 变成团队资产接入与长期维护CLAUDE.md 真正的价值不在个人使用而在团队协作。当它提交到 Git 之后它就从“某个人的提示词”变成了“团队的可执行规范”。新人 clone 仓库启动 Claude Code自动继承所有约定不需要口头交接。维护上建议遵循几条实践。第一把 CLAUDE.md 纳入 code review。规则变更和代码变更一样需要 review避免有人随手加一条“不要写测试”这种破坏性规则。第二定期清理。每季度过一遍删掉已经过时或不再需要的条目保持精简。第三安全红线单独成段放在文件靠前的位置因为靠前的内容权重更高。如果你还没配置好接入环境需要先在控制台生成 API Key然后参考接入文档把 Base URL、Key、Model ID 三件套填进对应配置文件。配置完成后重启会话用第 4 节的流程验证加载。对于长期做编码和 Agent 任务的团队可以考虑用 Coding Plan 来管理额度避免频繁切换 Key。验证模型是否可用时可以直接在模型对话页面测试确认响应正常再写进配置。最后说一个我自己的习惯每次项目架构发生重大变化时第一件事不是改代码而是先更新 CLAUDE.md。因为如果模型不知道新架构它后续生成的代码会持续偏离你的预期。把 CLAUDE.md 当成项目的一部分来维护而不是一次性配置它才能真正成为那个“每次启动都懂你”的文件。