Hooks 是 Claude Code 的事件系统—— 你可以在特定时机（工具调用前、调用后、会话开始、会话结束等）自动执行脚本。 最常见的用途：阻止危险命令、记录操作日志、注入安全检查。

Hook 事件类型

配置格式

Hooks 在 settings.json 中配置，三层嵌套：事件 → 匹配器 → 处理器。

// .claude/settings.json 或 .claude/settings.local.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",          // 匹配 Bash 工具
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/validate.sh"
          }
        ]
      }
    ]
  }
}

实战: 阻止危险的 rm -rf 命令

#!/bin/bash  —  .claude/hooks/block-rm.sh
# 从 stdin 读取 JSON 输入
COMMAND=$(jq -r '.tool_input.command' < /dev/stdin)

if echo "$COMMAND" | grep -q 'rm -rf'; then
  # 返回 JSON 阻止执行
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "rm -rf 已被 Hook 策略阻止"
    }
  }'
else
  # exit 0 + 无输出 = 允许继续
  exit 0
fi

Hook 处理器类型

Hook 的输入与输出

Skills（前身是 Custom Commands）让你把多步操作封装成 /command。 一个 Markdown 文件就是一个 Skill—— 定义 Claude 应该做什么、能用哪些工具、接受什么参数。 在 / 菜单中选择，一键执行。

创建你的第一个 Skill

# 创建 Skill 目录和文件
$ mkdir -p .claude/skills/fix-issue
$ cat > .claude/skills/fix-issue/SKILL.md << 'EOF'
---
name: fix-issue
description: 从 GitHub Issue 获取描述并修复
argument-hint: [issue-number]
arguments: [issue_number]
allowed-tools: Read Grep Glob Bash(gh *) Edit
---

## 上下文
- Issue 详情: !`gh issue view $issue_number`

## 任务
1. 阅读上面的 Issue 描述，理解要修复的问题
2. 用 Grep 和 Read 在代码中定位相关文件
3. 实现修复
4. 运行测试确认修复正确
5. 提交代码并在 commit message 中关联 Issue #$issue_number
EOF

# 使用: 在 Claude Code 中输入
> /fix-issue 42

Skill 文件结构

动态上下文注入

用 !`command` 语法在 Skill 加载时自动执行 shell 命令，将结果注入 Claude 的上下文：

# .claude/skills/pr-review/SKILL.md
---
name: pr-review
description: 审查当前分支的 PR
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## PR 上下文
- PR diff: !`gh pr diff`
- PR 评论: !`gh pr view --comments`
- 变更文件: !`gh pr diff --name-only`

## 审查要求
1. 检查安全漏洞 (OWASP Top 10)
2. 检查性能反模式
3. 检查代码风格一致性
4. 给出改进建议

Skill 存放位置

MCP（Model Context Protocol）让 Claude Code突破本地文件系统的边界—— 直接查询数据库、读取 Issue Tracker、调用 Sentry 错误监控、 甚至连接 Figma 获取设计稿。所有交互使用自然语言，不需要你写胶水代码。

添加 MCP 服务器

# 方式 1: HTTP 远程服务器
$ claude mcp add --transport http github \
    https://api.githubcopilot.com/mcp/ \
    --header "Authorization: Bearer $GITHUB_TOKEN"

# 方式 2: 本地 stdio 服务器
$ claude mcp add --transport stdio database \
    -- npx -y @bytebase/dbhub \
    --dsn "postgresql://readonly:pass@host:5432/mydb"

# 方式 3: 带 OAuth 认证的服务
$ claude mcp add --transport http sentry \
    https://mcp.sentry.dev/mcp
# 然后在 Claude Code 中用 /mcp 完成 OAuth 登录

# 查看已配置的服务器
$ claude mcp list

# 在 Claude Code 中检查状态
> /mcp

.mcp.json 配置文件

// 项目根目录 .mcp.json — 团队共享
{
  "mcpServers": {
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub"],
      "env": {
        "DB_DSN": "${DATABASE_URL}"      // 支持环境变量展开
      }
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    }
  }
}

MCP 使用场景

理解 Claude Code 的配置层级是正确使用 Hooks/Skills/MCP 的前提—— 在哪里配置决定了谁受影响、能否被覆盖。

配置优先级（从高到低）

实战: 团队安全策略编排

