Claude Code 自定义 Slash Commands 完全指南：打造你的专属命令库

<!-- .claude/commands/your-command.md -->
 
## 上下文
[告诉 Claude 当前的项目背景和技术栈]
 
## 任务
[明确要做什么]
 
## 约束
[列出必须遵守的规则]
 
## 输出格式
[期望的输出形式]

帮我写测试

为 $ARGUMENTS 编写单元测试。
 
技术栈：
- 测试框架：vitest
- 断言库：vitest 内置
- Mock：vi.mock()
 
要求：
1. 覆盖正常路径、边界情况和错误路径
2. 每个测试用 describe/it 组织，描述用中文
3. Mock 所有外部依赖（API 调用、文件系统、数据库）
4. 测试文件放在同目录的 __tests__ 下，命名为 [原文件名].test.ts
5. 不要测试实现细节，只测试公开接口的行为
 
先阅读目标文件，理解它的公开接口，然后再写测试。

先阅读以下文件了解项目规范：
- CLAUDE.md
- src/types/index.ts
- src/lib/constants.ts
 
然后为 $ARGUMENTS 生成符合项目规范的代码。

对 $ARGUMENTS 进行安全审计，按以下步骤执行：
 
### 第一步：静态分析
阅读代码，检查以下安全问题：
- SQL 注入
- XSS（跨站脚本）
- 命令注入
- 路径遍历
- 不安全的反序列化
 
### 第二步：依赖检查
检查 package.json 中的依赖是否有已知漏洞。
 
### 第三步：输出报告
用以下格式输出：
 
| 严重程度 | 问题 | 位置 | 建议修复 |
|---------|------|------|---------|
| 高/中/低 | 描述 | 文件:行号 | 修复方案 |
 
如果没有发现问题，明确说明"未发现安全问题"。

<!-- .claude/commands/compare.md -->
比较两个文件的实现差异并给出优化建议。
 
参数格式：`文件A 文件B`
 
示例用法：`/compare src/old-api.ts src/new-api.ts`
 
请分别阅读 $ARGUMENTS 中的两个文件，然后：
1. 列出主要差异
2. 分析各自的优缺点
3. 给出合并或优化建议

<!-- .claude/commands/doc.md -->
为 $ARGUMENTS 生成 JSDoc 文档注释。
 
要求：
- 为所有导出的函数、类、接口添加 JSDoc
- 包含 @param、@returns、@throws、@example
- 示例代码要可运行
- 不要修改函数实现，只添加注释
 
先阅读文件，理解每个导出成员的用途，再添加文档。

<!-- .claude/commands/commit-msg.md -->
基于当前 git diff --staged 的改动，生成一条 commit message。
 
格式要求：
- 类型: 简短描述（不超过 50 字符）
- 类型包括：feat、fix、refactor、docs、test、chore
- 描述用中文
 
$ARGUMENTS
 
如果上面有额外说明，请结合说明生成。否则根据 diff 内容自行判断。

<!-- .claude/commands/review.md -->
对当前 git diff --staged 中的改动进行 Code Review。
 
检查维度：
1. **安全性** — XSS、注入、敏感信息泄露、不安全的依赖
2. **性能** — 不必要的重渲染、内存泄漏、N+1 查询、大循环
3. **可维护性** — 命名清晰度、函数长度、职责单一性
4. **边界情况** — 空值处理、错误处理、并发安全
 
输出格式：
- 每个问题标注严重程度（🔴 高 / 🟡 中 / 🟢 低）
- 给出具体的修复建议和代码示例
- 最后给一个总体评价
 
如果代码质量很好，也请明确说明。

<!-- .claude/commands/refactor.md -->
分析 $ARGUMENTS 并给出重构建议。
 
分析维度：
1. 是否有重复代码可以提取
2. 函数是否过长，是否需要拆分
3. 是否有更好的设计模式可以应用
4. 类型定义是否可以优化
 
要求：
- 只建议有实际价值的重构，不要为了重构而重构
- 每个建议给出重构前后的代码对比
- 评估重构的风险和收益

<!-- .claude/commands/test.md -->
为 $ARGUMENTS 编写单元测试。
 
框架：vitest
规则：
1. 覆盖正常路径、边界情况、错误路径
2. describe/it 结构，描述用中文
3. Mock 外部依赖
4. 测试文件：同目录 __tests__/[文件名].test.ts
5. 只测试公开接口，不测试实现细节
 
