Claude Code 深度定制指南：CLAUDE.md、Commands、Skills 与Subagents

公众号名称：奇点先锋

作者名称：扶苏

发布时间：2026-03-04 09:00

本文将拆解 Claude Code 的核心定制模块：

CLAUDE.md

：项目级的持久化上下文与指令集。
Slash commands

（斜杠命令）：在终端通过 /command 触发的封装 Prompt。
Subagents

（子智能体）：拥有独立上下文窗口的专家模型，用于执行特定委托任务。
Skills

（技能）：Claude 可自动发现的复杂能力集（通常包含支持文件，无法通过 /... 手动运行）。
核心洞察

：Subagents 是保持主上下文（Context）清洁的关键。在 Plan Mode（规划模式）下，Claude Code 通常会将代码库扫描任务委托给 Explore 类型的子智能体，以防止主会话的上下文膨胀。

Claude Code 提供了多种方式来“注入”项目上下文或自动化工作流，但在实际工程中，选择哪种方式往往取决于具体场景。

为了具体化每种工具的权衡（Trade-offs），我将演示用四种不同方式解决同一个问题。剧透：对于文档抓取这类任务，Subagents（子智能体）是最佳选择，因为它们能有效隔离无关信息，保持主上下文的清洁。

场景痛点：文档知识滞后

Claude Code 的模型训练数据无法覆盖所有库的最新版本，因此它无法可靠地“记忆”当下的文档细节。

具体问题：我正在构建一个基于 Dexie.js（IndexedDB 封装库）的健身追踪应用。Claude 总是建议过时的代码模式，并且不知道 liveQuery()等新特性。

虽然 Claude Code 自身有机制获取其官方文档，但我们需要为我们使用的第三方库实现同样的能力。

下面我们将通过四种不同的工具来解决这个问题，并进行横向对比。

1. CLAUDE.md：常驻的项目记忆

核心机制

这是一个 Markdown 文件，在每次启动 Claude Code 时自动加载。将其视为项目的“ROM 记忆卡”。

定义：CLAUDE.md 是持久化的项目级指令，Claude 在每次会话开始时都会读取。

目录结构

project-root/
├── CLAUDE.md          // 项目根级配置
├── .claude/
│   └── CLAUDE.md      // 备选位置
└── tests/
    └── CLAUDE.md      // 仅在读取测试文件时加载

嵌套的 CLAUDE.md

Claude Code 支持嵌套发现机制。当 Claude 读取某个包含 CLAUDE.md 的子目录时，该文件会被自动注入上下文。这非常适合领域特定的指令：

tests/CLAUDE.md

— 测试规范与 Mock 模式。
src/db/CLAUDE.md

— 数据库特定模式与约束。
src/components/CLAUDE.md

— 组件架构指南。

只有当 Claude 实际访问该目录下的文件时，嵌套配置才会被加载，从而在不需要时保持主上下文的精简。

Dexie.js 解决方案实现

# CLAUDE.md

## Database

本项目使用 Dexie.js 操作 IndexedDB。在实现任何数据库代码前：

1. 从 https://dexie.org/llms.txt 获取文档索引。
2. 使用 `liveQuery()` 实现响应式数据绑定。
3. 遵循 `src/db/` 中的 Repository 模式。
4. 必须处理 `ConstraintError` 以应对键冲突。

运行效果

每次会话开始时，Claude 都知道“写数据库代码前要查阅 Dexie 文档”。

局限性（Context Drift）：在长会话中，随着对话历史增加，模型可能会逐渐降低早期系统指令的权重（遗忘），转而更关注最近的交互。

权衡分析

✅ 优势	❌ 劣势
零操作成本：自动加载	上下文漂移：长会话中指令容易被遗忘
团队共享：随 Git 仓库同步	占用主上下文：与当前对话竞争 Token 空间
维护简单：纯文本文件	缺乏强制性：Claude 自行决定是否遵循

2. Slash Commands：终端触发的封装技能

核心机制

这是一种保存好的 Prompt 模板，通过在终端输入 /command-name 调用。类似于宏（Macro）或快捷键。

