【翻译】引导 Claude Code：CLAUDE.md 文件、技能、钩子、规则与子智能体等

引导 Claude Code：CLAUDE.md 文件、技能、钩子、规则与子智能体等

Claude 从出生那天起就强调“适配你的工作方式”，而 Claude Code 更是把定制这件事做到了极致。一共七种手段能让你精确控制它的行为：CLAUDE.md 文件、规则、技能、子智能体、钩子、输出风格，还有追加系统提示词。每种方法在加载时机、长会话中的持久性，以及指令权重上都有明显区别——下面这张表能帮你一目了然。

方法	何时加载	压缩行为	上下文成本	适用场景
CLAUDE.md（根目录）	会话开始时加载；在整个会话期间始终保留在上下文中	已记忆化。读取一次并在会话中缓存；压缩后清除缓存并重新读取	高。每一行都会消耗 token	构建命令、目录布局、monorepo 结构、编码规范、团队规范
CLAUDE.md（子目录）	按需加载，当 Claude 读取该子目录下的文件时	在再次触及该子目录之前会丢失	低。仅在处理相关子目录时才消耗上下文	特定子目录的约定
规则（Rules）	会话开始时加载（用户级规则），或仅在触及匹配文件时加载（路径作用域）	压缩时重新注入	中。除非路径作用域	特定约束或约定
技能（Skills）	会话开始时加载名称与描述；调用技能时加载完整正文	已调用的技能在共享预算内重新注入；最旧的先被丢弃	低。完整正文仅在调用时加载	流程性工作流（部署或发布清单）
子智能体（Subagents）	会话开始时加载名称、描述与工具列表；仅通过 Agent 工具调用时加载正文	仅最终消息（摘要加元数据）返回主会话	低。主上下文中零成本，直到被调用	并行运行或应在隔离中执行的任务
钩子（Hooks）	在生命周期事件上触发	完全绕过压缩	低。配置位于主上下文之外	确定性自动化：运行 linter、发布到 Slack、阻塞命令
输出风格（Output styles）	会话开始时加载；注入系统提示词	永不压缩	高。占用上下文窗口，但会覆盖默认系统提示词	显著的角色变更
追加系统提示词	会话开始时加载；通过 CLI 标志传入	永不压缩；仅适用于该次调用	中。会话中首次请求后缓存	语气、回复长度、格式偏好

七种传递指令的方法

CLAUDE.md 文件

CLAUDE.md 放在项目根目录，会话启动时就加载进来，全程雷打不动。构造命令、目录布局、monorepo 结构、编码规范、团队约定——这些东西天然适合写在这里。

有两种变体：

的根目录文件，以及的子目录文件。根目录文件可以放在仓库共享，也可以本地保留个人偏好。无论是哪种，都会在会话开始时载入，不会被长对话冲掉。Claude Code 压缩聊天时，这些文件会被重新读取。子目录里的文件则不同：比如 app/api/CLAUDE.md，只有 Claude 读 app/api 下的文件时才会激活，之后一旦离开那个目录，内容就从上下文里消失了。

当前工作目录下的所有子目录 CLAUDE.md 都能起到这样的按需加载效果。不过要小心——共享仓库里的 CLAUDE.md 很容易膨胀成无人维护的配置文件：每个团队都往里塞指令，却从不清理。token 成本随文件大小线性增长。文件越大，重要指令被稀释的风险就越高。所以，当 CLAUDE.md 超过 200 行时，就该考虑把团队特定约定迁移到路径作用域的规则里，把流程搬进技能文件夹，让它们只在真正需要时才被加载。

把 CLAUDE.md 控制在一份简明摘要，指定负责人，对它的变更像审查代码一样严格。把它当做给 Claude 的代码库鸟瞰图，而不是一本百科全书。在 monorepo 里，每个团队可以拥有各自的子目录 CLAUDE.md；你还能通过 claudeMdExcludes 设置跳过那些从不接触的团队文件。至于必须适用于全组织的安全或合规标准，可以通过 MDM 或配置管理部署集中管理的 CLAUDE.md，本地设置无法绕过。

规则（Rules）

