Claude Code 规则配置完全指南：让 AI 助手更懂你的项目 🎯

想让 Claude Code 更好地理解你的项目？学会制定规则，让 AI 助手成为你的专属编程伙伴！

为什么需要为 Claude Code 制定规则？

你是否遇到过这样的情况：

• 🤔 Claude Code 生成的代码风格与项目不一致
• 😕 它不理解你的项目架构和约定
• 🤯 每次都要重复解释相同的项目背景

制定规则就是解决方案！ 通过配置文件，你可以：

• ✅ 统一代码风格和规范
• ✅ 定义项目架构和约定
• ✅ 预设开发流程和最佳实践
• ✅ 减少重复沟通，提高效率

规则配置文件概览

Claude Code 支持两种主要的规则配置方式：

1. CLAUDE.md - 项目上下文和规则文档（必需）
2. .claude/settings.json - 高级配置和 Hooks（可选）

让我们深入了解如何使用它们！

方法一：使用 CLAUDE.md 文件

CLAUDE.md 是 Claude Code 的核心配置文件，放在项目根目录。这个文件定义了 Claude 在处理你的项目时应该遵循的规则、约定和上下文。

创建 CLAUDE.md

在项目根目录创建 CLAUDE.md 文件：

touch CLAUDE.md
# 或
echo "# Claude Code Rules" > CLAUDE.md

CLAUDE.md 的基本结构

# 项目概述

这是一个 [项目类型] 项目，使用 [技术栈]。

## 项目架构

- 前端：React + TypeScript
- 后端：Node.js + Express
- 数据库：PostgreSQL

## 代码规范

### 命名约定
- 变量：使用 camelCase
- 常量：使用 UPPER_SNAKE_CASE
- 组件：使用 PascalCase

### 代码风格
- 使用 ESLint 和 Prettier
- 缩进：2 个空格
- 行尾分号：不使用

## 开发约定

- 所有 API 调用必须包含错误处理
- 组件必须包含 PropTypes 或 TypeScript 类型
- 提交前必须运行测试

完整的 CLAUDE.md 示例

# My Awesome Project

这是一个全栈 Web 应用，使用 React + Node.js 构建。

## 技术栈

- **前端**：React 18, TypeScript, Tailwind CSS
- **后端**：Node.js, Express, TypeScript
- **数据库**：PostgreSQL with Prisma ORM
- **测试**：Jest, React Testing Library

## 项目结构

src/
├── components/ # 可复用组件
├── pages/ # 页面组件
├── hooks/ # 自定义 Hooks
├── utils/ # 工具函数
├── api/ # API 调用
└── types/ # TypeScript 类型定义

## 代码规范

### 命名约定

