1. 引言

Claude Code 是 Anthropic 推出的一款基于终端的 AI 编程助手，它不仅仅是一个简单的代码补全工具，更是一个能够深度融入开发者工作流的智能体（Agent）。要真正发挥 Claude Code 的潜力，理解其核心扩展机制至关重要。本文将深入探讨 Claude Code 的四大核心概念：CLAUDE.md（项目级指令）、Hooks（生命周期钩子）、Skills（可复用技能）以及 Subagents（子智能体），帮助你从“会用”进阶到“精通”。

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

CLAUDE.md 是 Claude Code 的项目级配置文件，它位于项目根目录，定义了 Claude Code 在该项目中的行为准则、技术栈偏好、编码规范以及关键上下文。你可以把它理解为一份给 AI 助手的“项目宪法”。

2.1 为什么需要 CLAUDE.md？

在没有 CLAUDE.md 的情况下，Claude Code 每次启动时都只能依赖通用知识库和当前对话上下文。对于大型项目或特定技术栈的项目，这会导致：

  • 风格不一致：生成的代码可能不符合项目已有的编码规范。
  • 上下文缺失：需要反复解释项目架构、依赖关系或构建工具。
  • 效率低下：AI 可能会提出不适用于当前项目的方案。

CLAUDE.md 解决了这些问题，它让 Claude Code 在进入项目的第一秒就“了解”项目的一切。

2.2 CLAUDE.md 的核心内容

一个典型的 CLAUDE.md 文件通常包含以下部分：

# CLAUDE.md - 项目指南

## 技术栈
- 后端：Python 3.11 + FastAPI
- 前端：React 18 + TypeScript + Vite
- 数据库：PostgreSQL 15 + SQLAlchemy 2.0
- 测试：pytest + Playwright

## 编码规范
- 遵循 PEP 8，行宽 100 字符。
- 使用类型注解（Type Hints）。
- 所有公共函数和类必须包含 Docstring。
- 前端组件使用函数式组件 + Hooks。

## 项目结构
- `/backend/app`：FastAPI 应用主目录
- `/frontend/src`：React 源码
- `/tests`：测试用例

## 关键约定
- 数据库迁移使用 Alembic。
- API 路由前缀统一为 `/api/v1`。
- 错误处理使用自定义异常类，并返回统一格式的 JSON 响应。

## 常用命令
- 启动后端：`uvicorn backend.app.main:app --reload`
- 运行测试：`pytest`
- 构建前端：`npm run build`

2.3 如何创建 CLAUDE.md？

你可以手动创建，也可以让 Claude Code 帮你生成。一个高效的方法是：在项目根目录下运行 Claude Code，然后输入：

“请分析当前项目的技术栈、目录结构和代码风格，并生成一份 CLAUDE.md 文件。”

Claude Code 会扫描项目文件，自动推断出上述信息并生成草稿，你只需确认或微调即可。

2.4 CLAUDE.md 的生效范围

  • 全局生效：一旦创建，Claude Code 在项目内的所有会话都会自动加载并遵循该文件。
  • 可嵌套：虽然不常见，但理论上可以在子目录中放置 CLAUDE.md 来覆盖根目录的配置，适用于 Monorepo 等复杂项目结构。

3. Hooks：自定义工作流钩子

Hooks 是 Claude Code 提供的一种生命周期回调机制，允许你在 Claude Code 执行特定操作的前后，自动触发自定义脚本或命令。这为自动化工作流打开了大门。

3.1 Hooks 的类型

Claude Code 支持以下几种类型的 Hooks：

Hook 名称 触发时机 典型用途
pre-tool 在 Claude Code 调用任何工具（如读文件、写文件、运行命令）之前 权限检查、环境准备、日志记录
post-tool 在工具调用完成之后 结果验证、自动格式化、通知推送
pre-command 在 Claude Code 执行 Shell 命令之前 安全检查、命令审批
post-command 在 Shell 命令执行完成之后 输出分析、错误处理、自动重试

3.2 配置 Hooks

