编程导航会员会员
登录/注册

Claude Code凯神实战指南 - 第四章：让Claude连上一切——MCP、Hooks与Subagent实战

第四章：让Claude连上一切——MCP、Hooks与Subagent实战

📖 项目简介

这是由凯神精心打造的一套完整的 Claude Code 实战教程系列，从零基础环境安装，到企业级安全合规，全面系统地覆盖 Claude Code 的所有核心功能。

8个完整章节，包含：Commands / MCP / Hooks / Skills / Plugins / 团队协作 / 企业安全 等全部内容。

全中文编写，实战导向，每个章节都经过真实场景验证，帮助你快速从零开始，到能独立管理企业级项目。

👨‍🏫 关于作者

Lenyan 凯神

一名即将进入社会的应届生开发工程师。在学习 Claude Code 的过程中，深刻体验到它能极大提升开发效率。凯神把自己的学习笔记和实践经验整理成这套教程，希望帮助更多同学和新人开发者快速掌握这个强大工具。

这套教程的初衷很简单：让大家真正用上 Claude Code，提升编程效率，少走弯路。

凯神的观点：做好指挥官，让 AI 为你工作。

📚 笔记链接目录

1、Claude Code 实战指南 - 从零到起飞✨第一章

2、Claude Code 实战指南 - 30+命令与快捷键✨第二章

3、Claude Code 实战指南 - 自定义Commands让AI秒懂你✨第三章

4、Claude Code 实战指南 - MCP、Hooks与Subagent实战✨第四章

5、Claude Code 实战指南 - Skills定制给Claude装能力✨第五章

6、Claude Code 实战指南 - Plugins全攻略✨第六章

7、Claude Code 实战指南 - 企业级协作规范与CICD✨第七章

8、Claude Code 实战指南 - 企业深水区密钥安全✨第八章

立即开始学习 → 点击上方任意章节开始你的 Claude Code 之旅！🚀

目录

1. 前言

学完 Commands，你已经能把重复提示词压缩成一个词。

但 Claude 本身有能力边界——它不能直接操作数据库、不能搜网页、不能推代码到 GitHub。

MCP 和 Hooks 就是突破这个边界的两把钥匙：

工具解决什么问题类比
MCP让 Claude 调用外部服务（数据库/GitHub/搜索）给 Claude 装"插件"
Hooks让 Claude 在操作前后自动触发脚本（lint/测试/通知）给 Claude 设"自动触发器"

2. MCP 集成

2.1 MCP 是什么

MCP（Model Context Protocol）是 AI 连接外部工具的**"USB 标准"**——统一协议，任何 MCP Server 都能即插即用地被 Claude 调用。

对比没有 MCP有 MCP
对接成本每个工具单独开发一次开发，处处复用
兼容性各平台不通用开放标准，跨平台
生态各自为战社区共建，直接拿来用

2.2 配置方式

方式一：配置文件（推荐团队）

在项目根目录创建 .mcp.json：

▼
json
复制代码
{
  "mcpServers": {
    "服务器名": {
      "command": "npx",
      "args": ["-y", "包名", "附加参数"],
      "env": {
        "API_KEY": "${环境变量名}"
      }
    }
  }
}

${GITHUB_TOKEN} 会自动读取同名环境变量，不要把密钥硬写进文件。

方式二：CLI 快速添加（个人测试）

▼
bash
复制代码
claude mcp add <具体mcp地址>   # 添加
claude mcp list                          # 查看所有
claude mcp remove <名称>                 # 删除

▼
text
复制代码
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem D:/Desktop D:/develop


▼
text
复制代码
claude mcp list
或者/mcp


▼
text
复制代码
claude mcp remove filesystem -s user

删除成功：

作用域指定：

▼
bash
复制代码
claude mcp add --scope project <名称> ...  # 项目级（默认）
claude mcp add --scope user <名称> ...     # 用户级（全局）

2.3 常用服务器速查

