SuperClaude/docs/Development/project-structure-understanding.md

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追跡不可）

---

🔄 インストールフロー

ユーザー操作

# 1. インストール
pipx install SuperClaude
# または
npm install -g @bifrost_inc/superclaude

# 2. セットアップ実行
SuperClaude install

内部処理（setup/が実行）

# 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 が展開される

---

📝 開発ワークフロー

❌ 間違った方法

# Git管理外を直接変更
vim ~/.claude/commands/sc/pm.md  # ← ダメ！履歴追えない

# 変更テスト
claude  # 動作確認

# 変更が ~/.claude/ に残る
# → 元に戻すの忘れる
# → 設定がぐちゃぐちゃになる
# → Gitで追跡できない

✅ 正しい方法

Step 1: 既存実装を理解

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: 改善案をドキュメント化

cd ~/github/SuperClaude_Framework

# Git管理されているこのプロジェクト内で
Write docs/development/hypothesis-pm-improvement-YYYY-MM-DD.md

# 内容例:
# - 現状の問題
# - 改善案
# - 実装方針
# - 期待される効果

Step 3: テストが必要な場合

# バックアップ作成（必須！）
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: 本実装

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: 動作確認

# 開発版インストール
cd ~/github/SuperClaude_Framework
pip install -e .

# または
SuperClaude install --dev

# 実際の環境でテスト
claude
/sc:pm "test request"

---

🎯 重要なルール

Rule 1: Git管理の境界を守る

• 変更: このプロジェクト内のみ
• 確認: ~/.claude/ は読むだけ
• テスト: バックアップ → 変更 → 復元

Rule 2: テスト時は必ず復元

# テスト前
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/）

# 優先度: 高
setup/components/commands.py    # コマンドインストール
setup/components/modes.py       # モードインストール
setup/components/agents.py      # エージェント定義
setup/data/commands/*.md        # コマンド仕様（ソース）
setup/data/modes/*.md           # モード仕様（ソース）

# これらが ~/.claude/ に配置される

ランタイム側（superclaude/）

# 優先度: 中
superclaude/__main__.py         # CLIエントリーポイント
superclaude/core/              # コア機能実装
superclaude/agents/            # エージェントロジック

インストール後（~/.claude/）

# 優先度: 理解のため（変更不可）
~/.claude/commands/sc/pm.md    # 実際に動くPM仕様
~/.claude/MODE_*.md            # 実際に動くモード仕様
~/.claude/CLAUDE.md            # 実際に読み込まれるグローバル設定

---

🔍 デバッグ方法

インストール確認

# インストール済みコンポーネント確認
SuperClaude install --list-components

# インストール先確認
ls -la ~/.claude/commands/sc/
ls -la ~/.claude/*.md

動作確認

# Claude起動
claude

# コマンド実行
/sc:pm "test"

# ログ確認（必要に応じて）
tail -f ~/.claude/logs/*.log

トラブルシューティング

# 設定が壊れた場合
SuperClaude install --force    # 再インストール

# 開発版に切り替え
cd ~/github/SuperClaude_Framework
pip install -e .

# 本番版に戻す
pip uninstall superclaude
pipx install SuperClaude

---

💡 よくある間違い

間違い1: Git管理外を変更

# ❌ WRONG
vim ~/.claude/commands/sc/pm.md
git add ~/.claude/  # ← できない！Git管理外

間違い2: バックアップなしテスト

# ❌ WRONG
vim ~/.claude/commands/sc/pm.md
# テスト...
# 元に戻すの忘れる → 設定ぐちゃぐちゃ

間違い3: ソース確認せずに変更

# ❌ WRONG
「PMモード直したい」
→ いきなり ~/.claude/ 変更
→ ソースコード理解してない
→ 再インストールで上書きされる

正解

# ✅ 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管理下で開発

これで何百回も同じ説明をしなくて済むようになる。