8.4 自定义斜杠命令

自定义斜杠命令是 Claude Code 中最强大的自动化功能之一。通过将常用的提示词保存为可重用的命令，你可以用简单的 /命令名 语法快速调用复杂的工作流程。

什么是自定义斜杠命令#

自定义斜杠命令本质上是保存的提示词模板，存储为 Markdown 文件。当你调用一个斜杠命令时，文件内容会作为提示词发送给 Claude，触发预定义的工作流程。

核心特性#

• 简单易用：只需创建 Markdown 文件即可定义命令
• 版本控制：命令文件可以纳入 Git 管理，与团队共享
• 参数支持：可以接收动态参数，实现灵活的命令调用
• 工具集成：可以执行 Bash 命令、引用文件内容
• 命名空间：支持分层组织，避免命令冲突

命令类型与作用域#

Claude Code 支持三种类型的自定义命令：

1. 项目级命令（Project Commands）#

• 位置：.claude/commands/
• 作用域：仅在当前项目中可用
• 优先级：最高（会覆盖同名的个人命令）
• 调用方式：/project:命令名 或 /命令名
• 适用场景：项目特定的工作流程，可与团队共享

bash
复制
# 创建项目级命令mkdir -p .claude/commands
echo"分析代码并提供改进建议"> .claude/commands/review.md

2. 个人级命令（Personal Commands）#

• 位置：~/.claude/commands/
• 作用域：所有项目中可用
• 优先级：中等
• 调用方式：/命令名
• 适用场景：个人常用的通用工作流程

bash
复制
# 创建个人级命令mkdir -p ~/.claude/commands
echo"检查代码风格和最佳实践"> ~/.claude/commands/lint.md

3. 插件命令（Plugin Commands）#

• 位置：插件的 commands/ 目录
• 作用域：插件范围
• 优先级：最低（自动添加命名空间）
• 调用方式：/插件名__命令名
• 适用场景：插件提供的专用功能

创建第一个自定义命令#

让我们从一个简单的例子开始，创建一个代码审查命令。

基础命令示例#

创建文件 .claude/commands/review.md：

markdown
复制
请审查以下代码，关注以下方面：

1. **代码质量**：检查代码结构、可读性和可维护性
2. **潜在问题**：识别可能的 bug、性能问题和安全隐患
3. **最佳实践**：确保遵循语言和框架的最佳实践
4. **改进建议**：提供具体的优化建议

请提供详细的分析报告。

使用方式：

bash
复制
# 在 Claude Code 中输入/project:review

命令参数#

自定义命令支持动态参数，让命令更加灵活。

参数语法#

• $ARGUMENTS：捕获所有参数
• $1, $2, $3...：位置参数
• $@：所有参数的数组形式

带参数的命令示例#

创建文件 .claude/commands/fix-issue.md：

markdown
复制
---
description: 修复指定的 GitHub Issue
argument-hint: issue-number
---

# 任务：修复 Issue #$1

## 步骤

1. **理解问题**
   - 查看 Issue #$1 的描述和讨论
   - 识别问题的根本原因

2. **实现修复**
   - 编写解决方案代码
   - 确保代码质量和测试覆盖

3. **验证修复**
   - 运行相关测试
   - 确认问题已解决

4. **提交更改**
   - 创建描述性的提交信息
   - 引用 Issue #$1

请开始修复工作。

使用方式：

bash
复制
/project:fix-issue 123

多参数命令示例#

创建文件 .claude/commands/compare.md：

markdown
复制
---
description: 比较两个文件的差异
argument-hint: file1 file2
---

比较以下两个文件并总结主要差异：

**文件 1**: $1
**文件 2**: $2

请分析：
1. 结构差异
2. 功能差异
3. 性能影响
4. 迁移建议

使用方式：

bash
复制
/project:compare src/old-api.js src/new-api.js

执行 Bash 命令#

自定义命令可以执行 Shell 命令并将输出嵌入到提示词中。

语法#

使用 ! 前缀执行命令：

markdown
复制
!`命令内容`

Git 状态命令示例#

创建文件 .claude/commands/git-status.md：

markdown
复制
---
description: 分析 Git 仓库状态
allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git log:*)
---

# Git 仓库状态分析

## 当前状态
!`git status`

## 最近的更改
!`git diff HEAD`

