Claude Code 七种配置方式 · 个人总结

看了几篇解读 + 对照官方文档后的自己的理解 · 2026-07-03

先讲清楚：为什么分七种

以前我配置 Claude Code，基本就是往 CLAUDE.md 里堆东西。后来发现两件事：

上下文窗口是硬资源——塞越多，遵循度越差，长对话里尤其明显
「建议」和「必做」是两回事——写在 md 里的是概率性遵守，Hook 才是确定性执行

官方把配置拆成七种，本质上是在回答三个问题：什么时候进上下文、压缩后还在不在、占多少 token。选错位置，等于白写。

我自己的三条判断：

内容类型	放哪
事实（技术栈、命令、目录）	CLAUDE.md
流程（部署、审查、多步 SOP）	Skills
必须发生 / 绝对不能发生	Hooks + 权限

一张表看清七种方式

方式	加载时机	压缩后	Token	性质
根 CLAUDE.md	会话开始，全程在	缓存后重读，不丢	高，每行都占	建议
子目录 CLAUDE.md	读到该目录文件时	丢了，直到再碰该目录	低	建议
Rules（无 paths）	会话开始	重新注入	中	建议
Rules（有 paths）	匹配路径被读时	重新注入	低	建议
Skills	开始只加载名+描述；触发才加载全文	已触发的按预算重注入，最早的先丢	低→中	建议
Subagents	开始只加载名+描述+工具；Agent 工具调用时才跑	主会话只收最终摘要	主会话几乎零	隔离执行
Hooks	生命周期事件	完全绕过压缩	配置不进上下文	确定性
Output Styles	会话开始，进系统提示	不压缩	高，且权重最高	替换/追加系统提示
Append Prompt	CLI 单次传入	不压缩，仅当次	中，首请求后缓存	追加，单次

注：Output Styles 和 Append Prompt 算第七种里的两个变体，官方表格是分开列的。

1. CLAUDE.md — 项目常驻记忆

放什么：构建命令、目录结构、monorepo 布局、命名规范、团队约定——AI 需要始终知道的事实。

不放什么：部署 runbook、审查清单、30 行以上的步骤——这些该进 Skills。

两种加载行为（之前我搞混了）：

类型	行为
根目录	会话开始就加载；会话内 memoized；压缩后会重新读取
子目录（如 `app/api/CLAUDE.md`）	只有 Claude 读到该目录下文件才加载；压缩后会丢，直到再次碰那个目录

子目录 CLAUDE.md 和 path-scoped Rules 的压缩行为一样——这点容易记错。

200 行：官方明确建议上限。不是玄学，是实测：行数多了，无关任务也带着跑，遵循度反而下降。我有过类似体验，把流程全塞 CLAUDE.md 后，长对话里 AI 开始「选择性失忆」。

索引思维：CLAUDE.md 当目录，不当百科全书。

1
2
3

前端规范 → docs/FRONTEND.md
部署 → /deploy 技能
安全策略 → .claude/rules/security.md（path-scoped）

Monorepo：各团队子目录放自己的 CLAUDE.md；用 claudeMdExcludes 跳过不碰的团队目录。组织级安全策略可以 MDM 下发，个人 settings 无法 exclude。

个人 vs 项目：个人偏好（semantic commit、语气）放 ~/.claude/ 用户级；团队约定放项目级。别把个人习惯写进团队 CLAUDE.md。

维护方式：当代码对待——有 owner、PR review、出问题时回溯是不是某条规则太长或被淹没了。

2. Rules — 路径级约束

.claude/rules/ 下的 Markdown，YAML frontmatter 里加 paths 做作用域：

---
paths:
  - "src/api/**"
  - "**/*.handler.ts"
---
所有 API handler 必须用 Zod 校验输入

无 paths 的 Rule = 另一个 CLAUDE.md：会话开始就加载，改文档也带着，浪费 token。写 Rule 如果不加 paths，和直接往 CLAUDE.md 堆没区别。

** vs 子目录 CLAUDE.md**：

规范只跟某个模块目录走 → 子目录 CLAUDE.md
规范跨目录（所有 *.test.ts、所有 migration 文件）→ path-scoped Rule

3. Skills — 按需加载的流程

.claude/skills/<name>/SKILL.md，渐进式加载：

