2.1 Slash Commands 基础与自定义

什么是 Slash Commands

Slash Commands 是 Claude Code 中以 / 开头的快捷指令（类似于 Claude 的快捷键组合）

核心价值

价值	说明
效率提升	一个 Ctrl+C 和 Ctrl+V 的操作，Slash Commands 一行搞定
工作流复用	类似 Linux 的 `alias ll='ls -la'`，把常用操作变成简单命令
团队协作	团队成员共享同一套标准化工作流

内置 Slash Commands

Claude Code 提供多个内置命令

命令	功能	使用场景
`/clear`	清空对话历史	开始新任务时清理上下文
`/compact [指令]`	压缩对话历史	对话过长影响性能时
`/help`	显示帮助信息	查看所有命令
`/model`	切换 AI 模型	在 Sonnet/Opus/Haiku 间切换
`/cost`	查看 Token 消耗	监控成本
`/status`	显示会话状态和配置信息	调试配置问题
`/config`	打开配置编辑器	修改设置
`/add-dir`	添加工作目录	让 Claude 访问更多文件
`/mcp`	管理 MCP 服务器	配置外部工具
`/doctor`	诊断 Claude Code 安装问题	排查故障

使用示例：

bash

# 开始新任务时清理上下文
> /clear

# 当对话过长影响性能时
> /compact 请保留关于用户认证模块的核心讨论

自定义 Slash Commands

最强大的特性：你可以创建自己的专属命令，实现任何自定义工作流

存储位置

位置	路径	说明	显示标记
项目级	`.claude/commands/`	仅对当前项目有效，可 Git 共享	`(project)`
用户级	`~/.claude/commands/`	对所有项目有效	`(user)`

优先级：项目命令优先于用户命令

命名规则

自定义命令是 Markdown 文件（.md），文件名即命令名

.claude/commands/
   fix-issue.md        → /fix-issue
   code-review.md      → /code-review
   create-test.md      → /create-test
   frontend/
       component.md    → /component (project:frontend)

创建你的第一个自定义命令

最简命令

创建文件 .claude/commands/hello.md

markdown

请用友好的方式打招呼，并简要介绍你能帮助完成的开发任务。

调用：

bash

> /hello

一行文本即可让你拥有一个可复用的 Claude 指令

带 Frontmatter 的命令

Frontmatter 是可选的 YAML 头部，提供额外配置

markdown

---
description: 执行标准化代码审查
allowed-tools: Read, Edit
argument-hint: [文件路径]
model: claude-sonnet-4-20250514
---

执行标准化代码审查流程：
1. 检查代码风格
2. 识别潜在问题
3. 给出优化建议和具体代码示例
4. 总结审查结论

审查目标：$ARGUMENTS

Frontmatter 配置项

字段	说明	示例
`description`	命令描述（在 /help 中显示）	`"修复 GitHub Issue"`
`allowed-tools`	允许使用的工具	`Read, Edit, Bash(git:*)`
`argument-hint`	参数提示	`[issue-number] [priority]`
`model`	指定使用的模型	`claude-sonnet-4-20250514`
`disable-model-invocation`	禁止切换 Claude 调用的其他命令	`true`

参数化命令

`$ARGUMENTS` - 捕获所有参数

markdown

---
description: 自动修复 GitHub Issue
argument-hint: [issue-number]
---

修复 Issue #$ARGUMENTS
1. 使用 gh issue view 获取详情
2. 分析问题
3. 实现修复
4. 创建 PR

调用：

bash

> /fix-issue 123
# $ARGUMENTS 为: "123"

> /fix-issue 456 高优先级
# $ARGUMENTS 为: "456 高优先级"

`$1`, `$2`, `$3`... - 位置参数

markdown

---
description: 审查 PR 并设置优先级和分配
argument-hint: [pr-number] [priority] [assignee]
---

审查 PR #$1
- 优先级：$2
- 分配给：$3

审查要点：
1. 代码质量
2. 测试覆盖
3. 安全检查

调用：

bash

> /review-pr 456 high alice
# $1 = "456", $2 = "high", $3 = "alice"

高级语法技巧

1. 执行 Bash 命令（使用反引号包裹）

在命令中嵌入可执行的 Shell 指令

markdown

---
description: 显示当前项目的 Git 状态
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
---

## 项目状态

- Git 状态：`git status`
- 当前变更：`git diff HEAD`
- 当前分支：`git branch --show-current`
- 最近提交：`git log --oneline -5`

## 操作指南

根据状态信息，提供项目当前 Git 状态的完整分析：
1. 未提交的更改
2. 遵循 Conventional Commits 规范的提交建议
3. 执行提交命令

2. 引用上下文文件（使用 @ 符号）

markdown

---
description: 显示配置文件概览
---

请分析以下配置文件概览：
- 项目配置：@package.json
- TypeScript 配置：@tsconfig.json
- 环境配置：@.env.example

分析内容：
1. 依赖关系
2. 构建配置概览
3. 配置优化建议

3. 命令分类组织

使用子文件夹组织命令