分类服务器包名需 API Key推荐
文件filesystem@modelcontextprotocol/server-filesystem❌⭐⭐⭐
文件memory@modelcontextprotocol/server-memory❌⭐⭐
数据库sqlite@modelcontextprotocol/server-sqlite❌⭐⭐⭐
数据库postgres@modelcontextprotocol/server-postgres❌（需连接串）⭐⭐
开发github@modelcontextprotocol/server-github✅⭐⭐⭐
开发git@modelcontextprotocol/server-git❌⭐⭐
搜索brave-search@modelcontextprotocol/server-brave-search✅⭐⭐⭐
搜索fetch@modelcontextprotocol/server-fetch❌⭐⭐
知识context7@upstash/context7-mcp❌⭐⭐⭐
自动化puppeteer@modelcontextprotocol/server-puppeteer❌⭐⭐

典型配置示例（Filesystem + GitHub）：

▼
json
复制代码
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

启动 claude 时看到 ✓ filesystem ✓ github 即配置成功，C盘目录下 用户名下的 .claude.json文件。

image.png

2.4 三大作用域

作用域存储位置优先级适用场景
Local~/.claude.json（项目条目）最高含 API Key，绝不提交 Git
Project项目根 .mcp.json中团队共享，版本控制
User~/.claude.json（全局）最低个人通用工具，跨项目可用

选择原则：含密钥 → Local；团队必需 → Project；个人常用 → User。

2.5 在 Commands 中调用 MCP

第三章的 allowed-tools 直接支持 MCP 工具，格式：mcp__服务器名__工具名

▼
markdown
复制代码
---
allowed-tools:
  - mcp__github__create_issue
  - mcp__filesystem__read_file
  - mcp__brave-search__brave_web_search
---

这样 Commands 就能直接驱动 GitHub、文件系统、搜索等外部服务，形成完整自动化工作流。

2.6 故障排查

现象原因解决方法
启动时看不到 MCP 服务器配置文件路径或格式错误确认 .mcp.json 在项目根目录，JSON 格式正确
服务器启动失败Node.js 版本过低升级到 v18+
${VAR} 环境变量未生效变量未导出或终端未重启echo $VAR 验证，重启终端
工具调用被拒allowed-tools 未声明在 Commands frontmatter 加入工具名
npx 下载超时网络问题npm config set registry https://registry.npmmirror.com

3. Hooks 系统

3.1 Hooks 是什么

Hooks 是事件驱动的自动化触发器——Claude 执行特定操作时，自动运行你预设的 shell 脚本。

比如可以在ClaudeCode 写完代码后，自动执行某些命令的格式化，以便让最终的代码更加美观，更加符合我们的需求

Hook 时机触发事件典型用途
PreToolUseClaude 调用工具之前安全拦截危险命令、参数校验
PostToolUseClaude 调用工具之后自动 lint / 测试 / 格式化
PostToolUseFailureClaude 调用工具失败后错误日志记录、重试机制触发、失败原因分析
NotificationClaude 发送通知时桌面弹窗、音效提醒
StopClaude 完成一轮回复后自动保存、发送完成通知

类比：MCP 是给 Claude 装插件，Hooks 是给 Claude 装"自动触发器"——它做完某件事就自动帮你跑一段脚本。

3.2 配置方式

Hooks 写在 settings.json 的 hooks 字段，支持两个位置：

位置路径生效范围
项目级.claude/settings.json仅当前项目，可提交 Git
用户级~/.claude/settings.json所有项目

配置格式：

▼
json
复制代码
{
  "hooks": {
    "事件名": [
      {
        "matcher": "工具名正则",
        "hooks": [
          {
            "type": "command",
            "command": "要执行的 shell 命令"
          }
        ]
      }
    ]
  }
}

matcher 正则匹配规则详解：

matcher 用于精确控制 Hook 触发的工具范围，支持正则表达式：

模式含义示例
空字符串 ""匹配所有工具任何工具操作都触发
精确匹配工具名相同Write 仅匹配 Write 工具
竖线 |逻辑 OR，多个工具Write|Edit 同时匹配两个工具
.匹配任意单字符Wr.te 匹配 Write
^字符串开始^Bash$ 精确匹配 Bash，避免误匹配
$字符串末尾Tool$ 匹配以 Tool 结尾的工具

常见 matcher 模式示例：

