Claude Code指南：CLAUDE.md、技能、钩子与子代理的使用时机

规则

规则是.claude/rules/ 目录下的markdown文件，为Claude提供特定的约束或约定。

无范围限定的规则与CLAUDE.md类似，在会话开始时始终加载，并在压缩时重新注入。这可能会在任务不相关时加载上下文，从而浪费令牌。

路径限定的规则允许您通过添加paths字段来控制加载时机，从而仅在与任务相关时加载规则指令。

例如：限定于src/api/**范围的规则在仅处理文档的会话中不会进入上下文。只有当Claude读取该src/api/ 目录中的文件时才会加载。

具体如下：

---paths:-"src/api/**"-"**/*.handler.ts"---AllAPIhandlersmustvalidateinputwithZodbeforeprocessing.

提示：针对特定文件的约束（如“迁移仅追加”）最适合作为规则放在路径的前置元数据中。当指令涉及跨领域问题或出现在代码库多个（但非全部）角落的文件时，应使用路径限定规则而非嵌套的CLAUDE.md文件。

技能

技能位于.claude/skills/目录下，是Claude动态加载的指令、脚本和资源文件夹。每个技能都有一个SKILL.md文件，包含名称、描述和正文。

会话开始时仅加载名称和描述；当Claude调用技能时（通过斜杠命令（/code-review）或自动匹配任务），才会加载完整正文。

例如，/code-review是一个内置技能，用于审查当前差异并报告发现，而不修改文件。该技能定义了操作流程，使Claude在您每次调用时遵循相同的结构化方法。

在压缩时，Claude Code会重新注入已调用的技能，总预算为所有调用技能的总和。如果您在会话中调用了许多技能，最旧的会最先被丢弃。

提示：程序性指令（如部署工作流、发布清单或审查流程）应属于技能而非CLAUDE.md。

Claude Code自带技能，但您也可以编写自定义技能。我们的为Claude构建技能的完整指南向您展示如何操作。

子代理

子代理是.claude/agents/ 目录下的markdown文件，为特定辅助任务定义独立的助手。每个文件使用YAML前置元数据（名称、描述，以及可选的模型和工具访问字段），后跟成为该子代理系统提示的正文。

子代理与技能类似，名称、描述和工具列表在会话开始时加载，但代理正文中的较大上下文不会自动调用。Claude通过Agent工具调用它们，并传入提示字符串。

子代理正文中较大的指令上下文不仅不会自动调用，而且根本不会进入父对话。

然后子代理在自身全新的上下文窗口中运行，返回主会话的只有子代理的最终消息（通常是许多子任务的聚合结果）以及元数据。

这种模式可扩展：子代理最多可嵌套五层，动态工作流可以编排数十到数百个后台代理，而无需您指定子代理架构的每个细节。编排计划和中间结果存储在脚本变量中，而非Claude的上下文窗口中，从而实现规模扩展而不损失指令保真度。

提示： 这种隔离是选择子代理而非技能的主要原因之一。当深度搜索、日志分析或依赖审计等辅助任务会用您不再引用的中间结果使主对话变得杂乱时，请使用子代理。当您希望程序在主线程中执行以便查看和引导每一步时，请使用技能。

钩子

钩子是用户定义的命令、HTTP端点或LLM提示，通过在Claude生命周期中的特定事件（如文件编辑、工具调用或会话开始）触发，提供对Claude行为的更确定性控制。

您可以在settings.json、托管策略设置或技能/代理前置元数据中注册钩子。

有几种类型的钩子：command、HTTP、mcp_tool、prompt和agent。所有钩子都是确定性触发的。前三种确定性执行，而后两种（prompt和agent）使用Claude的判断而非规则集来确定输出。

钩子的上下文成本较低，因为配置或指令位于主上下文窗口之外。工具框架运行处理程序（command、http、mcp_tool）或使用单独窗口进行模型调用（prompt、agent），具体取决于钩子类型。

某些钩子的输出可能保存到主上下文窗口。例如，阻塞钩子的标准错误会保存在上下文中，以便Claude知道调用被拒绝的原因。

但大多数钩子不会将输出保存到主窗口，除非配置明确返回。如果您在压缩前使用PreCompact事件将聊天历史备份到另一个文件以供日后参考，Claude将不知道哪个文件保存了聊天历史。

