aaihubhub
← 文章库
Claude Code 小白进阶课：从第一次对话到可靠协作 · 第 10 课 / 共 20 课 ↗ AI 教程

10｜Hooks：在关键动作前后自动执行规则

配置工具前后、会话与通知 Hooks，并测试触发结果。

kimi
LESSON BRIEFING10 / 20

配置工具前后、会话与通知 Hooks，并测试触发结果。

全科医生不会把所有器械同时铺在桌上。遇到骨折才打开骨科工具箱，先读操作规程，再使用夹板和影像。Skill 也是按任务触发的专业包：说明书决定何时用、如何用、如何验收。

本课交付物

设计一个“Markdown 文章质检”Skill：写清触发条件、必读规则、检查步骤、输出格式与停止条件；用一篇故意缺标题层级的文章验证。

核心讲解

Hooks 是在 Claude Code 事件发生时自动执行的 shell 命令，用来做格式化、校验、通知、审计等自动化工作。

概览

Hooks 是事件驱动的自动化机制。它们会在 Claude Code 发生某些动作时自动运行，不需要你手动触发。

常见用途：

  • 写文件前自动格式化
  • 提交前运行测试
  • 扫描安全问题
  • 记录 bash 命令
  • 校验用户提示词
  • 发送团队通知

Hook 类型

Claude Code 提供 4 类、25 个事件：

  • Tool Hooks：PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest
  • Session Hooks：SessionStart、SessionEnd、Stop、StopFailure、SubagentStart、SubagentStop
  • Task Hooks：UserPromptSubmit、TaskCompleted、TaskCreated、TeammateIdle
  • Lifecycle Hooks：ConfigChange、CwdChanged、FileChanged、PreCompact、PostCompact、WorktreeCreate、WorktreeRemove、Notification、InstructionsLoaded、Elicitation、ElicitationResult

安装

mkdir -p ~/.claude/hooks
cp 06-hooks/*.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

然后在 ~/.claude/settings.json 里配置：

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": ["~/.claude/hooks/format-code.sh"]
    }],
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": ["~/.claude/hooks/security-scan.sh"]
    }]
  }
}

使用方法

Hooks 会在匹配到事件时自动执行。你可以把它理解成 Claude Code 的事件回调。

常见示例

  • format-code.sh - 写入前自动格式化
  • pre-commit.sh - 提交前跑测试
  • security-scan.sh - 做安全扫描
  • log-bash.sh - 记录 bash 命令
  • validate-prompt.sh - 校验输入
  • notify-team.sh - 发通知

最佳实践

  • 把 hooks 保持短小明确
  • 只做单一职责
  • 先在本地测试
  • 不要在 hook 里放复杂业务逻辑
  • 对副作用保持谨慎

故障排查

  • 检查文件路径和权限
  • 确认脚本可执行
  • 检查 settings.json 语法
  • 查看 Claude Code 版本兼容性

相关概念

  • Checkpoints and Rewind
  • Slash Commands
  • Skills
  • Subagents
  • Plugins
  • Advanced Features

更多资源

本站实战工作台

Skill 是带说明书的专业工具箱

一个 Skill 不只是长提示词。它定义何时触发、必须读取什么、允许调用哪些工具、按什么顺序工作、怎样验证、遇到什么情况停止。它把领域判断和可复用资产放在一起，让 Agent 不必每次从零发明流程。

以 Markdown 文章质检为例，Skill 可以包含标题层级规则、链接检查脚本、报告模板和一篇故意损坏的样例。触发描述必须足够窄：用户要求审查 Markdown 结构时使用，而不是任何写作任务都加载。

最小目录

markdown-quality/
├── SKILL.md
├── scripts/check-headings.mjs
├── references/style-guide.md
└── assets/report-template.md

SKILL.md 是路由与工作流，不应复制所有参考资料。主说明必须完整阅读；额外资料按任务需要加载。脚本适合确定性检查，模型适合解释语义问题，两者不要互相替代。

写清触发与不触发

描述中同时给正例和边界：审查标题层级、断链、代码围栏时触发；仅翻译文案、写社交标题时不触发。触发太宽会污染上下文，太窄则永远用不上。

设计一条可验证工作流

先发现 Markdown 文件与项目规则；再运行确定性扫描；然后人工语义审查标题是否表达内容；最后按严重级别输出路径、行号、原因和建议。禁止自动重写全文，除非用户明确要求修复。

停止条件也要写：文件缺失时请求位置；规则冲突时展示证据；脚本失败两次后报告阻塞，不循环安装工具。

用坏样例测试，而不是用完美样例展示

准备一篇包含跳级标题、重复 H1、未闭合围栏、空链接文字和超长段落的文档。记录 Skill 找到哪些、漏掉哪些、是否出现误报。再用一篇合法但结构特殊的文档检查它是否过度纠正。

安全与许可证

安装第三方 Skill 前检查来源、许可证、脚本和网络行为。Skill 是可执行能力，不是普通提示词收藏。不要让说明诱导读取密钥、扩大权限或把用户内容上传到未授权服务。复制模板进入产品时，按许可证保留必要通知。

本课交付

完成一个可安装的 markdown-quality Skill、两份测试文档和 evaluation.md。报告要区分脚本发现与模型判断，并列出已知盲区。真正的复用不是“每次输出长得一样”，而是每次都遵循同一质量方法，同时尊重当前内容的差异。