1. 引言

Claude Code 是 Anthropic 推出的命令行 AI 编程助手，它不仅能理解自然语言指令，还能通过一系列配置机制深度融入你的开发工作流。对于刚接触 Claude Code 的开发者来说，CLAUDE.md、Hooks、Skills、Subagents 这四个概念是进阶使用的关键，也是让 Claude Code 从「好用的聊天工具」进化为「团队级开发助手」的分水岭。

本文将逐一拆解这四个核心机制：它们分别解决什么问题、如何配置、彼此之间如何协作，并通过可运行的示例帮助你快速上手。

2. CLAUDE.md：项目级记忆与行为规范

2.1 它是什么

CLAUDE.md 是放在项目根目录（或 ~/.claude/ 全局目录）下的 Markdown 文件，用于向 Claude Code 提供项目上下文。每次会话启动时，Claude Code 会自动读取该文件，将其内容作为长期记忆注入到对话上下文中。

2.2 解决什么问题

• 减少重复解释：无需每次对话都重新说明项目结构、技术栈、构建命令。
• 统一编码规范：把团队的代码风格、命名约定、提交规范写进去，让 AI 输出更贴合团队标准。
• 提供关键路径：告诉 Claude 项目入口、测试命令、部署流程等高频信息。

2.3 配置示例

# 项目：电商后端服务

## 技术栈
- 语言：Java 17
- 框架：Spring Boot 3.2
- 构建：Maven

## 常用命令
- 本地启动：`mvn spring-boot:run`
- 运行测试：`mvn test`
- 打包：`mvn clean package`

## 代码规范
- 使用 Lombok 简化实体类
- Controller 层只做参数校验和路由，业务逻辑放 Service
- 所有对外接口返回统一响应体 `Result<T>`

## 注意事项
- 数据库迁移使用 Flyway，禁止手动改表
- 日志使用 SLF4J，禁止直接 `System.out.println`

2.4 层级与优先级

Claude Code 支持多级 CLAUDE.md，按优先级从高到低为：

1. 项目级：./CLAUDE.md（当前目录向上递归查找最近的）
2. 用户级：~/.claude/CLAUDE.md（全局个人偏好）
3. 企业级：由组织统一托管

当多级文件同时存在时，Claude Code 会合并读取，项目级内容优先于用户级。

3. Hooks：在关键节点注入自动化行为

3.1 它是什么

Hooks 是 Claude Code 的生命周期回调机制。它允许你在 Claude Code 执行过程中的特定节点（如工具调用前、会话开始、用户输入后）触发自定义脚本，从而实现对 AI 行为的拦截、校验和增强。

3.2 配置方式

Hooks 在 settings.json 中配置，支持两种位置：

• 项目级：.claude/settings.json
• 用户级：~/.claude/settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 scripts/validate_code.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"已读取文件\" >> /tmp/claude_hooks.log"
          }
        ]
      }
    ]
  }
}

3.3 常用 Hook 事件

事件名	触发时机	典型用途
PreToolUse	工具调用前	校验、拦截危险操作
PostToolUse	工具调用后	记录日志、触发后续流程
UserPromptSubmit	用户提交提示词后	注入额外上下文、敏感词过滤
Stop	一轮对话结束	清理临时文件、汇总结果
SubagentStop	子代理结束	收集子代理输出

3.4 实战：拦截危险命令

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 scripts/guard_bash.py"
          }
        ]
      }
    ]
  }
}

# scripts/guard_bash.py
import json, sys

# Claude Code 通过 stdin 传入 JSON 格式的工具调用信息
data = json.load(sys.stdin)
command = data.get("tool_input", {}).get("command", "")

# 黑名单检测
blocked = ["rm -rf /", "git push --force", "DROP TABLE"]
for keyword in blocked:
    if keyword in command:
        print(json.dumps({
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": f"检测到危险命令: {keyword}"
            }
        }))
        sys.exit(0)

# 默认放行
print(json.dumps({
    "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "allow"
    }
}))

4. Skills：可复用的能力包

4.1 它是什么

Skills 是 Claude Code 的可复用能力模块。一个 Skill 由一组指令、示例和资源文件组成，封装了某一类特定任务的完整方法论。与 CLAUDE.md 的「被动记忆」不同，Skill 是「主动能力」——当任务匹配时，Claude Code 会加载对应的 Skill 来指导自己完成任务。

4.2 目录结构

一个 Skill 通常放在 .claude/skills/<skill-name>/ 目录下：

