version = “1.0.0” sc_version = “4.1.5”

SuperClaude 入门到精进：从零掌握 AI 辅助开发框架

💡 核心洞察：SuperClaude 不是替代 Claude Code，而是通过行为上下文注入 配置和增强 它，将 AI 辅助开发提升到全新的系统化水平。

本文将带你从零开始，逐步掌握 SuperClaude 框架，通过丰富的实战示例和完整的待办事项应用项目，真正理解和运用这个强大的 AI 辅助开发工具。

📚 目录

SuperClaude 是什么？
快速开始（5分钟上手）
核心命令详解
AI 专家角色系统
MCP 服务器集成
完整实战项目：待办事项应用
实战场景与工作流
学习路线图（4周精进计划）
最佳实践与技巧
进阶主题
资源与参考
更新日志与维护

第一部分：SuperClaude 是什么？（概念理解）

1.1 核心概念

首先，让我们明确 SuperClaude 不是什么：

❌ 不是独立软件 - 它不需要单独安装和运行 ❌ 不替代 Claude Code - 它是构建在 Claude Code 之上的增强层 ❌ 不需要额外的 AI 模型 - 使用的是你已有的 Claude API

那么，SuperClaude 是什么？

✅ 配置框架（Configuration Framework） - 通过结构化的行为配置，让 Claude Code 按照特定模式工作 ✅ 行为上下文注入（Behavioral Context Injection） - 在运行时将专家级行为模式注入到 Claude 的响应中 ✅ 能力增强层 - 将 Claude Code 从通用助手转变为专业开发平台

1.2 框架能力概览

SuperClaude 提供了四大核心能力：

能力类型	数量	说明
📝 命令	21	`/sc:` 触发的专用命令，覆盖开发全流程
🤖 专家	14	领域专精的 AI 专家角色
🎯 模式	6	上下文适应的行为模式
🔌 MCP	6	外部工具集成服务器

1.3 工作原理图解

  flowchart LR
    A[用户输入 /sc:command] --> B[Claude Code]
    B --> C[读取上下文文件]
    C --> D[行为激活]
    D --> E{需要外部工具?}
    E -->|是| F[MCP 服务器集成]
    E -->|否| G[增强响应输出]
    F --> G

    style A fill:#e1f5ff
    style G fill:#c8e6c9
    style F fill:#fff9c4

魔法是如何发生的：当你输入 /sc:brainstorm 时，Claude Code 会：

识别 /sc: 触发器
读取对应的行为配置文件（.md 格式）
激活特定的专家角色和行为模式
根据需要调用 MCP 服务器
按照框架模式生成全面、系统的响应

第二部分：快速开始（5 分钟上手）

2.1 安装方法

SuperClaude 支持三种安装方式，选择最适合你的：

方法一：pipx（推荐）

    pipx install SuperClaude && SuperClaude install

优势：隔离环境，不污染系统 Python

方法二：pip

    pip install SuperClaude && SuperClaude install

适用：已熟悉 Python 包管理的开发者

方法三：npm

    npm install -g @bifrost_inc/superclaude && superclaude install

适用：前端开发者或 Node.js 生态系统用户

2.2 验证安装

安装完成后，在 Claude Code 中测试以下命令：

    # 交互式需求发现
/sc:brainstorm "我想开发一个任务管理 Web 应用"

# 分析现有代码
/sc:analyze src/

# 生成实现方案
/sc:implement "用户认证系统"

如果这些命令能够正常工作并产生预期响应，说明安装成功！

2.3 第一个项目体验

让我们通过一个完整的开发流程体验 SuperClaude 的强大能力：

    # 1️⃣ 需求探索
/sc:brainstorm "电商网站"

# 2️⃣ 加载项目上下文（如果已有代码）
/sc:load src/

# 3️⃣ 架构分析
/sc:analyze --focus architecture

# 4️⃣ 生成实施路线图
/sc:workflow "支付集成"

# 5️⃣ 构建功能
/sc:implement "Stripe 结账"

# 6️⃣ 测试验证
/sc:test --coverage

# 7️⃣ 保存会话进度
/sc:save "支付功能完成"

预期效果：每个命令都会触发对应的专家角色，生成结构化、专业化的响应，完全不同于简单的问答模式。

第三部分：核心命令详解（21 个命令）

SuperClaude 的 21 个核心命令覆盖了软件开发的完整生命周期。让我们按功能类别深入了解它们。

3.1 开发类命令

🎯 `/sc:build` - 智能项目构建

功能：自动检测框架并优化构建过程

基础用法：

    /sc:build my-project/

高级用法：

    # 自动检测框架并验证配置
/sc:build react-app/ --validate

# 生产构建（优化、压缩）
/sc:build --prod --optimize

# 指定框架类型
/sc:build vue-app/ --framework vue

使用场景：

🆕 新项目初始化
🔧 自动检测框架（React, Vue, Next.js, Svelte 等）
⚡ 优化构建配置（Vite, Webpack, Turbopack）

实际效果：

生成符合最佳实践的项目结构
自动配置 TypeScript、ESLint、Prettier
集成测试框架（Vitest, Jest）

🎯 `/sc:implement` - 特性实现

功能：从需求到代码的完整实现，自动选择专家角色

基础用法：

    /sc:implement "用户登录功能"

