<!-- title: Claude Code自定义命令与团队提示词库全实战 -->

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

## 概述

本教程深入讲解 Claude Code 的 **自定义命令系统**（`.claude/commands/` 目录），教你如何从零构建一套可复用的团队提示词库。学完你将掌握：项目级与用户级命令的作用域管理、`$ARGUMENTS` 模板变量、命令组合模式、以及如何通过 Git 将命令库标准化地分享给整个团队。**适用人群**：已使用 Claude Code 1-2 个月，希望减少重复提示、提升团队协作一致性的中高级开发者。

---

## 前置条件

| 条件 | 说明 |
|------|------|
| Claude Code 版本 | ≥ 1.0.x（2025年6月后发布） |
| Node.js | ≥ 18.x |
| 基础知识 | 熟悉 Markdown 语法、Git 基本操作 |
| 项目经验 | 至少在一个项目中使用过 Claude Code |
| 操作系统 | macOS / Linux / Windows（WSL2） |

确认安装版本：

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

---

## 一、为什么需要自定义命令？

### 1.1 痛点场景

每个开发者都有重复的工作流：

- **代码审查**：每次都要手写"请检查这个文件的性能、安全、可读性……"
- **部署流程**：每次都要回忆"先跑测试、再检查环境变量、再构建……"
- **新人交接**：每次都要重新解释项目架构和编码规范
- **Bug修复**：每次都要描述"请先看日志、定位问题、写测试、修代码……"

这些重复提示不仅浪费时间，还容易遗漏步骤。**自定义命令把重复的工作流压缩成一个单词**。

### 1.2 命令 vs 技能（Skills） vs 插件（Plugins）

很多开发者混淆这三个概念。它们的核心区别如下：

```mermaid
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
```

| 维度 | 自定义命令 | 技能（Skills） | 插件（Plugins） |
|------|-----------|---------------|----------------|
| 文件格式 | `.claude/commands/*.md` | `SKILL.md` | 完整目录结构 |
| 触发方式 | `/project:名称` 手动调用 | 上下文自动匹配 | 多种方式组合 |
| 作用域 | 项目级 / 用户级 | 项目级 / 全局 | 安装即全局 |
| 适合场景 | 标准化工作流 | 领域知识封装 | 完整工具链 |
| 学习成本 | ★☆☆ 低 | ★★☆ 中 | ★★★ 高 |
| 团队共享 | Git 原生支持 | Git 原生支持 | 需发布安装 |

> **本教程聚焦自定义命令**，这是三个扩展机制中最轻量、最容易上手、也最适合团队快速标准化的方案。

---

## 二、命令体系架构

### 2.1 目录结构与作用域

Claude Code 的命令系统有两层作用域：

```
你的开发环境
├── ~/.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
```

**调用规则**：
- 项目级命令：在项目目录内输入 `/project:命令名`
- 用户级命令：在任何位置输入 `/user:命令名`
- 子目录中的命令用 `/` 分隔路径

### 2.2 命令解析流程

```mermaid
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
```

---

## 三、从零创建第一个命令

### 3.1 初始化项目命令目录

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

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

### 3.2 创建第一个命令：`/project:review`

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

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

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

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

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

重点关注文件：$ARGUMENTS
```

> **关键点**：`$ARGUMENTS` 是内置的模板变量，它会捕获你在命令后输入的所有文本。

### 3.3 使用命令

在 Claude Code 会话中：

```
> /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 |
```

### 3.4 常见问题

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| 输入 `/project:review` 提示命令不存在 | 文件路径不对 | 确认在 `.claude/commands/review.md` |
| `$ARGUMENTS` 为空 | 命令后没有跟参数 | 使用 `/project:review 文件路径` |
| 命令内容没生效 | Markdown 格式错误 | 检查是否为纯文本 Markdown |
| 中文乱码 | 文件编码问题 | 确保使用 UTF-8 编码 |

---

## 四、进阶：多参数与条件逻辑

### 4.1 巧用 $ARGUMENTS 实现多参数

`$ARGUMENTS` 是一个原始字符串，你可以在命令内指导 Claude 如何解析：

创建 `.claude/commands/fix.md`：

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

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

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

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

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

使用方式：

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

### 4.2 分层命令设计模式

将复杂工作流拆分为多个原子命令，通过组合实现灵活调用：

```text
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
```

创建 `.claude/commands/check.md`（检查链）：

```markdown
## 项目健康检查

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

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

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

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

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

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

额外关注：$ARGUMENTS
```

---

## 五、用户级命令：跨项目通用工作流

### 5.1 创建用户级命令

用户级命令放在 `~/.claude/commands/` 目录，所有项目都能使用：

```bash
mkdir -p ~/.claude/commands
```

创建 `~/.claude/commands/explain.md`：

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

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

代码/文件路径：$ARGUMENTS

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

在任何项目中使用：

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

### 5.2 推荐的用户级命令集

| 命令 | 文件名 | 用途 |
|------|--------|------|
| `/user:commit` | `commit.md` | 生成规范的 Git 提交信息 |
| `/user:explain` | `explain.md` | 代码原理解释器 |
| `/user:refactor` | `refactor.md` | 安全重构向导 |
| `/user:debug` | `debug.md` | 系统化调试助手 |
| `/user:learn` | `learn.md` | 技术概念学习器 |
| `/user:scaffold` | `scaffold/` | 通用项目脚手架模板 |

创建 `~/.claude/commands/commit.md`：

```markdown
请为当前的代码变更生成 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
```

---

## 六、团队标准化：构建共享命令库

### 6.1 团队命令库架构

这是本教程的核心——如何让整个团队使用同一套命令：

```mermaid
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
```

**设计原则**：
- **项目级命令**（`.claude/commands/`）：团队共享，随项目版本控制
- **用户级命令**（`~/.claude/commands/`）：个人偏好，不进入版本控制

### 6.2 实战：创建团队标准命令集

#### 命令1：代码审查 `/project:review`

`.claude/commands/review.md`：

```markdown
# 代码审查命令

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

