<!-- title: Claude Code自定义命令开发：八种实战模式 -->

## 概述

本教程面向已掌握Claude Code基本操作的初中级开发者，目标是通过系统学习自定义命令（Custom Slash Commands）的开发，将日常重复性编码工作自动化。学完本教程，你将理解命令与Skill的本质区别，掌握八种实战命令模式的编写方法，并能为团队构建可复用的命令标准库。

**适用人群**：有1-3个月Claude Code使用经验，希望提升团队协作效率的开发者。

## 前置条件

| 条件 | 说明 |
|------|------|
| Claude Code | 已安装v1.0+，可通过 `claude --version` 确认 |
| 基础知识 | 熟悉终端操作、Markdown语法 |
| 项目环境 | 至少有一个Git仓库可供练习 |
| 编辑器 | VS Code或其他支持Markdown高亮的编辑器 |

## 第一步：理解命令系统架构

### 命令 vs Skill：何时用哪个

Claude Code提供两种扩展机制——自定义命令和Skills。很多开发者混淆二者，导致选型失误。

```mermaid
flowchart LR
    A[扩展需求] --> B{需要自动触发？}
    B -->|否| C{需要多文件结构？}
    B -->|是| D[使用 Skill]
    C -->|否| E{需要工具权限控制？}
    C -->|是| D
    E -->|否| F[使用 自定义命令]
    E -->|是| D

    style F fill:#4CAF50,color:#fff
    style D fill:#2196F3,color:#fff
```

**核心区别速查表**：

| 维度 | 自定义命令 | Skill |
|------|-----------|-------|
| 触发方式 | 手动输入 `/project:xxx` | 根据上下文自动激活 |
| 文件结构 | 单个 `.md` 文件 | 目录 + `SKILL.md` + 可选hooks |
| 适用场景 | 确定性工作流、团队标准操作 | 需要动态判断、工具集成的场景 |
| 学习成本 | 5分钟上手 | 需要30分钟理解完整机制 |
| 存放位置 | `.claude/commands/` | `.claude/skills/` |
| 共享方式 | Git提交 | Git提交或npm包 |

**选择原则**：能用命令解决的，不升级为Skill。命令是最小可行扩展，Skill是命令的重量级升级版。

### 命令的文件系统层级

```mermaid
graph TD
    A["~/.claude/"] --> B["commands/"]
    A --> C["settings.json"]

    D["项目根目录/.claude/"] --> E["commands/"]
    D --> F["CLAUDE.md"]

    B --> B1["review.md → /user:review"]
    B --> B2["deploy.md → /user:deploy"]

    E --> E1["review.md → /project:review"]
    E --> E2["migrate.md → /project:migrate"]
    E --> E3["test-gen.md → /project:test-gen"]

    style B fill:#FF9800,color:#fff
    style E fill:#4CAF50,color:#fff
```

两个存放位置决定命令的作用域：

- **用户级**：`~/.claude/commands/review.md` → 所有项目中通过 `/user:review` 调用
- **项目级**：`.claude/commands/review.md` → 仅当前项目通过 `/project:review` 调用

项目级命令提交到Git后，整个团队共享同一套命令库。

## 第二步：创建第一个自定义命令

### Hello World命令

在项目根目录创建命令文件：

```bash
mkdir -p .claude/commands
```

创建 `.claude/commands/hello.md`：

```markdown
请向用户问候，并简要说明当前项目的技术栈。

执行以下步骤：
1. 读取项目根目录的 package.json（或 pyproject.toml、go.mod 等）
2. 识别主要依赖和框架
3. 以友好、简洁的方式介绍项目概况
```

在Claude Code中调用：

```
/project:hello
```

**预期输出**：

```
你好！我分析了你的项目，这是一个基于 Next.js 14 + TypeScript 的全栈应用，
使用 Prisma 作为 ORM，PostgreSQL 作为数据库，部署在 Vercel 上。
主要依赖包括：React 19、TailwindCSS 4、Zustand。
```

### 命令文件的三要素

每个命令Markdown文件由三部分组成：

```markdown
---
描述区域（可选）：YAML front matter，用于命令元数据
---

## 上下文说明（推荐）
告诉Claude执行命令前需要了解的背景

## 执行步骤（必需）
1. 具体操作步骤
2. 每步的预期结果
3. 错误处理指引
```

## 第三步：掌握参数系统

### $ARGUMENTS 变量

