Claude Code自定义命令：打造你的专属提示词库 🎯

📅 更新于：2026年5月 | ✍️ 原创文章，转载请注明出处

---

📌 目录

1. 什么是自定义命令
2. 为什么需要自定义命令
3. 自定义命令的工作原理
4. 创建你的第一个命令
5. 命令语法详解
6. 10个实用命令模板
7. 团队共享命令
8. 高级用法与技巧
9. 常见问题与避坑
10. 总结

---

1. 什么是自定义命令

1.1 基本概念

自定义命令是 Claude Code 的一项强大功能，允许你：

📁 .claude/commands/
├── review.md          → /review
├── test.md            → /test
├── refactor.md        → /refactor
├── docs.md            → /docs
└── commit.md          → /commit

简单来说：把常用的提示词保存成模板，用 /命令名 一键调用。

1.2 与CLAUDE.md的区别

特性	CLAUDE.md	自定义命令
触发方式	自动加载	手动调用 /command
用途	项目上下文	可复用的任务模板
数量	通常1个	可以多个
内容	静态配置	动态任务指令

1.3 核心价值

🎯 价值1：一致性 —— 团队使用相同的提示词模板
🎯 价值2：效率 —— 一键调用，不用重复输入
🎯 价值3：标准化 —— 统一代码审查、测试、提交的流程
🎯 价值4：可维护 —— 修改模板，全局生效

---

2. 为什么需要自定义命令

2.1 没有自定义命令的痛点

# ❌ 痛点1：重复输入
"帮我做代码审查，检查类型安全、错误处理、性能问题、代码风格..."
# 每次都要输入一大段

# ❌ 痛点2：不一致
"帮我写测试" → 有人用Jest，有人用Vitest
"帮我写文档" → 有人用JSDoc，有人用Markdown
# 团队标准不统一

# ❌ 痛点3：容易遗漏
"帮我重构代码"
# 忘记说"保持测试通过"，结果重构后测试挂了

2.2 有自定义命令的好处

# ✅ 好处1：一键调用
/review
# 自动执行完整的代码审查流程

# ✅ 好处2：团队统一
/test
# 所有人用同样的测试生成模板

# ✅ 好处3：不会遗漏
/refactor
# 自动包含"保持测试通过"的约束

2.3 适用场景

场景	命令示例	说明
代码审查	/review	统一审查标准
测试生成	/test	统一测试框架和风格
代码重构	/refactor	包含约束条件
文档生成	/docs	统一文档格式
Git提交	/commit	统一提交信息格式
Bug修复	/fix	标准化修复流程
性能优化	/perf	包含性能测试步骤

---

3. 自定义命令的工作原理

3.1 文件结构

📁 项目根目录/
├── .claude/
│   └── commands/
│       ├── review.md        # 项目级命令
│       ├── test.md
│       └── refactor.md
├── src/
├── package.json
└── CLAUDE.md

3.2 命名规则

规则	示例	说明
文件名	review.md	命令名就是文件名
调用方式	/review	斜杠 + 文件名（不含.md）
大小写	Code-Review.md → /Code-Review	保持大小写
连字符	code-review.md → /code-review	支持连字符

3.3 加载时机

1. 你输入 /review
2. Claude Code 读取 .claude/commands/review.md
3. 将文件内容作为提示词执行
4. 支持变量替换（如 $ARGUMENTS）

3.4 作用域

位置	作用域	说明
.claude/commands/	项目级	只在当前项目生效
~/.claude/commands/	全局级	所有项目都可用

---

4. 创建你的第一个命令

4.1 步骤1：创建目录

# 在项目根目录创建
mkdir -p .claude/commands

4.2 步骤2：创建命令文件

# 创建一个代码审查命令
touch .claude/commands/review.md

4.3 步骤3：编写命令内容

# .claude/commands/review.md

请对当前文件或指定文件进行代码审查。

## 审查维度

1. **类型安全**
   - 是否有 `any` 类型
   - 类型定义是否完整
   - 是否有类型断言滥用

2. **错误处理**
   - 异步操作是否有 try-catch
   - 边界条件是否处理
   - 错误信息是否有意义

3. **性能**
   - 是否有不必要的重渲染
   - 是否有内存泄漏风险
   - 是否有可优化的循环

4. **代码风格**
   - 命名是否符合规范
   - 是否有重复代码
   - 注释是否充分

## 输出格式

请以表格形式输出：

| 问题类型 | 位置 | 问题描述 | 建议修改 |
|---------|------|----------|----------|
| 类型安全 | 第15行 | 使用了any类型 | 改为具体类型 |

