8.4 自定义斜杠命令
约 3812 字大约 13 分钟
自定义斜杠命令是 Claude Code 中最强大的自动化功能之一。通过将常用的提示词保存为可重用的命令,你可以用简单的 /命令名 语法快速调用复杂的工作流程。
什么是自定义斜杠命令
自定义斜杠命令本质上是保存的提示词模板,存储为 Markdown 文件。当你调用一个斜杠命令时,文件内容会作为提示词发送给 Claude,触发预定义的工作流程。
核心特性
- 简单易用:只需创建 Markdown 文件即可定义命令
- 版本控制:命令文件可以纳入 Git 管理,与团队共享
- 参数支持:可以接收动态参数,实现灵活的命令调用
- 工具集成:可以执行 Bash 命令、引用文件内容
- 命名空间:支持分层组织,避免命令冲突
命令类型与作用域
Claude Code 支持三种类型的自定义命令:
1. 项目级命令(Project Commands)
- 位置:.claude/commands/
- 作用域:仅在当前项目中可用
- 优先级:最高(会覆盖同名的个人命令)
- 调用方式:/project:命令名 或 /命令名
- 适用场景:项目特定的工作流程,可与团队共享
# 创建项目级命令
mkdir -p .claude/commands
echo "分析代码并提供改进建议" > .claude/commands/review.md2. 个人级命令(Personal Commands)
- 位置:~/.claude/commands/
- 作用域:所有项目中可用
- 优先级:中等
- 调用方式:/命令名
- 适用场景:个人常用的通用工作流程
# 创建个人级命令
mkdir -p ~/.claude/commands
echo "检查代码风格和最佳实践" > ~/.claude/commands/lint.md3. 插件命令(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.jsFrontmatter 配置
命令文件可以使用 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
footer
类型:feat, fix, docs, style, refactor, test, chore2. 代码重构命令
创建文件 .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__github__create-pr2. 与 Hooks 集成
可以在 Hooks 中自动触发自定义命令:
{
"hooks": {
"PostToolUse": [{
"matcher": "Edit|Write",
"hooks": [{
"type": "slash-command",
"command": "/project:test:smart-test"
}]
}]
}
}3. 与 Skills 集成
自定义命令可以调用 Skills 提供的功能,实现更复杂的工作流程。
小结
自定义斜杠命令是 Claude Code 中强大的自动化工具,通过合理设计和组织命令,可以显著提升开发效率。关键要点:
- 简单开始:从简单的命令开始,逐步增加复杂度
- 合理组织:使用命名空间和目录结构组织命令
- 充分利用:结合参数、Bash 执行、文件引用等特性
- 团队共享:将命令纳入版本控制,与团队共享最佳实践
- 持续优化:根据实际使用情况不断改进命令
通过掌握自定义斜杠命令,你可以将重复的工作流程自动化,让 Claude Code 成为更加高效的开发助手。
参考资源
- Claude Code 官方文档 - 斜杠命令
- .claude 目录规范
- 自定义命令最佳实践