命令支持通过 `$ARGUMENTS` 接收用户输入的动态参数。这是将静态命令转化为动态模板的关键。

创建 `.claude/commands/explain.md`：

```markdown
请详细解释以下代码或概念：$ARGUMENTS

要求：
1. 先给出一句话总结
2. 然后逐步展开细节
3. 提供一个实际使用示例
4. 标注常见的坑或注意事项
```

调用方式：

```
/project:explain React useEffect的清理函数
```

Claude会将"React useEffect的清理函数"替换到 `$ARGUMENTS` 的位置。

### 高级参数模板

创建 `.claude/commands/fix.md`：

```markdown
修复以下Bug：$ARGUMENTS

请按以下流程操作：

1. **定位问题**：根据描述搜索相关代码文件
2. **分析根因**：解释为什么会出现这个Bug
3. **提供修复**：直接修改代码，给出最小改动方案
4. **验证修复**：运行相关测试确认修复有效
5. **防止复发**：如果有必要，添加回归测试

注意事项：
- 优先使用最小改动原则，不要重构周边代码
- 如果修复涉及多个文件，逐一说明每个文件的改动原因
- 修改完成后运行 `git diff` 展示所有变更
```

## 第四步：八种实战命令模式

### 模式一：代码审查命令

创建 `.claude/commands/review.md`：

```markdown
对当前Git变更进行代码审查。

执行步骤：
1. 运行 `git diff --staged` 获取暂存区变更
2. 如果暂存区为空，运行 `git diff` 获取工作区变更
3. 逐文件分析变更内容，从以下维度审查：
   - **正确性**：逻辑是否正确，边界条件是否处理
   - **安全性**：是否存在注入、XSS等安全风险
   - **性能**：是否有明显的性能问题
   - **可读性**：命名是否清晰，结构是否合理
   - **一致性**：是否与项目既有代码风格一致
4. 对每个问题标注严重程度：🔴 必须修复 🟡 建议改进 🟢 可选优化
5. 给出总体评价和改进建议

输出格式：
## 审查摘要
- 审查文件数：X
- 发现问题数：X

## 问题详情
### 文件：path/to/file.ts
- [🔴] 第X行：问题描述 → 修复建议

## 改进建议
1. ...
```

调用方式：暂存文件后执行 `/project:review`

### 模式二：智能部署命令

创建 `.claude/commands/deploy.md`：

```markdown
执行部署流程到 $ARGUMENTS 环境。

部署前检查清单：
1. 确认当前Git分支和状态（`git status`）
2. 确认所有变更已提交
3. 运行测试套件确认通过
4. 检查环境变量是否配置完整

部署步骤：
1. 根据目标环境选择部署方式：
   - staging：推送到 staging 分支触发CI
   - production：创建版本标签并推送
2. 等待部署结果反馈
3. 执行冒烟测试验证部署成功

回滚方案：
如果部署失败，说明如何回滚到上一版本。

注意事项：
- production 部署前必须确认所有测试通过
- 部署后验证健康检查端点
```

### 模式三：数据库迁移命令

创建 `.claude/commands/migrate.md`：

```markdown
创建数据库迁移：$ARGUMENTS

操作流程：
1. 读取项目的ORM配置（Prisma/TypeORM/Django/Goose等）
2. 分析现有数据模型结构
3. 生成迁移文件，包含：
   - UP 迁移：应用变更
   - DOWN 迁移：回滚变更
4. 检查迁移是否会导致数据丢失
5. 如果有数据丢失风险，生成数据保护SQL

安全检查：
- 确认迁移不会锁表超过5秒（大表场景）
- 确认外键约束正确
- 确认索引创建不会阻塞写入

生成文件后运行 `git diff` 展示变更。
```

### 模式四：测试生成命令

创建 `.claude/commands/test-gen.md`：

```markdown
为以下代码生成测试：$ARGUMENTS

测试生成策略：
1. 读取目标文件，分析所有导出函数/方法
2. 为每个函数生成测试用例，覆盖：
   - 正常输入的Happy Path
   - 边界条件（空值、极大值、极小值）
   - 异常输入（错误类型、null、undefined）
   - 并发场景（如果适用）
3. 使用项目已有的测试框架和工具：
   - 检查 package.json 确认测试框架（Jest/Vitest/pytest/JUnit等）
   - 遵循项目现有的测试文件命名规范
   - 使用项目已有的测试工具函数（fixtures、mocks等）
4. 测试文件放在与项目惯例一致的位置

质量标准：
- 每个函数至少3个测试用例
- 测试描述使用清晰的中英文混合格式
- 包含必要的 setup 和 teardown
```