## 使用方式

- 默认审查当前文件
- 可以指定文件：/review src/utils/format.ts

4.4 步骤4：使用命令

# 在Claude Code中输入
/review

# 或者指定文件
/review src/utils/format.ts

4.5 完整示例

# 1. 进入项目目录
cd my-project

# 2. 创建命令目录
mkdir -p .claude/commands

# 3. 创建命令文件
cat > .claude/commands/review.md << 'EOF'
请对当前文件或指定文件进行代码审查。

## 审查维度
1. 类型安全
2. 错误处理
3. 性能
4. 代码风格

## 输出格式
以表格形式输出问题和建议。
EOF

# 4. 提交到Git
git add .claude/commands/
git commit -m "feat: 添加代码审查命令"

# 5. 使用
# 在Claude Code中输入 /review

---

5. 命令语法详解

5.1 基本语法

# 命令标题

命令的描述和说明。

## 具体指令

详细的任务步骤。

5.2 变量替换

Claude Code 支持在命令中使用变量：

变量	说明	示例
$ARGUMENTS	用户传入的参数	/review src/utils.ts → $ARGUMENTS = src/utils.ts

使用示例

# .claude/commands/fix.md

修复以下文件中的bug：$ARGUMENTS

## 步骤
1. 读取文件 $ARGUMENTS
2. 分析错误原因
3. 提供修复方案
4. 执行修复
5. 运行测试验证

# 使用时
/fix src/api/auth.ts
# $ARGUMENTS 会被替换为 "src/api/auth.ts"

5.3 条件逻辑

虽然命令文件不支持真正的条件语句，但你可以通过描述来实现：

# .claude/commands/test.md

为指定的文件或当前修改的代码生成测试。

## 判断逻辑

如果指定了文件（$ARGUMENTS不为空）：
- 为指定文件生成测试

如果没有指定文件：
- 查看git diff，为修改的代码生成测试

## 测试要求
- 使用项目配置的测试框架
- 包含正常case和异常case
- 测试覆盖率 > 80%

5.4 多行指令

# .claude/commands/docs.md

请为以下内容生成文档：

## 文档类型
- 如果是组件：生成Props文档和使用示例
- 如果是函数：生成JSDoc文档
- 如果是API：生成API文档

## 格式要求
```typescript
/**
 * 函数描述
 * @param paramName - 参数说明
 * @returns 返回值说明
 * @example
 * // 示例代码
 */

输出位置

• 组件文档：放在组件同目录下的README.md
• 函数文档：直接写在代码注释中

### 5.5 引用其他文件

```markdown
# .claude/commands/refactor.md

重构指定的代码，参考项目的编码规范。

## 参考文件
- 编码规范：.claude/conventions.md
- 组件示例：src/components/UserCard.tsx

## 重构要求
1. 阅读.claude/conventions.md了解编码规范
2. 参考src/components/UserCard.tsx的写法
3. 重构$ARGUMENTS指定的文件
4. 保持测试通过

---

6. 10个实用命令模板

6.1 代码审查命令

# .claude/commands/review.md

对代码进行全面审查。

## 审查清单

### 必查项
- [ ] 类型安全：是否有any、类型断言
- [ ] 错误处理：try-catch、边界条件
- [ ] 性能：重渲染、内存泄漏、循环优化
- [ ] 安全：XSS、SQL注入、敏感信息

### 代码风格
- [ ] 命名规范
- [ ] 代码重复
- [ ] 注释完整
- [ ] 测试覆盖

## 输出格式

### 问题汇总
| 严重程度 | 类型 | 位置 | 问题 | 建议 |
|---------|------|------|------|------|
| 🔴 高 | 类型安全 | 15行 | any类型 | 改为具体类型 |
| 🟡 中 | 性能 | 23行 | 未使用useMemo | 添加memo |

### 优点
- 列出代码的亮点

### 改进建议
- 给出具体的优化方向

$ARGUMENTS

6.2 测试生成命令

# .claude/commands/test.md

为指定代码生成单元测试。

## 测试框架
- 前端：Jest + React Testing Library
- 后端：Jest + Supertest（Node）/ JUnit 5（Java）

## 测试要求

### 覆盖场景
1. 正常流程（happy path）
2. 边界条件
3. 异常情况
4. 并发场景（如适用）

