自定义命令

什么是斜杠命令？

斜杠命令是 Claude Code 中用于快速执行常见操作的快捷方式。你可以使用内置命令，也可以创建自己的自定义命令来适配团队工作流。

内置命令

开箱即用的常用操作快捷方式。

自定义命令

用 Markdown 文件定义可复用的工作流程。

参数支持

命令支持变量插值，灵活传递参数。

团队共享

提交到版本控制，团队成员共同使用。

---

内置命令

Claude Code 提供了以下内置斜杠命令：

命令	功能
/help	显示所有可用命令
/clear	清除当前对话
/compact	压缩总结上下文
/status	显示会话信息
/plan	进入计划模式
/rewind	撤销更改
/simplify	审查变更代码并修复过度工程化
/batch	通过并行 worktree agent 进行大规模变更
/insights	生成使用分析报告
/exit	退出 Claude Code

/insights 命令

/insights 分析你的 Claude Code 使用历史，生成全面的报告，识别模式、痛点和优化机会。

功能分析

该命令处理你的会话数据以检测：

• 项目领域：自动将工作聚类为主题区域（如”前端开发”、“CLI 工具”、“文档”）
• 交互风格：识别工作流模式（计划驱动、探索性、迭代式、监督式）
• 成功模式：高亮工作良好的使用方式
• 摩擦类别：精确定位反复出现的问题
• 工具使用：追踪最常用的工具
• 多实例行为：检测并行会话模式
• 时间模式：识别最高效的时间窗口

报告输出

运行 /insights 生成交互式 HTML 报告（~/.claude/usage-data/report.html），包含：

• 一目了然总结：有效做法、阻碍因素、快速改进、高级工作流
• 工作领域：3-5 个自动检测的项目区域
• 使用分析：交互风格的叙述性分析
• 出色操作：3 个”大赢”——复杂工作流的检测
• 问题区域：3 个摩擦类别及示例和缓解策略
• 功能推荐：6+ 个 CLAUDE.md 建议，3 个功能设置
• 新使用方式：3 种使用模式及可复制提示
• 交互元素：代码复制按钮、图表、导航目录

# 基本用法
/insights

# 输出示例
# 1281 sessions · 10,442 messages · 3445h · 1160 commits
# 2025-12-15 to 2026-02-06
# Report URL: file:///Users/you/.claude/usage-data/report.html

# 打开报告
open ~/.claude/usage-data/report.html          # macOS
xdg-open ~/.claude/usage-data/report.html      # Linux

提示

建议使用频率：每月运行 /insights，每次会话运行 /status。在重大项目完成后、感觉卡住时、优化 CLAUDE.md 之前运行最为有效。

/simplify 命令

/simplify（v2.1.63+ 可用）审查最近修改的代码，检查过度工程化和冗余抽象，然后自动修复。

# 审查自上次提交以来的所有变更
/simplify

# 聚焦特定关注点
/simplify focus on error handling
/simplify check for unnecessary dependencies
/simplify look at the database query patterns

它在架构和结构层面分析代码，检查：

方面	说明
复用性	可以提取的重复逻辑
质量	降低可读性或可维护性的模式
效率	算法和结构改进

注意

/simplify 是架构级工具，补充 ESLint 或 Prettier 等格式化工具，而非替代它们。

/batch 命令

/batch（v2.1.63+ 可用）通过将工作分配到 5-30 个并行 agent 来编排大规模代码库变更，每个 agent 在独立的 git worktree 中工作并开启自己的 PR。

/batch migrate from react to vue
/batch replace all uses of lodash with native equivalents
/batch add type annotations to all JavaScript files

提示

/simplify 和 /batch 都是捆绑斜杠命令，随 Claude Code v2.1.63+ 一起发布，无需配置。

---

创建自定义命令

自定义命令是放置在 .claude/commands/ 目录中的 Markdown 文件，定义了 Claude 应遵循的工作流程。

目录结构

.claude/commands/
├── tech/           # 开发工作流
│   ├── commit.md
│   └── pr.md
├── product/        # 产品工作流
│   └── problem-framer.md
└── support/        # 支持工作流
    └── ticket-analyzer.md

命名规则

命令通过目录路径和文件名来调用：

文件位置	调用方式
tech/commit.md	/tech:commit
tech/pr.md	/tech:pr
product/problem-framer.md	/product:problem-framer

变量插值

命令可以接受参数：

# 我的命令

你收到了以下参数: $ARGUMENTS[0] $ARGUMENTS[1] $ARGUMENTS[2]
（或使用简写: $0 $1 $2）

按照参数内容进行处理。

调用方式：

/tech:deploy production

此时 $ARGUMENTS[0]（或 $0）的值为 production。

警告

重要变更 (v2.1.19)：参数语法从点号表示法 ($ARGUMENTS.0) 改为方括号语法 ($ARGUMENTS[0])。如果你有使用旧语法的自定义命令，请及时更新。

---

命令模板

以下是自定义命令的推荐结构：

# 命令名称

## 目的

[简要描述命令的功能]

## 流程

按以下步骤执行：

1. **步骤 1 名称**
   [详细说明]

2. **步骤 2 名称**
   [详细说明]

3. **步骤 3 名称**
   [详细说明]

## 参数

如果提供了参数：
- 第一个参数: $ARGUMENTS[0] (或 $0)
- 第二个参数: $ARGUMENTS[1] (或 $1)
- 处理方式: [说明]
如果没有参数: [默认行为]

## 输出格式

[预期输出结构]

## 示例

### 示例 1
输入: `/command arg1`
输出: [预期结果]

## 错误处理

如果 [错误条件]:
- [恢复操作]

---

实用命令示例

示例 1：提交命令

