<!-- title: Claude Code自定义命令与Subagent实战 -->

# Claude Code自定义命令与Subagent开发完全实战

**概述**：本教程深入讲解Claude Code两大核心扩展机制——自定义Slash命令和自定义Subagent。从`.claude/commands/`目录的Markdown命令文件编写，到`.claude/agents/`的YAML frontmatter配置，你将学会构建一套完整的个人开发工具箱。适合已掌握Claude Code基本操作、希望提升日常开发效率的中级用户。

**前置条件**：
- 已安装Claude Code CLI并完成API认证
- 熟悉Markdown和YAML基础语法
- 有至少一个Git项目可供实操
- 了解Claude Code基本交互方式（对话、工具调用）

---

## 一、核心概念：命令与智能体的区别

在开始编码之前，必须理解Claude Code扩展体系中三个概念的本质差异：

```mermaid
graph TD
    A[.claude 目录体系] --> B[commands/ 自定义命令]
    A --> C[agents/ 自定义Subagent]
    A --> D[rules/ 模块化规则]
    A --> E[skills/ 技能包]

    B --> B1[用户主动输入 /command-name]
    B --> B2[Markdown纯文本]
    B --> B3[无独立上下文窗口]

    C --> C1[Claude自动委托或 @提及]
    C --> C2[YAML frontmatter + Markdown]
    C --> C3[独立上下文窗口]

    D --> D1[自动加载到系统提示词]
    D --> D2[拆分大CLAUDE.md为小模块]

    E --> E1[条件触发式工作流]
    E --> E2[含SKILL.md的目录结构]

    style B fill:#4A90D9,color:white
    style C fill:#E67E22,color:white
    style D fill:#27AE60,color:white
    style E fill:#8E44AD,color:white
```

| 维度 | 自定义命令 (Commands) | Subagent |
|------|----------------------|----------|
| 触发方式 | 用户手动输入 `/xxx` | Claude自动判断或`@提及` |
| 上下文 | 共享主会话上下文 | 独立上下文窗口 |
| 模型选择 | 跟随主会话模型 | 可指定haiku/sonnet/opus |
| 工具访问 | 继承主会话全部工具 | 可精确控制白名单/黑名单 |
| 适用场景 | 固定步骤的可复用工作流 | 需要隔离的高噪音任务 |
| 文件格式 | 纯Markdown | YAML frontmatter + Markdown |
| 持久记忆 | 无 | 支持user/project/local三级 |

**选择原则**：如果你的工作流是线性的、需要用户交互的、步骤明确的，用命令。如果你的任务是噪音大的、可以并行跑的、只需要最终结论的，用Subagent。

---

## 二、.claude目录完整结构

理解目录结构是一切的基础。Claude Code有两个`.claude`目录：

```
your-project/
├── CLAUDE.md                      # 团队指令（提交到Git）
├── CLAUDE.local.md                # 个人覆盖（gitignore）
└── .claude/
    ├── settings.json              # 权限+配置（提交到Git）
    ├── settings.local.json        # 个人权限覆盖（gitignore）
    ├── .mcp.json                  # MCP服务器配置
    ├── rules/                     # 模块化规则文件
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    ├── commands/                  # 自定义Slash命令
    │   ├── review.md              # → /project:review
    │   ├── deploy.md              # → /project:deploy
    │   └── gsd/                   # 子目录组织
    │       ├── plan.md            # → /project:gsd:plan
    │       └── execute.md         # → /project:gsd:execute
    ├── skills/                    # 自动触发式技能
    │   └── deploy/
    │       └── SKILL.md
    ├── agents/                    # 自定义Subagent定义
    │   ├── code-reviewer.md
    │   ├── security-auditor.md
    │   └── research/
    │       └── docs-explorer.md
    └── hooks/                     # 事件驱动自动化脚本
        └── validate-bash.sh

~/.claude/                          # 全局个人配置（不提交）
├── CLAUDE.md                      # 全局指令
├── settings.json                  # 全局权限
├── commands/                      # 个人命令 → /user:xxx
│   ├── reflect.md
│   └── status.md
├── skills/                        # 个人技能
├── agents/                        # 个人Subagent
└── projects/                      # 会话历史+自动记忆
    └── <project-hash>/
        └── memory/
            └── MEMORY.md
```