先阅读目标文件理解接口，再写测试。

<!-- .claude/commands/test-edge.md -->
阅读 $ARGUMENTS 的现有测试文件，找出未覆盖的边界情况并补充测试。
 
重点关注：
- 空值 / undefined / null
- 空数组 / 空字符串
- 超大输入
- 并发调用
- 类型边界（如 Number.MAX_SAFE_INTEGER）
- 特殊字符和 Unicode
 
不要重复已有的测试用例。

<!-- .claude/commands/doc.md -->
为 $ARGUMENTS 中所有导出的函数、类、接口添加文档注释。
 
格式：JSDoc / TSDoc
包含：@param、@returns、@throws、@example
要求：
- 示例代码要可运行
- 不修改实现代码
- 复杂逻辑加 @remarks 说明设计意图

<!-- .claude/commands/changelog.md -->
基于最近的 git log 生成 CHANGELOG 条目。
 
$ARGUMENTS
 
如果指定了版本号，用该版本号；否则用日期。
 
格式：
## [版本号/日期]
 
### 新功能
- 描述
 
### 修复
- 描述
 
### 变更
- 描述
 
只包含用户可感知的变更，忽略内部重构和代码风格调整。

<!-- .claude/commands/commit-msg.md -->
基于 git diff --staged 生成 commit message。
 
格式：类型: 描述
类型：feat / fix / refactor / docs / test / chore / perf
描述：中文，不超过 50 字符
如果改动较大，加空行后写详细说明。
 
$ARGUMENTS

<!-- .claude/commands/pr-desc.md -->
基于当前分支与 main 的 diff，生成 Pull Request 描述。
 
运行 git log main..HEAD 和 git diff main...HEAD 获取改动。
 
格式：
## 概述
一句话描述这个 PR 做了什么。
 
## 改动内容
- 列出主要改动点
 
## 测试
- 描述如何测试这些改动
 
## 截图（如适用）
标注是否需要截图。

<!-- .claude/commands/debug.md -->
诊断以下问题：
 
$ARGUMENTS
 
步骤：
1. 理解问题描述
2. 定位可能的相关代码
3. 分析可能的原因（列出至少 3 个）
4. 给出最可能的原因和修复方案
5. 如果需要更多信息，说明需要什么
 
不要直接修改代码，先给出分析。

<!-- .claude/commands/explain.md -->
解释 $ARGUMENTS 的代码逻辑。
 
要求：
- 先给一句话总结这个文件/函数的作用
- 然后逐段解释关键逻辑
- 标注复杂或不直观的部分
- 如果有潜在问题，指出来
- 用类比帮助理解复杂概念

# 1. 写功能
> 实现用户收藏功能，收藏数据存 localStorage
 
# 2. 审查代码
> /review
 
# 3. 生成测试
> /test src/lib/favorites.ts
 
# 4. 生成文档
> /doc src/lib/favorites.ts
 
# 5. 生成提交信息
> /commit-msg

<!-- .claude/commands/ship.md -->
完成以下发布前检查流程：
 
1. 运行 git diff --staged 查看待提交的改动
2. 对改动进行 Code Review（检查安全、性能、可维护性）
3. 如果发现问题，列出问题但不自动修复
4. 如果没有问题，生成 commit message（格式：类型: 描述）
5. 输出最终的 commit 命令供我确认
 
不要自动执行 git commit，只输出命令。

git add .claude/commands/
git commit -m "feat: 添加团队共享的 Claude 命令"

## 可用的 Claude 命令
 
| 命令 | 用途 | 示例 |
|------|------|------|
| `/review` | 代码审查 | `/review` |
| `/test` | 生成测试 | `/test src/lib/posts.ts` |
| `/gen-component` | 生成组件 | `/gen-component UserProfile` |
| `/commit-msg` | 生成提交信息 | `/commit-msg` |
| `/pr-desc` | 生成 PR 描述 | `/pr-desc` |

<!--
  作者：@jimmy
  用途：生成符合项目规范的 React 组件
  更新：2026-03-15
-->
为 $ARGUMENTS 生成一个 React 组件...

<!-- .claude/commands/gen-component.md -->
生成一个名为 $ARGUMENTS 的 React 组件。
 