Hooks 的配置同样位于项目根目录，通常在一个名为 .claude/settings.json 的文件中（或通过 CLAUDE.md 中的 hooks 字段指定）。

示例：.claude/settings.json

{
  "hooks": {
    "pre-tool": [
      {
        "match": "tool:write",
        "command": "echo '即将写入文件: $TOOL_ARGS' >> /tmp/claude_hooks.log"
      }
    ],
    "post-command": [
      {
        "match": "command:run",
        "command": "if [ $? -ne 0 ]; then echo '命令执行失败，请检查'; fi"
      }
    ]
  }
}

更实用的例子：自动格式化代码

{
  "hooks": {
    "post-tool": [
      {
        "match": "tool:write",
        "command": "npx prettier --write $FILE_PATH"
      }
    ]
  }
}

这个 Hook 会在 Claude Code 每次写入文件后，自动使用 Prettier 格式化该文件，确保代码风格统一。

3.3 Hooks 的注意事项

  • 性能影响：复杂的 Hook 脚本可能会拖慢 Claude Code 的响应速度，建议保持 Hook 脚本轻量。
  • 安全性：Hook 拥有执行任意命令的权限，请确保其来源可信，避免引入安全漏洞。
  • 调试：Hook 执行失败通常不会阻断主流程，但会输出错误日志，方便你排查问题。

4. Skills：可复用的智能技能包

Skills 是 Claude Code 中可复用的、模块化的指令集。你可以把 Skills 理解为“AI 的插件”或“预置的专家知识”。通过 Skills，你可以让 Claude Code 瞬间掌握特定领域的专业知识或执行特定任务的流程。

4.1 Skills 的形态

一个 Skill 本质上是一个包含特定指令的 Markdown 文件，通常存放在项目内的 .claude/skills/ 目录下。

示例：.claude/skills/database-migration.md

# 数据库迁移技能

## 描述
本技能指导 Claude Code 如何安全地创建和执行数据库迁移。

## 步骤
1. 修改 `backend/app/models/` 下的模型文件。
2. 运行 `alembic revision --autogenerate -m "描述你的变更"` 生成迁移文件。
3. 检查生成的迁移文件，确保其正确性。
4. 运行 `alembic upgrade head` 应用迁移。
5. 如果迁移涉及数据迁移，请编写数据迁移脚本并放在 `backend/app/migrations/versions/` 下。

## 注意事项
- 永远不要在 `main` 分支上直接运行 `alembic upgrade head`。
- 生产环境的迁移必须经过 Code Review。

4.2 如何调用 Skills？

你可以通过以下方式让 Claude Code 使用某个 Skill：

  • 在对话中引用：直接说“请使用 database-migration 技能来创建这次模型变更的迁移。”
  • 自动匹配：当你的请求与某个 Skill 的描述高度相关时，Claude Code 可能会自动激活该 Skill。
  • 在 CLAUDE.md 中声明：你可以在 CLAUDE.md 中列出项目常用的 Skills，让 Claude Code 在启动时就加载它们。

4.3 Skills 的优势

  • 知识固化：将团队的最佳实践、复杂流程固化为可复用的技能，新人也能快速上手。
  • 一致性：确保 AI 在处理同类任务时，遵循统一的步骤和标准。
  • 模块化：不同的 Skills 可以组合使用，应对更复杂的场景。

5. Subagents：并行协作的子智能体

Subagents 是 Claude Code 最强大的特性之一，它允许 Claude Code 在需要时创建并委托任务给多个子智能体。这些子智能体可以并行工作，各自处理独立的任务，最后将结果汇总给主智能体。

5.1 Subagents 的工作原理

  1. 任务分解：主 Claude Code 智能体（Master Agent）分析你的复杂请求，将其拆解为多个独立的子任务。
  2. 子智能体创建：Master Agent 为每个子任务创建一个 Subagent。每个 Subagent 拥有独立的上下文、文件系统和工具调用能力。
  3. 并行执行：多个 Subagents 可以同时工作，互不干扰。例如，一个 Subagent 在修改前端代码，另一个在修改后端 API，第三个在编写测试用例。
  4. 结果汇总：所有 Subagents 完成任务后，Master Agent 会收集它们的结果，进行整合、冲突解决，并最终输出给用户。