▼
json
复制代码
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [{"type": "command", "command": "echo '任何工具都会触发'"}]
      },
      {
        "matcher": "Write",
        "hooks": [{"type": "command", "command": "echo '仅 Write 工具触发'"}]
      },
      {
        "matcher": "^Bash$",
        "hooks": [{"type": "command", "command": "echo '精确匹配 Bash，避免 BashScript 误触发'"}]
      },
      {
        "matcher": "Write|Edit",
        "hooks": [{"type": "command", "command": "prettier --write $CLAUDE_FILE_PATHS"}]
      },
      {
        "matcher": "Read.*",
        "hooks": [{"type": "command", "command": "echo 'Read 开头的工具'"}]
      }
    ]
  }
}

最佳实践：

  • 使用 ^精确匹配$ 避免正则范围过宽导致的意外触发
  • 在 PreToolUse 中用严格正则防御危险命令
  • PostToolUse 可用较宽松的正则（如 Write|Edit）

3.3 实战示例

**写完文件自动格式化（最常用）**提取路径 + 格式化文件

▼
json
复制代码
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs prettier --write"
          }
        ]
      }
    ]
  }
}

3.4 可用环境变量

Hook 脚本执行时，Claude 会注入以下变量：

变量含义示例值
$CLAUDE_TOOL_NAME当前调用的工具名Write
$CLAUDE_FILE_PATHS被操作的文件路径（空格分隔）src/app.ts src/utils.ts
$CLAUDE_PROJECT_DIR项目根目录/Users/me/project
$CLAUDE_TOOL_INPUT工具的完整输入（JSON）{"command":"ls -la"}

3.5 常用场景速查

场景事件工具 matcher脚本示意
保存后自动 prettierPostToolUseWrite|Editprettier --write $CLAUDE_FILE_PATHS
保存后自动 ESLintPostToolUseWrite|Editeslint --fix $CLAUDE_FILE_PATHS
写完跑单元测试PostToolUseWritenpm test -- --passWithNoTests
记录所有 Bash 命令PreToolUseBashecho $CLAUDE_TOOL_INPUT >> audit.log
完成后播放音效Stop（空）afplay /System/Library/Sounds/Glass.aiff
完成后桌面通知Stop（空）osascript -e 'display notification...'

注意：PreToolUse Hook 退出码为 2 时会阻止该工具调用，其余退出码不会阻断执行。

3.6 故障排查

现象原因解决方法
Hook 没有触发settings.json 路径或格式错误确认文件位置，JSON 格式用在线工具验证
脚本报"命令未找到"脚本用了 shell 别名或 PATH 不完整写完整路径，如 /usr/local/bin/prettier
PreToolUse 误拦截matcher 正则范围太宽精确化正则，如 ^Bash$ 而非 Bash
文件路径变量为空工具不涉及文件操作改用 $CLAUDE_TOOL_INPUT 获取完整输入

4. Subagent 子代理体系

4.1 Subagent 是什么

学完 MCP 和 Hooks，你已经能扩展 Claude 的能力边界——让它能调用外部服务、自动运行脚本。

但还有个更深的问题——一个 Claude 怎么同时精通 100+ 个专业领域？

Subagent（子代理）就是答案：Claude Code 通过 Task 工具启动的专业化 AI 代理，每个都是该领域的专家。

工具解决什么问题类比
MCP让 Claude 调用外部服务给 Claude 装"插件"
Hooks让 Claude 自动运行脚本给 Claude 设"自动触发器"
Subagent让 Claude 调动专家团队给 Claude 配"顾问团队"

Subagent 的核心优势

并行协作：同时启动多个专家代理，处理不同任务，效率翻倍。

▼
text
复制代码
单个 Claude 顺序处理：
  代码审查 → 性能优化 → 安全审计 → 文档生成（耗时）

多个 Subagent 并行处理：
  code-reviewer  ─────┐
  performance-pro ────┼──→ 同时并行，结果聚合（快速）
  security-auditor ───┤
  doc-writer  ────────┘

领域专业化：每个 Subagent 都是特定领域的深度专家，质量远高于通用 Claude。

按需扩展：100+ 专家代理库，你只需说一句话，Claude 自动调用最合适的专家。

