# SuperClaude 用户指南 🚀

## 🎯 简单真相

**在表面复杂性背后，SuperClaude 实际上很简单易用。**

您不需要学习所有命令、标志和角色。只需开始使用它！🎈

SuperClaude 有一个**智能路由系统**，试图弄清楚您需要什么：
- 输入 `/analyze some-code/` → 它选择正确的分析工具
- 询问安全问题 → 安全专家自动激活
- 处理前端 → UI 专家接管
- 调试某些东西 → 调查模式启动

**学习在使用中产生** - 您会自然地发现什么有效，而无需首先研究手册。

下面的详细指南？它们在您想要理解刚刚发生的事情或深入了解时存在。但说实话？大多数时候您可以直接尝试。😊

---

**TL;DR**：安装它，在您的代码上尝试 `/analyze` 或 `/build`，观看魔法发生。

---

SuperClaude v3.0 理解和使用的综合指南。但请记住 - 您可以直接跳到尝试使用！

## 目录 📖

1. [欢迎和概述](#欢迎和概述-)
2. [核心组件](#核心组件-)
3. [三种操作模式](#三种操作模式-)
4. [编排器系统](#编排器系统-)
5. [规则和原则](#规则和原则-)
6. [入门工作流程](#入门工作流程-)
7. [集成和协调](#集成和协调-)
8. [实用示例](#实用示例-)
9. [技巧和最佳实践](#技巧和最佳实践-)
10. [故障排除](#故障排除-常见问题-)
11. [下一步](#下一步-)

---

## 🚀 从这里开始

**想跳过阅读直接开始？** 这是您的 2 分钟入门：

```bash
# 在 Claude Code 中尝试这些命令：
/sc:help                    # 查看可用内容
/sc:analyze README.md       # SuperClaude 分析您的项目
/sc:workflow feature-prd.md # 从 PRD 生成实施工作流程（NEW！）
/sc:implement user-auth     # 创建功能和组件（v3 中的新功能！）
/sc:build                   # 智能构建与自动优化
/sc:improve messy-file.js   # 自动清理代码
```

**刚刚发生了什么？** SuperClaude 自动：
- 为每个任务选择正确工具 🛠️
- 激活适当专家（安全、性能等）🎭
- 应用智能标志和优化 ⚡
- 提供基于证据的建议 📊

**看到这有多容易了吗？** 无需学习 - SuperClaude 弄清楚复杂性，因此您不必。

想了解它如何工作？继续阅读。想继续实验？去吧！🎯

---

## 欢迎和概述 👋

### SuperClaude 到底是什么？🤔

SuperClaude 让 Claude Code 对开发工作更聪明。您得到的不是通用响应，而是来自不同专家（安全、性能、前端等）的专业帮助，他们了解自己的事情。

**诚实的真相**：我们刚刚发布了 v3.0，它刚从 beta 出来。它在做的事情上效果很好，但当我们在继续改进时，您应该预期会有一些粗糙边缘。我们构建这个是因为我们希望 Claude Code 对真实软件开发工作流程更有帮助。

**巧妙的部分？** 您不需要管理任何这种复杂性。只需使用像 `/analyze` 或 `/build` 这样的正常命令，SuperClay 通常会弄清楚涉及哪些专家和使用什么工具。🪄

### SuperClaude 添加了什么 ✨

**🛠️ 17 个专业命令**
- 规划工具：`/workflow`（NEW！）、`/estimate`、`/task`
- 开发工具：`/implement`、`/build`、`/design`
- 分析工具：`/analyze`、`/troubleshoot`、`/explain`
- 质量工具：`/improve`、`/cleanup`、`/test`
- 以及文档、git、部署等实用工具
- **您只需使用它们** - SuperClaude 自动处理复杂性
- **NEW**：`/workflow` 命令用于 PRD 到实施规划
- **NEW**：`/implement` 命令用于功能创建（恢复 v2 功能）

**🎭 11 个智能角色** *（知道何时介入）*
- AI 专家为不同领域调整行为
- **基于您的请求自动激活**（安全任务的安全专家等）
- 提供手动控制，但通常不需要
- 将其视为拥有一个知道何时帮助的整个开发团队

**🔧 MCP 服务器集成** *（智能外部工具）*
- Context7：官方库文档查找
- Sequential：复杂多步分析
- Magic：现代 UI 组件生成
- Playwright：浏览器自动化和测试
- **在需要时自动连接** - 您不管理这些东西

**📋 增强任务管理** *（在幕后发生）*
- 使用 TodoWrite/TodoWrite 进行进度跟踪
- 使用 `/task` 进行多会话项目管理
- 使用 `/spawn` 进行复杂编排
- 使用 `/loop` 进行迭代改进
- **主要是自动的** - SuperClay 跟踪您正在做的事情

**⚡ 令牌优化** *（智能效率）*
- 当上下文变满时智能压缩
- 高效通信的符号系统
- 大操作的性能优化
- **通常在需要时激活** 对于大型项目

### 当前状态（v3.0）📊

**✅ 运行良好的部分：**
- 安装系统（完全重写，更可靠）
- 带有 16 个命令和 11 个角色的核心框架
- MCP 服务器集成（大部分工作）
- 基本任务管理和工作流程自动化
- 文档和用户指南

**⚠️ 仍然粗糙的部分：**
- 这是初始版本 - 预期会有错误
- 某些 MCP 集成可能更顺畅
- 并非所有操作的性能都已优化
- 某些高级功能处于实验阶段

**❌ 我们移除的内容：**
- Hooks 系统（变得过于复杂，v4 中回归）

我们对 v3 作为基础相当满意，但绝对有改进空间。

### 它如何工作 🔄

**简单版本**：您输入类似 `/analyze auth.js` 的内容，SuperClaude 会弄清楚其余部分。

**稍微详细的版本**：

1. **智能路由** - 分析您要求什么
2. **自动专家选择** - 选择正确的专家（安全、性能等）
3. **工具协调** - 在有用时连接到外部系统
4. **质量保证** - 确保建议是可靠的

**您看不到任何这种复杂性** - 它只是感觉像 Claude 在开发方面变得更聪明了。

好处是大多数时候这通常会自动发生。您提出请求，SuperClaude 尝试弄清楚好方法，并用适当的工具和专业知识执行。通常不需要配置或设置 - 只是希望有更好的结果。✨

### 快速功能概览 🎯

| 组件 | 功能 | 了解更多（可选！）|
|-----------|--------------|------------|
| **命令** | 15 个自动激活的专业工具 | [命令指南](commands-guide.md) |
| **标志** | 大多自动激活的修饰符 | [标志指南](flags-guide.md) |
| **角色** | 知道何时帮助的 11 个 AI 专家 | [角色指南](personas-guide.md) |
| **MCP 服务器** | 在有用时连接的外部集成 | [本指南](#核心组件-🧩) |
| **模式** | 3 个不同工作流程的操作模式 | [本指南](#三种操作模式-🎭) |
| **编排器** | 使一切工作的智能路由 | [本指南](#编排器系统-🎯) |

**记住**：您可以在不阅读任何这些指南的情况下有效使用 SuperClaude。当您对其工作原理感到好奇时，它们就在这里！🎪

---

## 核心组件 🧩

SuperClaude 由几个协同工作的互连系统构建。这里是每个组件如何适应更大的图景。

### 命令：您的工具包 🛠️

命令是处理特定类型开发工作的专业工具。您得到的不是通用的"帮助我处理这个"，而是针对不同场景的目的构建工具。

**按目的组织的 15 个命令：**

**开发** 🔨
- `/build` - 项目构建、编译、打包
- `/design` - 系统架构和组件设计

**分析** 🔍
- `/analyze` - 全面的代码和系统分析
- `/troubleshoot` - 问题调查和调试
- `/explain` - 教育解释和学习

**质量** ✨
- `/improve` - 代码增强和优化
- `/cleanup` - 技术债务减少
- `/test` - 测试和覆盖率分析

**实用工具** 🔧
- `/document` - 文档创建
- `/git` - 增强 git 工作流程
- `/load` - 项目上下文加载
- `/estimate` - 项目估算
- `/task` - 长期项目管理
- `/spawn` - 复杂操作编排
- `/index` - 命令导航和帮助

每个命令都有自己的标志，自动激活适当的角色，并与相关的 MCP 服务器集成。有关详细示例和使用模式，请参阅[命令指南](commands-guide.md)。

### 标志：行为修饰符 🏁

标志改变 SuperClaude 处理您请求的方式。它们就像修改行为、添加能力或改变输出样式的命令行选项。

**关键标志类别：**

**规划和分析** 🧠
- `--think` / `--think-hard` / `--ultrathink` - 控制思考深度
- `--plan` - 运行前显示执行计划

**效率和控制** ⚡
- `--uc` - 大操作的超压缩输出
- `--safe-mode` - 带验证的保守执行
- `--validate` - 操作前风险评估

**MCP 服务器控制** 🔧
- `--c7` - 启用 Context7 用于文档
- `--seq` - 启用 Sequential 用于复杂分析
- `--magic` - 启用 Magic 用于 UI 组件
- `--play` - 启用 Playwright 用于测试

**高级编排** 🎭
- `--delegate` - 启用子代理委派进行并行处理
- `--wave-mode` - 带复合智能的多阶段执行
- `--loop` - 迭代改进模式

**焦点和范围** 🎯
- `--focus security` - 关注特定域
- `--scope project` - 设置分析范围
- `--persona-[name]` - 激活特定角色

标志通常基于上下文自动激活。例如，安全相关请求通常获得 `--persona-security` 和 `--focus security`。有关全面详细信息和模式，请参阅[标志指南](flags-guide.md)。

### 角色：AI 专家 🎭

角色就像按需拥有专家团队。每个带来不同的专业知识、优先级和问题方法。

**按域组织的 11 个角色：**

**技术专家** 🔧
- 🏗️ **architect** - 系统设计、长期架构
- 🎨 **frontend** - UI/UX、可访问性、前端性能
- ⚙️ **backend** - API、数据库、可靠性
- 🛡️ **security** - 威胁建模、漏洞
- ⚡ **performance** - 优化、瓶颈消除

**流程和质量** ✨
- 🔍 **analyzer** - 根因分析、调查
- 🧪 **qa** - 测试、质量保证
- 🔄 **refactorer** - 代码质量、技术债务
- 🚀 **devops** - 基础设施、部署

**知识和沟通** 📚
- 👨‍🏫 **mentor** - 教育、知识转移
- ✍️ **scribe** - 文档、技术写作

角色通常基于请求模式自动激活，但您可以使用 `--persona-[name]` 标志覆盖。每个都有不同的优先级（例如，安全角色优先考虑安全性而非速度）。有关详细描述和示例，请参阅[角色指南](personas-guide.md)。

### MCP 服务器：外部能力 🔧

MCP（模型上下文协议）服务器提供超出 Claude 本机能力的特殊能力。

**4 个集成服务器：**

**Context7** 📚
- **目的**：官方库文档和最佳实践
- **何时激活**：框架问题、外部库使用
- **提供什么**：最新文档、代码示例、模式
- **示例**：`/build react-app --c7` 获取 React 最佳实践

**Sequential** 🧠
- **目的**：复杂多步分析和系统思维
- **何时激活**：调试、系统设计、`--think` 标志
- **提供什么**：结构化问题解决、假设测试
- **示例**：`/troubleshoot "auth randomly fails" --seq`

**Magic** ✨
- **目的**：现代 UI 组件生成和设计系统
- **何时激活**：UI 组件请求、前端工作
- **提供什么**：React/Vue/Angular 组件、设计模式
- **示例**：`/build dashboard --magic` 创建现代 UI 组件

**Playwright** 🎭
- **目的**：浏览器自动化、E2E 测试、性能监控
- **何时激活**：测试工作流程、性能分析
- **提供什么**：跨浏览器测试、可视化验证、指标
- **示例**：`/test e2e --play` 运行全面浏览器测试

MCP 服务器通常自动协调，但您可以使用 `--all-mcp`、`--no-mcp` 或特定标志（如 `--c7`）控制它们。

### 组件如何协同工作 🤝

当组件协调时就很巧妙：

**示例：安全分析请求**
```bash
/sc:analyze auth-system/ --focus security
```

**通常发生的情况：**
1. **命令**：`/analyze` 处理代码分析
2. **标志**：`--focus security` 引导注意力
3. **角色**：🛡️ 安全专家自动激活
4. **MCP**：Sequential 提供系统分析
5. **编排器**：路由一切以实现最佳执行

**结果**：具有威胁建模视角、系统方法论和全面覆盖的安全聚焦分析。

这种协调通常为大多数请求发生 - SuperClaude 尝试为您的特定需求找出工具和专业知识的良好组合。

---

## 三种操作模式 🎭

SuperClaude 以三种不同的模式运行，优化开发工作流程的不同方面。了解这些模式有助于您充分利用框架。

### 任务管理模式 📋

**它是什么**：带进度跟踪和验证的结构化工作流程执行。

**何时使用**：任何需要跟踪和协调的多步操作。

**它如何工作**：SuperClaude 将工作分解为可管理任务，跟踪进度，并通过验证门确保质量。

#### 任务管理的四个层次

**层次 1：会话任务（TodoWrite/TodoWrite）**
- **范围**：当前 Claude Code 会话
- **容量**：每会话 3-20 个任务
- **状态**：待处理 📋、进行中 🔄、完成 ✅、阻塞 🚧
- **使用**：即时工作的实时进度跟踪

```bash
# SuperClaude 通常创建和管理会话任务
/sc:build large-project/
# → 创建："分析项目结构"、"运行构建过程"、"验证输出"
```

**层次 2：项目任务（/task 命令）**
- **范围**：多会话功能（几天到几周）
- **结构**：分层（史诗 → 故事 → 任务）
- **持久性**：跨会话状态管理
- **使用**：长期功能开发

```bash
/sc:task create "implement user dashboard" --priority high
/sc:task breakdown "payment integration"
/sc:task status  # 检查当前项目任务
```

**层次 3：复杂编排（/spawn 命令）**
- **范围**：复杂多域操作
- **功能**：并行/顺序协调、工具管理
- **使用**：涉及多个工具/系统的操作

```bash
/sc:spawn deploy-pipeline --parallel
/sc:spawn setup-dev-environment --monitor
```

**层次 4：迭代增强（/loop 命令）**
- **范围**：渐进精化工作流程
- **功能**：带验证的迭代周期
- **使用**：质量改进和精化

```bash
/sc:improve messy-code.js --loop --iterations 3
# → 通过周期之间的验证迭代改进代码
```

#### 任务状态管理

**核心原则**：
- **基于证据的进展**：可衡量的结果，而不仅仅是活动
- **单一焦点协议**：一次只有一个任务进行中
- **实时更新**：工作进展时即时状态更改
- **质量门**：完成任务前验证

**任务检测**：
- 多步操作（3+ 步）→ 创建任务分解
- 关键词：build、implement、create、fix、optimize → 激活任务跟踪
- 范围指示符：system、feature、comprehensive → 添加进度监控

### 内省模式 🧠

**它是什么**：元认知分析，让 SuperClaude 检查自己的推理和决策过程。

**何时使用**：复杂问题解决、框架故障排除、学习时刻，或当您使用 `--introspect` 明确请求时。

**它如何工作**：SuperClay 跳出正常操作来分析其思维模式、决策逻辑和操作序列。

#### 核心能力

**推理分析** 🧠
- 检查逻辑流和决策理由
- 评估思维链连贯性
- 识别假设和潜在偏见
- 根据证据验证推理

**操作序列审查** 🔄
- 分析工具选择有效性
- 审查工作流程模式和效率
- 考虑替代方法
- 识别优化机会

**框架合规检查** 🔍
- 根据 SuperClaude 规则和原则验证操作
- 识别与标准模式的偏差
- 需要时提供纠正指导
- 确保满足质量标准

**学习识别** 💡
- 从结果中提取洞察
- 识别可重用的成功模式
- 识别改进的知识差距
- 建议未来优化策略

#### 分析标记

当内省模式激活时，您将看到这些标记：

- 🧠 **推理分析** - 检查逻辑流和决策
- 🔄 **操作序列审查** - 分析工作流程有效性
- 🎯 **自我评估** - 元认知评估
- 📊 **模式识别** - 识别行为模式
- 🔍 **框架合规** - 检查规则遵守
- 💡 **回顾洞察** - 从结果中学习

#### 何时内省激活

**通常为以下情况激活**：
- 需要元认知监督的复杂多步问题
- 当结果不符合期望时的错误恢复
- 框架讨论或 SuperClaude 故障排除
- 重复行为模式识别需求

**手动激活**：
```bash
/sc:analyze complex-system/ --introspect
/sc:troubleshoot "framework confusion" --introspection
```

### 令牌效率模式 ⚡

**它是什么**：智能优化系统，在保持质量的同时最大化信息密度。

**何时使用**：大操作、当上下文接近限制时，或当您需要更快执行时。

**它如何工作**：基于上下文和角色感知的自适应压缩，使用符号、缩写和结构优化。

#### 压缩策略

**5 级自适应压缩**：
1. **最小**（0-40% 使用）：完整的细节，具有角色优化的清晰度
2. **高效**（40-70% 使用）：平衡压缩与域感知
3. **压缩**（70-85% 使用）：积极优化与质量门
4. **关键**（85-95% 使用）：保留基本上下文的的最大压缩
5. **紧急**（95%+ 使用）：带信息验证的超压缩

#### 符号系统

**核心逻辑和流程**：
- `→` 导致、暗示（`auth.js:45 → security risk`）
- `⇒` 转换为（`input ⇒ validated_output`）
- `&` 和、组合（`security & performance`）
- `»` 序列，然后（`build » test » deploy`）
- `∴` 因此（`tests fail ∴ code broken`）

**状态和进度**：
- ✅ 完成、通过
- ❌ 失败、错误
- ⚠️ 警告
- 🔄 进行中
- 🎯 目标、目的

**技术域**：
- ⚡ 性能
- 🔍 分析
- 🛡️ 安全
- 📦 部署
- 🎨 设计

#### 激活策略

**通常在以下情况激活**：
- 上下文使用 >75% → 启用压缩
- 大规模操作 → 防止令牌溢出
- 复杂编排 → 优化通信

**手动激活**：
```bash
/sc:analyze huge-codebase/ --uc  # 超压缩模式
/sc:improve legacy-system/ --uc --delegate auto  # 高效大型操作
```

**性能目标**（仍在改进中！）：
- 目标：~30-50% 令牌减少
- 质量：试图保留 ~95% 信息
- 速度：通常 <100ms 压缩决策
- 集成：与框架组件配合使用

#### 模式集成

三种模式经常协同工作：

```bash
/sc:improve large-legacy-system/ --wave-mode auto --uc --introspect
```

**发生什么**：
- **任务管理**：创建带进度跟踪的结构化改进计划
- **令牌效率**：压缩大规模操作的输出
- **内省**：分析改进策略并验证方法

---

## 编排器系统 🎯

编排器是 SuperClaude 的智能路由系统，试图分析您的请求并协调工具、角色和集成的良好组合。这是什么希望使 SuperClaude 感觉聪明和响应迅速，而不仅仅是单独工具的集合。

### 编排器如何工作 🔄

**将其视为智能调度员**：
1. **分析**您的请求以理解意图和复杂性
2. **路由**到命令、标志、角色和 MCP 服务器的最佳组合
3. **协调**执行以获得最佳结果
4. **通过质量门验证**以确保良好结果
5. **优化**性能和资源使用

### 检测引擎 🧠

检测引擎通过多个镜头分析每个请求：

#### 模式识别

**复杂性检测**：
- **简单**：单文件操作、基本任务（<3 步）→ 直接执行
- **中等**：多文件操作、分析任务（3-10 步）→ 标准路由
- **复杂**：系统范围更改、架构决策（>10 步）→ 高级编排

**域识别**：
- **前端**：像 "UI"、"component"、"responsive" 这样的关键词 → 🎨 frontend 角色 + Magic MCP
- **后端**：像 "API"、"database"、"service" 这样的关键词 → ⚙️ backend 角色 + Context7 MCP
- **安全**：像 "vulnerability"、"auth"、"compliance" 这样的关键词 → 🛡️ security 角色 + Sequential MCP
- **性能**：像 "slow"、"optimize"、"bottleneck" 这样的关键词 → ⚡ performance 角色 + Playwright MCP

**操作类型分类**：
- **分析**："analyze"、"review"、"understand" → Sequential MCP + analyzer 角色
- **创建**："create"、"build"、"implement" → Magic MCP（如果 UI）或 Context7（模式）
- **修改**："improve"、"refactor"、"optimize" → 适当的专家角色
- **调试**："troubleshoot"、"fix"、"debug" → Sequential MCP + analyzer 角色

#### 自动激活逻辑

**高置信度触发器**（90%+ 激活）：
```bash
/sc:analyze auth-system/ --focus security
# → 🛡️ security 角色 + Sequential MCP + --validate 标志
```

**基于上下文的激活**：
```bash
/sc:build react-components/
# → 🎨 frontend 角色 + Magic MCP + --c7 标志（React 文档）
```

**基于性能的激活**：
```bash
# 当上下文使用 >75%
/sc:analyze large-project/
# → 自动添加 --uc 标志用于压缩
```

### 路由智能 🚦

路由系统使用动态决策树将检测到的模式映射到最佳工具组合。

#### 主路由表

| 请求模式 | 通常自动激活 | 频率 | 为什么 |
|----------------|----------------|------------|-----|
| "analyze architecture" | 🏗️ architect + --ultrathink + Sequential | 大多数时候 | 复杂系统分析 |
| "create UI component" | 🎨 frontend + Magic + --uc | 相当频繁 | 前端域与生成 |
| "security audit" | 🛡️ security + --ultrathink + Sequential | 大多数时候 | 需要安全专业知识 |
| "debug complex issue" | 🔍 analyzer + --think + Sequential | 经常 | 调查方法论 |
| "improve performance" | ⚡ performance + --think-hard + Playwright | 相当频繁 | 性能专业知识 + 测试 |

#### 智能协调

**多服务器操作**：
```bash
/sc:design user-dashboard --type api
```
**编排器通常协调**：
- 🏗️ architect 角色（系统设计）
- 🎨 frontend 角色（UI 设计）
- Context7 MCP（框架模式）
- Sequential MCP（设计方法论）

**回退策略**：
- Context7 不可用 → WebSearch 文档 → 手动实施
- Sequential 超时 → 本机 Claude 分析 → 记录限制
- Magic 失败 → 基本组件生成 → 建议手动增强

### 质量门和验证框架 ✅

SuperClaude 试图为操作实现 8 步验证循环：

#### 8 步质量流程

1. **语法验证** - 语言解析器 + Context7 标准
2. **类型检查** - Sequential 分析 + 兼容性验证
3. **代码检查** - Context7 规则 + 质量分析
4. **安全审查** - Sequential 分析 + OWASP 合规性
5. **测试** - Playwright E2E + 覆盖率分析（目标是良好覆盖率）
6. **性能** - Sequential 分析 + 基准测试
7. **文档** - Context7 模式 + 完整性验证
8. **集成** - Playwright 测试 + 部署验证

#### 验证自动化

**持续集成**：
- CI/CD 管道集成
- 带早期故障检测的渐进验证
- 带全面指标的证据生成

**智能监控**：
- 带 ML 预测的成功率跟踪
- 基于历史模式的自适应验证
- 验证策略的自动优化

### 性能优化 ⚡

编排器通过多种策略尝试优化良好性能：

#### 资源管理

**令牌分配**：
- 检测引擎：1-2K 令牌用于模式分析
- 决策树：500-1K 令牌用于路由逻辑
- MCP 协调：基于激活服务器的可变
- 保留：10% 缓冲区用于意外复杂性

**操作批处理**：
- 当没有依赖时**并行执行**
- 相关操作之间的**上下文共享**
- 成功路由模式的**缓存策略**
- 防止资源耗尽的**智能排队**

#### 高级编排

**子代理委派**：
```bash
# 当检测到 >7 个目录或 >50 个文件时自动激活
/sc:analyze monorepo/
# → --delegate auto 标志 + 并行处理
```

**波浪编排**：
```bash
# 当复杂性 >0.7 + 文件 >20 + 操作类型 >2 时自动激活
/sc:improve legacy-system/
# → --wave-mode auto + 多阶段执行
```

### 实际编排示例 💡

#### 示例 1：安全分析请求
```bash
/sc:analyze user-auth/ --focus security
```

**编排器分析**：
- 域：安全（高置信度）
- 复杂性：中等（认证系统）
- 操作：分析 + 扫描

**通常协调**：
- 🛡️ security 角色（威胁建模视角）
- Sequential MCP（系统分析）
- --validate 标志（操作前安全检查）
- --think 标志（复杂安全模式）

**质量门**：所有 8 步，重点关注安全验证

#### 示例 2：前端性能优化
```bash
/sc:improve slow-dashboard/ --focus performance
```

**编排器分析**：
- 域：前端 + 性能（需要双重专业知识）
- 复杂性：高（性能优化）
- 操作：改进 + 验证

**通常协调**：
- ⚡ performance 角色（主要）
- 🎨 frontend 角色（次要，如果检测到 UI）
- Playwright MCP（性能测试）
- --think-hard 标志（复杂优化）

**质量门**：带基准测试的性能聚焦验证

#### 示例 3：大型代码库分析
```bash
/sc:analyze enterprise-monorepo/
```

**编排器分析**：
- 范围：大型（检测到 >50 个文件）
- 复杂性：高（企业规模）
- 资源：预测高令牌使用

**通常协调**：
- --delegate auto 标志（并行处理）
- --uc 标志（令牌优化）
- 🏗️ architect 角色（系统级分析）
- Sequential MCP（结构化分析）

**质量门**：跨子代理的分布式验证

### 编排器配置 ⚙️

**性能设置**：
```yaml
orchestrator_config:
  enable_caching: true
  parallel_operations: true
  max_parallel: 3
  token_reserve: 10%
  emergency_threshold: 90%
```

**智能设置**：
```yaml
  learning_enabled: true
  confidence_threshold: 0.7
  pattern_detection: aggressive
  wave_score_threshold: 0.7
```

编排器试图从成功模式中学习并根据结果改进未来路由决策。

---

## 规则和原则 📏

SuperClaude 根据核心规则和原则运行，确保一致、可靠和有用的行为。理解这些有助于您预测 SuperClaude 将如何处理问题以及为什么做出某些决策。

### 核心操作规则 ⚖️

这些是 SuperClaude 试图遵循的核心规则：

#### 文件操作安全 🔐
- **始终在写/编辑前读取** - SuperClaude 不会在不理解当前内容的情况下修改文件
- **仅使用绝对路径** - 防止路径遍历攻击并确保可靠的文件操作
- **从不自动提交** - SuperClaude 不会提交更改到 git，除非明确请求
- **首选批处理操作** - 将多个相关更改分组以保持一致性

**为什么这很重要**：这些规则防止数据丢失、安全漏洞和对代码库的意外修改。

#### 任务管理规则 📋
- **基于证据的进展** - 任务只有在有可衡量证据时才标记为完成
- **单一焦点协议** - 一次只有一个任务"进行中"以保持清晰
- **质量门** - 所有操作在完成前包括验证步骤
- **上下文保留** - 试图在操作之间很好地保留上下文

**为什么这很重要**：确保可靠的进展跟踪并防止工作丢失或遗忘。

#### 框架合规规则 🎯
- **首先检查依赖项** - 使用库前始终验证 package.json/requirements.txt
- **遵循现有模式** - 尊重项目约定、导入样式和架构
- **系统代码库更改** - 在进行项目范围修改前完成发现
- **验证完成** - 验证更改工作且不破坏现有功能

**为什么这很重要**：保持代码质量并与您现有项目结构保持一致。

### 开发原则 🛠️

这些原则指导 SuperClaude 如何处理开发问题：

#### 基于证据的决策 📊
**主要指令**："证据 > 假设 | 代码 > 文档 | 效率 > 冗长"

- **优化前测量** - 基于实际指标的绩效改进
- **系统测试假设** - 声明由可验证数据支持
- **记录决策理由** - 架构选择的清晰推理
- **从结果中学习** - 基于结果的持续改进

**在实践中**：
```bash
/sc:improve slow-api/ --focus performance
# → 测量当前性能、识别瓶颈、基于数据优化
```

#### SOLID 设计原则 🏗️
- **单一责任** - 每个组件有一个更改理由
- **开闭** - 对扩展开放，对修改关闭
- **里氏替换** - 派生类可替换基类
- **接口隔离** - 不强制依赖未使用的接口
- **依赖反转** - 依赖抽象而非具体

**为什么 SuperClaude 遵循这些**：导致可维护、可扩展和灵活的代码，更容易理解和修改。

#### 质量哲学 ✨
- **预防胜于检测** - 内置质量而非测试质量
- **简单胜于复杂** - 选择最简单有效的解决方案
- **可维护性胜于巧妙性** - 代码应该易于理解和修改
- **默认安全** - 从一开始就实施安全模式

#### 高级开发人员心态 🎓
SuperClaude 像经验丰富的开发人员一样处理问题：

- **系统思维** - 考虑整个系统的影响
- **长期视角** - 根据多个时间范围评估决策
- **风险校准** - 区分可接受和不可接受的风险
- **利益相关者意识** - 平衡技术完美与实际约束

### 规则和原则如何影响您 💡

#### 可预测行为
因为 SuperClaude 遵循一致规则，您可以预测它将如何处理问题：

```bash
/sc:improve legacy-authentication/
```
**您可以预期**：
- 建议更改前读取现有代码
- 遵循您项目的现有模式
- 安全优先方法（安全角色可能激活）
- 基于证据的建议和推理
- 标记改进完成前的质量门

#### 质量保证
原则确保高质量结果：

- **试图避免魔法更改** - SuperClaude 通常解释其推理
- **旨在无破坏性更改** - 试图保留现有功能
- **安全意识** - 安全原则很重要
- **债务感知** - 试图保持或减少复杂性

#### 透明度
您通常应该理解 SuperClaude 在做什么以及为什么：

```bash
/sc:analyze --introspect complex-system/
```
**显示您**：
- 决策过程
- 规则应用
- 原则遵守
- 考虑的替代方法

### 规则和原则在行动中的示例 🎯

#### 示例 1：系统重构
**请求**："清理这个混乱的代码库"

**应用的规则**：
- 更改前完成发现（搜索整个代码库）
- 修改前读取所有文件
- 遵循现有项目模式
- 用证据验证完成

**应用的原则**：
- 简单胜于复杂（减少不必要的复杂性）
- 基于证据的决策（前后测量复杂性）
- 质量保证（全面测试）
- 长期可维护性（考虑未来修改）

#### 示例 2：安全实施
**请求**："为我们的 API 添加身份验证"

**应用的规则**：
- 安全角色通常自动激活
- 绝不损害安全基础
- 首先检查现有模式
- 质量门包括安全验证

**应用的原则**：
- 默认安全（实施安全模式）
- 深度防御（多层安全）
- 基于证据的方法（遵循既定安全模式）
- 系统思维（考虑对整个应用的影响）

#### 示例 3：性能优化
**请求**："这个页面加载缓慢"

**应用的规则**：
- 优化前测量
- 基于证据的进展跟踪
- 用指标验证改进
- 保持现有功能

**应用的原则**：
- 测量驱动的优化
- 用户体验聚焦
- 系统方法论
- 预防胜于检测（识别根本原因）

### 规则执行和质量门 🚨

SuperClaude 通过其质量门系统执行规则：

#### 执行方法
- **操作前验证** - 开始前检查风险
- **实时监控** - 执行期间跟踪规则合规性
- **操作后验证** - 确认规则被遵循
- **证据收集** - 记录合规性以保持透明

#### 当规则受到挑战时
有时规则可能与即时需求冲突：

**示例**："让它快速工作，不要担心质量"

**SuperClaude 的响应**：
- 承认紧迫性
- 解释为什么质量规则对长期成功很重要
- 提供保持基本规则的折衷解决方案
- 如果质量标准放松，记录风险

### 指导角色行为的原则 🎭

每个角色都遵循核心原则，但强调不同方面：

- **🛡️ 安全角色**：安全 > 合规性 > 可靠性 > 性能
- **⚡ 性能角色**：首先测量 > 优化关键路径 > 用户体验
- **🏗️ 架构角色**：长期可维护性 > 可扩展性 > 性能
- **🎨 前端角色**：用户需求 > 可访问性 > 性能 > 技术优雅

**为什么这很重要**：您可以根据其核心原则预测不同角色如何优先考虑权衡。

### 活的原则 🌱

这些规则和原则并非一成不变。它们根据以下内容演变：

- **社区反馈** - 真实世界使用模式告知改进
- **结果分析** - 成功模式得到加强
- **技术变化** - 原则适应新开发实践
- **用户需求** - 规则平衡灵活性与一致性

目标是保持有用、可预测的行为，同时适应软件开发不断变化的格局。

---

## 入门工作流程 🛣️

现在您了解 SuperClaude 的组件，让我们看看不同开发场景的实用工作流程。这些模式将帮助您快速提高生产力。

### 首次设置 🎬

如果您还没有安装 SuperClaude，请参阅[安装指南](installation-guide.md)。安装后，这里是如何开始：

#### 快速验证
```bash
# 测试基本功能
/sc:help                    # 应该显示 SuperClaude 命令
/sc:analyze README.md       # 尝试分析简单文件
/sc:build --help           # 检查命令选项
```

#### 理解自动激活
尝试这些命令以查看 SuperClaude 如何自动选择正确工具：

```bash
# 前端工作 → frontend 角色 + Magic MCP
/sc:build src/components/

# 安全分析 → security 角色 + Sequential MCP
/sc:analyze auth/ --focus security

# 性能调查 → performance 角色 + Playwright MCP
/sc:analyze --focus performance slow-endpoints/
```

在输出中寻找自动激活的标志和角色。这展示了 SuperClaude 的智能路由在行动。

### 开发工作流程模式 🔄

#### 新项目入职
当开始在不熟悉的项目上工作时：

```bash
# 1. 加载项目上下文
/sc:load --deep --summary
# → 提供结构、依赖项、模式概览

# 2. 分析架构
/sc:analyze --focus architecture
# → 🏗️ architect 角色提供系统理解

# 3. 检查代码质量
/sc:analyze --focus quality
# → 🧪 qa 角色识别潜在问题

# 4. 审查文档
/sc:document README --type guide
# → ✍️ scribe 角色改进项目文档
```

#### 功能开发周期
用于开发新功能：

```bash
# 1. 设计阶段
/sc:design user-dashboard --type component
# → 🏗️ architect + 🎨 frontend 角色协调

# 2. 实施
/sc:build dashboard-components/
# → 🎨 frontend 角色 + Magic MCP 用于 UI 生成

# 3. 测试
/sc:test --type e2e dashboard/
# → 🧪 qa 角色 + Playwright MCP 用于测试

# 4. 文档
/sc:document dashboard/ --type api
# → ✍️ scribe 角色创建全面文档
```

#### 错误调查和解决
用于系统调试：

```bash
# 1. 问题调查
/sc:troubleshoot "login randomly fails" --think
# → 🔍 analyzer 角色 + Sequential MCP 用于方法论

# 2. 根因分析
/sc:analyze auth-flow/ --focus debugging
# → 带证据收集的系统调查

# 3. 修复实施
/sc:improve auth/ --safe-mode --validate
# → 带验证的安全改进

# 4. 验证测试
/sc:test auth-flow/ --coverage
# → 全面测试确保修复工作
```

#### 代码质量改进
用于改进现有代码：

```bash
# 1. 质量评估
/sc:analyze legacy-code/ --focus quality
# → 🔄 refactorer 角色识别改进机会

# 2. 安全改进
/sc:improve --preview legacy-code/
# → 应用前查看会更改什么

# 3. 应用改进
/sc:improve --safe legacy-code/
# → 仅应用低风险改进

# 4. 验证更改
/sc:test --coverage improved-code/
# → 确保改进不破坏功能
```

### 常见工作流程组合 🤝

#### 安全优先开发
```bash
# 安全聚焦开发
/sc:analyze --persona-security --focus security
/sc:build --validate --safe-mode
/sc:test --type security
/sc:git --persona-security --validate
```

#### 性能优化工作流程
```bash
# 性能聚焦开发
/sc:analyze --focus performance --persona-performance
/sc:improve --type performance --benchmark
/sc:test --focus performance --play
/sc:test --focus performance --play
```

#### 团队协作工作流程
```bash
# 协作开发模式
/sc:analyze team-code/ --persona-qa --focus quality
/sc:document features/ --persona-scribe --type guide
/sc:git --smart-commit --branch-strategy
/sc:task status  # 检查团队进展
```

### 高级工作流程模式 🚀

#### 大型代码库管理
用于处理企业规模项目：

```bash
# 高效大规模分析
/sc:analyze monorepo/ --delegate auto --uc --focus architecture
# → 并行处理 + 压缩 + 架构焦点

# 系统改进
/sc:improve legacy-system/ --wave-mode auto --safe-mode
# → 带安全检查的多阶段改进

# 全面质量审查
/sc:analyze enterprise-app/ --delegate folders --focus quality
# → 分布式质量分析
```

#### 遗留系统现代化
用于更新旧代码库：

```bash
# 评估阶段
/sc:analyze legacy/ --persona-architect --ultrathink
# → 深度架构分析

# 规划阶段
/sc:design modernization-strategy --type architecture
# → 全面的现代化计划

# 实施阶段
/sc:improve legacy/ --wave-mode systematic --safe-mode --loop
# → 迭代、安全改进与验证

# 迁移支持
/sc:migrate --type framework legacy-to-modern/
# → 框架迁移协助
```

#### 多域项目
用于跨越多个技术域的项目：

```bash
# 跨域协调
/sc:analyze fullstack-app/ --all-mcp --delegate auto
# → 所有 MCP 服务器 + 并行处理

# 域特定改进
/sc:improve frontend/ --persona-frontend --magic
/sc:improve backend/ --persona-backend --c7
/sc:improve infrastructure/ --persona-devops --seq

# 集成验证
/sc:test --type integration --play
# → 全面集成测试
```

### 工作流程优化技巧 💡

#### 从小开始，扩大规模
```bash
# 从聚焦范围开始
/sc:analyze single-component.js --focus quality

# 根据需要扩展
/sc:analyze entire-module/ --focus quality --delegate files

# 扩展到整个系统
/sc:analyze whole-project/ --delegate auto --uc
```

#### 使用渐进增强
```bash
# 基本命令
/sc:build project/

# 添加智能
/sc:build project/ --think --c7

# 完整编排
/sc:build project/ --wave-mode auto --all-mcp --delegate auto
```

#### 结合互补角色
```bash
# 安全 + 性能分析
/sc:analyze api/ --persona-security
/sc:analyze api/ --persona-performance

# 架构 + 质量审查
/sc:review system/ --persona-architect --focus architecture
/sc:review system/ --persona-qa --focus quality
```

### 故障排除工作流程 🚨

#### 当命令不如预期工作时
```bash
# 带内省调试
/sc:troubleshoot "command issues" --introspect
# → 对出错事情的元认知分析

# 尝试不同方法
/sc:analyze problem/ --persona-analyzer --seq
# → 系统调查方法论

# 检查框架状态
/sc:load framework-status/ --summary
# → 理解当前 SuperClaude 状态
```

#### 当性能缓慢时
```bash
# 为速度优化
/sc:analyze large-project/ --no-mcp --uc --scope module
# → 禁用额外功能、压缩输出、限制范围

# 对大任务使用委派
/sc:improve huge-codebase/ --delegate auto --concurrency 5
# → 带控制并行的并行处理
```

#### 当结果不够聚焦时
```bash
# 使用特定焦点标志
/sc:analyze code/ --focus security --scope file

# 手动激活适当角色
/sc:analyze frontend-code/ --persona-security  # 前端的安全视图

# 结合多种方法
/sc:analyze --focus performance --persona-performance --play
```

### 构建您自己的工作流程 🛠️

#### 识别您的常见模式
跟踪什么组合对您的特定需求有效：

```bash
# 安全聚焦 API 开发
alias secure-api="/build api/ --persona-security --validate --c7"

# 性能优化前端工作
alias perf-frontend="/build ui/ --persona-performance --magic --benchmark"

# 质量改进工作流程
alias quality-check="/scan --focus quality && /improve --safe-mode && /test --coverage"
```

#### 尝试标志组合
尝试不同组合以找到最有效：

```bash
# 用于学习：带文档的详细解释
/sc:explain concept --persona-mentor --verbose --c7

# 用于安全：最大验证和检查
/sc:improve critical-code/ --safe-mode --validate --preview

# 用于效率：压缩输出与并行处理
/sc:analyze big-project/ --uc --delegate auto --concurrency 3
```

记住：SuperClaude 从成功模式中学习，因此您使用有效组合越多，它就越善于为您的需求自动激活正确方法。

---

## 集成和协调 🤝

理解 SuperClaude 的组件如何协同工作是有效使用框架的关键。本节向您展示命令、标志、角色和 MCP 服务器如何自动协调 - 以及如何在需要时控制这种协调。

### 自动协调示例 🤖

SuperClaude 基于上下文自动协调组件。以下是它在实践中的工作原理：

#### 前端开发请求
```bash
/sc:build react-dashboard/
```

**自动协调**：
- **命令**：`/build` 处理编译和打包
- **角色**：🎨 frontend 自动激活（检测到 React）
- **MCP**：Magic 提供现代 UI 组件
- **MCP**：Context7 提供 React 最佳实践
- **标志**：`--c7` 自动激活用于框架文档

**结果**：带现代组件、可访问性检查和性能优化的 React 优化构建。

#### 安全分析请求
```bash
/sc:scan user-authentication/ --focus security
```

**自动协调**：
- **命令**：`/scan` 处理安全扫描
- **角色**：🛡️ security 自动激活（安全焦点）
- **MCP**：Sequential 提供系统分析
- **标志**：`--validate` 自动激活（高风险操作）
- **标志**：`--think` 自动激活（复杂安全模式）

**结果**：带威胁建模、漏洞检测和合规性检查的全面安全分析。

#### 性能调查
```bash
/sc:troubleshoot "API responses are slow"
```

**自动协调**：
- **命令**：`/troubleshoot` 处理调查
- **角色**：⚡ performance 自动激活（性能关键词）
- **角色**：🔍 analyzer 提供调查方法论
- **MCP**：Sequential 结构化调试过程
- **MCP**：Playwright 提供性能测试
- **标志**：`--think` 自动激活（复杂调试）

**结果**：带指标、瓶颈识别和优化建议的系统性能调查。

### 手动协调控制 🎛️

有时您想覆盖特定需求的自动协调：

#### 覆盖角色选择
```bash
# 从安全角度查看前端代码
/sc:analyze react-components/ --persona-security
# → UI 组件的安全分析（XSS、数据暴露等）

# 将架构思维应用于小实用程序
/sc:improve utility-function.js --persona-architect
# → 简单代码的设计模式和可扩展性
```

#### 控制 MCP 服务器使用
```bash
# 为速度禁用所有 MCP 服务器
/sc:analyze large-codebase/ --no-mcp
# → 40-60% 更快的执行，仅本机工具

# 为全面分析启用所有 MCP 服务器
/sc:analyze complex-system/ --all-mcp
# → 最大能力，更高令牌使用

# 使用特定 MCP 组合
/sc:build ui-components/ --magic --c7 --no-seq
# → UI 生成 + 文档，跳过复杂分析
```

#### 结合多个视角
```bash
# 不同角色的顺序分析
/sc:analyze payment-system/ --persona-security     # 安全视角
/sc:analyze payment-system/ --persona-performance  # 性能视角
/sc:analyze payment-system/ --persona-architect    # 架构视角

# 或自动协调
/sc:review payment-system/ --focus quality
# → 自动协调安全 + 性能 + 架构洞察
```

### 标志协调模式 🏁

标志协同工作以创建强大的组合：

#### 安全优先模式
```bash
# 关键代码的最大安全
/sc:improve production-auth/ --safe-mode --validate --preview
# → 保守更改 + 风险评估 + 应用前预览

# 大更改的安全探索
/sc:improve legacy-system/ --wave-mode auto --safe-mode --validate
# → 多阶段改进 + 安全检查 + 验证门
```

#### 性能优化模式
```bash
# 大操作快速执行
/sc:analyze huge-project/ --uc --no-mcp --scope module
# → 压缩输出 + 本机工具 + 有限范围

# 高效并行处理
/sc:improve monorepo/ --delegate auto --uc --concurrency 5
# → 并行处理 + 压缩 + 控制资源使用
```

#### 学习聚焦模式
```bash
# 带完整上下文的教学解释
/sc:explain complex-concept --persona-mentor --verbose --c7
# → 教学方法 + 详细解释 + 官方文档

# 带透明度的深度理解
/sc:analyze mysterious-code/ --persona-analyzer --think-hard --introspect
# → 调查方法论 + 深度分析 + 思维透明度
```

### MCP 服务器协调 🔧

MCP 服务器通常自动协同工作：

#### 文档 + 分析
```bash
/sc:improve old-react-code/
```
**MCP 协调**：
- Context7：获取当前 React 最佳实践
- Sequential：根据现代模式分析代码
- Magic：建议现代组件模式
- 结果：符合当前标准的现代化

#### 测试 + 性能
```bash
/sc:test dashboard/ --focus performance
```
**MCP 协调**：
- Sequential：规划全面测试策略
- Playwright：执行性能测试
- Context7：提供测试最佳实践
- 结果：符合行业标准的性能测试

#### 复杂问题解决
```bash
/sc:troubleshoot "complex multi-service issue" --ultrathink
```
**MCP 协调**：
- Sequential：结构化系统调查
- Context7：提供服务架构模式
- Playwright：测试服务交互
- 结果：全面的多域调试

### 角色协作模式 🎭

角色在复杂请求上自动协作：

#### 架构 + 安全
```bash
/sc:design payment-api --type secure
```
**角色协作**：
- 🏗️ architect：系统设计和可扩展性
- 🛡️ security：威胁建模和安全模式
- ⚙️ backend：API 实施模式
- 结果：安全、可扩展的 API 设计

#### 前端 + 性能
```bash
/sc:build dashboard --focus performance
```
**角色协作**：
- 🎨 frontend：UI/UX 和可访问性
- ⚡ performance：优化和指标
- 🏗️ architect：组件架构
- 结果：快速、可访问、结构良好的仪表板

#### 质量 + 重构
```bash
/sc:improve legacy-code/ --focus quality
```
**角色协作**：
- 🔄 refactorer：代码质量和模式
- 🧪 qa：测试和验证
- 🏗️ architect：结构改进
- 结果：清洁、测试、架构良好的代码

### 高级协调策略 🚀

#### 波浪编排
用于复杂多阶段操作：

```bash
/sc:improve enterprise-system/ --wave-mode systematic
```

**波浪协调**：
1. **分析波浪**：🔍 analyzer + Sequential 评估当前状态
2. **规划波浪**：🏗️ architect + Context7 设计改进
3. **实施波浪**：适当专家 + 工具实施更改
4. **验证波浪**：🧪 qa + Playwright 验证改进
5. **优化波浪**：⚡ performance + 指标优化结果

#### 子代理委派
用于并行处理：

```bash
/sc:analyze large-monorepo/ --delegate folders
```

**委派协调**：
- **主代理**：编排和综合结果
- **子代理**：单个文件夹的专业分析
- **协调**：结合域专业知识的结果
- **MCP 集成**：跨所有代理共享

#### 自适应智能
SuperClaude 基于上下文调整协调：

**开发阶段检测**：
- 规划阶段 → 🏗️ architect + ✍️ scribe 强调
- 实施阶段 → 领域专家 + Magic/Context7
- 测试阶段 → 🧪 qa + Playwright 强调
- 部署阶段 → 🚀 devops + 验证强调

**基于复杂性的扩展**：
- 简单任务 → 直接执行
- 中等复杂性 → 角色 + MCP 协调
- 高复杂性 → 波浪编排 + 委派

### 协调故障排除 🔧

#### 当自动协调出错时
```bash
# 激活太多工具（缓慢/昂贵）
/sc:analyze simple-file.js --no-mcp --answer-only
# → 简单任务的最少工具

# 激活了错误角色
/sc:analyze backend-api/ --persona-security
# → 用显式角色选择覆盖

# 分析深度不足
/sc:troubleshoot complex-issue --ultrathink --all-mcp
# → 强制最大能力
```

#### 优化协调
```bash
# 从简单开始，根据需要添加复杂性
/sc:analyze code.js                    # 基本分析
/sc:analyze code.js --think            # 添加思考
/sc:analyze code.js --think --c7       # 添加文档
/sc:analyze code.js --think --c7 --seq # 添加系统分析
```

#### 理解协调决策
```bash
# 看为什么选择某些工具
/sc:analyze complex-system/ --introspect
# → 显示决策过程和工具选择推理
```

### 集成最佳实践 💡

#### 让自动协调首先工作
- 相信 SuperClaude 的自动工具选择
- 仅当您需要特定视角时覆盖
- 从简单命令开始，根据需要添加标志

#### 理解标志交互
- 某些标志覆盖其他标志（`--no-mcp` 覆盖 `--c7`、`--seq`）
- 安全标志优先于优化标志
- 角色标志可以被更具体的角色请求覆盖

#### 使用适当范围
- 文件级：单个角色 + 最少 MCP
- 模块级：域角色 + 相关 MCP
- 系统级：多个角色 + 全面 MCP 协调

#### 监控资源使用
- 大操作 → 使用 `--uc` 和 `--delegate`
- 简单任务 → 使用 `--no-mcp` 和 `--answer-only`
- 关键操作 → 使用 `--safe-mode` 和 `--validate`

关键是理解 SuperClaude 的智能来自其组件之间的协调。自动协调在大多数时候效果良好，但知道如何控制它让您有灵活性处理任何情况。

---

## 实用示例 💡

展示 SuperClaude 在行动中的真实场景。这些示例演示不同组件如何协同工作来解决常见开发问题。

### 场景 1：新团队成员入职 👋

**情况**：您开始在不熟悉的 React/Node.js 电子商务项目上工作。

#### 步骤 1：项目理解
```bash
/sc:load --deep --summary
```
**发生什么**：
- 🔍 analyzer 角色激活（需要调查）
- Sequential MCP 结构化分析
- Context7 MCP 识别框架模式
- 创建全面项目概览

**输出**：项目结构、技术栈、依赖项和架构摘要。

#### 步骤 2：代码质量评估
```bash
/sc:analyze --focus quality
```
**自动协调**：
- 🧪 qa 角色激活（质量焦点）
- Sequential MCP 提供系统分析
- 扫描代码质量、安全和性能问题
- 生成可操作改进建议

**输出**：带特定问题和改进建议的质量报告。

#### 步骤 3：架构理解
```bash
/sc:analyze --focus architecture --persona-architect
```
**发生什么**：
- 🏗️ architect 角色提供系统设计视角
- Context7 MCP 带来 React/Node.js 架构模式
- Sequential MCP 结构化架构分析
- 识别设计模式、数据流和组件关系

**输出**：带设计模式和系统关系的架构概览。

#### 步骤 4：入门指南
```bash
/sc:document onboarding --type guide --persona-scribe
```
**发生什么**：
- ✍️ scribe 角色创建专业文档
- Context7 MCP 提供文档标准
- 将先前分析综合为新人友好指南
- 包括设置说明和关键概念

**输出**：为未来团队成员的全面入职指南。

**节省时间**：通常需要 2-3 天探索的内容在约 30 分钟内综合为全面理解。

### 场景 2：安全漏洞调查 🛡️

**情况**：安全扫描器标记了用户认证系统中的潜在问题。

#### 步骤 1：安全聚焦分析
```bash
/sc:scan auth-system/ --persona-security --focus security
```
**自动协调**：
- 🛡️ security 角色激活（安全专业知识）
- Sequential MCP 提供系统威胁建模
- Context7 MCP 带来 OWASP 和安全最佳实践
- `--validate` 标志自动激活（高风险操作）

**输出**：带威胁评估和漏洞优先级的详细安全分析。

#### 步骤 2：根因调查
```bash
/sc:troubleshoot "JWT token exposure in logs" --think --seq
```
**发生什么**：
- 🔍 analyzer 角色提供调查方法论
- `--think` 标志启用深度分析
- Sequential MCP 结构化调试过程
- 跟踪数据流并识别暴露点

**输出**：带证据链和影响评估的根因分析。

#### 步骤 3：安全实施
```bash
/sc:improve auth-system/ --focus security --safe-mode --validate
```
**自动协调**：
- 🛡️ security 角色保持安全焦点
- `--safe-mode` 确保保守更改
- `--validate` 确认更改后再应用
- Context7 MCP 提供安全编码模式

**输出**：最小风险和全面验证的安全改进。

#### 步骤 4：安全测试
```bash
/sc:test auth-system/ --type security --play
```
**发生什么**：
- 🧪 qa 角色提供测试专业知识
- Playwright MCP 执行安全测试场景
- 测试认证流程、会话管理和访问控制
- 验证安全改进正在工作

**输出**：带改进证据的全面安全测试结果。

**风险降低**：系统方法减少遗漏安全问题的机会并确保全面覆盖。

### 场景 3：性能优化冲刺 ⚡

**情况**：电子商务仪表板加载缓慢，影响用户体验。

#### 步骤 1：性能分析
```bash
/sc:analyze dashboard/ --focus performance --persona-performance
```
**自动协调**：
- ⚡ performance 角色激活（性能专业知识）
- Playwright MCP 提供性能指标和测试
- Context7 MCP 带来 React 性能最佳实践
- `--think-hard` 自动激活（复杂性能分析）

**输出**：带指标和优先优化机会的性能瓶颈识别。

#### 步骤 2：前端性能深度分析
```bash
/sc:analyze frontend/ --persona-frontend --focus performance --play
```
**发生什么**：
- 🎨 frontend 角色提供 UI/UX 视角
- ⚡ performance 角色协调（双重专业知识）
- Playwright MCP 测量核心 Web 指标、捆绑包大小、渲染时间
- Magic MCP 建议现代优化模式

**输出**：考虑可访问性和用户体验的前端特定性能分析。

#### 步骤 3：后端 API 性能
```bash
/sc:analyze api/ --persona-backend --focus performance
```
**自动协调**：
- ⚙️ backend 角色提供服务器端专业知识
- Sequential MCP 分析数据库查询和 API 模式
- Context7 MCP 提供 Node.js/Express 优化模式
- 识别慢查询、低效端点和缓存机会

**输出**：带数据库和 API 优化建议的后端性能分析。

#### 步骤 4：系统优化
```bash
/sc:improve dashboard/ --focus performance --loop --iterations 3
```
**发生什么**：
- ⚡ performance 角色领导优化
- `--loop` 启用迭代改进
- 每个周期：优化 → 测量 → 验证 → 改进
- 渐进增强与指标验证

**输出**：每个周期后带可衡量结果的迭代性能改进。

#### 步骤 5：性能测试验证
```bash
/sc:test dashboard/ --focus performance --play --benchmark
```
**发生什么**：
- Playwright MCP 执行全面性能测试
- 在多种设备、网络条件和浏览器上测试
- 测量核心 Web 指标、加载时间和用户交互指标
- 验证改进满足性能预算

**输出**：证明优化有效性的性能测试结果。

**性能提升**：系统方法通常通过可衡量验证实现 40-70% 性能改进。

### 场景 4：遗留代码现代化 🔄

**情况**：5 年历史的 React 应用需要现代化到当前标准。

#### 步骤 1：遗留评估
```bash
/sc:analyze legacy-app/ --persona-architect --ultrathink
```
**自动协调**：
- 🏗️ architect 角色提供结构分析
- `--ultrathink` 启用最大分析深度
- Context7 MCP 与当前 React 模式比较
- Sequential MCP 提供系统现代化评估

**输出**：带现代化路线图和风险评估的全面遗留分析。

#### 步骤 2：现代化规划
```bash
/sc:design modernization-strategy --type architecture --persona-architect
```
**发生什么**：
- 🏗️ architect 角色设计迁移策略
- Context7 MCP 提供当前 React 生态系统模式
- Sequential MCP 结构化现代化计划
- 识别迁移阶段、依赖项和风险

**输出**：带分阶段方法和风险缓解的详细现代化计划。

#### 步骤 3：安全增量改进
```bash
/sc:improve legacy-components/ --safe-mode --wave-mode systematic --loop
```
**自动协调**：
- 🔄 refactorer 角色领导代码改进
- `--safe-mode` 确保最小风险
- `--wave-mode systematic` 启用多阶段改进
- `--loop` 允许迭代精化
- 多个角色协调：architect、frontend、qa

**输出**：带安全检查和渐进增强的系统现代化。

#### 步骤 4：测试现代化
```bash
/sc:test modernized-app/ --type integration --coverage --play
```
**发生什么**：
- 🧪 qa 角色确保现代化过程中的质量
- Playwright MCP 提供全面测试
- 测试遗留兼容性和新功能
- 验证现代化不破坏现有功能

**输出**：证明现代化成功的全面测试结果。

**现代化成功**：系统方法将现代化风险降低 80% 并确保兼容性。

### 场景 5：多团队 API 设计 🌐

**情况**：设计多个团队将消费的新微服务 API。

#### 步骤 1：需求分析
```bash
/sc:design user-service-api --type api --persona-backend
```
**自动协调**：
- ⚙️ backend 角色提供 API 设计专业知识
- 🏗️ architect 角色协调系统集成
- Context7 MCP 提供 API 设计最佳实践
- Sequential MCP 结构化需求分析

**输出**：带端点、数据模型和集成模式的全面 API 设计。

#### 步骤 2：安全审查
```bash
/sc:review api-design/ --persona-security --focus security
```
**发生什么**：
- 🛡️ security 角色评估 API 安全
- 审查身份验证、授权和数据保护
- Context7 MCP 提供 OWASP API 安全指南
- 识别安全要求和威胁向量

**输出**：带强化建议和合规性要求的安全评估。

#### 步骤 3：性能考虑
```bash
/sc:analyze api-design/ --persona-performance --focus performance
```
**自动协调**：
- ⚡ performance 角色评估可扩展性
- 分析端点性能、缓存策略、速率限制
- Context7 MCP 提供高性能 API 模式
- 预测负载下的性能

**输出**：带可扩展性建议和优化策略的性能分析。

#### 步骤 4：多团队文档
```bash
/sc:document api/ --type api --persona-scribe --detailed
```
**发生什么**：
- ✍️ scribe 角色创建专业 API 文档
- Context7 MCP 提供 API 文档标准
- 创建示例、集成指南和故障排除
- 为多个消费团队定制

**输出**：带示例、集成指南和最佳实践的全面 API 文档。

#### 步骤 5：实施验证
```bash
/sc:build api-implementation/ --validate --test-coverage
```
**自动协调**：
- ⚙️ backend 角色实施 API 模式
- 🧪 qa 角色确保质量和测试
- Sequential MCP 根据设计验证实施
- 全面测试和验证

**输出**：带全面测试和验证的生产就绪 API 实施。

**协作效率**：多角色协调将设计迭代周期减少 60% 并改善跨团队对齐。

### 常见模式识别 🔍

这些示例显示 SuperClaude 组件协调的重复模式：

#### 调查 → 分析 → 实施 → 验证
大多数复杂工作流程遵循此模式，每个阶段都有适当的角色和工具。

#### 多角色协调
复杂问题受益于多个视角（安全 + 性能、架构 + 前端等）。

#### 渐进增强
从简单开始，根据需要添加复杂性（`--think` → `--think-hard` → `--ultrathink`）。

#### 安全优先方法
关键操作自动包括验证和安全检查（`--safe-mode`、`--validate`）。

#### 上下文感知工具选择
SuperClaude 基于检测上下文自动选择适当的 MCP 服务器和标志。

这些示例表明 SuperClaude 的价值来自其组件的智能协调，而不是任何单一能力。框架适应您的需求，同时保持一致的质量和安全标准。

---

## 技巧和最佳实践 🎯

基于真实世界使用模式和成功工作流程，这里有一些实用技巧，可以帮助您充分利用 SuperClaude。

### 成功开始 🚀

#### 从简单命令开始
```bash
#从这里开始 - 基本功能
/sc:help
/sc:analyze README.md
/sc:build --help

#而不是这里 - 复杂编排
/sc:improve entire-codebase/ --wave-mode force --all-mcp --delegate auto
```

**为什么**：在添加复杂性之前理解基本行为可防止混淆，并帮助您逐渐学习框架。

#### 首先相信自动激活
```bash
# 让 SuperClaude 选择工具
/sc:analyze auth-system/
# → 观察什么自动激活（可能是 security 角色 + 验证）

# 然后尝试手动控制
/sc:analyze auth-system/ --persona-performance
# → 看同一代码的不同视角
```

**为什么**：自动激活通常正确，并为您显示不同场景的最佳工具组合。

#### 使用预览和安全模式
```bash
# 首先看会发生什么
/sc:improve messy-code.js --preview

# 安全应用更改
/sc:improve messy-code.js --safe-mode

# 对于关键代码，两者都使用
/sc:improve production-auth/ --preview --safe-mode --validate
```

**为什么**：防止意外更改并帮助您在执行前理解 SuperClaude 会做什么。

### 标志使用模式 🏁

#### 从简单开始，添加复杂性
```bash
# 基本命令
/sc:analyze complex-system/

# 根据需要添加思考
/sc:analyze complex-system/ --think

# 如果涉及外部库，添加文档
/sc:analyze complex-system/ --think --c7

# 关键系统的全面分析
/sc:analyze complex-system/ --think-hard --c7 --seq --validate
```

**为什么**：增量复杂性帮助您理解每个标志添加什么，并避免过度工程简单问题。

#### 起作用的常见标志组合
```bash
# 安全改进工作流程
/sc:improve --preview → /improve --safe-mode → /test --coverage

# 深度调查工作流程
/sc:troubleshoot issue --think --seq → /analyze affected-code/ --focus quality

# 学习和文档工作流程
/sc:explain concept --persona-mentor --verbose --c7

# 性能优化工作流程
/sc:analyze --focus performance --persona-performance --play
```

**为什么**：这些组合是被证明的模式，彼此配合良好，不冲突。

#### 避免标志冲突
```bash
# ❌ 冲突标志
/sc:analyze code/ --no-mcp --c7  # --no-mcp 覆盖 --c7

# ❌ 反生产组合
/sc:analyze small-file.js --ultrathink --all-mcp  # 简单任务过度杀伤

# ✅ 合理组合
/sc:analyze large-system/ --think --delegate auto  # 复杂性适当
/sc:analyze simple-utility.js --answer-only       # 简单性适当
```

**为什么**：理解标志优先级和交互可防止意外行为和资源浪费。

### 角色优化 🎭

#### 让域自动激活工作
```bash
# 这些将自动获得正确角色
/sc:build react-components/     # → frontend 角色
/sc:scan auth/ --focus security # → security 角色
/sc:troubleshoot slow-api/      # → performance + analyzer 角色
```

**为什么**：自动激活基于证明模式，通常选择最合适的专业知识。

#### 手动覆盖不同视角
```bash
# 在同一代码上获得不同视角
/sc:analyze payment-flow/ --persona-security    # 安全视角
/sc:analyze payment-flow/ --persona-performance # 性能视角
/sc:analyze payment-flow/ --persona-architect   # 架构视角
```

**为什么**：不同角色提供独特的洞察，可以揭示他人可能错过的问题或机会。

#### 为项目阶段使用适当角色
```bash
# 规划阶段
/sc:design new-feature --persona-architect

# 实施阶段
/sc:build feature/ --persona-frontend  # 或 backend 等

# 测试阶段
/sc:test feature/ --persona-qa

# 文档阶段
/sc:document feature/ --persona-scribe
```

**为什么**：每个项目阶段受益于不同类型的专业知识和视角。

### MCP 服务器策略 🔧

#### 理解每个服务器何时有帮助
- **Context7**：使用框架、库或需要官方文档时
- **Sequential**：用于复杂调试、系统分析或架构决策
- **Magic**：用于 UI 组件生成、设计系统或前端开发
- **Playwright**：用于测试、性能测量或浏览器自动化

#### 为性能与能力优化
```bash
# 简单任务的快速执行
/sc:analyze simple-script.js --no-mcp

# 复杂问题的全面分析
/sc:analyze complex-system/ --all-mcp --think-hard

# 大多数工作的平衡方法
/sc:analyze typical-component/ --c7  # 只是文档查找
```

**为什么**：将 MCP 使用与任务复杂性相匹配可优化结果的速度和质量。

### 工作流程优化 📈

#### 使用渐进增强
```bash
# 级别 1：基本分析
/sc:analyze component.js

# 级别 2：复杂时添加思考
/sc:analyze component.js --think

# 级别 3：为框架添加文档
/sc:analyze component.js --think --c7

# 级别 4：关键代码的全面分析
/sc:analyze component.js --think-hard --c7 --seq --validate
```

**为什么**：从您需要的开始，只在必要时添加复杂性。防止过度工程并节省时间。

#### 批处理相关操作
```bash
# ✅ 高效：相关操作一起
/sc:analyze auth-system/ --focus security
/sc:improve auth-system/ --focus security --safe-mode
/sc:test auth-system/ --type security

# ❌ 低效：分散操作
/sc:analyze auth-system/
/sc:review different-system/
/sc:improve auth-system/  # 操作之间丢失上下文
```

**为什么**：批处理相关工作保持上下文，并允许 SuperClaude 在先前分析的基础上构建。

#### 使用适当范围
```bash
# 文件级特定问题
/sc:improve single-component.js --focus performance

# 模块级相关功能
/sc:analyze user-auth/ --scope module

# 项目级架构关注
/sc:analyze --scope project --focus architecture

# 系统级仅在必要时
/sc:analyze --scope system --delegate auto --uc
```

**为什么**：将范围与问题相匹配可防止分析不足和资源浪费。

### 性能和效率 🏃‍♂️

#### 管理上下文和令牌使用
```bash
# 大操作使用压缩
/sc:analyze huge-codebase/ --uc --delegate auto

# 重复分析，缓存结果
/sc:load project-context/  # 缓存项目理解
/sc:analyze specific-issue/  # 在缓存上下文上构建

# 简单问题最小化开销
/sc:explain quick-concept --answer-only --no-mcp
```

**为什么**：令牌效率保持操作快速并防止大项目中的上下文溢出。

#### 对大项目使用委派
```bash
# 适当时自动委派
/sc:analyze monorepo/ --delegate auto

# 特定需求的手动委派
/sc:analyze large-project/ --delegate folders --concurrency 3

# 小项目跳过委派
/sc:analyze small-app/ --no-delegate
```

**为什么**：委派为大规模操作提供显著加速（40-70%），同时保持质量。

#### 优化命令序列
```bash
# ✅ 高效序列
/sc:load project/           # 理解上下文一次
/sc:analyze --focus quality # 在理解上构建
/sc:improve --safe-mode     # 应用改进
/sc:test --coverage         # 验证更改

# ❌ 低效序列
/sc:analyze file1.js
/sc:analyze file2.js        # 重复设置
/sc:analyze file3.js        # 失去优化机会
```

**为什么**：顺序命令可以彼此构建上下文和分析以获得更好结果。

### 质量和安全 🛡️

#### 始终验证重要更改
```bash
# 生产代码
/sc:improve production-auth/ --safe-mode --validate --preview

# 实验功能
/sc:improve experimental-feature/ --validate

# 学习/探索
/sc:improve test-code/ --preview  # 看它会做什么
```

**为什么**：验证防止破坏性更改并帮助您理解修改的影响。

#### 有效使用质量门
```bash
# 让质量门自动运行
/sc:build production-app/  # 运行 8 步验证过程

# 为关键系统添加额外验证
/sc:build payment-system/ --validate --safe-mode

# 仅为实验工作跳过验证
/sc:build prototype/ --no-validate  # 谨慎使用
```

**为什么**：质量门在问题更便宜和更容易修复时及早捕获问题。

#### 保持证据链
```bash
# 提供证据的命令
/sc:analyze --focus performance  # → 性能指标
/sc:test --coverage             # → 覆盖率报告
/sc:scan --focus security       # → 安全评估

# 对复杂决策使用内省
/sc:analyze complex-system/ --introspect  # → 决策推理
```

**为什么**：基于证据的开发导致更好决策，当问题出现时更容易调试。

### 学习和成长 📚

#### 使用导师角色学习
```bash
# 学习新概念
/sc:explain GraphQL --persona-mentor --verbose

# 理解复杂代码
/sc:analyze complex-algorithm.js --persona-mentor

# 获得分步指导
/sc:build new-feature/ --persona-mentor --plan
```

**为什么**：导师角色优化理解和知识转移，而不仅仅是任务完成。

#### 尝试不同方法
```bash
# 在同一问题上尝试不同角色
/sc:analyze api-design/ --persona-architect
/sc:analyze api-design/ --persona-security
/sc:analyze api-design/ --persona-performance

# 比较工具组合
/sc:build app/ --magic --c7
/sc:build app/ --no-mcp --uc  # 更快但更简单
```

**为什么**：理解不同方法帮助您为不同情况选择最佳工具。

#### 构建您自己的模式
```bash
# 识别对您工作流程有效的内容
# 安全聚焦 API 开发
/sc:design api --persona-security --validate
/sc:build api --persona-backend --c7
/sc:test api --type security --play

# 创建您自己的高效组合
/sc:analyze code/ --think --c7 --safe-mode  # 您的个人"彻底分析"
```

**为什么**：开发您自己的证明模式可提高生产力并确保一致质量。

### 要避免的常见陷阱 ⚠️

#### 不要对简单任务过度工程
```bash
# ❌ 简单任务过度杀伤
/sc:analyze simple-utility.js --ultrathink --all-mcp --wave-mode force

# ✅ 简单任务适当
/sc:analyze simple-utility.js --focus quality
```

#### 不要忽略自动激活智慧
```bash
# ❌ 对抗系统
/sc:build react-app/ --persona-backend --no-magic  # 错误工具

# ✅ 与系统配合
/sc:build react-app/  # 让 frontend 角色和 Magic 自动激活
```

#### 不要为速度跳过安全
```bash
# ❌ 重要代码有风险
/sc:improve production-auth/ --force --no-validate

# ✅ 平衡方法
/sc:improve production-auth/ --safe-mode --validate  # 更安全但仍然高效
```

#### 不要使用您不理解的标志
```bash
# ❌ 标志崇拜
/sc:command --random-flags-that-look-important

# ✅ 理解每个标志做什么
/sc:command --think  # 因为我需要更深入分析
/sc:command --c7     # 因为我使用外部库
```

### 衡量成功 📊

跟踪什么对您的特定需求有效：

- **速度**：不同标志组合完成的速度如何？
- **质量**：哪种方法为您的的工作类型产生更好结果？
- **学习**：哪种组合帮助您更好理解问题？
- **安全**：哪种模式在您的环境中防止问题？

记住：SuperClaude 从成功模式中学习，因此一致使用有效组合有助于框架为您的特定工作流程更好地进行自动激活。

---

## 故障排除和常见问题 🚨

当 SuperClaude 不如预期工作时，这里是如何诊断和修复常见问题。

### 命令问题 🛠️

#### 命令不如预期工作

**问题**：命令产生意外结果或似乎忽略您的请求。

**诊断**：
```bash
# 检查什么自动激活
/sc:analyze code.js --introspect
# → 显示决策过程

# 尝试显式控制
/sc:analyze code.js --persona-analyzer --think --seq
# → 覆盖自动激活
```

**解决方案**：
```bash
# 更具体地说明您想要什么
/sc:improve code.js --focus performance --safe-mode

# 使用预览理解会发生什么
/sc:improve code.js --preview

# 从简单开始添加复杂性
/sc:analyze code.js                    # 基本
/sc:analyze code.js --think            # 添加深度
/sc:analyze code.js --think --c7       # 添加文档
```

**常见原因**：
- 自动激活选择了与您期望不同的工具
- 请求对 SuperClaude 理解意图太模糊
- 复杂性不匹配（简单请求与复杂标志或反之）

#### 命令运行太慢

**问题**：操作花费时间比预期长得多。

**诊断**：
```bash
# 检查激活了什么
/sc:analyze large-project/ --introspect
# → 看使用什么工具和服务器

# 监控资源使用
/sc:analyze large-project/ --verbose
# → 显示详细执行步骤
```

**解决方案**：
```bash
# 为速度优化
/sc:analyze large-project/ --uc --no-mcp --scope module

# 对大操作使用委派
/sc:analyze huge-codebase/ --delegate auto --concurrency 3

# 减少范围
/sc:analyze specific-component.js  # 而不是整个项目

# 禁用昂贵功能
/sc:analyze code/ --no-mcp --answer-only
```

**性能优化优先级**：
1. 减少范围（`--scope file` vs `--scope project`）
2. 使用压缩（`--uc`）
3. 禁用 MCP 服务器（`--no-mcp`）
4. 使用委派（`--delegate auto`）
5. 使用仅答案模式（`--answer-only`）

#### 命令产生太多输出

**问题**：信息超载，难以找到相关信息。

**解决方案**：
```bash
# 使用压缩
/sc:analyze large-system/ --uc

# 更具体地说明焦点
/sc:analyze system/ --focus security  # 而不是一般分析

# 对简单问题使用仅答案
/sc:explain concept --answer-only

# 限制范围
/sc:analyze --scope file specific-issue.js
```

### 标志问题 🏁

#### 标志冲突和意外行为

**问题**：标志似乎不起作用或产生意外结果。

**常见冲突**：
```bash
# ❌ 这些冲突
/sc:command --no-mcp --c7        # --no-mcp 覆盖 --c7
/sc:command --answer-only --plan # --answer-only 跳过规划
/sc:command --uc --verbose       # --uc 覆盖 --verbose

# ✅ 这些配合使用
/sc:command --think --c7 --seq   # 互补能力
/sc:command --safe-mode --validate --preview  # 分层安全
```

**标志优先级顺序**：
1. 安全标志（`--safe-mode`）> 优化标志
2. 显式标志 > 自动激活
3. `--no-mcp` 覆盖所有单个 MCP 标志
4. 最后指定的角色获胜
5. 范围：system > project > module > file

**诊断**：
```bash
# 检查实际激活的标志
/sc:command args --introspect
# → 显示优先级解析后的最终标志配置
```

#### 自动激活问题

**问题**：错误的标志或角色自动激活。

**解决方案**：
```bash
# 显式覆盖自动激活
/sc:analyze frontend-code/ --persona-security  # 强制安全视图
/sc:build project/ --no-mcp                    # 强制仅本机工具

# 使用更具体的语言
/sc:analyze "security vulnerabilities in auth system"  # 明确意图
# vs
/sc:analyze auth system                                # 模糊

# 检查什么关键词触发自动激活
/sc:help analyze  # 显示自动激活模式
```

**自动激活调试**：
```bash
# 看为什么某些标志激活
/sc:troubleshoot "why did --think-hard activate?" --introspect
```

### 角色问题 🎭

#### 激活了错误角色

**问题**：SuperClaude 为您的需求使用错误的专家。

**诊断**：
```bash
# 检查什么触发了角色激活
/sc:analyze code/ --introspect
# → 显示角色选择推理
```

**解决方案**：
```bash
# 用显式角色覆盖
/sc:analyze backend-api/ --persona-security  # 后端代码的安全视图
/sc:analyze ui-component/ --persona-performance  # 前端的性能视图

# 使用更具体的语言
/sc:analyze "security issues in payment processing"  # 触发安全角色
/sc:analyze "slow database queries"                  # 触发性能角色

# 尝试不同角色获得不同视角
/sc:analyze payment-system/ --persona-security    # 安全视图
/sc:analyze payment-system/ --persona-architect   # 架构视图
```

#### 角色似乎未激活

**问题**：预期角色行为但获得通用响应。

**检查角色激活**：
```bash
# 验证角色是否激活
/sc:analyze auth/ --persona-security --introspect
# → 应该显示安全聚焦推理

# 检查域关键词是否清晰
/sc:scan authentication --focus security  # 应该自动激活安全角色
```

**解决方案**：
```bash
# 对角色和焦点明确
/sc:analyze code/ --persona-security --focus security

# 为角色使用适当命令
/sc:scan --persona-security     # 安全扫描
/sc:test --persona-qa           # 质量聚焦测试
/sc:document --persona-scribe   # 专业文档
```

### MCP 服务器问题 🔧

#### MCP 服务器未激活

**问题**：预期 MCP 能力但它们似乎不工作。

**诊断**：
```bash
# 检查 MCP 服务器状态
/sc:troubleshoot "MCP servers not working" --introspect

# 验证 MCP 安装
/sc:load --summary  # 应该显示可用的 MCP 服务器

# 测试特定服务器
/sc:analyze react-app/ --c7     # 应该使用 Context7
/sc:troubleshoot issue --seq    # 应该使用 Sequential
/sc:build ui/ --magic           # 应该使用 Magic
/sc:test app/ --play            # 应该使用 Playwright
```

**常见解决方案**：
```bash
# 强制 MCP 激活
/sc:analyze code/ --all-mcp

# 检查服务器是否禁用
/sc:analyze code/ --c7  # 如果这不起作用，Context7 可能不可用

# 使用回退方法
/sc:analyze react-app/ --no-mcp  # 如果 MCP 不可用，使用本机工具
```

#### MCP 服务器太慢

**问题**：MCP 服务器集成导致性能缓慢。

**解决方案**：
```bash
# 为速度禁用 MCP
/sc:analyze large-project/ --no-mcp

# 使用选择性 MCP 激活
/sc:analyze react-code/ --magic --no-seq  # 仅 UI 生成，跳过分析

# 优化 MCP 使用
/sc:analyze code/ --uc --c7  # 压缩 + 仅文档
```

### 性能问题 ⚡

#### 操作使用太多令牌

**问题**：遇到上下文限制或昂贵操作。

**解决方案**：
```bash
# 自动启用压缩
/sc:analyze huge-project/ --uc

# 减少范围
/sc:analyze --scope module specific-area/
/sc:analyze --scope file specific-file.js

# 使用委派
/sc:analyze large-codebase/ --delegate auto --uc

# 禁用昂贵功能
/sc:analyze code/ --no-mcp --answer-only
```

#### 内存或资源问题

**问题**：由于资源约束，操作失败或非常缓慢。

**解决方案**：
```bash
# 减少并发
/sc:analyze large-project/ --delegate auto --concurrency 1

# 使用安全模式
/sc:improve large-system/ --safe-mode  # 更保守的资源使用

# 将工作分解为更小块
/sc:analyze module1/
/sc:analyze module2/
/sc:analyze module3/
# 而不是 /analyze entire-project/
```

### 质量和安全问题 🛡️

#### 不安全或有风险的建议

**问题**：SuperClaude 建议似乎有风险的更改。

**始终使用安全功能**：
```bash
# 应用前预览
/sc:improve important-code/ --preview

# 对关键代码使用安全模式
/sc:improve production-auth/ --safe-mode

# 添加验证
/sc:improve system/ --validate --safe-mode

# 使用迭代方法
/sc:improve complex-system/ --loop --safe-mode
```

#### 更改破坏功能

**问题**：应用的改进导致问题。

**预防**：
```bash
# 始终首先使用预览
/sc:improve code/ --preview

# 使用安全模式
/sc:improve code/ --safe-mode

# 更改后测试
/sc:improve code/ --safe-mode && /test code/
```

**恢复**：
- 使用 git 恢复更改
- 使用 `--safe-mode` 增量应用改进
- 使用 `--validate` 在应用前检查

### 框架和集成问题 🔗

#### SuperClaude 不理解项目上下文

**问题**：建议不符合您项目的模式或约束。

**解决方案**：
```bash
# 首先加载项目上下文
/sc:load --deep --summary

# 对项目类型明确
/sc:analyze react-typescript-app/ --c7  # 在描述中包括技术栈

# 使用适当角色
/sc:analyze node-api/ --persona-backend
/sc:analyze react-ui/ --persona-frontend
```

#### 不一致结果

**问题**：同一命令在不同时间产生不同结果。

**诊断**：
```bash
# 检查什么自动激活不同
/sc:command args --introspect

# 为一致性使用显式标志
/sc:analyze code/ --persona-analyzer --think --c7  # 显式配置
```

**解决方案**：
```bash
# 对需求更明确
/sc:improve code/ --focus performance --persona-performance --safe-mode

# 使用一致标志模式
/sc:analyze --think --c7     # 您的标准彻底分析
/sc:improve --safe-mode      # 您的标准安全改进
```

### 获取帮助 🆘

#### 当您卡住时

**自我诊断步骤**：
1. 使用 `--introspect` 理解 SuperClaude 在想什么
2. 尝试命令的更简单版本
3. 用显式标志检查自动激活
4. 在命令上使用 `--help` 查看选项

**升级路径**：
```bash
# 获取框架帮助
/sc:troubleshoot "SuperClaude framework issues" --introspect

# 检查文档
/sc:help                    # 命令概览
/sc:analyze --help          # 特定命令帮助

# 测试基本功能
/sc:analyze README.md       # 简单测试
/sc:build --help           # 检查命令是否工作
```

#### 报告问题

报告问题时，包括：
- **使用的确切命令**：`/analyze code/ --think --c7`
- **预期行为**："应提供安全分析"
- **实际行为**："仅提供基本代码审查"
- **上下文**："在 Node.js 认证系统上工作"
- **SuperClaude 版本**：用 `/help` 检查

**有用调试信息**：
```bash
# 获取诊断信息
/sc:troubleshoot "describe your issue" --introspect --verbose
# → 为错误报告提供详细上下文
```

### 常见问题快速参考 📋

| 问题 | 快速修复 | 命令 |
|---------|-----------|---------|
| 太慢 | 减少范围 + 压缩 | `--scope file --uc` |
| 错误角色 | 显式覆盖 | `--persona-security` |
| 输出太多 | 使用压缩 | `--uc` |
| 风险更改 | 使用安全功能 | `--safe-mode --preview` |
| MCP 不工作 | 强制激活或禁用 | `--all-mcp` 或 `--no-mcp` |
| 不一致结果 | 使用显式标志 | `--persona-x --think --c7` |
| 上下文问题 | 加载项目上下文 | `/load --deep` |
| 令牌限制 | 启用压缩 + 委派 | `--uc --delegate auto` |

记住：当有疑问时，从简单开始并逐渐添加复杂性。使用 `--introspect` 理解 SuperClaude 在想什么，当您需要特定行为时，不要犹豫覆盖自动激活。

---

## 下一步 🔮

SuperClaude v3.0 刚从 beta 出来，我们对它意味着什么诚实：它在做的事情上效果很好，但有粗糙边缘和改进空间。以下是您可以期望随着框架演进而发生的事情。

### 当前限制（让我们诚实）⚠️

#### 我们正在处理的已知问题

**性能优化**
- 某些操作比我们希望的慢，特别是当所有 MCP 服务器激活时
- 大规模操作的令牌使用可能更高效
- 非常大的代码库（>1000 文件）上的内存使用峰值

**MCP 服务器集成**
- 服务器连接偶尔超时或变得无响应
- MCP 服务器之间的错误处理可能更顺畅
- 某些高级 MCP 功能处于实验阶段，可能不可靠

**质量门**
- 8 步验证过程有时会遗漏边缘案例
- 质量指标可能更细粒度和可操作
- 集成测试验证需要改进

**自动激活智能**
- 角色选择偶尔错过上下文线索
- 标志自动激活对简单任务可能过于激进
- 模式识别在常见场景中效果很好，但在边缘案例中挣扎

#### 我们移除了什么（以及为什么）

**Hooks 系统（v4 中回归）**
- v2 hooks 系统变得过于复杂和有错误
- 导致性能问题和不可预测行为
- 正在用更好架构从头重新设计
- 将在 v4 中回归，具有改进的可靠性和更简单的配置

**某些高级命令**
- 将 20+ 个命令合并为 16 个基本命令
- 移除了不够稳定的实验命令
- 专注于让核心命令出色，而不是拥有许多平庸命令

### 短期改进（v3.x）🔧

我们直接关注让 v3 稳定和完善：

#### 性能优化（v3.1）
- **MCP 连接池**：重用连接以减少启动开销
- **智能缓存**：缓存 MCP 结果和分析结果
- **令牌优化**：更好的压缩算法和更智能的批处理
- **资源管理**：大项目的更好内存使用

**预期影响**：常见操作的 30-50% 性能改进。

#### MCP 服务器可靠性（v3.2）
- **连接弹性**：更好地处理 MCP 服务器超时和故障
- **优雅降级**：服务器不可用时的回退策略
- **健康监控**：MCP 服务器状态的实时监控
- **错误恢复**：自动重试和恢复机制

**预期影响**：MCP 相关故障和超时减少 80%。

#### 质量门增强（v3.3）
- **细粒度指标**：更具体和可操作的质量测量
- **自定义验证**：用户可配置的质量检查
- **证据跟踪**：验证结果的更好文档
- **集成测试**：系统范围更改的改进验证

**预期影响**：对自动化改进的更高信心和更好的质量指标。

### 中期演进（v4.0）🚀

下一个主要版本将专注于智能和用户体验：

#### 重新设计的 Hooks 系统
- **事件驱动架构**：框架和 hooks 之间的清晰分离
- **性能优化**：当不使用 hooks 时对核心操作无影响
- **简单配置**：易于设置和调试
- **可扩展性**：社区 hooks 和自定义集成

#### 增强 AI 协调
- **更智能自动激活**：更好的上下文理解和工具选择
- **学习模式**：框架从您成功的工作流程中学习
- **预测性协助**：基于当前上下文建议下一步
- **个性化**：适应您的编码风格和偏好

#### 高级编排
- **动态资源分配**：基于操作复杂性的智能扩展
- **并行处理**：独立操作的真正并行化
- **上下文保留**：会话中先前工作的更好记忆
- **工作流程模板**：常见开发场景的可重用模式

#### 扩展 MCP 生态系统
- **更多服务器**：额外专业能力（数据库、云、监控）
- **社区服务器**：社区贡献 MCP 服务器的框架
- **服务器市场**：新能力的轻松发现和安装
- **本地开发**：本地运行 MCP 服务器以获得更好性能

### 长期愿景（v5.0+）🌟

展望未来，我们正在探索更雄心勃勃的改进：

#### 智能和自动化
- **上下文理解**：对项目目标和约束的深度理解
- **主动协助**：基于代码分析和项目模式的建议
- **自动化工作流程**：常见开发任务的端到端自动化
- **代码演化跟踪**：理解您的代码库如何随时间变化

#### 团队和企业功能
- **多开发人员协调**：团队感知分析和推荐
- **项目记忆**：跨会话的项目上下文持久记忆
- **策略执行**：团队编码标准的自动执行
- **分析仪表板**：开发模式和生产力洞察

#### 平台集成
- **IDE 深度集成**：与流行开发环境的本机集成
- **CI/CD 管道集成**：构建过程中自动质量检查和改进
- **云开发**：与云开发平台的集成
- **API 生态系统**：自定义集成和工具的丰富 API

### 您如何影响开发 📝

#### 反馈和使用模式
我们积极监控：
- **命令使用模式**：哪些命令最/最不有用
- **标志组合**：哪些组合在实践中效果良好
- **错误模式**：常见故障模式和用户困惑点
- **性能瓶颈**：用户在哪里体验减速

#### 社区参与
- **GitHub Issues**：错误报告和功能请求有助于优先考虑开发
- **使用示例**：真实世界使用示例告知我们的测试和优化
- **文档反馈**：文档中的差距突出改进领域
- **集成请求**：特定工具/框架集成的请求指导 MCP 开发

#### Beta 测试计划
- **早期访问**：新功能发布前测试
- **反馈循环**：对实验功能的直接输入
- **性能测试**：帮助验证跨不同环境的优化
- **用例验证**：确保新功能适用于真实开发场景

### 保持更新 📡

#### 如何保持最新
```bash
# 定期检查更新
/sc:help  # 显示当前版本和更新可用性

# 监控开发进展
# - GitHub 发布：功能公告和变更日志
# - 文档更新：新模式和最佳实践
# - 社区讨论：技巧和高级使用模式
```

#### 迁移和兼容性
- **向后兼容性**：v3.x 更新保持命令兼容性
- **配置迁移**：版本间设置的自动迁移
- **弃用警告**：更改功能的提前通知
- **迁移指南**：主要版本升级的分步指南

### 现实期望 📊

#### 从更新中期望什么
- **v3.x 更新**：错误修复、性能改进、稳定增强
- **主要版本**：新功能、架构改进、扩展能力
- **社区贡献**：额外 MCP 服务器、工作流程模式、集成

#### 不期望什么
- **完美 AI**：SuperClaude 将继续有限制和边缘案例
- **一刀切**：不同项目和团队需要不同方法
- **零学习曲线**：新功能需要学习和实验
- **神奇解决方案**：复杂问题仍然需要人类专业知识和判断

### 为 SuperClaude 做贡献 🤝

#### 帮助方式
- **错误报告**：详细报告有助于提高稳定性和可靠性
- **功能请求**：真实世界需求驱动开发优先级
- **文档**：示例、指南和澄清帮助社区
- **社区支持**：帮助其他用户建立更强大的生态系统

#### 我们最重视什么
- **诚实反馈**：积极体验和挫败感都有助于改进框架
- **真实世界使用**：SuperClaude 在实际开发工作流程中如何工作（或不工作）
- **具体示例**：具体场景比抽象功能请求更有价值
- **耐心**：记住 v3.0 刚出 beta - 改进需要时间

### 底线 🎯

SuperClaude v3.0 是一个有增长空间的坚实基础。我们致力于：
- **诚实沟通**：不过度承诺，清楚限制和时间表
- **用户驱动开发**：优先解决真实问题的功能
- **质量胜于功能**：在添加新功能之前让现有能力出色
- **社区焦点**：构建为开发社区服务的框架

我们相信 SuperClaude 可以成为软件开发工作流程更有用的工具，但这需要时间、反馈和迭代才能到达那里。我们感谢您的耐心、反馈和持续使用，因为我们一起改进框架。

**想保持参与？** 观看 GitHub 仓库，尝试新功能，并在您的工作流程中让我们知道什么有效（什么无效）。您的真实世界使用和反馈将使 SuperClaude 对开发社区真正有价值。

---

## 结论 🎉

现在您对 SuperClaude v3.0 有了全面理解 - 其组件、能力和如何有效使用它们。让我们用关键要点总结，帮助您充分利用框架。

### 关键要点 🎯

#### SuperClaude 的核心价值
SuperClaude 通过以下方式将 Claude Code 从通用 AI 助手转变为专业开发伙伴：
- **15 个专业命令** 理解开发工作流程
- **11 个专家角色** 带来领域特定知识
- **智能编排** 自动协调工具
- **质量优先方法** 保持安全和可靠性

#### 力量在于协调
SuperClaude 的力量不来自任何单一功能，而来自组件如何协同工作：
- 命令通常激活适当角色和 MCP 服务器
- 角色在多域问题上相互协调
- 编排器优化工具选择和资源使用
- 质量门确保一致、可靠的结果

#### 从简单开始，智能扩展
使用 SuperClaude 的最佳方法是渐进的：
1. **从基本命令开始** 理解核心功能
2. **相信自动激活** 学习最佳工具组合
3. **在需要特定视角时添加手动控制**
4. **随着信心增长尝试高级功能**

### 什么让 SuperClaude 不同 🌟

#### 诚实关于限制
- 我们承认 v3.0 刚出 beta，有粗糙边缘
- 我们清楚记录什么效果良好与什么是实验性的
- 我们优先考虑可靠性而非华而不实功能
- 我们提供现实时间表和期望

#### 基于证据的开发
- 所有建议由可验证数据支持
- 质量门确保更改不破坏现有功能
- 基于真实使用模式的性能优化
- 用户反馈驱动的持续改进

#### 尊重您的工作流程
- 增强现有工具而非替换它们
- 保持与标准开发实践的兼容性
- 为所有自动决策提供手动覆盖
- 从简单任务扩展到复杂企业场景

### 实用下一步 🛣️

#### 对于新用户
1. **从安装开始**：遵循[安装指南](installation-guide.md)
2. **尝试基本命令**：`/help`、`/analyze README.md`、`/build --help`
3. **探索域指南**：[命令](commands-guide.md)、[标志](flags-guide.md)、[角色](personas-guide.md)
4. **逐渐建立信心**：简单任务 → 复杂工作流程 → 高级功能

#### 对于有经验的用户
1. **优化您的工作流程**：识别对您的需求效果良好的标志组合
2. **尝试协调实验**：在复杂问题上尝试不同角色组合
3. **提供反馈**：分享在您的环境中有效（和无效）的内容
4. **探索高级功能**：波浪编排、子代理委派、内省模式

### 何时使用 SuperClaude 🤔

#### SuperClaude 擅长于
- **开发工作流程**：构建、测试、部署、文档
- **代码分析**：质量评估、安全扫描、性能优化
- **学习和理解**：解释复杂系统、入职新项目
- **质量改进**：系统重构、技术债务减少
- **多域问题**：需要多种专业知识的问题

#### 何时使用标准 Claude Code
- **简单问题**：不需要专业工具的快速解释
- **创意写作**：非技术内容创建
- **一般研究**：软件主题之外的话题
- **头脑风暴**：没有特定实施需求的开放式构思

### SuperClaude 哲学 💭

#### 人机协作
SuperClaude 旨在增强人类专业知识，而非替换它：
- **您提供上下文和目标** - SuperClaude 提供执行和专业知识
- **您做决策** - SuperClaude 提供证据和建议
- **您理解您的约束** - SuperClaude 尊重并在范围内工作
- **您拥有结果** - SuperClaude 帮助您实现更好结果

#### 持续改进
框架通过以下方式变得更好：
- **使用模式**：学习实践中什么组合效果良好
- **用户反馈**：真实世界经验驱动开发优先级
- **基于证据的优化**：工具和工作流程的数据驱动改进
- **社区贡献**：共享知识和最佳实践

### 展望未来 🔮

#### 短期（未来 6 个月）
- 性能优化使操作快 30-50%
- 改进的 MCP 服务器可靠性减少 80% 故障
- 增强质量门提供更可操作的反馈
- 基于用户问题和反馈的更好文档

#### 中期（6-18 个月）
- 重新设计的 hooks 系统，具有更好架构和性能
- 基于从使用模式中学习的更智能自动激活
- 扩展 MCP 生态系统，带社区贡献服务器
- 真正并行处理的高级编排

#### 长期愿景
- 对项目和团队工作流程的深度上下文理解
- 基于代码分析和项目模式的主动协助
- 协作开发的团队感知功能
- 与 IDE、CI/CD 和云平台的丰富集成生态系统

### 最后想法 🎉

SuperClaude v3.0 代表增强软件开发工作流程的坚实基础。虽然它不完美，仍有改进空间，但它展示了如何深思熟虑地将 AI 集成到开发实践中，而不干扰现有工作流程或替换人类专业知识。

当 SuperClaude 让您更有生产力、帮助您学习新事物或捕获您可能错过的问题时，框架就成功了。它被设计为一个有用的同事，而不是理解您工艺的替代品。

#### 谢谢 🙏

感谢您花时间彻底理解 SuperClaude。您深思熟虑的使用、对粗糙边缘的诚实反馈和耐心将让这个框架对开发社区真正有价值。

无论您偶尔使用 SuperClaude 进行特定任务，还是将其深度集成到您的日常工作流程中，我们都希望它让您的开发体验更好一点。当它不如预期工作时，请告诉我们 - 那个反馈对改进非常宝贵。

**快乐编码！** 🚀 我们很高兴看到您与 SuperClaude 作为您的开发伙伴构建什么。

---

*最后更新：2024年7月*
*SuperClaude v3.0 用户指南*

*有问题、反馈或贡献，请访问我们的 GitHub 仓库或加入社区讨论。我们总是很高兴听到用户并了解您使用框架的经验。*