SuperClaude Framework 完整教程

项目仓库: SuperClaude-Org/SuperClaude_Framework

📝 前言

除了 Everything Claude Code，另一个值得关注的增强框架是 SuperClaude Framework。它是一个元编程配置框架，通过行为指令注入和组件编排，将 Claude Code 转换为结构化开发平台。无论是 30 个斜杠命令、PM Agent 模式，还是深度网络研究能力，SuperClaude 都能为你的开发工作带来全新的体验。

SuperClaude Framework 是一个元编程配置框架，通过行为指令注入和组件编排，将 Claude Code 转换为结构化开发平台。它提供系统化的工作流自动化，配备强大的工具和智能代理。

核心功能： - 🚀 30 个斜杠命令覆盖完整开发生命周期 - 🤖 PM Agent 模式实现智能项目管理 - 🔍 深度网络研究能力 - ⚡ 令牌高效的并行执行（3.5 倍速度提升） - 🛡️ 预执行置信度检查和后实现验证 - 🧠 跨会话学习能力

二、核心特性

2.1 行为指令注入

通过 CLAUDE.md 文件注入行为指令，定制 Claude Code 的工作方式。

2.2 PM Agent 模式

PM Agent 是核心组件，自动完成： - 上下文恢复 - 任务委托给不同角色 - PDCA 循环（Plan-Do-Check-Act） - 会话进度保存

示例：当你说"我想添加认证"时，PM Agent 会： 1. 激活头脑风暴模式 2. 委托给需求分析师、系统架构师、安全工程师等角色 3. 生成完整的实施方案

2.3 七种自适应行为模式

头脑风暴：提出正确问题
商业面板：多专家战略分析
深度研究：自主网络研究
编排：高效工具协调
令牌效率：30-50% 上下文节省
任务管理：系统化组织
内省：元认知分析

2.4 质量保证机制

预执行置信度检查：防止错误方向的工作
后实现验证：防止幻觉
跨会话学习：通过反射模式实现

三、快速开始

3.1 前提条件

确保系统满足以下要求： - Python: 3.10+ - Node.js: 18+ (如果使用 npm 安装) - Claude CLI: 最新版本 - pipx: 最新版本 (推荐) - Docker: (可选，用于 AIRIS MCP Gateway)

3.2 安装依赖

# 安装 pipx (macOS/Linux)
python -m pip install --user pipx
python -m pipx ensurepath

# 安装 Claude CLI
npm install -g @anthropic-ai/claude-cli

3.3 安装 SuperClaude

方法一: pipx 安装（推荐）

# 1. 安装 SuperClaude 包
pipx install superclaude

# 2. 安装斜杠命令
superclaude install

# 3. 验证安装
superclaude install --list
superclaude doctor

方法二: NPM 安装

# 安装 NPM 包（会自动安装 Python 包和命令）
npm install -g @bifrost_inc/superclaude

# 验证安装
which superclaude
superclaude doctor

方法三: Git 仓库安装

# 克隆仓库
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework

# 运行安装脚本
chmod +x install.sh
./install.sh

四、配置 MCP 服务器（可选）

MCP (Model Context Protocol) 服务器可以提供更快的执行速度和更少的 token 消耗。

4.1 交互式安装

1 2	# 交互式选择要安装的 MCP 服务器 superclaude mcp

4.2 列出可用服务器

1	superclaude mcp --list

4.3 安装特定服务器

1 2	# 安装 Tavily (网络搜索) 和 Context7 (官方文档) superclaude mcp --servers tavily --servers context7

4.4 AIRIS MCP Gateway（推荐）

AIRIS Gateway 需要 Docker，提供以下服务： - Serena: 代码理解 - Sequential: 推理 - Tavily: 网络搜索

安装过程会自动： 1. 检查 Docker 2. 创建相关目录 3. 下载 docker-compose.yml 4. 启动容器 5. 向 Claude Code 注册

五、30 个斜杠命令

所有命令都使用 /sc: 前缀，避免与用户自定义命令冲突。

5.1 命令分类

编排 (Orchestration)

命令	说明	示例
`/sc:pm`	项目管理	`/sc:pm "添加用户认证功能"`
`/sc:spawn`	生成子任务	`/sc:spawn "实现 API 端点"`
`/sc:task`	任务跟踪	`/sc:task list`
`/sc:workflow`	工作流管理	`/sc:workflow create`

发现 (Discovery)

命令	说明	示例
`/sc:brainstorm`	结构化头脑风暴	`/sc:brainstorm "如何优化性能"`
`/sc:research`	深度网络研究	`/sc:research "React 18 新特性"`

