深入理解 Claude Code：CLAUDE.md、Hooks、Skills、Subagents 全解析-开发者社区

1. 引言

Claude Code 是 Anthropic 推出的命令行 AI 编程助手，它不仅能理解自然语言指令，还能通过一系列机制实现高度可定制、可扩展的自动化编码工作流。对于想要真正驾驭 Claude Code 的开发者来说，仅仅会提问远远不够，理解其四大核心扩展机制——CLAUDE.md、Hooks、Skills和Subagents——才是从「会用」走向「精通」的关键。

本文将深入剖析这四大机制的原理与实战用法，通过大量可复制的代码示例，帮助你构建一套属于自己的高效 AI 编码工作流。

2. CLAUDE.md：项目的「记忆」与「行为准则」

2.1 什么是 CLAUDE.md

CLAUDE.md是 Claude Code 在项目中的核心配置文件。它相当于给 Claude 的一份「项目说明书」，告诉它项目的结构、技术栈、编码规范、常用命令以及需要特别注意的事项。每次会话启动时，Claude Code 会自动读取该文件，并将其作为长期记忆和上下文的一部分。

2.2 文件层级与加载机制

Claude Code 支持多级CLAUDE.md文件，它们按以下优先级从高到低加载：

企业级策略文件（/etc/claude-code/managed-settings.json中配置）
用户级全局文件（~/.claude/CLAUDE.md）
项目级文件（项目根目录的CLAUDE.md）
子目录级文件（各子目录下的CLAUDE.md，作用于该目录及其子目录）

当多个层级的文件同时存在时，Claude 会合并它们的内容，但更具体的层级（如子目录）会覆盖更通用层级（如用户级）的冲突指令。

2.3 实战：编写一份高质量的项目 CLAUDE.md

下面是一份针对一个 Python FastAPI 项目的CLAUDE.md示例：

# 项目：OrderAPI ## 项目概述 这是一个基于 FastAPI 的订单管理系统，使用 PostgreSQL 存储数据，通过 Redis 做缓存。 ## 技术栈 - Python 3.11+ - FastAPI 0.100+ - SQLAlchemy 2.0 - Alembic（数据库迁移） - Pytest（测试） ## 常用命令 - 启动开发服务器：`uvicorn app.main:app --reload` - 运行测试：`pytest` - 数据库迁移：`alembic upgrade head` - 代码格式化：`ruff format .` ## 编码规范 - 所有 API 路由必须使用 `/api/v1/` 前缀 - 使用类型注解，禁止使用 `Any` 类型 - 数据库会话必须通过依赖注入获取，禁止直接创建 - 所有业务逻辑写在 service 层，路由层只做参数校验和响应封装 ## 架构约定 - `app/models/`：SQLAlchemy 模型 - `app/schemas/`：Pydantic 模型 - `app/services/`：业务逻辑 - `app/api/`：路由定义 ## 注意事项 - 修改数据库模型后必须生成新的 Alembic 迁移 - 不要提交 `.env` 文件到版本控制 - 所有新增接口必须附带对应的单元测试

2.4 进阶技巧：使用`@`引用外部文件

当项目文档较多时，可以在CLAUDE.md中使用@语法引用其他文件，让 Claude 按需加载：

## 架构设计 @docs/architecture.md ## API 规范 @docs/api-conventions.md

这样既能保持主文件简洁，又能让 Claude 在需要时获取详细文档。

3. Hooks：自动化工作流的「触发器」

3.1 什么是 Hooks

Hooks 是 Claude Code 的生命周期回调机制。它允许你在 Claude 执行特定操作（如开始编辑文件、执行命令、完成一次回复）时，自动运行自定义脚本。这为工作流自动化、代码质量保障和安全防护提供了强大的支持。

3.2 Hook 的类型与触发时机

Hooks 通过settings.json配置，主要分为以下几类：

Hook 类型	触发时机	典型用途
`PreToolUse`	调用工具之前	权限校验、参数检查、敏感操作拦截
`PostToolUse`	调用工具之后	自动格式化、运行测试、日志记录
`Notification`	需要用户通知时	发送桌面通知、消息推送
`UserPromptSubmit`	用户提交提示词时	注入额外上下文、敏感信息过滤
`Stop`	Claude 完成回复时	自动提交代码、清理临时文件
`SubagentStop`	子代理完成时	汇总子代理结果

3.3 实战：配置一个 PreToolUse Hook 拦截危险命令

下面通过一个实际案例，演示如何用 Hook 拦截rm -rf这类危险命令。

首先，创建 Hook 脚本hooks/guard.js：

#!/usr/bin/env node// 接收 stdin 中的 JSON 输入letinput="";process.stdin.on("data",(chunk)=>(input+=chunk));process.stdin.on("end",()=>{constevent=JSON.parse(input);consttoolName=event.tool_name;consttoolInput=event.tool_input;// 拦截 Bash 工具中的危险命令if(toolName==="Bash"){constcommand=toolInput.command||"";if(command.includes("rm -rf")||command.includes("git push --force")){// 返回非零退出码并输出拦截原因console.error("危险命令已被 Hook 拦截："+command);process.exit(2);}}// 放行process.exit(0);});

