书籍 / Claude 完全指南：从 API 到 Agent 生产实战
第 43 章

Hooks 系统：26种事件 / 5种钩子类型 / stdin-stdout 协议完全指南

第四十三章：Claude Code Slash Commands：自定义工作流与技能复用

43.1 什么是 Slash Commands

在 Claude Code 的交互界面中，你可以输入以 / 开头的命令来触发预定义的工作流。这些命令被称为 Slash Commands（斜杠命令）。

Claude Code 内置了一些系统级 Slash Commands，例如：

但真正强大的是自定义 Slash Commands——你可以为自己的项目创建专属命令，将重复性工作流封装成一个简短的命令，在需要时随时调用。

想象一下：你每次需要添加新功能时，都要告诉 Claude"先写测试，确保测试失败，再写实现，确保测试通过，最后更新文档"。有了自定义命令，你只需输入 /feature，Claude 就会自动遵循这个完整流程。

43.2 自定义命令的存储位置

自定义 Slash Commands 存储在 .claude/commands/ 目录下，每个命令是一个 Markdown 文件：

项目根目录/
└── .claude/
    └── commands/
        ├── feature.md       # /feature 命令
        ├── review.md        # /review 命令
        ├── debug.md         # /debug 命令
        ├── deploy-check.md  # /deploy-check 命令
        └── refactor.md      # /refactor 命令

文件名（不含 .md 扩展名）就是命令名称。feature.md 对应的命令是 /feature。

同样，你可以在 ~/.claude/commands/ 中存放个人全局命令，这些命令在所有项目中都可用：

~/.claude/
└── commands/
    ├── standup.md      # 每日站会摘要命令（全局可用）
    ├── pr-review.md    # PR 审查命令（全局可用）
    └── explain.md      # 代码解释命令（全局可用）

43.3 命令文件的格式

命令文件本质上是一个给 Claude 的提示词（Prompt），但它有一些特殊的语法支持。

基础格式

# /feature —— 功能开发完整流程

你现在要帮助我开发一个新功能。请按照以下步骤执行：

## 步骤 1：理解需求
首先询问用户：
- 功能的名称和用途
- 接受标准（Acceptance Criteria）
- 涉及的模块或文件范围

## 步骤 2：写失败的测试
在实现功能之前，先写测试：
1. 创建测试文件（如果不存在）
2. 根据接受标准编写测试用例
3. 运行测试，确认它们失败（红灯）
4. 向用户展示失败的测试输出

## 步骤 3：实现功能
根据测试要求实现功能：
1. 分析测试用例，理解期望的行为
2. 编写最小化实现，使测试通过
3. 运行测试，确认它们通过（绿灯）

## 步骤 4：重构与文档
1. 检查代码是否符合项目规范
2. 如有必要，进行重构（保持测试通过）
3. 更新或创建相关文档

完成后，向用户提供一个简短的实现总结。

使用 $ARGUMENTS 接收参数

命令文件中可以使用 $ARGUMENTS 占位符，它会被替换为用户在命令后面输入的文本：

# /explain —— 代码解释

请解释以下代码或文件：`$ARGUMENTS`

在解释中包括：
1. 这段代码的主要功能
2. 关键的设计决策
3. 可能的改进点
4. 相关的使用示例

请用中文解释，语言要清晰、适合中级开发者理解。

使用时：

/explain src/utils/tokenizer.ts

$ARGUMENTS 会被替换为 src/utils/tokenizer.ts，Claude 就知道要解释哪个文件了。

使用 @file 引用上下文

在命令文件中，可以用 @文件路径 语法引用项目中的文件，将其内容注入命令上下文：

# /review —— 代码审查

请对 $ARGUMENTS 进行代码审查。

审查时参考以下标准：
@docs/code-review-checklist.md

请按照以下维度给出审查意见：
1. 代码正确性
2. 性能考量
3. 安全性
4. 可读性与可维护性
5. 测试覆盖

最后给出一个总体评分（1-10）和最重要的改进建议。

43.4 实用命令库：从实战中提炼