高级用法：

    # 指定专家角色
/sc:implement "REST API" --persona backend

# 带测试实现
/sc:implement "数据验证" --with-tests

# 指定技术栈
/sc:implement "用户认证" --stack nextjs --with-tests

使用场景：

✨ 从用户故事到代码实现
🎨 自动选择合适的架构模式
📝 生成符合规范的代码和文档
🧪 包含单元测试和集成测试

代码示例：

    // 输入: /sc:implement "用户登录" --with-tests

// SuperClaude 会生成：
// 1. 类型定义
interface LoginCredentials {
  email: string;
  password: string;
}

interface AuthResponse {
  token: string;
  user: User;
}

// 2. API 函数
export async function login(credentials: LoginCredentials): Promise<AuthResponse> {
  const response = await fetch('/api/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(credentials),
  });

  if (!response.ok) {
    throw new Error('登录失败');
  }

  return response.json();
}

// 3. 测试用例
describe('login', () => {
  it('should authenticate user with valid credentials', async () => {
    const result = await login({
      email: 'user@example.com',
      password: 'password123',
    });

    expect(result).toHaveProperty('token');
    expect(result).toHaveProperty('user');
  });
});

🎯 `/sc:design` - 系统设计

功能：创建架构图和设计规范

基础用法：

    /sc:design "微服务架构"

高级用法：

    # 架构设计
/sc:design "系统架构" --type architecture

# 组件设计
/sc:design "用户管理组件" --type component

# API 设计（生成 OpenAPI 规范）
/sc:design "GraphQL API" --format openapi

输出内容：

📊 架构图（Mermaid 格式）
📋 设计文档
🔄 数据流图
🎨 UI/UX 建议（针对组件设计）

3.2 分析类命令

🔍 `/sc:analyze` - 全面代码分析

这是 SuperClaude 最强大的命令之一，支持多维度、多深度的代码分析。

基础用法：

    /sc:analyze auth.js

思考深度梯度：

    /sc:analyze codebase/ --think           # ~4K tokens，多文件分析
/sc:analyze codebase/ --think-hard      # ~10K tokens，深度架构分析
/sc:analyze codebase/ --ultrathink      # ~32K tokens，最大深度分析

专注特定方面：

    # 安全分析
/sc:analyze api/ --focus security

# 性能分析
/sc:analyze component/ --focus performance

# 代码质量
/sc:analyze code/ --focus quality

# 可维护性
/sc:analyze legacy/ --focus maintainability

多角色视角：

    # 架构师视角
/sc:analyze design/ --persona-architect

# 安全专家视角
/sc:analyze auth/ --persona-security

# 性能专家视角
/sc:analyze db/ --persona-performance

# QA 视角
/sc:analyze code/ --persona-qa

实际案例：

    # 输入
/sc:analyze api/auth.js --focus security --think-hard

# 输出包括：
# 1. 安全漏洞识别（SQL 注入、XSS、CSRF）
# 2. 依赖项安全审计
# 3. 敏感数据处理检查
# 4. 认证/授权机制评估
# 5. 安全改进建议（带优先级）

🔍 `/sc:troubleshoot` - 问题排查

功能：系统化诊断，为错误提供逐步解决方案

基础用法：

    /sc:troubleshoot "登录失败"

高级用法：

    # 带日志分析
/sc:troubleshoot "500 错误" --logs logs/error.log

# 系统化诊断
/sc:troubleshoot "内存泄漏" --diagnose

# 指定环境
/sc:troubleshoot "生产环境崩溃" --env production

诊断流程：

📊 收集错误信息和上下文
🔍 分析根本原因
💡 提供多个可能的解决方案
⚠️ 评估每个方案的优缺点
✅ 推荐最佳解决方案

🔍 `/sc:explain` - 教学式解释

功能：帮助理解复杂代码或概念，导师模式

基础用法：

    /sc:explain complex-function.js

高级用法：

    # 概念讲解
/sc:explain "GraphQL vs REST"

# 导师模式（详细、互动式）
/sc:explain React Hooks --persona-mentor --verbose

# 深度技术讲解
/sc:explain "JavaScript 事件循环" --depth advanced

解释风格：

📚 从基础概念开始
🎨 使用图表和类比
💻 提供实际代码示例
❓ 互动式提问和验证
🔗 提供进一步学习资源

3.3 质量类命令

✨ `/sc:improve` - 代码优化

功能：自动应用最佳实践，优化代码质量

基础用法：

    /sc:improve code.js

安全模式（推荐用于生产代码）：

    # 预览模式（先看会发生什么）
/sc:improve code.js --preview

# 安全模式（只应用安全更改）
/sc:improve production-auth/ --safe-mode --validate

# 性能优化
/sc:improve app.js --type performance --benchmark

优化类型：

    # 性能优化
/sc:improve --type performance

# 代码质量
/sc:improve --type quality

# 可读性
/sc:improve --type readability

# 安全性
/sc:improve --type security

优化示例：

    // 优化前
const getUserData = async (id) => {
  const user = await db.query('SELECT * FROM users WHERE id = ' + id);
  const posts = await db.query('SELECT * FROM posts WHERE userId = ' + id);
  const comments = await db.query('SELECT * FROM comments WHERE userId = ' + id);
  return { user, posts, comments };
};

