Claude Code Commands 系统指南

什么是 Commands

Commands 是 Claude Code 的命令系统，允许你创建自定义的 Slash 命令来自动化重复性工作。

核心概念

自定义命令 = Markdown 文件
命令名 = 文件名（不含 .md）
命令内容 = Markdown 文件内容
参数 = $ARGUMENTS 变量

命令类型

| 类型 | 来源 | 位置 | 特点 | |------|------|------|------| | 内置命令 | 官方 | 程序内部 | 不可修改 | | 项目级命令 | 自定义 | .claude/commands/ | 仅当前项目 | | 用户级命令 | 自定义 | ~/.claude/commands/ | 所有项目共享 |

快速开始

创建第一个命令

步骤 1：创建命令目录

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

步骤 2：创建命令文件

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

# 问候命令

你好！我是你的 AI 助手。

用户想要问候的对象是：$ARGUMENTS

如果没有提供名字，请使用"朋友"作为默认称呼。

请用热情友好的方式问候，并询问今天可以帮助什么。

步骤 3：测试命令

# 启动 Claude Code
claude

# 使用命令
/hello 张三

命令文件结构

完整结构

一个完整的命令文件包含两部分：

frontmatter 配置区（可选）
Markdown 正文（必需）

---
description: 命令描述
argument-hint: <参数说明>
allowed-tools:
  - Read
  - Write
model: claude-sonnet-4-6
---

# 命令标题

命令的具体内容...

使用 $ARGUMENTS 接收参数

| 配置项 | 说明 | 示例 | |--------|------|------| | description | 命令描述 | 公众号文章创作命令 | | argument-hint | 参数提示 | <主题> [风格] | | allowed-tools | 允许的工具 | [Read, Write, WebSearch] | | model | 指定模型 | claude-opus-4-6 |

参数处理

基本用法

# 问候命令

用户要问候的对象是：$ARGUMENTS

调用示例：

/hello 张三
# $ARGUMENTS = "张三"

/hello
# $ARGUMENTS = ""

多参数解析

# 文章生成命令

## 参数格式
$ARGUMENTS 格式：<主题> [风格] [字数]

解析规则：
- 第一个参数：主题（必需）
- 第二个参数：风格（可选，默认"接地气"）
- 第三个参数：字数（可选，默认1500）

参数验证

# 代码审查命令

## 输入验证
首先检查 $ARGUMENTS：

**如果为空**：
提示用户：请提供文件路径
终止执行

**如果不是有效路径**：
提示用户：路径无效
终止执行

**如果验证通过**：
继续执行审查流程

## 执行步骤

### 步骤 1：读取配置
使用 Read 工具读取配置文件：

Read(".claude/settings.json")


### 步骤 2：搜索 TODO
使用 Grep 搜索所有 TODO：

Grep("TODO|FIXME", path="src/", type="py")


### 步骤 3：运行测试
使用 Bash 执行测试：
```bash
npm run test


## 命令作用域

### 项目级命令

**位置：** `.claude/commands/`  
**作用域：** 仅当前项目  
**适用场景：** 团队共享、项目特定

```bash
# 创建项目级命令
mkdir -p .claude/commands
echo "# 项目命令" > .claude/commands/deploy.md

用户级命令

位置： ~/.claude/commands/
作用域： 所有项目
适用场景： 个人工具、通用模板

# 创建用户级命令
mkdir -p ~/.claude/commands
echo "# 通用命令" > ~/.claude/commands/format.md

优先级规则

当同名命令存在于多个位置时：

1. 项目级（最高）: .claude/commands/
2. 用户级: ~/.claude/commands/
3. 内置命令（最低）

注意： 核心系统命令（如 /clear、/help）受保护，不能被覆盖。

命令命名空间

使用子目录组织命令：

.claude/commands/
├── dev/
│   ├── code-review.md    → /dev:code-review
│   └── debug.md          → /dev:debug
├── test/
│   └── generate.md       → /test:generate
└── deploy/
    └── prepare.md        → /deploy:prepare

实战案例

案例 1：代码审查命令

---
description: 代码审查命令 - 检查代码质量
argument-hint: <文件路径>
allowed-tools:
  - Read
---

# 代码审查命令

## 任务
对指定文件进行代码审查。

## 参数
文件路径：$ARGUMENTS

## 执行流程

### 步骤 1：验证参数
如果 $ARGUMENTS 为空，提示用户提供文件路径。

### 步骤 2：读取文件
使用 Read 工具读取文件内容。

### 步骤 3：执行审查
从以下维度审查代码：

**代码风格**
- 命名规范
- 缩进一致性
- 注释完整性

**潜在 Bug**
- 空值检查
- 边界条件
- 异常处理

**安全问题**
- SQL 注入风险
- XSS 风险
- 敏感信息泄露

### 步骤 4：输出报告
生成结构化的审查报告。