**优先级顺序**（从高到低）：
1. 管理策略（IT管理员部署的组织级配置）
2. `--agents` CLI参数（仅当前会话）
3. `.claude/agents/`（项目级）
4. `~/.claude/agents/`（用户级）
5. 插件的`agents/`目录

**Git提交建议**：
```gitignore
# .gitignore
CLAUDE.local.md
.claude/settings.local.json
.claude/agent-memory-local/
```

提交`.claude/commands/`、`.claude/agents/`、`.claude/rules/`到版本控制，团队成员克隆后即可使用。

---

## 三、自定义Slash命令开发

### 3.1 命令的本质：一个Markdown文件

命令的核心理念极其简单：**文件系统就是注册表，文件名就是命令名，文件内容就是实现**。没有构建步骤，没有注册流程，没有编译环节。

### 3.2 创建你的第一个命令

**步骤1：创建命令目录**

```bash
# 全局个人命令（所有项目可用）
mkdir -p ~/.claude/commands

# 项目级命令（仅当前项目可用）
mkdir -p .claude/commands
```

**步骤2：编写命令文件**

创建文件 `~/.claude/commands/reflect.md`：

```markdown
# 反思最近的工作

审查本会话中的近期工作，提取可操作的教训。

## 步骤
1. 运行 `git log -5 --oneline --stat` 查看最近的提交
2. 如有需要，运行 `git diff HEAD~1` 查看最新变更
3. 识别：错误假设、过度工程、遗漏的边界情况、
   失败的方法、有用的模式
4. 用 `save_observation` 保存每条发现，标题加"LESSON:"前缀
5. 用2-3句话总结捕获的内容
```

**步骤3：使用命令**

在Claude Code会话中输入：

```
/reflect
```

Claude读取该文件并按步骤执行。没有其他配置。

### 3.3 命名规则与子目录组织

文件名即命令名，`.md`扩展名被移除：

| 文件路径 | 命令名称 | 作用域 |
|---------|---------|--------|
| `~/.claude/commands/reflect.md` | `/user:reflect` | 全局个人 |
| `.claude/commands/deploy.md` | `/project:deploy` | 当前项目 |
| `~/.claude/commands/gsd/plan.md` | `/user:gsd:plan` | 全局个人 |
| `.claude/commands/gsd/execute.md` | `/project:gsd:execute` | 当前项目 |

子目录用冒号分隔，天然形成命名空间。这种设计让你可以组织大型命令集而不必担心命名冲突。

### 3.4 命令文件的高级写法

命令文件同时是文档和实现。一个好的命令应该包含：