// 优化后（使用 /sc:improve --type performance）
const getUserData = async (id: number) => {
  // 使用参数化查询防止 SQL 注入
  const [user, posts, comments] = await Promise.all([
    db.query('SELECT * FROM users WHERE id = $1', [id]),
    db.query('SELECT * FROM posts WHERE userId = $1', [id]),
    db.query('SELECT * FROM comments WHERE userId = $1', [id]),
  ]);

  // 只返回必要的字段
  return {
    user: sanitizeUser(user),
    posts: posts.map(sanitizePost),
    comments: comments.map(sanitizeComment),
  };
};

✨ `/sc:cleanup` - 技术债务清理

功能：清理冗余代码、未使用的依赖、过时的模式

基础用法：

    /sc:cleanup legacy/

波模式（系统性改进）：

    # 自动模式（分析后自动清理）
/sc:cleanup old-code/ --wave-mode auto

# 系统模式（分阶段、可回滚）
/sc:cleanup old-code/ --wave-mode systematic

# 交互模式（每个更改前询问）
/sc:cleanup old-code/ --wave-mode interactive

清理内容：

🗑️ 未使用的变量和函数
📦 未使用的依赖包
🔄 过时的 API 调用
📝 注释掉的代码
🎨 重复的代码片段

✨ `/sc:test` - 测试执行

功能：全面的测试策略和执行

测试类型：

    # 单元测试
/sc:test --type unit

# 集成测试
/sc:test --type integration

# E2E 测试（使用 Playwright）
/sc:test e2e --playwright

# 安全测试
/sc:test --type security

# 性能测试
/sc:test --type performance

覆盖率：

    # 带覆盖率报告
/sc:test --coverage

# 设置覆盖率目标
/sc:test --coverage --threshold 80

测试框架集成：

Vitest / Jest
Playwright / Cypress
React Testing Library
Supertest（API 测试）

3.4 项目管理类命令

📋 `/sc:workflow` - 工作流生成

功能：从 PRD 或需求生成结构化实施步骤

基础用法：

    /sc:workflow "用户注册功能"

高级用法：

    # 从 PRD 文件生成
/sc:workflow --from prd.md

# 指定开发方法论
/sc:workflow "支付集成" --methodology scrum

# 生成甘特图
/sc:workflow "项目启动" --gantt

输出内容：

📝 任务分解（WBS）
⏱️ 时间估算
🎯 依赖关系
📊 风险评估
✅ 验收标准

📋 `/sc:task` - 任务执行

功能：执行复杂任务，支持委托模式

基础用法：

    /sc:task "重构认证系统"

委托模式：

    # 自动委托（并行处理）
/sc:task "代码审查" --delegate auto

# 手动委托
/sc:task "性能优化" --delegate parallel

📋 `/sc:git` - Git 操作

功能：智能提交和分支策略

智能提交：

    /sc:git --smart-commit

分支策略：

    /sc:git --branch-strategy gitflow

生成的提交信息：

遵循 Conventional Commits 规范
自动分析更改内容
生成详细的提交描述

3.5 学习类命令

🧠 `/sc:brainstorm` - 需求发现

功能：交互式需求探索，Socratic 对话

基础用法：

    /sc:brainstorm "项目管理应用"

深度探索：

    /sc:brainstorm "SaaS 平台" --depth deep

探索维度：

💡 功能需求
🎯 用户场景
⚠️ 技术挑战
💰 商业价值
🔄 竞争分析

🧠 `/sc:explain` - 代码讲解

已在分析类命令中详细说明。

🧠 `/sc:learn` - 学习资源

功能：获取学习路径和官方文档参考

基础用法：

    /sc:learn "React Server Components"

高级用法：

    # 获取官方文档
/sc:learn --docs

# 生成学习路径
/sc:learn "TypeScript" --roadmap

# 获取最佳实践
/sc:learn "Next.js" --best-practices

3.6 其他重要命令

📂 `/sc:load` - 加载项目上下文

功能：导入项目结构，生成上下文摘要

基础用法：

    /sc:load src/

深度加载：

    # 深度加载（生成摘要）
/sc:load --deep --summary

# 指定范围
/sc:load components/ --scope module

# 排除目录
/sc:load src/ --exclude node_modules,dist

💾 `/sc:save` - 保存会话

功能：持久化会话上下文，便于后续恢复

基础用法：

    /sc:save "功能开发完成"

带标签保存：

    /sc:save "bug 修复" --tags fix,auth,critical

会话管理：

自动保存对话历史
保存项目上下文
保存未完成任务
生成会话报告

📑 `/sc:index` - 项目文档生成

功能：生成项目索引和知识库

基础用法：

    /sc:index

生成类型：

    # 项目索引
/sc:index --type project

# 知识库
/sc:index --type knowledge-base

# API 文档
/sc:index --type api

📄 `/sc:document` - 文档生成

功能：为代码生成各类文档

基础用法：

    /sc:document Button.jsx

文档类型：

    # 组件文档
/sc:document Button.jsx --type component

# API 文档（OpenAPI）
/sc:document api/ --type openapi

# 指南文档
/sc:document features/ --type guide

# README
/sc:document --type readme

🎯 `/sc:recommend` - 命令推荐

功能：获取最适合当前任务的命令建议

