1. 引言

Claude Code 作为一款强大的 AI 编程助手，其核心魅力在于高度的可定制性。然而，很多用户在深入使用时，会被 CLAUDE.md、Rules、Skills、Hooks 这几个概念搞得一头雾水。它们之间到底有什么区别？什么时候该用哪个？如何组合才能发挥最大威力？

本文将带你彻底理清这四者的分工与协作关系，并通过大量实战代码示例，让你看完就能上手，告别“乱用”时代。

2. 核心概念速览：一张表看懂分工

在深入代码之前，我们先通过一个表格快速建立全局认知。

概念	作用域	核心用途	触发时机	类比
CLAUDE.md	项目级	定义项目背景、技术栈、编码规范、全局约束	每次对话开始时自动注入	项目“宪法”
Rules	全局/项目级	定义通用或特定的行为规则、安全边界	每次对话开始时自动注入	行为“守则”
Skills	全局	定义可复用的能力、工具、工作流	通过 @skill 显式调用	可插拔的“工具箱”
Hooks	项目级	在特定生命周期（如文件读写、命令执行）前后执行自定义脚本	事件触发	自动化“哨兵”

3. CLAUDE.md：项目的“宪法”

CLAUDE.md 是 Claude Code 的项目级配置文件，通常放在项目根目录。它定义了 AI 助手在这个特定项目中应该如何表现。

3.1 核心职责

• 项目背景：描述项目是做什么的，目标用户是谁。
• 技术栈声明：明确使用的语言、框架、数据库、第三方服务。
• 编码规范：命名风格、代码结构、注释要求。
• 全局约束：禁止修改的文件、必须遵循的安全策略。

3.2 实战示例：一个 Python Web 项目的 CLAUDE.md

# CLAUDE.md - My Awesome API Project

## 项目概述
这是一个基于 FastAPI 的 RESTful API 服务，用于管理用户和订单数据。

## 技术栈
- 语言：Python 3.11+
- 框架：FastAPI
- 数据库：PostgreSQL + SQLAlchemy (async)
- 缓存：Redis
- 测试：pytest + httpx

## 编码规范
- 所有 API 端点必须使用 Pydantic 模型进行请求/响应校验。
- 数据库操作必须使用异步 Session。
- 函数和类必须包含类型注解。
- 日志使用 `structlog`，不要使用 `print`。
- 所有新功能必须编写单元测试和集成测试。

## 全局约束
- **严禁**修改 `alembic/versions/` 目录下的数据库迁移文件。
- **严禁**在代码中硬编码 API Key 或数据库密码，必须从环境变量读取。
- 所有对外 API 响应必须包含 `request_id` 字段。

## 目录结构

src/
api/ # API 路由
core/ # 核心配置与依赖
models/ # SQLAlchemy 模型
schemas/ # Pydantic 模型
services/ # 业务逻辑层
tests/
unit/
integration/

3.3 使用场景

• 新项目初始化：第一次与 Claude Code 协作时，先写好 CLAUDE.md。
• 接手旧项目：快速让 AI 理解项目背景和约束。
• 团队协作：统一 AI 助手的行为，避免不同开发者使用时产生不一致。

4. Rules：行为“守则”

Rules 是比 CLAUDE.md 更灵活、更细粒度的规则系统。它可以作用于全局（所有项目）或特定项目。

4.1 全局 Rules

全局 Rules 存放在 ~/.claude/rules/ 目录下，对所有项目生效。适合定义个人偏好或通用安全策略。

示例：~/.claude/rules/security.md

# 安全规则

1. 永远不要执行 `rm -rf /` 或任何可能破坏系统的命令。
2. 在安装新的 Python 包之前，先检查 `requirements.txt` 或 `pyproject.toml` 中是否已有。
3. 如果用户要求执行一个看起来有风险的命令（如 `curl ... | bash`），必须先向用户确认。

4.2 项目级 Rules

项目级 Rules 存放在项目根目录的 .claude/rules/ 下，仅对该项目生效。适合定义该项目特有的、但不想写在 CLAUDE.md 中的规则。

示例：.claude/rules/testing.md

# 测试规则

1. 在修改任何 `src/services/` 下的业务逻辑后，必须运行相关的单元测试。
2. 新增 API 端点时，必须同时在 `tests/integration/` 下创建对应的集成测试。
3. 测试覆盖率不得低于 80%。

4.3 Rules vs CLAUDE.md