会话开始：只有 name + description（几乎不占 token）
触发时：加载完整 body（/code-review 手动调，或 AI 根据 description 自动匹配）

Commands 已合并进 Skills：.claude/commands/ 还能用但是 legacy；新东西一律放 .claude/skills/。Skills 多了 auto-invocation——AI 看 description 自己决定要不要调，Commands 时代没有这能力。

两种触发模式：

模式	谁控制
用户调用 `/skill-name`	我
auto-invocation	AI 读 description 自行匹配

auto-invocation 写 description 要精准——太宽会误触发，太窄永远调不到。

压缩预算：一次会话触发太多 Skill，压缩后按总预算重注入，最早触发的先被踢。所以大需求别在一个会话里 /grill + /deploy + /review 全跑一遍，分会话更稳。

我的用法：工作流里的 /grill-with-docs、/to-prd、/implement、/review 本质上都是 Skills。Phase 0 规划、Phase 1 实现、Phase 2 审查各开新会话，也是为了避免 Skill 预算和上下文互相污染。

4. Subagents — 隔离干活的

.claude/agents/ 下每个文件一个独立助手，YAML frontmatter 配 name、description、model、tools 等。

和 Skills 的核心区别：

	Skill	Subagent
执行位置	主对话线程	独立上下文窗口
中间过程	全在主对话里	不回主对话
自动触发	可以	不行，必须 Agent 工具显式调用
适合	要看过程、随时干预	只要结论、过程很长

调研 50 个文件找 Bug 根因、扫日志、依赖审计——中间几万 token 的中间结果，主对话不需要看，Subagent 合适。

支持嵌套最多 5 层；/batch 批量迁移本质就是 Subagent 编排。很多工具现在能自动创建 Subagent，但理解「隔离上下文」这个设计点，才知道什么时候该手动 spawn。

我的倾向：implement 阶段仍是一 Issue 一会话 + Skill，不用 Subagent——我要看 diff 过程。调研型、只关心结论的任务才考虑 Subagent。

5. Hooks — 唯一靠谱的「必做」

前面六种本质上都是给 AI 的建议。Hooks 是 harness 在生命周期事件上跑的确定性逻辑，跟模型想不想无关。

注册位置：.claude/settings.json（项目级）或 ~/.claude/settings.json（用户级），也可 managed policy（组织级，用户改不了）。

常见事件：PreToolUse、PostToolUse、PreCompact、SessionStart、Stop 等。

Hook 类型要分清（之前容易误以为全是 shell 脚本）：

类型	是否确定性
command / HTTP / mcp_tool	✅ 确定性
prompt / agent	❌ 仍靠模型判断

经典用法：

PostToolUse：编辑后自动 Prettier / lint
PreToolUse：检测危险操作，exit code 2 拦截工具调用（拦截原因会进上下文让 AI 知道为啥被拒）
PreCompact：压缩前备份对话
Stop：跑测试脚本，不通过不让结束本轮（best practices 里提到的 unattended 验证闭环）

「永远不要做 X」：CLAUDE.md 写「别删 migration 文件」——长会话、压缩、文件里的 prompt injection 都可能破功。真防线是 PreToolUse Hook + Managed Settings 权限，组织级强制的 managed settings 用户本地改不掉。

这跟 fail-closed 设计一脉相承：别指望 AI 自觉，靠类型系统和权限兜底。

6. Output Styles — 慎用的高权重开关

.claude/output-styles/ 注入系统提示，不压缩，且官方说它是七种里指令遵循权重最高的。

自定义 Output Style 默认会替换 Claude Code 内置系统提示——改范围、注释习惯、安全处理、跑测试再收工这些默认行为会全没，变成「通用助手」而非「编程助手」。

frontmatter 里设 keep-coding-instructions: true 可以保留默认编程指令，自定义前先查内置三种：

Proactive — 更主动执行
Explanatory — 详细解释
Learning — 协作学习模式

我基本不用自定义 Output Style——改系统提示的副作用太大，不如 Skills 精准。

7. Append System Prompt — 临时微调

CLI --append-system-prompt，追加不替换，仅当次 invocation 生效，不持久化到文件。

适合：临时调语气、输出格式、加一段领域知识。

限制：追加越多，每条遵循度越低，冲突时更明显。首请求后 prompt caching 会降 input cost，但 verbose 风格会增加 output token。

和 Output Style 对比：Append 是加法、单次；Output Style 是文件级、可能替换默认行为、权重更高。

