一、Claude Code 核心能力剖析

Claude Code 的诞生引领了 AI Coding 领域的技术范式，先后定义了 Skills、PTC 等前沿技术理念，推动了 AI Coding 技术的加速发展。包括 Cursor 在内的众多产品都在 Follow 其产品设计，非常值得我们借鉴和学习。

1.1 Claude Code 是什么？

Claude Code 的产品初衷——更好地发挥出模型的能力！

Claude Code 具有多种产品形态：

• TUI：交互式终端，低开销占用系统资源使用 Agent
• Headless Mode：非交互式，便于批处理脚本集成
• Agent SDK：基于 Claude Code 进行二次开发，快速享受最前沿的 Agent 能力设计

产品形态

1.2 核心能力剖析

1.2.1 Command

通俗理解：Command 就是一个快捷方式，将预置的一段提示词发送至对话中。

command

Command 本质上是一个存放在指定位置的 Markdown 文件，通过 FrontMatter 定义配置属性（名称、描述等）。配置文件可存储在不同位置，对应不同的生效范围。

Claude Code 的命令分为两类：

1. 内置命令（/model、/help、/clear 等）

全部打包在一个压缩后的单文件 bundle 中：

~/software/node-v18.18.0-darwin-x64/lib/node_modules/@anthropic-ai/claude-code/cli.js

所有内置命令的代码都在里面，没有独立的命令文件。

2. 自定义命令

存放在以下目录：

在这些目录下创建 .md 文件即可定义自己的斜杠命令。例如创建 ~/.claude/commands/my-cmd.md，就能在任何项目中使用 /my-cmd。

自定义命令

自定义扩展实践

你可以从日常任务中提取共性规则，整理为规范的 SOP 流程，并用自然语言描述。也可以借助大模型来帮助整理。

示例：git-diff-desc 命令

整理前，需要每次手工输入提示词：

分析当前Git分支与Master分支代码差别，总结100字左右的摘要给我。

整理后，创建为标准 Command 文件：

---
name: git-diff-desc
description: 分析当前Git分支与Master分支代码差别，总结100字左右的摘要给我
---

分析当前Git分支与Master分支的代码差异，并生成一段简洁的中文摘要。

## 执行步骤

1. 使用 `git rev-parse --abbrev-ref HEAD` 获取当前分支名称
2. 使用 `git merge-base HEAD master` 找到当前分支与 master 的共同祖先
3. 使用 `git diff master...HEAD --stat` 查看变更文件概览
4. 使用 `git diff master...HEAD` 查看具体代码差异
5. 使用 `git log master..HEAD --oneline` 查看当前分支的提交记录

## 输出要求

- 用中文输出
- 摘要控制在 100 字左右
- 包含以下要点：
  - 当前分支名称
  - 主要变更了哪些模块/文件
  - 变更的核心内容（新功能、bug 修复、重构等）
  - 变更的影响范围
- 格式简洁，一段话概括即可

1.2.2 Subagent

Subagent 是 Claude Code 中专门用于处理特定任务的子代理，每个 Subagent 拥有独立的上下文窗口、系统提示词和工具权限。通过合理使用，可以显著改善复杂任务的处理能力。

简单理解：Claude Code 为主 Agent 配置了多个"工具人"，从关注过程转变为关注结果。

内置 Subagent 类型

各 Subagent 详细说明：

• Explore：当 Claude 需要搜索或理解代码库而不进行更改时，会委托给 Explore，使探索结果保持在主对话上下文之外。调用时可指定彻底程度：quick（快速查找）、medium（平衡探索）、very thorough（全面分析）
• Plan：在 Plan Mode 下，Claude 需要理解代码库时会委托给 Plan Subagent。可防止无限嵌套（Subagent 无法生成其他 Subagent），同时收集必要上下文
• general-purpose：当任务需要探索和修改、复杂推理或多个相关步骤时，Claude 会委托给 general-purpose