## 最近的提交
!`git log --oneline -10`

## 任务

基于以上信息：
1. 总结当前的更改
2. 识别未提交的文件
3. 建议下一步操作

测试运行命令示例#

创建文件 .claude/commands/test.md：

markdown
复制
---
description: 运行测试套件并分析结果
allowed-tools: Bash
---

# 运行测试套件

## 执行测试
!`npm test`

## 测试覆盖率
!`npm run test:coverage`

## 分析

请分析测试结果：
1. 识别失败的测试
2. 检查测试覆盖率
3. 提供改进建议

文件引用#

使用 @ 语法可以将文件内容包含到命令中。

语法#

markdown
复制
@文件路径

代码审查命令示例#

创建文件 .claude/commands/review-file.md：

markdown
复制
---
description: 审查指定文件
argument-hint: file-path
allowed-tools: Read
---

# 代码审查：$1

## 文件内容

@$1

## 审查要点

1. **代码质量**
   - 命名规范
   - 代码结构
   - 注释质量

2. **潜在问题**
   - 错误处理
   - 边界情况
   - 性能瓶颈

3. **安全性**
   - 输入验证
   - 敏感数据处理
   - 权限检查

请提供详细的审查报告和改进建议。

使用方式：

bash
复制
/project:review-file src/auth/login.js

Frontmatter 配置#

命令文件可以使用 YAML frontmatter 配置元数据和行为。

可用字段#

完整配置示例#

创建文件 .claude/commands/deploy.md：

markdown
复制
---
description: 部署应用到指定环境
argument-hint: environment (staging|production)
allowed-tools: Bash
model: sonnet
---

# 部署到环境：$1

## 部署前检查

### 代码质量检查
!`npm run lint`

### 运行测试
!`npm test`

## 构建应用

!`npm run build`

## 部署

!`npm run deploy:$1`

## 验证部署

!`curl https://$1.example.com/health`

## 报告

请报告部署状态和任何问题。

命令组织与命名空间#

随着命令数量增加，良好的组织结构变得重要。

目录结构#

使用子目录创建命名空间：

bash
复制
.claude/commands/
├── git/
│   ├── commit.md          # /project:git:commit
│   ├── status.md          # /project:git:status
│   └── review.md          # /project:git:review
├── test/
│   ├── unit.md            # /project:test:unit
│   ├── integration.md     # /project:test:integration
│   └── coverage.md        # /project:test:coverage
├── deploy/
│   ├── staging.md         # /project:deploy:staging
│   └── production.md      # /project:deploy:production
└── help.md                # /project:help

命名规范#

推荐使用动词-名词格式：

• /project:git:commit - Git 提交
• /project:test:run - 运行测试
• /project:deploy:staging - 部署到预发布环境
• /project:docs:generate - 生成文档

实用命令示例#

1. 智能提交命令#

创建文件 .claude/commands/git/smart-commit.md：

markdown
复制
---
description: 分析更改并创建规范的提交信息
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
---

# 智能 Git 提交

## 当前更改

!`git status`

## 差异详情

!`git diff --cached`

## 任务

1. 分析暂存的更改
2. 生成符合 Conventional Commits 规范的提交信息
3. 包含必要的说明和上下文
4. 如果有破坏性更改，添加 BREAKING CHANGE 标记
5. 执行提交

提交信息格式：

type(scope): subject

body

footer

bash
复制
类型：feat, fix, docs, style, refactor, test, chore

2. 代码重构命令#

创建文件 .claude/commands/refactor.md：

markdown
复制
---
description: 重构指定文件或模块
argument-hint: file-path
allowed-tools: Read, Edit
---

# 代码重构：$ARGUMENTS

## 当前代码

@$ARGUMENTS

## 重构目标

1. **提高可读性**
   - 改进命名
   - 简化复杂逻辑
   - 添加必要注释

2. **优化结构**
   - 提取重复代码
   - 分离关注点
   - 改进模块化

3. **性能优化**
   - 识别性能瓶颈
   - 优化算法复杂度
   - 减少不必要的计算

4. **保持功能**
   - 确保行为不变
   - 保持 API 兼容性

请执行重构并解释所做的更改。

3. 文档生成命令#

创建文件 .claude/commands/docs/generate.md：