### 模式五：API文档生成命令

创建 `.claude/commands/api-doc.md`：

```markdown
为项目API生成文档。

分析步骤：
1. 识别项目API框架（Express/FastAPI/Gin/Spring等）
2. 扫描所有路由/端点定义
3. 对每个端点提取：
   - HTTP方法和路径
   - 请求参数（Query/Path/Body）
   - 响应格式和状态码
   - 认证要求
   - 使用示例（curl命令）

输出格式：
按照OpenAPI 3.0规范生成文档，包含：
- API概述和认证说明
- 按资源分组的端点列表
- 请求/响应示例
- 错误码说明

将文档输出到 `docs/api-reference.md`。
```

### 模式六：安全审计命令

创建 `.claude/commands/security.md`：

```markdown
对项目进行安全审计，重点关注：$ARGUMENTS

审计范围（如果未指定参数，则执行全面审计）：

1. **依赖安全**
   - 运行 `npm audit` / `pip audit` / `go vuln check`
   - 分析已知漏洞的严重程度
   - 提供升级建议

2. **代码安全**
   - 搜索硬编码密钥和凭证
   - 检查SQL注入风险
   - 检查XSS风险
   - 检查不安全的反序列化
   - 检查路径遍历风险

3. **配置安全**
   - 检查CORS配置
   - 检查HTTP安全头
   - 检查认证/授权实现

4. **输出报告**
   - 🔴 高危：立即修复
   - 🟡 中危：计划修复
   - 🟢 低危：建议改进
```

### 模式七：性能分析命令

创建 `.claude/commands/perf.md`：

```markdown
分析以下模块的性能问题：$ARGUMENTS

分析维度：
1. **算法复杂度**
   - 识别O(n²)及以上复杂度的循环
   - 检查不必要的嵌套迭代
   - 分析递归深度

2. **内存使用**
   - 检查大对象创建和持有
   - 识别内存泄漏风险（未清理的引用、事件监听器）
   - 分析缓存策略

3. **I/O效率**
   - 检查同步I/O操作
   - 分析N+1查询问题
   - 检查不必要的网络请求

4. **前端特有**（如适用）
   - 组件重渲染分析
   - Bundle大小分析
   - 懒加载检查

输出格式：
## 性能报告
### 问题列表
| 严重度 | 文件 | 行号 | 问题描述 | 预期提升 |
|--------|------|------|----------|----------|

### 优化建议
按优先级排列具体的代码修改建议。
```

### 模式八：重构命令

创建 `.claude/commands/refactor.md`：

```markdown
重构目标：$ARGUMENTS

重构原则：
1. **小步前进**：每次只做一种重构，保持可编译/可运行
2. **测试保护**：重构前确认测试覆盖，重构后运行测试
3. **行为保持**：不改变外部可观察行为

重构流程：
1. 分析目标代码，识别"坏味道"：
   - 过长函数（>50行）
   - 过深嵌套（>3层）
   - 重复代码
   - 魔法数字/字符串
   - 过多参数（>4个）
   - 上帝类/模块
2. 制定重构计划，列出步骤
3. 逐步执行每个重构步骤
4. 每步完成后运行测试确认

输出要求：
- 每步重构前展示 `git diff`
- 说明重构动机和预期效果
- 最终给出重构前后的对比摘要
```

## 第五步：命令与Hooks联动

自定义命令的威力在与Hooks配合时倍增。Hooks可以在命令执行前后注入自动化逻辑。

### 在settings.json中配置Hooks

编辑 `.claude/settings.json`：

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo '命令执行完成：$(date)' >> .claude/command-log.txt"
          }
        ]
      }
    ]
  }
}
```

这个配置实现了：
- 每次Claude写入/编辑文件后自动格式化
- 每次命令执行完成后记录日志

### 命令执行防护

通过PreToolUse Hook防止命令在生产环境执行危险操作：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'DROP|DELETE|truncate|rm -rf'; then echo 'BLOCK: 危险操作已被拦截' >&2; exit 1; fi"
          }
        ]
      }
    ]
  }
}
```

## 第六步：构建团队命令标准库

### 项目命令库的目录结构

一个成熟的团队项目命令库应当包含：