### 测试结构
```javascript
describe('功能模块', () => {
  beforeEach(() => {
    // 初始化
  });

  afterEach(() => {
    // 清理
  });

  it('应该处理正常输入', () => {
    // 测试正常流程
  });

  it('应该处理边界条件', () => {
    // 测试边界
  });

  it('应该抛出错误', () => {
    // 测试异常
  });
});

输出位置

• 与源文件同目录，命名为 xxx.test.ts

$ARGUMENTS

### 6.3 重构命令

```markdown
# .claude/commands/refactor.md

重构指定的代码。

## 重构约束
1. **必须保持测试通过** —— 重构后运行所有测试
2. **不改变外部行为** —— 功能完全一致
3. **小步重构** —— 每次只做一个改动

## 重构方向
- 提取重复代码
- 简化复杂逻辑
- 改善命名
- 优化性能

## 步骤
1. 运行现有测试，确认通过
2. 分析代码，找出重构点
3. 执行重构
4. 再次运行测试，确认通过
5. 总结改动

## 输出格式
### 重构前
```typescript
// 原始代码

重构后

// 重构后的代码

改动说明

• 改动1：xxx
• 改动2：xxx

测试结果

• 通过：xx个
• 失败：xx个

$ARGUMENTS

### 6.4 文档生成命令

```markdown
# .claude/commands/docs.md

生成代码文档。

## 文档类型判断

### 如果是组件
生成：
1. Props接口文档
2. 使用示例
3. 注意事项

### 如果是函数
生成JSDoc文档：
```typescript
/**
 * 函数描述
 * 
 * @param paramName - 参数说明
 * @returns 返回值说明
 * @throws 错误说明
 * 
 * @example
 * const result = myFunction('input');
 */

如果是API接口

生成API文档：

• 请求方式
• URL路径
• 请求参数
• 响应格式
• 错误码

文档风格

• 使用中文
• 包含代码示例
• 简洁明了

$ARGUMENTS

### 6.5 Git提交命令

```markdown
# .claude/commands/commit.md

生成规范的Git提交信息。

## 步骤
1. 查看当前修改：`git diff`
2. 查看暂存区：`git diff --cached`
3. 分析改动类型
4. 生成提交信息
5. 执行提交

## 提交信息格式

():

Type类型

• ✨ feat: 新功能
• 🐛 fix: 修复bug
• 📝 docs: 文档
• 💄 style: 格式
• ♻️ refactor: 重构
• ✅ test: 测试
• 🔧 chore: 构建/工具

示例

✨ feat(auth): 添加微信登录支持

- 集成微信OAuth2.0
- 添加微信用户信息解析
- 更新登录页面UI

Closes #123

注意

• 使用中文描述
• 包含改动的具体内容
• 关联Issue（如有）

### 6.6 Bug修复命令

```markdown
# .claude/commands/fix.md

修复Bug的标准流程。

## 步骤

### 1. 理解问题
- 阅读错误信息
- 复现问题
- 确定影响范围

### 2. 分析原因
- 查看相关代码
- 定位问题根源
- 确定修复方案

### 3. 执行修复
- 编写修复代码
- 添加防护措施（避免再次发生）

### 4. 验证修复
- 运行测试
- 手动验证
- 检查边界情况

### 5. 总结
- 问题原因
- 修复方案
- 预防措施

## 输出格式
### 问题描述
[描述问题]

### 根本原因
[分析原因]

### 修复方案
```typescript
// 修复后的代码

测试结果

• 单元测试：✅ 通过
• 集成测试：✅ 通过

预防措施

• 如何避免类似问题

$ARGUMENTS

### 6.7 性能优化命令