5.2 Subagents 的典型应用场景

  • 大规模重构：同时重构多个模块，Subagents 可以并行处理不同模块的代码变更。
  • 多文件修改：需要同时修改前端、后端、数据库迁移和测试文件时，Subagents 可以分工协作。
  • 复杂调研：让一个 Subagent 去阅读文档，另一个去搜索 Stack Overflow，第三个去分析代码库，最后汇总调研结果。
  • 代码审查：让多个 Subagents 分别从安全性、性能、可读性等不同角度审查同一段代码。

5.3 Subagents 的注意事项

  • 资源消耗：创建多个 Subagents 会显著增加 Token 消耗和计算资源，适用于复杂任务。
  • 上下文隔离：Subagents 之间默认不共享上下文，Master Agent 负责协调。这意味着你需要确保 Master Agent 能够清晰地分配任务。
  • 结果一致性：并行工作可能导致代码冲突，Master Agent 需要具备解决冲突的能力。

6. 四者协同：构建强大的 AI 开发工作流

理解了这四个概念后，我们来看看它们如何协同工作，构建一个高效的 AI 辅助开发环境。

  1. CLAUDE.md 是基石：它为整个项目设定了规则和上下文，是所有后续操作的基础。
  2. Hooks 是自动化引擎：在 CLAUDE.md 定义的规则下，Hooks 自动执行格式化、测试、部署等重复性任务。
  3. Skills 是知识库：将复杂的、领域特定的流程封装成 Skills，供 Claude Code 随时调用。
  4. Subagents 是并行计算单元：面对复杂任务时，Master Agent 利用 Skills 中的知识，创建多个 Subagents 并行工作，并在 CLAUDE.md 的约束下，通过 Hooks 自动完成后续的代码检查和格式化。

一个完整的例子：

假设你有一个大型 Python 项目，CLAUDE.md 定义了使用 black 和 isort 进行格式化。你创建了一个 add-new-api-endpoint 的 Skill，描述了创建新 API 的完整步骤。然后你向 Claude Code 提出请求：“请为 User 模型添加一个获取用户活动日志的 API 端点。”

  1. Master Agent 读取 CLAUDE.md，了解项目规范。
  2. Master Agent 激活 add-new-api-endpoint Skill，获取创建 API 的步骤。
  3. Master Agent 将任务分解为：修改模型、创建 Schema、编写路由、编写测试。
  4. Master Agent 创建 4 个 Subagents，分别处理上述子任务。
  5. 每个 Subagent 在完成任务后，Hooks 自动触发 black 和 isort 格式化代码。
  6. Master Agent 收集所有 Subagents 的结果，整合代码，并输出最终结果。

7. 总结

Claude Code 的 CLAUDE.md、Hooks、Skills 和 Subagents 构成了一个强大而灵活的开发框架。CLAUDE.md 定义了项目的“宪法”，Hooks 提供了自动化的“手脚”，Skills 封装了专家的“大脑”，而 Subagents 则赋予了 AI 并行协作的“团队”能力。掌握这四大核心概念，你将能够把 Claude Code 从一个简单的代码助手，升级为真正融入你开发流程的智能协作伙伴。

# 人工智能 # linux # 服务器 # 运维 # 职场和发展
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

我给 AI 写了一套“规矩“：数仓开发骨架 Ware-Smith 的设计思考（前言）

Ware-Smith 是一套基于 [AI IDE] Skill 体系的开源数据建模骨架（Skeleton）,它解决的是：当你把数据开发交给 AI 时，如何保证它不乱来。

avatar 龙虾开发者社区
cover

敏捷开发团队2026年如何搭配Scrum、看板和混合模式？

avatar 龙虾开发者社区
cover

Agentic AI 生产就绪安全白皮书

avatar 龙虾开发者社区