Claude Code自定义命令与团队提示词库全实战

claude --version
# 预期输出: Claude Code v1.0.x 或更高

graph TD
    A[Claude Code 扩展体系] --> B[自定义命令<br/>.claude/commands/*.md]
    A --> C[技能 Skills<br/>SKILL.md + description]
    A --> D[插件 Plugins<br/>完整扩展包]

    B --> B1[显式调用 /project:xxx]
    B --> B2[轻量 Markdown 文件]
    B --> B3[适合团队流程标准化]

    C --> C1[上下文自动触发]
    C --> C2[含触发条件描述]
    C --> C3[适合领域知识封装]

    D --> D1[可包含命令+技能+Hooks+MCP]
    D --> D2[可发布到市场]
    D --> D3[适合完整工具链封装]

    style B fill:#4CAF50,color:#fff
    style C fill:#2196F3,color:#fff
    style D fill:#FF9800,color:#fff

你的开发环境
├── ~/.claude/commands/          ← 用户级命令（所有项目通用）
│   ├── daily-review.md          → /user:daily-review
│   ├── commit.md                → /user:commit
│   └── scaffold/
│       └── react-component.md   → /user:scaffold/react-component
│
└── your-project/                ← 项目目录
    └── .claude/
        └── commands/            ← 项目级命令（仅当前项目）
            ├── review.md        → /project:review
            ├── deploy.md        → /project:deploy
            ├── handoff.md       → /project:handoff
            └── api/
                ├── new.md       → /project:api/new
                └── test.md      → /project:api/test

sequenceDiagram
    participant U as 开发者
    participant CC as Claude Code
    participant FS as 文件系统

    U->>CC: 输入 /project:review $ARGUMENTS
    CC->>FS: 查找 .claude/commands/review.md
    FS-->>CC: 返回 Markdown 内容
    CC->>CC: 替换 $ARGUMENTS 占位符
    CC->>CC: 将内容作为提示词注入
    CC->>U: 按命令指令执行操作

    Note over U,FS: 也可以是 /user:review 查找 ~/.claude/commands/review.md

# 进入你的项目目录
cd your-project

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

请对以下文件或代码变更进行全面审查。

审查维度（按优先级排序）：

1. **正确性**：逻辑错误、边界条件、空指针/异常处理
2. **安全性**：SQL注入、XSS、敏感信息泄露、权限检查
3. **性能**：不必要的循环、内存泄漏、N+1查询
4. **可读性**：命名规范、函数长度、注释质量
5. **可维护性**：耦合度、重复代码、扩展性

输出格式：
- 使用表格列出发现的问题
- 每个问题标注严重级别（🔴 严重 / 🟡 警告 / 🔵 建议）
- 给出具体的修复建议和代码示例

重点关注文件：$ARGUMENTS

> /project:review src/auth/login.ts

# Claude Code 会自动：
# 1. 读取 .claude/commands/review.md 的内容
# 2. 将 "src/auth/login.ts" 替换 $ARGUMENTS
# 3. 按照审查维度执行分析

## 代码审查报告：src/auth/login.ts

| # | 级别 | 维度 | 问题 | 修复建议 |
|---|------|------|------|----------|
| 1 | 🔴 严重 | 安全性 | 密码明文传输 | 使用 bcrypt 哈希后再传输 |
| 2 | 🟡 警告 | 性能 | 登录成功后重新查询用户 | 使用已有查询结果 |
| 3 | 🔵 建议 | 可读性 | 函数超80行 | 拆分为 validateInput + authenticate |

你是一个专业的 Bug 修复助手。请按以下步骤操作：

## 输入解析
用户输入格式为：`<文件路径> --问题描述 <描述> --优先级 <high|medium|low>`

解析 $ARGUMENTS 提取上述参数。如果某个参数缺失，使用默认值：
- 优先级默认：medium
- 描述默认：根据文件内容推断

## 执行步骤
1. 读取指定文件，理解代码上下文
2. 定位问题根因（不要只修复表面症状）
3. 编写能复现问题的测试用例
4. 实现最小化修复
5. 运行测试验证修复
6. 检查修复是否引入新问题

## 输出格式
- **根因分析**（3句话以内）
- **修复方案**（含代码 diff）
- **测试用例**（完整可运行）
- **风险评估**（修复可能影响的范围）

> /project:fix src/api/payment.ts --问题描述 支付金额计算错误 --优先级 high

graph LR
    A[/project:check] --> B[/project:test]
    B --> C[/project:lint]
    C --> D[/project:review]
    D --> E[/project:commit]

    F[/project:deploy] --> G[组合调用]
    G --> A
    G --> B
    G --> H[/project:build]
    H --> I[/project:push]

    style G fill:#4CAF50,color:#fff

## 项目健康检查

请依次执行以下检查，每步通过后才进入下一步：

### 1. 依赖检查
- 运行 `npm audit` 检查安全漏洞
- 运行 `npm outdated` 检查过时依赖
- 如有高危漏洞，立即报告并停止

### 2. 类型检查
- 运行 `tsc --noEmit`
- 报告所有类型错误

### 3. 测试检查
- 运行 `npm test -- --coverage`
- 覆盖率低于 80% 的模块标红

### 4. Lint 检查
- 运行 `npm run lint`
- 按严重程度分类报告

### 汇总
最终输出一份简洁的检查报告表格，包含：
- 各步骤通过状态 ✅/❌
- 发现的问题数量和严重程度
- 建议的下一步操作

额外关注：$ARGUMENTS

mkdir -p ~/.claude/commands

请详细解释以下代码的工作原理。要求：

1. **整体功能**：用一句话概括这段代码做什么
2. **执行流程**：画出核心执行路径（用文字描述）
3. **关键决策**：解释代码中的关键设计选择和原因
4. **潜在问题**：指出可能存在的隐患
5. **改进建议**：如果有更好的实现方式，给出建议

代码/文件路径：$ARGUMENTS

注意：
- 假设我是具有1-2年经验的开发者，不需要解释基础语法
- 重点解释"为什么这样写"，而不仅仅是"做了什么"
- 如果涉及第三方库，说明库的选择理由

> /user:explain src/utils/debounce.ts

请为当前的代码变更生成 Git 提交信息。

## 规则
1. 遵循 Conventional Commits 规范：
   - feat: 新功能
   - fix: Bug修复
   - refactor: 重构（不改变行为）
   - docs: 文档
   - test: 测试
   - chore: 构建/工具变更
   - perf: 性能优化

2. Subject 行：
   - 不超过 50 个字符
   - 使用英文
   - 使用祈使语气（"add" 而非 "added"）

3. Body（如需要）：
   - 解释 "为什么" 而非 "做了什么"
   - 每行不超过 72 个字符

4. 先运行 `git diff --staged` 查看变更内容
5. 如果变更涉及多个关注点，建议拆分为多个提交

额外上下文：$ARGUMENTS

graph TB
    subgraph "团队 Git 仓库"
        A[项目根目录] --> B[.claude/]
        B --> C[commands/]
        C --> D[review.md]
        C --> E[deploy.md]
        C --> F[handoff.md]
        C --> G[api/]
        G --> H[new.md]
        G --> I[test.md]
        C --> J[db/]
        J --> K[migrate.md]
        J --> L[seed.md]
    end

    subgraph "开发者A - 前端"
        M[~/.claude/commands/]
        M --> N[component.md]
        M --> O[style.md]
    end

    subgraph "开发者B - 后端"
        P[~/.claude/commands/]
        P --> Q[api-test.md]
        P --> R[debug.md]
    end

    style C fill:#4CAF50,color:#fff
    style M fill:#2196F3,color:#fff
    style P fill:#2196F3,color:#fff

# 代码审查命令

你是一位严格但建设性的代码审查员。请审查指定的代码变更。

## 审查清单

### 必查项（每项必须明确通过/不通过）
- [ ] 输入验证：所有外部输入是否已验证和清洗
- [ ] 错误处理：是否有适当的 try/catch 和错误边界
- [ ] 日志记录：关键操作是否有日志（不含敏感信息）
- [ ] 类型安全：TypeScript 类型是否完整（无 any）
- [ ] 测试覆盖：是否有对应的单元/集成测试

### 按严重程度分类
- 🔴 P0 - 必须修复：安全漏洞、数据丢失风险、功能崩溃
- 🟡 P1 - 强烈建议：性能问题、可维护性差、缺少测试
- 🔵 P2 - 改进建议：命名优化、代码简化、文档补充

## 输出格式

### 审查摘要
| 维度 | 状态 | 问题数 |
|------|------|--------|
| 安全性 | ✅/❌ | N |
| 正确性 | ✅/❌ | N |
| 性能   | ✅/❌ | N |
| 可读性 | ✅/❌ | N |
| 测试   | ✅/❌ | N |

### 问题详情
对每个问题提供：位置、描述、严重程度、修复建议（含代码）

审查目标：$ARGUMENTS

# 部署前检查与执行

请执行完整的部署流程。环境：$ARGUMENTS（默认：staging）

## 阶段1：预检
1. 确认当前分支是从 main/latest 拉取的最新版本
2. 运行完整测试套件：`npm test`
3. 运行类型检查：`tsc --noEmit`
4. 运行 lint：`npm run lint`
5. 检查是否有未提交的变更

任何一步失败 → 停止并报告

## 阶段2：构建
1. 设置目标环境变量
2. 执行构建命令：`npm run build`
3. 检查构建产物大小是否异常（与上次对比）

## 阶段3：部署
1. 根据环境选择部署方式：
   - staging → 部署到测试环境
   - production → 需要额外确认才能继续
2. 执行部署命令
3. 等待部署完成

## 阶段4：验证
1. 检查健康检查端点
2. 验证关键API是否响应正常
3. 检查错误日志是否有新增异常

## 输出
每个阶段输出执行状态和关键指标。最终给出部署总结。

# 会话交接文档生成器

请生成一份完整的会话交接文档，让下一位开发者（或明天的你）能快速接续工作。

## 需要包含的信息

### 1. 当前进度
- 本会话完成了哪些任务
- 进行中的任务及其状态
- 未开始但已规划的任务

### 2. 关键决策记录
- 做了哪些架构/设计决策
- 决策理由（为什么选择A而非B）
- 是否有被否决的方案及原因

### 3. 代码变更概要
- 修改了哪些文件，每个文件的变更目的
- 新增的依赖及原因
- 数据库 schema 变更（如有）

### 4. 已知问题与风险
- 遗留的 TODO 项
- 已知的技术债务
- 潜在的兼容性问题

### 5. 下一步建议
- 按优先级排序的待办事项
- 需要注意的外部依赖或截止日期

## 格式要求
- 使用 Markdown 格式
- 每个部分控制在 200 字以内
- 代码变更用 diff 格式展示
- 附加到项目的 handoff/ 目录下，文件名含日期

额外关注点：$ARGUMENTS

# 确认命令目录结构正确
tree .claude/commands/
# 预期输出:
# .claude/commands/
# ├── review.md
# ├── deploy.md
# ├── handoff.md
# └── api/
#     ├── new.md
#     └── test.md

# 添加到 Git
git add .claude/commands/

# 提交（注意：这只是让命令进入版本控制，不要自动提交）
# 团队成员 pull 后即可使用这些命令

## 自定义命令开发规范

### 命名规则
- 使用小写英文，单词用 `-` 连接
- 命令名应反映动作：review / deploy / migrate / scaffold
- 子目录按领域划分：api/ / db/ /infra/

### 内容结构
每个命令文件必须包含：
1. **角色定义**：告诉 Claude 它扮演什么角色
2. **输入说明**：$ARGUMENTS 的格式和默认值
3. **执行步骤**：按顺序的操作指令
4. **输出格式**：期望 Claude 返回什么
5. **约束条件**：不能做什么（安全边界）

### 质量标准
- 命令描述应简洁明确（不超过 50 行）
- 使用 Markdown 标题和列表组织内容
- 关键约束用 **粗体** 或 `代码格式` 突出
- 测试命令是否按预期工作后再提交

# 创建新 API 端点

请按照项目的 API 设计规范创建新的端点。

## 规范来源
请先读取以下文件了解项目规范：
- `docs/api-design-guide.md` - API 设计指南
- `docs/error-codes.md` - 错误码定义
- `prisma/schema.prisma` - 数据模型

## 执行步骤
1. 根据规范创建路由文件
2. 编写请求验证中间件
3. 实现业务逻辑（含错误处理）
4. 编写 API 文档（OpenAPI 格式）
5. 编写集成测试

## API 信息
$ARGUMENTS

格式：`<方法> <路径> - <描述>`
示例：`POST /api/v1/orders - 创建新订单`

# 智能任务推荐

请分析当前项目的状态，推荐下一步应该做什么。

## 分析维度
1. 查看 `git status` 和 `git log --oneline -10` 了解近期变更
2. 查看 `TODO` 和 `FIXME` 注释的分布：`grep -r "TODO\|FIXME" src/`
3. 查看测试覆盖率报告（如果能运行）
4. 查看是否有未解决的 issue 或 PR review comment
5. 检查依赖更新状态：`npm outdated`

## 输出
按以下格式推荐 3-5 个任务：

| 优先级 | 任务 | 类型 | 预计时间 | 理由 |
|--------|------|------|----------|------|
| P0 | ... | bugfix | 30min | ... |
| P1 | ... | feature | 2h | ... |
| P2 | ... | refactor | 1h | ... |

类型可选：bugfix / feature / refactor / test / docs / chore

额外关注：$ARGUMENTS

# 发布流程编排器

请按以下顺序执行发布流程。**每步必须通过后才继续**。

## 流程

### Step 1: 代码审查
- 执行 /project:review 命令的逻辑
- 审查所有自上次发布以来的变更
- 如有 P0 问题 → 停止发布

### Step 2: 测试
- 运行完整测试套件
- 如有失败 → 停止发布

### Step 3: 版本号更新
- 查看 CHANGELOG.md 确定版本类型（major/minor/patch）
- 更新 package.json 版本号
- 请确认后再继续

### Step 4: 构建与部署
- 执行 /project:deploy production 的逻辑
- 部署后执行冒烟测试

### Step 5: 发布记录
- 更新 CHANGELOG.md
- 创建 Git tag
- 推送到远程仓库

版本类型：$ARGUMENTS（默认：根据变更自动判断）

your-fullstack-project/
├── .claude/
│   ├── commands/
│   │   ├── review.md          # 代码审查
│   │   ├── deploy.md          # 部署流程
│   │   ├── handoff.md         # 交接文档
│   │   ├── release.md         # 发布编排
│   │   ├── next.md            # 任务推荐
│   │   ├── check.md           # 健康检查
│   │   ├── fix.md             # Bug修复向导
│   │   ├── api/
│   │   │   ├── new.md         # 创建API端点
│   │   │   └── test.md        # API测试生成
│   │   ├── db/
│   │   │   ├── migrate.md     # 数据库迁移
│   │   │   └── seed.md        # 测试数据
│   │   └── fe/
│   │       ├── component.md   # 创建组件
│   │       └── page.md        # 创建页面
│   └── settings.json
└── CLAUDE.md

# React 组件生成器

请在项目中创建一个新的 React 组件。

## 规范读取
先读取以下文件了解项目组件规范：
- `src/components/.template/README.md`（如存在）
- `tailwind.config.ts`（了解样式系统）
- `src/components/ui/`（了解已有基础组件）

## 生成规则
1. 使用函数组件 + TypeScript
2. Props 使用 interface 定义，导出 Props 类型
3. 使用 React.forwardRef（如需要）
4. 样式使用 Tailwind CSS，遵循项目设计系统
5. 包含 JSDoc 注释
6. 导出组件为默认导出
7. 在同目录创建 `<ComponentName>.test.tsx` 测试文件
8. 在 `index.ts` 中添加导出

## 组件信息
$ARGUMENTS

格式：`<组件名> - <描述>`
示例：`UserAvatar - 显示用户头像，支持不同尺寸和状态`

# 数据库迁移助手

请创建数据库迁移文件。

## 前置步骤
1. 读取 `prisma/schema.prisma` 了解当前数据模型
2. 读取 `prisma/migrations/` 目录了解已有迁移
3. 确认项目的 ORM 和迁移工具

## 迁移规则
1. 迁移文件必须有明确的描述性名称
2. 新增字段必须有默认值或设为可选（向后兼容）
3. 删除字段前确认没有代码引用
4. 重命名字段使用两步迁移（add → migrate → drop）
5. 包含 rollback 方案
6. 更新 Prisma schema 文件

## 安全检查
- 是否会导致数据丢失？
- 是否需要数据回填？
- 对现有查询的影响？

## 输出
1. 迁移文件内容
2. Schema 变更 diff
3. 需要更新的应用代码
4. 数据回填脚本（如需要）
5. 回滚步骤

迁移描述：$ARGUMENTS

# API 集成测试生成器

请为指定端点生成完整的集成测试。

## 步骤
1. 读取目标路由文件了解端点实现
2. 读取 `tests/` 目录了解项目测试模式
3. 读取 `tests/helpers/` 了解测试工具函数
4. 读取 `prisma/seed.ts` 了解测试数据

## 测试覆盖矩阵
为每个端点生成以下场景的测试：

| 场景类型 | 示例 |
|----------|------|
| 成功路径 | 正确参数 → 200 + 预期响应 |
| 参数验证 | 缺少必填字段 → 400 |
| 权限控制 | 未认证 → 401 / 无权限 → 403 |
| 边界条件 | 空列表、超大输入、特殊字符 |
| 并发冲突 | 重复创建、乐观锁 |
| 数据一致性 | 创建后查询验证 |

## 格式要求
- 使用项目已有的测试框架（Jest/Vitest）
- 使用 describe/it 组织测试
- 每个测试用例包含清晰的描述
- 测试之间互不依赖（独立setup/teardown）

目标端点：$ARGUMENTS

graph LR
    A[发现重复模式] --> B[创建草稿命令]
    B --> C[个人测试验证]
    C --> D{效果如何？}
    D -->|不稳定| B
    D -->|稳定| E[提交到项目]
    E --> F[团队评审]
    F --> G{团队反馈？}
    G -->|需修改| E
    G -->|通过| H[正式纳入版本控制]
    H --> I[定期迭代优化]

    style H fill:#4CAF50,color:#fff

# 在 .gitignore 中排除敏感命令（如有）
# .gitignore
# .claude/commands/local-*   ← 以 local- 开头的命令不提交

# 使用有意义的提交信息
git commit -m "feat(commands): add /project:api/new endpoint generator"
git commit -m "fix(commands): update review.md to include security checklist"
git commit -m "refactor(commands): split deploy.md into check + deploy steps"

flowchart TB
    Start([开始使用自定义命令]) --> Init[初始化 .claude/commands/ 目录]

    Init --> Scope{选择作用域}
    Scope -->|团队共享| Project[创建项目级命令<br/>.claude/commands/*.md]
    Scope -->|个人通用| User[创建用户级命令<br/>~/.claude/commands/*.md]

    Project --> Design[设计命令结构]
    User --> Design

    Design --> Write[编写 Markdown 内容]
    Write --> Test[在 Claude Code 中测试]

    Test --> Result{测试通过？}
    Result -->|No| Refine[优化命令内容]
    Refine --> Test

    Result -->|Yes| Share{分享方式}
    Share -->|项目级| Git[git add .claude/commands/]
    Share -->|用户级| Keep[保留在本地 ~/.claude/]

    Git --> Team[团队成员 git pull]
    Team --> Use[所有人使用 /project:xxx]
    Keep --> Personal[个人在任何项目使用 /user:xxx]

    Use --> Feedback[收集使用反馈]
    Personal --> Feedback
    Feedback --> Iterate[迭代优化命令]
    Iterate --> Write

    style Start fill:#4CAF50,color:#fff
    style Iterate fill:#FF9800,color:#fff