存放在 .claude/rules/，专门用来表达特定约束。未限定作用域的规则跟 CLAUDE.md 行为一样：会话开始就加载，压缩时重新注入，无关工作时也会白白消耗 token。但你可以通过 paths 字段给它加上作用域——只有 Claude 读取匹配路径下的文件时，规则才会被激活。比如一条针对 src/api/** 的规则，如果当前会话只处理文档，它就乖乖待在上下文之外。

来看一个例子：

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

像“迁移文件仅追加、不可修改”这类针对特定文件的约束，本质就是规则。当指令是一个横切关注点，且只出现在代码库的某些角落时，路径作用域规则比嵌套的 CLAUDE.md 更优雅。

技能（Skills）

住在 .claude/skills/，每个技能是一个文件夹，里面包含 SKILL.md 以及配套脚本和资源。会话开始时，Claude 只加载技能的名称和描述；等到它通过斜杠命令（比如 /code-review）或自动匹配触发技能时，才会把完整指令拉进来。

技能由系统提示词触发。比如内置的 /code-review，每次调用都会基于当前 diff 做审查，只报告发现，绝不编辑文件。这个技能定义了一套 playbook，保证 Claude 每次执行都结构一致。会话压缩时，所有已被调用的技能会在一个共享预算内重新注入，如果调用的技能太多，最早的那个会被挤出。

流程性指令——部署工作流、发布清单、安全审查清单——最适合做成技能，而不是塞进 CLAUDE.md。内置技能已经够用，你也可以自己写。

子智能体（Subagents）

写在 .claude/agents/ 的 Markdown 文件里，为旁路任务创建一个隔离的环境。每个文件通过 YAML frontmatter 定义名称、描述，还可以指定模型和工具访问权限。正文则成为子智能体的系统提示词。类似技能，名称、描述和工具列表在会话开始就加载了，但真正的指令正文不会被自动调用——只有当 Claude 通过 Agent 工具显式呼叫它，并传入提示词时，才会激活。

Claude Code 的上下文窗口保存着对话的全部信息。而子智能体的指令正文不仅不会自动调用，它根本就不会进入父对话。子智能体在自己的独立上下文窗口里运行，唯一返回主会话的是最后那条聚合消息（加上元数据）。这个模式可以无限扩展：你最多嵌套五层子智能体，动态工作流能编排数十甚至数百个后台智能体，而所有编排计划和中间结果都存放在脚本变量里，不会胀大 Claude 的上下文窗口。

隔离是选择子智能体而非技能的第一理由。当你要做深度搜索、日志分析、依赖审计这类旁路任务，且中间结果你大概率不会再看第二遍时，子智能体是完美选项。相反，如果你希望每一步都看得到、随时能干预，那技能才是正解。

钩子（Hooks）

是用户定义的命令、HTTP 端点或大语言模型提示词，在 Claude 生命周期里的特定事件上被确定性触发。比如文件编辑完成后、工具调用前、会话开始……事件多了去了。

你在 settings.json、托管策略设置，或者 skill/agent 的 frontmatter 里注册钩子。钩子有五种类型：command、HTTP、mcp_tool、prompt 和 agent。前三种是纯确定性执行，后两种则借助 Claude 的判断来产生输出。钩子的上下文成本很低，因为配置本身不在主上下文窗口里。运行时框架在独立的窗口里运行处理器或模型调用。大部分钩子不会把输出带回主窗口，除非你特意配置了返回。例如，一个阻塞型钩子的标准错误会被写入上下文，这样 Claude 就能知道调用被拒绝的原因。但如果你在压缩前用 PreCompact 事件把聊天历史备份到文件，Claude 并不知道那个文件藏在哪里。

这一点让钩子从根本上区别于 CLAUDE.md、规则和技能。

任何应该“必须发生”的事情——编辑后自动运行 linter、完成时发布到 Slack、执行前阻止特定命令——都应该交给钩子。PreToolUse 钩子可以检查任何工具调用，并用退出码 2 将其拒之门外。因为它们本质上是代码，而不是 Claude 的指令，所以上下文成本极低。

输出风格（Output styles）

放在 .claude/output-styles/，它们把指令直接注入系统提示词，永不压缩。每个会话开始就加载，首次请求后缓存，上下文成本中等偏高。在所有定制手段中，输出风格的指令遵循权重最高——所以务必慎用。

更改输出风格会替换默认风格，除非你在 frontmatter 里设置 keep-coding-instructions: true。在 Claude Code 中，默认风格包含了大量关键内容：如何界定变更范围、何时添加注释、如何处理安全问题、验证习惯等等。一旦你自定义输出风格，所有这些都会被丢弃，Claude Code 将变为一个通用助手，而不是软件工程助手。

在动手写自定义风格之前，先看看内置的 、 和 。它们覆盖了最常见的使用场景——自主编码、教学模式、协作编程——不需要你维护任何风格文件。

追加系统提示词

如果不想因为修改输出风格而引发“蝴蝶效应”，更好的做法是使用 append-system-prompt 标志。它只是在原始系统提示词上做加法，不改动 Claude 的角色。这个标志在调用时传入，只对当次调用生效，不会跨会话持久化。追加提示词会增加输入 token，但提示词缓存会在首次请求后降低成本。需要注意，追加的指令越多，遵循度往往呈现递减回报——一旦超过某个临界点，Claude 的表现反而会变得不稳定。

追加系统提示词最适合添加具体的编码标准、输出格式或领域知识。记住，信息过量反而会适得其反。

Claude Code 定制快速提示

如果你发现自己正在做下面这些事，可能要想想是不是放错地方了：

• 在 CLAUDE.md 里写“每次 X，总是做 Y”。
  如果行为应该可靠发生，比如每次编辑后运行 prettier，那么请用钩子，而不是指令。模型选择运行格式化工具，与格式化工具自动运行，是两回事。

• 在 CLAUDE.md 里写“永远不要这样做”。
  当某事绝对不可发生时，指令是错误工具。Claude 大多数时候会遵守，但在长对话、模糊情境或提示注入面前可能掉链子。真正的护栏必须是确定性的——PreToolUse 钩子可以用退出码 2 阻塞调用。更进一步，

  托管设置
  由管理员部署，本地无法覆盖，是组织级强制护栏的唯一选择。

• 在 CLAUDE.md 里写 30 行流程。
  流程属于技能。CLAUDE.md 只放 Claude 应该始终知道的事实：构建命令、monorepo 布局、团队约定。部署 runbook 或安全审查清单放在 .claude/skills/ 里，正文只在调用时加载。

• 没有 paths 的 API 特定规则。
  如果规则只适用于 src/api/**，加上 paths: 限定作用域，否则它在不相关的工作中也会消耗 token。未限定作用域的规则在机制上等同于 CLAUDE.md。

• 把个人偏好写进项目级 CLAUDE.md。
  所有基于文件的方法都有用户级版本，无论你在哪个仓库，每次会话都会加载。本地文件放个人偏好（比如“始终用语义化提交信息”），项目级文件放团队范围的、针对特定代码库的偏好。

入门

把这几种方式组合起来后，你就可以把技能、子智能体、钩子、输出风格打包成 plugin，在队友或项目间共享一套设置。定制之路从了解这些工具开始，而真正的高手，懂得在正确的地方使用正确的工具。