- **变量和函数**：使用 `camelCase`
  ```typescript
  const userName = "John";
  function getUserData() {}

• 常量：使用 UPPER_SNAKE_CASE

  const API_BASE_URL = "https://api.example.com";
  const MAX_RETRY_COUNT = 3;
  

• 组件：使用 PascalCase

  function UserProfile() {}
  function NavigationBar() {}
  

• 文件命名：

  • 组件文件：PascalCase.tsx (如 UserProfile.tsx)
  • 工具文件：camelCase.ts (如 formatDate.ts)
  • 类型文件：camelCase.types.ts (如 user.types.ts)

代码风格

• 缩进：2 个空格
• 分号：不使用分号
• 引号：优先使用单引号，JSX 使用双引号
• 行长度：最大 100 字符
• 尾随逗号：多行结构使用尾随逗号

TypeScript 规范

• 所有函数必须有明确的返回类型
• 使用 interface 定义对象类型，type 定义联合类型
• 避免使用 any，优先使用 unknown
• 使用严格的 null 检查

// ✅ 正确示例
interface User {
  id: string;
  name: string;
  email: string;
}

function getUser(id: string): Promise<User | null> {
  // ...
}

// ❌ 错误示例
function getUser(id: any): any {
  // ...
}

React 组件规范

• 使用函数组件和 Hooks
• 组件文件必须包含：
  • 组件定义
  • PropTypes 或 TypeScript 接口
  • 导出语句

// ✅ 组件结构
interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: 'primary' | 'secondary';
}

export function Button({ label, onClick, variant = 'primary' }: ButtonProps) {
  return (
    <button className={`btn btn-${variant}`} onClick={onClick}>
      {label}
    </button>
  );
}

API 开发规范

错误处理

所有 API 调用必须包含错误处理：

async function fetchUserData(userId: string) {
  try {
    const response = await fetch(`/api/users/${userId}`);
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return await response.json();
  } catch (error) {
    console.error('Failed to fetch user data:', error);
    throw error;
  }
}

API 响应格式

所有 API 响应遵循统一格式：

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
  };
}

测试规范

• 所有公共函数必须有单元测试
• 组件必须有渲染测试
• 测试覆盖率目标：80% 以上
• 测试文件命名：*.test.ts 或 *.spec.ts

// user.test.ts
describe('getUserData', () => {
  it('should fetch user data successfully', async () => {
    // 测试实现
  });

  it('should handle errors gracefully', async () => {
    // 错误处理测试
  });
});

Git 提交规范

使用 Conventional Commits 格式：

• feat: 新功能
• fix: 修复 Bug
• docs: 文档更新
• style: 代码格式调整
• refactor: 重构
• test: 测试相关
• chore: 构建/工具相关

示例：

feat: add user authentication
fix: resolve login form validation issue
docs: update API documentation

安全规范

• 永远不要在代码中硬编码敏感信息（API keys, tokens）
• 使用环境变量存储配置
• 所有用户输入必须验证和清理
• 使用 HTTPS 进行所有 API 调用

性能优化

• 使用 React.memo 优化组件渲染
• 大列表使用虚拟滚动
• 图片使用懒加载
• API 调用使用防抖/节流

依赖管理

• 定期更新依赖包
• 使用 exact version 锁定主要依赖
• 运行 npm audit 检查安全漏洞

常见任务

添加新功能

1. 创建功能分支：git checkout -b feature/feature-name
2. 实现功能并编写测试
3. 运行测试确保通过
4. 提交代码并创建 PR

修复 Bug

1. 创建修复分支：git checkout -b fix/bug-description
2. 编写复现测试
3. 修复问题
4. 确保所有测试通过

禁止事项

• ❌ 不要提交 console.log 调试代码
• ❌ 不要使用 var，使用 let 或 const
• ❌ 不要忽略 TypeScript 错误
• ❌ 不要提交未格式化的代码
• ❌ 不要直接修改 main 分支

参考资源

• 项目 Wiki
• 设计系统文档
• API 文档

方法二：使用 .claude/settings.json

.claude/settings.json 用于配置高级功能，如 Hooks、环境变量等。

创建配置文件

mkdir -p .claude
touch .claude/settings.json

settings.json 基本结构

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/setup.sh"
          }
        ]
      }
    ],
    "BeforeEdit": [
      {
        "matcher": "*.ts",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix \"$CLAUDE_FILE\""
          }
        ]
      }
    ]
  },
  "context": {
    "maxFiles": 100,
    "excludePatterns": [
      "node_modules/**",
      ".git/**",
      "dist/**"
    ]
  }
}

常用配置示例

1. 自动安装依赖（SessionStart Hook）

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "npm install"
          }
        ]
      }
    ]
  }
}

2. 自动格式化代码（BeforeEdit Hook）

{
  "hooks": {
    "BeforeEdit": [
      {
        "matcher": "*.{js,jsx,ts,tsx}",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE\""
          }
        ]
      }
    ]
  }
}

3. 运行测试（AfterEdit Hook）

{
  "hooks": {
    "AfterEdit": [
      {
        "matcher": "*.test.{js,ts}",
        "hooks": [
          {
            "type": "command",
            "command": "npm test"
          }
        ]
      }
    ]
  }
}

4. 环境变量配置

{
  "environment": {
    "NODE_ENV": "development",
    "API_URL": "http://localhost:3000",
    "DEBUG": "true"
  }
}

引用其他文档（AGENTS.md）

如果你的项目有 AGENTS.md 文件（用于定义子代理），可以在 CLAUDE.md 中引用：

# 项目规则

@AGENTS.md

这是主要的项目规则文档。关于特定代理的配置，请参考上面的 AGENTS.md。

规则配置最佳实践

1. 保持简洁明了

✅ 正确做法：

## 代码风格
- 使用 2 空格缩进
- 不使用分号
- 使用单引号

❌ 错误做法：

## 代码风格
这是一个非常详细的代码风格指南，包含了所有可能的场景和边缘情况，虽然很全面，但可能让 Claude 感到困惑...

2. 提供具体示例

✅ 正确做法：

### 函数命名
使用动词开头：`getUserData()`, `calculateTotal()`, `validateInput()`

❌ 错误做法：

### 函数命名
函数应该有一个好的名字。

3. 使用分层结构

将规则组织成清晰的层次：

# 项目规则

## 1. 项目概述
## 2. 技术栈
## 3. 代码规范
  ### 3.1 命名约定
  ### 3.2 代码风格
  ### 3.3 最佳实践
## 4. 开发流程
## 5. 禁止事项

4. 定期更新

随着项目发展，及时更新规则：

• 添加新的技术栈
• 更新代码规范
• 记录新的最佳实践

5. 团队协作

确保团队成员都了解规则：

• 在 README 中说明 CLAUDE.md 的作用
• 在代码审查时检查规则遵循情况
• 定期回顾和更新规则

实际应用场景

场景 1：React 项目

# React 项目规则

## 组件规范
- 使用函数组件
- Props 使用 TypeScript 接口
- 使用 React.memo 优化性能

## 状态管理
- 简单状态使用 useState
- 复杂状态使用 useReducer
- 全局状态使用 Context API

## 示例
```typescript
interface UserCardProps {
  user: User;
  onEdit: (id: string) => void;
}