markdown
复制
---
description: 为代码生成文档
argument-hint: file-path
allowed-tools: Read, Write
---

# 生成文档：$1

## 源代码

@$1

## 文档要求

1. **API 文档**
   - 函数/方法签名
   - 参数说明
   - 返回值说明
   - 使用示例

2. **架构说明**
   - 模块职责
   - 依赖关系
   - 设计决策

3. **使用指南**
   - 快速开始
   - 常见用例
   - 最佳实践

请生成完整的 Markdown 文档。

4. 安全审计命令#

创建文件 .claude/commands/security/audit.md：

markdown
复制
---
description: 执行安全审计
argument-hint: file-or-directory
allowed-tools: Read, Grep, Bash
---

# 安全审计：$ARGUMENTS

## 审计范围

目标：$ARGUMENTS

## 检查项目

1. **输入验证**
   - SQL 注入风险
   - XSS 漏洞
   - 命令注入

2. **身份认证**
   - 密码存储
   - 会话管理
   - 权限控制

3. **敏感数据**
   - 硬编码凭证
   - 日志泄露
   - 加密使用

4. **依赖安全**
   - 已知漏洞
   - 过时的包

## 执行审计

!`npm audit`

请提供详细的安全审计报告和修复建议。

5. 性能分析命令#

创建文件 .claude/commands/performance/analyze.md：

markdown
复制
---
description: 分析代码性能
argument-hint: file-path
allowed-tools: Read, Bash
---

# 性能分析：$1

## 代码内容

@$1

## 分析维度

1. **时间复杂度**
   - 算法效率
   - 循环嵌套
   - 递归深度

2. **空间复杂度**
   - 内存使用
   - 数据结构选择
   - 缓存策略

3. **I/O 操作**
   - 文件读写
   - 网络请求
   - 数据库查询

4. **优化建议**
   - 瓶颈识别
   - 优化方案
   - 预期收益

请提供详细的性能分析报告。

高级技巧#

1. 组合多个命令#

创建文件 .claude/commands/workflow/pre-commit.md：

markdown
复制
---
description: 提交前的完整检查流程
allowed-tools: Bash
---

# 提交前检查流程

## 1. 代码格式化

!`npm run format`

## 2. 代码检查

!`npm run lint`

## 3. 类型检查

!`npm run type-check`

## 4. 运行测试

!`npm test`

## 5. 构建验证

!`npm run build`

## 结果分析

请分析所有检查的结果，如果有问题请提供修复建议。
如果一切正常，建议可以安全提交。

2. 条件执行#

创建文件 .claude/commands/test/smart-test.md：

markdown
复制
---
description: 智能测试执行
argument-hint: file-path (optional)
allowed-tools: Bash, Grep
---

# 智能测试执行

## 分析更改

!`git diff --name-only HEAD`

## 执行策略

如果提供了文件路径 ($ARGUMENTS)：
- 仅运行相关测试

如果没有提供文件路径：
- 分析 git diff 中的更改
- 识别受影响的模块
- 运行相关测试套件

## 执行测试

请根据更改范围智能选择要运行的测试。

3. 交互式命令#

创建文件 .claude/commands/interactive/feature.md：

markdown
复制
---
description: 交互式功能开发向导
---

# 功能开发向导

我将引导你完成新功能的开发流程。

## 第 1 步：需求分析

请描述你要开发的功能：$ARGUMENTS

我需要了解：
1. 功能的目标用户是谁？
2. 核心功能是什么？
3. 有哪些边界情况需要考虑？

## 第 2 步：设计方案

基于你的回答，我将：
1. 设计 API 接口
2. 规划数据结构
3. 确定技术方案

## 第 3 步：实现

我将帮助你：
1. 创建必要的文件
2. 实现核心逻辑
3. 添加错误处理

## 第 4 步：测试

我将：
1. 编写单元测试
2. 创建集成测试
3. 验证功能完整性

让我们开始吧！

命令文档化#

创建一个帮助命令来列出所有可用的自定义命令。

创建文件 .claude/commands/help.md：

markdown
复制
---
description: 显示所有可用的自定义命令
---

# 自定义命令帮助

## Git 相关命令

- `/project:git:commit` - 智能 Git 提交
- `/project:git:status` - 分析 Git 状态
- `/project:git:review` - 审查 Git 更改

## 测试命令