这使得这些钩子类型与CLAUDE.md、规则和技能有根本区别。您可以在我们的文章中了解更多 如何配置钩子。

提示：对于任何需要确定性发生的事件，请使用钩子：编辑后运行linter、完成时发布到Slack，或在特定命令执行前阻止它们。一个PreToolUse钩子可以检查任何工具调用并以退出码2拒绝。

它们的上下文成本较低，因为它们是工具框架运行的代码，而非加载到上下文中的指令。技能和钩子也是设计代理循环——重复运行直到满足停止条件的工作流——的构建块。

输出样式

输出样式是.claude/output-styles/ 向系统提示中注入指令。它们不会被压缩，在每次会话开始时加载，并在会话内首次请求后被缓存，这意味着它们具有中等程度的上下文成本。

由于它们位于系统提示中，输出风格在我们目前讨论的所有方法中具有最高的指令遵循权重，应谨慎使用。

对输出风格的更改将替换默认输出风格（除非您在风格的前置数据中设置了 keep-coding-instructions: true）。

在 Claude Code 中，这将移除告诉 Claude 它正在帮助用户处理软件工程任务的指令，并包含其他关键默认指令，例如：

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

默认情况下，自定义输出风格会丢弃所有这一切，Claude Code 变得更像通用助手而非软件工程师助手。

提示：在编写自定义输出风格之前，请检查内置风格。Proactive、Explanatory和Learning涵盖了最常见需求（自主性、教学模式、协作编码），无需您维护样式文件。

追加系统提示

修改输出风格的另一种方法是append-system-prompt标志。修改输出风格文件可能会对 Claude 的行为产生意想不到的大影响，而 append 标志仅对原始系统提示进行附加。它不会修改 Claude 的角色；只是向其默认角色添加指令。

它也在调用时传递，并且仅适用于该次调用，而不是作为跨会话持久化的文件。

与其他传递指令的方法相比，追加系统提示可能会产生更高的上下文成本。它会增加输入令牌，尽管提示缓存会在会话内的首次请求后降低此成本。指示 Claude 使用更冗长或更长的风格也会增加输出令牌。

提示：追加系统提示最适合添加特定的编码标准、输出格式或特定领域知识。请记住，追加系统提示在遵循性方面收益递减。通常，使用此方法提供的指令越多，Claude 对它们的遵循就越不严格，尤其是当它们相互矛盾时。

何时使用每种方法

如果您发现自己执行以下操作之一，您可能需要考虑为您的指令选择其他位置：

在 CLAUDE.md 中写“每次 X，总是做 Y”。如果该行为应可靠发生，例如每次编辑后运行 prettier 或完成时发布到 Slack，请改用 settings.json 中的钩子settings.json。模型选择运行格式化程序与格式化程序自动运行是不同的。

在 CLAUDE.md 中写“绝不做这个”。当有绝对不能发生的事情时，指令是错误的工具。Claude 大多数时候会遵循指令，但在压力下、长时间会话或模糊情况下，或由于任务中访问的文件中的提示注入，模型可能无法遵循提示规则。真正的护栏需要是确定性的，执行方法是钩子和权限。PreToolUse钩子可以检查调用并以退出码 2 阻止它。托管设置 更进一步：它们由管理员部署，不能被用户的本地配置覆盖，并且是强制执行确定性、组织范围护栏的唯一方式。

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

没有路径的 API 特定规则。如果规则仅适用于src/api/**，使用paths:限定它可以在不相关的工作期间使其脱离上下文。未限定范围的规则在机制上与将内容放入 CLAUDE.md 相同：始终加载，始终消耗令牌。

将个人偏好写入项目级 CLAUDE.md 文件。所有基于文件的方法都有一个用户级对应方法，无论您所在的仓库如何，每个 Claude Code 会话都会加载。使用本地文件存储个人偏好（始终使用语义化提交消息）。将项目级文件用于团队范围的但特定于给定代码库的偏好。

开始使用 Claude Code 自定义

您可以在我们的Claude Code 最佳实践文档中找到更多关于充分利用 Claude Code 的技巧和模式，从配置环境到并行会话扩展。

一旦您掌握了其中一些，您可以将其中许多（技能、子代理、钩子、输出风格）捆绑为插件，以便在团队成员或项目之间共享一致设置。

本文由 Anthropic 员工 Michael Segner 撰写。