Claude Code 配置体系 · 学习笔记
Published in：2026-04-12 | category： AI编程

Claude Code 配置体系 — 学习笔记

学习日期：2026-07-03
主题：AI 编程助手的「调教」架构 — 从 Anthropic 官方设计到可迁移的工程思维

一、为什么这件事值得学

Claude Code 的配置体系，表面上是「怎么让 AI 更听话」，底层其实是在回答一个更通用的问题：

如何把「概率性的 LLM」包装成「可预期的工程工具」？

大多数人对 AI 编程助手的用法还停留在：写一段 prompt，希望它每次都照做。但长对话、上下文压缩、任务切换、安全边界——这些真实场景会迅速击穿这种 naive 方案。

Anthropic 官方把 7 种配置方式拆开讲，本质上是在做关注点分离：什么必须常驻、什么按需加载、什么必须确定性执行、什么可以隔离出去。这套思路不只适用于 Claude Code，任何要落地生产的 Agent 系统都值得借鉴。

二、核心认知：上下文是稀缺资源

在深入每种配置之前，先建立一个底层模型：

1
上下文窗口 = 有限的工作台面积

所有配置方式的差异，都可以归结为三个问题：

  1. 什么时候占用了工作台？（加载时机）
  2. 对话变长、要「收拾桌子」时，它还在不在？（压缩行为）
  3. 它占多大面积？（token 成本）

很多人配置 AI 助手时的典型错误：把所有想让它知道的东西都塞进 CLAUDE.md。结果不是 AI 变聪明了，而是：

  • 简单任务也背着几百行无关规范
  • 真正重要的指令被稀释，遵循度下降
  • token 账单无声上涨

我的判断：配置 AI 助手和写软件架构一样 — 不是「能塞多少塞多少」，而是「什么信息在什么生命周期里可见」。

三、七种方式，一张心智地图

我不按官方文档顺序记，而是按信息的生命周期来理解：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
会话启动
  │
  ├─ 始终在场 ────────── CLAUDE.md（根目录）
  │                      Output Styles（替换系统提示）
  │
  ├─ 条件加载 ────────── Rules（读特定路径时）
  │                      子目录 CLAUDE.md（读该目录时）
  │
  ├─ 按需触发 ────────── Skills（用户 / AI 主动调用）
  │                      Append System Prompt（单次 CLI）
  │
  ├─ 隔离执行 ────────── Subagents（独立窗口，只回结论）
  │
  └─ 确定性执行 ──────── Hooks（不经过 AI 决策）

这张地图比记住 7 个名词更重要。遇到新需求时，先问「这条信息属于哪个生命周期」，再选配置方式，而不是反过来。

四、逐层理解 + 个人思考

4.1 CLAUDE.md — 不是百科全书，是索引卡

官方定位：项目手册，放「事实」不放「流程」。

我的理解：

CLAUDE.md 最接近真实团队里的 onboarding 文档 — 新同事第一天需要知道的：用什么技术栈、怎么构建、目录怎么组织、命名有什么规矩。你不会在 onboarding 里塞一份 50 页的部署 runbook，那是运维手册，需要时再去翻。

几个我自己会遵守的原则：

原则理由
200 行以内超出后边际收益为负，指令遵循度反而下降
只写「不变的事实」技术栈、构建命令、目录约定 — 这些不会随任务变
用指针代替全文「部署流程见 /deploy skill」比复制粘贴 30 步强
定期审计项目演进后 CLAUDE.md 容易过时，比没有更糟的是有但错的

一个反直觉的点：CLAUDE.md 越精简，AI 表现往往越好。不是因为 AI 变聪明了，而是因为信号噪声比提高了 — 每条指令的「权重」更大。

4.2 Rules — 精准的「地方法规」

Rules 解决的是 CLAUDE.md 覆盖不了的问题：同一条规范，只在特定文件类型 / 路径下生效。

比如「所有 API handler 必须用 Zod 验证」 — 这条规则对前端改 CSS 毫无意义，加载它纯属浪费。Rules 的 paths 作用域就是为此设计的。

