如果说 CLAUDE.md 是 Claude Code 的"系统提示词",那么多层配置架构就是这套系统的"继承体系"。掌握它,你就能精确控制 AI 在不同项目、不同目录、甚至不同子模块中的行为。

本节目标

  1. 理解 CLAUDE.md 的多层配置架构及加载优先级

  2. 掌握 .claude/rules/*.md 的路径作用域规则配置

  3. 学会使用 @import 语法构建模块化配置文件

  4. 理解 monorepo 场景下的配置继承机制

  5. 建立"CLAUDE.md 即团队资产"的管理理念

核心知识点

多层配置架构

Claude Code v2.1.x 的配置系统采用层叠继承模型,类似 CSS 的 cascading 机制。每一层可以覆盖或补充上一层的规则:

层级 1: ~/.claude/CLAUDE.md          ← 全局个人配置(机器级)
层级 2: ./CLAUDE.md                  ← 项目根配置(仓库级)
层级 3: ./CLAUDE.local.md            ← 本地覆盖(不入版本控制)
层级 4: .claude/rules/*.md           ← 路径作用域规则(精准控制)
层级 5: 子目录 ./subdir/CLAUDE.md    ← monorepo 子项目配置

合并机制:

  • 层级 1 始终最先加载(全局底线)

  • 层级 2-N 依次叠加,后加载的追加而非替换

  • 冲突策略:更具体的配置(目录更深的)优先级更高

  • CLAUDE.local.md 会追加到 CLAUDE.md 之后,而不是替换

各层级的使用场景

~/.claude/CLAUDE.md (个人全局配置)

放入跨项目通用的个人偏好:

# 个人全局配置
​
## 语言偏好
- 请始终使用中文回复我
- 代码注释使用中文,但代码本身(变量名、函数名)使用英文
​
## 编辑偏好
- 修改前先确认,不要自动覆盖我的文件
- 每次修改不超过 3 个文件,改完一批等我确认再继续
​
## 工具偏好
- 优先使用 gh CLI 操作 GitHub,不要用 API
- npm 操作请加 --legacy-peer-deps

./CLAUDE.md (项目级,入版本控制)

放入项目特定的技术约束、架构约定和编码规范:

# MyProject CLAUDE.md
​
## 技术栈
- 前端: React 18 + TypeScript 5 + Vite
- 状态管理: Zustand (不要引入 Redux)
- 样式: Tailwind CSS + CSS Modules
- 测试: Vitest + React Testing Library
​
## 架构约定
- 组件放在 src/components/<ComponentName>/ 目录下
- 每个组件目录包含: index.tsx, styles.module.css, types.ts, __tests__/
- API 调用统一通过 src/api/client.ts 的封装,不要直接使用 fetch/axios
- 错误处理使用 src/lib/errors.ts 中定义的 AppError 类
​
## 禁止事项
- 禁止使用 any 类型
- 禁止在组件中使用内联样式
- 禁止引入超过 50KB (gzipped) 的新依赖,需要先讨论
- 禁止直接操作 DOM,使用 React ref
​
## 测试要求
- 新组件必须有单元测试,覆盖率 > 80%
- 修改 API 层必须有集成测试
- 使用 MSW 模拟 API 响应

./CLAUDE.local.md (本地覆盖,不入版本控制)

放入个人开发环境的特殊配置、私密信息的使用提示(不是密码本身):

# 个人本地配置
​
## 本地环境
- 数据库连接使用 localhost:5432,用户名 postgres
- Redis 运行在默认端口 6379
- 我的 Node.js 版本是 20.11.0,请确保兼容
​
## 个人工作流
- 我喜欢先写测试再写实现
- 每完成一个功能就提一个 WIP commit,不要等到全部完成

.claude/rules/ 路径作用域规则

这是 Claude Code v2.1.x 中最强大的配置功能。你可以在 .claude/rules/ 目录下放置按路径模式生效的规则文件:

project/
├── .claude/
│   └── rules/
│       ├── all.md              # 对所有文件生效
│       ├── frontend.md         # 对 src/ 下所有文件生效
│       ├── api.md              # 对 src/app/api/ 生效
│       └── database.md         # 对 src/db/ 生效
├── src/
│   ├── app/
│   │   └── api/                ← api.md 在此作用
│   └── db/                     ← database.md 在此作用
└── CLAUDE.md

规则文件的路径映射通过文件名前的注释声明:

<!-- CLAUDE: path=src/app/api/**/*.ts -->
# API 路由开发规则
​
## 约定
- 所有 API 路由必须使用 src/lib/validate.ts 进行输入验证
- 响应格式统一使用 ApiResponse<T> 类型
- 错误处理使用 next(error) 传递,不要在路由中直接 try-catch