基础用法：

    /sc:recommend "重构代码"

列出所有推荐命令：

    /sc:recommend --list

❓ `/sc:help` - 帮助信息

功能：查看命令详情和使用方法

基础用法：

    /sc:help

# 查看特定命令
/sc:help /sc:implement

# 按类别查看
/sc:help --category analysis
/sc:help --category development

第四部分：AI 专家角色系统

SuperClaude 的 14 个 AI 专家角色是其核心优势之一，每个专家都在特定领域具有深度专精。

4.1 专家角色列表

🏗️ 架构类

角色	专精领域	自动触发场景
`@agent-architect`	系统架构设计、技术栈选择	`/sc:design --type architecture`
`@agent-design`	设计系统、UI/UX、组件设计	`/sc:design --type component`

💻 开发类

角色	专精领域	自动触发场景
`@agent-frontend`	React, Vue, 前端性能优化	分析 `.jsx`, `.vue`, `.tsx` 文件
`@agent-backend`	Node.js, Python, API 设计	分析 `.js`（后端）, `.py` 文件
`@agent-devops`	CI/CD, Docker, K8s, 部署	`/sc:build --prod`, DevOps 相关任务

🔒 质量类

角色	专精领域	自动触发场景
`@agent-security`	安全审计、漏洞检测	`/sc:analyze --focus security`
`@agent-qa`	测试策略、质量保证	`/sc:test`, `/sc:analyze --focus quality`
`@agent-performance`	性能优化、瓶颈分析	`/sc:analyze --focus performance`

📊 管理类

角色	专精领域	自动触发场景
`@agent-project-manager`	项目协调、需求管理	默认协调者，`/sc:workflow`
`@agent-scribe`	文档撰写、技术写作	`/sc:document`

🔬 分析类

角色	专精领域	自动触发场景
`@agent-analyst`	数据分析、指标追踪	数据相关任务

🎓 其他

角色	专精领域	自动触发场景
`@agent-mentor`	教学解释、概念讲解	`/sc:explain --persona-mentor`
`@agent-researcher`	技术研究、方案调研	`/sc:brainstorm` 深度模式

4.2 自动激活 vs 手动指定

自动激活（推荐）：

    # 分析认证代码 → 自动激活安全专家
/sc:analyze auth.js

# 分析 React 组件 → 自动激活前端专家
/sc:analyze Button.jsx

# 分析 API 端点 → 自动激活后端专家
/sc:analyze api/users.js

手动指定：

    # 强制使用架构师视角
/sc:analyze design/ --persona-architect

# 强制使用安全专家视角
/sc:analyze code/ --persona-security

# 强制使用性能专家视角
/sc:analyze api/ --persona-performance

4.3 多角色协作

通过组合不同专家角色，可以获得多维度的分析：

    # API 设计的多维度评估
/sc:analyze api/ --persona-architect     # 架构可行性
/sc:analyze api/ --persona-security      # 安全性
/sc:analyze api/ --persona-performance   # 性能
/sc:analyze api/ --persona-qa            # 可测试性

第五部分：MCP 服务器集成

MCP（Model Context Protocol）服务器为 SuperClaude 提供了强大的外部工具集成能力。

5.1 可用的 MCP 服务器

服务器	用途	自动触发场景
Context7	文档和最佳实践查询	`/sc:build`, 框架相关问题
Sequential	复杂推理和分析	`/sc:troubleshoot`, 深度分析
Magic	UI 组件生成	`/sc:build`（前端项目）
Playwright	E2E 测试	`/sc:test e2e`
Morphllm	大规模内容处理	大型代码库分析
Serena	跨会话持久化	`/sc:load`, `/sc:save`

5.2 自动集成示例

Context7 集成：

    # 自动查询 React 最佳实践
/sc:build react-app/

# Context7 会：
# 1. 查询 React 官方文档
# 2. 获取最新最佳实践
# 3. 应用推荐的项目结构
# 4. 配置推荐的工具链

Sequential 集成：

    # 自动使用复杂推理
/sc:troubleshoot "登录失败但无错误日志"

# Sequential 会：
# 1. 分析可能的错误原因
# 2. 生成诊断假设
# 3. 提供验证步骤
# 4. 逐步排除可能性

Magic 集成：

    # 自动生成 UI 组件
/sc:build dashboard

# Magic 会：
# 1. 分析设计需求
# 2. 生成组件代码
# 3. 创建响应式样式
# 4. 集成到项目中

5.3 配置 MCP 服务器

详细的 MCP 服务器配置请参考官方文档：SuperClaude MCP 配置指南

第六部分：完整实战项目：待办事项应用

让我们通过一个完整的待办事项应用项目，演示 SuperClaude 的全部能力。

6.1 项目概览

项目目标：构建一个功能完整的待办事项 Web 应用

技术栈：

🎨 前端：React 18 + TypeScript + Vite
🗃️ 状态管理：Zustand
💅 样式：Tailwind CSS
🧪 测试：Vitest + React Testing Library
📦 构建工具：Vite

核心功能：

✅ 添加/删除/编辑任务
🔄 任务状态切换（待办/完成）
🏷️ 任务分类和标签
🔍 搜索和过滤
💾 本地存储持久化
🌙 深色模式切换
📱 响应式设计

6.2 完整开发流程

