1. 引言

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

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

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

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

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中，便于按需启用/禁用。

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 python3importsubprocessimportsysdefget_git_diff():result=subprocess.run(['git','diff','HEAD'],capture_output=True,text=True)returnresult.stdoutdefanalyze_diff(diff_content):# 这里可以集成更复杂的分析逻辑，如调用 linter、静态分析工具等issues=[]if'TODO'indiff_content:issues.append("发现未处理的 TODO 注释，请确认是否需要处理。")if'print('indiff_content:issues.append("发现 print 语句，请确认是否应替换为日志记录。")returnissuesdefmain():diff=get_git_diff()ifnotdiff:print("没有发现代码变更。")returnissues=analyze_diff(diff)ifissues:print("### 代码审查结果")forissueinissues: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 事件

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")forbanned_cmdin"${BLACKLIST[@]}";doif[["$COMMAND"==*"$banned_cmd"*]];thenecho"❌ 危险命令被拦截:$COMMAND"exit1# 返回非零值阻止命令执行fidone# 白名单检查：只允许执行 git、npm、pip、python、docker 等安全命令ALLOWED_PREFIXES=("git""npm""pip""python""docker""ls""cat""echo""mkdir""touch""cp""mv")ALLOWED=falseforprefixin"${ALLOWED_PREFIXES[@]}";doif[["$COMMAND"=="$prefix"*]];thenALLOWED=truebreakfidoneif["$ALLOWED"=false];thenecho"⚠️ 命令 '$COMMAND' 不在白名单中，是否继续？(y/n)"read-rresponseif["$response"!="y"];thenexit1fifiexit0

.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添加许可证头..."fifiexit0

6.4 使用场景

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

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

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

7.1 场景描述

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

7.2 配置准备

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

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-writeHook 检查新文件是否包含许可证头（根据CLAUDE.md的约束）。
   • post-file-writeHook 自动运行pytest tests/integration/test_register.py。
5. 你：帮我审查一下这些变更。
6. Claude Code：调用@code-reviewSkill，运行git diff并执行review.py进行分析，输出审查结果。

7.4 协同效果

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

8. 总结与最佳实践

8.1 选择指南

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 项目配置一个完美的“大脑”吧！