决策树（我自己用的）

要写一条配置
    │
    ├─ 全局事实，≤200 行          → 根 CLAUDE.md
    ├─ 某模块事实                 → 子目录 CLAUDE.md
    ├─ 跨目录规范                 → Rules + paths
    ├─ 无 paths 的 Rule           → 别写，等于第二个 CLAUDE.md
    ├─ 多步流程 / SOP             → Skills
    ├─ 调研只要结论               → Subagent
    ├─ 每次 X 后必做 Y            → Hook（command 型）
    ├─ 绝对不能 X                 → PreToolUse Hook + 权限
    ├─ 改整体行为模式             → Output Style（先看内置）
    └─ 临时调一次                 → --append-system-prompt

不在「七法」里但经常一起出现的

能力	和七法的关系
Plugins	把 Skills + Subagents + Hooks + Output Styles 打包分享，不是第八种配置方式
MCP Servers	扩展工具面（读 DB、调 API），和「怎么调教行为」是另一条线
Agent Teams	Subagent 的规模化编排，日常多数场景用不到
Permissions / Managed Settings	和 Hook 配合做组织级硬边界

Cursor 侧有 .cursor/rules、.cursor/skills 等平行概念，思路类似：常驻规则 vs 按需技能 vs 确定性 hook。跨工具迁移配置时，先对齐「加载时机」而不是文件名。

设计思想（对我自己的启发）

事实 / 流程分离 — CLAUDE.md 是内存常驻变量，Skills 是按需 import 的函数
作用域收窄 — path-scoped Rules、子目录 CLAUDE.md、Skill 渐进加载，都是在对抗 context bloat
概率 vs 确定 — 「建议 AI 跑 lint」和「编辑完必跑 lint」不是一回事；安全边界必须确定性
隔离 vs 透明 — Skill 透明可干预，Subagent 隔离保主对话干净；选型看你要控过程还是只要结果
配置也是代码 — CLAUDE.md 会膨胀、会过时、会互相打架；需要 owner 和定期 prune

搭自己的 Agent 系统（不限 Claude Code）也适用：把「常驻记忆」「按需 SOP」「硬 guardrail」「后台 worker」分开设计，比一个大 system prompt 靠谱得多。

和我现有工作流的对照

配置原则	我现在的做法	待改进
CLAUDE.md 只放事实	Phase 0 用 `/grill-with-docs` 沉淀到 docs/	检查各项目 CLAUDE.md 是否超标、有无流程混入
Skills 放流程	`/grill-with-docs` → `/to-prd` → `/to-issues` → `/implement` → `/review`	description 写好 auto-invocation 边界
一 Issue 一会话	Phase 1 实现阶段	避免 Skill 预算和上下文交叉污染
审查换 AI	Phase 2 换厂商/换模型	本质是 Subagent/新会话隔离，不是同会话里叠 Skill
Hooks 做确定性	还没系统配	format/lint、危险命令拦截、Stop 前跑测试
索引而非百科全书	docs/ + CONTEXT.md 指针	monorepo 可考虑 path-scoped Rules

一个具体计划：

各 repo CLAUDE.md 审计：流程性内容迁 Skills，超 200 行拆索引
加 PostToolUse format hook，别写在 CLAUDE.md 里赌 AI 记得
加 PreToolUse 拦截 rm -rf、删 migration、动生产配置等
/review Skill 的 description 写清楚触发条件，避免 implement 会话误调
调研型任务试 Subagent，implement 仍保持主对话可见

最后想说的

七种方式看起来多，记一个核心就够：上下文窗口是最 scarce 的资源，确定性和概率性不要混用。

我之前的误区是把所有东西往 CLAUDE.md 塞——省事，但长对话里 AI 反而更不听话。拆成 Facts / Flows / Guards 三层之后，token 省下来，遵循度反而上去。

Output Styles 和 Append Prompt 我日常几乎不用；Hooks 和 path-scoped Rules 是被低估的两块——前者管「必须发生」，后者管「别什么都加载」。Skills 是目前 ROI 最高的投入点，把工作流里重复说的话封装成 /xxx，比每次 copy prompt 强一个数量级。

脑瓜呆呆

记录 Java 后端、中间件和工作中遇到问题的学习笔记。从 2021 年写到现在的个人学习笔记。