自定义 Slash Commands 开发

Slash Commands 是什么

在 Claude Code 中输入 / 会弹出一个命令列表。除了内置命令（如 /help、/clear、/compact），我们还可以创建自定义的 Slash Commands。

自定义 Slash Commands 本质上是预定义的 Prompt 模板。它们让我们把常用的、复杂的指令封装成简短的命令，一键触发。

# 不用 Slash Command
请审查 src/ 目录下最近修改的文件，关注类型安全、错误处理和性能问题，
以 Markdown 格式输出审查报告，包含严重程度分级...

# 用 Slash Command
/review

---

创建自定义命令

命令文件位置

Slash Commands 是 Markdown 文件，放在特定目录下：

位置	作用范围	说明
.claude/commands/	当前项目	团队共享，提交到 Git
~/.claude/commands/	所有项目	个人命令，不提交

最简单的命令

创建 .claude/commands/review.md：

审查当前项目中最近修改的文件，关注：
1. 代码质量和可读性
2. 潜在的 Bug 和边界情况
3. 性能问题
4. 安全隐患

以 Markdown 格式输出审查报告。

使用：

/review

就这么简单——文件名就是命令名，文件内容就是发送给 Claude Code 的 Prompt。

命令文件格式

<!-- .claude/commands/命令名.md -->

这里是 Prompt 内容。
支持 Markdown 格式。
可以包含代码块、列表等。

$ARGUMENTS 会被替换为用户输入的参数。

---

参数化命令

$ARGUMENTS 变量

$ARGUMENTS 是一个特殊变量，会被替换为用户在命令后输入的文本：

<!-- .claude/commands/explain.md -->
详细解释以下代码文件的功能和实现逻辑：

$ARGUMENTS

请包含：
1. 文件的整体用途
2. 主要函数/类的作用
3. 关键算法的解释
4. 依赖关系

使用：

/explain src/utils/search.ts

Claude Code 收到的实际 Prompt：

详细解释以下代码文件的功能和实现逻辑：

src/utils/search.ts

请包含：
1. 文件的整体用途
2. 主要函数/类的作用
3. 关键算法的解释
4. 依赖关系

多参数的处理

$ARGUMENTS 是整个参数字符串，如果需要多个参数，可以在 Prompt 中说明格式：

<!-- .claude/commands/migrate.md -->
将以下文件从一种格式迁移到另一种格式。

参数格式：<源文件> <目标格式>
参数：$ARGUMENTS

示例：
- `src/config.js TypeScript` → 将 JS 文件转换为 TS
- `src/styles.css Tailwind` → 将 CSS 转换为 Tailwind

请执行迁移并确保功能不变。

使用：

/migrate src/config.js TypeScript

---

实用命令示例

/review - 代码审查

<!-- .claude/commands/review.md -->
对以下文件或目录进行代码审查：

$ARGUMENTS

如果没有指定文件，审查最近 git 变更的文件。

审查标准：
1. **类型安全**：是否有 any 类型、缺失的类型注解
2. **错误处理**：是否有未捕获的异常、缺失的错误边界
3. **性能**：是否有不必要的重渲染、内存泄漏风险
4. **安全**：是否有 XSS、注入等安全风险
5. **可读性**：命名是否清晰、逻辑是否易懂

输出格式：
## 审查报告

### 严重问题 🔴
（必须修复）

### 建议改进 🟡
（建议修复）

### 小建议 🟢
（可选优化）

### 总结
（整体评价和改进方向）

/test - 生成测试

<!-- .claude/commands/test.md -->
为以下文件生成单元测试：

$ARGUMENTS

测试框架：Vitest
测试要求：
1. 覆盖所有导出的函数/类
2. 包含正常路径和边界情况
3. Mock 外部依赖
4. 使用 describe/it 结构
5. 测试文件放在对应的 tests/ 目录

生成测试后，运行 `npx vitest run` 确认通过。
如果有失败的测试，修复它们。

/refactor - 重构

<!-- .claude/commands/refactor.md -->
重构以下代码：

$ARGUMENTS

重构原则：
1. 保持功能不变（行为等价）
2. 提高可读性和可维护性
3. 减少重复代码
4. 改善类型安全
5. 遵循 SOLID 原则

步骤：
1. 先读取并理解当前代码
2. 列出重构计划
3. 逐步执行重构
4. 运行测试确认功能不变
5. 输出重构前后的对比摘要

/doc - 生成文档

<!-- .claude/commands/doc.md -->
为以下代码生成文档：

$ARGUMENTS

文档要求：
1. 为所有导出的函数/类/接口添加 JSDoc/TSDoc 注释
2. 包含参数说明、返回值说明、使用示例
3. 如果是组件，添加 Props 说明
4. 如果是 API，添加请求/响应示例

不要修改代码逻辑，只添加文档注释。

/fix - 修复问题

<!-- .claude/commands/fix.md -->
修复以下问题：

$ARGUMENTS

修复流程：
1. 理解问题描述
2. 定位相关代码
3. 分析根本原因
4. 实施修复
5. 添加防止回归的测试
6. 运行现有测试确认没有破坏其他功能

如果问题描述是 Issue 编号（如 #42），先用 `gh issue view` 获取详情。

/deploy - 部署检查

<!-- .claude/commands/deploy.md -->
执行部署前检查：

$ARGUMENTS

检查清单：
1. **构建检查**：运行 `npm run build`，确认无错误
2. **类型检查**：运行 `npx tsc --noEmit`
3. **Lint 检查**：运行 `npm run lint`
4. **测试检查**：运行 `npm test`
5. **依赖检查**：检查是否有已知漏洞（`npm audit`）
6. **环境变量**：检查 .env.example 中的变量是否都有对应值

