本文源自一个真实的中大型前端项目（Taro + React + MobX）在半年内 Claude Code 配置从「乱麻」到「四层清晰」的完整演进过程。
面向对象：已经在用 Claude Code、写过一些
CLAUDE.md/Agent/Skill、但发现「越用越慢、越用越飘」的团队。
一、先说痛点：你是不是也踩过这三个坑
用 Claude Code 三个月之后，我发现团队里几乎所有人都会经历同一条曲线：
第一阶段（蜜月期）：一个 CLAUDE.md 走天下，几十行搞定，AI 挺听话。
第二阶段（补丁期）：AI 生成的代码开始出问题——组件里塞 MobX、样式用了 BEM、className 用中划线……于是每发现一个错，就往 CLAUDE.md 里加一条规则。
第三阶段（膨胀期）：CLAUDE.md 涨到 800 行；又觉得该拆，于是开始建 Agent、建 Skill、建 rules/。结果同一条规则在四个文件里各写了一遍。
第四阶段（崩溃期）：
- 每次对话 Token 消耗大得离谱，长会话动不动被压缩；
- AI 反而抓不住重点，关键的架构约束被埋在几十条格式规范里；
- 改一条 MobX 规则，要在 rules、Agent、Skill 里各改一次，还经常漏改；
- 团队新人打开项目，光读配置就要一个小时。
一句话总结这个坑：
Claude Code 的规则不是越多越好，也不是越少越好，而是「该出现的时候出现」——按需加载才是设计意图。
这篇文章要解决的核心问题就是：如何把配置合理拆分到五层，让每一层都做自己该做的事，做到只引用不复制、只按需不常驻。
二、认清 Claude Code 的四个配置角色
在动手瘦身之前，必须先搞清楚 Claude Code 里四个核心概念的职能边界。这一步没搞清，怎么拆都是错的。
| 角色 | 加载时机 | 定位 | 一句话职能 |
|---|---|---|---|
| CLAUDE.md | 常驻每次对话 | 项目名片 + 路由表 | 「你是谁 / 你要去哪」 |
Rules（.claude/rules/） | 冷启动自动加载（常驻上下文） | 团队铁律 / 极简硬约束 | 「不能做什么」 |
Skill（.claude/skills/） | 触发式按需加载 | 操作手册 / 模板 / 案例 | 「怎么一步一步做」 |
Agent（.claude/agents/） | 主 Claude 主动调用 | 专业角色扮演器 | 「谁来做这件事」 |
划重点：这四个东西的加载时机完全不同。CLAUDE.md 和 rules 冷启动就会自动装进上下文，写多一行就贵一分——所以 rules 也只适合放极短的硬约束，稍微长一点的规则就应该下沉到 skill；skill 是命中触发词才加载；Agent 是主 Claude 判断路由后才调用。
所以规则该放哪一层，判断标准是两个维度——使用频率 + 内容长度。
高频 · 极短 ──► CLAUDE.md（路由表 / 项目名片）
高频 · 极短 ──► rules/ （只写"不能做什么"，一行一条）
高频 · 中长 ──► skills/ （写代码前触发加载，避免常驻）
低频 · 详细 ──► skills/ （场景专属手册）
主动调用 ──► agents/ （专业角色）
⚠️ rules 的容量红线：rules 内容越多，冷启动 Token 消耗越大。中长内容宁可放 skill 也不要塞 rules——skill 是按需加载模型，把中长规则收敛进 skill 才是符合 Claude Code 设计意图的做法。
三、每一层该放什么？不该放什么？（附对比案例）
3.1 CLAUDE.md —— 只做「路由表 + 项目名片」
CLAUDE.md 是每次对话都常驻上下文的文件，它的每一行都要用 Token 换。所以只写两类内容：
- 触发词路由表：告诉主 Claude「用户说什么关键词，就去调用哪个 Agent 或 Skill」
- 项目名片：一个表格说清项目类型、技术栈、目录结构
✅ 正确示例
## 🔴 前端任务调度规则（必须遵守）
| 任务类型 | 触发关键词 | 调用方式 |
|---------|-----------|---------|
| Figma 设计稿 | figma.com 链接 / 实现 Figma | Skill: figma-to-code |
| 创建新页面 | 创建页面 / 新建模块 | Agent: taro-developer |
| 代码审查 | 代码审查 / code review | Agent: taro-code-reviewer |
| 性能检查 | 性能分析 / 白屏 / 卡顿 | Agent: taro-performance-expert |
## 📊 项目概览
| 项目属性 | 说明 |
|---------|------|
| 项目类型 | 移动端微信小程序（Taro 3.x） |
| 核心技术栈 | Taro 3.6 + React 17 + MobX 4 |
| 设计规范 | 750px 设计稿，Taro 自动转换 |
为什么这样最优：主 Claude 一眼扫完这两张表，就知道「用户想干嘛、该调谁、该按什么栈干」——路由决策只需要这么多信息。
❌ 错误示范
## MobX 使用规范
useLocalStore 的完整用法如下：
（此处 500 行详细代码示例）
## 样式完整指南
（此处 300 行 SCSS 教程）
## 命名规范全清单
（此处 200 行细节）
这些东西根本不该常驻。它们属于「写代码前才需要」的内容——放到 skill 里，写代码时再触发加载进来。
修改前后的实际收益
某项目 CLAUDE.md 瘦身对比：
| 阶段 | 行数 | 每轮对话常驻 Token |
|---|---|---|
| 瘦身前 | 1500+ | 约 12,000 |
| 瘦身后 | < 150 | 约 1,200 |
Token 直接降到 1/10，路由能力反而更强。
3.2 rules/ —— 只写「极短的铁律」，不写「教程」
rules/ 目录会被冷启动自动加载，也是常驻上下文。所以它的容量红线比很多人想的更紧——只适合放极短的硬约束，一条规则最好一行搞定，稍微中长的内容就该下沉到 skill。
一句话原则：rules 是「禁止清单」，不是「使用手册」。
内容长度参考
| 内容长度 | 归属 |
|---|---|
| 一行一条的禁止项 | ✅ rules |
| 一句话的正向硬约束（配链接） | ✅ rules |
| 3-5 行以上的规则解释 | ⚠️ 边界，能下沉就下沉到 skill |
| 带代码示例的规则 | ❌ 不要放 rules，一律 skill |
| 完整使用教程 | ❌ 一律 skill |
✅ 推荐拆分方式
.claude/rules/
├── 000-forbidden.md # 禁止项（负向清单）
├── 100-tech-stack.md # 技术栈硬约束（正向定义）
├── 200-checklist.md # 交付前自检
└── 300-naming.md # 命名规范
编号前缀的巧思：加载按字典序，000-forbidden 优先看，让 AI 先知道「哪里是雷区」再干活。
✅ 铁律的正确写法：可执行、可检查
❌ 禁止使用 React Class 组件写法，全部使用函数组件 + Hooks
❌ 禁止组件使用 MobX Store 和 useObserver 包装
❌ 禁止 SCSS 使用 // 单行注释，只使用 /* */ 块注释
❌ 禁止手写 vw 单位，750 设计稿直接写 px
特点：
- 一条一行；
- 有明确的判断标准（class / MobX / // / vw）；
- 不解释为什么——那是 Skill / Agent 的事。
❌ 反面：把教程塞进 rules
## MobX 完整使用指南
### 1. 什么是 useObserver
useObserver 是 MobX-React-Lite 提供的 Hook……
### 2. 使用步骤
第一步：……第二步：……
（此处 500 行教程）
这些内容应该在 skills/taro-developer-create-page/ 里，写代码前触发加载。放 rules 是给冷启动每次都收「教程 Token 税」。
判断标准：如果一段规则在 rules 里超过 5 行、需要举例说明、或者要贴代码，那就是信号——它已经不适合 rules 了，应该搬到 skill。
✅ 正反引用而不复制
一条 MobX 规则的正确组织：
- 权威定义：只写在
rules/100-tech-stack.md rules/000-forbidden.md里写：> 正向规范详见 100-tech-stack.md#mobxagents/taro-developer.md里写：遵循 rules/100-tech-stack.md 的 MobX 规范skills/create-page/SKILL.md里写：详细规则见 rules/100-tech-stack.md
改动时只改一处，其他自动生效。 这是最容易出问题、也是收益最大的一条原则。
3.3 skills/ —— 操作手册，按触发词加载
Skill 是 Claude Code 中最符合「按需加载」设计意图的机制。它就是给 AI 准备的"如果发生 X 场景，就打开这本手册照做"。
真正复杂的东西——完整模板、生成步骤、代码示例、场景专属规则——全部应该收进 skill，不要放在常驻上下文。
✅ 真实项目 skill 拆分
.claude/skills/
├── figma-to-code/ # Figma 转代码
├── taro-developer-create-page/ # 创建页面
├── taro-developer-create-component/ # 创建组件
├── api-parser-core/ # API 解析核心
├── api-parser-normalizer/ # API 归一化
├── api-parser-yapi-mcp/ # YAPI 接入
└── commit/ # 提交规范
观察点：api-parser 被拆成 3 个 skill 而不是一个大而全，因为不同子任务的触发词不同，一起加载浪费上下文。
✅ 触发词是 Skill 的生命线
Skill 的 description 首句就是触发白名单，必须跟 CLAUDE.md 路由表逐字对齐：
✅ 正确：
description: Figma 设计稿转 Taro 页面/组件。
触发场景：
- 用户提供 figma.com 链接
- 要求从 Figma 设计稿生成代码
- 要求解析 Figma 设计稿
❌ 错误：
description: 一个很有用的前端工具
# 什么时候触发？没人知道，AI 也不知道
✅ Skill 内部再分层
skills/taro-developer-create-page/
├── SKILL.md # 触发条件 + 简要流程（先加载）
└── references/ # 详细模板（Claude 判断需要时才 Read）
├── use-store-js.md
├── constant-js.md
└── index-scss.md
SKILL.md 触发时加载，references/ 是二次按需——同一个 Skill 内部也能再拆按需层次，这一点特别值得抄作业。
3.4 agents/ —— 专业角色扮演器，不是知识仓库
Agent 是"专业角色"，不是"文档合集"。它的核心价值是职责隔离，而不是「什么都能做」。
✅ Agent 的严格边界
真实项目里的 Agent 分工：
| Agent | 职责 | 严禁 |
|---|---|---|
taro-developer | 前端开发、修改代码 | 不做审查、不做安全扫描 |
taro-code-reviewer | 代码审查 | 不改代码 |
taro-performance-expert | 性能分析 | 只读、不主动改业务代码 |
taro-security-auditor | 安全审计 | 只读、不主动改构建配置 |
taro-api-parser | API 文档解析 + service 生成 | 不做业务开发 |
关键原则：一个 Agent 只做一件事，绝不越权。
✅ Agent prompt 该写什么
应该写：
- 决策流程（"收到需求先做什么，再做什么"）
- 与主 Claude 的协作协议
- 3-5 个高价值案例（教学式）
不应该写：
- 详细技术教程（下沉到 skill）
- 完整禁止清单（引用 rules/）
- 穷举式案例列表（token 爆炸）
❌ 反面案例：越权的万能 Agent
❌ taro-developer 里塞进：
- 代码开发流程 ✅（正确）
- 代码审查规范 ❌（越权！该在 taro-code-reviewer）
- 性能分析方法 ❌（越权！该在 performance-expert）
- 安全审计规则 ❌（越权！该在 security-auditor）
问题：单个 Agent prompt 上万字，调用一次 token 爆炸；职责混乱，审查代码时反而想改代码。
修复后单个 Agent prompt 平均减少 70%。
✅ Agent 是「加载责任下沉」的关键节点
这是我在整套设计里觉得最优雅的一点：
主 Claude 收到"审查这个页面"的需求
│
├─ 主 Claude 不读项目决策文档（省 token）
├─ 主 Claude 不读代码审查详细规范（省 token）
│
└─ 调用 taro-code-reviewer Agent
│
├─ Agent 才去 Read rules/000-forbidden.md
├─ Agent 才去 Read 项目决策文档
└─ Agent 才加载审查专属规范
主 Claude 只做路由，专业上下文交给 Agent 自己加载。 这样主 Claude 的上下文永远瘦。
四、四条心法：搞懂了配置就不会飘
心法一：按需加载 > 分层
分层只是手段，按需加载才是本质。判断一段内容归属，先别问「它是啥类别」，而是问：
它需要被多频繁地读取？
├─ 每次任务都用？ → 常驻（CLAUDE.md / rules）
├─ 特定场景才用？ → 触发加载（skills / agents）
└─ 极少数场景才用？ → 按需 Read（local.md 里 Read 特定文件）
心法二：引用而不复制
同一条规则的权威定义只能存在于一个文件，其他地方只能用链接引用。
规则重复是所有配置腐化的起点。一旦复制了，就会分叉；一旦分叉了，就会打架；一旦打架了，AI 就会飘。
心法三：加载责任下沉到执行者
上下文应该在"需要它的执行者"那里加载，而不是在调度者这里加载。
主 Claude = 调度者，它只需要知道「用户想干嘛，该派谁去」。 Agent / Skill = 执行者，它自己去加载专业上下文。
这个原则一旦想通，配置架构自然就清晰了。
心法四：优先级必须显式声明
多人协作 + 个人私有配置时，一定要写清楚：
优先级从高到低：
1. .claude/rules/ ← 团队铁律（最高）
2. CLAUDE.md ← 团队路由表
3. agents/ + skills/ ← 执行手册
4. CLAUDE.local.md ← 个人索引
5. 个人决策文档 ← 个人偏好（最低）
冲突时永远以更高层为准。
为什么重要：防止某个成员的个人偏好悄悄覆盖团队规范。
五、反模式清单：这些坑我全踩过
| 反模式 | 症状 | 后果 | 修复 |
|---|---|---|---|
| 规则复制 | 同一条规则出现在 3+ 个文件 | 维护出现版本分叉 | 定权威位置，其他改链接 |
| CLAUDE.md 膨胀 | 超过 200 行 | 常驻 Token 浪费 | 拆分到 rules/ 和 skills/ |
| rules 膨胀 | 有规则超过 5 行 / 带代码示例 | 冷启动 Token 浪费 | 中长规则下沉到 skills/ |
| Agent 塞满知识 | prompt 上万字 | 单次调用 token 爆炸 | 案例精简到 3-5 个 |
| Skill 触发词模糊 | description 没写触发场景 | 该加载时不加载 | 首句必须是白名单 |
| 规则重定义 | 个人配置悄悄覆盖 rules | 团队协作不一致 | 显式声明优先级 |
| 一次性瘦身 | 只做过一次整理 | 半年后重新腐化 | 建立季度审计机制 |
六、瘦身操作 SOP：三阶段落地
阶段一：审计（P0，先干这个）
# 1. 搜索一条关键规则在配置文件里出现多少次
grep -rn "useObserver" .claude/ CLAUDE.md
# 2. 目标：权威定义 1 处 + 链接引用 N 处
# 3. 找到不是链接的多余定义，全部改成引用
产出：一份「规则重复率报告」。目标是每条规则的权威定义只有 1 个位置。
阶段二：下沉（P1）
对照下面这张表，把内容移到该在的层：
| 现在在哪 | 内容特征 | 应该去哪 |
|---|---|---|
| CLAUDE.md 里 | 完整代码模板 | → skills/ |
| CLAUDE.md 里 | 详细教程 | → skills/ |
| rules/ 里 | "怎么做" | → skills/ |
| rules/ 里 | 单条规则 > 5 行 | → skills/ |
| rules/ 里 | 带代码示例的规则 | → skills/ |
| rules/ 里 | 详细技术教程 | → skills/ |
| Agent 里 | 完整禁止清单 | → rules/（并链接引用） |
| Agent 里 | 详细模板 | → skills/ |
阶段三：治理（P2，长期）
每季度做一次：
- 从未被触发的 skill → 考虑删除或合并
- 长期未变动的 rules → 确认是否仍有约束意义
- 已废弃的 Agent → 及时下线
七、健康度自检表：五分钟自测
□ CLAUDE.md 是否只有路由表和项目名片？（< 200 行）
□ rules/ 是否只有极短的铁律和禁止项，无教程和代码示例？（每条规则 ≤ 5 行）
□ 每个 skill 的 description 是否明确写了触发场景？
□ 每个 Agent 的职责是否单一、不越权？
□ 同一条规则是否只有 1 处权威定义？
□ 团队规范与个人决策的优先级是否显式声明？
□ 是否有季度审计机制？
全部打勾 = 配置健康。有一项不达标 = 就是这一项在拖后腿。
八、最终目录结构参考
项目根目录/
├── CLAUDE.md # 团队共享·常驻·路由表（< 200 行）
├── CLAUDE.local.md # 个人·常驻·索引（git ignore）
└── .claude/
├── rules/ # 团队铁律·冷启动加载（只放极短的硬约束）
│ ├── 000-forbidden.md
│ ├── 100-tech-stack.md
│ ├── 200-checklist.md
│ └── 300-naming.md
├── skills/ # 操作手册·按触发词加载
│ ├── figma-to-code/
│ ├── taro-developer-create-page/
│ ├── taro-developer-create-component/
│ └── api-parser-*/
└── agents/ # 角色调度·主动调用
├── taro-developer.md
├── taro-code-reviewer.md
├── taro-performance-expert.md
├── taro-security-auditor.md
└── taro-api-parser.md
九、一句话收束
CLAUDE.md 做路由，rules 只做极短铁律，skills 做手册，agents 做角色。
四层各司其职，只引用不复制，只按需不常驻。
Claude Code 是个非常聪明的工具，但它的聪明是有代价的——你喂进去的每一个字都要付 Token 钱。真正会用 Claude Code 的团队，不是把规则写得最详细的团队，而是把规则放在最该出现的地方的团队。
规则不是越多越好，也不是越少越好——刚刚好，才是最好。
