智能构建：子代理、钩子与输出样式

除了简单的聊天，Claude Code 还提供了一个强大的工具集，用于构建健壮、智能的自动化。在这里，您将从用户晋升为创造者。在本章中，我们将探讨三个基本构建模块，它们允许您自定义、扩展和控制 Claude Code 的行为：子代理 (Subagents)、钩子 (Hooks) 和输出样式 (Output Styles)。

子代理 (Subagents)：您的专业 AI 团队

想象您正在管理一个软件项目。您不会要求一个开发人员同时精通数据库管理、前端设计和网络安全。相反，您会组建一个专家团队。这正是 Claude Code 中“子代理 (Subagents)”的作用。

子代理 (Subagent) 是您为特定任务定义的专业 AI 代理。它有自己的系统 prompt (提示)、自己允许的工具集和自己的上下文窗口 (context window)。当主要的 Claude Code 代理遇到一个与子代理专业领域匹配的任务时，它可以将该任务委托给这位专家。

您可以在用户级别 (~/.claude/agents/) 创建子代理，使其在任何地方都可用；也可以在项目级别 (.claude/agents/) 创建，以便与团队共享。它们被定义为带有 YAML frontmatter 的 Markdown 文件。

---
description: A subagent that reviews code for quality, style, and potential bugs.
allowedTools:
  - Read
  - Grep
---

You are an expert code reviewer. Your task is to analyze the provided code files. Look for violations of the project's style guide (PEP8 for Python), identify potential bugs, and suggest improvements for clarity and performance. Do not suggest adding new features.

在项目中有了这个文件，您现在就可以调用它了。如果您的 prompt (提示) 足够具体（例如 > review my recent code for style issues），Claude Code 可能会自动委托；您也可以明确请求它（例如 > use the code-reviewer subagent to check the auth module）。

钩子 (Hooks)：触发自定义操作

如果说子代理 (Subagents) 是您的专家，那么“钩子 (Hooks)”就是自动化流程，确保规则得到遵守，工作流保持一致。钩子是您可以配置在 Claude Code 执行生命周期中的特定点运行的自定义 shell 命令。它们为您提供了对代理行为的确定性控制。

这对于强制执行项目标准、与其他工具集成或添加自定义验证步骤来说非常强大。钩子在您的 settings.json 文件中配置。

以下是一些您可以插入钩子的关键事件：

PreToolUse：在工具（如 Write 或 Bash）使用之前运行。非常适合进行验证步骤。如果您的脚本返回非零退出代码，您甚至可以阻止工具的使用。
PostToolUse：在工具使用之后运行。非常适合记录操作或在文件写入后运行代码格式化程序/Linter。
UserPromptSubmit：在您提交 prompt (提示) 后立即运行，但在 Claude 看到它之前。您可以使用此功能注入额外上下文或验证 prompt。
Stop：当代理完成其响应时运行。

{
  "hooks": [
    {
      "event": "PostToolUse",
      "tool": "Write",
      "pattern": "\\.py$",
      "hook": "black $CLAUDE_CODE_TOOL_ARG_PATH"
    }
  ]
}

在此示例中，我们设置了一个 PostToolUse 钩子。每当 Claude Code 对以 .py 结尾的文件使用 Write 工具时，此钩子将自动在该文件上运行 black 代码格式化程序。这确保了所有生成的 Python 代码都遵循项目标准，而无需您或 AI 记住。

输出样式 (Output Styles)：控制呈现方式

您接收信息的方式与信息本身同样重要。Claude Code 提供了不同的“输出样式 (Output Styles)”，主要用于无头 (headless) 或脚本化使用，以确保您可以轻松解析和利用其响应。

在非交互模式下运行（-p 或 --print）时，您可以使用 --output-format 标志指定输出格式。

text (默认)：这提供标准的、人类可读的文本输出，类似于您在交互模式中看到的内容。
json：这种样式将整个响应格式化为单个 JSON 对象。这非常适合编程使用，因为您可以使用 jq 等工具轻松解析结果、成本、token 计数和其他元数据。
stream-json：对于实时应用程序，这种样式将对话作为一系列 JSON 对象流式传输，每个消息回合一个。这允许您在对话发生时处理它。

# Get a standard text response
claude -p "what is the capital of France?"

# Get the response as a single, parsable JSON object
claude -p "write a python function to add two numbers" --output-format json

# Get a stream of JSON objects representing the conversation
claude -p "build a simple web server in node.js" --output-format stream-json

通过掌握子代理 (Subagents)、钩子 (Hooks) 和输出样式 (Output Styles)，您可以将 Claude Code 从一个有用的助手转变为在您的开发生命周期中实现智能自动化的完全集成和定制的引擎。