⚠️ 重要提醒：使用多 Agent 并行调用的 token 消耗量巨大。每启动一个子代理都会消耗独立的上下文窗口。建议按需调用，不要一次性启动太多代理。

4.2 快速安装

方法一：交互式脚本安装（推荐）

▼
bash
复制代码
claude plugin marketplace add VoltAgent/awesome-claude-code-subagents

▼
text
复制代码
claude plugin install <plugin-name>

或者/plugin Installed界面自行安装

方法二：手动安装（完全控制）

  1. 确定存放路径：

    • 全局可用：~/.claude/agents/
    • 项目专用：.claude/agents/（项目根目录）

  2. 复制文件：从仓库的 categories/ 文件夹中找到你需要的 .md 代理定义文件，复制到上述路径即可。

验证安装：

▼
bash
复制代码
# 查看已启用的子代理
claude /agents

故障排查与相关截图：

如果是网络问题需要检查自己的代理软件（🪜）

可能安装过程需要代理软件，看自己的个人配置（自己的代理接口）或者手动安装

▼
text
复制代码
$env:HTTP_PROXY = "http://127.0.0.1:7897"
$env:HTTPS_PROXY = "http://127.0.0.1:7897"

4.3 /agents 交互式创建（从零搭建）

除了安装现成的代理库，你还可以用 /agents 命令从零创建自己的 Subagent——整个过程全程交互式引导，不需要手写任何配置文件。

第一步：输入 /agents

在 Claude Code 对话中输入 /agents，你会看到当前已有的代理列表，底部有 Create new agent 选项：

第二步：选择存放位置

选项说明适合场景
Project (.claude/agents/)仅当前项目可用项目专用代理
Personal (~/.claude/agents/)全局可用通用代理，跨项目复用

image.png

第三步：选择创建方式

方式说明适合
Generate with Claude（推荐）你只需描述需求，Claude 自动生成完整配置新手首选
Manual configuration手动填写每个字段需要精确控制的场景

第四步：描述代理职责

用自然语言描述这个代理应该做什么、什么时候被调用。写得越详细，生成效果越好：

▼
text
复制代码
这是一个用于代码审核的 SubAgent。在用户要求"代码审核"的时候调用它。

第五步：等待 Claude 生成

Claude 会根据你的描述自动生成代理的名称、系统提示词、工具选择等配置：

第六步：选择工具权限

选择这个代理可以使用哪些工具。根据代理职责按需勾选：

工具类别包含工具说明
Read-only toolsGlob、Grep、Read 等只读，安全无副作用
Edit toolsEdit、Write 等可修改文件
Execution toolsBash 等可执行命令
MCP tools已配置的 MCP 服务调用外部服务

第七步：选择模型

模型特点建议场景
Sonnet性能均衡，速度与质量兼顾日常代理首选
Opus最强推理能力，成本最高复杂架构 / 深度分析
Haiku速度快、成本低简单任务 / 批量处理
Inherit from parent继承主会话模型跟随当前设置

第八步：选择颜色标识

给代理设置一个背景色，方便在会话中一眼识别它的输出（比如代码审核用绿色、安全审计用红色）。

第九步：配置记忆

选项说明建议
Enable (.claude/agent-memory/)项目级记忆，代理会记住历史上下文推荐
None无持久记忆一次性任务
User scope全局记忆（~/.claude/agent-memory/）跨项目通用代理
Local scope本地记忆，不提交 Git含敏感信息的场景

第十步：确认保存

最终会展示代理的完整配置，确认无误后按 s 或 Enter 保存：

▼
text
复制代码
Name:        code-reviewer
Location:    .claude/agents/code-reviewer.md
Tools:       Glob, Grep, Read, WebFetch, WebSearch
Model:       Sonnet
Memory:      Project (.claude/agent-memory/)

Description: Use this agent when the user explicitly requests a
             '代码审核' (code review), '审查代码', '检查代码'...

System prompt:
你是一位资深代码审核专家，拥有超过15年的软件工程经验，
精通多种编程语言和架构模式...

实战调用