```
.claude/
├── commands/
│   ├── review.md          # 代码审查
│   ├── deploy.md          # 部署流程
│   ├── migrate.md         # 数据库迁移
│   ├── test-gen.md        # 测试生成
│   ├── api-doc.md         # API文档
│   ├── security.md        # 安全审计
│   ├── perf.md            # 性能分析
│   ├── refactor.md        # 重构
│   ├── sprint/
│   │   ├── start.md       # Sprint开始
│   │   ├── end.md         # Sprint结束
│   │   └── retro.md       # 回顾
│   └── infra/
│       ├── docker.md      # Docker操作
│       └── k8s.md         # Kubernetes操作
├── settings.json          # Hooks配置
└── CLAUDE.md              # 项目级指令
```

子目录中的命令访问路径为：`.claude/commands/sprint/start.md` → `/project:sprint-start`（用连字符代替斜杠）。

### 命令模板的版本管理

将命令文件纳入Git管理，确保团队一致性：

```bash
# 首次设置
git add .claude/commands/
git add .claude/settings.json
git commit -m "feat: 添加团队命令标准库"

# 团队成员获取
git pull  # 自动获取最新命令
```

在 `CLAUDE.md` 中添加命令索引：

```markdown
# 项目命令索引

| 命令 | 用途 | 参数 |
|------|------|------|
| /project:review | 代码审查 | 无 |
| /project:deploy | 部署 | 目标环境 |
| /project:migrate | 数据库迁移 | 迁移描述 |
| /project:test-gen | 测试生成 | 目标文件/函数 |
| /project:security | 安全审计 | 审计范围 |
```

## 实战案例：全栈项目命令库搭建

以下是一个完整的Next.js全栈项目命令库搭建流程。

### 步骤一：初始化命令目录

```bash
mkdir -p .claude/commands
mkdir -p .claude/commands/sprint
```

### 步骤二：创建核心命令

创建 `.claude/commands/feature.md`——功能开发全流程命令：

```markdown
开发新功能：$ARGUMENTS

请按以下流程执行完整的功能开发：

## 1. 分析阶段
- 读取 CLAUDE.md 了解项目架构
- 确认功能涉及哪些模块
- 列出需要创建/修改的文件清单

## 2. 实现阶段
- 按照项目既有代码风格编写代码
- 遵循项目路由、组件、API的组织规范
- 如果涉及数据库变更，同步生成迁移文件

## 3. 测试阶段
- 为新代码生成单元测试
- 运行全量测试确认无回归
- 检查TypeScript类型是否正确

## 4. 文档阶段
- 更新相关API文档
- 如有用户可见变更，更新CHANGELOG

## 5. 提交阶段
- 使用 Conventional Commits 格式
- 运行 `git diff --stat` 展示变更概览
- 等待确认后提交
```

### 步骤三：创建Sprint管理命令

创建 `.claude/commands/sprint/start.md`：

```markdown
初始化新Sprint：$ARGUMENTS

执行步骤：
1. 从项目的Issue列表或任务板获取待办事项
2. 按优先级排列本Sprint计划完成的任务
3. 为每个任务创建对应的Git分支命名规范：
   - feature/xxx - 新功能
   - fix/xxx - Bug修复
   - refactor/xxx - 重构
4. 输出Sprint计划表

输出格式：
## Sprint 计划
- Sprint名称：XXX
- 开始日期：YYYY-MM-DD
- 计划周期：X周

### 任务列表
| # | 任务 | 类型 | 优先级 | 分支 |
|---|------|------|--------|------|
```

### 步骤四：配置Hooks

创建 `.claude/settings.json`：

```json
{
  "permissions": {
    "allow": [
      "Bash(git status*)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(npm run lint*)",
      "Bash(npm run test*)",
      "Bash(npx prettier*)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}
```

### 步骤五：验证命令库

在Claude Code中逐个测试：

```
> /project:feature 用户注册邮箱验证
> /project:review
> /project:deploy staging
> /project:test-gen src/lib/auth.ts
> /project:security 依赖检查
```

### 完整工作流

```text
flowchart TB
    Start[开发者启动Claude Code] --> Cmd[/project:feature 需求描述]
    Cmd --> Analyze[分析需求+读取CLAUDE.md]
    Analyze --> Code[编写代码]
    Code --> Hook1[Hook: 自动格式化]
    Hook1 --> Test[运行测试]
    Test --> Review[/project:review]
    Review --> Fix{有问题？}
    Fix -->|是| Code
    Fix -->|否| Deploy[/project:deploy staging]
    Deploy --> Verify[验证部署]
    Verify --> Done[完成]

    style Cmd fill:#4CAF50,color:#fff
    style Review fill:#FF9800,color:#fff
    style Deploy fill:#2196F3,color:#fff
```

