驾驭 Claude Code：CLAUDE.md、技能、钩子、规则、子智能体等

引导 Claude Code：何时使用 CLAUDE.md、技能、hooks 和子智能体

Claude 的设计初衷是顺应你的工作方式，而在 Claude Code 中你可以对它进行自定义。

有七种方法可以指导 Claude 的行为：CLAUDE.md 文件、规则、技能、子智能体、hooks、输出样式，以及追加系统提示词。

每种方法控制以下方面：

指令何时加载到上下文中；
它是否能在长时间会话中持续存在（压缩行为）；以及
它拥有多大的权限。

下表快速总结了每种方法之间的关键差异，而本文则提供了更多细节和决策框架，帮助你确定每条 Claude 指令应该归属于何处。

方法	加载时机	压缩行为	上下文成本	何时使用
CLAUDE.md（根目录）	会话开始时；在整个会话期间保留在上下文中	记忆化。读取一次并缓存于会话中；压缩后缓存清除并重新读取	高。每一行无论是否相关都会消耗 token	构建命令、目录布局、monorepo 结构、编码规范、团队准则
CLAUDE.md（子目录）	按需触发，当 Claude 读取该子目录下的文件时	在该子目录再次被访问之前会丢失	低。仅当处理相关子目录时才消耗上下文	特定于某个子目录的规范
规则	会话开始时（用户级规则）或仅在匹配的文件被访问时（路径限定）	压缩时重新注入	中。除非路径限定，否则始终开启	特定约束或约定（例如，所有 API 处理程序必须使用 Zod 验证输入）
技能	会话开始时加载名称和描述；技能被调用时加载完整正文	被调用的技能会在共享预算内重新注入；最旧的优先被丢弃	低。仅在调用时加载完整正文；受被调用技能之间共享的 token 预算约束	流程性工作流（部署或发布检查清单）
子智能体	会话开始时加载名称、描述和工具列表；仅当通过 Agent 工具调用时加载正文	只有最终消息（摘要加元数据）返回主会话	低。在被调用前对主上下文零开销；在自身隔离的上下文窗口中运行	并行运行工作，或运行应隔离执行且仅返回摘要的侧任务（深度搜索、日志分析、依赖审计）
钩子	在生命周期事件时触发	完全绕过压缩	低。配置存在于主上下文之外；部分输出可能会返回（例如阻塞性错误）	确定性自动化：运行 linter、完成后发布到 Slack、阻止命令、在 PreCompact 时备份聊天历史
输出样式	会话启动时；注入到系统提示词中	从不被压缩	高。占用上下文窗口，但会覆盖默认系统提示词	重大角色变更（从代码助手变为通用助手）
追加系统提示词	会话启动时；作为 CLI 标志传入	从不被压缩；仅适用于该次调用	中等。在会话中首次请求后被缓存	语气、回复长度、格式偏好

传递指令的七种方法

自定义 Claude Code 行为有七种方式：CLAUDE.md 文件用于始终生效的项目上下文，规则用于硬性约束，技能用于可复用的流程，子智能体用于委派工作，钩子用于确定性自动化，以及输出样式或系统提示词追加用于全局变更。

每种方法都在上下文成本与权威性之间做权衡。这些方法影响 Claude 的行为，而另外两个独立的调节旋钮——你选择哪个模型和努力级别——则控制它有多强以及它工作有多努力。

CLAUDE.md 文件

CLAUDE.md 是位于项目根目录的 markdown 文件。它在会话开始时加载到上下文中，并在整个会话期间一直保留在那里。

构建命令、目录布局、monorepo 结构、编码约定和团队规范都很自然地适合放在这里。

有两种类型，它们的加载方式不同：

始终加载：第一种类型是根目录的 CLAUDE.md 文件，可以放在共享仓库中，和/或保存在本地以记录你针对某个项目的个人偏好。所有这些文件都会在会话开始时加载，并且在长时间会话中不会丢失或退化。当 Claude Code 压缩对话时，它会重新读取这些文件。
按需加载：位于你初始化会话所在文件夹之下的子目录中的 CLAUDE.md 文件。例如，app/api/CLAUDE.md会在 Claude 读取 app/api下的某个文件时加载，而不是在会话启动时加载。它与路径范围规则共享压缩行为：在被再次触及之前，该子目录的内容会一直处于消失状态。