然后在settings.json中注册该 Hook：

{"hooks":{"PreToolUse":[{"matcher":"Bash","hooks":[{"type":"command","command":"node hooks/guard.js"}]}]}}

3.4 实战：PostToolUse Hook 自动格式化代码

每次 Claude 编辑完 Python 文件后，自动运行ruff格式化：

{"hooks":{"PostToolUse":[{"matcher":"Edit|Write","hooks":[{"type":"command","command":"ruff format --quiet $(git diff --name-only | grep '\\.py$')"}]}]}}

3.5 Hook 的输入输出协议

Claude Code 通过 stdin 向 Hook 脚本传递 JSON 格式的事件数据，Hook 脚本通过 stdout 输出 JSON 格式的响应。核心字段如下：

输入事件示例：

{"session_id":"abc123","tool_name":"Edit","tool_input":{"file_path":"/path/to/app.py","old_string":"def foo():","new_string":"def foo():\n pass"}}

输出响应示例（用于 PreToolUse 拦截）：

{"decision":"block","reason":"该文件属于只读目录，禁止修改"}

4. Skills：可复用的「技能包」

4.1 什么是 Skills

Skills 是 Claude Code 中的可复用能力模块。一个 Skill 通常包含一组指令、示例和资源文件，用于教会 Claude 完成某一类特定任务。与CLAUDE.md的「被动记忆」不同，Skills 是「主动能力」，Claude 会在需要时自动调用它们。

4.2 Skill 的目录结构

一个标准的 Skill 目录结构如下：

~/.claude/skills/ └── code-review/ ├── SKILL.md # 技能定义文件（必需） ├── prompts/ # 可选的提示词模板 │ └── review.md └── scripts/ # 可选的辅助脚本 └── analyze.py

4.3 实战：创建一个代码审查 Skill

创建~/.claude/skills/code-review/SKILL.md：

--- name: code-review description: 对代码变更进行全面的代码审查，检查代码质量、安全性和潜在 bug。当用户要求「审查代码」「code review」或提交 PR 前使用。 --- # 代码审查技能 当你被要求进行代码审查时，请遵循以下流程： ## 审查步骤 1. **获取变更范围**：使用 `git diff` 获取当前分支的变更内容 2. **逐文件审查**：对每个变更文件执行以下检查： - 逻辑正确性：是否存在边界条件遗漏或逻辑错误 - 安全性：是否存在 SQL 注入、XSS、敏感信息泄露等风险 - 性能：是否存在明显的性能瓶颈 - 代码规范：是否符合项目的编码规范 3. **输出审查报告**：按以下格式输出： ```markdown ## 审查报告 ### 严重问题 - [文件:行号] 问题描述 ### 建议改进 - [文件:行号] 改进建议 ### 亮点 - 值得肯定的设计

注意事项

优先关注严重问题，不要过度纠结于代码风格
如果变更涉及数据库迁移，必须检查迁移脚本的安全性

### 4.4 在 CLAUDE.md 中声明 Skill 为了让 Claude 知道在什么场景下使用哪些 Skill，可以在 `CLAUDE.md` 中声明： ```markdown ## 可用技能 - 当需要审查代码时，使用 `code-review` 技能 - 当需要编写单元测试时，使用 `test-writer` 技能

4.5 实战：创建一个「提交信息生成」Skill

创建~/.claude/skills/commit-message/SKILL.md：

--- name: commit-message description: 根据代码变更生成符合 Conventional Commits 规范的提交信息。当用户要求「生成提交信息」「写 commit message」时使用。 --- # 提交信息生成技能 ## 执行步骤 1. 运行 `git diff --stat` 和 `git diff` 查看变更内容 2. 分析变更类型，确定 commit type： - `feat`：新功能 - `fix`：修复 bug - `refactor`：重构 - `docs`：文档变更 - `test`：测试相关 - `chore`：构建或辅助工具变动 3. 生成符合以下格式的提交信息：

():

示例

输入：修改了用户登录接口的密码加密方式
输出：

fix(auth): 修复密码加密方式 将 MD5 加密替换为 bcrypt，提升安全性。

5. Subagents：并行协作的「专业团队」

5.1 什么是 Subagents

Subagents 是 Claude Code 中的子代理机制。你可以创建多个具有不同「角色设定」和「专业领域」的子代理，让主 Claude 在需要时委派任务给它们。每个 Subagent 拥有独立的上下文窗口，可以并行工作，大幅提升复杂任务的完成效率。

5.2 Subagent 的配置方式

Subagents 通过.claude/subagents/目录下的 Markdown 文件定义。每个文件定义一个子代理：

.claude/subagents/ ├── frontend-expert.md ├── security-auditor.md └── test-writer.md

5.3 实战：定义一个前端专家 Subagent