维度	CLAUDE.md	Rules
文件位置	项目根目录	~/.claude/rules/ 或 .claude/rules/
作用域	项目级	全局或项目级
内容风格	项目“宪法”，宏观	行为“守则”，具体
典型内容	技术栈、目录结构、全局约束	编码细节、测试要求、安全策略

最佳实践：将项目背景、技术栈等不变的信息放在 CLAUDE.md；将具体的编码、测试、安全行为规则放在 Rules 中，便于按需启用/禁用。

5. Skills：可插拔的“工具箱”

Skills 是 Claude Code 最强大的特性之一。它允许你定义可复用的能力、工作流或工具，并在需要时通过 @skill 显式调用。

5.1 核心概念

• 定义：一个 Skill 是一个包含 skill.md 和可选脚本的目录。
• 存储位置：~/.claude/skills/。
• 调用方式：在对话中输入 @skill-name。
• 核心价值：将复杂、重复的工作流封装成一个简单的命令。

5.2 实战示例：创建一个“代码审查” Skill

目录结构：

~/.claude/skills/code-review/
  skill.md
  review.py

skill.md：

# Code Review Skill

## 描述
对当前工作区中的代码变更进行全面的代码审查。

## 用法
在对话中输入 `@code-review` 即可触发。

## 工作流
1. 运行 `git diff HEAD` 获取当前变更。
2. 调用 `review.py` 脚本对变更进行分析。
3. 输出审查结果，包括：代码质量、潜在 Bug、安全漏洞、性能建议。

review.py：

#!/usr/bin/env python3
import subprocess
import sys

def get_git_diff():
    result = subprocess.run(['git', 'diff', 'HEAD'], capture_output=True, text=True)
    return result.stdout

def analyze_diff(diff_content):
    # 这里可以集成更复杂的分析逻辑，如调用 linter、静态分析工具等
    issues = []
    if 'TODO' in diff_content:
        issues.append("发现未处理的 TODO 注释，请确认是否需要处理。")
    if 'print(' in diff_content:
        issues.append("发现 print 语句，请确认是否应替换为日志记录。")
    return issues

def main():
    diff = get_git_diff()
    if not diff:
        print("没有发现代码变更。")
        return
    
    issues = analyze_diff(diff)
    if issues:
        print("### 代码审查结果")
        for issue in issues:
            print(f"- {issue}")
    else:
        print("代码审查通过，未发现明显问题。")

if __name__ == "__main__":
    main()

5.3 使用场景

• 代码审查：@code-review
• 数据库迁移：@db-migrate
• 部署流程：@deploy-to-staging
• 日志分析：@analyze-logs

6. Hooks：自动化“哨兵”

Hooks 允许你在 Claude Code 的特定生命周期事件（如文件读写、命令执行）前后，自动执行自定义脚本。这类似于 Git Hooks，但作用于 AI 助手的操作。

6.1 核心概念

• 事件驱动：Hooks 由特定事件触发，而非手动调用。
• 前后拦截：可以在事件发生前（pre-*）或发生后（post-*）执行。
• 脚本执行：可以执行任何可执行脚本（Shell、Python、Node.js 等）。

6.2 支持的 Hook 事件

Hook 名称	触发时机	典型用途
pre-tool-execution	在 Claude Code 执行任何工具前	安全检查、日志记录
post-tool-execution	在 Claude Code 执行任何工具后	结果验证、通知
pre-file-write	在写入文件前	代码格式化、许可证头检查
post-file-write	在写入文件后	自动编译、触发测试
pre-command	在执行 Shell 命令前	命令白名单/黑名单检查
post-command	在执行 Shell 命令后	命令结果分析

6.3 实战示例：一个“安全哨兵” Hook

目录结构（在项目根目录的 .claude/hooks/ 下）：

.claude/hooks/
  pre-command.sh
  pre-file-write.sh

.claude/hooks/pre-command.sh：

#!/bin/bash
# 在 Claude Code 执行任何 Shell 命令前进行检查

COMMAND="$1"

# 黑名单命令
BLACKLIST=("rm -rf /" "dd if=" "mkfs" "> /dev/sda")

for banned_cmd in "${BLACKLIST[@]}"; do
    if [[ "$COMMAND" == *"$banned_cmd"* ]]; then
        echo "❌ 危险命令被拦截: $COMMAND"
        exit 1  # 返回非零值阻止命令执行
    fi
done

# 白名单检查：只允许执行 git、npm、pip、python、docker 等安全命令
ALLOWED_PREFIXES=("git" "npm" "pip" "python" "docker" "ls" "cat" "echo" "mkdir" "touch" "cp" "mv")

