mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-17 17:56:46 +00:00
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管理下で開発
|
||
|
||
これで**何百回も同じ説明をしなくて済む**ようになる。
|