Steering Claude Code: when to use CLAUDE.md, skills, hooks, and subagents

CLAUDE.md is a markdown file at the root of your project. It loads into context at session start and stays there for the entire session.

CLAUDE.md 是放在项目根目录的一个 markdown 文件。它在会话开始时加载进上下文,并在整段会话中一直留在那里。

Build commands, directory layout, monorepo structure, coding conventions, and team norms all fit naturally here.

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

There are two types, and they load differently:

它有两种类型,加载方式不同:

In a shared repository, CLAUDE.md grows the way any unowned config file does: every team appends its own instructions and nothing gets deleted. The cost compounds at scale.

在共享仓库里,CLAUDE.md 会像任何"无主"配置文件一样膨胀:每个团队都往里追加自己的指令,却没人删东西。规模一大,代价就复利式累积。

Every line loads into every session for every engineer working in the repo, whether it's relevant to their task or not. This consumes tokens and dilutes adherence to the instructions that actually matter. As the file grows, push team-specific conventions into path-scoped rules and procedures into skills, where they load only when relevant.

每一行都会为仓库里每一位工程师的每一次会话加载,无论它是否与其任务相关。这既消耗 token,又稀释了对真正重要的指令的遵循度。随着文件变大,把团队专属的约定挪进路径限定的 rule、把流程挪进 skill——它们只在相关时才加载。

Think of this file as giving Claude an overview of your codebase, or as an index pointing to other files where Claude can find more information as needed.

把这个文件想成是给 Claude 一份你代码库的概览,或者一个索引——指向其他文件,让 Claude 按需去那里找更多信息。

In monorepos, give each team's directory its own subdirectory CLAUDE.md so teams only load their own conventions, and developers can use the claudeMdExcludes setting to skip files from teams whose code they never touch.

在 monorepo 里,给每个团队的目录配一份自己的子目录 CLAUDE.md,这样各团队只加载自己的约定;开发者还能用 claudeMdExcludes 设置,跳过那些自己从不碰其代码的团队的文件。

For standards that must apply to every repository in the organization — security policies, compliance requirements — a centrally managed CLAUDE.md can be deployed to developer machines via MDM or config management, and it can't be excluded by individual settings.

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

More on setting up CLAUDE.md in our blog post, CLAUDE.md files: Customizing Claude Code for your codebase.

关于如何配置 CLAUDE.md,更多内容见我们的博客文章 《CLAUDE.md files: Customizing Claude Code for your codebase》。

Rules are markdown files in .claude/rules/ that give Claude specific constraints or conventions.

Rules 是放在 .claude/rules/ 里的 markdown 文件,给 Claude 特定的约束或约定。

Unscoped rules behave like CLAUDE.md in that they are always loaded at session start and get re-injected on compaction. This can waste tokens by loading context even when it's not relevant for the task at hand.

未限定作用域的 rule 表现得和 CLAUDE.md 一样:总是在会话开始时加载,并在压缩时重新注入。这可能浪费 token——即便对手头任务并不相关,也会把上下文加载进来。

Path-scoped rules allow you to load rule instructions only when they are relevant by adding a paths field that controls when they load.

路径限定的 rule 让你只在相关时才加载规则指令——通过添加一个 paths 字段来控制它们何时加载。