步骤 1：需求发现

    /sc:brainstorm "待办事项应用"

SuperClaude 会引导你探索：

核心功能需求
用户体验设计
技术栈选择
潜在技术挑战
扩展性考虑

输出示例：

    ## 需求探索结果

### 核心功能
- ✅ 任务 CRUD 操作
- 🏷️ 分类和标签系统
- 🔍 搜索和过滤
- 💾 数据持久化

### 用户体验
- 🎯 简洁直观的界面
- ⚡ 快速响应
- 📱 移动端友好
- 🌙 深色模式支持

### 技术建议
- React 18（现代特性）
- TypeScript（类型安全）
- Zustand（轻量状态管理）
- Tailwind CSS（快速开发）

### 技术挑战
- ⚠️ 状态同步
- ⚠️ 性能优化（大数据量）
- ⚠️ 离线支持

步骤 2：系统设计

    /sc:design "待办应用架构" --type architecture

设计输出：

组件层次结构：

  graph TD
    A[App] --> B[TodoProvider]
    B --> C[TodoHeader]
    B --> D[TodoInput]
    B --> E[TodoList]
    B --> F[TodoFilter]
    E --> G[TodoItem]
    G --> H[TodoContent]
    G --> I[TodoActions]

数据流设计：

  flowchart LR
    A[User Action] --> B[Event Handler]
    B --> C[Zustand Store]
    C --> D[State Update]
    D --> E[React Re-render]
    E --> F[localStorage Sync]

步骤 3：项目初始化

    /sc:build todo-app/ --framework react --with-typescript

生成的项目结构：

    todo-app/
├── src/
│   ├── components/          # UI 组件
│   │   ├── TodoHeader.tsx
│   │   ├── TodoInput.tsx
│   │   ├── TodoList.tsx
│   │   ├── TodoItem.tsx
│   │   └── TodoFilter.tsx
│   ├── stores/              # Zustand 状态管理
│   │   └── todoStore.ts
│   ├── hooks/               # 自定义 Hooks
│   │   └── useTodos.ts
│   ├── utils/               # 工具函数
│   │   └── storage.ts
│   ├── types/               # TypeScript 类型
│   │   └── todo.ts
│   ├── App.tsx
│   └── main.tsx
├── public/
├── tests/
│   ├── components/
│   └── utils/
├── package.json
├── tsconfig.json
├── vite.config.ts
└── tailwind.config.js

步骤 4：核心功能实现

4.1 任务数据模型

    /sc:implement "Todo 类型定义和接口" --with-tests

生成的代码：

    // src/types/todo.ts
export interface Todo {
  id: string;
  title: string;
  description?: string;
  completed: boolean;
  category: string;
  tags: string[];
  priority: 'low' | 'medium' | 'high';
  createdAt: Date;
  completedAt?: Date;
  dueDate?: Date;
}

export interface TodoFilter {
  search: string;
  category: string;
  tags: string[];
  status: 'all' | 'active' | 'completed';
}

export interface TodoStore {
  todos: Todo[];
  filter: TodoFilter;
  // Actions
  addTodo: (todo: Omit<Todo, 'id' | 'createdAt'>) => void;
  updateTodo: (id: string, updates: Partial<Todo>) => void;
  deleteTodo: (id: string) => void;
  toggleTodo: (id: string) => void;
  setFilter: (filter: Partial<TodoFilter>) => void;
  clearCompleted: () => void;
}

4.2 状态管理

    /sc:implement "Zustand todo store" --persona-frontend

    // src/stores/todoStore.ts
import { create } from 'zustand';
import { persist } from 'zustand/middleware';
import type { Todo, TodoStore } from '../types/todo';

export const useTodoStore = create<TodoStore>()(
  persist(
    (set, get) => ({
      todos: [],
      filter: {
        search: '',
        category: '',
        tags: [],
        status: 'all',
      },

      addTodo: (todo) => {
        const newTodo: Todo = {
          ...todo,
          id: crypto.randomUUID(),
          createdAt: new Date(),
        };
        set((state) => ({ todos: [...state.todos, newTodo] }));
      },

      updateTodo: (id, updates) =>
        set((state) => ({
          todos: state.todos.map((todo) =>
            todo.id === id ? { ...todo, ...updates } : todo
          ),
        })),

      deleteTodo: (id) =>
        set((state) => ({
          todos: state.todos.filter((todo) => todo.id !== id),
        })),

      toggleTodo: (id) =>
        set((state) => ({
          todos: state.todos.map((todo) =>
            todo.id === id
              ? {
                  ...todo,
                  completed: !todo.completed,
                  completedAt: !todo.completed ? new Date() : undefined,
                }
              : todo
          ),
        })),

      setFilter: (filter) =>
        set((state) => ({
          filter: { ...state.filter, ...filter },
        })),

      clearCompleted: () =>
        set((state) => ({
          todos: state.todos.filter((todo) => !todo.completed),
        })),
    }),
    {
      name: 'todo-storage',
    }
  )
);

4.3 UI 组件

    /sc:implement "TodoList 组件" --persona-frontend
/sc:implement "TodoItem 组件" --persona-frontend
/sc:implement "AddTodoForm 组件" --persona-frontend

TodoList 组件示例：

    // src/components/TodoList.tsx