也可以在一个文件中使用 path 指令覆盖多个路径:

<!-- CLAUDE: path=src/components/**/* -->
<!-- CLAUDE: path=src/hooks/**/* -->
# 前端组件与 Hooks 规则
​
## 约定
- 组件使用命名导出,不要使用默认导出
- Hooks 以 use 前缀命名
- 不要在 Hook 内部调用其他 Hook 时破坏顺序规则

@import 语法:模块化配置

当 CLAUDE.md 变长后,使用 @import 拆分为多个文件:

# CLAUDE.md (主文件)
​
## 项目概述
这是一个电商后台管理系统...
​
@import .claude/config/tech-stack.md
@import .claude/config/coding-standards.md
@import .claude/config/testing.md
@import .claude/config/git-workflow.md

被导入的文件是普通的 Markdown 文件:

# coding-standards.md
​
## 命名规范
- 文件名: kebab-case (user-profile.tsx)
- 组件名: PascalCase (UserProfile)
- 函数/变量: camelCase (getUserData)
- 常量: UPPER_SNAKE_CASE (MAX_RETRY_COUNT)
​
## 格式化
- 使用项目根目录的 .prettierrc 配置
- 缩进: 2 空格
- 行宽: 100 字符

@import 规则:

  • 支持相对路径和绝对路径

  • 可以嵌套导入(但不建议超过 2 层)

  • 导入的文件按声明顺序合并

  • 推荐将大型 CLAUDE.md 拆分为 3-5 个主题文件

Monorepo 子目录继承

在 monorepo 场景中,子目录的 CLAUDE.md 会继承根目录的配置,并可以追加子项目特定规则:

monorepo/
├── CLAUDE.md                       # "所有包使用 pnpm workspace"
├── packages/
│   ├── web/
│   │   └── CLAUDE.md               # 追加: "React + Next.js 约定"
│   ├── api/
│   │   └── CLAUDE.md               # 追加: "Express + Prisma 约定"
│   └── shared/
│       └── CLAUDE.md               # 追加: "纯 TypeScript,无框架依赖"

当你在 packages/web/ 目录下启动 Claude Code 时,它会自动合并:

  1. monorepo/CLAUDE.md (根配置)

  2. monorepo/packages/web/CLAUDE.md (子项目配置)

CLAUDE.md 作为团队资产

CLAUDE.md 不是个人笔记,而是一份团队共享的开发规范文件。它应该:

  1. 进入版本控制(.local.md 除外)

  2. 通过 PR 审查流程更新:任何对 CLAUDE.md 的修改都应该经过团队 review

  3. 定期维护:每季度审查一次 CLUADE.md,删除过时规则,添加新约定

  4. 新人友好:新成员入职后,CLAUDE.md 就是他们的"AI 辅助开发手册"

推荐的 CLAUDE.md PR 流程:
1. 开发者在 feature 分支提出 CLAUDE.md 修改
2. 至少一位团队成员 review
3. 讨论焦点:这条规则是否适合所有成员?是否有例外?
4. 合并后在团队频道通知

实操步骤

步骤 1:分析当前配置层级

执行以下命令查看你当前的 CLAUDE.md 加载情况:

# 查看个人全局配置
cat ~/.claude/CLAUDE.md
​
# 查看当前项目配置
cat ./CLAUDE.md 2>/dev/null || echo "项目根目录没有 CLAUDE.md"
​
# 查看本地覆盖
cat ./CLAUDE.local.md 2>/dev/null || echo "没有本地覆盖配置"
​
# 查看路径作用域规则
ls -la .claude/rules/ 2>/dev/null || echo "没有路径规则"

步骤 2:创建项目级 CLAUDE.md

# 在项目根目录创建
touch CLAUDE.md

填入项目关键技术信息(参考上方示例)。

步骤 3:创建路径作用域规则

mkdir -p .claude/rules
​
# 为 API 路由创建规则
cat > .claude/rules/api.md << 'EOF'
<!-- CLAUDE: path=src/app/api/**/* -->
# API 路由开发规则
- 所有输入使用 Zod schema 验证
- 响应格式统一: { success: boolean, data?: T, error?: string }
- 敏感操作记录审计日志
EOF
​
# 为数据库操作创建规则
cat > .claude/rules/database.md << 'EOF'
<!-- CLAUDE: path=src/db/**/* -->
# 数据库操作规则
- 使用 Prisma 进行所有数据库操作
- 迁移文件手动审查后再执行
- 查询默认分页,limit 最大 100
EOF

步骤 4:使用 @import 模块化

