mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-17 09:46:06 +00:00
3762d6ab24
Comprehensive restoration of all agents, modes, MCP integrations, and documentation. ## 🤖 Agents Restored (20 total) Added 17 new agent definitions to existing 3: - backend-architect, business-panel-experts, deep-research-agent - devops-architect, frontend-architect, learning-guide - performance-engineer, pm-agent, python-expert - quality-engineer, refactoring-expert, requirements-analyst - root-cause-analyst, security-engineer, socratic-mentor - system-architect, technical-writer ## 🎨 Behavioral Modes (7) - MODE_Brainstorming - Multi-perspective ideation - MODE_Business_Panel - Executive strategic analysis - MODE_DeepResearch - Autonomous research - MODE_Introspection - Meta-cognitive analysis - MODE_Orchestration - Tool coordination - MODE_Task_Management - Systematic organization - MODE_Token_Efficiency - Context optimization ## 🔌 MCP Server Integration (8) Documentation and configs for: - Tavily (web search) - Serena (session persistence) - Sequential (token-efficient reasoning) - Context7 (documentation lookup) - Playwright (browser automation) - Magic (UI components) - Morphllm (model transformation) - Chrome DevTools (performance) ## 📚 Core Documentation (6) - PRINCIPLES.md, RULES.md, FLAGS.md - RESEARCH_CONFIG.md - BUSINESS_PANEL_EXAMPLES.md, BUSINESS_SYMBOLS.md ## 📖 Documentation Restored (152 files) - User-Guide (en, jp, kr, zh) - 24 files - Developer-Guide - 5 files - Development docs - 10 files - Reference docs - 10 files - Getting-Started - 2 files - Plus examples and templates ## 📦 Package Configuration Updated pyproject.toml and MANIFEST.in to include: - modes/**/*.md - mcp/**/*.md, **/*.json - core/**/*.md - examples/**/*.md - Comprehensive docs in distribution ## 📁 Directory Structure plugins/superclaude/ and src/superclaude/: - agents/ (20 files) - modes/ (7 files) - mcp/ (8 docs + 8 configs) - core/ (6 files) - examples/ (workflow examples) docs/: - 152 markdown files - Multi-language support (en, jp, kr, zh) - Comprehensive guides and references ## 📊 Statistics - Commands: 30 - Agents: 20 - Modes: 7 - MCP Servers: 8 - Documentation Files: 152 - Total Resource Files: 200+ Created docs/reference/comprehensive-features.md with complete inventory. Source: commit d4a17fc Total changes: 150+ files added/modified 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
369 lines
9.2 KiB
Markdown
369 lines
9.2 KiB
Markdown
# SuperClaude Framework - Project Structure Understanding
|
||
|
||
> **Critical Understanding**: このプロジェクトとインストール後の環境の関係
|
||
|
||
---
|
||
|
||
## 🏗️ 2つの世界の区別
|
||
|
||
### 1. このプロジェクト（Git管理・開発環境）
|
||
|
||
**Location**: `~/github/SuperClaude_Framework/`
|
||
|
||
**Role**: ソースコード・開発・テスト
|
||
|
||
```
|
||
SuperClaude_Framework/
|
||
├── setup/ # インストーラーロジック
|
||
│ ├── components/ # コンポーネント定義（何をインストールするか）
|
||
│ ├── data/ # 設定データ（JSON/YAML）
|
||
│ ├── cli/ # CLIインターフェース
|
||
│ ├── utils/ # ユーティリティ関数
|
||
│ └── services/ # サービスロジック
|
||
│
|
||
├── superclaude/ # ランタイムロジック（実行時の動作）
|
||
│ ├── core/ # コア機能
|
||
│ ├── modes/ # 行動モード
|
||
│ ├── agents/ # エージェント定義
|
||
│ ├── mcp/ # MCPサーバー統合
|
||
│ └── commands/ # コマンド実装
|
||
│
|
||
├── tests/ # テストコード
|
||
├── docs/ # 開発者向けドキュメント
|
||
├── pyproject.toml # Python設定
|
||
└── package.json # npm設定
|
||
```
|
||
|
||
**Operations**:
|
||
- ✅ ソースコード変更
|
||
- ✅ Git コミット・PR
|
||
- ✅ テスト実行
|
||
- ✅ ドキュメント作成
|
||
- ✅ バージョン管理
|
||
|
||
---
|
||
|
||
### 2. インストール後（ユーザー環境・Git管理外）
|
||
|
||
**Location**: `~/.claude/`
|
||
|
||
**Role**: 実際に動作する設定・コマンド（ユーザー環境）
|
||
|
||
```
|
||
~/.claude/
|
||
├── commands/
|
||
│ └── sc/ # スラッシュコマンド（インストール後）
|
||
│ ├── pm.md
|
||
│ ├── implement.md
|
||
│ ├── test.md
|
||
│ └── ... (26 commands)
|
||
│
|
||
├── CLAUDE.md # グローバル設定（インストール後）
|
||
├── *.md # モード定義（インストール後）
|
||
│ ├── MODE_Brainstorming.md
|
||
│ ├── MODE_Orchestration.md
|
||
│ └── ...
|
||
│
|
||
└── .claude.json # Claude Code設定
|
||
```
|
||
|
||
**Operations**:
|
||
- ✅ **読むだけ**（理解・確認用）
|
||
- ✅ 動作確認
|
||
- ⚠️ テスト時のみ一時変更（**必ず元に戻す！**）
|
||
- ❌ 永続的な変更禁止（Git追跡不可）
|
||
|
||
---
|
||
|
||
## 🔄 インストールフロー
|
||
|
||
### ユーザー操作
|
||
```bash
|
||
# 1. インストール
|
||
pipx install SuperClaude
|
||
# または
|
||
npm install -g @bifrost_inc/superclaude
|
||
|
||
# 2. セットアップ実行
|
||
SuperClaude install
|
||
```
|
||
|
||
### 内部処理（setup/が実行）
|
||
```python
|
||
# setup/components/*.py が実行される
|
||
|
||
1. ~/.claude/ ディレクトリ作成
|
||
2. commands/sc/ にスラッシュコマンド配置
|
||
3. CLAUDE.md と各種 *.md 配置
|
||
4. .claude.json 更新
|
||
5. MCPサーバー設定
|
||
```
|
||
|
||
### 結果
|
||
- **このプロジェクトのファイル** → **~/.claude/ にコピー**
|
||
- ユーザーがClaude起動 → `~/.claude/` の設定が読み込まれる
|
||
- `/sc:pm` 実行 → `~/.claude/commands/sc/pm.md` が展開される
|
||
|
||
---
|
||
|
||
## 📝 開発ワークフロー
|
||
|
||
### ❌ 間違った方法
|
||
```bash
|
||
# Git管理外を直接変更
|
||
vim ~/.claude/commands/sc/pm.md # ← ダメ！履歴追えない
|
||
|
||
# 変更テスト
|
||
claude # 動作確認
|
||
|
||
# 変更が ~/.claude/ に残る
|
||
# → 元に戻すの忘れる
|
||
# → 設定がぐちゃぐちゃになる
|
||
# → Gitで追跡できない
|
||
```
|
||
|
||
### ✅ 正しい方法
|
||
|
||
#### Step 1: 既存実装を理解
|
||
```bash
|
||
cd ~/github/SuperClaude_Framework
|
||
|
||
# インストールロジック確認
|
||
Read setup/components/commands.py # コマンドのインストール方法
|
||
Read setup/components/modes.py # モードのインストール方法
|
||
Read setup/data/commands.json # コマンド定義データ
|
||
|
||
# インストール後の状態確認（理解のため）
|
||
ls ~/.claude/commands/sc/
|
||
cat ~/.claude/commands/sc/pm.md # 現在の仕様確認
|
||
|
||
# 「なるほど、setup/components/commands.py でこう処理されて、
|
||
# ~/.claude/commands/sc/ に配置されるのね」
|
||
```
|
||
|
||
#### Step 2: 改善案をドキュメント化
|
||
```bash
|
||
cd ~/github/SuperClaude_Framework
|
||
|
||
# Git管理されているこのプロジェクト内で
|
||
Write docs/Development/hypothesis-pm-improvement-YYYY-MM-DD.md
|
||
|
||
# 内容例:
|
||
# - 現状の問題
|
||
# - 改善案
|
||
# - 実装方針
|
||
# - 期待される効果
|
||
```
|
||
|
||
#### Step 3: テストが必要な場合
|
||
```bash
|
||
# バックアップ作成（必須！）
|
||
cp ~/.claude/commands/sc/pm.md ~/.claude/commands/sc/pm.md.backup
|
||
|
||
# 実験的変更
|
||
vim ~/.claude/commands/sc/pm.md
|
||
|
||
# Claude起動して検証
|
||
claude
|
||
# ... 動作確認 ...
|
||
|
||
# テスト完了後、必ず復元！！
|
||
mv ~/.claude/commands/sc/pm.md.backup ~/.claude/commands/sc/pm.md
|
||
```
|
||
|
||
#### Step 4: 本実装
|
||
```bash
|
||
cd ~/github/SuperClaude_Framework
|
||
|
||
# ソースコード側で変更
|
||
Edit setup/components/commands.py # インストールロジック修正
|
||
Edit setup/data/commands/pm.md # コマンド仕様修正
|
||
|
||
# テスト追加
|
||
Write tests/test_pm_command.py
|
||
|
||
# テスト実行
|
||
pytest tests/test_pm_command.py -v
|
||
|
||
# コミット（Git履歴に残る）
|
||
git add setup/ tests/
|
||
git commit -m "feat: enhance PM command with autonomous workflow"
|
||
```
|
||
|
||
#### Step 5: 動作確認
|
||
```bash
|
||
# 開発版インストール
|
||
cd ~/github/SuperClaude_Framework
|
||
pip install -e .
|
||
|
||
# または
|
||
SuperClaude install --dev
|
||
|
||
# 実際の環境でテスト
|
||
claude
|
||
/sc:pm "test request"
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 重要なルール
|
||
|
||
### Rule 1: Git管理の境界を守る
|
||
- **変更**: このプロジェクト内のみ
|
||
- **確認**: `~/.claude/` は読むだけ
|
||
- **テスト**: バックアップ → 変更 → 復元
|
||
|
||
### Rule 2: テスト時は必ず復元
|
||
```bash
|
||
# テスト前
|
||
cp original backup
|
||
|
||
# テスト
|
||
# ... 実験 ...
|
||
|
||
# テスト後（必須！）
|
||
mv backup original
|
||
```
|
||
|
||
### Rule 3: ドキュメント駆動開発
|
||
1. 理解 → docs/Development/ に記録
|
||
2. 仮説 → docs/Development/hypothesis-*.md
|
||
3. 実験 → docs/Development/experiment-*.md
|
||
4. 成功 → docs/patterns/
|
||
5. 失敗 → docs/mistakes/
|
||
|
||
---
|
||
|
||
## 📚 理解すべきファイル
|
||
|
||
### インストーラー側（setup/）
|
||
```python
|
||
# 優先度: 高
|
||
setup/components/commands.py # コマンドインストール
|
||
setup/components/modes.py # モードインストール
|
||
setup/components/agents.py # エージェント定義
|
||
setup/data/commands/*.md # コマンド仕様（ソース）
|
||
setup/data/modes/*.md # モード仕様（ソース）
|
||
|
||
# これらが ~/.claude/ に配置される
|
||
```
|
||
|
||
### ランタイム側（superclaude/）
|
||
```python
|
||
# 優先度: 中
|
||
superclaude/__main__.py # CLIエントリーポイント
|
||
superclaude/core/ # コア機能実装
|
||
superclaude/agents/ # エージェントロジック
|
||
```
|
||
|
||
### インストール後（~/.claude/）
|
||
```markdown
|
||
# 優先度: 理解のため（変更不可）
|
||
~/.claude/commands/sc/pm.md # 実際に動くPM仕様
|
||
~/.claude/MODE_*.md # 実際に動くモード仕様
|
||
~/.claude/CLAUDE.md # 実際に読み込まれるグローバル設定
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 デバッグ方法
|
||
|
||
### インストール確認
|
||
```bash
|
||
# インストール済みコンポーネント確認
|
||
SuperClaude install --list-components
|
||
|
||
# インストール先確認
|
||
ls -la ~/.claude/commands/sc/
|
||
ls -la ~/.claude/*.md
|
||
```
|
||
|
||
### 動作確認
|
||
```bash
|
||
# Claude起動
|
||
claude
|
||
|
||
# コマンド実行
|
||
/sc:pm "test"
|
||
|
||
# ログ確認（必要に応じて）
|
||
tail -f ~/.claude/logs/*.log
|
||
```
|
||
|
||
### トラブルシューティング
|
||
```bash
|
||
# 設定が壊れた場合
|
||
SuperClaude install --force # 再インストール
|
||
|
||
# 開発版に切り替え
|
||
cd ~/github/SuperClaude_Framework
|
||
pip install -e .
|
||
|
||
# 本番版に戻す
|
||
pip uninstall superclaude
|
||
pipx install SuperClaude
|
||
```
|
||
|
||
---
|
||
|
||
## 💡 よくある間違い
|
||
|
||
### 間違い1: Git管理外を変更
|
||
```bash
|
||
# ❌ WRONG
|
||
vim ~/.claude/commands/sc/pm.md
|
||
git add ~/.claude/ # ← できない！Git管理外
|
||
```
|
||
|
||
### 間違い2: バックアップなしテスト
|
||
```bash
|
||
# ❌ WRONG
|
||
vim ~/.claude/commands/sc/pm.md
|
||
# テスト...
|
||
# 元に戻すの忘れる → 設定ぐちゃぐちゃ
|
||
```
|
||
|
||
### 間違い3: ソース確認せずに変更
|
||
```bash
|
||
# ❌ WRONG
|
||
「PMモード直したい」
|
||
→ いきなり ~/.claude/ 変更
|
||
→ ソースコード理解してない
|
||
→ 再インストールで上書きされる
|
||
```
|
||
|
||
### 正解
|
||
```bash
|
||
# ✅ CORRECT
|
||
1. setup/components/ でロジック理解
|
||
2. docs/Development/ に改善案記録
|
||
3. setup/ 側で変更・テスト
|
||
4. Git コミット
|
||
5. SuperClaude install --dev で動作確認
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 次のステップ
|
||
|
||
このドキュメント理解後:
|
||
|
||
1. **setup/components/ 読解**
|
||
- インストールロジックの理解
|
||
- どこに何が配置されるか
|
||
|
||
2. **既存仕様の把握**
|
||
- `~/.claude/commands/sc/pm.md` 確認（読むだけ）
|
||
- 現在の動作理解
|
||
|
||
3. **改善提案作成**
|
||
- `docs/Development/hypothesis-*.md` 作成
|
||
- ユーザーレビュー
|
||
|
||
4. **実装・テスト**
|
||
- `setup/` 側で変更
|
||
- `tests/` でテスト追加
|
||
- Git管理下で開発
|
||
|
||
これで**何百回も同じ説明をしなくて済む**ようになる。
|