## 审查清单

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

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

## 输出格式

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

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

审查目标：$ARGUMENTS
```

#### 命令2：部署检查 `/project:deploy`

`.claude/commands/deploy.md`：

```markdown
# 部署前检查与执行

请执行完整的部署流程。环境：$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. 检查错误日志是否有新增异常

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

#### 命令3：交接文档 `/project:handoff`

`.claude/commands/handoff.md`：

```markdown
# 会话交接文档生成器

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

## 需要包含的信息

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

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

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

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

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

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

额外关注点：$ARGUMENTS
```

### 6.3 将命令纳入版本控制

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

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

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

> **关键优势**：命令文件就是纯 Markdown，天然适合 Git 版本控制。团队成员 `git pull` 后立即可用，零安装成本。

### 6.4 团队命令开发规范

在项目的 `CLAUDE.md` 中添加命令开发规范：

```markdown
## 自定义命令开发规范

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

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

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

---

## 七、高级技巧

### 7.1 命令引用项目文档

命令可以引用项目中已有的文档，实现"活文档"效果：

`.claude/commands/api/new.md`：

```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 - 创建新订单`
```

### 7.2 上下文感知命令

利用 Claude 的代码理解能力，让命令自动感知项目状态：

`.claude/commands/next.md`：

```markdown
# 智能任务推荐

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

## 分析维度
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
```

### 7.3 命令组合：元命令模式

创建一个"元命令"来编排其他命令的执行顺序：

`.claude/commands/release.md`：

```markdown
# 发布流程编排器

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

## 流程

### 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（默认：根据变更自动判断）
```

---

## 八、实战案例：全栈项目命令库

以下是一个完整的全栈 Web 项目命令库，你可以直接复制到项目中使用：

### 8.1 项目结构

```
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
```

### 8.2 前端组件生成器

`.claude/commands/fe/component.md`：

```markdown
# 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 - 显示用户头像，支持不同尺寸和状态`
```

### 8.3 数据库迁移助手

`.claude/commands/db/migrate.md`：

```markdown
# 数据库迁移助手

请创建数据库迁移文件。

## 前置步骤
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
```

### 8.4 API 测试生成器

`.claude/commands/api/test.md`：

```markdown
# API 集成测试生成器

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

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

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

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

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

目标端点：$ARGUMENTS
```

---

## 九、命令维护与演进

### 9.1 命令生命周期管理

```mermaid
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
```

### 9.2 命令质量检查清单

| 检查项 | 通过标准 |
|--------|----------|
| 命名清晰 | 看到 `/project:xxx` 就知道做什么 |
| 作用明确 | 一行描述命令的目的 |
| 输入说明 | `$ARGUMENTS` 的格式和默认值已说明 |
| 输出格式 | 期望的返回格式已定义 |
| 错误处理 | 异常情况的应对策略 |
| 安全约束 | 明确的边界和禁止事项 |
| 文档注释 | 文件头部有简短说明 |
| 实测通过 | 至少手动测试3次不同输入 |

### 9.3 命令版本管理最佳实践

```bash
# 在 .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"
```

---

## 十、完整工作流程图

```mermaid
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
```

---

## 延伸阅读

- [Commands - Claude Code 官方文档](https://code.claude.com/docs/en/commands) — 完整的内置命令参考
- [Extend Claude with skills - Claude Code 官方文档](https://code.claude.com/docs/en/skills) — Skills 系统详解
- [Claude Code Custom Slash Commands Guide - dudarik.com](https://dudarik.com/en/blog/claude-code-custom-slash-commands-skills-guide/) — 命令与 Skills 对比实战
- [Claude Code Cheat Sheet - ComputingForGeeks](https://computingforgeeks.com/claude-code-cheat-sheet/) — 2026 版完整速查表
- [Claude Code Custom Commands - Steve Kinney](https://stevekinney.com/courses/ai-development/claude-code-commands) — 命令开发课程

---

## 参考来源

1. [Commands - Claude Code Docs](https://code.claude.com/docs/en/commands) — Anthropic 官方命令参考文档，涵盖内置命令与自定义命令
2. [Claude Code Custom Slash Commands: /review, /handoff, /release - ClaudeCode Lab](https://claudecode-lab.com/en/blog/claude-code-custom-slash-commands/) — 团队级命令模式的实战案例与最佳实践
3. [How to Build Claude Code Skills That Actually Work - DEV Community](https://dev.to/whoffagents/how-to-build-claude-code-skills-custom-slash-commands-that-actually-work-1nje) — 命令编写技巧与常见错误规避
4. [Custom Commands and Slash Commands - Samanvya Tripathi](https://samanvya.dev/blog/claude-code-custom-commands) — 命令系统架构深度解析
5. [Claude Code Slash Commands Complete Reference 2026 - Learn Prompting](https://learn-prompting.fr/blog/claude-code-slash-commands-reference) — 2026年最新版完整命令参考指南

---

> **训练营适用性评估**：本教程适合 **进阶训练营**（学员已具备 Claude Code 基础使用经验）。预计教学时长 **3-4 小时**，其中讲解 1.5 小时、动手实操 1.5 小时、团队命令库共建练习 1 小时。建议搭配 Git 协作练习，让学员实际体验命令的团队共享流程。

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)