Codecc.dev
返回博客列表
实战技巧

Claude Code 自定义命令完全指南：提升开发效率的利器

CodeCC Team
·
·
约 25 分钟阅读
#claude-code #自定义命令 #工作流自动化 #开发效率

Claude Code 的强大之处不仅在于其 AI 能力，更在于其高度可定制性。通过自定义命令，你可以将重复的开发任务转化为简单的斜杠命令，大幅提升开发效率。本文将手把手教你如何创建和使用 Claude Code 自定义命令。

什么是 Claude Code 命令？

Claude Code 命令本质上是存储在 Markdown 文件中的可复用提示词。你可以通过斜杠命令（如 /review 或 /test）在终端中快速调用它们，而无需每次都重新输入完整的指令。

命令类型

Claude Code 支持两种类型的命令：

1. 内置命令

  • /help - 查看帮助信息
  • /clear - 清空对话历史
  • /config - 配置设置
  • /context - 查看上下文使用
  • /catchup - 从 Git 加载变更
  • /init - 初始化项目配置

2. 自定义命令

  • 项目级命令：存储在 .claude/commands/，团队共享
  • 个人命令：存储在 ~/.claude/commands/，跨项目使用

必备基础：创建 CLAUDE.md

在创建自定义命令之前，强烈建议先创建 CLAUDE.md 文件。这个文件为 Claude 提供了理解项目所需的关键上下文。

CLAUDE.md 应包含的内容

# 项目名称

## 项目概述
简要描述项目目标和功能

## 技术栈
- 前端：React + TypeScript + Vite
- 后端：Node.js + Express
- 数据库：PostgreSQL
- 测试：Vitest + React Testing Library