项目技术栈：
- Next.js 16 (App Router) + TypeScript
- Tailwind CSS v4
- next-intl 做 i18n
 
规则：
1. 默认生成 Server Component，除非组件名包含 "Client" 或需要交互
2. 文件放在 components/ 目录下
3. 使用 Tailwind CSS 做样式，不用 CSS Modules
4. 如果组件需要文本，使用 next-intl 的 useTranslations
5. 添加必要的 aria 属性确保可访问性
6. Props 用 interface 定义，命名为 [组件名]Props
 
先检查 components/ 目录下是否已有同名组件。

<!-- .claude/commands/i18n-check.md -->
检查项目的国际化完整性。
 
步骤：
1. 读取 messages/zh.json 和 messages/en.json
2. 对比两个文件的 key 结构，找出：
   - zh 有但 en 没有的 key
   - en 有但 zh 没有的 key
   - 值为空字符串的 key
3. 扫描 components/ 和 app/ 目录，找出硬编码的中文或英文文本
4. 检查是否有使用了但未定义的 i18n key
 
输出格式：
- 缺失的 key 列表（标注在哪个文件缺失）
- 硬编码文本列表（标注文件和行号）
- 未定义的 key 列表

<!-- .claude/commands/gen-post.md -->
创建一篇新的博客文章脚手架。
 
参数格式：slug 标题
示例：/gen-post my-new-post 我的新文章
 
根据 $ARGUMENTS 创建：
1. content/zh/[slug].mdx — 中文版，包含 frontmatter
2. content/en/[slug].mdx — 英文版，包含 frontmatter
 
Frontmatter 模板：
---
title: "标题"
date: "当前日期 YYYY-MM-DD"
description: 待填写
tags: ["待分类"]
---
 
## 前言
 
[在这里开始写作]
 
两个文件都创建好后，提醒我填写 description 和 tags。

<!-- .claude/commands/a11y-audit.md -->
对 $ARGUMENTS 进行可访问性审计。
 
检查清单：
1. **语义化 HTML** — 是否使用了正确的 HTML 元素（button vs div, nav vs div）
2. **ARIA 属性** — 是否有必要的 aria-label、aria-describedby、role
3. **键盘导航** — 所有交互元素是否可通过键盘访问
4. **焦点管理** — 模态框、下拉菜单是否有焦点陷阱
5. **颜色对比** — 文本颜色与背景色的对比度是否足够
6. **图片替代文本** — img 是否有 alt，装饰性图片是否有 aria-hidden
7. **动态内容** — 动态更新的内容是否有 aria-live
 
输出每个问题的位置和修复建议。

# 1. 生成组件脚手架
> /gen-component ReadingProgress
 
# Claude 生成 components/ReadingProgress.tsx
# 包含滚动监听、进度计算、Tailwind 样式
 
# 2. 检查可访问性
> /a11y-audit components/ReadingProgress.tsx
 
# Claude 指出需要添加 role="progressbar" 和 aria-valuenow
 
# 3. 生成测试
> /test components/ReadingProgress.tsx
 
# 4. 检查 i18n（如果组件有文本）
> /i18n-check
 
# 5. 审查并提交
> /review
> /commit-msg

<!-- .claude/commands/flutter-feature.md -->
为 Flutter 项目创建一个新功能模块的完整目录结构。
 
功能名称：$ARGUMENTS
 
创建以下目录和文件：
 
lib/features/[功能名]/
  data/
    models/[功能名]_model.dart
    repositories/[功能名]_repository_impl.dart
    datasources/[功能名]_remote_datasource.dart
  domain/
    entities/[功能名].dart
    repositories/[功能名]_repository.dart
    usecases/get_[功能名].dart
  presentation/
    cubits/[功能名]_cubit.dart
    cubits/[功能名]_state.dart
    pages/[功能名]_page.dart
    widgets/
 
每个文件只包含基本骨架（类定义、必要的 import），不写具体实现。
 
参考现有功能模块的代码风格（如 lib/features/auth/）。
功能名使用 snake_case。

<!-- .claude/commands/flutter-bloc.md -->
为 $ARGUMENTS 生成 Cubit 和 State 类。
 
参数格式：功能名 状态列表
示例：/flutter-bloc favorites Initial,Loading,Loaded,Error
 
