Claude Code 核心概念完全指南：CLAUDE.md、Skill、Command、Agent 与 Plan Mode

如果你刚开始用 Claude Code，大概率会被这几个概念搞晕：Skill 和 Command 有什么区别？Agent 到底是什么？Plan Mode 又算什么？这篇文章用一个贯穿全文的类比，把它们一次讲清楚。

---

先说结论：一张图看懂全部

在深入每个概念之前，先记住这张对比表，后面读完全文再回来看会更有体感：

概念	一句话解释	何时生效	独立上下文	类比
CLAUDE.md	项目规则	始终自动加载	否	公司规章制度
Skill	可复用的指令+资源包	Claude 自动识别或手动 /触发	可选	培训手册
Command	Skill 的旧称/子集	手动 /触发	否	快捷键
Agent	独立的 AI 专家实例	Claude 自动委派或你指定	是	外包专家
Plan Mode	只读的规划工作模式	手动或自动切换	内部可用子代理	先画图纸再施工

接下来我们一个一个拆解。

---

一、CLAUDE.md：你的项目"宪法"

它是什么

CLAUDE.md 是一个放在项目根目录的 Markdown 文件。每次你打开 Claude Code、开始一个新对话，它都会被自动加载到上下文中。你不需要做任何操作，Claude 就已经读过了这份文件。

适合放什么

放那些永远成立、每次对话都该遵守的信息：

• 技术栈声明：“前端用 React + TypeScript，后端用 Go + PostgreSQL”
• 代码规范：“使用 Conventional Commits 格式提交”
• 项目结构说明：哪个目录放什么
• 通用约定：“用中文回复”、“新功能必须有测试”

实际示例

# 项目：电商后台管理系统

## 技术栈
- 前端：React 18 + TypeScript + Ant Design
- 后端：Node.js + NestJS + PostgreSQL
- 测试：Jest + Playwright

## 规范
- 用中文交流
- 提交信息用 Conventional Commits
- 组件使用函数式写法 + Hooks
- API 路径遵循 RESTful 风格

## 目录结构
- /apps/web — 前端应用
- /apps/api — 后端服务
- /packages/shared — 前后端共享类型和工具
- /docs — 设计文档

进阶技巧：分层 CLAUDE.md

你可以在子目录放更具体的 CLAUDE.md。Claude Code 会同时加载根目录和当前工作目录的 CLAUDE.md。

比如在 /apps/web/CLAUDE.md 中写前端专属规范：

## 前端规范
- 状态管理用 Zustand，参考 /apps/web/stores 目录
- 新组件必须有对应的 .test.tsx 文件
- 样式用 Tailwind，不要写自定义 CSS

这样当你在前端目录下工作时，Claude 既知道全局规则，也知道前端专属约定。

常见误区

• 不要把 CLAUDE.md 写成小说。它会占用上下文窗口，信息越精炼越好。几十行到一两百行是合理范围。
• 不要把临时任务写进去。"今天要修复登录 bug"不属于 CLAUDE.md，直接在对话里说就行。
• 不要和 .cursorrules 混淆。CLAUDE.md 是 Claude Code 的机制，作用类似但不通用。

---

二、Skill（技能）：给 Claude 的"培训手册"

它是什么

Skill 是 Claude Code 中可复用的指令包。你把一套工作流程写成 Markdown，放到指定目录，它就成了 Claude 的一项"技能"。

Skill 最核心的特点是：Claude 可以自动判断什么时候该用它。你不需要每次都手动触发——当你的任务描述匹配了某个 skill 的 description 时，Claude 会自己把它加载进来。当然，你也可以用 /技能名 手动触发。

文件结构

.claude/skills/
└── review/
    ├── SKILL.md          # 核心文件（必须）
    ├── templates/         # 可选：模板文件
    └── examples/          # 可选：示例代码

每个 skill 是一个文件夹，里面必须有一个 SKILL.md。你还可以放脚本、模板、示例等支持文件——这是 skill 相比旧的 command 系统的一大优势。

SKILL.md 的结构

一个 SKILL.md 分为两部分：YAML frontmatter（配置）和 Markdown 正文（指令）。