实现 (Implementation)

命令	说明	示例
`/sc:implement`	代码实现	`/sc:implement "添加 JWT 认证"`
`/sc:design`	系统架构设计	`/sc:design "微服务架构"`

质量 (Quality)

命令	说明	示例
`/sc:analyze`	代码分析	`/sc:analyze src/`
`/sc:troubleshoot`	故障排查	`/sc:troubleshoot "API 超时"`
`/sc:test`	测试生成和执行	`/sc:test --coverage`
`/sc:build`	构建项目	`/sc:build --production`

改进 (Improvement)

命令	说明	示例
`/sc:improve`	代码改进	`/sc:improve src/utils.py`
`/sc:cleanup`	代码清理	`/sc:cleanup --unused`

文档 (Documentation)

命令	说明	示例
`/sc:explain`	代码解释	`/sc:explain src/auth.py`
`/sc:document`	文档生成	`/sc:document src/`
`/sc:index-repo`	仓库索引	`/sc:index-repo`

专家面板 (Expert Panels)

命令	说明	示例
`/sc:spec-panel`	规范专家面板	`/sc:spec-panel "API 设计"`
`/sc:business-panel`	商业专家面板	`/sc:business-panel "产品策略"`

实用工具 (Utilities)

命令	说明	示例
`/sc:git`	Git 操作	`/sc:git commit`
`/sc:estimate`	工作量估算	`/sc:estimate "新功能"`
`/sc:reflect`	反思和学习	`/sc:reflect`
`/sc:load`	加载上下文	`/sc:load session.json`
`/sc:save`	保存上下文	`/sc:save session.json`
`/sc:agent`	启动 AI 代理	`/sc:agent --type researcher`
`/sc:recommend`	命令推荐	`/sc:recommend`
`/sc`	显示帮助	`/sc`

六、核心命令详解

6.1 /sc:research - 深度网络研究

用于进行深度网络研究，支持并行搜索。如果安装了 Tavily MCP 服务器，研究能力会得到增强。

使用场景： - 技术调研 - 最佳实践研究 - 竞品分析 - 新技术学习

示例：

# 研究 React 18 新特性
/sc:research React 18 new features

# 研究 LLM Agent 架构
/sc:research LLM agent architectures 2024

# 研究 Python 异步最佳实践
/sc:research Python async best practices

6.2 /sc:implement - 代码实现

用于编写代码以实现功能，支持多种编程语言和框架。

使用场景： - 新功能开发 - API 端点实现 - 组件创建 - 数据层重构

示例：

# 添加 JWT 认证
/sc:implement "Add user authentication to the API using JWT"

# 创建 React 组件
/sc:implement "Create a new React component for a user profile page"

6.3 /sc:test - 测试生成和执行

用于生成测试和执行测试，包括覆盖率分析。如果安装了 Playwright MCP 服务器，可以进行 E2E 测试。

示例：

# 运行所有测试
/sc:test

# 测试特定目录并生成覆盖率报告
/sc:test src/components --type unit --coverage

# 运行 E2E 测试（需要 Playwright MCP）
/sc:test --type e2e

6.4 /sc:pm - 项目管理

启动 PM Agent 模式，自动管理项目开发流程。

使用场景： - 复杂功能开发 - 多步骤任务 - 需要多角色协作的任务

示例：

# 添加用户认证功能
/sc:pm "添加用户认证功能"

# 优化数据库性能
/sc:pm "优化数据库查询性能"

PM Agent 工作流程： 1. 理解需求 2. 激活相应的行为模式 3. 委托给专家角色（需求分析师、架构师、开发者等） 4. 执行 PDCA 循环 5. 保存进度和学习

6.5 /sc:brainstorm - 结构化头脑风暴

用于结构化的头脑风暴，提出正确的问题。

使用场景： - 需求分析 - 问题定义 - 方案设计 - 技术选型

6.6 /sc:index-repo - 仓库索引

索引仓库以优化上下文，提高后续命令的执行效率。

使用场景： - 新项目开始时 - 大型代码库 - 需要频繁查询代码

七、完整工作流程示例

7.1 开发新功能

# 1. 头脑风暴和需求分析
/sc:brainstorm "用户认证功能需求"

# 2. 研究最佳实践
/sc:research "JWT authentication best practices 2024"

# 3. 设计系统架构
/sc:design "用户认证系统架构"

# 4. 实现代码
/sc:implement "实现 JWT 认证中间件"

# 5. 生成测试
/sc:test src/auth/ --coverage

# 6. 生成文档
/sc:document src/auth/

# 7. 代码审查
/sc:analyze src/auth/