规则：
1. 使用 flutter_bloc 的 Cubit（不是 Bloc，除非明确要求）
2. State 使用 sealed class（Dart 3）
3. Loaded state 包含对应的数据字段
4. Error state 包含 String message 字段
5. Cubit 方法只定义签名，方法体写 TODO 注释
6. 添加 equatable 支持
 
文件：
- lib/features/[功能名]/presentation/cubits/[功能名]_cubit.dart
- lib/features/[功能名]/presentation/cubits/[功能名]_state.dart
 
参考项目中现有的 Cubit 实现风格。

<!-- .claude/commands/flutter-model.md -->
根据描述生成 Flutter 数据模型。
 
$ARGUMENTS
 
要求：
1. Entity（domain 层）：纯 Dart 类，不依赖任何包
2. Model（data 层）：继承 Entity，添加 fromJson/toJson
3. 使用 freezed 或手写，取决于项目现有风格
4. 如果用 Hive，添加 TypeAdapter
5. 包含 copyWith 方法
 
先检查项目中现有的 Model 实现方式，保持一致。

<!-- .claude/commands/flutter-test.md -->
为 $ARGUMENTS 生成测试。
 
自动判断测试类型：
- domain/usecases/ → 单元测试，mock Repository
- data/repositories/ → 单元测试，mock DataSource
- presentation/cubits/ → bloc_test，mock UseCase
- presentation/pages/ → Widget 测试，mock Cubit
- presentation/widgets/ → Widget 测试
 
规则：
1. 使用 mocktail 做 mock
2. Cubit 测试使用 bloc_test 包
3. Widget 测试使用 BlocProvider.value 注入 mock Cubit
4. 测试文件镜像 lib/ 的目录结构放在 test/ 下
5. 每个测试用 group/test 组织
 
先阅读目标文件，理解依赖关系，再写测试。

<!-- .claude/commands/flutter-review.md -->
对当前 git diff --staged 进行 Flutter 项目专属的 Code Review。
 
除了通用的代码审查（安全、性能、可维护性），额外检查：
 
1. **架构合规** — 是否遵守 Clean Architecture 的依赖规则
   - domain 层不依赖 data 层或 presentation 层
   - data 层不依赖 presentation 层
2. **状态管理** — Cubit/Bloc 使用是否正确
   - State 是否不可变
   - 是否在 Widget 中直接操作数据（应该通过 Cubit）
3. **Widget 优化**
   - 是否有不必要的 rebuild（缺少 const、BlocSelector）
   - 是否有过深的 Widget 嵌套（建议提取）
4. **Dart 规范**
   - 是否使用了 Dart 3 的新特性（patterns、sealed class）
   - 命名是否符合 Dart 规范（lowerCamelCase、UpperCamelCase）
5. **依赖注入** — 是否正确注册到 get_it

# 第一步：创建功能模块骨架
> /flutter-feature favorites
 
# Claude 创建完整的目录结构：
# lib/features/favorites/data/models/favorites_model.dart
# lib/features/favorites/data/repositories/favorites_repository_impl.dart
# lib/features/favorites/domain/entities/favorites.dart
# lib/features/favorites/domain/repositories/favorites_repository.dart
# lib/features/favorites/domain/usecases/get_favorites.dart
# lib/features/favorites/presentation/cubits/favorites_cubit.dart
# lib/features/favorites/presentation/cubits/favorites_state.dart
# lib/features/favorites/presentation/pages/favorites_page.dart
 
# 第二步：生成数据模型
> /flutter-model Favorite 实体：id(String), itemId(String),
  itemType(enum: article/video/podcast), createdAt(DateTime),
  userId(String)。使用 Hive 存储。
 
# 第三步：生成 Cubit
> /flutter-bloc favorites Initial,Loading,Loaded,Error
 
# 第四步：实现业务逻辑
> 实现 favorites 功能的 UseCase：
  - AddFavorite：添加收藏，检查是否已收藏
  - RemoveFavorite：取消收藏
  - GetFavorites：获取收藏列表，支持分页
  - CheckFavorite：检查某个 item 是否已收藏
 
# 第五步：生成测试
> /flutter-test lib/features/favorites/domain/usecases/
> /flutter-test lib/features/favorites/presentation/cubits/favorites_cubit.dart
 
# 第六步：代码审查
> /flutter-review