Slash Commands 既可以显式调用（输入 /command），也可以由 Claude 根据命令的 description（描述）自动触发。

更重要的是，Slash Commands 可以编排复杂行为：你可以在命令中明确指示它启动一个（或多个）Subagent，调用特定 Skill，将工作流水线化（例如：研究 → 代码库扫描 → 撰写文档），而不是试图在一个 Prompt 中完成所有工作。

与 Skills 的主要区别在于 封装形式与交互体验 (UX)：Slash Commands 是单文件入口，拥有极佳的终端 /... 自动补全体验；而 Skills 通常是包含辅助文件（模式、模板、脚本）的目录结构。

目录结构

.claude/
└── commands/
    └── dexie-help.md

Dexie.js 解决方案实现(`dexie-help.md`)

---
description: 基于最新文档获取 Dexie.js 开发指南
allowed-tools: Read, Grep, Glob, WebFetch
---

首先，从 https://dexie.org/llms.txt 抓取文档索引。
然后，基于用户的提问，抓取相关的文档页面。
最后，使用获取到的最新文档回答以下问题：

$ARGUMENTS

进阶编排示例：并行研究 (Research)

你可以定义一个 Slash Command，显式启动多个并行 Subagents，最终生成产物（如 docs/research/ 下的研究笔记）。

research.md

---

description: 通过网络搜索、文档查阅和代码库探索来研究特定问题
allowed-tools: Task, WebSearch, WebFetch, Grep, Glob, Read, Write, Bash
---

# Research: $ARGUMENTS

针对以下问题或主题进行研究：

> **$ARGUMENTS**

## 指令 (Instructions)

请像一位资深开发人员那样进行彻底的研究。并行启动多个子智能体（Subagents），从不同来源收集信息。

### 第一步：启动并行研究智能体

使用 `Task` 工具**并行**生成以下子智能体（务必在单条消息中同时下发）：

1.**Web 文档智能体 (Web Documentation Agent)**
   -`subagent_type`: general-purpose
   - 搜索该主题的官方文档。
   - 寻找最佳实践和推荐的设计模式。
   - 定位相关的 GitHub Issues 或讨论。

2.**Stack Overflow 智能体 (Stack Overflow Agent)**
   -`subagent_type`: general-purpose
   - 在 Stack Overflow 上搜索类似的问题和解决方案。
   - 寻找高票答案和被采纳的答案。
   - 记录常见的陷阱和注意事项。

3.**代码库探索智能体 (Codebase Explorer Agent)**
   -`subagent_type`: Explore
   - 在代码库中搜索相关的模式。
   - 查找针对类似问题的现有解决方案。
   - 识别相关的文件、函数或组件。

### 第二步：创建研究文档

待所有智能体完成任务后，在 `docs/research/.md` 路径下创建一个 Markdown 文件。

根据研究主题生成文件名：

- 转换为小写。
- 将空格替换为连字符（-）。
- 移除特殊字符。
- 添加今天的日期作为前缀：`YYYY-MM-DD-.md`。

示例："Vue 3 Suspense" → `docs/research/2024-12-06-vue-3-suspense.md`

首先，如果该文件夹不存在，请创建它：

```bash
mkdir -p docs/research
```

### 第三步：撰写研究文档

请按照以下章节结构来组织文档内容：

# Research: 

**Date:**
**Status:** Complete

## Problem Statement (问题陈述)

<描述问题背景及其重要性>

## Key Findings (关键发现)

<总结最相关的解决方案和方法>

## Codebase Patterns (代码库模式)

<记录当前代码库如何处理类似情况>

## Recommended Approach (推荐方案)

<基于所有研究提供你的建议>

## Sources (参考来源)

- [标题](URL) - 简要描述
- [标题](URL) - 简要描述

### 准则 (Guidelines)

-**官方文档优先**：其权重高于技术博客。
-**一致性优先**：优先选择与现有代码库模式相匹配的解决方案。
-**版本敏感**：注意特定版本的注意事项（如 Vue 3, TypeScript 等）。
-**标记冲突**：如果不同来源的信息存在冲突，请标记出来。
-**简洁有力**：编写简洁、可执行的内容。
-**主动语态**：通篇使用主动语态。