- `/project:test:unit` - 运行单元测试
- `/project:test:integration` - 运行集成测试
- `/project:test:coverage` - 生成测试覆盖率报告
- `/project:test:smart-test` - 智能测试执行

## 部署命令

- `/project:deploy:staging` - 部署到预发布环境
- `/project:deploy:production` - 部署到生产环境

## 代码质量命令

- `/project:review` - 代码审查
- `/project:refactor` - 代码重构
- `/project:security:audit` - 安全审计
- `/project:performance:analyze` - 性能分析

## 文档命令

- `/project:docs:generate` - 生成文档

## 工作流命令

- `/project:workflow:pre-commit` - 提交前检查
- `/project:interactive:feature` - 交互式功能开发

使用 `/project:命令名 --help` 查看具体命令的详细说明。

最佳实践#

1. 命令设计原则#

• 单一职责：每个命令专注于一个明确的任务
• 清晰命名：使用描述性的命令名称
• 参数验证：在命令中包含参数检查逻辑
• 错误处理：考虑异常情况并提供友好的错误信息
• 文档完善：使用 description 和 argument-hint 提供清晰的说明

2. 安全考虑#

• 工具权限：使用 allowed-tools 限制命令可以使用的工具
• 命令审查：定期审查自定义命令，确保没有安全风险
• 敏感信息：避免在命令中硬编码密码、API 密钥等敏感信息
• 输入验证：对用户输入进行验证，防止命令注入

3. 性能优化#

• 避免重复：将常用的逻辑提取为独立命令
• 缓存结果：对于耗时的操作，考虑缓存结果
• 并行执行：在可能的情况下并行执行独立的任务
• 超时设置：为长时间运行的命令设置合理的超时

4. 团队协作#

• 版本控制：将 .claude/commands/ 目录纳入 Git 管理
• 命名规范：团队统一命令命名规范
• 文档维护：保持命令文档的更新
• 代码审查：对新增或修改的命令进行审查

常见问题#

1. 命令不生效#

问题：创建了命令文件，但无法调用

解决方案：

• 检查文件路径是否正确（.claude/commands/）
• 确认文件扩展名为 .md
• 重启 Claude Code 或重新加载配置
• 使用 /help 查看命令是否被识别

2. 参数传递问题#

问题：参数没有正确传递到命令中

解决方案：

• 使用 $ARGUMENTS 捕获所有参数
• 使用 $1, $2 等捕获位置参数
• 在命令中添加调试输出：参数内容：$ARGUMENTS

3. Bash 命令执行失败#

问题：! 命令无法执行

解决方案：

• 在 frontmatter 中添加 allowed-tools: Bash
• 检查命令语法是否正确
• 确认命令在当前环境中可用
• 使用完整路径或检查 PATH 环境变量

4. 文件引用失败#

问题：@ 语法无法读取文件

解决方案：

• 在 frontmatter 中添加 allowed-tools: Read
• 检查文件路径是否正确（相对于项目根目录）
• 确认文件存在且有读取权限

与其他功能的集成#

1. 与 MCP 集成#

MCP 服务器可以通过特殊的命名模式暴露提示词作为斜杠命令：

bash
复制
/mcp__服务器名__提示词名

例如：

bash
复制
/mcp__github__create-pr

2. 与 Hooks 集成#

可以在 Hooks 中自动触发自定义命令：

json
复制
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "slash-command",
        "command": "/project:test:smart-test"
      }]
    }]
  }
}

3. 与 Skills 集成#

自定义命令可以调用 Skills 提供的功能，实现更复杂的工作流程。

小结#

自定义斜杠命令是 Claude Code 中强大的自动化工具，通过合理设计和组织命令，可以显著提升开发效率。关键要点：

1. 简单开始：从简单的命令开始，逐步增加复杂度
2. 合理组织：使用命名空间和目录结构组织命令
3. 充分利用：结合参数、Bash 执行、文件引用等特性
4. 团队共享：将命令纳入版本控制，与团队共享最佳实践
5. 持续优化：根据实际使用情况不断改进命令

通过掌握自定义斜杠命令，你可以将重复的工作流程自动化，让 Claude Code 成为更加高效的开发助手。

参考资源#

• Claude Code 官方文档 - 斜杠命令
• .claude 目录规范
• 自定义命令最佳实践