mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
docs: add parallel execution research findings
Add comprehensive research documentation: - parallel-execution-complete-findings.md: Full analysis results - parallel-execution-findings.md: Initial investigation - task-tool-parallel-execution-results.md: Task tool analysis - phase1-implementation-strategy.md: Implementation roadmap - pm-mode-validation-methodology.md: PM mode validation approach - repository-understanding-proposal.md: Repository analysis proposal Research validates parallel execution improvements and provides evidence-based foundation for framework enhancements. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
kazuki
483
docs/research/repository-understanding-proposal.md
Normal file
483
docs/research/repository-understanding-proposal.md
Normal file
@@ -0,0 +1,483 @@
|
||||
# Repository Understanding & Auto-Indexing Proposal
|
||||
|
||||
**Date**: 2025-10-19
|
||||
**Purpose**: Measure SuperClaude effectiveness & implement intelligent documentation indexing
|
||||
|
||||
## 🎯 3つの課題と解決策
|
||||
|
||||
### 課題1: リポジトリ理解度の測定
|
||||
|
||||
**問題**:
|
||||
- SuperClaude有無でClaude Codeの理解度がどう変わるか？
|
||||
- `/init` だけで充分か？
|
||||
|
||||
**測定方法**:
|
||||
```yaml
|
||||
理解度テスト設計:
|
||||
質問セット: 20問（easy/medium/hard）
|
||||
easy: "メインエントリポイントはどこ？"
|
||||
medium: "認証システムのアーキテクチャは？"
|
||||
hard: "エラーハンドリングの統一パターンは？"
|
||||
|
||||
測定:
|
||||
- SuperClaude無し: Claude Code単体で回答
|
||||
- SuperClaude有り: CLAUDE.md + framework導入後に回答
|
||||
- 比較: 正解率、回答時間、詳細度
|
||||
|
||||
期待される違い:
|
||||
無し: 30-50% 正解率（コード読むだけ）
|
||||
有り: 80-95% 正解率（構造化された知識）
|
||||
```
|
||||
|
||||
**実装**:
|
||||
```python
|
||||
# tests/understanding/test_repository_comprehension.py
|
||||
class RepositoryUnderstandingTest:
|
||||
"""リポジトリ理解度を測定"""
|
||||
|
||||
def test_with_superclaude(self):
|
||||
# SuperClaude導入後
|
||||
answers = ask_claude_code(questions, with_context=True)
|
||||
score = evaluate_answers(answers, ground_truth)
|
||||
assert score > 0.8 # 80%以上
|
||||
|
||||
def test_without_superclaude(self):
|
||||
# Claude Code単体
|
||||
answers = ask_claude_code(questions, with_context=False)
|
||||
score = evaluate_answers(answers, ground_truth)
|
||||
# ベースライン測定のみ
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 課題2: 自動インデックス作成（最重要）
|
||||
|
||||
**問題**:
|
||||
- ドキュメントが古い/不足している時の初期調査が遅い
|
||||
- 159個のマークダウンファイルを手動で整理は非現実的
|
||||
- ネストが冗長、重複、見つけられない
|
||||
|
||||
**解決策**: PM Agent による並列爆速インデックス作成
|
||||
|
||||
**ワークフロー**:
|
||||
```yaml
|
||||
Phase 1: ドキュメント状態診断 (30秒)
|
||||
Check:
|
||||
- CLAUDE.md existence
|
||||
- Last modified date
|
||||
- Coverage completeness
|
||||
|
||||
Decision:
|
||||
- Fresh (<7 days) → Skip indexing
|
||||
- Stale (>30 days) → Full re-index
|
||||
- Missing → Complete index creation
|
||||
|
||||
Phase 2: 並列探索 (2-5分)
|
||||
Strategy: サブエージェント分散実行
|
||||
Agent 1: Code structure (src/, apps/, lib/)
|
||||
Agent 2: Documentation (docs/, README*)
|
||||
Agent 3: Configuration (*.toml, *.json, *.yml)
|
||||
Agent 4: Tests (tests/, __tests__)
|
||||
Agent 5: Scripts (scripts/, bin/)
|
||||
|
||||
Each agent:
|
||||
- Fast recursive scan
|
||||
- Pattern extraction
|
||||
- Relationship mapping
|
||||
- Parallel execution (5x faster)
|
||||
|
||||
Phase 3: インデックス統合 (1分)
|
||||
Merge:
|
||||
- All agent findings
|
||||
- Detect duplicates
|
||||
- Build hierarchy
|
||||
- Create navigation map
|
||||
|
||||
Phase 4: メタデータ保存 (10秒)
|
||||
Output: PROJECT_INDEX.md
|
||||
Location: Repository root
|
||||
Format:
|
||||
- File tree with descriptions
|
||||
- Quick navigation links
|
||||
- Last updated timestamp
|
||||
- Coverage metrics
|
||||
```
|
||||
|
||||
**ファイル構造例**:
|
||||
```markdown
|
||||
# PROJECT_INDEX.md
|
||||
|
||||
**Generated**: 2025-10-19 21:45:32
|
||||
**Coverage**: 159 files indexed
|
||||
**Agent Execution Time**: 3m 42s
|
||||
**Quality Score**: 94/100
|
||||
|
||||
## 📁 Repository Structure
|
||||
|
||||
### Source Code (`superclaude/`)
|
||||
- **cli/**: Command-line interface (Entry: `app.py`)
|
||||
- `app.py`: Main CLI application (Typer-based)
|
||||
- `commands/`: Command handlers
|
||||
- `install.py`: Installation logic
|
||||
- `config.py`: Configuration management
|
||||
- **agents/**: AI agent personas (9 agents)
|
||||
- `analyzer.py`: Code analysis specialist
|
||||
- `architect.py`: System design expert
|
||||
- `mentor.py`: Educational guidance
|
||||
|
||||
### Documentation (`docs/`)
|
||||
- **user-guide/**: End-user documentation
|
||||
- `installation.md`: Setup instructions
|
||||
- `quickstart.md`: Getting started
|
||||
- **developer-guide/**: Contributor docs
|
||||
- `architecture.md`: System design
|
||||
- `contributing.md`: Contribution guide
|
||||
|
||||
### Configuration Files
|
||||
- `pyproject.toml`: Python project config (UV-based)
|
||||
- `.claude/`: Claude Code integration
|
||||
- `CLAUDE.md`: Main project instructions
|
||||
- `superclaude/`: Framework components
|
||||
|
||||
## 🔗 Quick Navigation
|
||||
|
||||
### Common Tasks
|
||||
- [Install SuperClaude](docs/user-guide/installation.md)
|
||||
- [Architecture Overview](docs/developer-guide/architecture.md)
|
||||
- [Add New Agent](docs/developer-guide/agents.md)
|
||||
|
||||
### File Locations
|
||||
- Entry point: `superclaude/cli/app.py:cli_main`
|
||||
- Tests: `tests/` (pytest-based)
|
||||
- Benchmarks: `tests/performance/`
|
||||
|
||||
## 📊 Metrics
|
||||
|
||||
- Total files: 159 markdown, 87 Python
|
||||
- Documentation coverage: 78%
|
||||
- Code-to-doc ratio: 1:2.3
|
||||
- Last full index: 2025-10-19
|
||||
|
||||
## ⚠️ Issues Detected
|
||||
|
||||
### Redundant Nesting
|
||||
- ❌ `docs/reference/api/README.md` (single file in nested dir)
|
||||
- 💡 Suggest: Flatten to `docs/api-reference.md`
|
||||
|
||||
### Duplicate Content
|
||||
- ❌ `README.md` vs `docs/README.md` (95% similar)
|
||||
- 💡 Suggest: Merge and redirect
|
||||
|
||||
### Orphaned Files
|
||||
- ❌ `old_setup.py` (no references)
|
||||
- 💡 Suggest: Move to `archive/` or delete
|
||||
|
||||
### Missing Documentation
|
||||
- ⚠️ `superclaude/modes/` (no overview doc)
|
||||
- 💡 Suggest: Create `docs/modes-guide.md`
|
||||
|
||||
## 🎯 Recommendations
|
||||
|
||||
1. **Flatten Structure**: Reduce nesting depth by 2 levels
|
||||
2. **Consolidate**: Merge 12 redundant README files
|
||||
3. **Archive**: Move 5 obsolete files to `archive/`
|
||||
4. **Create**: Add 3 missing overview documents
|
||||
```
|
||||
|
||||
**実装**:
|
||||
```python
|
||||
# superclaude/indexing/repository_indexer.py
|
||||
|
||||
class RepositoryIndexer:
|
||||
"""リポジトリ自動インデックス作成"""
|
||||
|
||||
def create_index(self, repo_path: Path) -> ProjectIndex:
|
||||
"""並列爆速インデックス作成"""
|
||||
|
||||
# Phase 1: 診断
|
||||
status = self.diagnose_documentation(repo_path)
|
||||
|
||||
if status.is_fresh:
|
||||
return self.load_existing_index()
|
||||
|
||||
# Phase 2: 並列探索（5エージェント同時実行）
|
||||
agents = [
|
||||
CodeStructureAgent(),
|
||||
DocumentationAgent(),
|
||||
ConfigurationAgent(),
|
||||
TestAgent(),
|
||||
ScriptAgent(),
|
||||
]
|
||||
|
||||
# 並列実行（これが5x高速化の鍵）
|
||||
with ThreadPoolExecutor(max_workers=5) as executor:
|
||||
futures = [
|
||||
executor.submit(agent.explore, repo_path)
|
||||
for agent in agents
|
||||
]
|
||||
results = [f.result() for f in futures]
|
||||
|
||||
# Phase 3: 統合
|
||||
index = self.merge_findings(results)
|
||||
|
||||
# Phase 4: 保存
|
||||
self.save_index(index, repo_path / "PROJECT_INDEX.md")
|
||||
|
||||
return index
|
||||
|
||||
def diagnose_documentation(self, repo_path: Path) -> DocStatus:
|
||||
"""ドキュメント状態診断"""
|
||||
claude_md = repo_path / "CLAUDE.md"
|
||||
index_md = repo_path / "PROJECT_INDEX.md"
|
||||
|
||||
if not claude_md.exists():
|
||||
return DocStatus(is_fresh=False, reason="CLAUDE.md missing")
|
||||
|
||||
if not index_md.exists():
|
||||
return DocStatus(is_fresh=False, reason="PROJECT_INDEX.md missing")
|
||||
|
||||
# 最終更新が7日以内か？
|
||||
last_modified = index_md.stat().st_mtime
|
||||
age_days = (time.time() - last_modified) / 86400
|
||||
|
||||
if age_days > 7:
|
||||
return DocStatus(is_fresh=False, reason=f"Stale ({age_days:.0f} days old)")
|
||||
|
||||
return DocStatus(is_fresh=True)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 課題3: 並列実行が実際に速くない
|
||||
|
||||
**問題の本質**:
|
||||
```yaml
|
||||
並列実行のはず:
|
||||
- Tool calls: 1回（複数ファイルを並列Read）
|
||||
- 期待: 5倍高速
|
||||
|
||||
実際:
|
||||
- 体感速度: 変わらない？
|
||||
- なぜ？
|
||||
|
||||
原因候補:
|
||||
1. API latency: 並列でもAPI往復は1回分
|
||||
2. LLM処理時間: 複数ファイル処理が重い
|
||||
3. ネットワーク: 並列でもボトルネック
|
||||
4. 実装問題: 本当に並列実行されていない？
|
||||
```
|
||||
|
||||
**検証方法**:
|
||||
```python
|
||||
# tests/performance/test_actual_parallel_execution.py
|
||||
|
||||
def test_parallel_vs_sequential_real_world():
|
||||
"""実際の並列実行速度を測定"""
|
||||
|
||||
files = [f"file_{i}.md" for i in range(10)]
|
||||
|
||||
# Sequential実行
|
||||
start = time.perf_counter()
|
||||
for f in files:
|
||||
Read(file_path=f) # 10回のAPI呼び出し
|
||||
sequential_time = time.perf_counter() - start
|
||||
|
||||
# Parallel実行（1メッセージで複数Read）
|
||||
start = time.perf_counter()
|
||||
# 1回のメッセージで10 Read tool calls
|
||||
parallel_time = time.perf_counter() - start
|
||||
|
||||
speedup = sequential_time / parallel_time
|
||||
|
||||
print(f"Sequential: {sequential_time:.2f}s")
|
||||
print(f"Parallel: {parallel_time:.2f}s")
|
||||
print(f"Speedup: {speedup:.2f}x")
|
||||
|
||||
# 期待: 5x以上の高速化
|
||||
# 実際: ???
|
||||
```
|
||||
|
||||
**並列実行が遅い場合の原因と対策**:
|
||||
```yaml
|
||||
Cause 1: API単一リクエスト制限
|
||||
Problem: Claude APIが並列tool callsを順次処理
|
||||
Solution: 検証が必要（Anthropic APIの仕様確認）
|
||||
Impact: 並列化の効果が限定的
|
||||
|
||||
Cause 2: LLM処理時間がボトルネック
|
||||
Problem: 10ファイル読むとトークン量が10倍
|
||||
Solution: ファイルサイズ制限、summary生成
|
||||
Impact: 大きなファイルでは効果減少
|
||||
|
||||
Cause 3: ネットワークレイテンシ
|
||||
Problem: API往復時間がボトルネック
|
||||
Solution: キャッシング、ローカル処理
|
||||
Impact: 並列化では解決不可
|
||||
|
||||
Cause 4: Claude Codeの実装問題
|
||||
Problem: 並列実行が実装されていない
|
||||
Solution: Claude Code issueで確認
|
||||
Impact: 修正待ち
|
||||
```
|
||||
|
||||
**実測が必要**:
|
||||
```bash
|
||||
# 実際に並列実行の速度を測定
|
||||
uv run pytest tests/performance/test_actual_parallel_execution.py -v -s
|
||||
|
||||
# 結果に応じて：
|
||||
# - 5x以上高速 → ✅ 並列実行は有効
|
||||
# - 2x未満 → ⚠️ 並列化の効果が薄い
|
||||
# - 変わらない → ❌ 並列実行されていない
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 実装優先順位
|
||||
|
||||
### Priority 1: 自動インデックス作成（最重要）
|
||||
|
||||
**理由**:
|
||||
- 新規プロジェクトでの初期理解を劇的に改善
|
||||
- PM Agentの最初のタスクとして自動実行
|
||||
- ドキュメント整理の問題を根本解決
|
||||
|
||||
**実装**:
|
||||
1. `superclaude/indexing/repository_indexer.py` 作成
|
||||
2. PM Agent起動時に自動診断→必要ならindex作成
|
||||
3. `PROJECT_INDEX.md` をルートに生成
|
||||
|
||||
**期待効果**:
|
||||
- 初期理解時間: 30分 → 5分（6x高速化）
|
||||
- ドキュメント発見率: 40% → 95%
|
||||
- 重複/冗長の自動検出
|
||||
|
||||
### Priority 2: 並列実行の実測
|
||||
|
||||
**理由**:
|
||||
- 「速くない」という体感を数値で検証
|
||||
- 本当に並列実行されているか確認
|
||||
- 改善余地の特定
|
||||
|
||||
**実装**:
|
||||
1. 実際のタスクでsequential vs parallel測定
|
||||
2. API呼び出しログ解析
|
||||
3. ボトルネック特定
|
||||
|
||||
### Priority 3: 理解度測定
|
||||
|
||||
**理由**:
|
||||
- SuperClaudeの価値を定量化
|
||||
- Before/After比較で効果証明
|
||||
|
||||
**実装**:
|
||||
1. リポジトリ理解度テスト作成
|
||||
2. SuperClaude有無で測定
|
||||
3. スコア比較
|
||||
|
||||
---
|
||||
|
||||
## 💡 PM Agent Workflow改善案
|
||||
|
||||
**現状のPM Agent**:
|
||||
```yaml
|
||||
起動 → タスク実行 → 完了報告
|
||||
```
|
||||
|
||||
**改善後のPM Agent**:
|
||||
```yaml
|
||||
起動:
|
||||
Step 1: ドキュメント診断
|
||||
- CLAUDE.md チェック
|
||||
- PROJECT_INDEX.md チェック
|
||||
- 最終更新日確認
|
||||
|
||||
Decision Tree:
|
||||
- Fresh (< 7 days) → Skip indexing
|
||||
- Stale (7-30 days) → Quick update
|
||||
- Old (> 30 days) → Full re-index
|
||||
- Missing → Complete index creation
|
||||
|
||||
Step 2: 状況別ワークフロー選択
|
||||
Case A: 充実したドキュメント
|
||||
→ 通常のタスク実行
|
||||
|
||||
Case B: 古いドキュメント
|
||||
→ Quick index update (30秒)
|
||||
→ タスク実行
|
||||
|
||||
Case C: ドキュメント不足
|
||||
→ Full parallel indexing (3-5分)
|
||||
→ PROJECT_INDEX.md 生成
|
||||
→ タスク実行
|
||||
|
||||
Step 3: タスク実行
|
||||
- Confidence check
|
||||
- Implementation
|
||||
- Validation
|
||||
```
|
||||
|
||||
**設定例**:
|
||||
```yaml
|
||||
# .claude/pm-agent-config.yml
|
||||
|
||||
auto_indexing:
|
||||
enabled: true
|
||||
|
||||
triggers:
|
||||
- missing_claude_md: true
|
||||
- missing_index: true
|
||||
- stale_threshold_days: 7
|
||||
|
||||
parallel_agents: 5 # 並列実行数
|
||||
|
||||
output:
|
||||
location: "PROJECT_INDEX.md"
|
||||
update_claude_md: true # CLAUDE.mdも更新
|
||||
archive_old: true # 古いindexをarchive/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 期待される効果
|
||||
|
||||
### Before（現状）:
|
||||
```
|
||||
新規リポジトリ調査:
|
||||
- 手動でファイル探索: 30-60分
|
||||
- ドキュメント発見率: 40%
|
||||
- 重複見逃し: 頻繁
|
||||
- /init だけ: 不十分
|
||||
```
|
||||
|
||||
### After（自動インデックス）:
|
||||
```
|
||||
新規リポジトリ調査:
|
||||
- 自動並列探索: 3-5分（10-20x高速）
|
||||
- ドキュメント発見率: 95%
|
||||
- 重複自動検出: 完璧
|
||||
- PROJECT_INDEX.md: 完璧なナビゲーション
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
1. **即座に実装**:
|
||||
```bash
|
||||
# 自動インデックス作成の実装
|
||||
# superclaude/indexing/repository_indexer.py
|
||||
```
|
||||
|
||||
2. **並列実行の検証**:
|
||||
```bash
|
||||
# 実測テストの実行
|
||||
uv run pytest tests/performance/test_actual_parallel_execution.py -v -s
|
||||
```
|
||||
|
||||
3. **PM Agent統合**:
|
||||
```bash
|
||||
# PM Agentの起動フローに組み込み
|
||||
```
|
||||
|
||||
これでリポジトリ理解度が劇的に向上するはずです！
|
||||
Reference in New Issue
Block a user