当 Claude 读取 cwd 下某个目录中的文件时，该目录之下的所有子目录 CLAUDE.md 文件都会加载。

在共享仓库中，CLAUDE.md 会像任何无人负责的配置文件一样不断膨胀：每个团队都追加自己的指令，而没有任何内容会被删除。随着规模扩大，成本会不断累积。

每一行都会加载进仓库中每位工程师的每个会话，无论它是否与其任务相关。这会消耗 token，并稀释对真正重要指令的遵循程度。随着文件不断增长，把团队特定的约定放进按路径作用域的规则中，把流程放进技能中，这样它们只在相关时才会加载。

提示：让 CLAUDE.md 保持在 200 行以内，给它指定一位负责人，并像对待代码一样审查对它的改动。内容本身应遵循与任何提示词相同的规则：编写有效的提示词意味着要明确、解释约束背后的原因，并给出示例。

把这个文件看作是为 Claude 提供代码库概览，或者看作一个索引，指向 Claude 在需要时可以找到更多信息的其他文件。

在 monorepo 中，为每个团队的目录提供各自的子目录 CLAUDE.md，这样团队只会加载自己的约定，开发者也可以使用 claudeMdExcludes 设置来跳过那些他们从不接触其代码的团队的文件。

对于必须适用于组织中每个仓库的标准——安全策略、合规要求——可以通过 MDM 或配置管理将集中管理的 CLAUDE.md 部署到开发者机器上，并且它无法被个人设置排除。

关于设置 CLAUDE.md 的更多内容，请参阅我们的博客文章 CLAUDE.md 文件：为你的代码库定制 Claude Code。

视频 · 前往原文观看

规则

规则是 .claude/rules/ 中的 markdown 文件，用于给 Claude 提供特定的约束或约定。

未限定作用域的规则行为与 CLAUDE.md 类似，它们总是在会话开始时加载，并在压缩时重新注入。这可能会浪费 token，因为即使与当前任务无关，也会加载上下文。

路径限定作用域的规则允许你仅在相关时加载规则指令，方法是添加一个 paths 字段来控制它们的加载时机。

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

它看起来是这样的：

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

提示：针对特定文件的约束，比如"迁移是只追加的"，最适合作为一条规则放在你的 paths: frontmatter 中。当指令涉及横切关注点或出现在代码库多个（但非全部）角落的文件时，应优先使用按路径限定的规则，而非嵌套的 CLAUDE.md 文件。

技能

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

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

例如，/code-review 是一个内置技能，它会审查你当前的 diff 并报告发现，而不编辑文件。该技能定义了操作手册，因此每次你调用它时，Claude 都会遵循相同的结构化方法。

在压缩时，Claude Code 会重新注入已调用的技能，所有已调用技能的总量受一个总预算限制。如果你在一次会话中调用了许多技能，最旧的会最先被丢弃。

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

Claude Code 自带技能，但你也可以编写自己的自定义技能。我们的为 Claude 构建技能的完整指南会告诉你如何操作。

子智能体

子智能体是 .claude/agents/ 中的 markdown 文件，用于为特定的辅助任务定义隔离的助手。每个文件使用 YAML frontmatter（name、description，以及可选的 model 和工具访问字段），其后是正文，正文会成为该子智能体的系统提示词。

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

Claude Code 的上下文窗口容纳了 Claude 关于你此次会话所知道的一切。这里的交互式时间线详细展示了哪些内容会在何时加载。

子智能体正文中更大的指令性上下文不仅不会自动调用，而且根本不会进入父对话。

子智能体随后会在自己全新的上下文窗口中运行，而返回主会话的唯一内容就是子智能体的最终消息（通常是许多子任务的汇总结果）以及元数据。

这种模式可以扩展：子智能体最多可嵌套五层，而动态工作流可以编排数十到数百个后台智能体，而无需你逐一指定子智能体架构的每个细节。编排计划和中间结果存放在脚本变量中，而非 Claude 的上下文窗口里，这使得规模化成为可能，同时不会损失指令的忠实度。

提示：这种隔离正是选择子智能体而非技能的主要原因之一。当某项副任务——比如深度搜索、一轮日志分析或依赖项审计——会用你之后不会再引用的中间结果弄乱主对话时，就该使用子智能体。当你希望流程在主线程内展开、以便你能看到并引导每一步时，就该使用技能。