案例 2：文章创作命令

---
description: 文章创作命令
argument-hint: <主题>
allowed-tools:
  - Read
  - Write
  - WebSearch
---

# 文章创作命令

## 任务
根据主题创作文章。

主题：$ARGUMENTS

## 执行流程

### 步骤 1：信息收集
使用 WebSearch 搜索主题相关信息。

### 步骤 2：构思大纲
- 引言
- 核心内容
- 总结

### 步骤 3：撰写文章
按照大纲撰写完整文章。

### 步骤 4：保存文章
使用 Write 工具保存到 articles 目录。

高级技巧

命令组合

在命令中调用其他命令：

# 工作流命令

## 执行步骤

### 步骤 1：热点扫描
执行 /hotspot 命令获取热点。

### 步骤 2：创作文章
使用选定主题执行 /write 命令。

### 步骤 3：质量检查
执行 /check 命令进行检查。

模块化设计

创建可复用的模块：

# 写作风格模块
# 文件：.claude/modules/writing-style.md

## 语言风格
- 说人话，不说 AI 腔
- 用"你"而不是"您"
- 举例子比讲道理更有效

## 句式要求
- 短句优先
- 每段不超过 150 字

在命令中引用模块：

## 步骤 1：加载写作规范
Read(".claude/modules/writing-style.md")

## 步骤 2：按规范创作
遵循加载的写作规范创作文章...

常见问题

Q1: 命令文件放在哪里？

项目级：.claude/commands/
用户级：~/.claude/commands/

Q2: 如何传递参数？

在命令后直接输入，用 $ARGUMENTS 接收：

/write AI 教程
# $ARGUMENTS = "AI 教程"

Q3: frontmatter 是必须的吗？

不是必须的，但推荐使用以提供更好的用户体验。

Q4: 如何指定使用的模型？

在 frontmatter 中设置：

---
model: claude-opus-4-6
---

Q5: 命令可以调用其他命令吗？

可以！在命令中说明调用哪个命令即可。

Q6: 如何限制命令可用的工具？

使用 allowed-tools 配置：

---
allowed-tools:
  - Read
  - Write
---

Q7: 命令不执行怎么办？

检查清单：

文件是否存在于正确位置
文件名是否正确（含 .md 扩展名）
frontmatter 格式是否正确
是否重启过 Claude Code

Q8: 如何查看可用命令？

# 方法 1：help 命令
/help

# 方法 2：Tab 补全
输入 / 然后按 Tab 键

Q9: 如何分享命令给团队？

将 .claude/commands/ 加入 Git 版本控制：

git add .claude/commands/
git commit -m "Add custom commands"
git push

Q10: 命令有大小限制吗？

没有硬性限制，但建议：

单个命令文件不超过 500 行
复杂逻辑拆分为多个命令
通用内容提取为模块

最佳实践

命名规范

使用英文命名
使用小写字母和连字符
名称要简洁明确

✅ /code-review
✅ /write-article
❌ /CodeReview
❌ /写文章

目录组织

.claude/commands/
├── dev/          # 开发类命令
├── test/         # 测试类命令
├── deploy/       # 部署类命令
└── content/      # 内容类命令

文档注释

在命令文件中添加清晰的注释：

---
description: 代码审查命令
argument-hint: <文件路径>
---

# 代码审查命令

## 功能说明
对指定文件进行全面的代码质量审查。

## 使用方法
/code-review src/main.py

## 参数说明
- 文件路径：要审查的文件路径（必需）

错误处理

在命令中添加参数验证和错误处理：

## 输入验证
如果 $ARGUMENTS 为空：
- 提示用户正确的使用方法
- 终止执行

如果文件不存在：
- 提示文件路径无效
- 终止执行

命令速查表

基础命令模板

---
description: 命令描述
argument-hint: <参数>
allowed-tools:
  - Read
  - Write
---

# 命令标题

## 任务
执行的任务描述

## 参数
$ARGUMENTS

## 执行步骤

### 步骤 1
...

### 步骤 2
...

## 输出格式
...

frontmatter 配置

---
description: 命令描述
argument-hint: <必需> [可选]
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - WebSearch
model: claude-sonnet-4-6
---

Claude Command Suite - 148+ 专业命令
Awesome Claude Code - 社区精选资源

总结

通过本指南，你已经掌握了：

Commands 基础 - 命令的本质和类型
命令开发 - frontmatter 配置、参数处理、工具调用
高级技巧 - 命令组合、模块化设计
最佳实践 - 命名规范、目录组织、错误处理

下一步学习：

MCP 集成 - 连接外部工具
Hooks 系统 - 自动化触发
Skills 定制 - 创建技能包

参考资源

更新日期： 2026年4月29日
适用版本： Claude Code v2.1.92+

Claude Code Commands 系统指南

分享这篇文章