.claude/commands/
   frontend/
      component.md      → /component (project:frontend)
      style-check.md    → /style-check (project:frontend)
   backend/
      api-test.md       → /api-test (project:backend)
      db-migrate.md     → /db-migrate (project:backend)
   review.md             → /review (project)

注意：子文件夹名会显示在命令后面帮助区分同名命令

实战案例

案例 1：GitHub Issue 自动修复

文件路径： .claude/commands/fix-github-issue.md

markdown

---
description: 修复 GitHub Issue
argument-hint: [issue-number]
allowed-tools: Bash(gh:*), Read, Edit, Grep, Glob
---

# 修复 GitHub Issue #$ARGUMENTS

## 第一步：获取信息

执行：`gh issue view $ARGUMENTS`

## 第二步：分析问题

根据 Issue 描述：
1. 分析问题根本原因
2. 定位相关代码
3. 列出可能的修复方案

## 第三步：实现修复

1. 修改必要的代码文件
2. 添加适当的错误处理
3. 确保代码符合项目规范

## 第四步：验证

1. 运行相关测试
2. 确认修改无 lint 错误
3. 验证功能正常工作

## 第五步：提交

创建符合规范的提交信息（包含 Issue 引用）

调用：

bash

> /fix-github-issue 42

案例 2：代码审查命令

文件路径： .claude/commands/code-review.md

markdown

---
description: 执行标准化代码审查
allowed-tools: Read, Grep, Glob, Bash(git diff:*)
---

# 代码审查

## 获取变更文件
执行：`git diff --name-only HEAD~1`

## 获取具体变更
执行：`git diff HEAD~1`

## 审查要点

请对上述代码变更进行全面审查：

### 1. 代码质量
- [ ] 逻辑正确性
- [ ] 命名规范
- [ ] 参数验证

### 2. 安全检查
- [ ] 无 SQL 注入风险
- [ ] 无 XSS 漏洞
- [ ] 敏感信息无泄露

### 3. 性能考量
- [ ] 无明显性能问题
- [ ] 内存使用合理
- [ ] 数据库查询优化

### 4. 可维护性
- [ ] 代码易于理解
- [ ] 有适当的注释

请提供完整审查报告，包括问题列表、严重程度和修复建议。

案例 3：React 组件生成器

文件路径： .claude/commands/frontend/react-component.md

markdown

---
description: 创建 React 组件
argument-hint: [ComponentName]
allowed-tools: Write, Read
---

# 创建 React 组件：$1

## 参考现有组件规范
@src/components/Button.tsx

## 生成要求

在 `src/components/` 目录下创建组件 `$1`

1. **主文件** `$1.tsx`
   - 使用 TypeScript
   - 使用函数组件
   - 定义 Props 接口
   - 添加 JSDoc 注释

2. **样式文件** `$1.module.css`
   - 使用 CSS Modules
   - 遵循 BEM 命名

3. **导出更新** 更新 `src/components/index.ts`

## 组件功能

- 支持 className 传入
- 支持 ref 转发
- 确保可访问性符合规范

调用：

bash

> /react-component UserProfile

案例 4：TDD 开发循环

文件路径： .claude/commands/tdd-cycle.md

markdown

---
description: TDD 开发循环辅助
argument-hint: [功能描述]
allowed-tools: Read, Write, Edit, Bash
---

# TDD 循环：$ARGUMENTS

## 第一步（红灯阶段）

1. 根据需求 "$ARGUMENTS" 编写失败的测试
2. 测试要点：
   - 测试文件正确命名
   - 测试粒度适当
   - 遵循 AAA 模式（Arrange-Act-Assert）

运行测试确认失败：
执行：`npm test -- --watchAll=false 2>&1 | tail -20`

## 第二步（绿灯阶段）

1. 编写最少量代码让测试通过
2. 不要过度设计
3. 再次运行测试确认通过

## 第三步（重构阶段）

1. 在测试保护下重构代码
2. 改进代码质量
3. 确认测试仍然通过后结束

重复以上步骤直到功能完整且代码质量满足要求

案例 5：上下文保存与恢复

文件路径： ~/.claude/commands/context-save.md

markdown

---
description: 保存当前工作上下文
allowed-tools: Write, Bash
---

# 保存工作上下文

请将当前对话的关键信息保存到 `.claude/context-snapshot.md`：

## 项目信息
- 当前时间：`date`
- 当前分支：`git branch --show-current`
- 最近提交：`git log --oneline -3`

## 当前正在进行的任务
[请总结当前对话中讨论的主要任务]

## 已完成的工作
[列出已完成的操作]

## 待办事项
[列出尚未完成或需要后续处理的事项]

## 重要决策记录
[记录重要的技术决策]

文件路径： ~/.claude/commands/context-restore.md

markdown

---
description: 恢复之前保存的工作上下文
allowed-tools: Read
---

# 恢复工作上下文

请读取并理解之前保存的工作状态：

@.claude/context-snapshot.md

然后：
1. 总结上次会话的工作状态
2. 确认待办事项
3. 准备继续未完成的工作