### 第四步：确认完成

文件写入完成后，输出文件路径，以便用户查找。

运行效果

/dexie-help 如何创建复合索引?

d运行效果

Claude 接收指令，获取文档，查找相关页面并回答问题——这是显式触发的。

权衡分析

✅ 优势	❌ 劣势
精准控制：完全由你决定何时运行	记忆负担：必须记得输入 `/dexie-help`
参数支持：可针对特定问题传入参数	一次性：知识不会在消息间持久化
轻量级：单文件配置即可	被动触发：自动运行依赖 `description` 匹配度

3. Subagents：拥有独立上下文的专家

核心机制

这是一个拥有独立上下文窗口的专用 AI “人格”。Claude 将整个任务委托给它，并接收返回结果。

由于抓取 Dexie 文档涉及阅读多个页面，会产生大量 Token 噪音，将其封装在 Subagent 中可以防止主会话达到上下文上限。

定义：Subagent 是一个隔离的 Claude 实例，独立执行任务，仅将最终结果返回给主会话。

提示：Subagents 保持主上下文清洁 即使任务仅仅是“探索”，Subagents 也是极佳的默认选择。它们允许 Claude 进行大量的阅读/搜索，而不会将过程垃圾倾倒进主线程。

这在 Plan Mode（规划模式） 中尤为常见：Claude Code 通常会启动一个 Explore 类型的 Subagent 来扫描代码库并返回相关文件/模式的精简地图，从而保持主会话聚焦且不膨胀。

Claude Code 还支持 Async Agents（异步智能体）：你可以发射一个 Agent 让它在后台运行，自己继续工作 (Ctrl + B)，等它完成后再回来查看更新。

目录结构

.claude/
└── agents/
    └── dexie-specialist.md

Dexie.js 解决方案实现（dexie-specialist.md）

---
name: dexie-db-specialist
description: 当任务涉及 Dexie.js 或 IndexedDB 的任何方面时（包括实现、修改、查询、审查或优化数据库代码），请使用此智能体。具体场景包括：创建或修改数据库 Schema、编写查询、处理事务、使用 liveQuery 实现响应式查询、排查 Dexie 相关问题，或审查现有 Dexie 代码以改进质量和符合最佳实践。\n\nExamples:\n\n\n\nContext: 用户询问关于改进其 Dexie.js 代码的事宜.\n\nuser: "在这个代码库中，关于 Dexie 的部分我还能做哪些改进？"\n\nassistant: "我将调用dexie-db-specialist 智能体，对照当前的最佳实践来审查您的 Dexie.js 实现。"\n\n\n\n由于用户询问关于 Dexie.js 的改进建议，应使用dexie-db-specialist 智能体来获取最新文档，并针对优化机会、功能缺失和违反最佳实践的情况审查现有代码。\n\n\n\n\n\n\n\nContext: 用户需要向数据库添加一张新表.\n\nuser: "我需要添加一张新的 ‘goals’（目标）表来追踪健身目标。\n\nassistant: "我需要添加一张新的 ‘goals’（目标）表来追踪健身目标。"\n\n由于用户需要修改 Dexie 数据库 Schema，应使用 dexie-db-specialist 智能体先获取最新的 Dexie.js 文档，然后遵循最佳实践来实现 Schema 变更。\n\n\n\nContext: 用户正在咨询 Dexie 的查询模式.\n\nuser: "在 Dexie 中，我该如何根据多个肌群来查询训练动作？"\n\nassistant: "让我调用 dexie-db-specialist 智能体，基于最新的 Dexie.js 文档为您提供准确的解答。"\n\n\n\n由于用户询问 Dexie.js 的查询能力，应使用 dexie-db-specialist 智能体获取文档，并提供关于复合查询和过滤的准确、最新的回答。\n\n\n\n\n\n\n\nContext: 用户遇到了与 Dexie 相关的报错.\n\nuser: "我在尝试添加训练记录时遇到了 'ConstraintError'（约束错误）。"\n\nassistant: "我将咨询 dexie-db-specialist 智能体来诊断这个数据库约束问题。"\n\n\n\n由于这是 Dexie.js 报错，应使用 dexie-db-specialist 智能体获取关于错误处理和约束冲突的相关文档，以提供准确的故障排查指导。\n\n\n\n\n\n\n\nContext: 用户需要实现响应式查询.\n\nuser: "当添加新的健身记录时，健身列表应该能自动更新。"\n\nassistant: "我将调用 dexie-db-specialist 智能体，通过 liveQuery 来实现响应式查询。"\n\n\n\n由于 Dexie 的响应式数据绑定需要使用 liveQuery，应使用 dexie-db-specialist 智能体获取关于 liveQuery 和 Vue 集成模式（如 useLiveQuery）的最新文档。\n\n\n\n