除了内置 Subagent，用户还可以创建自定义 Subagent，自行配置提示词、工具限制、权限模式、Hooks 和 Skills。

/agents 查看

Subagent 的作用

1）处理更长程任务

在大模型存在上下文长度限制的前提下，Claude Code 将"大任务拆小任务"，把原本只能塞进一个上下文里的信息拆分到多个子上下文中分别处理，从而在整体上突破单一上下文的实际可用上限，提升可处理任务的复杂度。

2）提升处理效率

Claude Code 可以同时唤起多个 Subagent 并行处理同一任务，并将不同 Subagent 的处理结果进行汇聚和总结，从而提升任务处理效率。

典型示例：代码库搜索时，主 Agent 自动唤起多个 Subagent 分别对不同代码目录进行并行搜索，最后聚合结果形成最终输出。

自定义 Subagent 配置

Subagent 由一个 Markdown 配置文件定义，包含 FrontMatter（name、description、model、color、tools）和 System Prompt。

配置路径：.claude/agents/<agent-name>.md

示例：hutool-check — 扫描项目代码，找出可用 Hutool 替代的地方

---
name: hutool-check
description: >
  Use this agent when analyzing Java project code to find utility
  classes and code snippets that can be replaced with Hutool equivalents.
  Examples:
  <example>
  Context: User wants to optimize Java utility usage
  user: "检查项目中哪些工具类可以用 Hutool 替代"
  assistant: "I'll use the hutool-check agent to scan the project."
  </example>
  <example>
  Context: User is reviewing custom utility code
  user: "这些自定义的 StringUtils 能不能用 Hutool 代替"
  assistant: "I'll use the hutool-check agent to analyze and suggest replacements."
  </example>
model: sonnet
color: green
tools: ["Read", "Grep", "Glob"]
---

你是一个 Java 项目工具类优化专家，专注于识别项目中可以被 Hutool 替代的自定义工具类和代码片段。

**核心职责：**
1. 扫描项目中以 Util/Utils/Helper/Tool 结尾的自定义工具类
2. 识别代码中可被 Hutool 方法替代的片段
3. 给出具体的 Hutool 替代方案和写法示例

**扫描重点：**
- 字符串处理（判空、截取、拼接、转换）
- 集合操作（判空、转换、过滤、分组）
- 日期时间处理（格式化、解析、计算）
- 文件/IO 操作（读写、拷贝、遍历）
- Bean 拷贝与属性操作
- 加密解密（MD5、AES、RSA）
- HTTP 请求、JSON 处理、正则匹配
- 类型转换、唯一 ID 生成

**Hutool 工具类映射：**

| 工具类 | 用途 | 工具类 | 用途 |
|--------|------|--------|------|
| StrUtil | 字符串 | CollUtil | 集合 |
| DateUtil | 日期 | FileUtil | 文件 |
| BeanUtil | Bean | Convert | 类型转换 |
| ReflectUtil | 反射 | SecureUtil | 加密 |
| HttpUtil | HTTP | JSONUtil | JSON |
| ReUtil | 正则 | IdUtil | ID 生成 |
| MapUtil | Map | ObjectUtil | 对象 |
| NumberUtil | 数字 | ArrayUtil | 数组 |

**执行流程：**
1. 检查 pom.xml/build.gradle 是否已引入 Hutool 依赖
2. 搜索自定义工具类，分析方法功能
3. 扫描代码中可替代的模式
4. 匹配 Hutool 对应方案

**输出格式：**

### 1. 可替代的自定义工具类
| 自定义工具类 | 文件路径 | 方法 | Hutool 替代方案 | 替代写法示例 |
|---|---|---|---|---|

### 2. 可优化的代码片段
| 文件路径:行号 | 当前写法 | Hutool 替代写法 | 涉及 Hutool 类 |
|---|---|---|---|

### 3. 依赖配置建议
如未引入 Hutool，给出 Maven/Gradle 依赖配置。