保存完成后，直接在对话里说 "给我做下代码审核"——Claude 会自动识别并调用刚刚创建的 code-reviewer 代理。

你会看到绿色标识，表示 Subagent 正在独立执行审核任务：

审核完成后，代理会返回完整的审核报告，收工：

凯神提醒：/agents 交互式创建是目前最推荐的方式——不需要手写 .md 文件，Claude 帮你自动生成完整配置（名称、描述、系统提示词、工具权限全都有），新手 2 分钟就能搞定一个专属代理。

4.4 代理目录总览

VoltAgent 提供的 10 大类专家代理（100+ 代理），按需安装：

1️⃣ 核心开发 (Core Development)

api-designer / backend-developer / electron-pro / frontend-developer / fullstack-developer / graphql-architect / microservices-architect / mobile-developer / ui-designer / websocket-engineer / wordpress-master

2️⃣ 语言专家 (Language Specialists)

typescript-pro / python-pro / rust-engineer / golang-pro / java-architect / javascript-pro / react-expert / vue-expert / angular-architect / nextjs-developer / swift-expert / kotlin-expert / cpp-pro / csharp-developer / php-pro / sql-pro / django-developer / laravel-expert / rails-expert / spring-boot-engineer / flutter-expert / elixir-expert / dotnet-core-expert / powershell-pro

3️⃣ 基础设施 (Infrastructure)

cloud-architect / devops-engineer / kubernetes-expert / terraform-engineer / database-admin / sre / deployment-engineer / azure-infra-engineer / network-engineer / platform-engineer / security-engineer / incident-responder / windows-infra-admin

4️⃣ 质量与安全 (Quality & Security)

code-reviewer / security-auditor / qa-automation-engineer / performance-engineer / debugging-expert / error-detective / penetration-tester / architecture-reviewer / accessibility-tester / chaos-engineer / compliance-auditor / testing-automation-expert

5️⃣ 数据与人工智能 (Data & AI)

ai-engineer / llm-architect / ml-engineer / data-engineer / data-scientist / data-analyst / database-optimizer / postgres-pro / mlops-engineer / nlp-engineer / prompt-engineer

6️⃣ 开发者体验 (Developer Experience)

refactoring-expert / documentation-engineer / git-workflow-manager / legacy-code-modernizer / mcp-developer / build-engineer / cli-developer / dependency-manager / dx-optimizer / tooling-engineer

7️⃣ 专业领域 (Specialized Domains)

blockchain-developer / game-developer / fintech-engineer / iot-engineer / embedded-systems-engineer / api-documenter / seo-specialist / mobile-app-developer / m365-admin

8️⃣ 业务与产品 (Business & Product)

product-manager / business-analyst / project-manager / scrum-master / technical-writer / ux-researcher / customer-success-manager / sales-engineer / legal-advisor / content-marketing-specialist

9️⃣ 元数据与编排 (Meta & Orchestration)

multi-agent-coordinator / workflow-orchestrator / agent-organizer / agent-installer / context-manager / task-dispatcher / error-coordinator / performance-monitor / knowledge-synthesizer / it-ops-orchestrator

推荐新手起点：

  • code-reviewer（代码审查）
  • debugging-expert（调试）
  • refactoring-expert（重构）
  • documentation-engineer（文档）

4.5 并行调用多个专家

自动识别调用

当你的描述符合某个子代理的专业领域时，Claude 会自动调用对应的专家：

▼
text
复制代码
你：这段代码有性能问题
Claude：[自动识别] 调用 performance-engineer 代理...
        基于性能优化的最佳实践，我来分析瓶颈...

你：帮我检查代码质量
Claude：[自动识别] 调用 code-reviewer 代理...
        我注意到以下代码质量问题...

显式调用多个专家

对于复杂任务，显式并行调用多个专家：

▼
text
复制代码
并行调用各个专家查看/解决 XXXX 问题

需要：
- code-reviewer 检查代码质量
- performance-engineer 分析性能
- security-auditor 审计安全漏洞

Claude 会同时启动 3 个子代理，返回综合报告。

常见场景示例

