9.3 安装与配置

引言

本节将指导你完成 SuperClaude 的安装和配置。SuperClaude 提供两种使用方式：

斜杠命令方式（推荐）- 安装 30 个命令到 Claude Code
配置文件方式 - 直接使用配置文件（无需安装）

📋 前置要求

必需环境

组件	最低版本	推荐版本
Python	3.10+	3.11+
Claude Code	最新版	最新版
pipx	1.0+	最新版
Git	2.0+	最新版

验证环境

bash

# 检查 Python 版本
python --version  # 或 python3 --version
# 应输出: Python 3.10.x 或更高

# 检查 pipx
pipx --version
# 如果未安装: brew install pipx && pipx ensurepath

# 检查 Claude Code
claude --version
# 应输出版本号

# 检查 Git
git --version

安装 pipx（如果需要）

bash

# macOS
brew install pipx
pipx ensurepath

# Linux
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# 重启终端使 PATH 生效

1️⃣ 方式一：斜杠命令安装（推荐）

步骤 1：安装 SuperClaude 包

bash

# 使用 pipx 安装（推荐）
pipx install superclaude

# 验证安装
superclaude --version
# 应输出: superclaude 0.4.0 或更高

步骤 2：安装斜杠命令

bash

# 安装 30 个斜杠命令到 Claude Code
superclaude install

# 安装完成后，命令位于: ~/.claude/commands/

步骤 3：验证安装

bash

# 列出已安装的命令
ls ~/.claude/commands/

# 在 Claude Code 中验证
# 打开 Claude Code，输入:
/sc
# 应显示所有可用的 SuperClaude 命令

步骤 4：（可选）安装 MCP 服务器

bash

# 列出可用的 MCP 服务器
superclaude mcp --list

# 交互式安装
superclaude mcp
# 按提示选择要安装的 MCP 服务器

# 或直接安装特定服务器
superclaude mcp install context7
superclaude mcp install serena

安装后目录结构

~/.claude/
├── commands/                    # SuperClaude 命令
│   ├── sc.md                   # 显示所有命令
│   ├── sc-brainstorm.md        # 头脑风暴
│   ├── sc-implement.md         # 功能实现
│   ├── sc-research.md          # 深度研究
│   └── ... (共 30 个命令)
│
├── settings.json               # Claude Code 设置
│
└── skills/                     # 技能（如果有）

2️⃣ 方式二：配置文件方式

如果你不想安装 Python 包，可以直接使用配置文件。

步骤 1：克隆仓库

bash

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

步骤 2：复制配置文件到项目

bash

# 复制核心配置文件到你的项目
cp CLAUDE.md /path/to/your/project/
cp PLANNING.md /path/to/your/project/
cp KNOWLEDGE.md /path/to/your/project/
cp TASK.md /path/to/your/project/

步骤 3：自定义配置

编辑复制的文件，根据你的项目需求进行调整：

markdown

# CLAUDE.md 示例自定义

## 项目特定规则

### 技术栈
- 前端: React + TypeScript
- 后端: Python FastAPI
- 数据库: PostgreSQL

### 代码风格
- 使用 ESLint + Prettier
- 遵循 PEP 8

### 特定约束
- 所有 API 必须版本化 (/api/v1/)
- 必须包含单元测试

3️⃣ 配置文件详解

CLAUDE.md - 行为规则

这是 SuperClaude 的核心配置文件，Claude Code 在会话开始时自动读取。

markdown

# CLAUDE.md 结构

## Python 环境规则
- 使用 UV 作为包管理器（强制）
- 使用 src/ 布局

## 开发工作流
- 功能分支开发
- 提交前测试

## PM Agent 核心模式
- ConfidenceChecker: 执行前验证
- SelfCheckProtocol: 执行后验证
- ReflexionPattern: 错误学习

## 并行执行
- Wave → Checkpoint → Wave 模式

## MCP 服务器集成
- Context7: 文档查询
- Serena: 跨会话记忆
- ...

## Git 工作流
- 永不 force push
- 功能分支必须

PLANNING.md - 架构规则

定义项目的不可妥协原则：

markdown

# PLANNING.md 结构

## 项目愿景
[描述项目目标]

## 架构概览
[系统架构图/描述]

## 设计原则
1. 证据驱动开发
2. 置信度优先
3. 并行优先执行
4. Token 效率
5. 无幻觉