和子目录 CLAUDE.md 怎么选？

  • 规范绑定一个模块目录 → 子目录 CLAUDE.md 足够
  • 规范跨目录生效（如所有 *.test.ts） → 必须用 Rules

我的思考：Rules 本质上是 AI 时代的 .editorconfig / eslint overrides — 按路径施加不同约束。如果你已经在项目里用 lint 规则做分层约束，Rules 的配置思路应该很直觉。

4.3 Skills — 目前最被低估的能力

Skills 的渐进式加载设计，我认为是整个配置体系里最优雅的部分：

1
2
会话开始 → 只加载 Skill 名称 + 一行描述（几乎零成本）
触发时   → 加载完整 SKILL.md（按需付费）

这意味着你可以定义几十个 Skill — 部署、审查、创建组件、写测试、发版 checklist — 而平时它们不占上下文。

为什么我说它被低估？

大多数人把 Skills 当成「高级 prompt 模板」，但它真正的价值是工作流封装：

  • 把重复性、多步骤、需要判断分支的流程固化下来
  • 新人（或未来的自己）不需要重新摸索「审查代码要检查哪些点」
  • 团队可以共享同一套 Skill，减少「每个人 prompt 写法不同导致结果不一致」

一个需要注意的坑：压缩对话时，已触发的 Skills 会按预算重新注入，最早触发的可能被丢弃。所以一次会话里不要贪多 — 聚焦当前任务，完成后再开新会话触发下一个 Skill。

我的实践方向：任何我做过两次以上的多步骤流程，都值得封装成 Skill。判断标准不是「流程复不复杂」，而是「下次还需不需要重新解释一遍」。

4.4 Subagents — 上下文隔离的利器

Subagent 和 Skill 最容易混淆，我的区分标准很简单：

SkillSubagent
执行位置主对话上下文独立上下文窗口
中间过程可见，可干预不可见，只回结论
适合场景需要协作、逐步确认调研、搜索、分析类「只要结果」

典型 Subagent 场景：

  • 在代码库里深度搜索 Bug 根因（中间可能翻几十个文件）
  • 分析日志定位性能瓶颈
  • 调研某个库有没有替代方案
  • 批量迁移（Claude Code 的 /batch 本质就是 Subagent 编排）

我的思考：Subagent 解决的是 LLM 上下文窗口的「污染问题」。调研类任务的中间过程可能产生几万 token 的噪音，如果全堆在主对话里，很快就会把真正重要的上下文挤出去。Subagent 相当于把「脏活」外包出去，主对话保持干净。

这跟微服务里的「异步任务队列」思维类似 — 长耗时、高噪音的任务不应该阻塞主流程。

4.5 Hooks — 唯一确定性的一环

前面所有配置方式 — CLAUDE.md、Rules、Skills — 本质上都是给 AI 的建议。AI 大概率会遵循，但在以下情况下可能失效：

  • 长对话后上下文被压缩
  • 任务复杂，AI 注意力被分散
  • 遇到 prompt 注入（文件里藏了恶意指令）

Hooks 不同：它是自动化代码，绑定到 Claude Code 的生命周期事件，触发即执行，不经过 AI 决策。

1
2
3
PreToolUse   → 工具调用前（拦截危险操作）
PostToolUse  → 工具调用后（自动格式化、跑 lint）
PreCompact   → 压缩对话前（保存关键状态）

我认为最值得记住的观点：

「永远不要做 X」不能靠指令保证，必须靠 Hook + 权限双保险。

这跟软件安全里的 fail-closed 设计一脉相承 — 默认拒绝，显式允许。你不会靠注释防止函数被误调用，你会用类型系统和权限检查兜底。AI 助手的安全边界也应该一样。

典型 Hook 用法：

  • 编辑文件后自动 Prettier（不依赖 AI 记得格式化）
  • 提交前自动 lint
  • 拦截删除数据库迁移文件的操作
  • 完成任务后发通知

判断标准：「每次 X 后必须做 Y」→ 用 Hook，不要写进 CLAUDE.md。