// .claude/settings.json — 团队共享安全策略
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "if": "Bash(rm *)",
          "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
        }]
      },
      {
        "matcher": "Write",
        "hooks": [{
          "type": "command",
          "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-write.sh"
        }]
      }
    ],
    "Stop": [
      {
        "hooks": [{
          "type": "command",
          "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/auto-lint.sh"
        }]
      }
    ]
  },
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(npx vitest *)"]
  }
}

Hooks、Skills 和 MCP 不是孤立的—— 它们组合在一起就是一个可编程的自动化 pipeline。

组合示例: 自动化 Bug 修复流水线

# Skill: /fix-sentry — 从 Sentry 获取错误并自动修复
---
name: fix-sentry
description: 从 Sentry 获取最新错误并修复
allowed-tools: Read Grep Glob Edit Bash(npm test *)
---

## Sentry 上下文
最新错误列表: !`claude mcp call sentry get_issues --limit 5`

## 工作流
1. 阅读错误详情，找到堆栈中的源文件和行号
2. Read 对应源文件，分析根因
3. Edit 修复代码
4. 运行测试确认修复
5. 为此 Bug 写一个回归测试
6. 提交代码，commit message 关联 Sentry Issue ID

# 配合 Hook: 修复后自动通知 Slack
# settings.json 中添加 PostToolUse Hook
# 当 Bash(git commit) 执行成功后，发送 Webhook 到 Slack

更多编排模式

今天的练习会修改你项目的 .claude/ 目录。 如果你还没有这个目录，Claude Code 已经在首次运行时创建过了。

Lab 1 — 创建一个 PreToolUse Hook

写一个 Hook，在 Claude 执行任何 Bash 命令时记录日志。

# 创建 hook 脚本
$ mkdir -p .claude/hooks
$ cat > .claude/hooks/log-bash.sh << 'EOF'
#!/bin/bash
INPUT=$(cat /dev/stdin)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // "unknown"')
TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
echo "$TIMESTAMP | BASH | $COMMAND" >> .claude/hooks/audit.log
EOF
$ chmod +x .claude/hooks/log-bash.sh

# 在 settings.local.json 中配置
# 让 Claude 帮你配:
> 在 .claude/settings.local.json 中添加一个 PreToolUse Hook，
> 匹配 Bash 工具，执行 .claude/hooks/log-bash.sh

# 然后执行一些操作，检查日志
> 运行 ls 命令
$ cat .claude/hooks/audit.log

Lab 2 — 创建一个自定义 Skill

创建一个 /explain 命令，让 Claude 用大白话解释一个函数。

# 创建 Skill
$ mkdir -p .claude/skills/explain
$ cat > .claude/skills/explain/SKILL.md << 'EOF'
---
name: explain
description: 用大白话解释一个函数或文件
argument-hint: [file-path]
arguments: [path]
allowed-tools: Read Grep
---

## 任务
读取 $path 文件的内容，然后:
1. 用一句话总结这个文件/函数的目的
2. 列出输入和输出
3. 解释核心逻辑（用非技术人员能理解的语言）
4. 指出可能的坑（边界条件、隐含假设）
EOF

# 使用
> /explain src/utils/parseCSV.ts

Lab 3 — 配置 MCP 服务器 (可选)

如果你有 GitHub Token，可以尝试添加 GitHub MCP 服务器。

# 添加 GitHub MCP (需要 GITHUB_TOKEN 环境变量)
$ claude mcp add --transport http github \
    https://api.githubcopilot.com/mcp/ \
    --header "Authorization: Bearer $GITHUB_TOKEN"

# 检查连接状态
> /mcp

# 如果连接成功，尝试:
> 列出这个仓库最近的 5 个 Issue
> 读一下 Issue #1 的内容

Lab 4 — 查看现有配置

# 用 /hooks 查看所有活跃的 hooks
> /hooks

# 用 /mcp 查看所有 MCP 服务器状态
> /mcp

# 让 Claude 解释你的配置
> 读一下 .claude/settings.json 和 .claude/settings.local.json
> 告诉我当前配置了哪些 hook 和权限

1. PreToolUse Hook 的输入和输出格式是什么？exit code 0 和 exit code 2 分别代表什么？
2. Skill 的 !`command` 语法有什么作用？为什么它比在 Skill 里让 Claude 运行命令更好？
3. MCP 服务器的三个 scope 分别存放在哪里？什么类型的配置应该放在哪个 scope？
4. 配置优先级从高到低是什么？如果 project settings 和 local settings 有冲突，谁赢？
5. 描述一个结合 Hook + Skill + MCP 的工作流编排场景，说明每个组件各自负责什么。