7.1 KiB
7.1 KiB
CLAUDE.md
本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。
快速参考
常用命令
安装与配置：
# 以开发模式安装
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
包管理：
# 从 PyPI（推荐）
uv add SuperClaude
# 从源码
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
uv sync
测试（有限）：
# 注意：尚无正式测试套件
# 文档中有引用但未实现：
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 角色：架构师、前端、后端、分析员、安全员、文员等
- 智能路由尝试选择合适的专家
开发工作流程
开发环境设置
# 克隆并设置
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 - 详细安装说明
日常开发命令
# 快速安装测试
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