model: sonnet
color: orange
---

你是一位 Dexie.js 数据库专家，对 IndexedDB、响应式查询以及 Vue 3 集成模式有深刻的理解。你的首要职责是为所有 Dexie.js 实现提供准确的、基于文档的指导。

## 关键的第一步 (Critical First Step)

**在回答任何 Dexie.js 问题或实现任何 Dexie 相关代码之前，你必须：**

1.  从 `https://dexie.org/llms.txt` 获取文档索引，以理解可用的文档结构。
2.  根据手头的任务，抓取相关的文档页面，确保你的指导是准确且最新的。
3.  只有在完成上述步骤后，才开始进行代码实现或回答问题。

这是一条**不可协商**的规则。Dexie.js 存在许多细微差别和特定版本的行为，必须查阅官方文档。

## 你的专业领域涵盖 (Your Expertise Covers)

-**Schema 设计**：表定义、索引（简单、复合、多条目 multi-entry）、主键、版本迁移。
-**CRUD 操作**：`add()`, `put()`, `update()`, `delete()`, `bulkAdd()`, `bulkPut()`。
-**查询 (Querying)**：`where()`, `filter()`, `equals()`, `between()`, `anyOf()`, `startsWithIgnoreCase()`, 复合查询。
-**响应式查询**：用于实时更新的 `liveQuery()`，以及与 Vue 响应式系统的集成。
-**事务 (Transactions)**：事务作用域、嵌套事务、事务内的错误处理。
-**关系 (Relationships)**：外键、表关联、填充相关数据（Populating）。
-**性能优化**：索引策略、查询优化、批量操作。
-**错误处理**：Dexie 特有的错误（`ConstraintError`, `AbortError` 等）。

## 项目上下文 (Project Context)

你正在处理一个 Vue 3 PWA 健身追踪应用，该项目使用：

-**Dexie.js** (IndexedDB) 实现离线优先的数据持久化。
-**TypeScript** (开启严格模式)。
- 在 `src/db/` 目录下采用 **Repository 模式** 进行数据库访问抽象。
- 使用 **Pinia Store** 消费 Repository。

在实现代码时，确保你的代码：

1.  遵循 `src/db/` 中现有的 Repository 模式。
2.  使用 TypeScript 接口定义表结构。
3.  正确集成 Vue 3 响应式系统（使用 `@vueuse/rxjs` 中的 `useLiveQuery` 或类似方案）。
4.  使用正确的类型定义优雅地处理错误。

## 文档抓取策略 (Documentation Fetching Strategy)

当从 `https://dexie.org/llms.txt` 抓取时：

1.  解析 Sitemap 以识别相关的文档页面。
2.  根据任务抓取特定页面（例如：对于查询任务，抓取 `WhereClause` 和 `Collection` 文档）。
3.  处理复杂主题时，交叉参考多个页面。

常用的参考文档章节：

-`/docs/Table/Table` - 核心表操作
-`/docs/WhereClause/WhereClause` - 查询构建
-`/docs/Collection/Collection` - 结果集操作
-`/docs/liveQuery()` - 响应式查询
-`/docs/Dexie/Dexie` - 数据库实例配置
-`/docs/Version/Version` - Schema 迁移

## 响应格式 (Response Format)