export const UserCard = React.memo(({ user, onEdit }: UserCardProps) => {
  return <div>{/* 组件实现 */}</div>;
});

场景 2：Node.js API 项目

# Node.js API 项目规则

## 路由规范
- 使用 RESTful API 设计
- 路由文件放在 `routes/` 目录
- 控制器逻辑放在 `controllers/` 目录

## 错误处理
- 使用统一错误处理中间件
- 错误响应格式：`{ error: { code, message } }`

## 中间件
- 认证：`authMiddleware`
- 验证：`validateMiddleware`
- 日志：`loggerMiddleware`

场景 3：Python 数据科学项目

# Python 数据科学项目规则

## 代码规范
- 遵循 PEP 8
- 使用类型提示
- 函数文档使用 docstring

## 数据处理
- 使用 pandas 处理数据
- 使用 numpy 进行数值计算
- 数据清洗函数放在 `utils/data_cleaning.py`

## 示例
```python
def clean_data(df: pd.DataFrame) -> pd.DataFrame:
    """清洗数据，移除缺失值和异常值"""
    # 实现逻辑
    return df

## 验证规则是否生效

配置完成后，测试一下：

```bash
# 启动 Claude Code
claude

# 询问项目规则
> what are the coding standards for this project?

# 让 Claude 生成代码，看是否符合规则
> create a new React component called UserProfile

如果 Claude 生成的代码符合你的规则，说明配置成功！🎉

常见问题 FAQ

Q: CLAUDE.md 文件应该放在哪里？

A: 放在项目根目录，与 package.json 或 README.md 同级。

Q: 可以同时使用 CLAUDE.md 和 settings.json 吗？

A: 可以！CLAUDE.md 定义规则和上下文，settings.json 配置行为和执行流程。

Q: 规则配置会影响性能吗？

A: 不会。规则文件只在会话开始时读取，对性能影响可忽略不计。

Q: 如何让团队共享规则？

A: 将 CLAUDE.md 和 .claude/settings.json 提交到版本控制系统（Git），团队成员会自动共享。

Q: 可以针对不同环境设置不同规则吗？

A: 可以。在 settings.json 中使用环境变量，或创建多个配置文件和条件逻辑。

Q: 规则太多会让 Claude 困惑吗？

A: 不会，但建议保持简洁和结构化。过于冗长的规则可能影响效率。

总结

为 Claude Code 制定规则是提高开发效率的关键：

1. ✅ 创建 CLAUDE.md - 定义项目规则和上下文
2. ✅ 配置 settings.json - 设置高级功能和 Hooks
3. ✅ 提供具体示例 - 帮助 Claude 更好理解
4. ✅ 保持更新 - 随着项目发展更新规则
5. ✅ 团队共享 - 确保所有成员使用相同规则

下一步

• 📝 为你的项目创建 CLAUDE.md 文件
• ⚙️ 配置 .claude/settings.json 自动化任务
• 🧪 测试规则是否生效
• 📚 查看 官方文档 了解更多配置选项
• 💬 在社区分享你的规则配置经验

---

开始制定你的专属规则吧！ 🚀

让 Claude Code 更懂你的项目，让开发效率翻倍提升！

如果这篇文章对你有帮助，别忘了点赞和分享！有规则配置相关的问题，欢迎在评论区讨论。