ALLOWED=false
for prefix in "${ALLOWED_PREFIXES[@]}"; do
    if [[ "$COMMAND" == "$prefix"* ]]; then
        ALLOWED=true
        break
    fi
done

if [ "$ALLOWED" = false ]; then
    echo "⚠️  命令 '$COMMAND' 不在白名单中，是否继续？(y/n)"
    read -r response
    if [ "$response" != "y" ]; then
        exit 1
    fi
fi

exit 0

.claude/hooks/pre-file-write.sh：

#!/bin/bash
# 在写入文件前，自动添加许可证头（如果是 Python 文件）

FILE_PATH="$1"
FILE_EXT="${FILE_PATH##*.}"

if [ "$FILE_EXT" == "py" ]; then
    # 检查是否已有许可证头
    if ! head -1 "$FILE_PATH" 2>/dev/null | grep -q "# Copyright"; then
        # 在文件开头插入许可证头
        LICENSE_HEADER="# Copyright $(date +%Y) My Company. All rights reserved.\n# Licensed under the MIT License.\n"
        # 注意：这里只是演示，实际修改文件内容需要更复杂的处理
        echo "📝 正在为 $FILE_PATH 添加许可证头..."
    fi
fi

exit 0

6.4 使用场景

• 安全防护：阻止危险命令的执行。
• 代码质量：在写入前自动格式化代码。
• 自动化工作流：文件变更后自动运行测试。
• 合规检查：确保所有新文件都包含必要的许可证头。

7. 四者协同：一个完整的实战工作流

现在，让我们通过一个完整的场景，看看这四者如何协同工作。

7.1 场景描述

你正在开发一个 FastAPI 项目，需要 Claude Code 帮你添加一个新的用户注册 API。

7.2 配置准备

1. CLAUDE.md：定义了项目背景、技术栈和全局约束（如必须使用异步 Session）。
2. Rules：定义了测试规则（新增 API 必须写集成测试）。
3. Skills：定义了一个 @code-review Skill，用于审查代码变更。
4. Hooks：定义了一个 pre-command Hook，阻止危险命令；一个 post-file-write Hook，在写入新文件后自动运行相关测试。

7.3 工作流执行

1. 你：帮我添加一个用户注册 API，路径为 /api/v1/register，使用邮箱和密码注册。
2. Claude Code 启动：
   • 自动读取 CLAUDE.md，了解项目是 FastAPI + SQLAlchemy async。
   • 自动加载 Rules，知道新增 API 需要写集成测试。
3. Claude Code 生成代码：
   • 在 src/api/v1/ 下创建 register.py。
   • 在 src/schemas/ 下创建 register_schema.py。
   • 在 src/services/ 下创建 register_service.py。
   • 在 tests/integration/ 下创建 test_register.py。
4. Hooks 介入：
   • pre-file-write Hook 检查新文件是否包含许可证头（根据 CLAUDE.md 的约束）。
   • post-file-write Hook 自动运行 pytest tests/integration/test_register.py。
5. 你：帮我审查一下这些变更。
6. Claude Code：调用 @code-review Skill，运行 git diff 并执行 review.py 进行分析，输出审查结果。

7.4 协同效果

• CLAUDE.md 提供了项目上下文，确保代码风格一致。
• Rules 确保了测试覆盖。
• Hooks 自动执行了安全检查和测试。
• Skills 简化了代码审查流程。

8. 总结与最佳实践

8.1 选择指南

需求	推荐方案
定义项目背景和技术栈	CLAUDE.md
定义通用的编码规范	Rules（全局）
定义项目特有的行为规则	Rules（项目级）
封装可复用的工作流	Skills
在特定事件前后自动执行操作	Hooks

8.2 最佳实践

1. 从 CLAUDE.md 开始：每个项目都应该有一个 CLAUDE.md，这是 AI 助手理解项目的基石。
2. Rules 要具体：规则越具体，AI 的执行效果越好。避免模糊的描述。
3. Skills 要封装：将复杂的、多步骤的工作流封装成 Skill，可以大幅提升效率。
4. Hooks 要谨慎：Hooks 有自动执行的能力，务必确保脚本的安全性和稳定性。
5. 组合使用：四者不是互斥的，而是互补的。合理组合可以发挥最大威力。
6. 版本控制：将 CLAUDE.md、.claude/rules/、.claude/hooks/ 纳入 Git 版本控制，方便团队共享和追踪变更。

通过本文的梳理和实战，相信你已经彻底理解了 CLAUDE.md、Rules、Skills、Hooks 的分工与协作方式。现在，去给你的 Claude Code 项目配置一个完美的“大脑”吧！