以下是一组经过实践验证的自定义命令，涵盖了日常开发的常见场景：

/feature：功能开发 TDD 流程

# /feature —— TDD 功能开发

功能名称或描述：$ARGUMENTS

请按 TDD（测试驱动开发）流程实现这个功能：

**阶段一：规划（先不要写代码）**
1. 分析这个功能需要修改哪些文件
2. 识别需要测试的核心行为（3-5 个关键场景）
3. 向我确认理解是否正确

**阶段二：写测试**
1. 创建或更新测试文件
2. 为每个核心行为写一个测试用例
3. 运行：`pnpm test $ARGUMENTS_TEST_FILE`
4. 确认所有新测试都失败（这是正确的）

**阶段三：实现**
1. 写最简实现，使测试通过
2. 运行测试，确认全部通过
3. 展示最终通过的测试输出

**阶段四：收尾**
1. 检查代码是否符合 CLAUDE.md 中的规范
2. 必要时重构（保持测试通过）
3. 用一段话总结你做了什么

/review：代码审查

# /review —— 代码审查

审查目标：$ARGUMENTS

**审查流程：**

首先，读取并理解以下文件：$ARGUMENTS

然后，从以下维度进行审查：

**1. 功能正确性**
- 逻辑是否正确？
- 边界情况是否处理？
- 错误处理是否完善？

**2. 代码质量**
- 命名是否清晰、有意义？
- 函数是否单一职责？
- 是否有重复代码可以提取？

**3. 性能**
- 是否有明显的性能问题（N+1 查询、不必要的重渲染等）？
- 大数据量下的表现如何？

**4. 安全性**
- 是否有 SQL 注入、XSS 等安全漏洞？
- 敏感数据是否正确处理？

**5. 可测试性**
- 现有测试是否充分？
- 是否有未覆盖的重要场景？

最后，给出优先级排序的改进建议（P0 必须修复，P1 建议修复，P2 可选优化）。

/debug：系统性调试

# /debug —— 系统性调试

问题描述：$ARGUMENTS

请用系统性方法帮我调试这个问题：

**步骤 1：理解问题**
- 症状是什么？（实际行为 vs 期望行为）
- 这个问题是什么时候开始的？
- 可以稳定复现吗？

**步骤 2：收集信息**
请帮我查看以下内容：
1. 相关的错误日志（如有）
2. 涉及的代码文件
3. 最近的 git 变更（`git log --oneline -10`）

**步骤 3：形成假设**
基于收集到的信息，列出 2-3 个可能的原因，并按可能性排序。

**步骤 4：验证假设**
对每个假设，提出具体的验证方法（添加日志、写测试用例等）。

**步骤 5：实施修复**
确认根因后，实施修复并验证问题解决。

/migrate：数据库迁移

# /migrate —— 数据库迁移辅助

迁移需求：$ARGUMENTS

**注意：数据库迁移是高风险操作，请严格按步骤执行。**

**步骤 1：分析影响**
1. 哪些表会被修改？
2. 是否有数据需要转换？
3. 是否会影响现有查询或索引？
4. 生产数据量大概是多少？（影响迁移时间）

**步骤 2：准备迁移脚本**
1. 修改 schema.prisma（如适用）
2. 生成迁移文件：`pnpm db:migrate`
3. 检查生成的 SQL，确认符合预期

**步骤 3：本地验证**
1. 在本地数据库应用迁移：`pnpm db:push`
2. 运行相关测试
3. 手动验证数据完整性

**步骤 4：回滚方案**
写出如果迁移失败的回滚步骤。

**重要提示：**
- 不要在高峰期执行迁移
- 生产迁移前一定要备份
- 考虑使用蓝绿部署减少停机时间

/standup：生成站会摘要（全局命令）

# /standup —— 每日站会摘要

请根据今天的工作生成一个站会摘要。

**数据来源：**
请执行以下命令收集信息：
1. `git log --since="yesterday" --author="$(git config user.name)" --oneline`
2. `git diff --stat HEAD~5 HEAD`

**摘要格式：**

**昨天完成：**
[基于 git log 总结完成的工作]

