Claude Code 高级教程：CLAUDE.md、Skills、Hooks、Subagent 到底怎么用？

Rules

Rules 是位于 .claude/rules/ 中的 Markdown 文件，用于向 Claude 提供特定的约束或约定。

未限定作用域的 Rules 与 CLAUDE.md 类似：它们始终会在会话开始时加载，并在压缩时重新注入。即使这些 Context 与当前任务无关，也会被加载，从而浪费 Token。

限定路径作用域的 Rules 允许你添加一个 paths 字段来控制其加载时机，使规则指令仅在相关时才被加载。

例如：作用域限定为 src/api/** 的规则不会在仅处理文档的会话中进入 Context。只有当 Claude 读取 src/api/ 目录中的文件时，它才会被加载。

具体如下：

---
paths:
  - "src/api/**"
  - "**/*.handler.ts"
---
All API handlers must validate input with Zod before processing.

提示：像“迁移只能追加”这种针对特定文件的约束，最适合作为 Rule 放在你的 paths: frontmatter 中。当指令涉及横切关注点，或涉及出现在代码库多个位置（但并非所有位置）的文件时，应优先使用限定路径作用域的 Rule，而不是嵌套的 CLAUDE.md 文件。

Skills

Skills 以指令、脚本和资源文件夹的形式位于 .claude/skills/ 中，由 Claude 动态加载。每个 Skill 都有一个 SKILL.md 文件，其中包含名称、描述和正文。

会话开始时只加载名称和描述；当 Claude 调用该 Skill 时，才会加载完整正文。调用可以通过斜杠命令（/code-review），也可以通过自动匹配任务触发。

Skills 通过你的系统 Prompt 触发。

例如，/code-review 是一个内置 Skill，它会审查你当前的 diff 并报告发现的问题，但不会编辑文件。该 Skill 定义了一套执行流程，因此每次调用时，Claude 都会采用相同的结构化方法。

压缩时，Claude Code 会在所有已调用 Skills 的总预算范围内重新注入这些 Skills。如果你在一次会话中调用了很多 Skills，最早调用的会优先被移除。

提示： 部署工作流、发布检查清单或审查流程等程序性指令应放在 Skill 中，而不是 CLAUDE.md 中。

Claude Code 自带一些 Skills，但你也可以编写自己的自定义 Skills。我们的构建 Claude Skills 完整指南会告诉你具体方法。

Subagent

Subagent 是位于 .claude/agents/ 中的 Markdown 文件，用来定义执行特定旁支任务的隔离式助手。每个文件先使用 YAML frontmatter（名称、描述，以及可选的模型和工具访问字段），之后的正文会成为该 Subagent 的系统 Prompt。

Subagent 与 Skill 类似：会话开始时会加载名称、描述和工具列表，但 Agent 正文中更大规模的 Context 不会被自动调用。Claude 会通过 Agent 工具调用它们，并传入一个 Prompt 字符串。

Claude Code 的 Context window 包含 Claude 掌握的所有会话信息。这里的交互式时间线会展示各类内容何时加载。

Subagent 正文中规模较大的指令 Context 不仅不会被自动调用，而且根本不会进入父对话。

随后，Subagent 会在自己全新的 Context window 中运行，返回主会话的只有 Subagent 的最终消息（通常是许多子任务的汇总结果）以及元数据。

这种模式能够规模化扩展：Subagent 最多可以嵌套五层，而动态工作流可以编排数十乃至数百个后台 Agent，无需你逐一指定 Subagent 架构的每个细节。编排计划和中间结果保存在脚本变量中，而不是 Claude 的 Context window 中，因此可以在不损失指令保真度的前提下实现规模化扩展。

提示： 这种隔离性正是选择 Subagent 而不是 Skill 的主要原因之一。当深度搜索、日志分析或依赖审计等旁支任务产生的中间结果会弄乱主对话，而且之后不会再引用这些结果时，请使用 Subagent。如果你希望某个流程在主线程内执行，以便查看并引导每一步，请使用 Skill。

Hooks

Hooks 是用户定义的命令、HTTP 端点或 LLM Prompt。它们会在 Claude 生命周期中的特定事件发生时触发，例如编辑文件、调用工具或启动会话，从而对 Claude 的行为提供更具确定性的控制。

Claude Code 会话中可以触发 Hook 的事件图。

你可以在 settings.json、托管策略设置或 Skill/Agent 的 frontmatter 中注册 Hooks。

Hooks 有多种类型：command、HTTP、mcp_tool、prompt 和 agent。所有 Hooks 都会被确定性地触发。前三种会以确定性方式执行；后两种 prompt 和 agent 则依靠 Claude 的判断，而不是一套规则来决定输出。

Hooks 的 Context 成本很低，因为配置或指令位于主 Context window 之外。根据 Hook 类型，运行框架会执行处理程序（command、http、mcp_tool），或使用独立窗口发起模型调用（prompt、agent）。

某些 Hooks 的输出可能会被保存到主 Context window 中。例如，阻塞型 Hook 的标准错误会被保存在 Context 中，让 Claude 知道调用被拒绝的原因。

但除非配置明确返回输出，否则大多数 Hooks 的输出不会保存到主窗口中。如果你在压缩前使用 PreCompact 事件将聊天记录备份到另一个文件以供日后参考，Claude 并不会知道聊天记录保存在哪个文件里。