# 8. Git 提交
/sc:git commit "feat: add JWT authentication"

7.2 性能优化

# 1. 分析性能问题
/sc:troubleshoot "API 响应慢"

# 2. 研究优化方案
/sc:research "API performance optimization techniques"

# 3. 实施优化
/sc:improve src/api/

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

# 5. 反思和学习
/sc:reflect

7.3 使用 PM Agent

# 启动 PM Agent，自动完成整个流程
/sc:pm "添加用户认证功能，包括 JWT、密码加密、权限管理"

# PM Agent 会自动：
# 1. 激活头脑风暴模式
# 2. 委托给需求分析师、架构师，安全工程师
# 3. 生成实施方案
# 4. 执行开发任务
# 5. 生成测试和文档
# 6. 保存进度

八、项目结构

SuperClaude Framework 的核心组件：

SuperClaude_Framework/
├── src/superclaude/
│   ├── pytest_plugin.py          # pytest 插件（自动加载）
│   ├── pm_agent/                 # PM Agent 模式
│   │   ├── confidence.py         # 预执行置信度检查
│   │   ├── self_check.py         # 后实现验证
│   │   └── reflexion.py          # 错误学习
│   ├── execution/                # 并行执行模式
│   │   └── parallel.py           # Wave→Checkpoint→Wave 模式
│   └── cli/                      # 命令行工具
│       ├── main.py               # superclaude 命令
│       └── doctor.py             # 健康检查
├── commands/                     # 30 个斜杠命令
│   ├── sc-research.md
│   ├── sc-implement.md
│   ├── sc-test.md
│   └── ...
└── install.sh                    # 安装脚本

九、高级功能

9.1 并行执行

SuperClaude 支持令牌高效的并行执行，实现 3.5 倍速度提升。

Wave→Checkpoint→Wave 模式： 1. Wave 1: 并行执行多个独立任务 2. Checkpoint: 验证结果 3. Wave 2: 基于 Wave 1 的结果继续并行执行

9.2 跨会话学习

通过反射模式实现跨会话学习： - 记录错误和解决方案 - 学习最佳实践 - 优化未来决策

9.3 令牌效率优化

30-50% 上下文节省
智能上下文管理
增量更新而非完全重写

9.4 专家面板

多专家协作模式： - 规范专家面板: 技术规范设计 - 商业专家面板: 战略分析和决策

十、注意事项

10.1 命令前缀

所有 SuperClaude 命令都使用 /sc: 前缀，避免与用户自定义命令冲突。

10.2 MCP 服务器

MCP 服务器是可选的，但可以显著提升性能和功能： - Tavily: 增强网络研究能力 - Context7: 提供官方文档查找 - Serena: 增强代码理解 - Playwright: 支持 E2E 测试

10.3 Docker 要求

AIRIS MCP Gateway 需要 Docker。如果不使用 AIRIS，可以单独安装其他 MCP 服务器。

10.4 Python 版本

需要 Python 3.10+，建议使用最新版本。

十一、常见问题

Q1: 如何查看所有可用命令？

# 显示所有 SuperClaude 命令
/sc

# 列出已安装的命令
superclaude install --list

Q2:如何验证安装是否成功？

# 运行健康检查
superclaude doctor

# 检查包安装
pipx list | grep superclaude

Q3:如何更新 SuperClaude？

1
2
3

# pipx 安装的更新方法
pipx upgrade superclaude
superclaude install  # 重新安装命令

Q4:如何卸载 SuperClaude？

# 卸载命令
superclaude uninstall

# 卸载包（pipx）
pipx uninstall superclaude

十二、最佳实践

12.1 项目初始化

新项目开始时：

# 1. 索引仓库
/sc:index-repo

# 2. 创建项目规划
/sc:pm "项目初始化和架构设计"

# 3. 生成文档
/sc:document

12.2 开发流程

遵循标准开发流程：

1	研究 → 设计 → 实现 → 测试 → 文档 → 审查 → 提交

12.3 使用 PM Agent

对于复杂任务，优先使用 PM Agent：

1	/sc:pm "详细描述你的需求"

12.4 定期反思

定期使用反思命令学习和改进：

1	/sc:reflect

12.5 保存和加载上下文

长期项目中保存上下文：

# 保存当前上下文
/sc:save project-context.json

# 加载上下文
/sc:load project-context.json

十三、相关资源

GitHub 仓库: https://github.com/SuperClaude-Org/SuperClaude_Framework
文档: https://github.com/SuperClaude-Org/SuperClaude_Framework/wiki
问题反馈: https://github.com/SuperClaude-Org/SuperClaude_Framework/issues

祝你使用愉快！🎉