import { useTodoStore } from '../stores/todoStore';
import { TodoItem } from './TodoItem';
import { useMemo } from 'react';

export function TodoList() {
  const { todos, filter } = useTodoStore();

  const filteredTodos = useMemo(() => {
    return todos.filter((todo) => {
      // 搜索过滤
      if (filter.search && !todo.title.toLowerCase().includes(filter.search.toLowerCase())) {
        return false;
      }

      // 分类过滤
      if (filter.category && todo.category !== filter.category) {
        return false;
      }

      // 状态过滤
      if (filter.status === 'active' && todo.completed) return false;
      if (filter.status === 'completed' && !todo.completed) return false;

      return true;
    });
  }, [todos, filter]);

  return (
    <ul className="space-y-2">
      {filteredTodos.map((todo) => (
        <TodoItem key={todo.id} todo={todo} />
      ))}
    </ul>
  );
}

4.4 样式系统

    /sc:implement "Tailwind 配置和深色模式" --persona-frontend

    // tailwind.config.js
/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#f0f9ff',
          100: '#e0f2fe',
          500: '#0ea5e9',
          600: '#0284c7',
          700: '#0369a1',
        },
      },
    },
  },
  plugins: [],
};

步骤 5：功能完善

5.1 搜索和过滤

    /sc:implement "搜索过滤功能" --with-tests

5.2 本地持久化

    /sc:implement "localStorage 持久化" --focus performance

5.3 响应式设计

    /sc:implement "移动端适配" --persona-frontend

步骤 6：测试

    /sc:test --coverage
/sc:test e2e --playwright

生成的测试示例：

    // tests/components/TodoItem.test.tsx
import { describe, it, expect } from 'vitest';
import { render, screen, fireEvent } from '@testing-library/react';
import { TodoItem } from '@/components/TodoItem';
import { useTodoStore } from '@/stores/todoStore';

describe('TodoItem', () => {
  it('should render todo title', () => {
    const todo = {
      id: '1',
      title: 'Test Todo',
      completed: false,
      category: 'personal',
      tags: [],
      priority: 'medium' as const,
      createdAt: new Date(),
    };

    render(<TodoItem todo={todo} />);
    expect(screen.getByText('Test Todo')).toBeInTheDocument();
  });

  it('should toggle todo completion', () => {
    const todo = {
      id: '1',
      title: 'Test Todo',
      completed: false,
      category: 'personal',
      tags: [],
      priority: 'medium' as const,
      createdAt: new Date(),
    };

    render(<TodoItem todo={todo} />);

    const checkbox = screen.getByRole('checkbox');
    fireEvent.click(checkbox);

    const store = useTodoStore.getState();
    expect(store.todos.find((t) => t.id === '1')?.completed).toBe(true);
  });
});

步骤 7：代码质量检查

    /sc:analyze --focus quality
/sc:analyze --focus security
/sc:analyze --focus performance --persona-performance

步骤 8：代码优化

    /sc:improve src/ --type performance --benchmark
/sc:improve src/ --type quality --validate

步骤 9：生产构建

    /sc:build --prod --optimize
/sc:test --type security

步骤 10：文档生成

    /sc:document components/ --type guide
/sc:document --type readme
/sc:index

步骤 11：部署准备

    /sc:build --static --analyze-bundle
/sc:git --smart-commit

6.3 项目时间线

阶段	时间	主要命令	产出
需求分析	30分钟	`/sc:brainstorm`, `/sc:design`	需求文档、架构设计
项目初始化	15分钟	`/sc:build`	项目骨架
核心开发	2-3小时	`/sc:implement` × 8	完整功能实现
测试	1小时	`/sc:test`, `/sc:analyze`	测试报告、质量分析
优化	1小时	`/sc:improve`	性能优化、代码改进
文档	30分钟	`/sc:document`, `/sc:index`	项目文档
部署	15分钟	`/sc:build --prod`	生产构建

总计：约 5-6 小时完成完整项目

第七部分：实战场景与工作流

7.1 新项目启动工作流

    # 1. 需求发现
/sc:brainstorm "任务管理 SaaS 应用"

# 2. 架构设计
/sc:design "系统架构" --type architecture

# 3. 项目初始化
/sc:build task-manager/ --framework nextjs

# 4. 核心功能实现
/sc:implement "用户认证"
/sc:implement "任务 CRUD"
/sc:implement "团队协作"

# 5. 测试
/sc:test --coverage

# 6. 保存进度
/sc:save "MVP 完成"

7.2 代码审查工作流

    # 1. 质量分析
/sc:analyze pr/ --persona-qa --focus quality

# 2. 安全审查
/sc:analyze pr/ --persona-security --focus security

# 3. 性能检查
/sc:analyze pr/ --persona-performance --focus performance

# 4. 文档生成
/sc:document pr/ --type changelog

# 5. 智能提交
/sc:git --smart-commit

7.3 Bug 修复工作流

    # 1. 问题诊断
/sc:troubleshoot "登录失败" --logs

# 2. 深度分析
/sc:analyze auth/ --think-hard --focus debugging

# 3. 修复实施
/sc:implement "修复登录 bug" --safe-mode --validate

# 4. 回归测试
/sc:test --type unit auth/
/sc:test e2e --playwright

# 5. 保存
/sc:save "bug-fix-login"

