CLAUDE.md 配置与最佳实践：为 Claude Code 设定专属上下文

AI 开发方法论 , , , ,

CLAUDE.md 配置与最佳实践：为 Claude Code 设定专属上下文

简介

CLAUDE.md 是 Claude Code 在项目根目录读取的上下文配置文件。当 Claude Code 在项目中工作时，会自动读取这个文件，了解项目结构、代码规范、开发流程和约束条件。一个好的 CLAUDE.md 可以让 Claude Code 生成的代码风格一致、符合项目约定、减少人工修正。

本文覆盖 CLAUDE.md 的完整配置能力，包括指令语法、模块化组合策略、多工具协同（OpenSpec / Skills / Rules），以及从简单到高级的实战模板。

前置要求

  • 已安装并配置好 Claude Code（参考 fnos 中的 Claude-Code-安装教程.md）。
  • 有一个使用 Git 管理的项目仓库。
  • 了解基本的 Markdown 语法。
  • 建议先阅读 OpenSpec 基础教程（2026-06-06-OpenSpec-基础概念与-OPSX-工作流.md），了解规范驱动开发的整体理念。

详细步骤

1. CLAUDE.md 的位置与加载机制

CLAUDE.md 位于项目根目录：

1
2
3
4
5
6
my-project/
├── CLAUDE.md           ← Claude Code 启动时自动读取
├── .gitignore
├── src/
├── tests/
└── package.json

加载顺序（优先级从高到低）：

层级 路径 作用
项目级 项目根目录/CLAUDE.md 当前项目的上下文配置
全局级 ~/.claude/CLAUDE.md 所有项目的全局默认配置
内置 Claude Code 自身知识 不需要配置的通用能力

两个文件会合并，项目级配置会覆盖全局级中的同名字段。项目根目录的 CLAUDE.md 优先于全局目录中的。

2. 基本语法与结构

CLAUDE.md 使用 Markdown 格式，Claude Code 通过章节标题理解配置意图。推荐的结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# CLAUDE.md

## 项目简介
简短描述项目是什么、主要技术栈。

## 代码规范
- 代码风格、命名规则、文件组织方式
- 测试要求与覆盖率标准

## 开发流程
- 新功能开发的步骤
- 提交信息的格式规范
- 分支策略

## 约束条件
- 不要修改的文件或目录
- 需要谨慎操作的部分
- 依赖管理规则

3. 核心配置模块详解

3.1 项目简介

这是最重要的部分——让 Claude Code 第一次进入项目就理解大体结构：

1
2
3
4
5
6
7
8
9
10
11
# CLAUDE.md

## 项目简介

基于 Express + Prisma + PostgreSQL 的电商后台管理系统。
- 前端: React 18 + TypeScript + Tailwind CSS
- 后端: Express + Prisma ORM
- 数据库: PostgreSQL
- 测试: Vitest (前端) + Jest (后端)
- 包管理: pnpm
- 运行时: Node.js 20+

3.2 代码规范

定义代码风格和命名规则，减少格式化噪音：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
## 代码规范

### 命名规则
- 组件: PascalCase (UserCard, OrderTable)
- 函数/变量: camelCase (fetchUserData, isLoading)
- 常量: UPPER_SNAKE_CASE (MAX_RETRY_COUNT)
- 文件: kebab-case (user-card.tsx, order-service.ts)
- 数据库字段: snake_case (created_at, user_id)

### 目录结构
- src/components/ — UI 组件
- src/pages/ — 页面组件
- src/api/ — API 调用
- src/hooks/ — 自定义 hooks
- src/lib/ — 工具函数
- tests/ — 测试文件

### 导入顺序
1. 外部依赖 (react, express)
2. 内部模块 (@/components, @/lib)
3. 类型定义 (types)
4. 样式文件 (.css, .module.css)

3.3 开发流程

引导 Claude Code 按照团队的开发流程工作：

1
2
3
4
5
6
7
8
9
10
11
12
13
## 开发流程

1. 先阅读现有代码理解架构，不要重写已经存在的功能
2. 新功能使用 OpenSpec 流程: propose → explore → apply → archive
3. 写代码之前先写测试，遵循测试驱动开发
4. 每次修改后运行相关测试: pnpm test -- --related
5. 保持提交粒度适中，一个功能点一个提交

### 提交信息格式
<type>: <简短描述>

类型: feat / fix / refactor / test / docs / chore
示例: feat: add user login API

3.4 约束条件

这是防止 AI 越界的关键部分：

1
2
3
4
5
6
7
8
## 约束条件

- 【禁止】修改 node_modules/、dist/、.next/ 等生成目录
- 【禁止】修改数据库迁移文件（由 DBA 统一管理）
- 【谨慎】修改 package.json 中的依赖版本需要说明理由
- 【谨慎】修改公共类型定义（src/types/）需先沟通
- 【必须】所有 API 新增端点需要补充对应的类型定义
- 【必须】修改环境变量配置需要更新 .env.example

