Claude Code 指令应存放于何处：CLAUDE.md、路径规则还是钩子？
了解为何 Claude Code 将 CLAUDE.md 视为上下文、如何对其进行精简、按路径设置作用域规则、将必运行步骤移至钩子函数中，以及如何验证实际加载了哪些内容。
来源: 7 CLAUDE.md Patterns That Actually Change How Claude Writes Code
目前大多数使用 Claude Code 的团队都会保留一个 CLAUDE.md 文件，但很少有人能说清楚它究竟发挥了什么作用。常见的情况是该文件内容已增至数百行，模型会执行部分指令而忽略其他指令。解决之道往往不是寻找更好的模板，而是弄清楚文件的实际用途，并将每条指令分配给能够处理它的相应机制。本指南介绍了七种实用方法，从精简文件内容、按路径设置规则、将硬性要求放入钩子函数中，到检查 Claude 实际加载了什么内容。
如果您是从空白文件开始，这份关于编写有效CLAUDE.md的实用指南会介绍相关内容与结构。但这里关注的重点不同：哪些指令应该出现在CLAUDE.md中，其余的又该放在何处。
CLAUDE.md是上下文，而非配置
其他所有问题都源于这一误解。Claude Code会将该文件作为消息注入对话中，它并不会被合并到系统提示词中，运行时也没有任何机制来强制执行它。模型会读取该文件并尽力遵循其中的指示，除此之外并无其他保障；而当表述模糊或存在相互矛盾的指令时，这种保障的可能性会更小。
一个实用的心智模型是为技术娴熟的队友准备的交接备忘录，他们可以在喝晨间咖啡时快速浏览，随后便投入实际工作中。经过这一流程筛选后留下的，只有那些简短、具体且逻辑一致的内容。因此，长度、精确度以及内部一致性才是你真正可以掌控的因素，而非风格问题。
确保主文件行数不超过200行
目前的建议是保持文件行数在200行左右。超过这个限度，文件会占用更多的上下文空间，遵守规则的难度也会随之增加而非降低。
这看似违反直觉：指令越多，实际被遵循的反而越少。每一行都会与其他所有行以及对话内容争夺有限的注意力。试想一个文件已有340行的团队，将其缩减到约120行后，Claude就能更可靠地遵循这些指令。被删除的行并非错误，只是叠加在重要指令之上的冗余信息而已。
此外还存在一个硬性上限，不过你应避免刻意设计来突破它：根据撰写本文时的文档说明，超过4 MiB的文件会被完全跳过。在文件大小接近该数值之前，其指令遵循度就已经开始下降。
删除Claude可从代码库中获取的内容
最有效的编辑规则很简单：删除 Claude 通过阅读代码库就能理解的内容。这与 Claude Code 自带的 /doctor 检查功能所建议的删减方式一致，该功能会移除文件夹结构、依赖项列表以及高层架构描述，但会保留那些可能存在的隐患、设计思路以及偏离工具默认设置的习惯。换句话说，它颠倒了这些文件通常包含的内容。
需要删除的内容：
- 文件夹结构，因为 Claude 本身就能列出目录。
- 依赖项列表，这些信息已记录在
package.json中。 - 关于架构的叙述性概述，代码能更准确地表达这些内容。
需要保留的内容：
- 看似错误但实际上是刻意设计的代码。
- 放弃显而易见解决方案的原因。
一个好的测试标准是：如果一名技术娴熟的工程师在打开代码库后能在十分钟内掌握它，就无需将其收录；如果只有通过出错才能了解其功能，才应记录下来。
以零成本为人类留下注释
在文件内容传递给 Claude 之前，块级 HTML 注释会被移除。这让你可以为维护文件的人添加注释而不消耗模型的任何计算资源，例如记录某个部分为何被移动：
<!-- Deleted the API section — moved to .claude/rules/api.md, Sep 2026 -->
你的团队成员可以看到这些历史记录；模型则无需为此付费。
@imports 可整理文件但不会保存上下文
当 CLAUDE.md 文件变得过长时，人们通常会将其拆分成多个文档并导入：
@docs/architecture.md
@docs/api-conventions.md
@docs/testing.md
这看起来像是懒加载，但实际上并非如此。导入的文件会在启动时与引用它们的CLAUDE.md一同被展开并加载到上下文中。即便将340行内容拆分成四个独立的文件，最终加载的仍然是同样的340行。
导入功能确实有实际用途。它们有助于整理代码结构，还能让你在多个工具之间共享同一套标准化的说明文档。如果某个仓库已经存在AGENTS.md文件，那么在CLAUDE.md中只需添加一条@AGENTS.md指令，就能避免维护两份不同的版本。不过不要指望它们能减少上下文的使用量。对于那些只需在特定情况下才需要加载的指令，就需要使用基于路径的条件规则。
利用 .claude/rules 和路径来限定条件规则的适用范围
.claude/rules/目录中的文件可在其前置信息中声明paths字段。这一功能实现了人们对于导入功能的期望：全局范围的规则在Claude读取或编辑对应文件之前不会被激活。API规则文件的前置信息可能如下所示：
---
paths:
- "src/api/**/*.ts"
---
在前置信息之后，规则主体则包含仅适用于该部分结构的规范，比如输入验证、统一的错误格式以及允许使用SQL的位置：
# API rules- Every endpoint validates input before touching the database
- Errors use the standard envelope in `src/api/errors.ts`
- No direct SQL outside `src/api/repositories/`
这样一来，前端开发无需为API相关的规范支付令牌费用，而API开发则无需为测试相关规范付费。
实际上，这就是解决 CLAUDE.md 内容过于冗杂的良方。按主题划分内容，将每个主题对应到其所属的目录中，而将根目录留给对整个项目都适用的通用指南。没有 paths 字段的规则文件会在每次会话中都被加载，因此应将其视为一种刻意的设计选择而非默认行为。
Globs 支持大括号扩展，因此一条规则即可覆盖多种文件扩展名以及不同的匹配模式：
---
paths:
- "src/**/*.{ts,tsx}"
- "tests/**/*.test.ts"
---
必须执行的步骤应放在 hooks 中
“每次提交前进行代码检查”、“不要直接推送到 main 分支”或“编辑完每个文件后都要格式化”这类要求在 CLAUDE.md 中很常见。这些规则大多数情况下都会被遵守，一旦出现例外情况就会引起注意，进而让团队认为该模型不可靠。
但这正是有文档记载的行为：CLAUDE.md会影响Claude的运作，却无法保证其一定如此。对于那些必须在会话生命周期中的特定时刻执行的操作，钩子会在该时刻运行Shell命令，而无需考虑模型的判断。甚至PreToolUse钩子可以完全阻止工具调用，这是任何加粗或大写的Markdown格式都无法做到的。
区分不同类型指令的实用方法如下：
- Claude通常应遵循的惯例写在CLAUDE.md中。
- 代码库中某个特定领域的规则则放在
.claude/rules/目录下，并指定相应的paths。 - 不允许有任何异常的情况会被转化为钩子。
- 可重复的多步骤流程则被定义为技能。
将少数“始终生效”的规则移至 hooks 中有双重好处：这些要求现在能够真正得到执行，同时文件中也去掉了那些永远无法生效的代码行，从而让更多精力集中在那些确实有效的指令上。
验证实际加载了什么
运行 /context 并查看其内存文件部分，那里会准确显示当前运行会话已加载的内容。/memory 则通过列出用户级和项目级的文件并允许你打开它们来补充这一功能。二者结合可将“Claude 是否忽略了这些内容？”这类疑问从猜测变为可验证的事实。令人惊讶的是，花时间去完善那些根本未被加载的文件的表述其实相当简单。
多个合并文件之间的矛盾
没有任何内容会被覆盖，所有文件都会被拼接在一起。Claude Code从工作目录开始，逐层向上遍历文件系统根目录，沿途收集所有的CLAUDE.md文件，然后按从根到叶的顺序排列。如果在某一层级同时存在CLAUDE.local.md文件，那么该文件会跟随其兄弟文件CLAUDE.md一同处理。在单仓库项目中，两个文件很可能会给出相互矛盾的指引；遇到这种情况时Claude可能会直接选择其中一个，而不会向你提示任何冲突信息。
你并未请求的父级文件
如果上级目录中的CLAUDE.md文件混入了你的会话中，你可以在本地设置中使用claudeMdExcludes选项通过通配符来排除这些文件。
压缩后仍保留的内容
/compact操作后会从磁盘重新读取项目根目录下的CLAUDE.md并再次注入，因此其中的指令会保留下来。仅在对话中提及的内容则会丢失。如果每次压缩后都反复进行同样的修正，那就说明这些内容应该被写入文件中。
初始蓝图
如果要从头开始编写配置文件，一个合理的目标结构如下：
- 根目录下的CLAUDE.md文件行数控制在120行左右，仅包含适用于所有场景的规则。
- 条件性指导规则存放在
.claude/rules/目录中，并使用路径通配符表示。 - 每一项必须始终遵守的“恒定”要求都通过钩子函数实现。
- 不会存在那种仅阅读仓库十分钟就能掌握的内容。
- 每次修改后都要快速执行
/context检查。
包括需要单独说明的自动记忆等功能在内的完整参考信息，可在 Claude Code 的内存文档中找到。其行为和限制会不断变化，因此当实际效果与预期不符时请查阅该文档。
核心要点
- 为供人阅读的同事编写 CLAUDE.md，而非供机器执行的文件：内容要简短、具体且无矛盾。
- 更短的文件更容易被准确遵循；凡是代码库已告知 Claude 的内容都应删除。
- 导入功能虽能重新组织内容，但会加载所有内容；真正实现延迟加载的是路径范围的规则。
- 任何需要每次都执行的操作都需要通过钩子实现，因为上下文仅能影响行为。
- 在调整措辞之前，应将
/context视为真实信息来源。