7.4 遗留系统现代化

    # 1. 深度架构分析
/sc:analyze legacy/ --persona-architect --ultrathink

# 2. 现代化规划
/sc:design modernization-strategy --type architecture

# 3. 迭代改进（波模式）
/sc:improve legacy/ --wave-mode systematic --safe-mode --loop

# 4. 文档更新
/sc:index
/sc:document legacy/ --type guide

7.5 安全优先开发

    # 1. 安全设计
/sc:design "认证系统" --focus security

# 2. 安全实现
/sc:implement "JWT 认证" --persona-security

# 3. 安全审查
/sc:analyze auth/ --persona-security --focus security

# 4. 安全测试
/sc:test --type security

# 5. 合规检查
/sc:analyze --persona-security --compliance gdpr

第八部分：学习路线图（4 周精进计划）

第 1 周：核心命令掌握

学习重点：

/sc:brainstorm - 需求探索
/sc:analyze - 代码分析
/sc:implement - 功能实现

练习任务：

完成待办事项应用项目
使用基础命令完成开发周期
熟悉命令参数和标志

学习目标：

✅ 独立完成第一个项目
✅ 理解 SuperClaude 工作原理
✅ 掌握核心命令的基本用法

第 2 周：行为模式和标志

学习重点：

思考深度标志（--think, --think-hard, --ultrathink）
专注标志（--focus security, --focus performance）
预览和安全模式（--preview, --safe-mode）

练习任务：

使用不同深度分析同一代码库
组合多个专注标志
使用预览模式测试改进

学习目标：

✅ 优化个人工作流
✅ 理解不同标志的使用场景
✅ 掌握高级参数组合

第 3 周：MCP 服务器集成

学习重点：

配置和使用 MCP 服务器
理解自动集成机制
工具选择和组合

练习任务：

配置 Context7 获取框架文档
使用 Playwright 进行 E2E 测试
使用 Magic 生成 UI 组件

学习目标：

✅ 充分利用外部工具
✅ 理解 MCP 工作原理
✅ 配置自定义 MCP 服务器

第 4 周：高级模式和精通

学习重点：

自定义工作流
会话管理（/sc:load, /sc:save）
团队协作模式
波模式系统改进

练习任务：

创建个人专属工作流
管理多个项目会话
设计团队协作规范

学习目标：

✅ 框架精通
✅ 可以指导他人使用
✅ 设计团队工作流程

第九部分：最佳实践与技巧

9.1 命令使用习惯

从简单开始，按需添加复杂度

    # 基础
/sc:analyze code.js

# 添加深度
/sc:analyze code.js --think

# 添加文档参考
/sc:analyze code.js --think --c7

使用安全模式

    # 生产代码总是先预览
/sc:improve production-auth/ --safe-mode --validate --preview

选择适当的作用域

    # 文件级
/sc:analyze single-component.js

# 模块级
/sc:analyze user-auth/

# 项目级
/sc:analyze --scope project

9.2 效率最大化技巧

让自动激活先工作

先使用基本命令，观察 SuperClaude 如何自动选择工具和专家。只在需要特定视角时才手动覆盖。

使用预览和安全模式

    # 先查看会发生什么
/sc:improve code.js --preview

# 确认后再应用安全更改
/sc:improve code.js --safe-mode

大型操作的令牌管理

    # 压缩输出并并行处理
/sc:analyze huge-codebase/ --uc --delegate auto

使用导师角色学习

    # 学习新概念时使用导师模式
/sc:explain GraphQL --persona-mentor --verbose

9.3 避免常见错误

过度使用高级标志 - 不是所有任务都需要 --ultrathink
忽略预览模式 - 在生产代码上总是先使用 --preview
手动指定专家 - 让系统自动激活，除非有特殊需求
跳过会话保存 - 使用 /sc:save 保持上下文连续性

第十部分：进阶主题

10.1 SuperClaude vs 标准 Claude Code

使用 SuperClaude ✅	使用标准 Claude 💭
构建完整软件项目	简单问题或解释
系统化工作流和质量门控	一次性编码任务
复杂、多组件系统	学习编程概念
长期项目需要持久化	快速原型或实验
团队协作和标准	代码片段生成
领域专精需求	通用编程帮助

10.2 理解行为上下文注入

SuperClaude 通过 .md 文件注入行为：

触发器：/sc: 和 @agent-
激活：读取对应的 .md 上下文文件
响应：按照框架模式生成全面响应

10.3 自定义和扩展

详细的自定义配置请参考官方文档。

第十一部分：资源与参考

11.1 官方资源

GitHub 仓库：SuperClaude-Org/SuperClaude_Framework
快速开始：Quick Start Guide
命令参考：Commands Guide
PyPI：pypi.org/project/superclaude/
NPM：@bifrost_inc/superclaude

11.2 社区资源

中文指南：SuperClaude 核心命令快捷键指南
YouTube：Claude Code Done Right | The SuperClaude Method
Medium：A Tool to Supercharge Claude Code
Reddit：SuperClaude and claude code discussion

11.3 相关工具

Claude Code：anthropics/claude-code
Claude Code Best Practices：Official Guide
Claude Code Cheat Sheet：GitHub

版本控制与更新策略

📝 更新日志

v1.0.0 (2026-01-12)