这使得这些 Hook 类型与 CLAUDE.md、Rules 和 Skills 有着根本区别。你可以在我们的文章如何配置 Hooks中了解更多信息。

提示： 凡是应该确定性执行的操作，都应使用 Hooks，例如在编辑后运行 linter、完成后发布到 Slack，或者在特定命令执行前将其阻止。PreToolUse Hook 可以检查任意工具调用，并以退出码 2 拒绝该调用。

Hooks 的 Context 成本很低，因为它们是由运行框架执行的代码，而不是加载到 Context 中供 Claude 遵循的指令。Skills 和 Hooks 也是设计 Agent 循环的基本构件——这种重复工作流会持续运行，直至满足停止条件。

输出样式

输出样式是位于 .claude/output-styles/ 中的文件，用于将指令注入系统 Prompt。它们绝不会被压缩，会在每次会话开始时加载，并在会话内首次请求后被缓存，因此具有中等程度的 Context 成本。

由于输出样式位于系统 Prompt 中，它们在目前介绍的所有方法中具有最高的指令遵循权重，因此应谨慎使用。

更改输出样式将替换默认输出样式（除非你在该样式的 frontmatter 中设置 keep-coding-instructions: true）。

在 Claude Code 中，这会移除那些要求 Claude 帮助用户处理软件工程任务的指令，以及其他关键的默认指令，例如：

• 如何界定变更范围；
• 何时添加或省略代码注释；
• 如何处理安全问题；以及
• 在宣告工作完成前运行测试等验证习惯。

默认情况下，自定义输出样式会移除所有这些内容，Claude Code 将更像是一个通用助手，而不是软件工程助手。

提示：在编写自定义输出样式之前，请先查看内置样式。Proactive、Explanatory 和 Learning 覆盖了最常见的需求（自主执行、教学模式和协作式编码），而且无需你维护样式文件。

追加系统 Prompt

修改输出样式的另一种选择是使用 append-system-prompt 标志。修改输出样式文件可能会给 Claude 的行为带来大范围的意外变化，而追加标志只会在原有系统 Prompt 的基础上添加内容。它不会修改 Claude 的角色，只会为其默认角色添加指令。

它也是在调用时传入的，并且只对当次调用生效，而不会作为文件跨会话持久保存。

与其他传递指令的方法相比，追加系统 Prompt 可能具有更高的 Context 成本。它会增加输入 Token，不过 Prompt 缓存会在会话中的首次请求之后降低这项成本。要求 Claude 采用更详细或更长的表达风格也会增加输出 Token。

提示： 追加系统 Prompt 最适合添加特定编码标准、输出格式要求或特定领域知识。请记住，通过追加系统 Prompt 来提高指令遵循度的收益会逐渐递减。一般而言，使用这种方法提供的指令越多，Claude 遵循这些指令的严格程度就越低，尤其是在指令之间存在冲突时。

每种方法的适用场景

如果你发现自己在做以下事情之一，可能需要考虑将指令放到其他位置：

在 CLAUDE.md 中写“每次发生 X 时，始终执行 Y”。 如果某个行为必须可靠发生，例如每次编辑后运行 prettier，或完成后发布到 Slack，请改用 settings.json 中的 Hook。让模型选择运行格式化工具，与格式化工具自动运行并不是一回事。

在 CLAUDE.md 中写“绝不要这样做”。 当某件事情绝对不能发生时，指令并不是合适的工具。Claude 在大多数情况下都会遵循指令，但在压力之下、长会话或情况模糊时，或者由于任务过程中访问的文件包含 Prompt injection，模型可能无法遵守通过 Prompt 提供的规则。真正的防护措施必须具有确定性，可用于强制执行的方法是 Hooks 和权限。PreToolUse Hook 可以检查调用，并以退出码 2 将其阻止。托管设置则更进一步：它们由管理员部署，无法被用户的本地配置覆盖，也是强制实施确定性组织级防护措施的唯一方式。

在 CLAUDE.md 中写 30 行的流程。 流程应放在 Skills 中。CLAUDE.md 用于存放 Claude 应始终掌握的事实：构建命令、monorepo 布局和团队约定。部署运行手册或安全审查检查清单应放在 .claude/skills/ 中，使其正文只在被调用时加载。

没有 paths 的 API 专用规则。 如果某条规则仅适用于 src/api/**，使用 paths: 限定其作用域，可以避免它在处理无关工作时进入 Context。未限定作用域的 Rule 在机制上与将内容放入 CLAUDE.md 完全相同：始终加载，也始终消耗 Token。

将个人偏好写入项目级 CLAUDE.md 文件。 所有基于文件的方法都有对应的用户级配置，无论你位于哪个 repo，这些配置都会在每次 Claude Code 会话中加载。个人偏好（例如始终使用语义化提交消息）应使用本地文件。项目级文件应保留给整个团队共享、但特定于某个代码库的偏好。

开始自定义 Claude Code

你可以在我们的 Claude Code 最佳实践文档中找到更多充分利用 Claude Code 的技巧和模式，涵盖从配置环境到跨并行会话规模化扩展的各个方面。

当你让其中几种方式正常工作后，可以将其中多种方式（Skills、Subagent、Hooks、输出样式）打包成一个插件，在团队成员或项目之间共享一套一致的配置。

本文由 Anthropic 员工 Michael Segner 撰写。