## 绝对规则

### 🔴 CRITICAL（永不妥协）
- 安全和数据安全
- 测试失败不跳过
- 功能分支开发

### 🟡 IMPORTANT（强烈偏好）
- 完整性: 开始 = 完成
- 范围纪律

### 🟢 RECOMMENDED
- 并行操作
- 工具专业化

## 快速参考决策树
[决策流程图]

KNOWLEDGE.md - 积累的知识

记录项目开发过程中学到的经验：

markdown

# KNOWLEDGE.md 结构

## 架构决策

### 决策 1: 使用 JWT 认证
- 日期: 2024-01-15
- 原因: 无状态、易扩展
- 替代方案: Session-based
- 权衡: 无法即时撤销

## 常见陷阱

### 陷阱 1: 未验证环境变量
- 问题: 部署时配置缺失
- 解决: 启动时验证所有必需变量

## 成功模式

### 模式 1: API 版本化
- 路径: /api/v1/
- 好处: 向后兼容、渐进迁移

## 性能优化

### 优化 1: 数据库查询
- 问题: N+1 查询
- 解决: 使用 prefetch_related
- 效果: 100ms → 10ms

TASK.md - 当前任务

跟踪项目当前的任务和优先级：

markdown

# TASK.md 结构

## 🔴 CRITICAL（阻止发布）
- [ ] 修复安全漏洞 #123

## 🔥 HIGH PRIORITY
- [ ] 完成用户认证模块
- [ ] 添加 API 文档

## 📋 MEDIUM PRIORITY
- [ ] 优化数据库查询
- [ ] 添加日志系统

## 📈 LOW PRIORITY
- [ ] 更新 README
- [ ] 代码注释完善

4️⃣ MCP 服务器配置

可用的 MCP 服务器

服务器	用途	配置方式
Tavily	网络搜索	API Key
Context7	官方文档	无需配置
Sequential	多步推理	无需配置
Serena	语义记忆	本地服务
Playwright	浏览器自动化	安装浏览器
Magic	UI 生成	API Key
Morphllm	代码转换	API Key
Chrome DevTools	性能分析	Chrome 安装

配置 MCP 服务器

方式 1：通过 superclaude 命令

bash

# 交互式配置
superclaude mcp

# 这将引导你完成配置，包括：
# 1. 选择要安装的服务器
# 2. 配置 API Key（如需要）
# 3. 更新 Claude Code 设置

方式 2：手动配置

编辑 ~/.claude/settings.json:

json

{
  "mcpServers": {
    "tavily": {
      "command": "npx",
      "args": ["-y", "@anthropic/tavily-mcp"],
      "env": {
        "TAVILY_API_KEY": "your-api-key"
      }
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@anthropic/context7-mcp"]
    },
    "serena": {
      "command": "npx",
      "args": ["-y", "@anthropic/serena-mcp"]
    }
  }
}

验证 MCP 配置

bash

# 在 Claude Code 中测试
# 输入以下命令，应该能看到 MCP 服务器响应

# 测试 Context7
"使用 Context7 查询 React useState 的文档"

# 测试 Serena
"列出所有 memories"

5️⃣ 项目级配置

初始化新项目

bash

# 创建项目目录
mkdir my-project
cd my-project

# 初始化 Git
git init

# 创建 SuperClaude 配置文件
touch CLAUDE.md PLANNING.md KNOWLEDGE.md TASK.md

# 或使用模板
superclaude init

配置文件模板

CLAUDE.md 模板：

markdown

# Project CLAUDE.md

## 项目信息
- 名称: [项目名称]
- 类型: [Web App / CLI / Library / ...]
- 技术栈: [列出主要技术]

## 开发规范

### 代码风格
- [具体规范]

### 测试要求
- 单元测试覆盖率: ≥80%
- 集成测试: 必须