创建.claude/subagents/frontend-expert.md：

--- name: frontend-expert description: 前端开发专家，精通 React、Vue、TypeScript 和现代 CSS。当需要实现或修改前端界面时使用。 tools: Read, Grep, Glob, Edit, Write, Bash model: sonnet --- # 前端专家 你是一名资深前端工程师，拥有 10 年以上的 Web 开发经验。 ## 专业领域 - React 18+ / Vue 3+ 组件开发 - TypeScript 类型系统 - 响应式布局与 CSS 动画 - 前端性能优化 - 无障碍访问（a11y） ## 工作准则 1. 所有组件必须使用 TypeScript 编写 2. 组件样式使用 CSS Modules 或 Tailwind，禁止使用全局样式 3. 必须处理 loading、error、empty 三种状态 4. 性能敏感场景使用 `React.memo` 或 `useMemo` 优化 5. 代码提交前必须通过 ESLint 检查 ## 输出规范 - 提供完整的组件代码，包含样式和类型定义 - 说明组件的 props 接口 - 给出使用示例

5.4 实战：定义一个安全审计 Subagent

创建.claude/subagents/security-auditor.md：

--- name: security-auditor description: 安全审计专家，擅长发现代码中的安全漏洞。当需要检查代码安全性或进行安全审查时使用。 tools: Read, Grep, Glob, Bash model: sonnet --- # 安全审计专家 你是一名应用安全工程师，专注于 Web 应用安全。 ## 审查重点 1. **注入攻击**：SQL 注入、命令注入、模板注入 2. **认证与授权**：越权访问、会话管理缺陷 3. **敏感数据**：硬编码密钥、日志泄露、不安全的存储 4. **XSS 攻击**：反射型、存储型、DOM 型 5. **依赖安全**：存在已知漏洞的第三方库 ## 工作流程 1. 使用 `grep` 搜索敏感模式（如 `password`、`secret`、`api_key`） 2. 审查用户输入的处理流程 3. 检查数据库查询语句的构造方式 4. 输出安全审查报告，按严重程度分级 ## 输出格式 ```markdown ## 安全审查报告 ### 🔴 严重漏洞 - 位置、漏洞类型、攻击路径、修复建议 ### 🟡 中危问题 - 位置、问题描述、改进建议 ### 🟢 安全实践 - 做得好的地方

5.5 在 CLAUDE.md 中声明 Subagents

## 子代理 - 涉及前端界面开发时，委派给 `frontend-expert` - 涉及安全审查时，委派给 `security-auditor` - 涉及测试编写时，委派给 `test-writer`

5.6 Subagent 的调用方式

当主 Claude 判断任务适合委派时，会自动调用 Subagent。你也可以在提示词中显式要求：

请让 frontend-expert 子代理审查一下这个 React 组件的性能问题。

6. 四大机制协同实战：构建一个完整的自动化工作流

下面通过一个综合案例，展示如何将四大机制组合起来，构建一个完整的开发工作流。

6.1 场景描述

假设我们要开发一个 Node.js 的 REST API 服务，希望实现以下自动化：

每次 Claude 编辑代码后自动运行测试
提交代码前自动进行安全审查
生成符合规范的提交信息

6.2 项目结构

my-api/ ├── CLAUDE.md ├── .claude/ │ └── subagents/ │ ├── security-auditor.md │ └── test-writer.md ├── ~/.claude/ │ ├── settings.json │ └── skills/ │ ├── code-review/ │ │ └── SKILL.md │ └── commit-message/ │ └── SKILL.md

6.3 配置 CLAUDE.md

# 项目：MyAPI ## 技术栈 - Node.js 20+ - Express 4 - Jest（测试） ## 常用命令 - 启动：`npm start` - 测试：`npm test` ## 子代理 - 涉及安全审查时，使用 `security-auditor` - 涉及测试编写时，使用 `test-writer` ## 技能 - 提交代码前，使用 `commit-message` 技能生成提交信息

6.4 配置 Hooks

在~/.claude/settings.json中配置：

{"hooks":{"PostToolUse":[{"matcher":"Edit|Write","hooks":[{"type":"command","command":"npm test -- --silent"}]}],"PreToolUse":[{"matcher":"Bash","hooks":[{"type":"command","command":"node ~/.claude/hooks/guard.js"}]}]}}

6.5 工作流效果

当开发者对 Claude 说「帮我实现用户注册接口」时，整个工作流如下：

主 Claude读取CLAUDE.md，了解项目结构和规范
主 Claude编写代码，使用Edit工具修改文件
PostToolUse Hook自动触发，运行npm test验证代码
如果涉及安全敏感操作，主 Claude委派security-auditor子代理进行审查
开发完成后，开发者要求「生成提交信息」，主 Claude调用commit-message技能生成规范提交信息

7. 最佳实践与注意事项

7.1 CLAUDE.md 编写建议

保持简洁：只写必要的信息，避免冗长
使用明确的指令：用「必须」「禁止」等强约束词
定期更新：随