---
name: review
description: 审查代码的质量、安全性和规范性。在 PR 前自检或被要求做代码审查时使用。
tools: Read, Grep, Glob
---

## 审查流程

对代码进行以下维度的审查：

1. **逻辑正确性**：是否有 bug、边界条件遗漏、空值处理
2. **安全性**：是否存在注入、XSS、敏感信息泄露等风险
3. **性能**：是否有 N+1 查询、不必要的重复计算、内存泄漏风险
4. **规范性**：是否符合 CLAUDE.md 中定义的项目规范
5. **测试覆盖**：关键逻辑是否有测试、边界情况是否被覆盖

## 输出格式

给出具体的问题描述、所在文件和行号、以及改进建议的代码示例。
按严重程度分类：🔴 必须修复 / 🟡 建议改进 / 🟢 可选优化

frontmatter 关键配置详解

字段	作用	示例
name	技能名称，也是 /命令名	review
description	告诉 Claude 何时自动使用这个 skill	"审查代码质量和安全性"
tools	限制 skill 可用的工具	Read, Grep, Glob（只读）
allowed-tools	同 tools，更精细的控制	Bash(npm test:*)
disable-model-invocation	设为 true 表示只能你手动触发	适合有副作用的操作如部署
user-invocable	设为 false 表示只能 Claude 自动调用	适合背景知识类 skill
context: fork	在独立子代理中运行，不污染主对话	适合需要大量探索的任务
agent	指定用哪个子代理执行	Explore、Plan、自定义 agent
model	指定用哪个模型	sonnet、opus、haiku

存放位置

• 项目级：.claude/skills/（随 git 共享，团队共用）
• 个人级：~/.claude/skills/（只有你自己能用）

动态上下文注入

Skill 有一个很强的特性——可以用 ! 语法在 skill 加载时执行 shell 命令，把实时数据注入到提示词中：

---
name: pr-summary
description: 总结当前 PR 的变更
context: fork
agent: Explore
---

## 当前 PR 信息
- PR diff：!`gh pr diff`
- 变更文件：!`gh pr diff --name-only`

## 任务
总结这个 PR 的主要变更...

这里 !gh pr diff`` 会在 skill 加载时先执行，Claude 看到的是实际的 diff 输出，而不是这条命令本身。

---

三、自定义命令（Slash Command）：Skill 的"前身"

历史背景

在 2025 年 10 月 Anthropic 推出 Skill 系统之前，Claude Code 只有 Command 系统。命令放在 .claude/commands/ 目录下，每个 .md 文件就是一个 /命令名。

**现在这两套系统已经合并了。**放在 .claude/commands/review.md 和放在 .claude/skills/review/SKILL.md 效果完全一样，都会创建 /review 命令。旧的 commands 文件仍然可以正常工作。

Skill vs Command 还有区别吗？

功能上已经统一，但在设计意图上有微妙差异：

	Command	Skill
核心理念	“我主动按下按钮”	“Claude 自动识别何时使用”
触发方式	只能手动 /命令名	手动或 Claude 自动
文件形式	单个 .md 文件	文件夹（可含支持文件）
额外能力	无	frontmatter 配置、支持文件、动态注入
推荐程度	继续可用，但不推荐新建	推荐

建议：新的工作流统一用 skill 方式创建，放在 .claude/skills/ 下。

---

四、Agent（子代理）：独立工作的"外包专家"

它是什么

Agent 是一个完全独立的 Claude 实例。它有自己的上下文窗口、系统提示词、工具权限，甚至可以用不同的模型。它和你的主对话是隔离的——干完活只把最终结果送回来，中间过程不会出现在你的对话里。

这是 Agent 和前面所有概念最本质的区别：独立上下文。

为什么需要独立上下文？

想象你让 Claude 在一个大型代码库中搜索某个 bug 的根因。它可能需要读几十个文件、搜索大量代码。如果这些内容全部留在主对话的上下文里，你的对话很快就会"爆掉"——上下文窗口被填满，Claude 开始遗忘早期的对话内容。

Agent 解决了这个问题。它在自己的"房间"里完成所有探索工作，最后只给你一份精炼的报告。你的主对话保持干净。

