【Claude Code七种自定义指令方式技术解析】从CLAUDE.md到Hooks的选择指南

文章目录Claude Code七种自定义指令方式技术解析从CLAUDE.md到Hooks的选择指南一、引言二、三个决定因素加载时机、压缩行为、上下文成本三、七种自定义指令方式逐一拆解3.1 CLAUDE.md项目根基说明书3.2 Rules无范围规则与路径范围规则3.3 Skills按需调用的技能包3.4 Subagents隔离上下文运行的子智能体3.5 Hooks生命周期事件触发的确定性自动化3.6 Output Styles注入系统提示、永不压缩的方式3.7 附加系统提示append-system-promptCLI 标志仅单次有效四、横向对比全景表五、决策指南什么场景该用什么六、工程实践组合使用的建议七、总结Claude Code七种自定义指令方式技术解析从CLAUDE.md到Hooks的选择指南一、引言亲爱的朋友们创作不容易若对您有帮助的话请点赞收藏加关注哦您的关注是我持续创作的动力谢谢大家有问题请私信或联系邮箱jasonai.fngmail.com很多人用 Claude Code 的方式是把所有要求一股脑塞进CLAUDE.md——构建命令、编码规范、部署清单、团队约定全堆在一个文件里。结果是文件越写越长超过 200 行之后重要信息被淹没在细节里会话跑久了上下文被挤占Claude 该记住的规则反而被压缩掉了。问题的根源在于CLAUDE.md只是 Claude Code 提供的七种自定义指令方式之一而不是唯一的答案。官方博客《Steering Claude Code: skills, hooks, subagents and more》系统梳理了这七种方式——CLAUDE.md、规则Rules、技能Skills、子智能体Subagents、钩子Hooks、输出样式Output Styles、附加系统提示append-system-prompt——并指出它们本质上都在控制同一组变量指令什么时候加载进上下文、压缩时会发生什么、要花多少 token 成本。理解这三个变量才能判断一条指令到底该放在哪里。本文逐一拆解这七种方式的技术细节并给出组合使用的实践建议。二、三个决定因素加载时机、压缩行为、上下文成本在具体讲七种方式之前先明确评判标准——每一种方式都是这三个变量的不同组合变量含义加载时机When指令是会话一开始就常驻上下文还是等到被调用时才加载压缩行为Compaction当 Claude Code 对长会话历史做上下文压缩时这条指令会被保留、重新注入还是直接丢失上下文成本Cost这条指令长期占用了多少 token 预算七种方式的核心区别就是这三个变量的排列组合不同——先记住这个框架后面每一种方式的设计动机都能对应上。三、七种自定义指令方式逐一拆解3.1 CLAUDE.md项目根基说明书CLAUDE.md分为两种类型行为差异很大类型加载时机压缩行为上下文成本根目录 CLAUDE.md会话开始时加载整个会话期间常驻记忆化缓存压缩后重新读取高子目录 CLAUDE.md如app/api/CLAUDE.mdClaude 读取该目录下文件时按需加载压缩后丢失低根目录CLAUDE.md适合放全局性、贯穿始终的内容构建命令、目录结构说明、单仓monorepo整体布局、编码规范、团队约定。子目录CLAUDE.md适合放局部性的约定比如某个子系统特有的接口规范不需要在处理其他模块代码时也占着上下文。工程建议把根目录CLAUDE.md控制在 200 行以内明确文件所有者像对待代码一样 review 它的变更在单仓项目里可以给各团队建各自的子目录CLAUDE.md并通过claudeMdExcludes配置跳过与当前任务无关团队的文件避免无谓的上下文消耗。3.2 Rules无范围规则与路径范围规则规则存放在.claude/rules/目录下的 Markdown 文件中分为两种作用域---paths:-src/api/**-**/*.handler.ts---所有 API 处理程序必须在处理请求前使用 Zod 校验输入参数。无范围规则不带pathsfrontmatter机制上等同于写进CLAUDE.md——会话开始时始终加载始终占用 token。路径范围规则带pathsfrontmatter只有当 Claude 实际接触到匹配路径的文件时才加载对应规则压缩后会按需重新注入。路径范围规则解决的正是文件特定约束这类问题——比如某个目录下的数据库迁移文件只能追加、不能修改历史记录这种规则只在触碰到相关文件时才有意义写进全局CLAUDE.md纯属浪费上下文。3.3 Skills按需调用的技能包技能存放在.claude/skills/目录下每个技能是一个文件夹包含一个SKILL.md文件内含名称、描述和具体执行内容。加载机制的关键点会话开始时只有技能的名称和描述被加载进上下文只有当 Claude 实际调用这个技能通过斜杠命令或任务自动匹配时SKILL.md的完整内容才会加载。已调用过的技能内容会按 token 预算重新注入预算不够时最旧的会最先被清理。这种先加载摘要、按需加载全文的设计渐进式加载意味着即使技能内容很长比如一份完整的部署清单或发布流程只要没被调用几乎不占用上下文——这跟CLAUDE.md全程常驻的成本模型完全不同。判断标准很简单如果你发现自己在对话里反复粘贴同一套操作手册这就是该做成技能的信号。3.4 Subagents隔离上下文运行的子智能体子智能体配置存放在.claude/agents/目录下的 Markdown 文件中frontmatter 里定义名称、描述以及可选的模型和工具访问权限。核心机制子智能体在自己全新的上下文窗口里运行独立处理任务只把最终消息通常是多个子任务聚合后的结果摘要连同元数据一起返回给主对话——过程中产生的所有中间上下文都不会污染主会话。子智能体支持嵌套最深可以嵌套到五层。这个特性决定了子智能体最适合应该被隔离执行、只需要一个摘要结果的工作比如深度代码搜索、日志分析、依赖审计——这些任务过程中会产生大量探索性上下文读了几十个文件、跑了很多次搜索但主对话真正需要的只是结论。3.5 Hooks生命周期事件触发的确定性自动化钩子注册在settings.json、企业管理策略设置或技能/子智能体的 frontmatter 中在文件编辑、工具调用、会话开始等生命周期事件被触发时执行。钩子分两类类型说明确定性钩子command执行命令、HTTP、mcp_tool行为可预测、可复现非确定性钩子prompt、agent本质上还是调用模型做判断典型用途包括文件保存后自动跑 linter、把关键操作结果推送到 Slack、拦截特定危险命令的执行。钩子最关键的优势它的配置本身存在于主上下文之外——是 harnessClaude Code 运行时直接执行的处理程序而不是需要加载进 Claude 上下文、由模型记住并遵守的指令。这意味着钩子实现的规则是结构性保证不存在模型可能忘记遵守的问题这也是为什么绝对不能做某事这类强约束应该用 PreToolUse 钩子而不是写在CLAUDE.md里提醒模型。3.6 Output Styles注入系统提示、永不压缩的方式输出样式存放在.claude/output-styles/目录下内容会被直接注入到系统提示system prompt中。关键特性每个会话开始时加载第一次请求后被缓存永不被压缩——在七种方式里权重最高因为它直接改写了 Claude 的系统提示层而不是作为对话上下文的一部分存在。Claude Code 内置了 Proactive、Explanatory、Learning 等输出样式可供选择。重要提醒自定义输出样式会替换默认输出样式除非显式设置keep-coding-instructions: true保留默认的编码相关指令——这是最容易踩的坑自定义输出样式如果没处理好这个开关可能导致原本内置的编码行为规范被意外覆盖。3.7 附加系统提示append-system-promptCLI 标志仅单次有效通过命令行标志传入claude --append-system-prompt本次任务优先使用函数式编程风格避免可变状态这种方式只在原始系统提示基础上追加内容不会替换或修改 Claude 的角色定位仅对本次 CLI 调用生效会话内第一次请求后同样会被缓存。适合传入编码标准、输出格式偏好、特定领域知识这类一次性、临时性的补充说明。需要注意的限制塞进去的指令越多Claude 严格遵守每一条的程度反而越低——这不是这种方式独有的问题但在这里因为是一把梭式追加更容易被滥用成大杂烩指令效果反而打折扣。四、横向对比全景表方式存放位置加载时机压缩行为上下文成本适用场景CLAUDE.md根目录项目根目录会话开始全程常驻记忆化缓存压缩后重新读取高构建命令、目录结构、编码规范CLAUDE.md子目录各子目录读取该目录文件时按需加载压缩后丢失低子目录特定约定Rules路径范围.claude/rules/匹配路径时加载压缩时重新注入中等文件特定约束如迁移仅追加Skills.claude/skills/名称/描述常驻调用时加载全文按预算重新注入最旧先删低部署清单、发布流程等程序化工作流Subagents.claude/agents/名称/描述常驻调用时启动仅返回最终消息低深度搜索、日志分析等隔离任务Hookssettings.json等生命周期事件触发绕过压缩不在模型上下文内低确定性自动化linter、备份、拦截命令Output Styles.claude/output-styles/每次会话开始永不压缩高重大角色/行为转变append-system-promptCLI 标志会话开始永不压缩中等单次编码标准、格式偏好补充五、决策指南什么场景该用什么需求场景不应该用应该用“每次遇到 X 就自动做 Y”写在 CLAUDE.md 里提醒模型Hookssettings.json中配置“绝对不能做某件事”CLAUDE.md 里的强调性提示PreToolUse 钩子或企业级 Managed 设置一套 30 行左右的操作流程塞进 CLAUDE.mdSkills.claude/skills/某个 API 目录特有的规则无路径范围的全局规则带paths:的路径范围规则个人使用习惯偏好写进项目级 CLAUDE.md影响所有协作者用户级本地配置文件需要跑大量探索但只要结论在主对话里直接跑Subagents隔离上下文只回传摘要临时改变本次输出风格长期修改 output-stylesappend-system-promptCLI 标志判断的核心逻辑是先问这条指令要不要一直生效、要不要占主对话的上下文、能不能用确定性代码替代模型的记忆——凡是能交给钩子做的确定性操作就不要指望模型每次都记得遵守写在文字里的规则。六、工程实践组合使用的建议实际项目中这七种方式往往是组合使用而不是二选一项目结构示例 ├── CLAUDE.md ← 全局构建命令、目录结构200行 ├── app/api/CLAUDE.md ← API 子系统特有约定 ├── .claude/ │ ├── rules/ │ │ └── migrations.md ← paths范围迁移文件仅追加规则 │ ├── skills/ │ │ └── release-checklist/ ← 发布清单按需调用 │ ├── agents/ │ │ └── log-analyzer.md ← 隔离运行的日志分析子智能体 │ ├── output-styles/ │ │ └── concise.md ← 项目统一的简洁输出风格 │ └── settings.json ← 钩子配置PreToolUse拦截危险命令这套组合的分工逻辑很清晰CLAUDE.md兜底全局上下文路径规则处理局部强约束技能封装可复用的程序化流程子智能体隔离探索性任务钩子兜底绝对不能出错的确定性规则输出样式统一团队风格——七种方式各司其职而不是全部压在一个文件里。七、总结维度核心要点判断框架加载时机、压缩行为、上下文成本三个变量决定每种方式的适用场景CLAUDE.md全局常驻适合构建命令与编码规范控制在200行以内Rules路径范围规则避免无关上下文消耗适合文件特定强约束Skills名称常驻按需加载全文适合程序化工作流共享token预算Subagents隔离上下文运行只返回最终消息适合并行/探索性隔离任务Hooks绕过模型上下文由harness直接执行适合确定性自动化Output Styles注入系统提示、永不压缩适合重大角色/行为转变append-system-promptCLI单次生效适合临时性编码标准补充七种方式没有优劣之分只有场景是否匹配——把它们都理解为控制同一组变量的不同旋钮而不是七个孤立的功能点才能真正搭建出一套既省 token、又可靠的项目级 Claude Code 配置体系。参考资料Steering Claude Code: skills, hooks, subagents and more — Claude by AnthropicCreate custom subagents — Claude Code Docs7 Ways to Steer Claude Code: CLAUDE.md, Skills, Hooks, Rules, Subagents and More — Automata AI