10 CLAUDE.md 进阶

如果说 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 工具"变成"懂得你们项目所有规则的数字团队成员"。