内置 Agent

Claude Code 自带几个内置 agent，Claude 会在合适的时候自动使用：

• Explore：只读的代码探索 agent，擅长搜索和分析代码库
• Plan：在 Plan Mode 下收集信息的研究 agent
• general-purpose：能读能写的通用 agent，处理复杂多步骤任务

你通常不需要直接调用它们，Claude 会自己判断何时委派。

自定义 Agent

当内置 agent 不够用时，你可以创建自己的。

文件结构：放在 .claude/agents/ 或 ~/.claude/agents/ 下，是一个带 YAML frontmatter 的 Markdown 文件。

# .claude/agents/test-writer.md
---
name: test-writer
description: 为代码编写全面的测试用例。当需要补充测试、提高覆盖率时使用。
tools: Read, Write, Bash(npm test:*), Grep, Glob
model: sonnet
---

你是一个专注于测试的专家。编写测试时：

1. 先阅读被测代码，理解其功能和边界条件
2. 参考项目中已有的测试风格（查看 __tests__ 或 *.test.* 文件）
3. 覆盖以下场景：
   - 正常路径（happy path）
   - 边界值和空值
   - 错误处理和异常情况
   - 并发和竞态条件（如适用）
4. 测试命名格式：should [预期行为] when [条件]
5. 写完后运行测试确认全部通过

frontmatter 关键字段

字段	作用
name	agent 标识符
description	极其重要——Claude 根据这个判断是否自动委派任务给这个 agent
tools	可用工具白名单。不写则继承主对话的所有工具
model	使用哪个模型：opus（最强）、sonnet（均衡）、haiku（快速）

创建方式

方式一：交互式创建（推荐新手）

在 Claude Code 中输入 /agents，按提示操作。Claude 会帮你生成配置。

方式二：手动创建

直接在对应目录下创建 .md 文件，按上面的格式填写即可。

使用方式

Agent 有两种触发方式：

1. 自动委派：Claude 根据任务内容和 agent 的 description 自动判断是否需要委派。你什么都不用做。
2. 显式调用：在对话中说"用 test-writer agent 给这个模块写测试"。

什么时候该用 Agent？

不要一开始就创建大量 agent。以下情况才需要：

• 上下文经常爆：某些任务需要读大量文件，用 agent 隔离
• 需要并行处理：比如同时做安全审计和写文档
• 需要权限隔离：比如审计 agent 只能读不能写，防止误改代码
• 需要不同模型：便宜的任务用 haiku，复杂推理用 opus

---

五、Plan Mode：先侦察再行动

它是什么

Plan Mode 不是一个"配置"，而是 Claude Code 的一种工作模式。在这个模式下，Claude 只做只读操作——它可以读文件、搜索代码、分析架构，但不能修改任何东西。

你可以把它理解为"侦察模式"：先摸清地形，画好作战计划，确认方案后再动手。

怎么进入

• 手动进入：按 Shift+Tab 两次（第一次进入 Auto-Accept 模式，第二次进入 Plan Mode）
• 启动时指定：claude --permission-mode plan
• 自动触发：给 Claude 一个足够复杂的任务时，它有时会自己进入计划模式

典型工作流

1. Shift+Tab × 2 进入 Plan Mode
2. 描述你的需求："我需要给系统添加 OAuth2 认证"
3. Claude 分析现有代码、提出方案、列出步骤
4. 你审查计划，用 Ctrl+G 在编辑器中修改
5. 满意后退出 Plan Mode，Claude 按计划执行

Plan Mode 的价值

Plan Mode 解决的核心问题是：防止 Claude 在没想清楚的情况下就开始改代码。

没有 Plan Mode 时，你说"重构认证系统"，Claude 可能立刻就开始改文件，改到一半发现方向不对，已经改了一堆文件，回退成本很高。

有了 Plan Mode，Claude 先花时间研究代码库、理解依赖关系、评估风险，然后给你一份完整的实施计划。你确认后再执行，成功率大大提高。

Plan Mode 与 Agent 的关系

Plan Mode 内部也会使用 agent。当 Claude 在 Plan Mode 下需要大量阅读代码时，它通常会派出 Explore 类型的子代理去扫描代码库，子代理返回精炼的信息，保持主对话的上下文干净。