```markdown
# .claude/commands/perf.md

性能分析与优化。

## 分析维度

### 前端性能
- 组件重渲染
- Bundle大小
- 首屏加载时间
- 内存泄漏

### 后端性能
- 数据库查询
- API响应时间
- 缓存命中率
- 并发处理

## 步骤
1. 识别性能瓶颈
2. 测量当前性能
3. 实施优化
4. 验证优化效果

## 常见优化手段

### 前端
- React.memo
- useMemo / useCallback
- 虚拟滚动
- 代码分割
- 图片懒加载

### 后端
- 数据库索引
- 查询优化
- 缓存策略
- 异步处理

## 输出格式
### 性能瓶颈
[描述发现的问题]

### 优化方案
[具体优化措施]

### 优化前后对比
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| 加载时间 | 3s | 1s | 66% |

$ARGUMENTS

6.8 API接口生成命令

# .claude/commands/api.md

生成RESTful API接口代码。

## 技术栈
- 框架：Express / FastAPI / Spring Boot
- 数据库：MySQL / PostgreSQL
- ORM：Prisma / SQLAlchemy / MyBatis-Plus

## 生成内容
1. Controller/Router
2. Service层
3. Repository/DAO层
4. 数据模型
5. 请求/响应DTO
6. 单元测试

## 命名规范
- Controller: `xxxController.ts`
- Service: `xxxService.ts`
- Repository: `xxxRepository.ts`
- DTO: `xxxRequest.ts`, `xxxResponse.ts`

## 代码风格
- RESTful设计
- 统一错误处理
- 参数验证
- 日志记录

## 使用方式
/api 用户管理 CRUD
/api 订单查询接口
/api 文件上传接口

$ARGUMENTS

6.9 数据库迁移命令

# .claude/commands/migrate.md

生成数据库迁移脚本。

## 步骤
1. 分析模型变更
2. 生成迁移脚本
3. 检查数据兼容性
4. 提供回滚方案

## 迁移类型
- 创建表
- 添加字段
- 修改字段
- 删除字段
- 添加索引
- 数据迁移

## 输出格式
### 迁移脚本
```sql
-- Up
CREATE TABLE users (
  id INT PRIMARY KEY AUTO_INCREMENT,
  name VARCHAR(255) NOT NULL,
  email VARCHAR(255) UNIQUE,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Down
DROP TABLE users;

注意事项

• 是否有数据丢失风险
• 是否需要数据迁移
• 是否影响现有功能

$ARGUMENTS

### 6.10 技术方案命令

```markdown
# .claude/commands/design.md

生成技术方案文档。

## 文档结构

### 1. 需求背景
- 业务需求
- 技术需求
- 约束条件

### 2. 方案设计
- 整体架构
- 模块划分
- 接口设计
- 数据模型

### 3. 技术选型
- 框架选择
- 中间件选择
- 第三方服务

### 4. 实现计划
- 阶段划分
- 时间估算
- 风险点

### 5. 测试方案
- 单元测试
- 集成测试
- 性能测试

## 输出格式
使用Markdown格式，包含：
- 架构图（文字描述）
- 接口表格
- 数据模型ER图（文字描述）
- 代码示例

$ARGUMENTS

---

7. 团队共享命令

7.1 为什么团队共享很重要

🎯 统一标准 —— 代码审查、测试、提交都有标准
🎯 提高效率 —— 新人直接用现成命令
🎯 减少沟通 —— 不用反复解释"怎么做"

7.2 共享方式

方式1：提交到Git仓库（推荐）

# 1. 创建命令目录
mkdir -p .claude/commands

# 2. 添加命令文件
# ... 创建各个命令文件

# 3. 提交到Git
git add .claude/commands/
git commit -m "feat: 添加Claude Code自定义命令"

# 4. 团队成员拉取后即可使用
git pull

方式2：使用全局命令

# 在用户目录下创建
mkdir -p ~/.claude/commands

# 添加通用命令
# 这些命令在所有项目都可用

7.3 团队命令清单建议

命令	用途	优先级
/review	代码审查	⭐⭐⭐ 必须
/test	测试生成	⭐⭐⭐ 必须
/commit	Git提交	⭐⭐⭐ 必须
/refactor	代码重构	⭐⭐ 推荐
/docs	文档生成	⭐⭐ 推荐
/fix	Bug修复	⭐⭐ 推荐
/api	API生成	⭐ 可选

7.4 命令维护

# .claude/commands/README.md

# Claude Code 自定义命令

## 命令列表

| 命令 | 说明 | 维护者 |
|------|------|--------|
| /review | 代码审查 | @zhangsan |
| /test | 测试生成 | @lisi |
| /commit | Git提交 | @wangwu |

## 使用方法
1. 确保在项目根目录
2. 输入 `/命令名` 即可

## 添加新命令
1. 在 `.claude/commands/` 目录创建 `.md` 文件
2. 按照现有命令的格式编写
3. 提交到Git

## 注意事项
- 命令文件必须是 `.md` 格式
- 命令名即文件名（不含.md）
- 支持中文内容

---

8. 高级用法与技巧

8.1 组合命令

创建一个命令调用其他命令：

# .claude/commands/full-workflow.md

完整的开发工作流。

## 步骤

### 1. 代码审查
先执行 /review，确保代码质量

### 2. 生成测试
执行 /test，补充测试用例

### 3. 性能检查
执行 /perf，检查性能问题

### 4. 生成文档
执行 /docs，更新文档

### 5. 提交代码
执行 /commit，规范提交

## 注意
- 每个步骤完成后确认再进行下一步
- 如果某个步骤失败，停下来修复后再继续

8.2 条件执行

# .claude/commands/smart-test.md

智能测试生成。

## 判断逻辑

### 情况1：指定了文件
如果 $ARGUMENTS 不为空：
- 为指定文件生成测试

### 情况2：未指定文件
如果 $ARGUMENTS 为空：
- 查看 `git diff --name-only` 获取修改的文件
- 为这些文件生成测试

### 情况3：有未提交的修改
如果有未提交的修改：
- 只测试修改的部分

### 情况4：没有修改
如果没有修改：
- 运行所有测试，检查覆盖率

8.3 环境感知

# .claude/commands/dev.md

根据环境执行不同操作。

## 环境判断

### 开发环境
如果当前是开发环境（NODE_ENV=development）：
- 启动开发服务器
- 开启热更新
- 显示详细日志

### 测试环境
如果当前是测试环境（NODE_ENV=test）：
- 运行测试
- 生成覆盖率报告

### 生产环境
如果当前是生产环境（NODE_ENV=production）：
- 构建生产版本
- 优化资源
- 压缩代码

8.4 模板继承

# .claude/commands/base-review.md

代码审查基础模板。

## 基础检查项
- 类型安全
- 错误处理
- 代码风格

---

# .claude/commands/frontend-review.md

前端代码审查（继承base-review）。

## 基础检查项
参考 /base-review 的检查项

## 额外检查项
- 组件设计
- 状态管理
- 样式方案
- 性能优化

8.5 动态参数

# .claude/commands/generate.md

代码生成器。

## 使用方式
/generate component UserProfile
/generate api users
/generate model Order

## 参数解析

$ARGUMENTS 的第一个参数是类型：
- component: 生成组件
- api: 生成API接口
- model: 生成数据模型

$ARGUMENTS 的第二个参数是名称：
- 作为生成文件的名称

## 根据类型执行

### 如果类型是 component
生成 React 组件代码

### 如果类型是 api
生成 RESTful API 代码

### 如果类型是 model
生成数据模型代码

---

9. 常见问题与避坑

9.1 命令不生效

问题：输入 /review 没反应

排查步骤：

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

# 2. 检查文件名是否正确
# 必须是 .md 结尾

# 3. 检查是否在项目根目录
pwd

# 4. 检查Claude Code版本
# 确保是最新版本

9.2 变量不替换

问题：$ARGUMENTS 没有被替换

原因：可能是语法错误

解决：

# ❌ 错误
文件：$ARGUMENTS

# ✅ 正确
文件：$ARGUMENTS
# 确保 $ARGUMENTS 前后有空格

9.3 命令冲突

问题：项目命令和全局命令同名

解决：

优先级：项目命令 > 全局命令

如果项目有 .claude/commands/review.md
全局有 ~/.claude/commands/review.md
会使用项目级的命令

9.4 中文文件名问题

问题：中文文件名可能导致问题

建议：

# ❌ 不推荐
.claude/commands/代码审查.md

# ✅ 推荐
.claude/commands/review.md

9.5 命令太长

问题：命令文件内容太多，Claude可能忽略部分

建议：

- 控制在200行以内
- 分步骤说明
- 使用列表而不是长段落
- 重点内容加粗

---

10. 总结

10.1 核心要点

要点	说明
位置	.claude/commands/ 目录
格式	Markdown文件
调用	/命令名
变量	$ARGUMENTS 获取参数
共享	提交到Git仓库

10.2 快速开始清单

• 创建 .claude/commands/ 目录
• 添加 /review 命令
• 添加 /test 命令
• 添加 /commit 命令
• 提交到Git仓库
• 团队成员拉取使用

10.3 命令模板清单

命令	文件	用途
/review	review.md	代码审查
/test	test.md	测试生成
/refactor	refactor.md	代码重构
/docs	docs.md	文档生成
/commit	commit.md	Git提交
/fix	fix.md	Bug修复
/perf	perf.md	性能优化
/api	api.md	API生成
/migrate	migrate.md	数据库迁移
/design	design.md	技术方案

10.4 下篇预告

📌 下一篇：我们将提供一个完整的Claude Code提示词模板库——20个高频场景的即拿即用模板，涵盖日常开发的方方面面。

---

📚 参考资料

1. Anthropic官方文档 - Claude Code Custom Commands - 2026年5月
2. Claude Code最佳实践 - 官方指南

---

💬 你在团队中使用Claude Code自定义命令了吗？有什么好的实践？欢迎分享！

📌 如果这篇文章对你有帮助，别忘了点赞收藏，关注我获取更多Claude Code实战技巧！