07_Claude Code之CLAUDE.md与项目配置最佳实践

07 Claude Code之CLAUDE.md与项目配置最佳实践CLAUDE.md 是 Claude Code 的项目级系统提示但 90% 的人都在错误使用它——越长越全反而效果更差。本文提出精准优于全面的配置哲学详解 Litmus Test 编写法、 条件加载、.claude/rules/ 目录按需加载、imports 引用机制以及 Monorepo 多层级配置方案。附完整示例和避坑指南让你的 CLAUDE.md 真正成为项目规范的 AI 可执行版本。关键字CLAUDE.md、项目配置、上下文工程、.claude/rules、imports、条件加载、项目规范、AI指令优化标签Claude CodeCLAUDE.md项目配置上下文工程团队协作AI规范提示工程写在前面CLAUDE.md 是 Claude Code 最容易被误解的功能之一。很多人把它当成一个越长越好的文件——把能想到的项目规范、编码标准、工作流程全部塞进去。结果是每次会话都消耗大量上下文 tokenClaude 在规则堆里迷路实际效果反而变差。真正高质量的 CLAUDE.md 应该是精准的而不是全面的。这篇文章分享我摸索出来的 CLAUDE.md 配置哲学和实操技巧。一、CLAUDE.md 的本质CLAUDE.md 是项目级的系统提示扩展。它会在每次 Claude Code 会话开始时自动加载成为 Claude 理解这个项目的基础上下文。会话初始化流程 ↓ 加载 Claude Code 系统提示内置约15-20K token ↓ 发现并加载 CLAUDE.md 文件从当前目录向上查找直到 git root ↓ 加载 .claude/rules/ 目录下的规则按需或全量 ↓ 会话就绪等待用户输入加载层级多个 CLAUDE.md 可以共存在 Monorepo 中Claude 会按路径层级收集所有 CLAUDE.mdmonorepo/ -- CLAUDE.md # 仓库级规范总是加载 -- apps/ | -- frontend/ | | -- CLAUDE.md # 前端特定规范在前端目录工作时加载 | -- backend/ | -- CLAUDE.md # 后端特定规范在后端目录工作时加载 -- packages/ -- shared/ -- CLAUDE.md # 共享包规范在apps/frontend/目录下工作时Claude 会加载两层仓库根的 CLAUDE.md apps/frontend/的 CLAUDE.md后者内容优先。这个机制非常有用把团队通用规范放在根级把技术栈特定规范放在子目录。二、CLAUDE.md 内容设计原则原则一Litmus Test石蕊测试对 CLAUDE.md 的每一行问自己“没有这行Claude 会犯具体的错误吗”# 删掉这行会发生什么 使用 TypeScript 编写代码 → Claude 可能默认用 JavaScript有价值 ✓ 代码要清晰可读 → Claude 本来就会写清晰代码没有价值 ✗ 所有错误处理必须记录到 logger不能用 console.log → 不写Claude 可能用 console.log有价值 ✓ 请保持代码的高质量 → 废话删除 ✗原则二60-200 行是健康区间少于 60 行可能缺少关键约定Claude 会做错误假设60-200 行黄金区间足够指引但不占用过多上下文超过 200 行应该考虑拆分到.claude/rules/目录原则三写约束不写教程CLAUDE.md 告诉 Claude “不能做什么和必须做什么”而不是教它如何完成任务# 不好教程式Claude 早就知道这些 API端点应该处理错误并返回适当的HTTP状态码。 使用404表示资源不存在400表示请求无效500表示服务器错误。 # 好约束式告诉 Claude 项目特定规范 所有API错误必须使用 ErrorResponse 结构体不能直接返回字符串。 错误代码使用项目定义的 ErrorCode 枚举参见 pkg/errors/codes.go。三、一个真实项目的 CLAUDE.md 示例这是我在一个 Go React 全栈项目中使用的 CLAUDE.md经过多次精简优化# 项目用户行为分析平台 ## 技术栈 - 后端Go 1.21使用 Gin 框架gorm PostgreSQL - 前端React 18 TypeScriptViteZustand 状态管理 - 部署Dockerk8s使用 GitHub Actions CI/CD ## 关键约定 ### Go 后端 - 错误处理必须使用 pkg/errors 包的 AppError不能用 errors.New 或 fmt.Errorf - 日志使用 pkg/logger 的结构化日志不能用 fmt.Println 或 log.Print - 数据库所有查询必须通过 Repository 层不能在 Handler 里直接调用 gorm - 测试表驱动测试风格mock 放在 _test.go 文件的 TestMain 中 ### React 前端 - 组件状态局部用 useState跨组件用 useStoreZustand禁止用 Redux - API 调用统一使用 src/api/ 目录下的 API 客户端不能直接 fetch - 样式Tailwind CSS only不能写内联 style不能新建 CSS 文件 ### 通用规范 - 所有公共 API 函数必须有 JSDoc/GoDoc 注释 - 禁止提交 .env 文件使用 .env.example 作为模板 - 分支命名feat/, fix/, chore/ 前缀 ## 常用命令 - 启动开发make dev - 运行测试make test - 数据库迁移make migrate-up - 生成 API 文档make docs总计约 55 行Claude 能从这里获得所有项目特定的关键约束。四、.claude/rules/ 目录按需加载的规则当 CLAUDE.md 开始臃肿时把细分规则迁移到.claude/rules/目录.claude/rules/ -- typescript.md # TypeScript 特定规范 -- testing.md # 测试规范 -- database.md # 数据库使用规范 -- security.md # 安全规范 -- api-design.md # API 设计规范条件加载只在处理相关文件时加载--- paths: - **/*.ts - **/*.tsx --- # TypeScript 规范 - 优先使用 interface 而不是 type除非需要联合类型 - 不允许 any 类型使用 unknown 类型守卫 - 所有 Promise 必须有错误处理.catch() 或 try/catch - 使用 satisfies 运算符代替 as 类型断言当 Claude 处理.ts或.tsx文件时这条规则自动加载处理.go文件时不加载节省上下文。五、imports 引用机制CLAUDE.md 支持用语法引用其他文件实现动态内容注入# 项目规范 ## API 文档 请参考以下 API 设计规范 docs/api-design-guide.md ## Git 工作流 docs/git-workflow.md ## 当前架构 ARCHITECTURE.md被引用的文件在会话中按需加载不写在 CLAUDE.md 里就不占用上下文。# 常用的 imports 模式 # 引用 README让 Claude 了解项目背景 README.md # 引用包依赖让 Claude 知道可用的库 package.json # 引用全局个人配置 ~/.claude/personal-preferences.md六、Monorepo 的 CLAUDE.md 架构Monorepo 是 CLAUDE.md 层级系统最能发挥价值的场景monorepo/CLAUDE.md约50行 - 通用代码规范 - 跨包的接口约定 - CI/CD 流程 apps/frontend/CLAUDE.md约40行 - React/TypeScript 特定规范 - 组件库使用规范 - 测试框架Vitest Testing Library apps/backend/CLAUDE.md约40行 - Go 编码规范 - 内部包使用约定 - 数据库访问模式每个子目录的 Claude 只加载仓库级 当前目录级不会加载其他子目录的规范。精准、高效。七、CLAUDE.md 质量检查清单定期对 CLAUDE.md 做一次审查用这个清单[ ] 每一行都能回答没有这行会出错吗Litmus Test [ ] 总行数在 200 行以内 [ ] 没有解释 Claude 已经知道的通用最佳实践 [ ] 有明确的技术栈声明语言版本、框架版本 [ ] 有项目特定的约束非通用规范 [ ] 有常用命令不需要 Claude 自己去猜 [ ] 细分规范已迁移到 .claude/rules/ 目录 [ ] 被 imports 引用的文件都存在总结CLAUDE.md 的最高境界是任何新加入项目的开发者打开 Claude Code说跑一下测试它就能正确运行——不需要额外解释因为 CLAUDE.md 已经提供了所有必要的上下文。记住三个关键原则Litmus Test每行都能防止 Claude 犯具体错误精简优于全面60-200 行是健康区间按需分层细分规范用.claude/rules/条件加载