### 4. 总结
- 可替代项数量
- 优先级建议（收益最大、风险最低的优先）
- 兼容性注意事项

如何唤起 Subagent

最常用的方式是前两种：/agents 菜单选择 或 /hutool-check 直接调用。

主 Agent 与 Subagent 的上下文隔离机制

Claude Code 主 Agent 与 Subagent 采用相互隔离的上下文，目的是避免上下文污染。

1）发起任务

主 Agent 通过 Task 工具调用 Subagent，调用时自动生成以下参数：

2）返回任务结果

Subagent 执行完成后，以 prompt 作为第一条输入消息，将模型生成的最后一条消息作为 Task 工具的返回结果给到主 Agent。主 Agent 不关心 Subagent 的执行过程。

3）共享更多上下文

与分布式系统的设计思路一致，若不同 Subagent 之间需要共享更多数据，可以通过写入文件并传递文件路径的方式实现，避免模型处理过多的上下文内容，提升任务执行效果。

1.2.3 Skills

Skill 是 Claude Code 中将专业知识打包成可复用功能的机制，每个 Skill 包含一个 SKILL.md 文件，其中包含 Claude Code 在对应场景时读取的指令。

每个 Skill 本质上是一个文件夹，核心是 SKILL.md，里面用结构化方式描述：技能名称、解决什么任务、需要哪些步骤/脚本/资源，以及调用时应遵循的规则。

{skill-name}/
├── SKILL.md          # 必需：主文件，包含 Skill 定义
├── reference.md      # 可选：详细参考文档
├── examples.md       # 可选：使用示例
├── scripts/          # 可选：辅助脚本
│   └── helper.py
└── templates/        # 可选：模板文件
    └── template.txt

常见 Skills 分类

代码质量类

架构分析类

测试相关类

Skill 加载机制：渐进式披露

Claude Code 在对话前会先读取所有 Skill 的名字和简短描述，匹配当前任务是否适合用某个 Skill；只有匹配成功时，才按需加载该 Skill 的详细说明和脚本，这就是所谓的"渐进式披露"。

Skill 示例：design-pattern

功能：识别代码中适合引入设计模式的场景。

---
name: design-pattern
description: >
  Use this skill when the user asks to analyze Java code for design
  pattern opportunities, mentions "设计模式", "代码坏味道", "重构",
  "if-else太多", "代码结构优化", or wants to identify code smells
  and refactor with appropriate patterns.
allowed-tools: Read, Grep, Glob
---

# Java 设计模式识别与重构建议

识别 Java 项目代码中的坏味道（Code Smell），推荐合适的设计模式进行重构。
不过度设计，只在确实能提升可读性、可维护性、可扩展性时才建议引入。

## 适用场景

- 项目代码中存在大量 if-else / switch-case
- 对象创建逻辑复杂或散落各处
- 类职责过重，违反单一职责原则
- 多处重复的流程骨架，仅细节不同
- 需要对对象层层包装增强功能
- 一个对象变化需通知多个依赖方

## 坏味道 → 模式映射

| 代码坏味道 | 推荐模式 |
|---|---|
| 大量 if-else / switch-case 分支 | 策略模式、状态模式 |
| 对象创建逻辑复杂或散落各处 | 工厂模式、建造者模式 |
| 类职责过重，多种不相关逻辑 | 外观模式、中介者模式 |
| 多处重复流程骨架，仅细节不同 | 模板方法模式 |
| 需要层层包装增强功能 | 装饰器模式 |
| 对象变化需通知多个依赖方 | 观察者模式 |
| 需要兼容不同接口的实现 | 适配器模式 |
| 全局唯一实例管理混乱 | 单例模式（结合 Spring） |
| 复杂对象树形结构处理 | 组合模式 |
| 需要撤销/回滚操作 | 命令模式、备忘录模式 |

## 分析原则