## 开发命令
- `npm install` - 安装依赖
- `npm run dev` - 启动开发服务器 (http://localhost:3000)
- `npm run build` - 生产构建
- `npm run test` - 运行测试
- `npm run lint` - 代码检查

## 代码风格
- 使用 2 空格缩进
- 优先使用函数式组件和 Hooks
- 文件名使用 PascalCase (组件) 和 camelCase (工具函数)
- 所有导出的函数必须有 JSDoc 注释

## 关键文件位置
- 组件：`src/components/`
- API 路由：`src/api/`
- 工具函数：`src/utils/`
- 类型定义：`src/types/`

## 测试指南
- 所有组件必须有单元测试
- API 端点必须有集成测试
- 测试覆盖率 > 80%

## 已知问题
- 开发服务器热重载在 Windows 上偶尔失效
- API 限流：每分钟 100 次请求

快速生成 CLAUDE.md

使用内置命令生成模板：

/init

Claude 会根据项目类型生成一个初始的 CLAUDE.md 文件，你可以在此基础上进行完善。

重要提示：不要试图一开始就写出完美的 CLAUDE.md。将它视为活文档，在使用过程中逐步添加 Claude 重复询问的信息。

创建简单的项目命令

让我们从一个最简单的代码审查命令开始。

步骤 1：创建命令目录

在项目根目录创建 .claude/commands/ 文件夹：

mkdir -p .claude/commands

步骤 2：创建命令文件

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

审查提供的代码，重点关注：
1. 代码清晰度和可读性
2. 性能问题
3. 潜在的 Bug
4. 错误处理

不要提出纯粹的风格建议。

步骤 3：使用命令

在 Claude Code 会话中：

# 审查当前上下文中的代码
/review

# 审查特定文件
/review @src/components/Button.tsx

# 审查多个文件
/review @src/components/*.tsx

就是这么简单！ 文件名 review.md 自动成为命令名 /review。

创建个人跨项目命令

如果某个命令在多个项目中都很有用，可以创建个人命令。

创建个人命令目录

mkdir -p ~/.claude/commands

示例：通用测试命令

创建 ~/.claude/commands/test-all.md：

执行以下测试流程：

1. 运行所有单元测试
2. 运行集成测试（如果存在）
3. 生成测试覆盖率报告
4. 总结测试结果，包括：
   - 通过/失败的测试数量
   - 代码覆盖率百分比
   - 需要关注的失败测试

如果测试失败，提供修复建议。

这个命令现在可以在你的所有项目中使用！

高级功能：动态参数

通过参数让命令更加灵活。

使用 $ARGUMENTS

$ARGUMENTS 捕获命令后的所有内容。

示例：修复 GitHub Issue 命令

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

请分析并修复 GitHub Issue：$ARGUMENTS

按照以下步骤执行：

1. 使用 `gh issue view $ARGUMENTS` 获取 Issue 详情
2. 理解问题描述和复现步骤
3. 在代码库中搜索相关文件
4. 实现修复方案
5. 编写并运行测试验证修复
6. 创建 commit，commit message 引用 Issue 编号

完成后提供修复总结。

使用：

/fix-issue 123

Claude 会自动将 123 替换到 $ARGUMENTS 的位置。

使用位置参数 $1, $2, $3

对于需要多个参数的命令，使用位置参数更清晰。

示例：创建新组件命令

创建 .claude/commands/new-component.md：

创建一个新的 React 组件：

- 组件名：$1
- 组件类型：$2 (如果未提供，默认为 "functional")

步骤：
1. 在 `src/components/$1/` 创建目录
2. 创建 `index.tsx` 文件，包含组件实现
3. 创建 `$1.test.tsx` 测试文件
4. 创建 `$1.module.css` 样式文件（如果需要）
5. 在组件目录添加 `README.md` 说明组件用法

确保：
- 使用 TypeScript 类型注解
- 添加 PropTypes 或 TypeScript 接口
- 包含基本的单元测试
- 添加使用示例

使用：

/new-component Button
/new-component Modal functional

YAML Frontmatter 配置

通过 YAML frontmatter 为命令添加元数据和权限配置。

基础 Frontmatter

---
description: 创建带有上下文的 git commit
argument-hint: [提交信息]
---

创建一个 git commit，提交信息为：$ARGUMENTS
使用 !"git status" 的输出来指导 commit 内容。

Frontmatter 字段说明：

  • description - 命令描述，在 /help 中显示
  • argument-hint - 参数提示，帮助用户正确使用命令
  • allowed-tools - 预授权的工具和脚本（见下文）

预授权工具：allowed-tools

最强大的 frontmatter 功能是 allowed-tools，它允许命令自动执行特定的 bash 命令或脚本，无需每次都请求用户批准。

示例：Git 提交命令

创建 .claude/commands/commit.md：

---
description: 创建语义化的 git commit
allowed-tools:
  - Bash(git status:*)
  - Bash(git diff:*)
  - Bash(git add:*)
  - Bash(git commit:*)
  - Bash(git push:*)
---

执行 Git 提交流程：

1. 运行 `git status` 查看当前状态
2. 运行 `git diff --staged` 查看暂存的变更
3. 分析变更类型（feature/fix/refactor/docs 等）
4. 使用 `git add` 添加所有相关文件
5. 创建符合语义化规范的 commit message：
   - feat: 新功能
   - fix: 修复 Bug
   - refactor: 重构
   - docs: 文档更新
   - test: 测试相关
   - chore: 构建/工具变更
6. 使用 `git commit -m` 提交
7. 询问是否推送到远程（如果用户同意，执行 `git push`）

用户通过使用此命令明确授权执行这些 git 操作。

使用：

/commit

由于 allowed-tools 的配置，Claude 可以自动执行所有必要的 git 命令，无需每次都请求批准！

安全提示： 只对你信任的命令使用 allowed-tools，避免授权可能造成破坏的操作。

实战示例

下面是三个经过实战检验的命令模板，你可以直接使用或根据需求调整。

示例 1：智能 Git 自动化

.claude/commands/smart-commit.md：

---
description: 智能创建语义化 git commit 并推送
allowed-tools:
  - Bash(git diff:*)
  - Bash(git add:*)
  - Bash(git commit:*)
  - Bash(git push:*)
---

执行智能 Git 提交流程：

## 第一步：分析变更
运行 `git diff --staged` 获取已暂存的变更。
如果没有暂存的文件，运行 `git status` 查看未暂存的变更。

## 第二步：添加文件
使用 `git add` 添加所有修改和新增的文件。

## 第三步：生成 Commit Message
基于变更内容，生成简洁明了的单行 commit message，使用语义化规范：

- **feat**: 新功能
- **fix**: Bug 修复
- **refactor**: 代码重构（不改变功能）
- **perf**: 性能优化
- **docs**: 文档更新
- **style**: 代码格式调整（不影响逻辑）
- **test**: 测试相关
- **chore**: 构建工具或依赖更新

格式：`type(scope): description`

示例：
- `feat(auth): add Google OAuth login`
- `fix(api): handle null values in user endpoint`
- `refactor(utils): simplify date formatting logic`

## 第四步：创建 Commit
使用生成的 message 执行 commit。

## 第五步：推送到远程
将 commit 推送到 origin。

**重要**：用户通过调用此命令明确授权执行这些 git 操作。

示例 2：项目上下文初始化

.claude/commands/primer.md：

---
description: 系统性理解项目结构和当前任务
---

# 项目理解流程

当开始新会话时，按照以下系统化方法理解项目：

## 第一步：项目概览与结构

1. **阅读根目录的 README.md**
   - 了解项目目标和功能
   - 查看安装和运行说明

2. **获取完整文件清单**
   - 运行 `git ls-files` 获取所有跟踪的文件
   - 识别关键目录和文件组织方式

3. **查看项目结构**
   - 运行 `tree -L 3 -I 'node_modules|dist|build'`
   - 理解目录层级和组织逻辑

## 第二步：核心文档

1. **阅读 PLANNING.md**（如果存在）
   - 了解架构和设计决策
   - 理解技术选型原因

2. **阅读 TASK.md 或 TODO.md**（如果存在）
   - 查看当前工作状态
   - 了解优先级和待办事项

3. **阅读 CLAUDE.md**
   - 理解项目规范和约定
   - 熟悉开发命令和工作流

## 第三步：技术栈分析

1. **检查 package.json** (前端/Node.js 项目)
   - 主要依赖和框架
   - 可用的 npm scripts

2. **检查配置文件**
   - TypeScript: `tsconfig.json`
   - 构建工具: `vite.config.ts`, `webpack.config.js`
   - 测试: `vitest.config.ts`, `jest.config.js`
   - Linter: `.eslintrc`, `.prettierrc`

## 第四步：验证理解

在继续工作前，回答以下问题：

1. **项目目的**：这个项目的主要目标是什么？
2. **本地开发**：如何构建、测试和运行项目？
3. **架构组件**：主要的架构组件和模块有哪些？
4. **当前任务**：当前正在进行的工作和优先级是什么？
5. **技术栈**：使用了哪些主要技术和框架？

## 第五步：总结报告

提供一个简洁的项目总结，包括：
- 项目类型和用途
- 主要技术栈
- 目录结构概览
- 当前工作重点
- 需要注意的特殊配置或约定

如果有任何不清楚的地方，请提出具体问题。

示例 3：代码审查助手

.claude/commands/code-review.md：

---
description: 全面的代码审查，按优先级分类问题
---

# 代码审查助手

你是一位经验丰富的代码审查专家。你的主要职责包括：

## 第一步：代码库分析

1. **理解代码结构**
   - 阅读相关文件的代码
   - 理解代码的业务逻辑和数据流
   - 识别使用的设计模式

2. **查看 CLAUDE.md**
   - 了解项目的编码规范
   - 熟悉项目特定的约定

## 第二步：问题识别

按照以下类别识别问题：

### 1. 安全性 (Security)
- SQL 注入、XSS、CSRF 漏洞
- 敏感数据泄露
- 不安全的依赖
- 认证和授权问题

### 2. 性能 (Performance)
- 不必要的循环和计算
- 内存泄漏风险
- 数据库查询优化机会
- 缓存策略改进

### 3. 代码质量 (Code Quality)
- 代码重复（DRY 原则违反）
- 过于复杂的函数
- 命名不清晰
- 缺少错误处理
- 不一致的代码风格

### 4. 最佳实践 (Best Practices)
- 违反 SOLID 原则
- 缺少类型注解（TypeScript）
- 测试覆盖不足
- 文档缺失
- 不符合项目规范

## 第三步：优先级排序

为每个发现的问题分配优先级：

- **Critical (严重)**: 安全漏洞、数据损坏风险、生产环境崩溃
- **High (高)**: 重大性能问题、关键功能 Bug、数据一致性问题
- **Medium (中)**: 可读性问题、小的性能优化、测试缺失
- **Low (低)**: 代码风格、命名改进、非关键文档

## 第四步：更新任务文件

1. **阅读现有的 TASK.md** 文件
2. **追加新发现的问题** 作为可操作的任务
3. **不要重复** 已存在的任务
4. **按优先级排序** 新任务

格式示例：
```markdown
## 代码审查发现 - [日期]

### Critical
- [ ] [安全] 修复 user API 中的 SQL 注入漏洞 (src/api/users.ts:45)

### High
- [ ] [性能] 优化产品列表查询，添加索引 (src/db/queries.ts:78)
- [ ] [Bug] 修复购物车更新时的状态不一致 (src/components/Cart.tsx:120)

### Medium
- [ ] [测试] 为 PaymentService 添加单元测试 (src/services/payment.ts)
- [ ] [重构] 简化 validateUserInput 函数逻辑 (src/utils/validation.ts:34)

### Low
- [ ] [文档] 为 API 端点添加 JSDoc 注释
- [ ] [风格] 统一使用单引号（部分文件使用双引号）

第五步：总结报告

提供一个简洁的审查总结：

  1. 总体评价：代码质量的整体印象
  2. 关键发现：最重要的 3-5 个问题
  3. 统计信息：按优先级分类的问题数量
  4. 建议的行动计划：优先处理的任务顺序

最后，展示更新后的 TASK.md 相关部分。


## 命令 vs Agent Skills：何时使用哪个？

Claude Code 提供了两种自动化机制，理解它们的区别很重要。

### 对比表格

| 方面 | 斜杠命令 (Commands) | Agent Skills |
|------|-------------------|--------------|
| **复杂度** | 简单提示词模板 | 复杂的多步骤工作流 |
| **文件结构** | 单个 `.md` 文件 | 目录 + `SKILL.md` + 资源文件 |
| **调用方式** | 手动（`/command`） | 自动（根据上下文触发） |
| **适用场景** | 可复用的提示词模板 | 标准化的团队工作流 |
| **学习曲线** | 低 | 中到高 |
| **灵活性** | 高（即时修改） | 中（需要更新结构） |

### 使用建议

**使用命令（Commands）当你需要：**
- ✅ 快速可复用的提示词
- ✅ 手动触发的工作流
- ✅ 简单的参数化任务
- ✅ 跨项目的通用操作

**使用技能（Skills）当你需要：**
- ✅ 复杂的多步骤工作流
- ✅ 自动化的上下文感知行为
- ✅ 团队标准化流程
- ✅ 需要额外资源文件的功能

**实例对比：**

| 任务 | 推荐方式 |
|------|---------|
| 快速代码审查 | 命令 `/review` |
| 完整的 PR 审查流程（包括测试、文档检查等） | Skill |
| 创建 git commit | 命令 `/commit` |
| 完整的发布流程（版本号、changelog、打标签等） | Skill |
| 运行特定测试 | 命令 `/test` |
| 智能测试套件选择和执行 | Skill |

## 命令管理最佳实践

### 1. 命令命名规范

**推荐的命名风格：**
- 使用动词开头：`review`, `test`, `commit`, `fix`
- 简洁明了：`new-component` 而不是 `create-a-new-react-component`
- 使用连字符分隔多个单词：`fix-issue` 而不是 `fixissue` 或 `fix_issue`

**避免：**
- ❌ 过长的名称：`review-code-for-bugs-and-performance`
- ❌ 含糊的名称：`do-stuff`, `helper`, `util`
- ❌ 与内置命令冲突：`clear`, `help`, `config`

### 2. 组织命令文件

对于大型项目，考虑使用子目录组织命令：

.claude/commands/ ├── git/ │ ├── commit.md │ ├── pr.md │ └── rebase.md ├── test/ │ ├── unit.md │ ├── integration.md │ └── e2e.md └── review/ ├── code.md ├── security.md └── performance.md


**使用：**
```bash
/git/commit
/test/unit
/review/security

3. 文档化你的命令

在项目根目录创建 COMMANDS.md 文档所有自定义命令：

# 项目自定义命令

## Git 工作流

### /commit
创建语义化的 git commit 并推送到远程。
- **用法**: `/commit`
- **权限**: 自动执行 git 命令

### /pr
准备并创建 Pull Request。
- **用法**: `/pr [target-branch]`
- **示例**: `/pr main`

## 代码审查

### /review
全面的代码审查，按优先级分类问题。
- **用法**: `/review [@file]`
- **示例**: `/review @src/components/Button.tsx`

## 测试

### /test-all
运行所有测试并生成覆盖率报告。
- **用法**: `/test-all`

### /test-changed
只测试变更的文件。
- **用法**: `/test-changed`

4. 版本控制

将项目命令纳入版本控制：

git add .claude/commands/
git commit -m "docs: add custom Claude commands"

不要提交个人命令： 个人命令（~/.claude/commands/）不应该提交到项目仓库。

5. 团队共享

在 README.md 中介绍自定义命令：

## Claude Code 命令

本项目包含以下自定义 Claude Code 命令：

- `/commit` - 智能 Git 提交
- `/review` - 代码审查
- `/test-all` - 完整测试
- `/primer` - 项目上下文初始化

详见 [COMMANDS.md](./COMMANDS.md) 获取完整文档。

6. 持续优化

收集反馈并改进：

  • 记录命令使用频率
  • 团队成员的改进建议
  • 发现重复提示词的模式
  • 定期更新命令以反映项目变化

常见问题

Q1: 命令文件可以有多大？

A: 理论上没有限制，但建议保持在 200 行以内。如果命令过于复杂，考虑：

  • 将其拆分为多个更小的命令
  • 或者创建一个 Agent Skill

Q2: 可以在命令中调用其他命令吗？

A: 不能直接调用，但可以在命令中提示 Claude 执行类似的任务：

首先执行代码审查（类似 /review 命令的功能），
然后运行所有测试（类似 /test-all 命令的功能）。

Q3: 如何调试命令？

A:

  1. 在命令中添加详细的步骤说明
  2. 使用 /context 查看 Claude 如何理解命令
  3. 逐步测试命令，从简单到复杂
  4. 查看 Claude 的输出，调整提示词

Q4: allowed-tools 的安全性如何保证？

A:

  • 只对可信的命令使用 allowed-tools
  • 避免授权危险操作（如 rm -rf）
  • 使用通配符时要谨慎（如 Bash(*:*) 会允许所有命令）
  • 定期审查 allowed-tools 配置

推荐的安全实践：

---
# ✅ 安全：明确指定命令
allowed-tools:
  - Bash(git status:*)
  - Bash(git diff:*)
  - Bash(npm test:*)

# ❌ 不安全：过于宽泛
allowed-tools:
  - Bash(*:*)
---

Q5: 个人命令会覆盖项目命令吗？

A: 是的。如果个人命令（~/.claude/commands/）和项目命令（.claude/commands/）同名，个人命令会优先。

优先级顺序：

  1. 个人命令 (~/.claude/commands/)
  2. 项目命令 (.claude/commands/)
  3. 内置命令

Q6: 命令支持哪些 Markdown 语法？

A: 命令文件支持所有标准 Markdown 语法：

  • 标题（#, ##, ###）
  • 列表（有序和无序）
  • 代码块
  • 链接
  • 粗体和斜体

但 YAML frontmatter 必须在文件开头。

实用命令合集

以下是一些经过社区验证的实用命令，可以直接使用：

快速修复命令

.claude/commands/quick-fix.md：

---
description: 快速修复 linter 错误
allowed-tools:
  - Bash(npm run lint:*)
  - Bash(npx eslint:*)
---

1. 运行 `npm run lint` 查看所有 linter 错误
2. 分析错误类型和位置
3. 自动修复所有可自动修复的错误
4. 对于需要手动修复的错误，提供具体的修复建议
5. 显示修复前后的对比

依赖更新命令

.claude/commands/update-deps.md：

---
description: 安全更新依赖包
allowed-tools:
  - Bash(npm outdated:*)
  - Bash(npm update:*)
---

1. 运行 `npm outdated` 查看过期的依赖
2. 分析每个依赖的更新类型（major/minor/patch）
3. 优先更新 patch 和 minor 版本
4. 对于 major 版本更新，检查 CHANGELOG 和 breaking changes
5. 执行更新并运行测试
6. 如果测试失败，提供修复建议

文档生成命令

.claude/commands/gen-docs.md：

---
description: 为函数和组件生成文档
---

分析 $ARGUMENTS 指定的文件，为所有导出的函数和组件生成：

1. **JSDoc 注释**（JavaScript/TypeScript）
   - 函数描述
   - 参数说明（包括类型）
   - 返回值说明
   - 使用示例

2. **组件文档**（React）
   - 组件用途说明
   - Props 接口文档
   - 使用示例代码
   - 注意事项

3. **README 文件**（如果是目录）
   - 模块概览
   - 导出内容列表
   - 使用指南

确保文档：
- 清晰易懂
- 包含实际示例
- 保持与代码同步

总结

Claude Code 自定义命令是提升开发效率的强大工具。通过本文，你已经学会了：

  1. ✅ 理解命令的基本概念和类型
  2. ✅ 创建项目级和个人级命令
  3. ✅ 使用动态参数和 YAML frontmatter
  4. ✅ 配置 allowed-tools 实现自动化
  5. ✅ 区分命令和 Agent Skills 的使用场景
  6. ✅ 掌握命令管理的最佳实践

下一步行动：

  • 在你的项目中创建第一个自定义命令
  • 完善 CLAUDE.md 文件
  • 探索 Agent Skills 以处理更复杂的工作流
  • 与团队分享你的命令，共同提升效率

记住：最好的命令是那些能解决你实际问题的命令。从小处着手，逐步完善，让 Claude Code 真正成为你的开发伙伴！

相关阅读：