Anthropic 官方博客放出一份 Claude Code 调教指南。

这篇指南把七种自定义机制，按加载时机、上下文开销和执行权限三条线划分，教你如何让 Claude Code 乖乖听话，不跑偏。

CLAUDE.md 文件、rules（规则）、skills（技能）、subagents（子代理）、hooks（钩子）、output styles（输出风格）、append-system-prompt（追加系统提示）七种方式，覆盖了 Claude Code 行为定制的全部入口。

每一种在加载时机、压缩行为、上下文开销和适用场景上都不一样。把它们摆到合适的位置，Claude Code 才能乖乖干活。

而选哪一种机制，本质上是在选你愿意为这条指令付多少上下文成本、给它多大权力。

七种机制一览

Anthropic 把七种自定义方式整理成一张总览表。每一种机制都对应三个核心维度，指令何时进入上下文，长会话压缩后是否保留，权限有多大。

这张表是所有判断的基础，记下来或收藏起来，遇到具体场景对照查就行。

七种机制不是互斥关系，更像一套分工明确的工具箱。

Anthropic 反复强调一个核心判断维度，指令是否需要在长会话压缩后保留，是否值得为它付常驻上下文的成本，是否需要确定性而非模型自主判断。把这三个问题想清楚，七种机制的选择基本就定了。

下面按机制类别拆开讲，最后给一些建议帮你避坑。

文件、规则与代理

CLAUDE.md 是放在项目根目录的 markdown 文件，会话开始就进上下文，整个会话常驻。构建命令、目录布局、monorepo（单体仓库）结构、编码规范、团队约定都适合放这里。

它分两种加载方式。一种是常驻型，根目录的 CLAUDE.md，可以放在共享仓库里，也可以放在本地存个人偏好。会话开始就加载，长会话里也不会丢失或衰减，Claude Code 压缩对话时还会重新读一遍。

另一种是按需型，子目录里的 CLAUDE.md。比如 app/api/CLAUDE.md，只有 Claude 读取 app/api 下的文件时才会加载，会话开始时不会。它的压缩行为和路径限定规则一样，被触碰后才会重新出现。

共享仓库里，CLAUDE.md 像无人维护的配置文件，每个团队都往里加自己的指令，没人删东西。规模一大成本就叠加。每一行都会进入每个工程师的每次会话，不管相不相关，既消耗 token，又稀释真正重要指令的执行力度。

所以，文件越大，越应该把团队专属约定挪到路径限定规则里，把流程性内容挪到 skills 里，让它们只在需要时加载。

CLAUDE.md 应该控制在 200 行以内，指定一个负责人，像审查代码一样审查它的变更。把它当作给 Claude 看的代码库概览，或者一个索引，指向其他 Claude 可以按需查阅的文件。

monorepo 里给每个团队的目录配一个子目录 CLAUDE.md，团队只加载自己的约定。开发者可以用 claudeMdExcludes 设置跳过从不碰的团队的文件。组织级标准（安全策略、合规要求）可以走 MDM（移动设备管理）或配置管理工具统一部署到开发者机器上，个人设置无法排除。

rules 是放在 .claude/rules/ 目录下的 markdown 文件，给 Claude 提供具体约束或约定。它和 CLAUDE.md 的差别主要在路径控制能力，CLAUDE.md 是全量常驻，rules 可以做精细的路径限定。

