mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
refactor: migrate to clean architecture with src/ layout
## Migration Summary
- Moved from flat `superclaude/` to `src/superclaude/` (PEP 517/518)
- Deleted old structure (119 files removed)
- Added new structure with clean architecture layers
## Project Structure Changes
- OLD: `superclaude/{agents,commands,modes,framework}/`
- NEW: `src/superclaude/{cli,execution,pm_agent}/`
## Build System Updates
- Switched: setuptools → hatchling (modern, PEP 517)
- Updated: pyproject.toml with proper entry points
- Added: pytest plugin auto-discovery
- Version: 4.1.6 → 0.4.0 (clean slate)
## Makefile Enhancements
- Removed: `superclaude install` calls (deprecated)
- Added: `make verify` - Phase 1 installation verification
- Added: `make test-plugin` - pytest plugin loading test
- Added: `make doctor` - health check command
## Documentation Added
- docs/architecture/ - 7 architecture docs
- docs/research/python_src_layout_research_20251021.md
- docs/PR_STRATEGY.md
## Migration Phases
- Phase 1: Core installation ✅ (this commit)
- Phase 2: Lazy loading + Skills system (next)
- Phase 3: PM Agent meta-layer (future)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
kazuki
529
docs/architecture/PM_AGENT_COMPARISON.md
Normal file
529
docs/architecture/PM_AGENT_COMPARISON.md
Normal file
@@ -0,0 +1,529 @@
|
||||
# PM Agent: Upstream vs Clean Architecture Comparison
|
||||
|
||||
**Date**: 2025-10-21
|
||||
**Purpose**: 本家（Upstream）と今回のクリーンアーキテクチャでのPM Agent実装の違い
|
||||
|
||||
---
|
||||
|
||||
## 🎯 概要
|
||||
|
||||
### Upstream (本家) - Skills型PM Agent
|
||||
|
||||
**場所**: `~/.claude/skills/pm/` にインストール
|
||||
**形式**: Markdown skill + Python init hooks
|
||||
**読み込み**: Claude Codeが起動時に全Skills読み込み
|
||||
|
||||
### This PR - Core型PM Agent
|
||||
|
||||
**場所**: `src/superclaude/pm_agent/` Pythonパッケージ
|
||||
**形式**: Pure Python modules
|
||||
**読み込み**: pytest実行時のみ、import必要分だけ
|
||||
|
||||
---
|
||||
|
||||
## 📂 ディレクトリ構造比較
|
||||
|
||||
### Upstream (本家)
|
||||
|
||||
```
|
||||
~/.claude/
|
||||
└── skills/
|
||||
└── pm/ # PM Agent Skill
|
||||
├── implementation.md # ~25KB - 全ワークフロー
|
||||
├── modules/
|
||||
│ ├── git-status.md # ~5KB - Git状態フォーマット
|
||||
│ ├── token-counter.md # ~8KB - トークンカウント
|
||||
│ └── pm-formatter.md # ~10KB - ステータス出力
|
||||
└── workflows/
|
||||
└── task-management.md # ~15KB - タスク管理
|
||||
|
||||
superclaude/
|
||||
├── agents/
|
||||
│ └── pm-agent.md # ~50KB - Agent定義
|
||||
├── commands/
|
||||
│ └── pm.md # ~5KB - /sc:pm command
|
||||
└── core/
|
||||
└── pm_init/ # Python init hooks
|
||||
├── __init__.py
|
||||
├── context_contract.py # ~10KB - Context管理
|
||||
├── init_hook.py # ~10KB - Session start
|
||||
└── reflexion_memory.py # ~12KB - Reflexion
|
||||
|
||||
Total: ~150KB ≈ 35K-40K tokens
|
||||
```
|
||||
|
||||
**特徴**:
|
||||
- ✅ Skills系: Markdown中心、人間可読
|
||||
- ✅ Auto-activation: セッション開始時に自動実行
|
||||
- ✅ PDCA Cycle: docs/pdca/ にドキュメント蓄積
|
||||
- ❌ Token heavy: 全Markdown読み込み
|
||||
- ❌ Claude Code依存: Skillsシステム前提
|
||||
|
||||
---
|
||||
|
||||
### This PR (Clean Architecture)
|
||||
|
||||
```
|
||||
src/superclaude/
|
||||
└── pm_agent/ # Python package
|
||||
├── __init__.py # Package exports
|
||||
├── confidence.py # ~8KB - Pre-execution
|
||||
├── self_check.py # ~15KB - Post-validation
|
||||
├── reflexion.py # ~12KB - Error learning
|
||||
└── token_budget.py # ~10KB - Budget management
|
||||
|
||||
tests/pm_agent/
|
||||
├── test_confidence_check.py # 18 tests
|
||||
├── test_self_check_protocol.py # 16 tests
|
||||
├── test_reflexion_pattern.py # 16 tests
|
||||
└── test_token_budget.py # 29 tests
|
||||
|
||||
Total: ~45KB ≈ 10K-12K tokens (import時のみ)
|
||||
```
|
||||
|
||||
**特徴**:
|
||||
- ✅ Python-first: コードとして実装
|
||||
- ✅ Lazy loading: 使う機能のみimport
|
||||
- ✅ Test coverage: 79 tests完備
|
||||
- ✅ Pytest integration: Fixtureで簡単利用
|
||||
- ❌ Auto-activation: なし（手動or pytest）
|
||||
- ❌ PDCA docs: 自動生成なし
|
||||
|
||||
---
|
||||
|
||||
## 🔄 機能比較
|
||||
|
||||
### 1. Session Start Protocol
|
||||
|
||||
#### Upstream (本家)
|
||||
```yaml
|
||||
Trigger: EVERY session start (自動)
|
||||
Method: pm_init/init_hook.py
|
||||
|
||||
Actions:
|
||||
1. PARALLEL Read:
|
||||
- docs/memory/pm_context.md
|
||||
- docs/memory/last_session.md
|
||||
- docs/memory/next_actions.md
|
||||
- docs/memory/current_plan.json
|
||||
2. Confidence Check (200 tokens)
|
||||
3. Output: 🟢 [branch] | [n]M [n]D | [token]%
|
||||
|
||||
Token Cost: ~8K (memory files) + 200 (confidence)
|
||||
```
|
||||
|
||||
#### This PR
|
||||
```python
|
||||
# 自動実行なし - 手動で呼び出し
|
||||
from superclaude.pm_agent.confidence import ConfidenceChecker
|
||||
|
||||
checker = ConfidenceChecker()
|
||||
confidence = checker.assess(context)
|
||||
|
||||
Token Cost: ~2K (confidence moduleのみ)
|
||||
```
|
||||
|
||||
**差分**:
|
||||
- ❌ 自動実行なし
|
||||
- ✅ トークン消費 8.2K → 2K (75%削減)
|
||||
- ✅ オンデマンド実行
|
||||
|
||||
---
|
||||
|
||||
### 2. Pre-Execution Confidence Check
|
||||
|
||||
#### Upstream (本家)
|
||||
```markdown
|
||||
# superclaude/agents/pm-agent.md より
|
||||
|
||||
Confidence Check (200 tokens):
|
||||
❓ "全ファイル読めた？"
|
||||
❓ "コンテキストに矛盾ない？"
|
||||
❓ "次のアクション実行に十分な情報？"
|
||||
|
||||
Output: Markdown形式
|
||||
Location: Agent definition内
|
||||
```
|
||||
|
||||
#### This PR
|
||||
```python
|
||||
# src/superclaude/pm_agent/confidence.py
|
||||
|
||||
class ConfidenceChecker:
|
||||
def assess(self, context: Dict[str, Any]) -> float:
|
||||
"""
|
||||
Assess confidence (0.0-1.0)
|
||||
|
||||
Checks:
|
||||
1. Documentation verified? (40%)
|
||||
2. Patterns identified? (30%)
|
||||
3. Implementation clear? (30%)
|
||||
|
||||
Budget: 100-200 tokens
|
||||
"""
|
||||
# Python実装
|
||||
return confidence_score
|
||||
```
|
||||
|
||||
**差分**:
|
||||
- ✅ Python関数として実装
|
||||
- ✅ テスト可能（18 tests）
|
||||
- ✅ Pytest fixture利用可能
|
||||
- ✅ 型安全
|
||||
- ❌ Markdown定義なし
|
||||
|
||||
---
|
||||
|
||||
### 3. Post-Implementation Self-Check
|
||||
|
||||
#### Upstream (本家)
|
||||
```yaml
|
||||
# agents/pm-agent.md より
|
||||
|
||||
Self-Evaluation Checklist:
|
||||
- [ ] Did I follow architecture patterns?
|
||||
- [ ] Did I read documentation first?
|
||||
- [ ] Did I check existing implementations?
|
||||
- [ ] Are all tasks complete?
|
||||
- [ ] What mistakes did I make?
|
||||
- [ ] What did I learn?
|
||||
|
||||
Token Budget:
|
||||
Simple: 200 tokens
|
||||
Medium: 1,000 tokens
|
||||
Complex: 2,500 tokens
|
||||
|
||||
Output: docs/pdca/[feature]/check.md
|
||||
```
|
||||
|
||||
#### This PR
|
||||
```python
|
||||
# src/superclaude/pm_agent/self_check.py
|
||||
|
||||
class SelfCheckProtocol:
|
||||
def validate(self, implementation: Dict[str, Any])
|
||||
-> Tuple[bool, List[str]]:
|
||||
"""
|
||||
Four Questions Protocol:
|
||||
1. All tests pass?
|
||||
2. Requirements met?
|
||||
3. Assumptions verified?
|
||||
4. Evidence exists?
|
||||
|
||||
7 Hallucination Red Flags detection
|
||||
|
||||
Returns: (passed, issues)
|
||||
"""
|
||||
# Python実装
|
||||
```
|
||||
|
||||
**差分**:
|
||||
- ✅ プログラマティックに実行可能
|
||||
- ✅ 16 tests完備
|
||||
- ✅ Hallucination detection実装
|
||||
- ❌ PDCA docs自動生成なし
|
||||
|
||||
---
|
||||
|
||||
### 4. Reflexion (Error Learning)
|
||||
|
||||
#### Upstream (本家)
|
||||
```python
|
||||
# superclaude/core/pm_init/reflexion_memory.py
|
||||
|
||||
class ReflexionMemory:
|
||||
"""
|
||||
Error learning with dual storage:
|
||||
1. Local JSONL: docs/memory/solutions_learned.jsonl
|
||||
2. Mindbase: Semantic search (if available)
|
||||
|
||||
Lookup: mindbase → grep fallback
|
||||
"""
|
||||
```
|
||||
|
||||
#### This PR
|
||||
```python
|
||||
# src/superclaude/pm_agent/reflexion.py
|
||||
|
||||
class ReflexionPattern:
|
||||
"""
|
||||
Same dual storage strategy:
|
||||
1. Local JSONL: docs/memory/solutions_learned.jsonl
|
||||
2. Mindbase: Semantic search (optional)
|
||||
|
||||
Methods:
|
||||
- get_solution(error_info) → past solution lookup
|
||||
- record_error(error_info) → save to memory
|
||||
- get_statistics() → recurrence rate
|
||||
"""
|
||||
```
|
||||
|
||||
**差分**:
|
||||
- ✅ 同じアルゴリズム
|
||||
- ✅ 16 tests追加
|
||||
- ✅ Mindbase optional化
|
||||
- ✅ Statistics追加
|
||||
|
||||
---
|
||||
|
||||
### 5. Token Budget Management
|
||||
|
||||
#### Upstream (本家)
|
||||
```yaml
|
||||
# agents/pm-agent.md より
|
||||
|
||||
Token Budget (Complexity-Based):
|
||||
Simple Task (typo): 200 tokens
|
||||
Medium Task (bug): 1,000 tokens
|
||||
Complex Task (feature): 2,500 tokens
|
||||
|
||||
Implementation: Markdown定義のみ
|
||||
Enforcement: 手動
|
||||
```
|
||||
|
||||
#### This PR
|
||||
```python
|
||||
# src/superclaude/pm_agent/token_budget.py
|
||||
|
||||
class TokenBudgetManager:
|
||||
BUDGETS = {
|
||||
"simple": 200,
|
||||
"medium": 1000,
|
||||
"complex": 2500,
|
||||
}
|
||||
|
||||
def use(self, tokens: int) -> bool:
|
||||
"""Track usage"""
|
||||
|
||||
@property
|
||||
def remaining(self) -> int:
|
||||
"""Get remaining budget"""
|
||||
|
||||
def get_recommendation(self) -> str:
|
||||
"""Suggest optimization"""
|
||||
```
|
||||
|
||||
**差分**:
|
||||
- ✅ プログラム的に強制可能
|
||||
- ✅ 使用量トラッキング
|
||||
- ✅ 29 tests完備
|
||||
- ✅ pytest fixture化
|
||||
|
||||
---
|
||||
|
||||
## 📊 トークン消費比較
|
||||
|
||||
### シナリオ: PM Agent利用時
|
||||
|
||||
| フェーズ | Upstream | This PR | 削減 |
|
||||
|---------|----------|---------|------|
|
||||
| **Session Start** | 8.2K tokens (auto) | 0K (manual) | -8.2K |
|
||||
| **Confidence Check** | 0.2K (included) | 2K (on-demand) | +1.8K |
|
||||
| **Self-Check** | 1-2.5K (depends) | 1-2.5K (same) | 0K |
|
||||
| **Reflexion** | 3K (full MD) | 3K (Python) | 0K |
|
||||
| **Token Budget** | 0K (manual) | 0.5K (tracking) | +0.5K |
|
||||
| **Total (typical)** | **12.4K tokens** | **6K tokens** | **-6.4K (52%)** |
|
||||
|
||||
**Key Point**: Session start自動実行がない分、大幅削減
|
||||
|
||||
---
|
||||
|
||||
## ✅ 維持される機能
|
||||
|
||||
| 機能 | Upstream | This PR | Status |
|
||||
|------|----------|---------|--------|
|
||||
| Pre-execution confidence | ✅ | ✅ | **維持** |
|
||||
| Post-implementation validation | ✅ | ✅ | **維持** |
|
||||
| Error learning (Reflexion) | ✅ | ✅ | **維持** |
|
||||
| Token budget allocation | ✅ | ✅ | **維持** |
|
||||
| Dual storage (JSONL + Mindbase) | ✅ | ✅ | **維持** |
|
||||
| Hallucination detection | ✅ | ✅ | **維持** |
|
||||
| Test coverage | Partial | 79 tests | **改善** |
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 削除される機能
|
||||
|
||||
### 1. Auto-Activation (Session Start)
|
||||
|
||||
**Upstream**:
|
||||
```yaml
|
||||
EVERY session start:
|
||||
- Auto-read memory files
|
||||
- Auto-restore context
|
||||
- Auto-output status
|
||||
```
|
||||
|
||||
**This PR**:
|
||||
```python
|
||||
# Manual activation required
|
||||
from superclaude.pm_agent.confidence import ConfidenceChecker
|
||||
checker = ConfidenceChecker()
|
||||
```
|
||||
|
||||
**影響**: ユーザーが明示的に呼び出す必要あり
|
||||
**代替案**: Skillsシステムで実装可能
|
||||
|
||||
---
|
||||
|
||||
### 2. PDCA Cycle Documentation
|
||||
|
||||
**Upstream**:
|
||||
```yaml
|
||||
Auto-generate:
|
||||
- docs/pdca/[feature]/plan.md
|
||||
- docs/pdca/[feature]/do.md
|
||||
- docs/pdca/[feature]/check.md
|
||||
- docs/pdca/[feature]/act.md
|
||||
```
|
||||
|
||||
**This PR**:
|
||||
```python
|
||||
# なし - ユーザーが手動で記録
|
||||
```
|
||||
|
||||
**影響**: 自動ドキュメント生成なし
|
||||
**代替案**: Skillsとして実装可能
|
||||
|
||||
---
|
||||
|
||||
### 3. Task Management Workflow
|
||||
|
||||
**Upstream**:
|
||||
```yaml
|
||||
# workflows/task-management.md
|
||||
- TodoWrite auto-tracking
|
||||
- Progress checkpoints
|
||||
- Session continuity
|
||||
```
|
||||
|
||||
**This PR**:
|
||||
```python
|
||||
# TodoWriteはClaude Codeネイティブツールとして利用可能
|
||||
# PM Agent特有のワークフローなし
|
||||
```
|
||||
|
||||
**影響**: PM Agent統合ワークフローなし
|
||||
**代替案**: pytest + TodoWriteで実現可能
|
||||
|
||||
---
|
||||
|
||||
## 🎯 移行パス
|
||||
|
||||
### ユーザーが本家PM Agentの機能を使いたい場合
|
||||
|
||||
**Option 1: Skillsとして併用**
|
||||
```bash
|
||||
# Core PM Agent (This PR) - always installed
|
||||
pip install -e .
|
||||
|
||||
# Skills PM Agent (Upstream) - optional
|
||||
superclaude install-skill pm-agent
|
||||
```
|
||||
|
||||
**Result**:
|
||||
- Pytest fixtures: `src/superclaude/pm_agent/`
|
||||
- Auto-activation: `~/.claude/skills/pm/`
|
||||
- **両方利用可能**
|
||||
|
||||
---
|
||||
|
||||
**Option 2: Skills完全移行**
|
||||
```bash
|
||||
# 本家Skills版のみ使用
|
||||
superclaude install-skill pm-agent
|
||||
|
||||
# Pytest fixturesは使わない
|
||||
```
|
||||
|
||||
**Result**:
|
||||
- Upstream互換100%
|
||||
- トークン消費は本家と同じ
|
||||
|
||||
---
|
||||
|
||||
**Option 3: Coreのみ（推奨）**
|
||||
```bash
|
||||
# This PRのみ
|
||||
pip install -e .
|
||||
|
||||
# Skillsなし
|
||||
```
|
||||
|
||||
**Result**:
|
||||
- 最小トークン消費
|
||||
- Pytest integration最適化
|
||||
- Auto-activation なし
|
||||
|
||||
---
|
||||
|
||||
## 💡 推奨アプローチ
|
||||
|
||||
### プロジェクト用途別
|
||||
|
||||
**1. ライブラリ開発者 (pytest重視)**
|
||||
→ **Option 3: Core のみ**
|
||||
- Pytest fixtures活用
|
||||
- テスト駆動開発
|
||||
- トークン最小化
|
||||
|
||||
**2. Claude Code パワーユーザー (自動化重視)**
|
||||
→ **Option 1: 併用**
|
||||
- Auto-activation活用
|
||||
- PDCA docs自動生成
|
||||
- Pytest fixturesも利用
|
||||
|
||||
**3. 本家互換性重視**
|
||||
→ **Option 2: Skills のみ**
|
||||
- 100% Upstream互換
|
||||
- 既存ワークフロー維持
|
||||
|
||||
---
|
||||
|
||||
## 📋 まとめ
|
||||
|
||||
### 主な違い
|
||||
|
||||
| 項目 | Upstream | This PR |
|
||||
|------|----------|---------|
|
||||
| **実装** | Markdown + Python hooks | Pure Python |
|
||||
| **配置** | ~/.claude/skills/ | site-packages/ |
|
||||
| **読み込み** | Auto (session start) | On-demand (import) |
|
||||
| **トークン** | 12.4K | 6K (-52%) |
|
||||
| **テスト** | Partial | 79 tests |
|
||||
| **Auto-activation** | ✅ | ❌ |
|
||||
| **PDCA docs** | ✅ Auto | ❌ Manual |
|
||||
| **Pytest fixtures** | ❌ | ✅ |
|
||||
|
||||
### 互換性
|
||||
|
||||
**機能レベル**: 95%互換
|
||||
- Core機能すべて維持
|
||||
- Auto-activationとPDCA docsのみ削除
|
||||
|
||||
**移行難易度**: Low
|
||||
- Skills併用で100%互換可能
|
||||
- コード変更不要（import pathのみ）
|
||||
|
||||
### 推奨
|
||||
|
||||
**このPRを採用すべき理由**:
|
||||
1. ✅ 52%トークン削減
|
||||
2. ✅ 標準Python packaging
|
||||
3. ✅ テストカバレッジ完備
|
||||
4. ✅ 必要ならSkills併用可能
|
||||
|
||||
**本家Upstream維持すべき理由**:
|
||||
1. ✅ Auto-activation便利
|
||||
2. ✅ PDCA docs自動生成
|
||||
3. ✅ Claude Code統合最適化
|
||||
|
||||
**ベストプラクティス**: **併用** (Option 1)
|
||||
- Core (This PR): Pytest開発用
|
||||
- Skills (Upstream): 日常使用のAuto-activation
|
||||
- 両方のメリット享受
|
||||
|
||||
---
|
||||
|
||||
**作成日**: 2025-10-21
|
||||
**ステータス**: Phase 2完了時点の比較
|
||||
Reference in New Issue
Block a user