mkdir -p .claude/config
​
# 拆分配置
cat > .claude/config/tech-stack.md << 'EOF'
# 技术栈
- 运行时: Node.js 20 LTS
- 框架: Next.js 14 (App Router)
- 数据库: PostgreSQL 16 + Prisma ORM
- 缓存: Redis 7
EOF
​
# 在主文件中导入
echo '@import .claude/config/tech-stack.md' >> CLAUDE.md

避坑指南

坑 1:CLAUDE.local.md 放入敏感信息

CLAUDE.local.md 虽然不上传版本控制,但它会以纯文本形式发送给 Claude API。绝对不要在其中写入:

  • API 密钥或 Token

  • 数据库密码

  • 任何形式的凭证

环境变量是管理敏感信息的唯一正确方式。

坑 2:规则冲突时的"最后加载胜利"陷阱

由于配置是逐层叠加的,后加载的同名规则会覆盖前面的。如果你在 ~/.claude/CLAUDE.md 中写了"始终使用中文",但项目 ./CLAUDE.md 中写了"代码注释使用英文",后者会生效。

建议:在项目级 CLAUDE.md 中明确声明哪些规则是有意覆盖全局配置的:

## 覆盖全局配置
以下规则覆盖我的个人全局配置:
- 本项目的代码注释使用英文(而不是中文)
- 本项目的测试框架使用 Vitest(而不是 Jest)

坑 3:路径规则未生效

路径作用域规则依赖于你在哪个目录下启动 Claude Code。如果你在 src/ 目录外编辑 src/app/api/ 下的文件,规则可能不会被触发。

验证方法:在 Claude Code 中提问:

当前会话加载了哪些配置文件?按优先级排序。

Claude Code 会列出当前生效的配置文件和规则。

坑 4:@import 循环引用

如果 a.md 导入了 b.md,而 b.md 又导入了 a.md,会导致无限循环。Claude Code 会检测并报错,但最好在设计导入结构时就避免循环。

# 推荐的单向导入结构
CLAUDE.md
├── .claude/config/tech-stack.md
├── .claude/config/coding-standards.md
│   └── .claude/config/naming.md  (子导入,但不可回导到 coding-standards.md)
└── .claude/config/testing.md

课后作业

作业 1:配置审计

  1. 列出你当前项目中所有生效的 CLAUDE 配置(全局 ~/.claude/CLAUDE.md + 项目 ./CLAUDE.md + ./CLAUDE.local.md + .claude/rules/)

  2. 标记出任何冲突或冗余的规则

  3. 提出优化方案:哪些可以合并,哪些应该拆分为路径规则

作业 2:为你的项目建立完整的 CLAUDE.md 体系

  1. 创建一个模块化的项目 CLAUDE.md(至少使用 3 个 @import 子文件)

  2. 创建至少 2 个 .claude/rules/ 路径规则(如:前端规则 + API 规则)

  3. 创建 CLAUDE.local.md 管理你的个人环境配置

  4. 在 Claude Code 中验证所有配置正确加载

作业 3:设计团队 CLAUDE.md 管理流程

为你的团队设计一份 CLAUDE.md 管理规范:

# 团队 CLAUDE.md 管理规范
​
## 修改流程
1. 
​
## 审查要求
- 最少 X 人 approve
- 
​
## 版本策略
- 重大修改需要团队讨论
-

总结

CLAUDE.md 进阶配置的核心价值在于精确控制 AI 的行为边界:

  • 多层架构让你在不同粒度上设定规则:从全局到项目,从目录到文件

  • 路径作用域规则让 AI 在数据库代码中自动遵循数据库规范,在前端代码中自动遵循组件约定

  • @import 模块化让配置文件本身也符合软件工程的"高内聚、低耦合"原则

  • 团队资产化让 CLAUDE.md 成为团队知识的外化载体,而不是个人的私密配置

善用这些机制,Claude Code 会从"一个 AI 工具"变成"懂得你们项目所有规则的数字团队成员"。

# 编辑器
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

RAG技术怎么让AI笔记工具读懂你的知识库？

avatar AtomGit开源社区

从 NVIDIA 驱动到 CUDA + cuDNN 完全配置指南（附避坑）

恭喜你！走到这一步，你的电脑已经是一台名副其实的深度学习工作站了。用 GPU 加速训练神经网络（速度提升几十到上百倍）跑 LLM（大语言模型）、Stable Diffusion（AI 绘画）等前沿项目课后作业运行一个 MNIST 手写数字识别的 PyTorch 示例，观察 GPU 使用率（在任务管理器性能选项卡查看）。尝试用nvidia-smi实时监控显存占用。有任何问题请在评论区留言，我会尽量解

avatar AtomGit开源社区
cover

【AI大模型应用开发工程师特训笔记】第04讲（第四章）：运算符

avatar AtomGit开源社区