### Git 工作流
- 主分支: main
- 功能分支: feature/*
- 提交格式: conventional commits

## 特定规则
[项目特定的规则]

---
*基于 SuperClaude Framework v4.1.9*

PLANNING.md 模板：

markdown

# Project PLANNING.md

## 项目愿景
[一句话描述项目目标]

## 架构概览

[架构图或描述]


## 设计原则
1. [原则 1]
2. [原则 2]
3. [原则 3]

## 技术决策

### 决策 1: [主题]
- 选择: [方案]
- 原因: [理由]
- 权衡: [取舍]

## 绝对规则

### 🔴 CRITICAL
- [规则 1]
- [规则 2]

### 🟡 IMPORTANT
- [规则 1]
- [规则 2]

### 🟢 RECOMMENDED
- [规则 1]
- [规则 2]

---
*基于 SuperClaude Framework v4.1.9*

6️⃣ 高级配置

自定义命令

你可以创建自定义斜杠命令：

bash

# 创建自定义命令目录
mkdir -p ~/.claude/commands/custom/

# 创建自定义命令
cat > ~/.claude/commands/custom/my-command.md << 'EOF'
---
name: my-command
description: 我的自定义命令
---

# 我的自定义命令

这个命令会...

## 执行步骤
1. 步骤一
2. 步骤二
3. 步骤三
EOF

配置 Pytest 插件

SuperClaude 包含一个 Pytest 插件，提供额外的测试功能：

python

# pyproject.toml
[project.entry-points.pytest11]
superclaude = "superclaude.pytest_plugin"

# 使用示例
import pytest

@pytest.mark.confidence_check
def test_feature(confidence_checker):
    """使用置信度检查器"""
    context = {"test_name": "test_feature"}
    assert confidence_checker.assess(context) >= 0.7

@pytest.mark.self_check
def test_implementation(self_check_protocol):
    """使用自我检查协议"""
    implementation = {"code": "...", "tests": [...]}
    passed, issues = self_check_protocol.validate(implementation)
    assert passed, f"验证失败: {issues}"

环境变量配置

bash

# ~/.bashrc 或 ~/.zshrc

# SuperClaude 配置
export SUPERCLAUDE_CONFIG_PATH=~/.config/superclaude
export SUPERCLAUDE_LOG_LEVEL=INFO

# MCP API Keys
export TAVILY_API_KEY=your-tavily-key
export MAGIC_API_KEY=your-magic-key

# 可选: 自定义命令路径
export CLAUDE_COMMANDS_PATH=~/.claude/commands

7️⃣ 常见问题

Q1: 安装后 /sc 命令不工作

bash

# 检查命令文件是否存在
ls ~/.claude/commands/sc.md

# 如果不存在，重新安装
superclaude install --force

# 重启 Claude Code

Q2: MCP 服务器连接失败

bash

# 检查 MCP 配置
cat ~/.claude/settings.json

# 检查 API Key 是否正确
echo $TAVILY_API_KEY

# 测试 MCP 服务器
npx -y @anthropic/context7-mcp

Q3: 置信度检查总是失败

markdown

# 常见原因：
1. 需求不够清晰 → 添加更多细节
2. 缺少现有代码上下文 → 先读取相关文件
3. 没有文档验证 → 使用 Context7 MCP

# 解决方案：
- 提供更详细的需求描述
- 先执行代码搜索了解现有实现
- 引用官方文档支持你的方案

Q4: 跨会话记忆不工作

bash

# 检查 Serena MCP 是否配置
cat ~/.claude/settings.json | grep serena

# 确保 Serena 服务运行
# 在 Claude Code 中测试
"list_memories()"

# 如果没有输出，重新配置 Serena
superclaude mcp install serena

Q5: 如何更新 SuperClaude

bash

# 更新 Python 包
pipx upgrade superclaude

# 重新安装命令
superclaude install --force

# 更新 MCP 配置（如需要）
superclaude mcp --update

8️⃣ 配置清单

最小配置（快速开始）

✅ 安装 superclaude 包
✅ 运行 superclaude install
✅ 验证 /sc 命令工作

完整配置（团队使用）

✅ 推荐配置
✅ 配置所有 MCP 服务器
✅ 创建 KNOWLEDGE.md
✅ 创建 TASK.md
✅ 配置 Pytest 插件
✅ 设置环境变量
✅ 创建团队共享配置

📊 配置验证脚本

使用以下脚本验证你的配置是否正确：

bash

#!/bin/bash
# superclaude-verify.sh

echo "=== SuperClaude 配置验证 ==="

# 检查 Python 版本
echo -n "Python 版本: "
python --version 2>/dev/null || python3 --version

# 检查 superclaude 安装
echo -n "SuperClaude 版本: "
superclaude --version 2>/dev/null || echo "未安装"

# 检查命令目录
echo -n "命令目录: "
if [ -d ~/.claude/commands ]; then
    echo "✅ 存在 ($(ls ~/.claude/commands | wc -l) 个文件)"
else
    echo "❌ 不存在"
fi

# 检查 MCP 配置
echo -n "MCP 配置: "
if [ -f ~/.claude/settings.json ]; then
    if grep -q "mcpServers" ~/.claude/settings.json; then
        echo "✅ 已配置"
    else
        echo "⚠️ 文件存在但无 MCP 配置"
    fi
else
    echo "❌ settings.json 不存在"
fi

# 检查项目配置文件
echo "项目配置文件:"
for file in CLAUDE.md PLANNING.md KNOWLEDGE.md TASK.md; do
    if [ -f "$file" ]; then
        echo "  ✅ $file"
    else
        echo "  ❌ $file"
    fi
done

echo "=== 验证完成 ==="

保存为 superclaude-verify.sh，运行：

bash

chmod +x superclaude-verify.sh
./superclaude-verify.sh

下一节： 9.4 实战案例 — 通过实际案例学习 SuperClaude 的使用！

SuperClaude 教程 v1.0 | 2025 Edition | 基于 SuperClaude Framework v4.1.9

9.3 安装与配置 ​

引言 ​

📋 前置要求 ​

必需环境 ​

验证环境 ​

安装 pipx（如果需要） ​

1️⃣ 方式一：斜杠命令安装（推荐） ​

步骤 1：安装 SuperClaude 包 ​

步骤 2：安装斜杠命令 ​

步骤 3：验证安装 ​

步骤 4：（可选）安装 MCP 服务器 ​

安装后目录结构 ​

2️⃣ 方式二：配置文件方式 ​

步骤 1：克隆仓库 ​

步骤 2：复制配置文件到项目 ​

步骤 3：自定义配置 ​

3️⃣ 配置文件详解 ​

CLAUDE.md - 行为规则 ​

PLANNING.md - 架构规则 ​

KNOWLEDGE.md - 积累的知识 ​

TASK.md - 当前任务 ​

4️⃣ MCP 服务器配置 ​

可用的 MCP 服务器 ​

配置 MCP 服务器 ​

方式 1：通过 superclaude 命令 ​

方式 2：手动配置 ​

验证 MCP 配置 ​

5️⃣ 项目级配置 ​

初始化新项目 ​

配置文件模板 ​

6️⃣ 高级配置 ​

自定义命令 ​

配置 Pytest 插件 ​

环境变量配置 ​

7️⃣ 常见问题 ​

Q1: 安装后 /sc 命令不工作 ​

Q2: MCP 服务器连接失败 ​

Q3: 置信度检查总是失败 ​

Q4: 跨会话记忆不工作 ​

Q5: 如何更新 SuperClaude ​

8️⃣ 配置清单 ​

最小配置（快速开始） ​

推荐配置（日常使用） ​

完整配置（团队使用） ​

📊 配置验证脚本 ​

9.3 安装与配置

引言

📋 前置要求

必需环境

验证环境

安装 pipx（如果需要）

1️⃣ 方式一：斜杠命令安装（推荐）

步骤 1：安装 SuperClaude 包

步骤 2：安装斜杠命令

步骤 3：验证安装

步骤 4：（可选）安装 MCP 服务器

安装后目录结构

2️⃣ 方式二：配置文件方式

步骤 1：克隆仓库

步骤 2：复制配置文件到项目

步骤 3：自定义配置

3️⃣ 配置文件详解

CLAUDE.md - 行为规则

PLANNING.md - 架构规则

KNOWLEDGE.md - 积累的知识

TASK.md - 当前任务

4️⃣ MCP 服务器配置

可用的 MCP 服务器

配置 MCP 服务器

方式 1：通过 superclaude 命令

方式 2：手动配置

验证 MCP 配置

5️⃣ 项目级配置

初始化新项目

配置文件模板

6️⃣ 高级配置

自定义命令

配置 Pytest 插件

环境变量配置

7️⃣ 常见问题

Q1: 安装后 /sc 命令不工作

Q2: MCP 服务器连接失败

Q3: 置信度检查总是失败

Q4: 跨会话记忆不工作

Q5: 如何更新 SuperClaude

8️⃣ 配置清单

最小配置（快速开始）

推荐配置（日常使用）

完整配置（团队使用）

📊 配置验证脚本