```markdown
# 安全审计

对项目代码进行安全审查，检查OWASP Top 10相关漏洞。

## 检查清单
- [ ] SQL注入：搜索所有数据库查询，检查参数化使用
- [ ] XSS：搜索所有用户输入渲染点，检查转义处理
- [ ] 命令注入：搜索所有exec/spawn调用，检查输入验证
- [ ] 敏感数据泄露：搜索硬编码的密钥、token、密码
- [ ] 不安全的依赖：运行 `npm audit` 或 `pip audit`
- [ ] CORS配置：检查跨域策略是否过于宽松
- [ ] 认证缺陷：检查JWT实现、session管理

## 执行步骤
1. 使用 Grep 工具搜索 `eval(`、`innerHTML`、`exec(`、`password`、
   `secret`、`api_key` 等关键词
2. 检查 .env 文件是否在 .gitignore 中
3. 运行依赖审计命令
4. 检查认证中间件实现
5. 按严重程度分类输出报告

## 输出格式
按以下结构输出：
- 🔴 严重：可直接被利用的漏洞
- 🟡 警告：潜在风险，需要评估
- 🟢 建议：安全最佳实践建议
```

### 3.5 实战：GSD命令套件

GSD（Get Stuff Done）是一套完整的项目管理命令集。以下是核心命令的实现：

**`~/.claude/commands/gsd/new-project.md`**：

```markdown
# 初始化新项目

深度收集上下文后初始化项目，而非简单地创建目录结构。

## 步骤
1. 研究现有代码库，映射依赖关系
2. 识别集成点和技术约束
3. 在开始实现前，向用户提出澄清问题
4. 创建 PROJECT.md 作为项目唯一真相来源
5. 包含：架构决策、技术栈、模块划分、里程碑

## 关键原则
- 不做假设，先问再做
- 理解现有系统再规划新功能
- 记录每一个架构决策的理由
```

**`~/.claude/commands/gsd/debug.md`**：

```markdown
# 系统化调试

用科学方法替代随机试错。

## 调试流程
1. **观察**：精确描述异常行为，收集错误日志
2. **假设**：基于证据提出1-3个可能原因
3. **测试**：设计最小实验验证每个假设
4. **结论**：记录哪些假设被证实/推翻
5. **修复**：基于验证结果实施最小化修复

## 输出要求
- 每次只测试一个变量
- 记录每个实验的输入、预期、实际结果
- 如果3轮假设未解决，暂停并重新审视问题定义
```

### 3.6 常见问题与解决方案

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 输入`/xxx`后无反应 | 文件路径或命名错误 | 检查`.claude/commands/xxx.md`是否存在 |
| 命令执行偏离预期 | 指令过于宽泛 | 添加具体的步骤和输出格式要求 |
| 项目命令不可见 | 在错误目录启动 | 确保在项目根目录启动Claude Code |
| 子目录命令无法识别 | 子目录嵌套过深 | Claude Code递归扫描，确认文件名无空格 |
| 命令结果不一致 | Markdown指令歧义 | 使用编号步骤代替散文描述 |

---

## 四、自定义Subagent开发

### 4.1 Subagent的核心价值

Subagent的关键优势是**上下文隔离**。当主会话变成一堆日志、grep输出和死胡同研究的垃圾场时，Subagent把噪音工作移到独立窗口，只返回干净的结论。

```mermaid
graph LR
    subgraph 主会话
        A[用户指令] --> B[Claude主线程]
    end

    B -->|委托| C[Subagent A<br/>代码审查]
    B -->|委托| D[Subagent B<br/>文档研究]
    B -->|委托| E[Subagent C<br/>测试运行]

    C -->|返回摘要| B
    D -->|返回摘要| B
    E -->|返回摘要| B

    style C fill:#E67E22,color:white
    style D fill:#3498DB,color:white
    style E fill:#2ECC71,color:white
```

### 4.2 方法一：使用/agents命令（推荐新手）

这是最简单的创建方式：

**步骤1**：在Claude Code中运行：
```
/agents
```

**步骤2**：切换到"Library"标签，选择"Create new agent"

**步骤3**：选择作用域：
- **Personal**：保存到`~/.claude/agents/`，所有项目可用
- **Project**：保存到`.claude/agents/`，仅当前项目

**步骤4**：选择"Generate with Claude"，描述你的Subagent：
```
一个代码改进Agent，扫描文件并建议可读性、
性能和最佳实践方面的改进。它应该解释每个
问题，展示当前代码，并提供改进版本。
```

**步骤5**：选择工具（只读审查取消选择写入工具）

**步骤6**：选择模型（代码审查推荐Sonnet，快速探索推荐Haiku）

**步骤7**：选择颜色（UI中区分不同Agent）

**步骤8**：配置记忆（选择User scope启用跨会话学习）

**步骤9**：保存并测试：
```
用code-improver Agent来建议改进这个项目
```

### 4.3 方法二：手动编写Subagent文件

创建文件 `.claude/agents/code-reviewer.md`：

```yaml
---
name: code-reviewer
description: Reviews code for quality, security, and best practices. Use after code changes or before commits.
tools: [Read, Glob, Grep, Bash]
disallowedTools: [Edit, Write]
model: sonnet
permissionMode: plan
memory: project
color: "#E67E22"
---

你是一位高级代码审查专家。分析代码时遵循以下原则：

## 审查维度

### 代码质量
- 命名是否清晰表达意图
- 函数是否保持单一职责（<30行）
- 嵌套层级是否超过3层
- 是否存在重复代码可以抽取

### 安全性
- 输入验证是否充分
- 是否存在注入风险
- 敏感数据处理是否安全
- 认证授权是否正确实现

### 可维护性
- 错误处理是否完善
- 日志是否足够但不冗余
- 类型定义是否精确
- 依赖关系是否合理

## 输出格式

对每个发现的问题：
1. **位置**：文件路径:行号
2. **类别**：质量/安全/性能/可维护性
3. **严重程度**：🔴严重 🟡警告 🟢建议
4. **当前代码**：问题代码片段
5. **改进建议**：修改后的代码和理由

最后给出总体评分（1-10）和最重要的3个改进建议。
```

### 4.4 Frontmatter字段全解

| 字段 | 必填 | 说明 | 示例 |
|------|------|------|------|
| `name` | 是 | 唯一标识符，小写+连字符 | `code-reviewer` |
| `description` | 是 | 何时委托给此Agent | `"Reviews code for quality issues"` |
| `tools` | 否 | 可用工具白名单 | `[Read, Grep, Glob]` |
| `disallowedTools` | 否 | 工具黑名单 | `[Edit, Write, Bash]` |
| `model` | 否 | 使用的模型 | `haiku`/`sonnet`/`opus`/`inherit` |
| `permissionMode` | 否 | 权限模式 | `default`/`plan`/`auto` |
| `maxTurns` | 否 | 最大交互轮数 | `10` |
| `skills` | 否 | 预加载的技能 | `[security-review]` |
| `mcpServers` | 否 | 可用的MCP服务器 | `["slack", "github"]` |
| `hooks` | 否 | 生命周期钩子 | 参见Hooks文档 |
| `memory` | 否 | 持久记忆范围 | `user`/`project`/`local` |
| `background` | 否 | 后台运行 | `true`/`false` |
| `isolation` | 否 | 隔离模式 | `worktree` |
| `color` | 否 | UI显示颜色 | `"#E67E22"` |

### 4.5 模型选择策略

```mermaid
graph TD
    A[任务类型判断] --> B{需要深度推理？}
    B -->|是| C[opus]
    B -->|否| D{需要代码修改？}
    D -->|是| E[sonnet]
    D -->|否| F{响应速度关键？}
    F -->|是| G[haiku]
    F -->|否| E

    H[示例场景] --> I[代码审查 → sonnet]
    H --> J[快速搜索 → haiku]
    H --> K[架构设计 → opus]
    H --> L[文档研究 → haiku]
    H --> M[安全审计 → sonnet]
```

**关键原则**：
- `haiku`：只读探索、快速搜索、简单分析（成本最低，速度最快）
- `sonnet`：代码审查、测试运行、中等复杂度任务（平衡性价比）
- `opus`：架构设计、复杂重构、高难度问题（最高能力，最贵）
- `inherit`：继承主会话模型（默认值）

---

## 五、实战案例：构建完整开发工具箱

以下是一个完整的、可直接使用的开发工具箱配置。

### 5.1 项目结构

```
my-project/
├── CLAUDE.md
├── .claude/
│   ├── commands/
│   │   ├── review.md           # 代码审查命令
│   │   ├── security-check.md   # 安全检查命令
│   │   ├── test-coverage.md    # 测试覆盖率命令
│   │   └── deploy/
│   │       ├── staging.md      # 部署到staging
│   │       └── production.md   # 部署到production
│   ├── agents/
│   │   ├── code-reviewer.md    # 代码审查Agent
│   │   ├── security-auditor.md # 安全审计Agent
│   │   └── test-runner.md      # 测试运行Agent
│   └── rules/
│       ├── code-style.md       # 代码风格规则
│       └── testing.md          # 测试规则
```

### 5.2 CLAUDE.md配置

```markdown
# My Project

## 常用命令
- `npm run dev` — 启动开发服务器 (端口3000)
- `npm test` — 运行测试套件 (Vitest)
- `npm run lint` — 代码检查 (ESLint + Prettier)
- `npm run build` — TypeScript编译

## 架构
- Next.js 15 App Router + TypeScript
- 数据层：Prisma ORM + PostgreSQL
- API路由在 `src/app/api/`
- 组件在 `src/components/`
- 测试镜像 `src/` 结构在 `tests/`

## 约定
- 所有API响应格式：`{ data, error, meta }`
- 组件使用函数式 + hooks
- 禁止使用 `any` 类型
- 提交前必须通过lint和测试
```

### 5.3 审查命令 `.claude/commands/review.md`

```markdown
# 代码审查

对当前Git暂存区的变更进行完整审查。

## 步骤
1. 运行 `git diff --cached` 查看暂存变更
2. 运行 `git diff` 查看未暂存变更
3. 运行 `npm run lint` 检查代码规范
4. 运行 `npm test` 执行相关测试
5. 基于以下维度评估变更：
   - 代码质量和可读性
   - 潜在Bug和边界情况
   - 安全漏洞
   - 性能影响
   - 测试覆盖是否充分

## 输出格式
- 🟢 可以合并
- 🟡 需要小幅修改（列出具体建议）
- 🔴 需要重大修改（列出阻塞问题）

如果需要深度审查，建议使用 @code-reviewer Agent。
```

### 5.4 安全审计Agent `.claude/agents/security-auditor.md`

```yaml
---
name: security-auditor
description: Scans code for security vulnerabilities following OWASP Top 10. Use proactively before releases and after auth-related changes.
tools: [Read, Glob, Grep, Bash]
disallowedTools: [Edit, Write]
model: sonnet
permissionMode: plan
memory: project
color: "#E74C3C"
---

你是一位应用安全专家。对代码进行系统化安全审计。

## 扫描范围

### 注入攻击
- 搜索所有数据库查询，检查参数化使用
- 搜索 `eval(`、`exec(`、`spawn(`、`child_process`
- 检查用户输入是否直接拼接到命令中

### 身份认证
- JWT实现是否正确（算法、密钥管理、过期处理）
- Session管理是否安全
- 密码存储是否使用bcrypt/argon2

### 敏感数据
- 搜索硬编码的密钥：`password`、`secret`、`api_key`、`token`
- 检查 `.env` 文件是否在 `.gitignore` 中
- 验证HTTPS在传输层的强制使用

### CORS与CSRF
- 跨域策略是否限制来源
- CSRF Token是否正确实现

### 依赖安全
- 运行 `npm audit`（Node.js）或 `pip audit`（Python）
- 检查是否使用了已知有漏洞的版本

## 输出格式

```
## 安全审计报告

### 执行摘要
- 审计范围：[文件数]个文件
- 发现问题：🔴 [严重] 🟡 [警告] 🟢 [建议]

### 严重问题
1. [文件:行号] 问题描述 + 修复方案

### 警告
1. [文件:行号] 问题描述 + 建议方案

### 改进建议
1. 建议内容

### 整体评分：X/10
```
```

### 5.5 测试运行Agent `.claude/agents/test-runner.md`

```yaml
---
name: test-runner
description: Runs tests, analyzes failures, and suggests fixes. Use when tests fail or before committing changes.
tools: [Read, Glob, Grep, Bash]
disallowedTools: [Edit, Write]
model: haiku
maxTurns: 15
color: "#2ECC71"
---

你是一位测试工程师。专注于运行测试和分析失败原因。

## 工作流程
1. 识别最近的代码变更（git diff）
2. 确定需要运行的测试范围
3. 执行相关测试套件
4. 如果测试通过，报告成功
5. 如果测试失败：
   a. 读取失败的测试文件
   b. 读取被测试的源文件
   c. 分析失败原因（断言错误、异常、超时）
   d. 建议具体的修复方案

## 输出格式
- 测试结果摘要：通过/失败/跳过数量
- 失败测试的根因分析
- 建议的修复步骤（按优先级排列）
```

### 5.6 使用流程

```mermaid
sequenceDiagram
    participant U as 开发者
    participant CC as Claude Code
    participant CR as code-reviewer
    participant SA as security-auditor
    participant TR as test-runner

    U->>CC: /review
    CC->>CC: 读取 .claude/commands/review.md
    CC->>TR: 委托运行测试
    TR-->>CC: 测试通过，覆盖率92%
    CC->>CR: 委托代码审查
    CR-->>CC: 发现2个警告，3个建议
    CC->>SA: 委托安全审计
    SA-->>CC: 无严重问题，1个建议
    CC-->>U: 综合报告：🟡 需要小幅修改

    Note over U,CC: 开发者也可以直接@指定Agent
    U->>CC: @security-auditor 检查新的认证模块
    CC->>SA: 直接委托
    SA-->>CC: 审计结果
    CC-->>U: 安全审计报告
```

---

## 六、Rules模块化规则

当CLAUDE.md超过200行时，Claude的指令遵循度会下降。Rules系统解决了这个问题——将大CLAUDE.md拆分为小模块。

### 6.1 规则文件结构

创建 `.claude/rules/code-style.md`：

```markdown
# 代码风格规则

## TypeScript
- 严格模式：always
- 优先使用 `interface` 而非 `type` 定义对象
- 使用 `unknown` 而非 `any` 处理未知类型
- 枚举使用 `const enum` 或字符串联合类型

## React
- 函数式组件，禁止class组件
- Props使用interface定义
- 使用 `useCallback` 包装事件处理器
- 自定义Hook以 `use` 开头

## 命名约定
- 文件：kebab-case（`user-profile.tsx`）
- 组件：PascalCase（`UserProfile`）
- 函数/变量：camelCase
- 常量：UPPER_SNAKE_CASE
- CSS类：使用CSS Modules或Tailwind
```

创建 `.claude/rules/testing.md`：

```markdown
# 测试规则

## Vitest配置
- 测试文件与源文件同目录，命名为 `*.test.ts`
- 使用 `describe`/`it` 组织测试
- Mock外部依赖，不Mock内部模块

## 覆盖率要求
- 核心业务逻辑：≥90%
- API路由：≥80%
- UI组件：≥60%（侧重交互逻辑）

## 测试结构
遵循 AAA 模式：
1. Arrange：设置测试数据和前置条件
2. Act：执行被测试的操作
3. Assert：验证结果符合预期
```

### 6.2 规则加载机制

Rules文件在每次会话启动时自动加载到系统提示词中。它们与CLAUDE.md的内容合并，Claude看到的是一份统一的指令集。不需要手动引用——放在`.claude/rules/`目录下就自动生效。

---

## 七、命令与Subagent协同模式

### 7.1 命令作为入口，Subagent作为执行者

最佳实践是让命令充当"指挥官"，在需要时委托给专门的Subagent：

```markdown
<!-- .claude/commands/full-review.md -->
# 全面审查

执行完整的代码审查流程。

## 步骤
1. 运行 `npm run lint` 检查代码规范
2. 如果lint通过，使用 @test-runner 运行测试
3. 如果测试通过，使用 @code-reviewer 审查代码质量
4. 使用 @security-auditor 进行安全扫描
5. 汇总所有Agent的报告，给出综合评分

## 注意
- 如果任何步骤失败，报告失败原因并建议修复
- 不要在主线程中做大量文件搜索，委托给Agent
```

### 7.2 后台并行执行

对于可以并行跑的Agent，设置`background: true`：

```yaml
---
name: parallel-research
description: Research multiple topics in parallel using background agents.
background: true
model: haiku
tools: [Read, Glob, Grep, Bash]
---

研究以下主题并返回摘要：
- 项目使用的框架版本和已知问题
- 类似项目中的常见模式
- 性能优化的最佳实践
```

### 7.3 Worktree隔离执行

当并行修改可能冲突时，使用`isolation: worktree`：

```yaml
---
name: refactor-worker
description: Performs code refactoring in an isolated worktree to avoid conflicts.
isolation: worktree
model: sonnet
tools: [Read, Edit, Write, Glob, Grep, Bash]
permissionMode: auto
---
```

---

## 八、调试与排错

### 8.1 Subagent不被触发

**症状**：你创建了Agent但Claude从不自动委托给它。

**原因**：`description`字段不够明确。

**修复**：使用动作导向的语言描述。对比：

```yaml
# ❌ 弱描述——Claude不知道何时使用
description: A code review agent.

# ✅ 强描述——触发条件明确
description: Reviews code for quality, security, and best practices. Use proactively after code changes or before commits.
```

### 8.2 Subagent使用了不该用的工具

**症状**：只读Agent尝试编辑文件。

**修复**：同时使用`tools`白名单和`disallowedTools`黑名单：

```yaml
tools: [Read, Glob, Grep]        # 只允许这三个
disallowedTools: [Edit, Write, Bash]  # 明确禁止写入
```

### 8.3 Agent上下文溢出

**症状**：Agent运行一段时间后开始"压缩"或丢失信息。

**修复**：
1. 设置`maxTurns`限制交互轮数（如`maxTurns: 10`）
2. 使用`model: haiku`降低成本和上下文消耗
3. 在提示词中要求"只返回摘要，不返回原始数据"

### 8.4 新创建的Agent不生效

**原因**：磁盘上的Agent文件在会话启动时加载。

**修复**：
- 通过`/agents`界面创建的Agent立即生效
- 手动创建的文件需要重启会话
- 或者在会话中使用`/agents`刷新Agent列表

---

## 九、团队协作最佳实践

### 9.1 项目级配置提交策略

```bash
# 提交到Git的文件（团队共享）
git add .claude/commands/
git add .claude/agents/
git add .claude/rules/
git add .claude/settings.json
git add CLAUDE.md

# 不提交的文件（个人配置）
echo "CLAUDE.local.md" >> .gitignore
echo ".claude/settings.local.json" >> .gitignore
echo ".claude/agent-memory-local/" >> .gitignore
```

### 9.2 命令与Agent的命名规范

团队应统一命名规范以避免混乱：

| 类型 | 命名规范 | 示例 |
|------|---------|------|
| 命令 | 动词或动词短语 | `/review`、`/deploy`、`/test-coverage` |
| Agent | 名词，描述角色 | `code-reviewer`、`security-auditor` |
| 命名空间 | 子目录组织 | `/gsd:plan`、`/deploy:staging` |

### 9.3 文档化你的Agent

在项目的README或CONTRIBUTING中记录：

```markdown
## Claude Code配置

本项目包含以下自定义配置：

### 命令
- `/review` — 审查暂存区变更
- `/deploy:staging` — 部署到staging环境

### Subagents
- `code-reviewer` — 代码质量和最佳实践审查
- `security-auditor` — OWASP安全审计
- `test-runner` — 测试执行和失败分析

### 使用建议
提交前运行 `/review` 获取完整审查报告。
```

---

## 十、性能与成本优化

### 10.1 模型路由策略

```mermaid
graph TD
    A[任务到达] --> B{需要修改代码？}
    B -->|否，只读| C{复杂分析？}
    B -->|是| D{高难度重构？}
    C -->|否| E[haiku 成本$0.25/M token]
    C -->|是| F[sonnet 成本$3/M token]
    D -->|否| F
    D -->|是| G[opus 成本$15/M token]

    style E fill:#2ECC71,color:white
    style F fill:#F39C12,color:white
    style G fill:#E74C3C,color:white
```

### 10.2 成本对比实例

以"审查一个50文件的项目"为例：

| 方案 | 模型 | 预估Token | 预估成本 |
|------|------|----------|---------|
| 主会话直接审查 | opus | ~200K | ~$3.00 |
| Subagent(sonnet)审查 | sonnet | ~150K | ~$0.45 |
| Subagent(haiku)快速扫描 | haiku | ~100K | ~$0.025 |

**结论**：将审查工作委托给`haiku`模型的Subagent，成本降低120倍，同时保护主会话上下文不被审查日志污染。

### 10.3 上下文节省

Subagent最大的隐性价值不是模型成本，而是**主会话上下文空间的节省**。一个长会话中，大量文件读取、grep结果、测试输出会迅速填满上下文窗口。一旦触发压缩（compaction），之前的对话质量会下降。Subagent把噪音工作隔离到独立窗口，主会话只保留结论和决策。

---

## 延伸阅读

- [Claude Code官方文档：Create custom subagents](https://code.claude.com/docs/en/sub-agents) — Anthropic官方Subagent完整参考
- [Claude Code .claude Directory Guide](https://computingforgeeks.com/claude-code-dot-claude-directory-guide/) — .claude目录结构与配置全解
- [Builder.io: Claude Code Subagents Guide](https://www.builder.io/blog/claude-code-subagents) — 创建、使用和调试Subagent的实践指南
- [Custom Commands and Slash Commands](https://samanvya.dev/blog/claude-code-custom-commands) — 命令开发的深度实战教程
- [Claude Code Best Practices: 15 Tips from 6 Projects](https://aiorg.dev/blog/claude-code-best-practices) — 生产项目中的最佳实践汇总

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| 适合训练营类型 | AI编程工具实战营、团队工程化训练营、Claude Code深度用户训练营 |
| 预计教学时长 | 4-6小时（含实操练习） |
| 难度等级 | 中级（需具备Claude Code基础使用经验） |
| 实操占比 | 70%（大量动手创建命令和Agent） |
| 最佳分组方式 | 2-3人一组，每组一个真实项目 |
| 结业产出 | 每人拥有一套可复用的个人命令+Agent工具箱 |

> [!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)