1. **不过度设计** — 只有明确收益时才建议引入
2. **结合 Spring 生态** — 优先利用 Spring 已有支持（如依赖注入天然支持策略模式）
3. **考虑团队成本** — 评估引入后的学习成本和维护复杂度
4. **渐进式重构** — 优先影响范围小、风险低的改动

## 执行步骤

1. 扫描项目结构，了解整体架构和分层
2. 逐模块分析代码，识别坏味道
3. 匹配适合的设计模式
4. 评估引入收益和风险
5. 按格式输出重构建议

## 输出格式

### 1. 优化点总览
| 序号 | 文件路径 | 代码坏味道 | 推荐模式 | 收益评估 | 优先级 |
|---|---|---|---|---|---|

### 2. 重构详情（每个优化点）
- **当前问题**：现有代码的问题描述
- **推荐模式**：模式名称及选择理由
- **重构前**：关键代码片段
- **重构后**：引入模式后的代码示例
- **影响范围**：涉及哪些类需要改动

### 3. 总结
- 可优化点数量
- 按优先级排序的重构路线图
- 风险点提示

Skill 与 Command 的区别

Claude Code 并没有以 Command 形式展示 Skill，但支持在输入框中直接唤起。这说明 Claude Code 期望 Skill 的加载不需要用户关注，而是自动加载。

其中 <available_skills/> 标签包含了可加载的 Skill 名称和描述信息，模型会根据这些信息判断何时以及如何调用该工具进行 Skill 加载。

1.2.4 Hooks

Hooks 是 Claude Code 提供的接入 Agent 推理循环过程的一种能力，可以在 Claude Code 生命周期的不同阶段执行用户配置的脚本。Hooks 为 Claude Code 的行为提供了可预测的确定性，确保某些操作一定会发生，而不是依赖于让大模型自行决定。

常见用法：

• Agent 操作审计
• 用户输入改写
• 工具执行权限确认
• Agent 任务完成通知

Hook 示例

以下是一个 PostToolUse 类型 Hook，在 Edit 或 Write 工具调用后，自动对 .ts 文件执行 Prettier 格式化：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}

Hook 事件一览

核心事件（最常用）

用户交互事件

会话生命周期事件

其他事件

PreToolUse 特别说明（最强大）

它是唯一能控制执行流程的 Hook：

可匹配的工具名：Bash、Edit、Write、Read、Glob、Grep、Task、WebFetch、WebSearch 以及所有 MCP 工具。

Hook 配置位置

创建 Hook

在 Claude Code 中创建 Hook 的最快方法是通过 /hooks 交互式菜单。

hooks 菜单

1.3 技术对比与选型决策

Hooks 能力相对容易理解，对于外部系统集成是第一选择。

但很多人在使用 Command、Subagent、Skills 时存在使用困惑，比如：

• 代码提交功能既可以用 git-committer Subagent，也可以定义 git-commit Command
• 节省上下文占用，Subagent 和 Skills 都能达到效果

因为都是对上下文中的提示词进行管理，所以容易产生技术决策问题。

1.3.1 通俗理解

通俗理解

• Command：是"人"给 Agent 下达指令，指令通常是"任务描述"和"任务要求"
• Subagent：主 Agent 通过 Task 工具唤起 Subagent"工具人"工作，提示词配置的是"人设描述"、"价值观"
• Skills：主子 Agent 进行工作的"指导方针"
• CLAUDE.md（AGENTS.md）：长期记忆文件，包含"价值观"、"红线"、"员工手册"

Story 辅助理解相互关系：

• 用户通过 Command 让 Subagent 加载 Skill 完成某个任务
• Subagent 自动判断一个任务需要加载特定 Skill 来完成
• 多个 Subagent 都可以加载 Skill，如果 Skill 不够通用可以直接设置给 Subagent
• 常用的 Agent 执行准则可以放到 AGENTS.md 当中

1.3.2 特性对比

对 Command、Subagent 以及 Skill 三种特性的功能项对比：

特性对比

参靠：https://code.claude.com/docs/