在提供实现方案时：

1.**引用文档**：注明你查阅了哪些文档。
2.**解释思路**：在展示代码前先解释方法论。
3.**提供 TypeScript 代码**：必须遵循项目规范。
4.**包含错误处理**：针对操作类型提供适当的错误处理逻辑。
5.**注明注意事项**：提示任何陷阱或特定版本的行为。

## 质量保证 (Quality Assurance)

- 始终依据抓取到的文档验证你的建议。
- 如果文档不清楚或不可用，明确说明这一点，并在给出最佳建议时附上适当的警告。
- 当存在多种实现方式时，解释各自的权衡（Trade-offs）。
- 考虑 IndexedDB 的局限性（如无全文搜索、存储限制等）。

切记：你的价值在于提供**经过文档验证的、准确的** Dexie.js 指导。永远不要猜测 API 细节——务必先抓取并验证。

运行效果

当你询问有关 Dexie 的问题时，Claude 会自动识别这是一个数据库任务，并将其委托给 Specialist（专家）。专家在自己的上下文窗口中工作，抓取文档，执行任务，并将提炼后的结果返回给主会话。

权衡分析

✅ 优势	❌ 劣势
自动委托：任务匹配时自动触发	开销较大：启动独立的 Agent 进程
上下文隔离：不污染主会话	即时性低：返回的是摘要，非流式输出
模型灵活：可指定模型（如 Opus 处理复杂任务）	交互限制：无法直接与子智能体对话
安全沙箱：可限制工具权限	配置复杂：设置相对繁琐

4. Skills：具备自动发现能力的技能包

核心机制

Skills 是一种结构化的能力集，Claude 可以自动发现并在主会话中使用。与简单的 Slash Commands 不同，Skills 通常包含多个文件：参考文档、脚本、模板和实用工具。

目录结构

.claude/
└── skills/
    └── dexie-expert/
        ├── SKILL.md           // 主定义文件
        ├── PATTERNS.md        // 常用模式
        ├── MIGRATIONS.md      // 迁移指南
        └── scripts/
            └── validate-schema.ts

自动发现机制

Claude 主要依据 description 来决定是否调用某个 Skill。你可以通过询问 Claude Code 请准确向我展示，在你看来到底是什么样子的？ 来查看它所识别到的 XML 结构。

当它给出回答时，你通常会看到类似于的结构化区块（通常还会有一个专门用于斜杠命令的独立区块，例如）。



dexie-expert

      Dexie.js 数据库指南。当处理 IndexedDB、Schema 定义、查询、liveQuery 等任务时使用。

以下是一个章节的简略示例（部分内容使用 ... 进行了省略）：



skill-creator

      高效技能创建指南。当你想要创建或更新技能时使用。
      ...

user



c4-architecture

      使用 C4 模型 Mermaid 图表生成架构文档。
      ...

user



vue-composables

      遵循既定模式和最佳实践，编写高质量的 Vue 3 Composables。
      ...

managed


  ...

Dexie.js 解决方案实现

---name: dexie-expertdescription: Dexie.js 数据库指南。在处理 IndexedDB、Schema 定义、查询、liveQuery 或数据库迁移时使用。allowed-tools: Read, Grep, Glob, WebFetch---
# Dexie.js 专家
当用户需要关于 Dexie.js 或 IndexedDB 的帮助时：
1. 抓取 https://dexie.org/llms.txt2. 仅抓取与当前任务相关的文档页面3. 将获取的指导建议应用到本仓库的代码模式中

最小可行性测试：“冒烟测试” Skill

如果你想验证 Skill 是否能通过 Task 工具启动 Subagent，可以使用以下“冒烟测试”脚本：

SKILL.md (subagent-smoke-test)