场景调用代理效果
代码审查code-reviewer快速找出质量问题
性能优化performance-engineer + database-optimizer全面分析瓶颈
安全审计security-auditor + penetration-tester深度安全检查
新项目启动architecture-reviewer + project-manager + tech-writer快速生成架构文档
重构遗留代码legacy-code-modernizer + refactoring-expert系统现代化
API 设计api-designer + api-documenter完整的设计方案

4.6 故障排查

现象原因解决方法
/agents 看不到任何代理安装路径错误或仓库未克隆确认代理文件在 ~/.claude/agents/ 或 .claude/agents/
代理安装成功但不被调用Subagent 定义文件格式错误检查 .md 文件的 frontmatter 格式
并行调用代理导致超时启动的代理太多，超过 token 限制减少并行代理数量，改为分批调用
代理返回结果不符合预期代理描述匹配度不高在调用时更明确地说明需求，或显式指定代理
Token 消耗过多每个子代理都有独立上下文按需调用，避免一次性启动太多代理

5. 总结

本章你已掌握：

  1. MCP 本质：AI 连接外部工具的 USB 标准，.mcp.json 配置，npx 启动
  2. 常用服务器：filesystem / github / sqlite / context7 等 10 个主流 Server 速查
  3. 三大作用域：Local（私密）> Project（团队）> User（全局），按需选择
  4. Commands 联动：mcp__服务器名__工具名 在 Commands 中直接调用 MCP
  5. Hooks 本质：事件驱动的 shell 脚本，PreToolUse / PostToolUse / Stop 三大时机
  6. Hooks 实战：自动格式化、安全日志、完成通知，一次配置永久生效
  7. Subagent 本质：Claude 调动的专家团队，100+ 代理库，按需并行协作
  8. /agents 创建：交互式引导从零搭建专属代理，2 分钟完成，不需手写配置
  9. Subagent 实战：快速安装、自动识别、显式并行调用，提升开发效率 10 倍

6. 参考资料

MCP 相关资源

Hooks 相关资源

Subagent 相关资源

下一步学习

章节主题你将学到
第05章Skills 定制——给Claude装上专属能力包Skill 开发、自动激活机制、复杂提示词组织
第06章CLAUDE.md 完整配置指南项目规范管理、长期记忆维护、团队协作
第07章Plugins 生态完整指南插件安装、配置与自定义开发

作者简介：一名正在实习的Java开发工程师，热爱技术分享，专注于性能优化和系统架构设计。

觉得有用的话可以点点赞 (/ω＼)，支持一下。

如果愿意的话关注一下。会对你有更多的帮助。

每周都会不定时更新哦 >人< 。

版权声明：本文为原创技术文章，转载请注明出处。

AI
文档
笔记

相关专栏

ClaudeCode实战指南

ClaudeCode实战指南

ClaudeCode实战指南

0个评论
全部评论
点击登录，快来和大家讨论吧～
表情
图片
暂无评论
lenyan
lenyan
等级vip
内容推荐
更多
智能协同云图库-进入编辑报错解决
4
27 岁，我终于做出了自己的游戏！但是一行代码都没写
5
最近在使用ChatGPT/Codex过程中发现了一个官方bug：高频日志写盘，会损坏电脑磁盘的寿命。桌面版和CLI都有这个问题，目前最新版的ChatGPT/Codex还没有彻底解决这个问题（虽然官方自称已经修复了，但实测还是有高频日志写盘问题）。建议使用下面这段提示词发给AI让它检查和修复：帮我检查 ~./codex/logs_2.sqlite 是否因 TRACE 日志持续高频写盘；如果中招，先备
2
codex
2
#字节内推# 实习、校招、社招均有岗位
4
作者分享
更多
CloudCLI：将AI编程助手带入图形界面的革命性工具
5
Claude Code凯神实战指南 - 第八章：企业深水区——密钥安全、团队配置与合规审计全攻略
6
Claude Code凯神实战指南 - 第七章：从单兵到团队——企业级协作规范、CI/CD 与安全合规实战
7
Claude Code凯神实战指南 - 第六章：Plugins全攻略——一键安装海量扩展，还能自己造轮子
7
Claude Code凯神实战指南 - 第五章：Skills定制——给Claude装上专属能力包
6
下载 APP