跳到主要内容

CLAUDE.md 配置指南

概述​

CLAUDE.md 是 Claude Code 中最重要的配置文件，它是项目与 AI 之间的桥梁，帮助 Claude 理解你的项目结构、编码规范和工作流程。本指南将教你如何编写高效的 CLAUDE.md 文件。

核心原则​

1. 理解大语言模型的无状态特性​

  • 会话隔离：每次会话开始时，Claude 对你的代码库一无所知
  • 信息必须：必须通过 CLAUDE.md 提供项目背景信息
  • 默认加载：CLAUDE.md 是唯一默认进入每次对话的文件

2. 少即是多原则​

  • 指令限制：保持文件简洁，建议不超过 300 行
  • 关注重点：只包含真正必要的项目信息
  • 避免冗余：删除无关的通用指导内容

3. 渐进式信息呈现​

对于大型项目，采用渐进披露策略：

project_docs/
├── architecture.md
├── api-guidelines.md
├── testing-strategy.md
└── deployment-guide.md

在 CLAUDE.md 中引用这些文档，而不是包含所有内容。

CLAUDE.md 的核心作用​

作为项目地图​

告诉 Claude：

  • WHAT：技术栈、项目结构、目录组织
  • WHY：项目目的、各模块功能
  • HOW：工作方式、使用工具、验证方法

基本结构示例​

# 项目上下文

## 项目概述
[一句话描述项目]

## 技术栈
- 主要框架和语言
- 数据库和缓存
- 第三方服务

## 目录结构
- `src/` - 源代码
- `tests/` - 测试文件
- `docs/` - 项目文档

## 开发规范
- 编码标准
- 命名约定
- 提交规范

## 常用命令
```bash
npm run dev      # 开发服务器
npm run test     # 运行测试
npm run build    # 构建项目

注意事项​

  • 特殊的架构决策
  • 重要的业务规则

## 编写最佳实践

### 1. 提供"项目地图"

包含简洁的项目说明和清晰的目录结构，帮助 Claude 快速建立认知模型。

### 2. 说明开发环境与工具链

明确告诉 Claude：
- 使用的工具和版本
- 命令格式和关键参数
- 典型使用场景
- 测试和构建流程

### 3. 定义标准工作流

为不同类型的任务制定标准流程：
- 需要调研的任务
- 需要设计方案的任务
- 验证和测试要求

### 4. 避免常见错误

- **不要**把 Claude 当作代码检查器
- **不要**包含过多的代码风格规则
- **不要**自动生成，要精心设计
- **不要**包含项目特定外的通用信息

## 使用 /init 命令

面对不熟悉的项目，使用 `/init` 命令自动生成初始 CLAUDE.md：

```bash
cd your-project
claude
/init

/init 之后的步骤​

  1. 检查准确性：验证所有推断的信息
  2. 补充潜规则：添加团队约定和工作流
  3. 精简内容：删除不适用的通用指导
  4. 版本控制：提交到代码仓库

工具自动设置​

配置允许的工具​

在 settings.json 中配置：

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(./config/*.json)",
      "WebFetch"
    ]
  }
}

MCP 服务器配置​

{
  "enableAllProjectMcpServers": true,
  "enabledMcpServers": ["github", "filesystem"]
}

实战案例​

案例 1：微服务项目​

# 微服务项目配置

## 项目概述
基于 Spring Cloud 的微服务架构，包含 15+ 个服务。

## 核心服务
- user-service：用户管理
- order-service：订单处理
- payment-service：支付

## 技术栈
- Spring Boot 2.7 + Spring Cloud 2021
- MySQL 8.0 + Redis 6.0
- RabbitMQ 3.9

## 开发规范
- 统一异常处理
- 数据库事务管理
- 接口幂等性检查

案例 2：前端项目​

# React 前端项目

## 项目概述
React 18 + TypeScript 企业级应用。

## 技术栈
- React 18 + TypeScript
- TDesign UI
- React Query
- Zustand
- Vite

## 项目结构
- src/components/：通用组件
- src/pages/：页面组件
- src/hooks/：自定义 hooks

## 编码规范
- 函数组件 + hooks
- TypeScript 严格模式
- ESLint + Prettier

进阶技巧​

1. 保持上下文"干净"​

使用 /clear 命令重置上下文，清除历史记录但保留 CLAUDE.md。

2. 使用自定义命令​

在 .claude/commands/ 创建常用命令：

# .claude/commands/performance.md
分析性能问题并提供优化建议

3. 团队协作​

  • 将 CLAUDE.md 纳入版本控制
  • 定期审查和更新
  • 建立变更流程
  • 维护配置模板

常见问题​

Q: Claude 不遵守 CLAUDE.md 指令？​

  1. 检查指令是否过于复杂
  2. 使用更明确的语言
  3. 在对话开始时明确提及规则

Q: 文件应该多大？​

  • 保持简洁，< 300 行
  • 只包含必要信息
  • 使用引用指向详细文档

Q: 如何处理多项目？​

  • 根目录放通用配置
  • 子目录放特定配置
  • 使用继承和覆盖机制

总结​

  1. 引导而非指令：用于引导 Claude 理解项目
  2. 简洁至上：包含尽可能少的必要指令
  3. 普遍适用：保持内容简洁且适用性广
  4. 渐进披露：告诉 Claude 如何找到信息，而非所有信息
  5. 精心设计：避免自动生成，打磨每一行内容
  6. 持续优化：根据项目发展不断改进

相关资源​