4.6 Output Styles & Append System Prompt — 轻量调参

这两个我用得少，但理解它们的边界很重要：

Output Styles：

  • 注入系统提示词，永不被压缩
  • ⚠️ 会替换默认系统提示词 — 内置的安全行为、修改范围判断等会丢失
  • 内置 Proactive / Explanatory / Learning 三种，够用就别自定义

Append System Prompt：

  • CLI 参数，单次生效，追加而非替换
  • 适合临时调整语气或输出格式
  • 指令越多遵循度越低，别滥用

我的建议：90% 的场景不需要碰这两个。需要改 AI 行为时，优先想能不能用 Skill 或 Rule 解决。

五、决策框架（我自己的版本）

遇到新需求，我按这个顺序想：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
1. 这是「项目事实」还是「操作流程」？
   ├─ 事实 → CLAUDE.md
   └─ 流程 → Skill

2. 这条规范是否只在特定路径下有意义？
   └─ 是 → Rule（带 paths）

3. 中间过程是否很长、且我不需要看到？
   └─ 是 → Subagent

4. 这件事是否「必须发生」，不能依赖 AI 自觉？
   └─ 是 → Hook

5. 这是「绝对不能做」的安全红线？
   └─ 是 → Hook + 权限，不要只写指令

6. 只是临时调整一次会话的行为？
   └─ 是 → Append System Prompt

六、可迁移到 Agent 系统的设计原则

Claude Code 的配置体系，提炼成 4 条可以迁移到其他 Agent 项目的设计原则：

6.1 事实与流程分离

常驻上下文只放「不变的事实」，可变的多步骤流程按需加载。这直接对应软件工程里的「数据与逻辑分离」。

6.2 渐进式披露（Progressive Disclosure）

不要一次性把所有信息塞给 AI。先给索引，需要时再展开。这和 UI 设计里的 progressive disclosure 是同一个思想 — 减少认知负荷，提高信号质量。

6.3 确定性优于概率性

凡是「必须发生」或「绝对不能发生」的事，不要指望 LLM 的概率性遵循。用 Hook、权限、类型系统、中间件等确定性机制兜底。

6.4 隔离执行，避免污染

长耗时、高噪音的任务（搜索、分析、调研）应该在隔离环境中执行，只把结论带回主流程。这跟分布式系统里的 bulkhead pattern（舱壁模式）同构。

七、对我当前工作的启发

结合 Cursor / Claude Code 的日常使用，我打算做的几件事：

  1. 审计 CLAUDE.md：把超过 5 行的流程性内容移到 Skills
  2. 封装重复流程：代码审查、部署检查、新模块脚手架 — 每个做成 Skill
  3. Rules 按路径分层：API 层、DB 层、前端组件层各一套，避免全局加载
  4. 关键安全操作用 Hook：不依赖 AI「记得不要删 migration」
  5. 调研类任务主动用 Subagent：保持主对话上下文干净

八、遗留问题 & 待验证

  • Skills 在团队间共享的最佳实践是什么？Git 管理 vs 个人本地？
  • Subagent 嵌套 5 层的实际使用场景有哪些？是否过度设计？
  • Hook 的性能开销在长会话中是否可感知？
  • Output Style 替换默认提示词后，哪些内置行为会丢失？需要实测清单
  • 这套配置体系迁移到 Cursor Rules / Skills 时的对应关系

九、一句话总结

配置 AI 编程助手，不是在写更好的 prompt，而是在设计一套信息生命周期管理系统 — 什么常驻、什么按需、什么隔离、什么确定性执行。CLAUDE.md 是索引卡，Skills 是工作流，Subagents 是外包，Hooks 是安全网。搞清楚了这四层，7 种配置方式自然各归其位。

本笔记为个人学习总结，参考了 Anthropic 官方博文《Steering Claude Code》及社区解读，加入了个人理解和工程化思考。

AI编程 Agent Claude Code
Prev:
《格鲁夫给经理人的第一课》读书笔记（五）：中层管理者的双重角色
Next:
Claude Code 七种配置方式 · 个人总结