输出部署就绪报告，标注通过/未通过的检查项。

/perf - 性能分析

<!-- .claude/commands/perf.md -->
分析以下代码的性能：

$ARGUMENTS

分析维度：
1. **时间复杂度**：关键算法的 Big O 分析
2. **空间复杂度**：内存使用分析
3. **I/O 操作**：文件读写、网络请求的效率
4. **渲染性能**（如果是前端组件）：重渲染、DOM 操作
5. **数据库查询**（如果涉及）：N+1 问题、索引使用

给出具体的优化建议和代码示例。

---

项目命令 vs 用户命令

项目命令（团队共享）

放在 .claude/commands/，提交到 Git：

.claude/
└── commands/
    ├── review.md      # 代码审查
    ├── test.md        # 生成测试
    ├── deploy.md      # 部署检查
    └── fix.md         # 修复问题

适合：

• 团队统一的工作流
• 项目特定的操作
• 需要版本控制的命令

用户命令（个人使用）

放在 ~/.claude/commands/，不提交：

~/.claude/
└── commands/
    ├── explain-zh.md  # 用中文解释代码
    ├── commit.md      # 我的 commit 风格
    └── morning.md     # 每日开始的例行检查

适合：

• 个人偏好的工作流
• 跨项目通用的命令
• 实验性的命令

---

高级技巧

1. 命令组合

一个命令可以触发多个步骤：

<!-- .claude/commands/pr-ready.md -->
准备提交 PR，执行以下步骤：

1. 运行 `npm run lint:fix` 修复格式问题
2. 运行 `npm run test` 确认测试通过
3. 运行 `npx tsc --noEmit` 确认类型正确
4. 查看 `git diff --stat` 了解变更范围
5. 基于变更内容生成 PR 标题和描述
6. 使用 `gh pr create` 创建 PR

PR 的额外说明：$ARGUMENTS

2. 条件逻辑

在 Prompt 中加入条件判断：

<!-- .claude/commands/smart-fix.md -->
智能修复代码问题：

$ARGUMENTS

根据问题类型选择策略：
- 如果是 TypeScript 类型错误：修复类型定义，不改变运行时行为
- 如果是 ESLint 错误：优先使用 --fix 自动修复，手动修复剩余问题
- 如果是测试失败：先分析失败原因，再决定是修复代码还是更新测试
- 如果是运行时错误：添加错误处理，编写回归测试

3. 模板继承

通过引用其他文件实现模板复用：

<!-- .claude/commands/review-security.md -->
执行安全专项审查：

$ARGUMENTS

参考 .claude/prompts/security-checklist.md 中的安全检查清单。
参考 .claude/prompts/review-template.md 中的审查报告模板。

重点关注 OWASP Top 10 中的安全风险。

4. 上下文感知

命令可以利用项目上下文：

<!-- .claude/commands/new-feature.md -->
创建新功能：

$ARGUMENTS

请遵循以下项目约定：
1. 参考 CLAUDE.md 中的编码规范
2. 参考现有代码的风格（查看 src/ 目录下的文件）
3. 新组件放在 src/components/ 目录
4. 新工具函数放在 src/utils/ 目录
5. 为新代码编写测试
6. 更新相关文档

---

团队协作

共享命令的版本控制

# .gitignore
# 不要忽略项目命令
# .claude/commands/  ← 不要加这行

# 忽略个人配置
.claude/settings.local.json

命令的命名约定

建议团队统一命名规范：

前缀	含义	示例
无前缀	通用命令	review.md, test.md
check-	检查类	check-types.md, check-security.md
gen-	生成类	gen-test.md, gen-doc.md
fix-	修复类	fix-lint.md, fix-types.md

命令文档

在 .claude/commands/ 目录下创建一个 README：

<!-- .claude/commands/README.md -->
# 项目 Slash Commands

| 命令 | 说明 | 参数 |
|------|------|------|
| /review | 代码审查 | 文件路径（可选） |
| /test | 生成测试 | 文件路径 |
| /fix | 修复问题 | 问题描述或 Issue 编号 |
| /deploy | 部署检查 | 环境名称（可选） |
| /doc | 生成文档 | 文件路径 |

---

调试命令

查看命令列表

在 Claude Code 中输入 / 查看所有可用命令，包括自定义命令。

测试命令

创建命令后，直接在 Claude Code 中测试：

/review src/utils/format.ts

如果效果不理想，修改 .claude/commands/review.md 的内容，下次使用时自动生效。

常见问题

问题	原因	解决方案
命令不出现在列表中	文件位置不对	确认在 .claude/commands/ 目录下
命令不出现在列表中	文件扩展名不对	必须是 .md 文件
$ARGUMENTS 没有被替换	拼写错误	确认是 $ARGUMENTS（全大写）
命令效果不好	Prompt 不够清晰	添加更多上下文和约束

---

从简单到复杂

入门：3 个必备命令

刚开始使用自定义命令，建议先创建这三个：

1. /review - 代码审查
2. /test - 生成测试
3. /fix - 修复问题

进阶：工作流命令

熟悉后，创建覆盖完整工作流的命令：

4. /pr-ready - PR 准备
5. /deploy - 部署检查
6. /refactor - 代码重构

高级：领域特定命令

根据项目特点创建专属命令：

7. /new-api - 创建新的 API 端点
8. /new-component - 创建新的 React 组件
9. /db-migrate - 数据库迁移辅助

---

Slash Commands 是 Claude Code 的”快捷键”。好的命令设计能把 5 分钟的 Prompt 编写压缩到 1 秒钟的命令输入。花时间打磨你的命令库，就像打磨你的 IDE 配置一样——它会在每一天的工作中回报你。