对比：Slash Commands vs Skills

维度	Slash Commands	Skills
复杂度	简单快捷指令	复杂工作流程
文件结构	单个 `.md` 文件	文件夹 + `SKILL.md` + 资源
调用方式	显式使用 `/command`	Claude 自动判断调用
使用场景	明确的单一操作	复杂的多步骤任务
参数传递	`$ARGUMENTS`, `$1`, `$2`	配置文件驱动

选择指南

使用 Slash Commands 当：

需要简单快捷的操作
参数明确可预知
执行一次性任务
流程相对固定

使用 Skills 当：

复杂度高的多步骤任务
需要持久化的数据或配置
Claude 自动判断调用的场景
需要共享模板和资源

实用技巧

1. 工具权限控制

markdown

---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
---

模式说明：

Bash(git:*) — 允许所有 git 命令
Bash(npm run:*) — 允许所有 npm run 命令
Read, Grep, Glob — 只读操作

2. 命令发现

bash

# 查看所有可用命令
> /help

# 命令显示格式
/command-name (project)   # 项目命令
/command-name (user)      # 用户命令

3. 调试技巧

bash

# 查看命令文件内容
cat .claude/commands/my-command.md

# 测试参数替换
echo "Arguments: test1 test2" | sed 's/Arguments/\$ARGUMENTS/'

实践最佳建议

命令设计原则

单一职责 — 每个命令只做一件事
参数明确 — 使用 argument-hint 清晰说明需要什么参数
描述清晰 — description 要一目了然，方便快速选择
工具最小化 — allowed-tools 只授予必要的工具权限

组织结构建议

.claude/commands/
   git/
      commit.md
      pr.md
   test/
      unit.md
      e2e.md
   review/
      code.md
      security.md
   README.md          # 命令说明文档

维护建议

提交到 Git — 项目命令应该在 .claude/commands/ 下并提交
版本管理 — 重要命令应该有版本记录
文档完善 — 编写 README 说明每个命令的用法

自检清单

创建命令前的检查：

[ ] 命令名称是否清晰表达功能（名称 = 命令作用）
[ ] description 是否完整
[ ] 参数使用是否正确（$ARGUMENTS 或 $1, $2）
[ ] allowed-tools 是否设置
[ ] 最佳执行路径是否测试过
[ ] 测试命令在典型场景下运行正常

本节小结

Slash Commands = 效率快捷键！ — 一键执行复杂操作
两种存储方式 — 项目级共享、用户级私有
Markdown 格式 — 简单易维护
参数灵活多样 — $ARGUMENTS 捕获全部，$1, $2 位置参数
高级语法 — ` 执行命令，@ 引用文件
权限控制 — allowed-tools 限制使用的工具

下一节： 2.2 Skills 基础概念和结构 — 了解比 Commands 更强大的 Skills 系统

参考资料：

2.1 Slash Commands 基础与自定义 ​

什么是 Slash Commands ​

核心价值 ​

内置 Slash Commands ​

使用示例： ​

自定义 Slash Commands ​

存储位置 ​

命名规则 ​

创建你的第一个自定义命令 ​

最简命令 ​

带 Frontmatter 的命令 ​

Frontmatter 配置项 ​

参数化命令 ​

$ARGUMENTS - 捕获所有参数 ​

$1, $2, $3... - 位置参数 ​

高级语法技巧 ​

1. 执行 Bash 命令（使用反引号包裹） ​

2. 引用上下文文件（使用 @ 符号） ​

3. 命令分类组织 ​

实战案例 ​

案例 1：GitHub Issue 自动修复 ​

案例 2：代码审查命令 ​

案例 3：React 组件生成器 ​

案例 4：TDD 开发循环 ​

案例 5：上下文保存与恢复 ​

对比：Slash Commands vs Skills ​

选择指南 ​

实用技巧 ​

1. 工具权限控制 ​

2. 命令发现 ​

3. 调试技巧 ​

实践最佳建议 ​

命令设计原则 ​

组织结构建议 ​

维护建议 ​

自检清单 ​

本节小结 ​

2.1 Slash Commands 基础与自定义

什么是 Slash Commands

核心价值

内置 Slash Commands

使用示例：

自定义 Slash Commands

存储位置

命名规则

创建你的第一个自定义命令

最简命令

带 Frontmatter 的命令

Frontmatter 配置项

参数化命令

`$ARGUMENTS` - 捕获所有参数

`$1`, `$2`, `$3`... - 位置参数

高级语法技巧

1. 执行 Bash 命令（使用反引号包裹）

2. 引用上下文文件（使用 @ 符号）

3. 命令分类组织

实战案例

案例 1：GitHub Issue 自动修复

案例 2：代码审查命令

案例 3：React 组件生成器

案例 4：TDD 开发循环

案例 5：上下文保存与恢复

对比：Slash Commands vs Skills

选择指南

实用技巧

1. 工具权限控制

2. 命令发现

3. 调试技巧

实践最佳建议

命令设计原则

组织结构建议

维护建议

自检清单

本节小结