**今天计划：**
[询问用户今天的计划，或基于未完成的工作推断]

**阻塞与风险：**
[是否有需要帮助的问题？]

请用简洁、专业的语言，控制在 3-5 句话。

43.5 命令的高级技巧

命令链式调用

在一个命令中，你可以引导 Claude 在完成后提示用户运行下一个命令，实现工作流的链式执行：

# /new-component —— 创建新 React 组件

创建名为 `$ARGUMENTS` 的 React 组件。

1. 在 `src/components/$ARGUMENTS/` 目录下创建：
   - `index.tsx`（组件主体）
   - `$ARGUMENTS.test.tsx`（测试文件）
   - `$ARGUMENTS.stories.tsx`（Storybook stories）
   - `types.ts`（类型定义）

2. 实现一个带 Props 类型和基础 JSDoc 的组件骨架

3. 完成后提示用户：
   "组件已创建。建议运行 `/review src/components/$ARGUMENTS/` 进行代码审查。"

命令中的条件逻辑

命令文件支持自然语言描述的条件逻辑，Claude 会根据实际情况执行：

# /cleanup —— 代码清理

对 $ARGUMENTS 进行代码清理。

**如果是 TypeScript 文件：**
- 修复所有 TypeScript 报错
- 移除未使用的导入
- 确保所有导出函数有类型注解

**如果是测试文件：**
- 移除重复的测试用例
- 确保每个测试有清晰的描述
- 检查是否有被注释掉的测试（可能需要删除或恢复）

**如果是整个目录：**
- 先列出目录中的文件
- 按优先级逐个处理
- 提供一个处理完成的摘要

使用 Bash 命令收集上下文

命令文件中可以引导 Claude 运行 Shell 命令来收集信息，再基于信息做决策：

# /health-check —— 项目健康检查

请对当前项目进行健康检查，收集并分析以下信息：

**代码质量**
```bash
npm run lint 2>&1 | head -50

测试状态

npm test -- --passWithNoTests 2>&1 | tail -20

依赖安全

npm audit --audit-level=moderate 2>&1 | head -30

TypeScript 错误

npx tsc --noEmit 2>&1 | head -30

基于以上输出，给出项目当前状态的评估和需要优先处理的问题列表。


## 43.6 技能复用：构建团队命令库

自定义 Slash Commands 最强大的价值在于**团队技能共享**。当一个工程师总结出某种高效的工作流，可以将其编写为命令文件，提交到项目仓库，让整个团队都能使用。

### 建立命令库的最佳实践

**1. 命令命名约定**

动词-名词 格式： /create-component # 创建组件 /test-api # 测试 API /review-pr # 审查 PR

单词命令（常用动作）： /review # 代码审查 /debug # 调试 /deploy # 部署检查 /migrate # 数据库迁移


**2. 命令文档化**

每个命令文件的开头应该有清晰的说明：

```markdown
# /review —— 代码审查

**用途**：对指定的文件或目录进行全面的代码审查
**参数**：文件路径或目录路径（可选，不提供则审查当前修改的文件）
**示例**：
  /review src/api/users.ts
  /review src/components/

**输出**：按优先级排序的改进建议列表

---
[命令内容...]

3. 版本迭代命令

随着项目演进，命令也需要更新。在 CLAUDE.md 中记录命令库的变更历史，并鼓励团队成员在遇到命令不满足需求时提出改进：

## Slash Commands 使用指南

项目命令位于 `.claude/commands/`。

常用命令：
- `/feature <描述>` — TDD 功能开发
- `/review <文件>` — 代码审查
- `/debug <问题>` — 系统性调试

如果某个命令的工作流不满足你的需求，请提 PR 改进它。

43.7 命令与 Hooks 的协作

Slash Commands 和 Hooks 可以形成强大的协作：

这种分层设计意味着：

两者配合，构成了 Claude Code 工程化的完整闭环。

小结

Slash Commands 是 Claude Code 工作流自动化的核心工具。

关键要点：

本章评分
4.6  / 5  (3 评分)

💬 留言讨论