---name: subagent-smoke-testdescription: 子智能体冒烟测试 (Smoke Test)。当用户想要验证在此仓库中通过 Task 工具生成子智能体是否正常工作时使用。---
# 子智能体冒烟测试
本技能纯粹是为了验证子智能体（Subagents）的端到端工作流是否正常。
## 执行步骤
1. 使用 **Task** 工具启动一个子智能体。
- 使用 `subagent_type: general-purpose`。- 给它分配一个简单的、只读的任务：- 读取 `package.json` 并总结关键脚本 (scripts)。- 读取 `astro.config.ts` 并总结主要的集成配置 (integrations)。- 使用 Glob（或等效工具）列出根目录下的顶层文件夹。
2. 等待子智能体完成运行。
3. 向用户返回一份简短报告：
-`Subagent status: success`（或 `failed`）- 一份包含 3–6 个要点的任务发现总结。- 如果失败，请提供最可能的修复建议（例如：工具权限问题、Task 工具被禁用）。
## 建议的 Task Prompt
使用类似以下内容作为 Task 的 Payload（有效负载）：
- “你是一个助手子智能体。请对本仓库进行快速的只读扫描：    - 读取 `package.json` 并总结主要脚本。    - 读取 `astro.config.ts` 并总结关键集成。    - 对仓库根目录执行 Glob，列举顶层文件夹。    最后返回一份简洁的报告。”

运行效果

Skills 是自动发现的，当 Claude 认为当前任务匹配时会应用它。它们在主会话中运行，因此你可以进行实时迭代。

权衡分析

✅ 优势	❌ 劣势
智能匹配：基于描述自动应用	共享上下文：占用主会话 Token
实时交互：在主会话中运行	触发不确定：完全由 Claude 决定是否使用
资源丰富：可包含脚本、模板等辅助文件	配置门槛：比 Slash Commands 复杂
高度复用：打包的工作流	不可手动调用：无法通过终端 `/...` 直接运行

关键洞察：实际上，二者的核心区别在于 UX（用户体验） + 封装形式：

Slash Commands

：通过终端 /command 手动运行的命令。

Skills

：结构化的能力包（目录），Claude 视情况自动取用。

决策矩阵：如何选择？

选择…	场景	原因
CLAUDE.md	希望 Claude 启动时_始终_遵循项目规则	自动加载；随 Git 共享
Slash command	需要按需运行的、显式的一次性工作流	可通过 `/...` 发现；支持参数
Subagent	任务涉及大量调研（阅读/搜索/合成）	使用独立上下文窗口；返回提炼结果
Skill	希望 Claude 自动识别并应用复杂能力	打包的能力集（通常含辅助文件）

机制关系图

机制	运行在主会话	独立上下文	可启动 Subagents	可使用 Skills	可通过 `/...` 手动运行
CLAUDE.md	✅	❌	❌	❌	❌
Slash command	✅	❌	✅ (通过 `Task`)	✅ (间接)	✅
Skill	✅	❌	✅ (若允许 `Task`)	✅ (间接)	❌
Subagent	❌	✅	⚠️ 可能 (视工具权限)	✅ (若配置)	⚠️ 通常被委托

总结

使用 Subagents（尤其是 Plan Mode 中的 Explore）来保持主上下文的精简与聚焦。
使用 Slash Commands 来创建显式的、可重复的终端入口。
使用 Skills 来封装 Claude 可自动应用的丰富工作流（含辅助文件）。
使用 CLAUDE.md 来定义简短、通用的项目公约与标准。

内容效果不满意？点此反馈

场景痛点：文档知识滞后

1. CLAUDE.md：常驻的项目记忆

核心机制

目录结构

嵌套的 CLAUDE.md

Dexie.js 解决方案实现

运行效果

权衡分析

2. Slash Commands：终端触发的封装技能

核心机制

目录结构

Dexie.js 解决方案实现(dexie-help.md)

进阶编排示例：并行研究 (Research)

d运行效果

权衡分析

3. Subagents：拥有独立上下文的专家

核心机制

目录结构

Dexie.js 解决方案实现（dexie-specialist.md）

运行效果

权衡分析

4. Skills：具备自动发现能力的技能包

核心机制

目录结构

自动发现机制

Dexie.js 解决方案实现

最小可行性测试：“冒烟测试” Skill

运行效果

权衡分析

决策矩阵：如何选择？

机制关系图

总结

Dexie.js 解决方案实现(`dexie-help.md`)