## 常见问题与解决方案

### 问题1：命令不显示在补全列表

**原因**：文件路径或命名不符合规范。

**解决**：

```bash
# 检查文件是否存在
ls -la .claude/commands/

# 确认文件名不含空格和特殊字符
# 正确：review.md, test-gen.md, deploy.md
# 错误：code review.md, test gen.md
```

### 问题2：$ARGUMENTS为空

**原因**：调用时未提供参数。

**解决**：命令名和参数之间用空格分隔：

```
# 正确
/project:fix 登录页面白屏问题

# 错误（无参数）
/project:fix
```

如果命令设计为可选参数，在Markdown中使用条件逻辑：

```markdown
对以下内容进行审查：$ARGUMENTS

（如果未指定参数，则审查当前所有未提交的变更）
```

### 问题3：项目命令与用户命令冲突

**现象**：`/project:review` 和 `/user:review` 同时存在。

**解决**：Claude Code通过前缀区分二者，不存在真正的冲突。但建议团队统一使用项目级命令，避免个人命令与团队标准不一致。

### 问题4：命令执行时间过长

**原因**：命令中包含过多步骤或要求Claude执行大量文件搜索。

**解决**：拆分为多个原子命令。例如将"代码审查+测试+部署"拆分为三个独立命令，由开发者按需组合调用。

### 问题5：Hooks不生效

**检查清单**：

```bash
# 1. 确认配置文件位置
cat .claude/settings.json | head -20

# 2. 确认JSON格式正确
python3 -c "import json; json.load(open('.claude/settings.json'))"

# 3. 确认Hook命令可手动执行
npx prettier --write test.ts
```

## 命令设计原则

### 一致性原则

团队所有命令遵循统一的输出格式：

```markdown
## 命令名称
### 摘要
一句话说明执行结果

### 详情
具体内容...

### 下一步
建议的后续操作
```

### 原子性原则

每个命令只做一件事。避免创建"瑞士军刀"式命令。

```mermaid
graph LR
    A[不好的设计] --> B["/project:everything"]

    C[好的设计] --> D["/project:review"]
    C --> E["/project:test"]
    C --> F["/project:deploy"]

    style A fill:#f44336,color:#fff
    style C fill:#4CAF50,color:#fff
```

### 渐进增强原则

命令从简单开始，根据使用频率逐步增强：

1. **v1**：纯文本提示，无参数
2. **v2**：添加 `$ARGUMENTS` 支持
3. **v3**：添加条件逻辑和错误处理
4. **v4**：添加Hooks联动
5. **v5**：升级为完整Skill（如果需要自动触发）

```mermaid
flowchart LR
    V1[v1: 静态提示] --> V2[v2: 参数化]
    V2 --> V3[v3: 条件逻辑]
    V3 --> V4[v4: Hooks联动]
    V4 --> V5[v5: 升级为Skill]

    style V1 fill:#E8F5E9
    style V2 fill:#C8E6C9
    style V3 fill:#A5D6A7
    style V4 fill:#81C784,color:#fff
    style V5 fill:#4CAF50,color:#fff
```

## 参考来源

1. [Commands - Claude Code Docs](https://code.claude.com/docs/en/commands) — 官方命令完整参考文档
2. [Hooks reference - Claude Code Docs](https://code.claude.com/docs/en/hooks) — 官方Hooks生命周期事件参考
3. [Extend Claude with skills - Claude Code Docs](https://code.claude.com/docs/en/skills) — 官方Skills与命令对比指南
4. [Command Templates - DeepWiki](https://deepwiki.com/FlorianBruniaux/claude-code-ultimate-guide/14.3-command-templates) — 社区维护的命令模板集合
5. [Best practices - Claude Code Docs](https://code.claude.com/docs/en/best-practices) — 官方最佳实践指南

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| 适合训练营类型 | 企业内训、开发者工效提升营、团队标准化工作坊 |
| 预计教学时长 | 2-3小时（含实操练习） |
| 学员前置要求 | 有Claude Code基础使用经验 |
| 实操占比 | 70%实操 + 30%讲解 |
| 产出物 | 每个学员带走一套适合自己项目的命令库 |

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)