---

六、它们之间的关系：一个公司的类比

把 Claude Code 想象成你开的一家公司：

CLAUDE.md 是公司的规章制度。每个员工入职第一天就要读，所有人随时遵守。它不针对某个具体任务，而是定义"我们公司怎么做事"。

Skill 是培训手册。“如何做代码审查”、“如何写测试”、“如何处理部署”——每个手册针对一类任务，员工（Claude）遇到相关任务时自动翻阅对应手册，或者你直接说"按照代码审查手册来"。

Command 是快捷键。和培训手册本质相同，只是更强调"你主动触发"。现在已经和 Skill 合并了。

Agent 是外包专家。你雇了一个安全顾问、一个测试专家。他们各自带着自己的工具箱（工具权限），在自己的办公室（独立上下文）里工作，做完后给你一份报告。他们不会占用你的办公桌（主对话上下文）。

Plan Mode 是开工前的方案评审会。在动工之前，先让团队调研现状、评估风险、画出蓝图。确认无误后，再从"评审"切换到"施工"。

---

七、实战建议：我该从哪个开始？

新手路径（推荐）

第 1 天：写好 CLAUDE.md
         ↓
第 1 周：学会用 Plan Mode 做规划
         ↓
第 2 周：把重复工作流做成 2-3 个 Skill
         ↓
需要时：遇到上下文问题或并行需求，再引入 Agent

不同阶段用什么

项目阶段	推荐工具	原因
需求分析/架构设计	Plan Mode	只需要研究和讨论，不需要改代码
功能开发	Skill（implement、review）	固化 TDD 等重复流程
测试补充	直接对话或 Skill	Claude 本身很擅长匹配测试风格
安全审计	Agent（只读权限）	需要隔离上下文、限制写权限
PR 与发布	直接对话	Claude 原生支持 gh pr create

避坑指南

1. 不要过度配置。Vanilla Claude Code + 一个好的 CLAUDE.md，比 20 个 skill + 10 个 agent 的过度工程化系统更好用。从痛点出发，逐步添加。

2. 不要把 CLAUDE.md 写太长。它占用每次对话的上下文。几十到一两百行足够，超过了就该拆分到 skill 里。

3. Skill 的 description 要写好。这是 Claude 自动识别的依据。描述清楚"什么时候该用"比描述"它能做什么"更重要。

4. Agent 的 description 同理。写得模糊会导致 Claude 频繁误委派或者该委派时不委派。

5. Plan Mode 不是万能的。简单的 bug 修复或小改动，直接让 Claude 做就行，不需要每次都先规划。Plan Mode 适合复杂任务、大型重构、不熟悉的代码库。

---

八、与 Cursor 的对比：为什么 Claude Code 中 Agent 没那么"重要"？

如果你从 Cursor 转过来，可能会觉得"Agent"是一个核心功能。但在 Claude Code 中，感受完全不同。

Cursor 是 IDE-first。它的默认体验是"你写代码，AI 帮你补全"。Agent 模式是一个重大的功能升级——让 AI 从被动辅助变成主动执行，可以自主编辑多个文件、运行命令。所以在 Cursor 里，"开不开 Agent 模式"是一个关键选择。

Claude Code 是 Agent-first。它打开就已经是一个全能 agent——能读整个代码库、改多个文件、跑测试、提交代码。你不需要"切换到 Agent 模式"。

所以 Claude Code 里的"自定义 Agent"不是"开启 agent 能力"，而是给已有的主 agent 配备下属专家。它是一种进阶优化手段，不是核心功能。大多数人只用 CLAUDE.md + Skill + Plan Mode 就能覆盖日常开发的绝大部分场景。

---

总结

Claude Code 的扩展体系可以用一句话概括：

CLAUDE.md 定规矩，Skill 教方法，Agent 请专家，Plan Mode 做规划。

不要被概念的数量吓到。从 CLAUDE.md 开始，遇到重复工作做成 Skill，遇到上下文问题引入 Agent，复杂任务先用 Plan Mode 想清楚。简单、渐进、按需——这就是最好的使用策略。

---