SuperClaude/docs/Development/installation-flow-understanding.md

SuperClaude Installation Flow - Complete Understanding

学習内容: インストーラーがどうやって ~/.claude/ にファイルを配置するかの完全理解

---

🔄 インストールフロー全体像

ユーザー操作

# Step 1: パッケージインストール
pipx install SuperClaude
# または
npm install -g @bifrost_inc/superclaude

# Step 2: セットアップ実行
SuperClaude install

内部処理の流れ

1. Entry Point:
   File: superclaude/__main__.py → main()

2. CLI Parser:
   File: superclaude/__main__.py → create_parser()
   Command: "install" サブコマンド登録

3. Component Manager:
   File: setup/cli/install.py
   Role: インストールコンポーネントの調整

4. Commands Component:
   File: setup/components/commands.py → CommandsComponent
   Role: スラッシュコマンドのインストール

5. Source Files:
   Location: superclaude/commands/*.md
   Content: pm.md, implement.md, test.md, etc.

6. Destination:
   Location: ~/.claude/commands/sc/*.md
   Result: ユーザー環境に配置

---

📁 CommandsComponent の詳細

クラス構造

class CommandsComponent(Component):
    """
    Role: スラッシュコマンドのインストール・管理
    Parent: setup/core/base.py → Component
    Install Path: ~/.claude/commands/sc/
    """

主要メソッド

1. __init__()

def __init__(self, install_dir: Optional[Path] = None):
    super().__init__(install_dir, Path("commands/sc"))

理解:

• install_dir: ~/.claude/ （ユーザー環境）
• Path("commands/sc"): サブディレクトリ指定
• 結果: ~/.claude/commands/sc/ にインストール

2. _get_source_dir()

def _get_source_dir(self) -> Path:
    # setup/components/commands.py の位置から計算
    project_root = Path(__file__).parent.parent.parent
    # → ~/github/SuperClaude_Framework/

    return project_root / "superclaude" / "commands"
    # → ~/github/SuperClaude_Framework/superclaude/commands/

理解:

Source: ~/github/SuperClaude_Framework/superclaude/commands/*.md
Target: ~/.claude/commands/sc/*.md

つまり:
superclaude/commands/pm.md
  ↓ コピー
~/.claude/commands/sc/pm.md

3. _install() - インストール実行

def _install(self, config: Dict[str, Any]) -> bool:
    self.logger.info("Installing SuperClaude command definitions...")

    # 既存コマンドのマイグレーション
    self._migrate_existing_commands()

    # 親クラスのインストール実行
    return super()._install(config)

理解:

1. ログ出力
2. 旧バージョンからの移行処理
3. 実際のファイルコピー（親クラスで実行）

4. _migrate_existing_commands() - マイグレーション

def _migrate_existing_commands(self) -> None:
    """
    旧Location: ~/.claude/commands/*.md
    新Location: ~/.claude/commands/sc/*.md

    V3 → V4 移行時の処理
    """
    old_commands_dir = self.install_dir / "commands"
    new_commands_dir = self.install_dir / "commands" / "sc"

    # 旧場所からファイル検出
    # 新場所へコピー
    # 旧場所から削除

理解:

• V3: /analyze → V4: /sc:analyze
• 名前空間衝突を防ぐため /sc: プレフィックス

5. _post_install() - メタデータ更新

def _post_install(self) -> bool:
    # メタデータ更新
    metadata_mods = self.get_metadata_modifications()
    self.settings_manager.update_metadata(metadata_mods)

    # コンポーネント登録
    self.settings_manager.add_component_registration(
        "commands",
        {
            "version": __version__,
            "category": "commands",
            "files_count": len(self.component_files),
        },
    )

理解:

• ~/.claude/.superclaude.json 更新
• インストール済みコンポーネント記録
• バージョン管理

---

📋 実際のファイルマッピング

Source（このプロジェクト）

~/github/SuperClaude_Framework/superclaude/commands/
├── pm.md                  # PM Agent定義
├── implement.md           # Implement コマンド
├── test.md                # Test コマンド
├── analyze.md             # Analyze コマンド
├── research.md            # Research コマンド
├── ...（全26コマンド）

Destination（ユーザー環境）

~/.claude/commands/sc/
├── pm.md                  # → /sc:pm で実行可能
├── implement.md           # → /sc:implement で実行可能
├── test.md                # → /sc:test で実行可能
├── analyze.md             # → /sc:analyze で実行可能
├── research.md            # → /sc:research で実行可能
├── ...（全26コマンド）

Claude Code動作

User: /sc:pm "Build authentication"

Claude Code:
  1. ~/.claude/commands/sc/pm.md 読み込み
  2. YAML frontmatter 解析
  3. Markdown本文を展開
  4. PM Agent として実行

---

🔧 他のコンポーネント

Modes Component

File: setup/components/modes.py
Source: superclaude/modes/*.md
Target: ~/.claude/*.md

Example:
  superclaude/modes/MODE_Brainstorming.md
    ↓
  ~/.claude/MODE_Brainstorming.md

Agents Component

File: setup/components/agents.py
Source: superclaude/agents/*.md
Target: ~/.claude/agents/*.md（または統合先）

Core Component

File: setup/components/core.py
Source: superclaude/core/CLAUDE.md
Target: ~/.claude/CLAUDE.md

これがグローバル設定！

---

💡 開発時の注意点

✅ 正しい変更方法

# 1. ソースファイルを変更（Git管理）
cd ~/github/SuperClaude_Framework
vim superclaude/commands/pm.md

# 2. テスト追加
Write tests/test_pm_command.py

# 3. テスト実行
pytest tests/test_pm_command.py -v

# 4. コミット
git add superclaude/commands/pm.md tests/
git commit -m "feat: enhance PM command"

# 5. 開発版インストール
pip install -e .
# または
SuperClaude install --dev

# 6. 動作確認
claude
/sc:pm "test"

❌ 間違った変更方法

# ダメ！Git管理外を直接変更
vim ~/.claude/commands/sc/pm.md

# 変更は次回インストール時に上書きされる
SuperClaude install  # ← 変更が消える！

---

🎯 PM Mode改善の正しいフロー

Phase 1: 理解（今ここ！）

✅ setup/components/commands.py 理解完了
✅ superclaude/commands/*.md の存在確認完了
✅ インストールフロー理解完了

Phase 2: 現在の仕様確認

# ソース確認（Git管理）
Read superclaude/commands/pm.md

# インストール後確認（参考用）
Read ~/.claude/commands/sc/pm.md

# 「なるほど、こういう仕様になってるのか」

Phase 3: 改善案作成

# このプロジェクト内で（Git管理）
Write docs/development/hypothesis-pm-enhancement-2025-10-14.md

内容:
- 現状の問題（ドキュメント寄りすぎ、PMO機能不足）
- 改善案（自律的PDCA、自己評価）
- 実装方針
- 期待される効果

Phase 4: 実装

# ソースファイル修正
Edit superclaude/commands/pm.md

変更例:
- PDCA自動実行の強化
- docs/ ディレクトリ活用の明示
- 自己評価ステップの追加
- エラー時再学習フローの追加

Phase 5: テスト・検証

# テスト追加
Write tests/test_pm_enhanced.py

# テスト実行
pytest tests/test_pm_enhanced.py -v

# 開発版インストール
SuperClaude install --dev

# 実際に使ってみる
claude
/sc:pm "test enhanced workflow"

Phase 6: 学習記録

# 成功パターン記録
Write docs/patterns/pm-autonomous-workflow.md

# 失敗があれば記録
Write docs/mistakes/mistake-2025-10-14.md

---

📊 Component間の依存関係

Commands Component:
  depends_on: ["core"]

Core Component:
  provides:
    - ~/.claude/CLAUDE.md（グローバル設定）
    - 基本ディレクトリ構造

Modes Component:
  depends_on: ["core"]
  provides:
    - ~/.claude/MODE_*.md

Agents Component:
  depends_on: ["core"]
  provides:
    - エージェント定義

MCP Component:
  depends_on: ["core"]
  provides:
    - MCPサーバー設定

---

🚀 次のアクション

理解完了！次は：

1. ✅ superclaude/commands/pm.md の現在の仕様確認
2. ✅ 改善提案ドキュメント作成
3. ✅ 実装修正（PDCA強化、PMO機能追加）
4. ✅ テスト追加・実行
5. ✅ 動作確認
6. ✅ 学習記録

このドキュメント自体がインストールフローの完全理解記録として機能する。 次回のセッションで読めば、同じ説明を繰り返さなくて済む。