4. 完整的中级配置模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
# CLAUDE.md

## 项目简介

前后端分离的电商后台管理系统。

**技术栈：**
- 前端: React 18 + TypeScript + Tailwind CSS + TanStack Query
- 后端: Express.js + Prisma ORM + Zod 验证
- 数据库: PostgreSQL 15
- 测试: Vitest + Playwright
- CI/CD: GitHub Actions

## 代码规范

1. TypeScript 严格模式，避免使用 any
2. 组件文件使用默认导出，工具函数使用具名导出
3. 所有 API 响应都要包装在统一格式中: { code, data, message }
4. 错误优先使用自定义业务异常，不要直接 throw Error
5. 函数长度控制在 50 行以内，超过则拆分

## 开发流程

1. 新功能: OpenSpec 规范驱动 (/opsx:propose → explore → apply → archive)
2. 小修复: 直接在对话中描述需求
3. 紧急修复: 直接改代码，但事后补充测试
4. 每次提交前运行: pnpm run check (lint + type-check + test)

## 测试要求

- 新增工具函数必须写单元测试
- API 端点必须有集成测试覆盖正常和异常路径
- 组件测试覆盖主要交互路径
- 测试不 mocking 过多层，优先集成测试

## 约束条件

- 不要修改 .github/ 下的 CI 配置文件
- 不要手动编辑 prisma/schema.prisma（使用 prisma migrate）
- 所有环境变量必须从 process.env 读取，无硬编码
- 敏感信息（密码、token）不得写入代码或日志

5. 模块化组合策略

当配置变得太庞大时，可以用 .claude/instructions/ 目录拆分：

1
2
3
4
5
6
7
8
my-project/
├── CLAUDE.md              ← 主文件（项目概览 + 核心约束）
├── .claude/
│   └── instructions/
│       ├── coding-style.md    ← 代码规范细则
│       ├── test-requirements.md  ← 测试要求
│       ├── git-workflow.md    ← Git 分支/提交规范
│       └── security-rules.md  ← 安全编码规则

CLAUDE.md 中引用子文件：

1
2
3
4
5
6
7
8
9
10
11
## 代码规范

详见 `.claude/instructions/coding-style.md`。

## 开发流程

详见 `.claude/instructions/git-workflow.md`。

## 约束条件

详见 `.claude/instructions/security-rules.md`。

6. 与 Claude Code Skills 配合

CLAUDE.md 描述”当前项目是什么”，Skills 描述”我可以怎么做”。两者互补：

能力 CLAUDE.md Skills
作用范围 单个项目 全局可复用
关注点 项目上下文 执行能力
存储位置 项目根目录 ~/.claude/skills/
加载方式 自动 手动 /skill 调用
内容类型 规范 + 约束 模板 + 流程

组合示例：

1
2
3
4
5
6
# CLAUDE.md

## 开发流程
- 使用 /skill review 对代码进行审查
- 使用 /skill write-test 为新功能补充测试
- 提交前运行: pnpm run check

7. 与 OpenSpec 配合

CLAUDE.md 中声明 OpenSpec 工作流，让每次对话都遵循规范驱动开发：

1
2
3
4
5
6
7
## 开发流程

本项目使用 OpenSpec 规范驱动开发：
1. 新功能: /opsx:propose → 审核 → /opsx:explore → 审核 → /opsx:apply
2. 小修复: 直接在对话中描述，跳过 propose
3. 紧急修复: 直接 apply，事后 /opsx:archive 补流程
4. 已归档的 spec 可在 openspec/archive/ 查阅

8. 最佳实践清单

✅ 推荐的写法：

  • 用明确的章节标题分组，Claude Code 依赖 Markdown 标题来定位
  • 约束条件用「【禁止】/【必须】/【谨慎】」标记严重程度
  • 给出具体的代码示例说明想要的风格
  • 测试命令写清楚，让 AI 自动验证
  • 定期更新，与技术栈变化同步

❌ 避免的写法：

  • 不要写矛盾规则（如”用 React”又在另一处说”用 Vue”）
  • 不要写过于宽泛的要求（”写出高质量的代码”无实际意义）
  • 不要写项目无关的内容（CLA status、LICENSE 信息）
  • 不要把环境变量或密钥写入 CLAUDE.md

9. 调试 CLAUDE.md

如果 Claude Code 没有按预期读取配置，按以下顺序排查：

1
2
3
4
5
6
7
8
9
10
11
# 检查文件是否存在
ls -la CLAUDE.md

# 检查文件编码（必须是 UTF-8）
file CLAUDE.md

# 检查文件名大小写（必须是 CLAUDE.md，不是 claude.md）
echo "CLAUDE.md" | grep -E '^CLAUDE\\.md$'

