8.4 自定义斜杠命令

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

什么是自定义斜杠命令

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

核心特性

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

命令类型与作用域

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

1. 项目级命令（Project Commands）

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

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

2. 个人级命令（Personal Commands）

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

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

3. 插件命令（Plugin Commands）

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

创建第一个自定义命令

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

基础命令示例

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

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

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

请提供详细的分析报告。

使用方式：

# 在 Claude Code 中输入
/project:review

命令参数

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

参数语法

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

带参数的命令示例

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

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

# 任务：修复 Issue #$1

## 步骤

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

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

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

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

请开始修复工作。

使用方式：

/project:fix-issue 123

多参数命令示例

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

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

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

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

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

使用方式：

/project:compare src/old-api.js src/new-api.js

执行 Bash 命令

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

语法

使用 ! 前缀执行命令：

!`命令内容`

Git 状态命令示例

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

---
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：

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

# 运行测试套件

## 执行测试
!`npm test`

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

## 分析

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

文件引用

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

语法

@文件路径

代码审查命令示例

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

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

# 代码审查：$1

## 文件内容

@$1

## 审查要点

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

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

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

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

使用方式：

/project:review-file src/auth/login.js

Frontmatter 配置

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

可用字段

字段	必需	说明
`description`	否	命令的简短描述，显示在命令列表中
`argument-hint`	否	参数提示文本，帮助用户了解期望的参数格式
`allowed-tools`	否	允许使用的工具列表（逗号分隔）
`model`	否	指定使用的模型：`sonnet`、`opus`、`haiku`
`disable-model-invocation`	否	设为 `true` 时，仅执行脚本而不调用 Claude

完整配置示例

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

---
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`

## 报告

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

命令组织与命名空间

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

目录结构

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

.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：

---
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


类型：feat, fix, docs, style, refactor, test, chore

2. 代码重构命令

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

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

# 代码重构：$ARGUMENTS

## 当前代码

@$ARGUMENTS

## 重构目标

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

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

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

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

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

3. 文档生成命令

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

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

# 生成文档：$1

## 源代码

@$1

## 文档要求

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

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

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

请生成完整的 Markdown 文档。

4. 安全审计命令

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

---
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：

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

# 性能分析：$1

## 代码内容

@$1

## 分析维度

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

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

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

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

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

高级技巧

1. 组合多个命令

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

---
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：

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

# 智能测试执行

## 分析更改

!`git diff --name-only HEAD`

## 执行策略

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

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

## 执行测试

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

3. 交互式命令

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

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

# 功能开发向导

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

## 第 1 步：需求分析

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

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

## 第 2 步：设计方案

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

## 第 3 步：实现

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

## 第 4 步：测试

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

让我们开始吧！

命令文档化

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

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

---
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 服务器可以通过特殊的命名模式暴露提示词作为斜杠命令：

/mcp__服务器名__提示词名

例如：

/mcp__github__create-pr

2. 与 Hooks 集成

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

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

3. 与 Skills 集成

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

小结

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

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

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

8.4 自定义斜杠命令

什么是自定义斜杠命令

核心特性

命令类型与作用域

1. 项目级命令（Project Commands）

2. 个人级命令（Personal Commands）

3. 插件命令（Plugin Commands）

创建第一个自定义命令

基础命令示例

命令参数

参数语法

带参数的命令示例

多参数命令示例

执行 Bash 命令

语法

Git 状态命令示例

测试运行命令示例

文件引用

语法

代码审查命令示例

Frontmatter 配置

可用字段

完整配置示例

命令组织与命名空间

目录结构

命名规范

实用命令示例

1. 智能提交命令

2. 代码重构命令

3. 文档生成命令

4. 安全审计命令

5. 性能分析命令

高级技巧

1. 组合多个命令

2. 条件执行

3. 交互式命令

命令文档化

最佳实践

1. 命令设计原则

2. 安全考虑

3. 性能优化

4. 团队协作

常见问题

1. 命令不生效

2. 参数传递问题

3. Bash 命令执行失败

4. 文件引用失败

与其他功能的集成

1. 与 MCP 集成

2. 与 Hooks 集成

3. 与 Skills 集成

小结

参考资源