✨ 初始版本发布
📚 完整的 11 部分教程
🎯 包含完整实战项目（待办事项应用）
💡 最佳实践和技巧
🔄 版本管理和更新策略

最近重大更新：2026-01-12 下次计划更新：2026-Q2（跟随 SuperClaude 新版本） SuperClaude 版本：4.1.5 教程版本：1.0.0

🤝 贡献指南

发现错误或有改进建议？欢迎贡献！

🐛 报告问题：GitHub Issues
💡 提出建议：在文章下方评论
✍️ 改进文档：提交 Pull Request

⚠️ 注意事项

保持更新 - SuperClaude 版本更新快，需定期检查新功能
实践为主 - 鼓励读者边学边做
社区贡献 - 欢迎反馈和补充
官方为准 - 最终以官方文档为准

🎯 总结

SuperClaude 是一个强大的 AI 辅助开发框架，通过系统化的命令、专家角色和 MCP 集成，将 Claude Code 提升到了全新的水平。

通过本教程，你学会了：

✅ SuperClaude 的核心概念和工作原理
✅ 21 个核心命令的使用方法
✅ 14 个 AI 专家角色的应用场景
✅ MCP 服务器的集成能力
✅ 完整项目的开发流程
✅ 实战场景的工作流组合
✅ 4 周循序渐进的学习路线
✅ 最佳实践和效率技巧

下一步行动：

安装 SuperClaude：pipx install SuperClaude && SuperClaude install
完成待办事项应用项目
按照 4 周学习路线逐步精进
加入社区，分享你的经验

祝你在 AI 辅助开发的旅程中一帆风顺！🚀

Sources:

SuperClaude 入门到精进：从零掌握 AI 辅助开发框架

📚 目录

第一部分：SuperClaude 是什么？（概念理解）

1.1 核心概念

1.2 框架能力概览

1.3 工作原理图解

第二部分：快速开始（5 分钟上手）

2.1 安装方法

方法一：pipx（推荐）

方法二：pip

方法三：npm

2.2 验证安装

2.3 第一个项目体验

第三部分：核心命令详解（21 个命令）

3.1 开发类命令

🎯 /sc:build - 智能项目构建

🎯 /sc:implement - 特性实现

🎯 /sc:design - 系统设计

3.2 分析类命令

🔍 /sc:analyze - 全面代码分析

🔍 /sc:troubleshoot - 问题排查

🔍 /sc:explain - 教学式解释

3.3 质量类命令

✨ /sc:improve - 代码优化

✨ /sc:cleanup - 技术债务清理

✨ /sc:test - 测试执行

3.4 项目管理类命令

📋 /sc:workflow - 工作流生成

📋 /sc:task - 任务执行

📋 /sc:git - Git 操作

3.5 学习类命令

🧠 /sc:brainstorm - 需求发现

🧠 /sc:explain - 代码讲解

🧠 /sc:learn - 学习资源

3.6 其他重要命令

📂 /sc:load - 加载项目上下文

💾 /sc:save - 保存会话

📑 /sc:index - 项目文档生成

📄 /sc:document - 文档生成

🎯 /sc:recommend - 命令推荐

❓ /sc:help - 帮助信息

第四部分：AI 专家角色系统

4.1 专家角色列表

🏗️ 架构类

💻 开发类

🔒 质量类

📊 管理类

🔬 分析类

🎓 其他

4.2 自动激活 vs 手动指定

4.3 多角色协作

第五部分：MCP 服务器集成

5.1 可用的 MCP 服务器

5.2 自动集成示例

5.3 配置 MCP 服务器

第六部分：完整实战项目：待办事项应用

6.1 项目概览

6.2 完整开发流程

步骤 1：需求发现

步骤 2：系统设计

步骤 3：项目初始化

步骤 4：核心功能实现

4.1 任务数据模型

4.2 状态管理

4.3 UI 组件

4.4 样式系统

步骤 5：功能完善

5.1 搜索和过滤

5.2 本地持久化

5.3 响应式设计

步骤 6：测试

步骤 7：代码质量检查

步骤 8：代码优化

步骤 9：生产构建

步骤 10：文档生成

步骤 11：部署准备

6.3 项目时间线

第七部分：实战场景与工作流

7.1 新项目启动工作流

7.2 代码审查工作流

🎯 `/sc:build` - 智能项目构建

🎯 `/sc:implement` - 特性实现

🎯 `/sc:design` - 系统设计

🔍 `/sc:analyze` - 全面代码分析

🔍 `/sc:troubleshoot` - 问题排查

🔍 `/sc:explain` - 教学式解释

✨ `/sc:improve` - 代码优化

✨ `/sc:cleanup` - 技术债务清理

✨ `/sc:test` - 测试执行

📋 `/sc:workflow` - 工作流生成

📋 `/sc:task` - 任务执行

📋 `/sc:git` - Git 操作

🧠 `/sc:brainstorm` - 需求发现

🧠 `/sc:explain` - 代码讲解

🧠 `/sc:learn` - 学习资源

📂 `/sc:load` - 加载项目上下文

💾 `/sc:save` - 保存会话

📑 `/sc:index` - 项目文档生成

📄 `/sc:document` - 文档生成

🎯 `/sc:recommend` - 命令推荐

❓ `/sc:help` - 帮助信息