钩子

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

你可以在 settings.json、托管策略设置或技能/智能体的 frontmatter 中注册 hook。

hook 有几种类型：command、HTTP、mcp_tool、prompt 和 agent。所有 hook 都是确定性触发的。前三种以确定性方式执行，而后两种——prompt 和 agent——则使用 Claude 的判断而非一套规则来决定输出。

hook 的上下文开销很低，因为配置或指令位于主上下文窗口之外。根据 hook 类型的不同，harness 会运行处理程序（command、http、mcp_tool），或使用独立的窗口进行模型调用（prompt、agent）。

某些 hook 的输出可能会被保存到主上下文窗口。例如，阻塞型 hook 的标准错误会被保存到上下文中，这样 Claude 就能知道该调用为何被拒绝。

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

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

提示：凡是应当确定性地发生的事情，都可以使用 hook：在编辑后运行 linter、在完成时向 Slack 发送消息，或在特定命令执行前将其拦截。一个 PreToolUse hook 可以检查任意工具调用，并以退出码 2 拒绝它。

它们的上下文开销很低，因为它们是 harness 运行的代码，而不是被加载进上下文的、给 Claude 的指令。技能和 hook 也是设计智能体循环的构建块——即重复运行直到满足停止条件的工作流。

输出样式

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

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

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

在 Claude Code 中，这会移除那些告诉 Claude 它正在帮助用户完成软件工程任务的指令，以及包含其他关键默认指令的内容，例如：

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

默认情况下，自定义输出样式会丢弃所有这些内容，Claude Code 也就更像一个通用助手，而非软件工程师助手。

提示：在编写自定义输出样式之前，先看看内置样式。主动式、解释式和学习式已覆盖了最常见的需求（自主性、教学模式、协作式编码），你无需自己维护一个样式文件。

追加系统提示词

修改输出样式的另一种替代方案是 append-system-prompt 标志。修改输出样式文件可能会对 Claude 的行为造成巨大的、非预期的改变，而追加标志只是对原始系统提示词做增量添加。它不会修改 Claude 的角色；只是为其默认角色添加指令。

它同样在调用时传入，且仅对该次调用生效，而不会作为文件跨会话持久保存。

追加系统提示词相比其他传递指令的方式，可能会带来更高的上下文开销。它会增加输入 token，不过在会话中的首次请求之后，提示词缓存会降低这一开销。指示 Claude 使用更冗长或更长的风格也会增加输出 token。

提示：追加系统提示词最适合用于添加特定的编码规范、输出格式或领域特定知识。请记住，追加系统提示词在遵循度上存在收益递减。一般来说，你用这种方式提供的指令越多，Claude 遵循得就越不严格，尤其是在指令之间存在矛盾时。

何时使用每种方法

如果你发现自己正在做以下某件事，或许可以考虑将指令放到其他位置：

在 CLAUDE.md 中写“每次 X，总是执行 Y”。如果该行为应当可靠地发生，比如每次编辑后运行 prettier 或完成后发布到 Slack，请改用 settings.json 中的 hook。模型选择运行格式化工具，与格式化工具自动运行，是两回事。

在 CLAUDE.md 中写“绝不要这样做”。当某些事情绝对不允许发生时，用指令是错误的手段。Claude 大多数时候会遵循指令，但在压力之下、在长时间会话中、在模棱两可的情形下，或者由于任务中访问的某个文件里存在提示词注入，模型可能无法遵循一条提示词规则。真正的护栏必须是确定性的，而强制执行的手段是 hooks 和 permissions。一个 PreToolUse hook 可以检查一次调用并以退出码 2 阻止它。托管设置更进一步：它们由管理员部署，无法被用户的本地配置覆盖，并且是强制执行确定性、组织级护栏的唯一方式。

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

一条没有路径限定的 API 专属规则。如果一条规则只适用于 src/api/**，用 paths: 限定其作用范围，可以让它在不相关的工作中不进入上下文。一条未限定作用范围的规则，在机制上等同于把内容放进 CLAUDE.md：始终加载，始终消耗 token。

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

Claude Code 自定义入门

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

当你让其中几项运转起来后，可以将它们中的许多（技能、子智能体、钩子、输出样式）打包为一个插件，以便在团队成员或项目之间共享一套协调一致的配置。