1. 在 .claude/commands/tech/ 目录下创建 commit.md
2. 写入以下内容
3. 使用 /tech:commit 或 /tech:commit "修复登录问题" 调用

# 提交当前变更

## 目的

创建遵循 Conventional Commits 规范的格式化 git 提交。

## 流程

1. **检查状态**
   运行 `git status` 查看所有变更。

2. **分析变更**
   运行 `git diff` 了解具体改动。

3. **查看历史**
   运行 `git log -5 --oneline` 查看近期提交风格。

4. **撰写消息**
   按以下规范创建提交消息：
   - `feat`: 新功能
   - `fix`: 修复 Bug
   - `refactor`: 代码重构
   - `docs`: 文档更新
   - `test`: 测试变更
   - `chore`: 维护性工作

5. **暂存并提交**
   git add [相关文件]
   git commit -m "[类型](范围): 描述"

6. **验证**
   运行 `git status` 确认提交成功。

## 参数

如果提供 $ARGUMENTS[0]：
- 用作提交消息提示: "$0"

示例 2：PR 命令

# 创建 Pull Request

## 目的

在 GitHub 上创建有充分文档的 Pull Request。

## 流程

1. **检查分支状态**
   - `git status` - 确认工作目录干净
   - `git branch` - 确认在功能分支上
   - `git log main..HEAD` - 查看所有提交

2. **分析变更**
   - `git diff main...HEAD` - 查看相对 main 的所有变更
   - 了解 PR 的完整范围

3. **推送（如需要）**
   如果分支未推送：
   git push -u origin [分支名]

4. **创建 PR**
   gh pr create --title "[标题]" --body "[内容]"

## PR 正文模板

## Summary
[1-3 个要点描述变更]

## Changes
- [具体变更 1]
- [具体变更 2]

## Testing
- [ ] 单元测试通过
- [ ] 手动测试完成
- [ ] 无回归

## 参数

如果提供 $ARGUMENTS[0]：
- 用作 PR 标题提示: "$0"

## 错误处理

如果不在功能分支上：
- 警告: "请先创建功能分支"

如果工作目录有未提交变更：
- 询问: "是否先提交变更？"

示例 3：问题框架命令

# 问题框架分析

## 目的

在设计解决方案之前，挑战和完善问题定义。

## 流程

1. **捕获初始问题**
   记录用户陈述的问题。

2. **5 Why 分析**
   连续问"为什么？"5 次找到根本原因：
   - Why 1: [第一层回答]
   - Why 2: [更深入的回答]
   - Why 3: [更进一步]
   - Why 4: [接近根源]
   - Why 5: [根本原因]

3. **利益相关者分析**
   - 谁受到影响？
   - 谁有决策权？
   - 谁从解决方案中受益？

4. **约束识别**
   - 技术约束
   - 业务约束
   - 时间约束
   - 资源约束

5. **成功标准**
   定义可衡量的成果：
   - [指标 1]: [目标]
   - [指标 2]: [目标]

6. **重新定义问题**
   写出精炼的问题陈述：
   "我们如何为 [用户] 做到 [行动] 以实现 [结果]？"

## 输出格式

### 问题分析报告

**原始问题**: [如所述]
**根本原因**: [来自 5 Why 分析]
**精炼问题陈述**: "我们如何为 [Y] 做到 [X] 以实现 [Z]？"
**成功标准**: 1. [可衡量的成果]
**约束**: [约束列表]

---

/insights 深度解读

分析架构

/insights 的分析管道通过 7 个阶段处理会话数据：

1. 会话过滤：从 ~/.claude/projects/ 加载，排除 agent 子会话、少于 2 条用户消息或持续时间不到 1 分钟的会话
2. 对话摘要：将超过 30,000 字符的会话分块为 25,000 字符的片段
3. 特征提取：使用 Claude Haiku 将会话分类为结构化类别
4. 聚合分析：检测跨会话模式和重复工作流
5. 总结生成：在四个维度上生成”一目了然”综合报告
6. 报告渲染：生成带有可视化图表和叙述性段落的交互式 HTML
7. 特征缓存：将分类结果保存到 ~/.claude/usage-data/facets/ 以加速后续运行

分类系统维度

目标类型

共 13 种目标类型：调试/调查、实现功能、修复 Bug、编写脚本/工具、重构代码、配置系统、创建 PR/提交、数据分析、理解代码库、编写测试、编写文档、部署/基础设施、缓存预热

摩擦类型

共 12 种摩擦类别：请求被误解、方法错误、代码有 Bug、用户拒绝操作、Claude 被阻止、用户提前终止、文件位置错误、过度工程化、慢/冗长、工具失败、请求不明确、外部问题

满意度

6 个级别：挫败 -> 不满 -> 可能满意 -> 满意 -> 开心 -> 不确定

成果

4 种状态：未达成 -> 部分达成 -> 大部分达成 -> 完全达成

与其他分析工具的比较

工具	范围	输出	使用场景
/insights	会话行为、摩擦、模式	交互式 HTML 报告	工作流优化
/status	仅当前会话	文本摘要	实时监控
ccboard	经济性、成本分析	TUI/Web 仪表盘	预算跟踪
Git 历史	仅代码变更	提交日志	交付指标

提示

最佳实践：每月运行 /insights，每次会话运行 /status，每周运行 ccboard，获得全面的可见性。

---

最佳实践

组织命令

按团队职能组织目录：tech/、product/、support/，保持结构清晰。

详细流程

每个命令都应包含明确的步骤说明，让 Claude 精确执行。

参数灵活性

既支持有参数调用，也定义无参数时的默认行为。

错误处理

预设错误场景和恢复策略，确保命令健壮性。