For example: a rule scoped to src/api/** stays out of context during a docs-only session. It would only be loaded whenever Claude reads files within that src/api/ directory.

例如:一个限定到 src/api/** 的规则,在纯写文档的会话里就不会进入上下文。它只会在 Claude 读取 src/api/ 目录内的文件时才被加载。

Here's what that looks like:

它长这样:

Skills live in .claude/skills/ as folders of instructions, scripts, and resources that Claude loads dynamically. Each skill has a SKILL.md file with a name, description, and body.

Skills 以文件夹形式住在 .claude/skills/ 里,包含指令、脚本和资源,由 Claude 动态加载。每个 skill 都有一个 SKILL.md 文件,含名称、描述和正文。

Only the name and description load at session start; the full body loads when Claude invokes the skill, either through a slash command (/code-review) or by auto-matching the task.

会话开始时只加载名称和描述;完整正文在 Claude 调用该 skill 时才加载——要么通过斜杠命令(/code-review),要么通过与任务自动匹配。

For example, /code-review is a built-in skill that reviews your current diff and reports its findings without editing files. The skill defines the playbook so Claude follows the same structured approach every time you invoke it.

例如,/code-review 是一个内置 skill,它会审查你当前的 diff 并报告发现,但不改动文件。这个 skill 定义了一套"打法",使得你每次调用时 Claude 都遵循相同的结构化方法。

On compaction, Claude Code re-injects invoked skills up to a total budget across all invoked skills. If you've invoked many skills during a session, the oldest ones drop first.

压缩时,Claude Code 会在"所有已调用 skill"的一个总预算范围内重新注入这些 skill。如果你在一次会话里调用了很多 skill,最早的会先被丢弃。

Claude Code ships with skills, but you can also write your own custom skills. Our complete guide to building skills for Claude shows you how.

Claude Code 自带一些 skill,但你也可以写自己的自定义 skill。我们的《构建 Claude skill 完整指南》会教你怎么做。

Subagents are markdown files in .claude/agents/ that define isolated assistants for specific side tasks. Each file uses YAML frontmatter (name, description, plus optional fields for model and tool access) followed by a body that becomes that subagent's system prompt.

Subagents 是放在 .claude/agents/ 里的 markdown 文件,为特定的旁支任务定义隔离的助手。每个文件用 YAML frontmatter(名称、描述,外加 model 和工具访问权限等可选字段),后面跟一段正文——这段正文会成为该 subagent 的系统提示。

Subagents are similar to skills in that the name, description, and tool list load at session start, but the larger context within the body of the agent doesn't auto-invoke. Claude calls them via the Agent tool, passing in a prompt string.

Subagent 与 skill 相似之处在于:名称、描述和工具清单在会话开始时加载,但 agent 正文里那一大段上下文不会自动触发。Claude 通过 Agent 工具调用它们,传入一个 prompt 字符串。

The interactive timeline here walks through what loads and when.

这里的交互式时间线会带你走一遍:什么在何时加载。

Not only does the larger instructional context within the body of the subagent not auto-invoke, it never enters the parent conversation at all.

subagent 正文里那一大段指令上下文,不仅不会自动触发,它压根就从不进入父对话。

The subagent then runs in its own fresh context window, and the only thing that returns to your main session is the subagent's final message (often the aggregated result of many subtasks) plus metadata.

于是这个 subagent 在自己全新的上下文窗口里运行,而唯一返回到你主会话的,只有它的最终消息(通常是许多子任务的汇总结果)加上元数据。

This pattern scales: subagents can nest up to five levels deep, and dynamic workflows orchestrate tens to hundreds of background agents without requiring you to specify each detail of the subagent architecture. The orchestration plan and intermediate results live in script variables rather than in Claude's context window, which enables scale without losing instructional fidelity.

这套模式可以规模化:subagent 最多能嵌套五层,而 dynamic workflows(动态工作流)能编排数十到数百个后台 agent,而无需你逐一指定 subagent 架构的每个细节。编排方案和中间结果活在脚本变量里,而不是 Claude 的上下文窗口里——这让规模化得以实现,又不损失指令的保真度。

Hooks are user-defined commands, HTTP endpoints, or LLM prompts that provide more deterministic control over Claude's behavior by firing on specific events in Claude's lifecycle like file edits, tool calls, or session start.

Hooks 是用户自定义的命令、HTTP 端点或 LLM prompt,它们通过在 Claude 生命周期中的特定事件(如文件编辑、工具调用、会话开始)上触发,来对 Claude 的行为提供更具确定性的控制。

You register hooks in settings.json, managed policy settings, or skill/agent frontmatter.

你可以在 settings.json、托管策略设置、或 skill / agent 的 frontmatter 里注册 hook。

There are several types of hooks: command, HTTP, mcp_tool, prompt, and agent. All hooks are deterministically triggered. The first three execute deterministically while the latter two, prompt and agent, use Claude's judgment rather than a set of rules to determine the output.

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

Hooks have low context costs because the configuration or instruction lives outside the main context window. The harness runs the handler (command, http, mcp_tool) or makes model calls with separate windows (prompt, agent) depending on the hook type.

hook 的上下文开销很低,因为配置或指令活在主上下文窗口之外。视 hook 类型而定,harness 要么运行处理器(command、http、mcp_tool),要么用独立的窗口发起模型调用(prompt、agent)。

Some hooks may have the output saved to the main context window. For example, a blocking hook's standard error is saved within context so Claude knows why the call was denied.

有些 hook 的输出可能会被保存到主上下文窗口。例如,一个阻断型 hook 的标准错误(stderr)会被保存进上下文,好让 Claude 知道那次调用为何被拒。

But most hooks won't have the output saved to the main window unless the configuration explicitly returns it. If you backed up your chat history into another file for later reference before compaction using the PreCompact event, Claude wouldn't know which file had the chat history saved.

但大多数 hook 除非配置里明确返回,否则输出不会被保存到主窗口。如果你用 PreCompact 事件在压缩前把聊天记录备份到另一个文件里以备日后查阅,Claude 是不会知道哪个文件存了聊天记录的。

This makes these hook types fundamentally different from CLAUDE.md, rules, and skills. You can learn more in our post how to configure hooks.

这使得这些 hook 类型与 CLAUDE.md、rules 和 skills 有着根本区别。更多内容见我们的文章《如何配置 hook》。

They have low context cost because they are code that the harness runs rather than instructions to Claude that get loaded into context.

它们上下文开销低,因为它们是 harness 运行的代码,而不是加载进上下文、发给 Claude 的指令。

Output styles are files in .claude/output-styles/ that inject instructions into the system prompt. They never get compacted, load at the start of every session, and are cached after the first request within a session, meaning they have a moderate context cost.

Output styles 是放在 .claude/output-styles/ 里、把指令注入系统提示的文件。它们永不被压缩,在每次会话开始时加载,并在会话内第一次请求后被缓存——也就是说上下文开销中等。

Because they sit in the system prompt, output styles carry the highest instruction-following weight of any method that we've covered so far and should be used judiciously.

由于它们位于系统提示中,output style 在我们目前讲过的所有方法里,携带着最高的"指令遵循权重",因此应当审慎使用。

Changes to the output style will replace the default output style (unless you set keep-coding-instructions: true in the style's frontmatter).

对 output style 的改动会替换掉默认的 output style(除非你在该风格的 frontmatter 里设置 keep-coding-instructions: true)。

In Claude Code, this would remove instructions that tell Claude it is helping users with software engineering tasks and contains other critical default instructions such as:

在 Claude Code 里,这会移除那些告诉 Claude"你在帮用户完成软件工程任务"的指令,以及其他关键的默认指令,比如:

By default, a custom output style drops all of this and Claude Code becomes more of a general assistant than a software engineer assistant.

默认情况下,一个自定义 output style 会把这些全部丢弃,于是 Claude Code 更像一个通用助手,而非软件工程助手。

An alternative to modifying output styles is the append-system-prompt flag. Whereas modifying output style files can have large, unintended changes to Claude's behavior, the append flag is only additive to the original system prompt. It doesn't modify Claude's role; it just adds instructions to its default role.

修改 output style 之外的另一个选择,是 --append-system-prompt 参数。修改 output style 文件可能对 Claude 的行为造成大而意外的改动,而 append 参数只是在原始系统提示上做加法。它不修改 Claude 的角色,只是在其默认角色之上添加指令。

It is also passed at invocation time, and only applies to that invocation, rather than persisted as a file across sessions.

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

Appending the system prompt can have a higher context cost compared to other methods of passing instructions. It increases input tokens, though prompt caching reduces this cost after the first request in a session. Instructing Claude to use a more verbose or longer style also increases output tokens.

相比其他传递指令的方法,追加系统提示的上下文开销可能更高。它会增加输入 token,不过在会话第一次请求之后,prompt 缓存会降低这一成本。让 Claude 采用更啰嗦或更长的风格,也会增加输出 token。