不带路径限定的 rules 行为和 CLAUDE.md 一样，会话开始就加载，压缩时重新注入。任务无关时也会被加载，浪费 token。路径限定规则通过 paths 字段控制加载时机，让规则只在相关时进入上下文。限定到 src/api/** 的规则，在纯文档会话里不会进上下文，只有 Claude 读取 src/api/ 目录下文件时才加载。

代码示例：

文件级别的约束（比如 migrations 是只追加的）适合放进 paths frontmatter（前置元数据）。当指令涉及跨切面关注点或出现在多个但非全部代码区域时，路径限定规则比嵌套 CLAUDE.md 更合适。

skills 放在 .claude/skills/ 目录下，是文件夹形式的指令、脚本和资源集合，由 Claude 动态加载。

每个 skill 有一个 SKILL.md 文件，包含名称、描述和主体。会话开始时只加载名称和描述，主体在 Claude 调用该 skill 时才加载。

调用方式有两种，一种是通过 slash command（斜杠命令）比如 /code-review，一种是任务自动匹配。

举个例子，/code-review 是一个内置 skill，会审查当前的 diff（代码差异）并报告发现，不修改文件。skill 定义了 playbook（操作手册），Claude 每次调用都按同一套结构化流程走。

压缩时，Claude Code 会按共享预算重新注入已调用的 skills。一次会话里调用了多个 skill，最早的会被先丢弃。

流程性指令（部署工作流、发布检查清单、代码审查流程）应该放进 skill 而不是 CLAUDE.md。

subagents 是放在 .claude/agents/ 目录下的 markdown 文件，定义用于特定副任务的隔离助手。每个文件用 YAML frontmatter（包含 name、description，以及可选的 model 和 tool access 字段），后面跟一段主体，主体会变成该 subagent 的系统提示。

subagents 和 skills 类似，名称、描述、工具列表在会话开始时加载，但主体不会自动调用。Claude 通过 Agent tool（Agent 工具）调用它，传入一段 prompt 字符串。

主体的指令上下文不会自动调用，也永远不会进入父对话。subagent 在自己的全新上下文窗口里运行，回到主会话的只有 subagent 的最终消息（通常是多个副任务的聚合结果）加元数据。

subagents 的模式可以扩展。支持最多五层嵌套，动态工作流可以编排几十到几百个后台 agent，不需要你逐个指定架构细节。编排计划和中间结果存在脚本变量里，不在 Claude 的上下文窗口里，既能扩展又不丢失指令保真度。

举一个具体场景，你让 Claude 做一次大型依赖审计，要扫 200 个包、查每个包的安全公告、给出升级建议。如果走主线程，中间结果会把上下文塞满，连原始任务都丢了。换 subagent 编排，每个包派一个 agent 处理，只把最终汇总报告回主会话，主线程还能继续推理下一步动作。

隔离是选 subagent 而不是 skill 的主要原因。当副任务（深度搜索、日志分析、依赖审计）会让中间结果塞满主对话，而你之后不会再引用这些结果时，就用 subagent。当你希望流程在主线程里展开，能看到并引导每一步时，就用 skill。

钩子、风格与提示

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

hooks 在 settings.json、managed policy（托管策略）设置或 skill/agent frontmatter 里注册。类型有五种，command、HTTP、mcp_tool、prompt、agent。前三种确定性执行，后两种（prompt 和 agent）用 Claude 的判断而不是规则决定输出。

hooks 上下文开销低，因为配置或指令在主上下文窗口之外。harness 执行 handler（处理程序），或用独立窗口做模型调用。部分 hook 的输出会保存到主上下文窗口。比如阻断型 hook 的标准错误会进入上下文，让 Claude 知道调用为什么被拒绝。

但大多数 hook 的输出不会进主窗口，除非配置明确返回。用 PreCompact 事件把聊天记录备份到另一个文件，Claude 不会知道备份到了哪里。

hooks 跟 CLAUDE.md、rules、skills 有本质区别，原因就在这里。前三者都是给 Claude 看的指令，遵循与否取决于模型当下的判断。hooks 是代码层确定性触发，模型连选择权都没有。

hooks 用于一切需要确定性发生的场景，编辑后跑 lint、完成后发 Slack、命令执行前阻断。PreToolUse hook 可以检查任何工具调用，exit code 2 就能拒绝它。它们上下文开销低，因为运行的是 harness 执行的代码，而不是加载进上下文给 Claude 看的指令。

output styles 是放在 .claude/output-styles/ 目录下的文件，把指令注入系统提示。它们不会被压缩，每次会话开始就加载，会话内首次请求后缓存，上下文开销中等。

因为它们位于系统提示里，在所有方法里指令遵循权重最高，需要谨慎使用。修改 output style 会替换默认 output style，除非在 frontmatter 里设置 keep-coding-instructions: true。

在 Claude Code 里，自定义 output style 会移除告诉 Claude 它在帮用户做软件工程任务的指令，以及其他关键默认指令，包括如何限定改动范围、何时加或省略代码注释、遇到安全顾虑怎么办、验证习惯（比如声明工作完成前先跑测试）。

默认情况下自定义 output style 会丢掉所有这些，Claude Code 会从软件工程助手变成更通用的助手。能力没变，但角色定位偏移之后，模型在很多细节行为上会跟着偏。比如原本声明完成前会主动跑测试，换 style 后可能就直接交差。

写自定义 output style 之前，先看内置的几种。Proactive、Explanatory、Learning 覆盖了最常见的需求（自主性、教学模式、协作编码），不用自己维护 style 文件。

修改 output style 文件可能对 Claude 行为产生意料之外的大变化，append-system-prompt（追加系统提示）flag 是另一种选择，只对原始系统提示做加法。它不修改 Claude 的角色，只往默认角色上加指令。追加系统提示在调用时传入，只对本次调用生效，不会作为文件跨会话保留。

追加系统提示比其他指令传递方式上下文开销更高。它增加输入 token，prompt caching（提示缓存）能降低会话内首次请求后的成本。

追加系统提示适合加具体的编码标准、输出格式或领域知识。

注意追加方式在执行力度上有边际递减。一般而言，往系统提示里塞的指令越多，Claude 遵循得越不严格，尤其是互相矛盾的指令，几条打架的指令放在一起，模型往往会各取一部分执行，结果哪条都没真正落地。

落地建议

实际用起来，遇到下面几种情况，说明你该换个地方放指令了：

1，CLAUDE.md 里写了每次 X 都要做 Y。

行为需要可靠发生时（每次编辑后跑 prettier、完成后发 Slack），就改成 settings.json 里的 hook。模型选择跑 formatter（格式化工具）和 formatter 自动跑，是两回事。

2，CLAUDE.md 里写了绝对不能做某件事。

某件事绝对不能发生时，指令不是合适的工具。Claude 大多数时候会遵循，但在压力下、长会话里、模糊场景里，或因为任务中访问的文件里有 prompt injection（提示注入），模型可能失败。

真正的 guardrail（护栏）需要确定性，执行方式是 hooks 和 permissions（权限）。PreToolUse hook 检查调用，exit code 2 阻断。managed settings（托管设置）更进一步，由管理员部署，用户本地配置无法覆盖，是组织级确定性护栏的唯一方式。

3，CLAUDE.md 里塞了 30 行流程。

流程属于 skills。CLAUDE.md 是给 Claude 始终记住的事实，构建命令、monorepo 布局、团队约定。部署 runbook（操作手册）或安全审查清单应该放在 .claude/skills/，主体只在调用时加载。

4，针对 API 的规则没加 paths。

规则只适用于 src/api/** 时，用 paths 限定能让它在无关工作时退出上下文。不限定路径的规则和把内容塞进 CLAUDE.md 在机制上完全一样，永远加载，永远消耗 token。

5，把个人偏好写进项目级 CLAUDE.md 文件。

所有文件级方式都有用户级对应物，无论在哪个仓库都会为每次 Claude Code 会话加载。个人偏好（始终用语义化 commit 消息）放本地文件。项目级文件留给团队级但特定于某个代码库的偏好。

弄懂几种机制之后，可以把多个机制（skills、subagents、hooks、output styles）打包成 plugin（插件），跨团队或跨项目共享一套一致的配置。

一个团队沉淀出的发布检查 skill、一段 PreToolUse 阻断 hook、一套专属 output style，组合成 plugin 之后，新成员装上插件就能复用整套工作流，不用一项项配置。

让 Claude Code 听话，除了指令本身，还需要明白指令放哪里、什么时候加载、给多大权力。

七种机制各有脾气，摆错位置再精准的指令也会失效。

你最常用哪一种，又踩过哪种坑？

参考资料：

https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more