# CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。

## 快速参考

### 常用命令

**安装与配置：**
```bash
# 以开发模式安装
uv sync

# 运行安装程序（多种选项）
SuperClaude install                    # 快速设置（推荐）
SuperClaude install --interactive      # 交互式组件选择
SuperClaude install --minimal          # 最小化安装
SuperClaude install --profile developer # 完整开发者设置
SuperClaude install --dry-run          # 预览更改而不应用

# 替代安装方法
python3 -m SuperClaude install
SuperClaude update --verbose
SuperClaude backup --create
SuperClaude uninstall --yes
```

**包管理：**
```bash
# 从 PyPI（推荐）
uv add SuperClaude

# 从源码
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
uv sync
```

**测试（有限）：**
```bash
# 注意：尚无正式测试套件
# 文档中有引用但未实现：
python Tests/comprehensive_test.py
python Tests/task_management_test.py
python Tests/performance_test_suite.py
```

## 架构概述

SuperClaude Framework v3.0 是一个**基于 Python 的 Claude Code 增强系统**，通过专业命令、角色（personas）和 MCP 服务器集成扩展 AI 辅助开发功能。

### 核心结构

```
SuperClaude_Framework/
├── SuperClaude/              # 框架文件（安装到 ~/.claude/）
│   ├── Core/                 # 9 个定义行为的核心文档文件
│   │   ├── CLAUDE.md         # 主入口点
│   │   ├── COMMANDS.md       # 命令执行框架
│   │   ├── FLAGS.md          # 标志参考
│   │   ├── PERSONAS.md       # 11 个专业角色（personas）
│   │   ├── MCP.md            # MCP 服务器集成
│   │   ├── ORCHESTRATOR.md   # 智能路由系统
│   │   ├── PRINCIPLES.md     # 核心原则
│   │   ├── RULES.md          # 操作规则
│   │   ├── MODES.md          # 操作模式
│   ├── Commands/             # 16 个基于 Markdown 的斜杠命令
│   │   ├── analyze.md
│   │   ├── build.md
│   │   ├── implement.md      # v3 中的新增功能（替换 v2 的 /build 功能）
│   │   └── ...
│   └── Hooks/                # v3 中已移除，v4 中将回归
│
├── setup/                    # 安装系统
│   ├── base/                 # 核心安装程序基础架构
│   ├── components/           # 组件安装程序
│   ├── core/                 # 注册表和验证
│   ├── managers              # 配置、文件、设置管理器
│   ├── operations            # 安装、更新、卸载、备份操作
│   └── utils                 # UI、日志、安全工具
│
├── config/                   # 配置
│   ├── features.json         # 功能定义
│   └── requirements.json     # 系统要求
│
├── profiles/                 # 安装配置文件
│   ├── quick.json            # 快速设置
│   ├── minimal.json          # 最小化安装
│   └── developer.json        # 完整开发者设置
│
├── Docs/                     # 用户文档（5 个指南）
└── SuperClaude/__main__.py   # 统一 CLI 入口点
```

### 核心组件

**1. 安装系统（`setup/` 模块）**
- 模块化安装程序，支持基于组件的安装
- 入口点：`SuperClaude/__main__.py`（254 行）
- 操作：安装、更新、卸载、备份
- 配置文件：quick、minimal、developer

**2. 框架文件（`SuperClaude/` 目录）**
- 9 个核心文档文件指导 Claude 的行为
- 16 个 Markdown 格式的斜杠命令定义
- 安装到 `~/.claude/` 以集成 Claude Code

**3. MCP 集成**
- Context7：文档查找
- Sequential：复杂分析
- Magic：UI 组件生成
- Playwright：浏览器自动化

**4. 角色系统（Personas System）**
- 11 个专业 AI 角色：架构师、前端、后端、分析员、安全员、文员等
- 智能路由尝试选择合适的专家

## 开发工作流程

### 开发环境设置

```bash
# 克隆并设置
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
uv sync

# 以开发模式安装
SuperClaude install --profile developer
```

### 核心开发领域

**框架文件** - 修改 `SuperClaude/Core/` 和 `SuperClaude/Commands/` 以实现：
- 文档和行为变更
- 命令定义和更新
- 角色配置

**安装系统** - 在 `setup/` 模块中工作以实现：
- 安装程序改进
- 组件管理
- 配置文件调整

**配置** - 更新以下文件：
- `config/requirements.json` - 系统要求
- `config/features.json` - 功能定义
- `profiles/*.json` - 安装配置文件

### 代码组织模式

- **模块化架构：** 跨模块分离关注点
- **文档驱动：** Markdown 文件定义行为
- **基于组件：** 安装分解为离散组件
- **配置文件驱动：** 多种安装配置文件适用于不同用例
- **错误处理：** 具有回退机制的全面错误处理

## 重要说明

### v2 到 v3 迁移

**破坏性变更：** `/build` 命令发生了变化！
- v2: `/build myFeature` = 功能实现
- v3: `/sc:build` = 仅编译/打包
- v3: `/sc:implement` = 功能实现（新功能！）

**迁移：** 将 `v2 /build myFeature` 替换为 `v3 /sc:implement myFeature`

### 已知问题

- 这是 v3.0 的初始发布版本 - 预期会有错误
- Hooks 系统已移除（v4 中将回归）
- 无正式测试套件（文档中有引用但未实现）
- 无 linting/格式化配置
- MCP 集成部分工作

### 构建系统

- **构建后端：** Hatchling（通过 pyproject.toml）
- **包管理器：** uv（现代 Python 包管理器）
- **依赖：** 最小化（仅 `setuptools>=45.0.0`）
- **语言：** Python 3.8+（专注于标准库）

## 重要文档

- **README.md**（342 行）- 主要项目文档、安装指南
- **CONTRIBUTING.md** - 贡献指南、代码标准
- **Docs/superclaude-user-guide.md** - 完整用户概览
- **Docs/commands-guide.md** - 全部 16 个斜杠命令说明
- **Docs/flags-guide.md** - 命令标志和选项
- **Docs/installation-guide.md** - 详细安装说明

## 日常开发命令

```bash
# 快速安装测试
SuperClaude install --dry-run

# 更新安装
SuperClaude update --verbose

# 更改前创建备份
SuperClaude backup --create

# 查看所有安装选项
SuperClaude install --help

# 使用特定配置文件运行安装程序
SuperClaude install --profile developer
```

## 配置

安装后，用户可以通过以下方式进行自定义：
- `~/.claude/settings.json` - 主配置
- `~/.claude/*.md` - 框架行为文件

## 未来路线图（v4）

- Hooks 系统重新设计和回归
- 增强的 MCP 套件
- 性能改进
- 更多角色
- 跨 CLI 支持

## 故障排除

**安装问题：**
- 检查 Python 3.8+ 已安装
- 确保 `~/.claude/` 目录权限
- 使用 `--verbose` 标志获取详细输出
- 从 v2 升级时进行备份和全新安装

**开发问题：**
- 框架文件位于 `SuperClaude/`（安装到 `~/.claude/`）
- 安装系统位于 `setup/` 模块
- 入口点是 `SuperClaude/__main__.py`