# 检查是否有语法格式问题
# 在对话中提问："请告诉我你从 CLAUDE.md 读取了哪些配置"

代码示例

一个最小可用的 CLAUDE.md

适合个人项目或快速原型：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# CLAUDE.md

## 项目
TypeScript + Bun 的 CLI 工具。

## 规范
- Bun 运行时，不使用 Node.js
- 使用 Bun 内置测试框架 (bun test)
- 文件命名: kebab-case

## 流程
1. 先阅读现有 src/ 下的文件了解风格
2. 新命令在 src/commands/ 下创建
3. 运行 bun test 验证
4. 运行 bun run src/index.ts 端到端测试

多文件模块化示例

CLAUDE.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# CLAUDE.md

## 项目
Express + Prisma + React 全栈电商平台。

## 模块引用
请参考 .claude/instructions/ 下的文件获取完整规范：
- coding-style.md — 代码风格细则
- test-requirements.md — 测试要求
- security.md — 安全编码规则

## 约束条件
- 【禁止】修改 node_modules/、dist/、.next/
- 【必须】每个 API 端点添加输入验证

.claude/instructions/coding-style.md：

1
2
3
4
5
6
7
8
9
10
# 代码规范

## 命名
- 组件: PascalCase (UserProfile)
- 函数: camelCase (getUserData)
- 常量: UPPER_SNAKE_CASE (API_BASE_URL)

## 文件组织
- 每个组件一个文件
- 同目录下不超过 10 个文件，超出则创建子目录

常见问题

1. CLAUDE.md 和 .claude/instructions/ 中的配置冲突了怎么办？

.claude/instructions/ 中的文件会在 CLAUDE.md 之后被加载。如果两者定义了矛盾的规则，以 .claude/instructions/ 中的为准。建议在 CLAUDE.md 中写不可变的核心约束，在 instructions 中写可变的流程规范。

2. 全局 CLAUDE.md 和项目 CLAUDE.md 的关系？

项目级 CLAUDE.md 覆盖全局级 (~/.claude/CLAUDE.md) 的同名字段。推荐在全局级中写个人通用规范（如提交信息格式），在项目级中写项目特定信息（如技术栈、目录结构）。

3. 配置太多导致 Claude Code 上下文被挤占怎么办？

使用模块化组合策略，只把最核心的约束放在 CLAUDE.md 中，细则拆分到 .claude/instructions/ 子文件。Claude Code 会在需要时按需读取子文件。

4. 如何让 CLAUDE.md 对 Codex 或 OpenCode 也生效？

这些工具各有自己的配置文件命名：

工具 配置文件 等效能力
Claude Code CLAUDE.md
Codex CLI CODEX.md (或 .codex/) 类似 CLAUDE.md
OpenCode 无标准格式 需通过对话描述
Hermes Agent 系统提示词 在配置中定义

如果想统一管理，可以用脚本维护一套跨工具的配置模板。

5. CLAUDE.md 中能否使用环境变量或动态内容？

不能。CLAUDE.md 是纯静态 Markdown 文件，不支持变量插值或模板渲染。如果需要在不同环境使用不同配置，应在 .claude/instructions/ 中按需切换。

6. 项目中有多个前端（React + Vue）怎么办？

在 CLAUDE.md 中用条件判断风格的文字说明：

1
2
3
4
5
6
7
## 项目结构
- web/react-app/ — React 应用（主前端）
- web/admin-vue/ — Vue 管理后台

## 代码规范
- 在 react-app/ 下工作时：使用 React + JSX
- 在 admin-vue/ 下工作时：使用 Vue 3 + Composition API

7. CLAUDE.md 修改后需要重启 Claude Code 吗？

不需要。CLAUDE.md 在每次加载项目时被读取。如果 Claude Code 已经在工作，可以通过对话告诉他文件已更新，或者输入 /reload 重新读取配置。

8. 不小心把敏感信息写入了 CLAUDE.md 并提交了？

立即处理：

1
2
3
4
5
6
7
# 从 Git 历史中彻底删除（谨慎！会重写历史）
git filter-branch --force --index-filter \
  'git rm --cached --ignore-unmatch CLAUDE.md' \
  --prune-empty -- --all

# 修改文件内容后强制推送
git push --force --all

同时轮换被泄露的密钥/Token。

小结

CLAUDE.md 是 Claude Code 用户最值得花时间配置的文件。一个精心编写的 CLAUDE.md 能显著提升 AI 生成代码的质量和一致性。核心原则：

  1. 明确约束——告诉 AI 什么不能做比告诉它能做什么更重要
  2. 提供上下文——告诉 AI 项目全貌，让它少走弯路
  3. 保持简洁——只写最有用的信息，避免淹没关键约束
  4. 定期维护——随着项目演进更新配置

CaoZHProgrammer

学习使我快乐。