.claude/skills/
└── code-review/
    ├── SKILL.md          # 技能定义（必填）
    ├── examples/
    │   └── review-example.md
    └── scripts/
        └── check_style.py

4.3 SKILL.md 的写法

---
name: code-review
description: 对代码变更进行系统性审查，检查安全性、性能和可维护性。当用户要求 review 代码或提交 PR 时使用。
---

# 代码审查技能

## 审查流程
1. 先读取变更文件列表，了解改动范围
2. 按以下维度逐项检查：
   - 安全性：SQL 注入、XSS、敏感信息泄露
   - 性能：循环嵌套、N+1 查询、大对象复制
   - 可维护性：命名、注释、重复代码
3. 输出审查报告，按严重程度分级

## 输出格式
- 🔴 严重：必须修复
- 🟡 建议：应当改进
- 🟢 提示：可选优化

4.4 与 CLAUDE.md 的分工

维度	CLAUDE.md	Skills
定位	项目级静态记忆	任务级动态能力
加载时机	每次会话自动加载	按需匹配加载
内容	项目事实、规范、命令	方法论、流程、示例
更新频率	低频（项目变更时）	可高频迭代

5. Subagents：并行协作的子代理

5.1 它是什么

Subagents 是 Claude Code 的子代理机制。你可以定义多个具有不同角色定位、系统提示词和工具权限的子代理，让主代理在需要时委派任务给它们，实现并行处理和职责分离。

5.2 配置方式

Subagents 定义在 .claude/agents/ 目录下，每个子代理一个 Markdown 文件：

---
name: security-reviewer
description: 安全审查专家，负责检查代码中的安全漏洞。当需要审查安全性时使用。
tools: Read, Grep, Bash
model: sonnet
---

# 安全审查专家

你是一名资深安全工程师，专注于 Web 应用安全。

## 审查重点
- 认证与授权逻辑
- 输入校验与注入防护
- 敏感数据存储与传输

## 工作方式
- 先定位关键入口文件
- 逐层追踪数据流
- 输出漏洞清单及修复建议

5.3 关键配置项

配置项	说明	示例
name	子代理名称	security-reviewer
description	触发条件描述	当需要安全审查时使用
tools	允许使用的工具白名单	Read, Grep, Bash
model	使用的模型	sonnet / opus

5.4 协作流程

6. 四者协同：一个完整的工作流示例

假设你在一个电商项目中，需要「新增一个用户注册接口，并确保安全合规」。四个机制可以这样协同：

1. CLAUDE.md 提供项目上下文：技术栈、代码规范、已有工具类。
2. Subagents 分工协作：主代理负责接口开发，security-reviewer 子代理并行审查安全风险。
3. Hooks 保驾护航：PreToolUse 拦截危险命令，PostToolUse 记录变更日志。
4. Skills 提供方法论：api-development Skill 指导接口开发的完整流程和最佳实践。

7. 最佳实践与注意事项

7.1 渐进式引入

不要一次性配置全部机制。建议按以下顺序逐步引入：

1. 先写好 CLAUDE.md，让 AI 理解项目
2. 再添加 1-2 个高频使用的 Skill
3. 然后配置关键节点的 Hooks
4. 最后按需拆分 Subagents

7.2 常见误区

• CLAUDE.md 写得过长：超过 100 行会稀释重点，建议精简到核心信息。
• Hooks 脚本不健壮：Hook 脚本异常会导致整个流程中断，务必做好异常处理。
• Skill 命名模糊：description 写得不清晰会导致匹配不到，要写清楚触发场景。
• Subagents 权限过大：给子代理过多工具权限会增加安全风险，遵循最小权限原则。

7.3 调试技巧

• 用 claude --debug 查看详细的上下文注入日志
• 在 Hook 脚本中输出 JSON 到 stderr 便于排查
• 用 claude --print 非交互模式快速验证配置效果

8. 总结

CLAUDE.md、Hooks、Skills、Subagents 构成了 Claude Code 的四大核心扩展机制：

• CLAUDE.md 是「记忆」，让 AI 懂项目
• Hooks 是「神经」，让 AI 行为可控
• Skills 是「肌肉记忆」，让 AI 会做事
• Subagents 是「团队」，让 AI 能协作

掌握这四者，你就能把 Claude Code 从单打独斗的编码助手，升级为深度融入团队流程的智能开发伙伴。建议从 CLAUDE.md 开始，逐步构建属于你自己的 AI 协作体系。