mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
docs: add PM Agent architecture and MCP integration documentation
## PM Agent Architecture Redesign ### Auto-Activation System - **pm-agent-auto-activation.md**: Behavior-based auto-activation architecture - 5 activation layers (Session Start, Documentation Guardian, Commander, Post-Implementation, Mistake Handler) - Remove manual `/sc:pm` command requirement - Auto-trigger based on context detection ### Responsibility Cleanup - **pm-agent-responsibility-cleanup.md**: Memory management strategy and MCP role clarification - Delete `docs/memory/` directory (redundant with Mindbase) - Remove `write_memory()` / `read_memory()` usage (Serena is code-only) - Clear lifecycle rules for each memory layer ## MCP Integration Policy ### Core Definitions - **mcp-integration-policy.md**: Complete MCP server definitions and usage guidelines - Mindbase: Automatic conversation history (don't touch) - Serena: Code understanding only (not task management) - Sequential: Complex reasoning engine - Context7: Official documentation reference - Tavily: Web search and research - Clear auto-trigger conditions for each MCP - Anti-patterns and best practices ### Optional Design - **mcp-optional-design.md**: MCP-optional architecture with graceful fallbacks - SuperClaude works fully without any MCPs - MCPs are performance enhancements (2-3x faster, 30-50% fewer tokens) - Automatic fallback to native tools - User choice: Minimal → Standard → Enhanced setup ## Key Benefits **Simplicity**: - Remove `docs/memory/` complexity - Clear MCP role separation - Auto-activation (no manual commands) **Reliability**: - Works without MCPs (graceful degradation) - Clear fallback strategies - No single point of failure **Performance** (with MCPs): - 2-3x faster execution - 30-50% token reduction - Better code understanding (Serena) - Efficient reasoning (Sequential) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
kazuki
455
docs/architecture/pm-agent-auto-activation.md
Normal file
455
docs/architecture/pm-agent-auto-activation.md
Normal file
@@ -0,0 +1,455 @@
|
|||||||
|
# PM Agent Auto-Activation Architecture
|
||||||
|
|
||||||
|
## Problem Statement
|
||||||
|
|
||||||
|
**Current Issue**: PM Agent functionality requires manual `/sc:pm` command invocation, making it easy to forget and inconsistently applied.
|
||||||
|
|
||||||
|
**User Concern**: "今は、/sc:pmコマンドを毎回叩かないと、PM-modeやってくれないきがする"
|
||||||
|
|
||||||
|
## Solution: Behavior-Based Auto-Activation
|
||||||
|
|
||||||
|
PM Agent should activate automatically based on **context detection**, not manual commands.
|
||||||
|
|
||||||
|
### Architecture Overview
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
PM Agent Activation Layers:
|
||||||
|
|
||||||
|
Layer 1 - Session Start (ALWAYS):
|
||||||
|
Trigger: Every new conversation session
|
||||||
|
Action: Auto-restore context from docs/memory/
|
||||||
|
Detection: Session initialization event
|
||||||
|
|
||||||
|
Layer 2 - Documentation Guardian (CONTINUOUS):
|
||||||
|
Trigger: Any file operation in project
|
||||||
|
Action: Ensure relevant docs are read before implementation
|
||||||
|
Detection: Write/Edit tool usage
|
||||||
|
|
||||||
|
Layer 3 - Commander (ON-DEMAND):
|
||||||
|
Trigger: Complex tasks (>3 steps OR >3 files)
|
||||||
|
Action: Orchestrate sub-agents and track progress
|
||||||
|
Detection: TodoWrite usage OR complexity keywords
|
||||||
|
|
||||||
|
Layer 4 - Post-Implementation (AUTO):
|
||||||
|
Trigger: Task completion
|
||||||
|
Action: Document learnings and update knowledge base
|
||||||
|
Detection: Completion keywords OR test pass
|
||||||
|
|
||||||
|
Layer 5 - Mistake Handler (IMMEDIATE):
|
||||||
|
Trigger: Errors or test failures
|
||||||
|
Action: Root cause analysis and prevention documentation
|
||||||
|
Detection: Error messages OR test failures
|
||||||
|
```
|
||||||
|
|
||||||
|
## Implementation Strategy
|
||||||
|
|
||||||
|
### 1. Session Start Auto-Activation
|
||||||
|
|
||||||
|
**File**: `~/.claude/superclaude/agents/pm-agent.md`
|
||||||
|
|
||||||
|
**Trigger Detection**:
|
||||||
|
```yaml
|
||||||
|
session_start_indicators:
|
||||||
|
- First message in new conversation
|
||||||
|
- No prior context in current session
|
||||||
|
- Token budget reset to baseline
|
||||||
|
- No active TodoWrite items in memory
|
||||||
|
```
|
||||||
|
|
||||||
|
**Auto-Execution (No Manual Command)**:
|
||||||
|
```yaml
|
||||||
|
Wave 1 - PARALLEL Context Restoration:
|
||||||
|
1. Bash: git status && git branch
|
||||||
|
2. PARALLEL Read (silent):
|
||||||
|
- Read docs/memory/pm_context.md (if exists)
|
||||||
|
- Read docs/memory/last_session.md (if exists)
|
||||||
|
- Read docs/memory/next_actions.md (if exists)
|
||||||
|
- Read docs/memory/current_plan.json (if exists)
|
||||||
|
- Read CLAUDE.md (ALWAYS)
|
||||||
|
- Read docs/patterns/*.md (recent 5 files)
|
||||||
|
|
||||||
|
Checkpoint - Confidence Check (200 tokens):
|
||||||
|
❓ "全ファイル読めた？"
|
||||||
|
❓ "コンテキストに矛盾ない？"
|
||||||
|
❓ "次のアクション実行に十分な情報？"
|
||||||
|
|
||||||
|
IF confidence >70%:
|
||||||
|
→ Output: 📍 [branch] | [status] | 🧠 [token]%
|
||||||
|
→ Ready for user request
|
||||||
|
ELSE:
|
||||||
|
→ Report what's missing
|
||||||
|
→ Request user clarification
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key Change**: This happens **automatically** at session start, not via `/sc:pm` command.
|
||||||
|
|
||||||
|
### 2. Documentation Guardian (Continuous)
|
||||||
|
|
||||||
|
**Purpose**: Ensure documentation is ALWAYS read before making changes
|
||||||
|
|
||||||
|
**Trigger Detection**:
|
||||||
|
```yaml
|
||||||
|
pre_write_checks:
|
||||||
|
- BEFORE any Write tool usage
|
||||||
|
- BEFORE any Edit tool usage
|
||||||
|
- BEFORE complex TodoWrite (>3 tasks)
|
||||||
|
|
||||||
|
detection_logic:
|
||||||
|
IF tool_name in [Write, Edit, MultiEdit]:
|
||||||
|
AND file_path matches project patterns:
|
||||||
|
→ Auto-trigger Documentation Guardian
|
||||||
|
```
|
||||||
|
|
||||||
|
**Auto-Execution**:
|
||||||
|
```yaml
|
||||||
|
Documentation Guardian Protocol:
|
||||||
|
|
||||||
|
1. Identify Relevant Docs:
|
||||||
|
file_path: src/auth.ts
|
||||||
|
→ Read docs/patterns/authentication-*.md
|
||||||
|
→ Read docs/mistakes/auth-*.md
|
||||||
|
→ Read CLAUDE.md sections matching "auth"
|
||||||
|
|
||||||
|
2. Confidence Check:
|
||||||
|
❓ "関連ドキュメント全部読んだ？"
|
||||||
|
❓ "過去の失敗パターン把握してる？"
|
||||||
|
❓ "既存の成功パターン確認した？"
|
||||||
|
|
||||||
|
IF any_missing:
|
||||||
|
→ Read missing docs
|
||||||
|
→ Update understanding
|
||||||
|
→ Proceed with implementation
|
||||||
|
ELSE:
|
||||||
|
→ Proceed confidently
|
||||||
|
|
||||||
|
3. Pattern Matching:
|
||||||
|
IF similar_mistakes_found:
|
||||||
|
⚠️ "過去に同じミス発生: [mistake_pattern]"
|
||||||
|
⚠️ "防止策: [prevention_checklist]"
|
||||||
|
→ Apply prevention before implementation
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key Change**: Automatic documentation reading BEFORE any file modification.
|
||||||
|
|
||||||
|
### 3. Commander Mode (On-Demand)
|
||||||
|
|
||||||
|
**Purpose**: Orchestrate complex multi-step tasks with sub-agents
|
||||||
|
|
||||||
|
**Trigger Detection**:
|
||||||
|
```yaml
|
||||||
|
commander_triggers:
|
||||||
|
complexity_based:
|
||||||
|
- TodoWrite with >3 tasks
|
||||||
|
- Operations spanning >3 files
|
||||||
|
- Multi-directory scope (>2 dirs)
|
||||||
|
- Keywords: "refactor", "migrate", "redesign"
|
||||||
|
|
||||||
|
explicit_keywords:
|
||||||
|
- "orchestrate"
|
||||||
|
- "coordinate"
|
||||||
|
- "delegate"
|
||||||
|
- "parallel execution"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Auto-Execution**:
|
||||||
|
```yaml
|
||||||
|
Commander Protocol:
|
||||||
|
|
||||||
|
1. Task Analysis:
|
||||||
|
- Identify independent vs dependent tasks
|
||||||
|
- Determine parallelization opportunities
|
||||||
|
- Select appropriate sub-agents
|
||||||
|
|
||||||
|
2. Orchestration Plan:
|
||||||
|
tasks:
|
||||||
|
- task_1: [agent-backend] → auth refactor
|
||||||
|
- task_2: [agent-frontend] → UI updates (parallel)
|
||||||
|
- task_3: [agent-test] → test updates (after 1+2)
|
||||||
|
|
||||||
|
parallelization:
|
||||||
|
wave_1: [task_1, task_2] # parallel
|
||||||
|
wave_2: [task_3] # sequential dependency
|
||||||
|
|
||||||
|
3. Execution with Tracking:
|
||||||
|
- TodoWrite for overall plan
|
||||||
|
- Sub-agent delegation via Task tool
|
||||||
|
- Progress tracking in docs/memory/checkpoint.json
|
||||||
|
- Validation gates between waves
|
||||||
|
|
||||||
|
4. Synthesis:
|
||||||
|
- Collect sub-agent outputs
|
||||||
|
- Integrate results
|
||||||
|
- Final validation
|
||||||
|
- Update documentation
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key Change**: Auto-activates when complexity detected, no manual command needed.
|
||||||
|
|
||||||
|
### 4. Post-Implementation Auto-Documentation
|
||||||
|
|
||||||
|
**Trigger Detection**:
|
||||||
|
```yaml
|
||||||
|
completion_indicators:
|
||||||
|
test_based:
|
||||||
|
- "All tests passing" in output
|
||||||
|
- pytest: X/X passed
|
||||||
|
- ✅ keywords detected
|
||||||
|
|
||||||
|
task_based:
|
||||||
|
- All TodoWrite items marked completed
|
||||||
|
- No pending tasks remaining
|
||||||
|
|
||||||
|
explicit:
|
||||||
|
- User says "done", "finished", "complete"
|
||||||
|
- Commit message created
|
||||||
|
```
|
||||||
|
|
||||||
|
**Auto-Execution**:
|
||||||
|
```yaml
|
||||||
|
Post-Implementation Protocol:
|
||||||
|
|
||||||
|
1. Self-Evaluation (The Four Questions):
|
||||||
|
❓ "テストは全てpassしてる？"
|
||||||
|
❓ "要件を全て満たしてる？"
|
||||||
|
❓ "思い込みで実装してない？"
|
||||||
|
❓ "証拠はある？"
|
||||||
|
|
||||||
|
IF any_fail:
|
||||||
|
❌ NOT complete
|
||||||
|
→ Report actual status
|
||||||
|
ELSE:
|
||||||
|
✅ Proceed to documentation
|
||||||
|
|
||||||
|
2. Pattern Extraction:
|
||||||
|
- What worked? → docs/patterns/[pattern].md
|
||||||
|
- What failed? → docs/mistakes/[mistake].md
|
||||||
|
- New learnings? → docs/memory/patterns_learned.jsonl
|
||||||
|
|
||||||
|
3. Knowledge Base Update:
|
||||||
|
IF global_pattern_discovered:
|
||||||
|
→ Update CLAUDE.md with new rule
|
||||||
|
IF project_specific_pattern:
|
||||||
|
→ Update docs/patterns/
|
||||||
|
IF anti_pattern_identified:
|
||||||
|
→ Update docs/mistakes/
|
||||||
|
|
||||||
|
4. Session State Update:
|
||||||
|
- Write docs/memory/session_summary.json
|
||||||
|
- Update docs/memory/next_actions.md
|
||||||
|
- Clean up temporary docs (>7 days old)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key Change**: Automatic documentation after task completion, no manual trigger needed.
|
||||||
|
|
||||||
|
### 5. Mistake Handler (Immediate)
|
||||||
|
|
||||||
|
**Trigger Detection**:
|
||||||
|
```yaml
|
||||||
|
error_indicators:
|
||||||
|
test_failures:
|
||||||
|
- "FAILED" in pytest output
|
||||||
|
- "Error" in test results
|
||||||
|
- Non-zero exit code
|
||||||
|
|
||||||
|
runtime_errors:
|
||||||
|
- Exception stacktrace detected
|
||||||
|
- Build failures
|
||||||
|
- Linter errors (critical only)
|
||||||
|
|
||||||
|
validation_failures:
|
||||||
|
- Type check errors
|
||||||
|
- Schema validation failures
|
||||||
|
```
|
||||||
|
|
||||||
|
**Auto-Execution**:
|
||||||
|
```yaml
|
||||||
|
Mistake Handler Protocol:
|
||||||
|
|
||||||
|
1. STOP Current Work:
|
||||||
|
→ Halt further implementation
|
||||||
|
→ Do not workaround the error
|
||||||
|
|
||||||
|
2. Reflexion Pattern:
|
||||||
|
a) Check Past Errors:
|
||||||
|
→ Grep docs/memory/solutions_learned.jsonl
|
||||||
|
→ Grep docs/mistakes/ for similar errors
|
||||||
|
|
||||||
|
b) IF similar_error_found:
|
||||||
|
✅ "過去に同じエラー発生済み"
|
||||||
|
✅ "解決策: [past_solution]"
|
||||||
|
→ Apply known solution
|
||||||
|
|
||||||
|
c) ELSE (new error):
|
||||||
|
→ Root cause investigation
|
||||||
|
→ Document new solution
|
||||||
|
|
||||||
|
3. Documentation:
|
||||||
|
Create docs/mistakes/[feature]-YYYY-MM-DD.md:
|
||||||
|
- What Happened (現象)
|
||||||
|
- Root Cause (根本原因)
|
||||||
|
- Why Missed (なぜ見逃したか)
|
||||||
|
- Fix Applied (修正内容)
|
||||||
|
- Prevention Checklist (防止策)
|
||||||
|
- Lesson Learned (教訓)
|
||||||
|
|
||||||
|
4. Update Knowledge Base:
|
||||||
|
→ echo '{"error":"...","solution":"..."}' >> docs/memory/solutions_learned.jsonl
|
||||||
|
→ Update prevention checklists
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key Change**: Immediate automatic activation when errors detected, no manual trigger.
|
||||||
|
|
||||||
|
## Removal of Manual `/sc:pm` Command
|
||||||
|
|
||||||
|
### Current State
|
||||||
|
- `/sc:pm` command in `~/.claude/commands/sc/pm.md`
|
||||||
|
- Requires user to manually invoke every session
|
||||||
|
- Inconsistent application
|
||||||
|
|
||||||
|
### Proposed Change
|
||||||
|
- **Remove** `/sc:pm` command entirely
|
||||||
|
- **Replace** with behavior-based auto-activation
|
||||||
|
- **Keep** pm-agent persona for all behaviors
|
||||||
|
|
||||||
|
### Migration Path
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Step 1 - Update pm-agent.md:
|
||||||
|
Remove: "Manual Invocation: /sc:pm command"
|
||||||
|
Add: "Auto-Activation: Behavior-based triggers (see below)"
|
||||||
|
|
||||||
|
Step 2 - Delete /sc:pm command:
|
||||||
|
File: ~/.claude/commands/sc/pm.md
|
||||||
|
Action: Archive or delete (functionality now in persona)
|
||||||
|
|
||||||
|
Step 3 - Update rules.md:
|
||||||
|
Agent Orchestration section:
|
||||||
|
- Remove references to /sc:pm command
|
||||||
|
- Add auto-activation trigger documentation
|
||||||
|
|
||||||
|
Step 4 - Test Auto-Activation:
|
||||||
|
- Start new session → Should auto-restore context
|
||||||
|
- Make file changes → Should auto-read relevant docs
|
||||||
|
- Complete task → Should auto-document learnings
|
||||||
|
- Encounter error → Should auto-trigger mistake handler
|
||||||
|
```
|
||||||
|
|
||||||
|
## Benefits
|
||||||
|
|
||||||
|
### 1. No Manual Commands Required
|
||||||
|
- ✅ PM Agent always active, never forgotten
|
||||||
|
- ✅ Consistent documentation reading
|
||||||
|
- ✅ Automatic knowledge base maintenance
|
||||||
|
|
||||||
|
### 2. Context-Aware Activation
|
||||||
|
- ✅ Right behavior at right time
|
||||||
|
- ✅ No unnecessary overhead
|
||||||
|
- ✅ Efficient token usage
|
||||||
|
|
||||||
|
### 3. Guaranteed Documentation Quality
|
||||||
|
- ✅ Always read relevant docs before changes
|
||||||
|
- ✅ Automatic pattern documentation
|
||||||
|
- ✅ Mistake prevention through Reflexion
|
||||||
|
|
||||||
|
### 4. Seamless Orchestration
|
||||||
|
- ✅ Auto-detects complex tasks
|
||||||
|
- ✅ Auto-delegates to sub-agents
|
||||||
|
- ✅ Auto-tracks progress
|
||||||
|
|
||||||
|
## Token Budget Impact
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Current (Manual /sc:pm):
|
||||||
|
If forgotten: 0 tokens (no PM functionality)
|
||||||
|
If remembered: 200-500 tokens per invocation
|
||||||
|
Average: Inconsistent, user-dependent
|
||||||
|
|
||||||
|
Proposed (Auto-Activation):
|
||||||
|
Session Start: 200 tokens (ALWAYS)
|
||||||
|
Documentation Guardian: 0-100 tokens (as needed)
|
||||||
|
Commander: 0 tokens (only if complex task)
|
||||||
|
Post-Implementation: 200-2,500 tokens (only after completion)
|
||||||
|
Mistake Handler: 0 tokens (only if error)
|
||||||
|
|
||||||
|
Total per session: 400-3,000 tokens (predictable)
|
||||||
|
|
||||||
|
Trade-off: Slight increase in baseline usage
|
||||||
|
Benefit: 100% consistent PM Agent functionality
|
||||||
|
ROI: Prevents 5K-50K token waste from wrong implementations
|
||||||
|
```
|
||||||
|
|
||||||
|
## Implementation Checklist
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Phase 1 - Core Auto-Activation:
|
||||||
|
- [ ] Update pm-agent.md with auto-activation triggers
|
||||||
|
- [ ] Remove session start from /sc:pm command
|
||||||
|
- [ ] Test session start auto-restoration
|
||||||
|
- [ ] Verify token budget calculations
|
||||||
|
|
||||||
|
Phase 2 - Documentation Guardian:
|
||||||
|
- [ ] Add pre-write documentation checks
|
||||||
|
- [ ] Implement pattern matching logic
|
||||||
|
- [ ] Test with various file operations
|
||||||
|
- [ ] Verify no performance degradation
|
||||||
|
|
||||||
|
Phase 3 - Commander Mode:
|
||||||
|
- [ ] Add complexity detection logic
|
||||||
|
- [ ] Implement sub-agent delegation
|
||||||
|
- [ ] Test parallel execution patterns
|
||||||
|
- [ ] Verify progress tracking
|
||||||
|
|
||||||
|
Phase 4 - Post-Implementation:
|
||||||
|
- [ ] Add completion detection logic
|
||||||
|
- [ ] Implement auto-documentation triggers
|
||||||
|
- [ ] Test pattern extraction
|
||||||
|
- [ ] Verify knowledge base updates
|
||||||
|
|
||||||
|
Phase 5 - Mistake Handler:
|
||||||
|
- [ ] Add error detection logic
|
||||||
|
- [ ] Implement Reflexion pattern lookup
|
||||||
|
- [ ] Test mistake documentation
|
||||||
|
- [ ] Verify prevention checklist updates
|
||||||
|
|
||||||
|
Phase 6 - Cleanup:
|
||||||
|
- [ ] Archive /sc:pm command
|
||||||
|
- [ ] Update all documentation
|
||||||
|
- [ ] Remove manual invocation references
|
||||||
|
- [ ] Final integration testing
|
||||||
|
```
|
||||||
|
|
||||||
|
## Example Workflow (After Implementation)
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
User Session:
|
||||||
|
|
||||||
|
1. Start Conversation:
|
||||||
|
Claude: [Auto-activates PM Agent]
|
||||||
|
Claude: 📍 feature/auth | ✨ Clean | 🧠 15% (30K/200K)
|
||||||
|
User: "Fix authentication bug in auth.ts"
|
||||||
|
|
||||||
|
2. Pre-Implementation:
|
||||||
|
Claude: [Documentation Guardian activates]
|
||||||
|
Claude: [Reads docs/patterns/authentication-*.md silently]
|
||||||
|
Claude: [Reads docs/mistakes/auth-*.md silently]
|
||||||
|
Claude: ⚠️ Past mistake found: "Missing token validation"
|
||||||
|
Claude: Applying prevention checklist before implementation...
|
||||||
|
|
||||||
|
3. Implementation:
|
||||||
|
Claude: [Makes changes with prevention applied]
|
||||||
|
Claude: [Runs tests]
|
||||||
|
Claude: ✅ All tests passing
|
||||||
|
|
||||||
|
4. Post-Implementation:
|
||||||
|
Claude: [Auto-activates documentation]
|
||||||
|
Claude: [Runs Four Questions self-check]
|
||||||
|
Claude: [Extracts pattern: "Token validation pattern"]
|
||||||
|
Claude: [Updates docs/patterns/authentication-token-validation.md]
|
||||||
|
Claude: ✅ Task complete with documentation updated
|
||||||
|
|
||||||
|
User: [Never had to invoke /sc:pm manually]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Conclusion
|
||||||
|
|
||||||
|
This architecture ensures PM Agent functionality is **always active** through behavior-based triggers, eliminating the need for manual `/sc:pm` command invocation while maintaining clear responsibility separation and guaranteed documentation quality.
|
||||||
306
docs/architecture/pm-agent-responsibility-cleanup.md
Normal file
306
docs/architecture/pm-agent-responsibility-cleanup.md
Normal file
@@ -0,0 +1,306 @@
|
|||||||
|
# PM Agent Responsibility Cleanup & MCP Integration
|
||||||
|
|
||||||
|
## 問題整理
|
||||||
|
|
||||||
|
### 1. 既存MODEとの重複
|
||||||
|
|
||||||
|
**MODE_Task_Management.md と pm-agent.md が完全重複**:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
MODE_Task_Management.md:
|
||||||
|
- write_memory() / read_memory() 使用
|
||||||
|
- Serena MCP依存
|
||||||
|
- セッション開始時のlist_memories()
|
||||||
|
- TodoWrite + memory並行管理
|
||||||
|
|
||||||
|
pm-agent.md:
|
||||||
|
- docs/memory/ ファイル管理
|
||||||
|
- ローカルファイルベース
|
||||||
|
- セッション開始時のRead並行実行
|
||||||
|
- TodoWrite + docs/memory/並行管理
|
||||||
|
|
||||||
|
結論: 完全に機能が重複、統合必須
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Memory管理の責務が不明確
|
||||||
|
|
||||||
|
**現状の問題**:
|
||||||
|
```yaml
|
||||||
|
docs/memory/:
|
||||||
|
- いつクリアするか決まってない
|
||||||
|
- ファイルベース vs MCP memoryの使い分け不明
|
||||||
|
- ライフサイクル管理なし
|
||||||
|
|
||||||
|
write_memory() (Serena MCP):
|
||||||
|
- いつ使うべきか不明確
|
||||||
|
- docs/memory/との使い分けなし
|
||||||
|
- 削除タイミング不明
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. MCPの役割分担が曖昧
|
||||||
|
|
||||||
|
**ユーザーの指摘**:
|
||||||
|
- Serena = コード理解に使う
|
||||||
|
- Memory = Mindbaseに任せるべき
|
||||||
|
- 現状は役割が混在
|
||||||
|
|
||||||
|
## 解決策: 責務の明確化
|
||||||
|
|
||||||
|
### Memory Management Strategy
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Level 1 - Session Memory (Mindbase MCP):
|
||||||
|
Purpose: 会話履歴の長期保存（Claude Code標準機能）
|
||||||
|
Technology: Mindbase MCP (自動管理)
|
||||||
|
Scope: 全プロジェクト横断
|
||||||
|
Lifecycle: 永続（自動管理）
|
||||||
|
Use Cases:
|
||||||
|
- 過去の会話検索
|
||||||
|
- 長期的なパターン学習
|
||||||
|
- プロジェクト間の知識共有
|
||||||
|
|
||||||
|
Level 2 - Project Documentation (File-based):
|
||||||
|
Purpose: プロジェクト固有の知識ベース
|
||||||
|
Technology: Markdown files in docs/
|
||||||
|
Scope: プロジェクトごと
|
||||||
|
Lifecycle: Git管理（明示的削除まで永続）
|
||||||
|
Locations:
|
||||||
|
docs/patterns/: 成功パターン（永続）
|
||||||
|
docs/mistakes/: 失敗記録（永続）
|
||||||
|
CLAUDE.md: グローバルルール（永続）
|
||||||
|
|
||||||
|
Level 3 - Task State (Serena MCP - Code Understanding):
|
||||||
|
Purpose: コードベース理解のためのシンボル管理
|
||||||
|
Technology: Serena MCP
|
||||||
|
Scope: セッション内
|
||||||
|
Lifecycle: セッション終了で自動削除
|
||||||
|
Use Cases:
|
||||||
|
- コード構造の理解
|
||||||
|
- シンボル間の関係追跡
|
||||||
|
- リファクタリング支援
|
||||||
|
|
||||||
|
Level 4 - TodoWrite (Claude Code Built-in):
|
||||||
|
Purpose: 現在のタスク進捗管理
|
||||||
|
Technology: Claude Code標準機能
|
||||||
|
Scope: セッション内
|
||||||
|
Lifecycle: タスク完了で削除
|
||||||
|
Use Cases:
|
||||||
|
- 現在進行中のタスク追跡
|
||||||
|
- サブタスクの管理
|
||||||
|
- 進捗の可視化
|
||||||
|
```
|
||||||
|
|
||||||
|
### Memory Lifecycle Rules
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Session Start:
|
||||||
|
1. Mindbaseから過去の関連会話を自動ロード（Claude Code標準）
|
||||||
|
2. docs/patterns/ と docs/mistakes/ を読む（必要に応じて）
|
||||||
|
3. CLAUDE.md を常に読む
|
||||||
|
4. Serena: 使わない（コード理解時のみ）
|
||||||
|
5. TodoWrite: 新規作成（必要なら）
|
||||||
|
|
||||||
|
During Work:
|
||||||
|
1. Mindbase: 自動保存（Claude Code標準）
|
||||||
|
2. docs/: 新しいパターン/ミスを文書化
|
||||||
|
3. Serena: コード理解時のみ使用
|
||||||
|
4. TodoWrite: 進捗更新
|
||||||
|
|
||||||
|
Session End:
|
||||||
|
1. Mindbase: 自動保存（Claude Code標準）
|
||||||
|
2. docs/: 学習内容を永続化
|
||||||
|
3. Serena: 自動削除（何もしない）
|
||||||
|
4. TodoWrite: 完了タスクはクリア
|
||||||
|
|
||||||
|
Monthly Maintenance:
|
||||||
|
1. docs/patterns/: 古い（>6ヶ月）で未参照なら削除
|
||||||
|
2. docs/mistakes/: 重複をマージ
|
||||||
|
3. CLAUDE.md: ベストプラクティス抽出
|
||||||
|
```
|
||||||
|
|
||||||
|
### MCP Role Clarification
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Mindbase MCP (会話履歴):
|
||||||
|
Auto-Managed: Claude Codeが自動管理
|
||||||
|
PM Agent Role: なし（自動で動く）
|
||||||
|
User Action: なし（透明）
|
||||||
|
|
||||||
|
Serena MCP (コード理解):
|
||||||
|
Trigger: コードベース理解が必要な時のみ
|
||||||
|
PM Agent Role: コード理解時に自動活用
|
||||||
|
Examples:
|
||||||
|
- リファクタリング計画
|
||||||
|
- シンボル追跡
|
||||||
|
- コード構造分析
|
||||||
|
NOT for: タスク管理、会話記憶
|
||||||
|
|
||||||
|
Sequential MCP (複雑な推論):
|
||||||
|
Trigger: 複雑な分析・設計が必要な時
|
||||||
|
PM Agent Role: Commander modeで活用
|
||||||
|
Examples:
|
||||||
|
- アーキテクチャ設計
|
||||||
|
- 複雑なデバッグ
|
||||||
|
- システム分析
|
||||||
|
|
||||||
|
Context7 MCP (ドキュメント参照):
|
||||||
|
Trigger: 公式ドキュメント参照が必要な時
|
||||||
|
PM Agent Role: Pre-Implementation Confidence Check
|
||||||
|
Examples:
|
||||||
|
- ライブラリの使い方確認
|
||||||
|
- ベストプラクティス参照
|
||||||
|
- API仕様確認
|
||||||
|
```
|
||||||
|
|
||||||
|
## 統合後のPM Agent Architecture
|
||||||
|
|
||||||
|
### 削除すべきもの
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
DELETE:
|
||||||
|
1. docs/memory/ ディレクトリ全体
|
||||||
|
理由: Mindbaseと重複、ライフサイクル不明確
|
||||||
|
|
||||||
|
2. MODE_Task_Management.md の memory操作部分
|
||||||
|
理由: pm-agent.mdと重複
|
||||||
|
|
||||||
|
3. pm-agent.md の docs/memory/ 参照
|
||||||
|
理由: Mindbaseに統合
|
||||||
|
|
||||||
|
4. write_memory() / read_memory() 使用
|
||||||
|
理由: Serenaはコード理解専用
|
||||||
|
```
|
||||||
|
|
||||||
|
### 統合後の責務
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
PM Agent Core Responsibilities:
|
||||||
|
|
||||||
|
1. Session Lifecycle Management:
|
||||||
|
Start:
|
||||||
|
- Git status確認
|
||||||
|
- CLAUDE.md読み込み
|
||||||
|
- docs/patterns/ 最近5件読み込み
|
||||||
|
- Mindbase自動ロード（Claude Code標準）
|
||||||
|
|
||||||
|
End:
|
||||||
|
- docs/patterns/ or docs/mistakes/ 更新
|
||||||
|
- CLAUDE.md更新（必要なら）
|
||||||
|
- Mindbase自動保存（Claude Code標準）
|
||||||
|
|
||||||
|
2. Documentation Guardian:
|
||||||
|
- 実装前にdocs/patterns/とdocs/mistakes/を確認
|
||||||
|
- 関連ドキュメントを自動読み込み
|
||||||
|
- Pre-Implementation Confidence Check
|
||||||
|
|
||||||
|
3. Commander (Complex Tasks):
|
||||||
|
- TodoWrite でタスク管理
|
||||||
|
- Sequentialで複雑な分析
|
||||||
|
- 並列実行の調整
|
||||||
|
|
||||||
|
4. Post-Implementation Documentation:
|
||||||
|
- 成功パターン → docs/patterns/
|
||||||
|
- 失敗記録 → docs/mistakes/
|
||||||
|
- グローバルルール → CLAUDE.md
|
||||||
|
|
||||||
|
5. Mistake Handler (Reflexion):
|
||||||
|
- docs/mistakes/ 検索（過去の失敗確認）
|
||||||
|
- 新しいミス → docs/mistakes/ 文書化
|
||||||
|
- 防止策の適用
|
||||||
|
```
|
||||||
|
|
||||||
|
### 簡潔な実装
|
||||||
|
|
||||||
|
**不要な複雑性の削除**:
|
||||||
|
```yaml
|
||||||
|
削除:
|
||||||
|
- docs/memory/ 全体（Mindbaseで代替）
|
||||||
|
- write_memory() 使用（Serenaはコード理解専用）
|
||||||
|
- 複雑なメモリ管理ロジック
|
||||||
|
|
||||||
|
残す:
|
||||||
|
- docs/patterns/（成功パターン）
|
||||||
|
- docs/mistakes/（失敗記録）
|
||||||
|
- CLAUDE.md（グローバルルール）
|
||||||
|
- TodoWrite（進捗管理）
|
||||||
|
```
|
||||||
|
|
||||||
|
**シンプルな自動起動**:
|
||||||
|
```yaml
|
||||||
|
Session Start:
|
||||||
|
1. git status && git branch
|
||||||
|
2. Read CLAUDE.md
|
||||||
|
3. Read docs/patterns/*.md (最近5件)
|
||||||
|
4. Mindbase自動ロード（透明）
|
||||||
|
5. 準備完了 → ユーザーリクエスト待機
|
||||||
|
|
||||||
|
実装前:
|
||||||
|
1. 関連docs/patterns/とdocs/mistakes/読む
|
||||||
|
2. Confidence Check
|
||||||
|
3. Context7で公式ドキュメント確認（必要なら）
|
||||||
|
|
||||||
|
実装中:
|
||||||
|
1. TodoWrite更新
|
||||||
|
2. コード理解が必要 → Serena使用
|
||||||
|
3. 複雑な分析 → Sequential使用
|
||||||
|
|
||||||
|
実装後:
|
||||||
|
1. パターン抽出 → docs/patterns/
|
||||||
|
2. ミス記録 → docs/mistakes/
|
||||||
|
3. グローバルルール → CLAUDE.md
|
||||||
|
4. Mindbase自動保存
|
||||||
|
```
|
||||||
|
|
||||||
|
## 移行手順
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Phase 1 - Cleanup:
|
||||||
|
- [ ] docs/memory/ ディレクトリ削除
|
||||||
|
- [ ] MODE_Task_Management.md からmemory操作削除
|
||||||
|
- [ ] pm-agent.md からdocs/memory/参照削除
|
||||||
|
|
||||||
|
Phase 2 - MCP Role Clarification:
|
||||||
|
- [ ] pm-agent.md にMCP使用ガイドライン追加
|
||||||
|
- [ ] Serena = コード理解専用 明記
|
||||||
|
- [ ] Mindbase = 自動管理 明記
|
||||||
|
- [ ] Sequential = 複雑な分析 明記
|
||||||
|
- [ ] Context7 = 公式ドキュメント参照 明記
|
||||||
|
|
||||||
|
Phase 3 - Documentation:
|
||||||
|
- [ ] docs/patterns/README.md 作成（成功パターン記録ガイド）
|
||||||
|
- [ ] docs/mistakes/README.md 作成（失敗記録ガイド）
|
||||||
|
- [ ] Memory管理ポリシー文書化
|
||||||
|
|
||||||
|
Phase 4 - Testing:
|
||||||
|
- [ ] セッション開始の自動ロードテスト
|
||||||
|
- [ ] 実装前のドキュメント確認テスト
|
||||||
|
- [ ] 実装後の文書化テスト
|
||||||
|
- [ ] MCPの適切な使用テスト
|
||||||
|
```
|
||||||
|
|
||||||
|
## 利点
|
||||||
|
|
||||||
|
**シンプルさ**:
|
||||||
|
- ✅ Memory管理層が明確（Mindbase / File-based / TodoWrite）
|
||||||
|
- ✅ MCPの役割が明確（Serena=コード、Sequential=分析、Context7=ドキュメント）
|
||||||
|
- ✅ 不要な複雑性削除（docs/memory/削除、write_memory()削除）
|
||||||
|
|
||||||
|
**保守性**:
|
||||||
|
- ✅ ライフサイクルが明確（永続 vs セッション内）
|
||||||
|
- ✅ 責務分離（会話=Mindbase、知識=docs/、進捗=TodoWrite）
|
||||||
|
- ✅ 削除ルールが明確（月次メンテナンス）
|
||||||
|
|
||||||
|
**効率性**:
|
||||||
|
- ✅ 自動管理（Mindbase、Serena自動削除）
|
||||||
|
- ✅ 必要最小限のファイル読み込み
|
||||||
|
- ✅ 適切なMCP使用（コード理解時のみSerena）
|
||||||
|
|
||||||
|
## 結論
|
||||||
|
|
||||||
|
**削除**: docs/memory/全体、write_memory()使用、MODE_Task_Management.mdのmemory部分
|
||||||
|
|
||||||
|
**統合**: Mindbase（会話履歴）+ docs/（知識ベース）+ TodoWrite（進捗）+ Serena（コード理解）
|
||||||
|
|
||||||
|
**簡潔化**: 責務を明確にして、不要な複雑性を削除
|
||||||
|
|
||||||
|
これでPM Agentはシンプルかつ強力になります。
|
||||||
507
docs/mcp/mcp-integration-policy.md
Normal file
507
docs/mcp/mcp-integration-policy.md
Normal file
@@ -0,0 +1,507 @@
|
|||||||
|
# MCP Integration Policy
|
||||||
|
|
||||||
|
SuperClaude FrameworkにおけるMCP (Model Context Protocol) サーバーの統合ポリシーと使用ガイドライン。
|
||||||
|
|
||||||
|
## MCP Server Definitions
|
||||||
|
|
||||||
|
### Core MCP Servers
|
||||||
|
|
||||||
|
#### Mindbase MCP
|
||||||
|
```yaml
|
||||||
|
Name: mindbase
|
||||||
|
Purpose: 会話履歴の長期保存と検索
|
||||||
|
Category: Memory Management
|
||||||
|
Auto-Managed: true (Claude Code標準機能)
|
||||||
|
PM Agent Role: None (自動管理、触らない)
|
||||||
|
|
||||||
|
Capabilities:
|
||||||
|
- 会話履歴の永続化
|
||||||
|
- セマンティック検索
|
||||||
|
- プロジェクト横断の知識共有
|
||||||
|
- 過去の会話からの学習
|
||||||
|
|
||||||
|
Lifecycle:
|
||||||
|
Start: 自動ロード
|
||||||
|
During: 自動保存
|
||||||
|
End: 自動保存
|
||||||
|
Cleanup: 自動（ユーザー設定による）
|
||||||
|
|
||||||
|
Usage Pattern:
|
||||||
|
- PM Agent: 使用しない（Claude Codeが自動管理）
|
||||||
|
- User: 透明（意識不要）
|
||||||
|
- Integration: 完全自動
|
||||||
|
|
||||||
|
Do NOT:
|
||||||
|
- 明示的にmindbase操作しない
|
||||||
|
- PM Agentでmindbase制御しない
|
||||||
|
- 手動でメモリ管理しない
|
||||||
|
|
||||||
|
Reason: Claude Code標準機能として完全に自動管理される
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Serena MCP
|
||||||
|
```yaml
|
||||||
|
Name: serena
|
||||||
|
Purpose: コードベース理解のためのシンボル管理
|
||||||
|
Category: Code Understanding
|
||||||
|
Auto-Managed: false (明示的使用)
|
||||||
|
PM Agent Role: コード理解タスクで自動活用
|
||||||
|
|
||||||
|
Capabilities:
|
||||||
|
- シンボル追跡（関数、クラス、変数）
|
||||||
|
- コード構造分析
|
||||||
|
- リファクタリング支援
|
||||||
|
- 依存関係マッピング
|
||||||
|
|
||||||
|
Lifecycle:
|
||||||
|
Start: 何もしない
|
||||||
|
During: コード理解時に使用
|
||||||
|
End: 自動削除（セッション終了）
|
||||||
|
Cleanup: 自動
|
||||||
|
|
||||||
|
Usage Pattern:
|
||||||
|
Use Cases:
|
||||||
|
- リファクタリング計画
|
||||||
|
- コード構造分析
|
||||||
|
- シンボル間の関係追跡
|
||||||
|
- 大規模コードベース探索
|
||||||
|
|
||||||
|
NOT for:
|
||||||
|
- タスク管理
|
||||||
|
- 会話記憶
|
||||||
|
- ドキュメント保存
|
||||||
|
- プロジェクト知識管理
|
||||||
|
|
||||||
|
Trigger Conditions:
|
||||||
|
- Keywords: "refactor", "analyze code structure", "find all usages"
|
||||||
|
- File Count: >10 files involved
|
||||||
|
- Complexity: Cross-file symbol tracking needed
|
||||||
|
|
||||||
|
Example:
|
||||||
|
Task: "Refactor authentication system across 15 files"
|
||||||
|
→ Serena: Track auth-related symbols
|
||||||
|
→ PM Agent: Coordinate refactoring with Serena insights
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Sequential MCP
|
||||||
|
```yaml
|
||||||
|
Name: sequential-thinking
|
||||||
|
Purpose: 複雑な推論と段階的分析
|
||||||
|
Category: Reasoning Engine
|
||||||
|
Auto-Managed: false (明示的使用)
|
||||||
|
PM Agent Role: Commander modeで複雑タスク分析
|
||||||
|
|
||||||
|
Capabilities:
|
||||||
|
- 段階的推論
|
||||||
|
- 仮説検証
|
||||||
|
- 複雑な問題分解
|
||||||
|
- システム設計分析
|
||||||
|
|
||||||
|
Lifecycle:
|
||||||
|
Start: 何もしない
|
||||||
|
During: 複雑分析時に使用
|
||||||
|
End: 分析結果を返す
|
||||||
|
Cleanup: 自動
|
||||||
|
|
||||||
|
Usage Pattern:
|
||||||
|
Use Cases:
|
||||||
|
- アーキテクチャ設計
|
||||||
|
- 複雑なバグ分析
|
||||||
|
- システム設計レビュー
|
||||||
|
- トレードオフ分析
|
||||||
|
|
||||||
|
NOT for:
|
||||||
|
- 単純なタスク
|
||||||
|
- 直感的に解決できる問題
|
||||||
|
- コード生成（分析のみ）
|
||||||
|
|
||||||
|
Trigger Conditions:
|
||||||
|
- Keywords: "design", "architecture", "analyze tradeoffs"
|
||||||
|
- Complexity: Multi-component system analysis
|
||||||
|
- Uncertainty: Multiple valid approaches exist
|
||||||
|
|
||||||
|
Example:
|
||||||
|
Task: "Design microservices architecture for authentication"
|
||||||
|
→ Sequential: Step-by-step design analysis
|
||||||
|
→ PM Agent: Document design decisions in docs/patterns/
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Context7 MCP
|
||||||
|
```yaml
|
||||||
|
Name: context7
|
||||||
|
Purpose: 公式ドキュメントとライブラリパターン参照
|
||||||
|
Category: Documentation Reference
|
||||||
|
Auto-Managed: false (明示的使用)
|
||||||
|
PM Agent Role: Pre-Implementation Confidence Check
|
||||||
|
|
||||||
|
Capabilities:
|
||||||
|
- 公式ドキュメント検索
|
||||||
|
- ライブラリベストプラクティス
|
||||||
|
- API仕様確認
|
||||||
|
- フレームワークパターン
|
||||||
|
|
||||||
|
Lifecycle:
|
||||||
|
Start: 何もしない
|
||||||
|
During: ドキュメント参照時に使用
|
||||||
|
End: 情報を返す
|
||||||
|
Cleanup: 自動
|
||||||
|
|
||||||
|
Usage Pattern:
|
||||||
|
Use Cases:
|
||||||
|
- ライブラリの使い方確認
|
||||||
|
- ベストプラクティス参照
|
||||||
|
- API仕様確認
|
||||||
|
- 公式パターン学習
|
||||||
|
|
||||||
|
NOT for:
|
||||||
|
- プロジェクト固有ドキュメント（docs/使用）
|
||||||
|
- 社内ドキュメント
|
||||||
|
- カスタム実装パターン
|
||||||
|
|
||||||
|
Trigger Conditions:
|
||||||
|
- Pre-Implementation: Confidence check時
|
||||||
|
- Keywords: "official docs", "best practices", "how to use [library]"
|
||||||
|
- New Library: 初めて使うライブラリ
|
||||||
|
|
||||||
|
Example:
|
||||||
|
Task: "Implement JWT authentication with jose library"
|
||||||
|
→ Context7: Fetch jose official docs and patterns
|
||||||
|
→ PM Agent: Verify implementation against official patterns
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Tavily MCP
|
||||||
|
```yaml
|
||||||
|
Name: tavily
|
||||||
|
Purpose: Web検索とリアルタイム情報取得
|
||||||
|
Category: Research
|
||||||
|
Auto-Managed: false (明示的使用)
|
||||||
|
PM Agent Role: Research modeで情報収集
|
||||||
|
|
||||||
|
Capabilities:
|
||||||
|
- Web検索
|
||||||
|
- 最新情報取得
|
||||||
|
- 技術記事検索
|
||||||
|
- エラーメッセージ検索
|
||||||
|
|
||||||
|
Lifecycle:
|
||||||
|
Start: 何もしない
|
||||||
|
During: 研究・調査時に使用
|
||||||
|
End: 検索結果を返す
|
||||||
|
Cleanup: 自動
|
||||||
|
|
||||||
|
Usage Pattern:
|
||||||
|
Use Cases:
|
||||||
|
- 最新のライブラリバージョン確認
|
||||||
|
- エラーメッセージの解決策検索
|
||||||
|
- 技術トレンド調査
|
||||||
|
- 公式ドキュメント検索（Context7にない場合）
|
||||||
|
|
||||||
|
NOT for:
|
||||||
|
- プロジェクト内情報（Grep使用）
|
||||||
|
- コードベース検索（Serena使用）
|
||||||
|
- 過去の会話（Mindbase使用）
|
||||||
|
|
||||||
|
Trigger Conditions:
|
||||||
|
- Keywords: "search", "latest", "current"
|
||||||
|
- Error: Unknown error message
|
||||||
|
- Research: New technology investigation
|
||||||
|
|
||||||
|
Example:
|
||||||
|
Task: "Find latest Next.js 15 App Router patterns"
|
||||||
|
→ Tavily: Search web for latest patterns
|
||||||
|
→ PM Agent: Document findings in docs/patterns/
|
||||||
|
```
|
||||||
|
|
||||||
|
## MCP Selection Matrix
|
||||||
|
|
||||||
|
### By Task Type
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Code Understanding:
|
||||||
|
Primary: Serena MCP
|
||||||
|
Secondary: Grep (simple searches)
|
||||||
|
Example: "Find all authentication-related symbols"
|
||||||
|
|
||||||
|
Complex Analysis:
|
||||||
|
Primary: Sequential MCP
|
||||||
|
Secondary: Native reasoning (simple cases)
|
||||||
|
Example: "Design authentication architecture"
|
||||||
|
|
||||||
|
Documentation Reference:
|
||||||
|
Primary: Context7 MCP
|
||||||
|
Secondary: Tavily (if not in Context7)
|
||||||
|
Example: "How to use React Server Components"
|
||||||
|
|
||||||
|
Research & Investigation:
|
||||||
|
Primary: Tavily MCP
|
||||||
|
Secondary: Context7 (official docs)
|
||||||
|
Example: "Latest security best practices 2025"
|
||||||
|
|
||||||
|
Memory & History:
|
||||||
|
Primary: Mindbase MCP (automatic)
|
||||||
|
Secondary: None (fully automated)
|
||||||
|
Example: N/A (transparent)
|
||||||
|
|
||||||
|
Task Management:
|
||||||
|
Primary: TodoWrite (built-in)
|
||||||
|
Secondary: None
|
||||||
|
Example: Track multi-step implementation
|
||||||
|
```
|
||||||
|
|
||||||
|
### By Complexity Level
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Simple (1-2 files, clear path):
|
||||||
|
MCPs: None (native tools sufficient)
|
||||||
|
Tools: Read, Edit, Grep, Bash
|
||||||
|
|
||||||
|
Medium (3-10 files, some complexity):
|
||||||
|
MCPs: Context7 (if new library)
|
||||||
|
Tools: MultiEdit, Glob, Grep
|
||||||
|
|
||||||
|
Complex (>10 files, architectural changes):
|
||||||
|
MCPs: Serena + Sequential
|
||||||
|
Coordination: PM Agent Commander mode
|
||||||
|
Tools: Task delegation, parallel execution
|
||||||
|
|
||||||
|
Research (information gathering):
|
||||||
|
MCPs: Tavily + Context7
|
||||||
|
Mode: DeepResearch mode
|
||||||
|
Tools: WebFetch (selective)
|
||||||
|
```
|
||||||
|
|
||||||
|
## PM Agent Integration Rules
|
||||||
|
|
||||||
|
### Session Lifecycle
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Session Start:
|
||||||
|
Auto-Execute:
|
||||||
|
1. git status && git branch
|
||||||
|
2. Read CLAUDE.md
|
||||||
|
3. Read docs/patterns/*.md (latest 5)
|
||||||
|
4. Mindbase auto-load (automatic)
|
||||||
|
|
||||||
|
MCPs Used:
|
||||||
|
- Mindbase: Automatic (no explicit call)
|
||||||
|
- Others: None (wait for task)
|
||||||
|
|
||||||
|
Output: 📍 [branch] | [status] | 🧠 [token]%
|
||||||
|
|
||||||
|
Pre-Implementation:
|
||||||
|
Auto-Execute:
|
||||||
|
1. Read relevant docs/patterns/
|
||||||
|
2. Read relevant docs/mistakes/
|
||||||
|
3. Confidence check
|
||||||
|
|
||||||
|
MCPs Used:
|
||||||
|
- Context7: If new library (automatic)
|
||||||
|
- Serena: If complex refactor (automatic)
|
||||||
|
|
||||||
|
Decision:
|
||||||
|
High Confidence (>90%): Proceed
|
||||||
|
Medium (70-89%): Present options
|
||||||
|
Low (<70%): Stop, request clarification
|
||||||
|
|
||||||
|
During Implementation:
|
||||||
|
Manual Trigger:
|
||||||
|
- TodoWrite: Progress tracking
|
||||||
|
- Serena: Code understanding (if needed)
|
||||||
|
- Sequential: Complex analysis (if needed)
|
||||||
|
|
||||||
|
MCPs Used:
|
||||||
|
- Serena: On code complexity trigger
|
||||||
|
- Sequential: On analysis keyword
|
||||||
|
- Context7: On documentation need
|
||||||
|
|
||||||
|
Post-Implementation:
|
||||||
|
Auto-Execute:
|
||||||
|
1. Self-evaluation (Four Questions)
|
||||||
|
2. Pattern extraction
|
||||||
|
3. Documentation update
|
||||||
|
|
||||||
|
MCPs Used:
|
||||||
|
- Mindbase: Automatic save
|
||||||
|
- Others: None (file-based documentation)
|
||||||
|
|
||||||
|
Output:
|
||||||
|
- Success → docs/patterns/
|
||||||
|
- Failure → docs/mistakes/
|
||||||
|
- Global → CLAUDE.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### MCP Activation Triggers
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Serena MCP:
|
||||||
|
Auto-Trigger Keywords:
|
||||||
|
- "refactor"
|
||||||
|
- "analyze code structure"
|
||||||
|
- "find all usages"
|
||||||
|
- "symbol tracking"
|
||||||
|
|
||||||
|
Auto-Trigger Conditions:
|
||||||
|
- File count > 10
|
||||||
|
- Cross-file changes
|
||||||
|
- Symbol renaming
|
||||||
|
- Dependency analysis
|
||||||
|
|
||||||
|
Manual Override: --serena flag
|
||||||
|
|
||||||
|
Sequential MCP:
|
||||||
|
Auto-Trigger Keywords:
|
||||||
|
- "design"
|
||||||
|
- "architecture"
|
||||||
|
- "analyze tradeoffs"
|
||||||
|
- "complex problem"
|
||||||
|
|
||||||
|
Auto-Trigger Conditions:
|
||||||
|
- System design task
|
||||||
|
- Multiple valid approaches
|
||||||
|
- Uncertainty in implementation
|
||||||
|
- Architectural decision
|
||||||
|
|
||||||
|
Manual Override: --seq flag
|
||||||
|
|
||||||
|
Context7 MCP:
|
||||||
|
Auto-Trigger Keywords:
|
||||||
|
- "official docs"
|
||||||
|
- "best practices"
|
||||||
|
- "how to use [library]"
|
||||||
|
- New library detected
|
||||||
|
|
||||||
|
Auto-Trigger Conditions:
|
||||||
|
- Pre-Implementation confidence check
|
||||||
|
- New library in package.json
|
||||||
|
- Framework pattern needed
|
||||||
|
|
||||||
|
Manual Override: --c7 flag
|
||||||
|
|
||||||
|
Tavily MCP:
|
||||||
|
Auto-Trigger Keywords:
|
||||||
|
- "search"
|
||||||
|
- "latest"
|
||||||
|
- "current trends"
|
||||||
|
- "find error solution"
|
||||||
|
|
||||||
|
Auto-Trigger Conditions:
|
||||||
|
- Research mode active
|
||||||
|
- Unknown error message
|
||||||
|
- Latest version check
|
||||||
|
|
||||||
|
Manual Override: --tavily flag
|
||||||
|
```
|
||||||
|
|
||||||
|
## Anti-Patterns (禁止事項)
|
||||||
|
|
||||||
|
### DO NOT
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
❌ Mindbaseを明示的に操作:
|
||||||
|
Reason: 完全自動管理、PM Agentは触らない
|
||||||
|
Instead: 何もしない（自動で動く）
|
||||||
|
|
||||||
|
❌ Serenaをタスク管理に使用:
|
||||||
|
Reason: コード理解専用
|
||||||
|
Instead: TodoWrite使用
|
||||||
|
|
||||||
|
❌ write_memory() / read_memory() 使用:
|
||||||
|
Reason: Serenaはコード理解専用、タスク管理ではない
|
||||||
|
Instead: TodoWrite + docs/
|
||||||
|
|
||||||
|
❌ docs/memory/ ディレクトリ作成:
|
||||||
|
Reason: Mindbaseと重複
|
||||||
|
Instead: docs/patterns/ と docs/mistakes/ 使用
|
||||||
|
|
||||||
|
❌ 全タスクでSequential使用:
|
||||||
|
Reason: トークン浪費
|
||||||
|
Instead: 複雑分析時のみ
|
||||||
|
|
||||||
|
❌ Context7をプロジェクトドキュメントに使用:
|
||||||
|
Reason: 公式ドキュメント専用
|
||||||
|
Instead: Read docs/ 使用
|
||||||
|
```
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### Efficient MCP Usage
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
✅ Right Tool for Right Job:
|
||||||
|
Simple → Native tools (Read, Edit, Grep)
|
||||||
|
Medium → Context7 (new library)
|
||||||
|
Complex → Serena + Sequential
|
||||||
|
|
||||||
|
✅ Lazy Evaluation:
|
||||||
|
Don't preload MCPs
|
||||||
|
Activate only when needed
|
||||||
|
Let PM Agent auto-trigger
|
||||||
|
|
||||||
|
✅ Clear Separation:
|
||||||
|
Memory: Mindbase (automatic)
|
||||||
|
Knowledge: docs/ (file-based)
|
||||||
|
Progress: TodoWrite (session)
|
||||||
|
Code: Serena (understanding)
|
||||||
|
|
||||||
|
✅ Documentation First:
|
||||||
|
Pre-Implementation: Context7 + docs/patterns/
|
||||||
|
During: TodoWrite tracking
|
||||||
|
Post: docs/patterns/ or docs/mistakes/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Testing & Validation
|
||||||
|
|
||||||
|
### MCP Integration Tests
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Test Cases:
|
||||||
|
|
||||||
|
1. Mindbase Auto-Load:
|
||||||
|
- Start session
|
||||||
|
- Verify past context loaded automatically
|
||||||
|
- No explicit mindbase calls
|
||||||
|
|
||||||
|
2. Serena Code Understanding:
|
||||||
|
- Task: "Refactor auth across 15 files"
|
||||||
|
- Verify Serena auto-triggered
|
||||||
|
- Verify symbol tracking used
|
||||||
|
|
||||||
|
3. Sequential Complex Analysis:
|
||||||
|
- Task: "Design microservices architecture"
|
||||||
|
- Verify Sequential auto-triggered
|
||||||
|
- Verify step-by-step reasoning
|
||||||
|
|
||||||
|
4. Context7 Documentation:
|
||||||
|
- Task: "Implement with new library"
|
||||||
|
- Verify Context7 auto-triggered
|
||||||
|
- Verify official docs referenced
|
||||||
|
|
||||||
|
5. Tavily Research:
|
||||||
|
- Task: "Find latest security patterns"
|
||||||
|
- Verify Tavily auto-triggered
|
||||||
|
- Verify web search executed
|
||||||
|
```
|
||||||
|
|
||||||
|
## Migration Checklist
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
From Old System:
|
||||||
|
- [ ] Remove docs/memory/ references
|
||||||
|
- [ ] Remove write_memory() / read_memory() calls
|
||||||
|
- [ ] Remove MODE_Task_Management.md memory sections
|
||||||
|
- [ ] Update pm-agent.md with new MCP policy
|
||||||
|
|
||||||
|
To New System:
|
||||||
|
- [ ] Add MCP integration policy docs
|
||||||
|
- [ ] Update pm-agent.md triggers
|
||||||
|
- [ ] Add auto-activation logic
|
||||||
|
- [ ] Test MCP selection matrix
|
||||||
|
- [ ] Validate anti-patterns enforcement
|
||||||
|
```
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- PM Agent: `~/.claude/superclaude/agents/pm-agent.md`
|
||||||
|
- Modes: `~/.claude/superclaude/modes/MODE_*.md`
|
||||||
|
- Rules: `~/.claude/superclaude/framework/rules.md`
|
||||||
|
- Memory Cleanup: `docs/architecture/pm-agent-responsibility-cleanup.md`
|
||||||
454
docs/mcp/mcp-optional-design.md
Normal file
454
docs/mcp/mcp-optional-design.md
Normal file
@@ -0,0 +1,454 @@
|
|||||||
|
# MCP Optional Design
|
||||||
|
|
||||||
|
## 基本原則: MCPはオプション
|
||||||
|
|
||||||
|
**重要**: SuperClaude Frameworkは **MCPなしでも完全に動作** します。
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Core Principle:
|
||||||
|
MCPs: Optional enhancements (性能向上のオプション)
|
||||||
|
Native Tools: Always available (常に利用可能)
|
||||||
|
Fallback: Automatic (自動フォールバック)
|
||||||
|
|
||||||
|
Design Philosophy:
|
||||||
|
"MCPs enhance, but never required"
|
||||||
|
"Native tools are the foundation"
|
||||||
|
"Graceful degradation always"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Fallback Strategy
|
||||||
|
|
||||||
|
### MCP vs Native Tools
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Code Understanding:
|
||||||
|
With MCP: Serena (シンボル追跡、高速)
|
||||||
|
Without MCP: Grep + Read (テキスト検索、確実)
|
||||||
|
Degradation: 機能維持、速度低下のみ
|
||||||
|
|
||||||
|
Complex Analysis:
|
||||||
|
With MCP: Sequential (構造化推論、トークン効率)
|
||||||
|
Without MCP: Native reasoning (同等品質、トークン増)
|
||||||
|
Degradation: トークン使用量増加のみ
|
||||||
|
|
||||||
|
Documentation:
|
||||||
|
With MCP: Context7 (公式ドキュメント、キュレーション済み)
|
||||||
|
Without MCP: WebFetch + WebSearch (生データ、手動フィルタ)
|
||||||
|
Degradation: 情報の質が若干低下
|
||||||
|
|
||||||
|
Research:
|
||||||
|
With MCP: Tavily (最適化検索、構造化結果)
|
||||||
|
Without MCP: WebSearch (標準検索)
|
||||||
|
Degradation: 検索効率が若干低下
|
||||||
|
|
||||||
|
Memory:
|
||||||
|
With MCP: Mindbase (自動管理、永続化)
|
||||||
|
Without MCP: Session context only (セッション内のみ)
|
||||||
|
Degradation: クロスセッション記憶なし
|
||||||
|
```
|
||||||
|
|
||||||
|
## PM Agent Without MCPs
|
||||||
|
|
||||||
|
### Fully Functional Without Any MCP
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Session Start:
|
||||||
|
With MCPs:
|
||||||
|
- Git status ✅
|
||||||
|
- Read CLAUDE.md ✅
|
||||||
|
- Read docs/patterns/ ✅
|
||||||
|
- Mindbase auto-load ⚡ (optional)
|
||||||
|
|
||||||
|
Without MCPs:
|
||||||
|
- Git status ✅
|
||||||
|
- Read CLAUDE.md ✅
|
||||||
|
- Read docs/patterns/ ✅
|
||||||
|
- Session context only ✅
|
||||||
|
|
||||||
|
Result: 完全動作（クロスセッション記憶以外）
|
||||||
|
|
||||||
|
Pre-Implementation:
|
||||||
|
With MCPs:
|
||||||
|
- Read docs/patterns/ ✅
|
||||||
|
- Read docs/mistakes/ ✅
|
||||||
|
- Context7 official docs ⚡ (optional)
|
||||||
|
- Confidence check ✅
|
||||||
|
|
||||||
|
Without MCPs:
|
||||||
|
- Read docs/patterns/ ✅
|
||||||
|
- Read docs/mistakes/ ✅
|
||||||
|
- WebSearch official docs ✅
|
||||||
|
- Confidence check ✅
|
||||||
|
|
||||||
|
Result: 完全動作（ドキュメント取得が若干遅い）
|
||||||
|
|
||||||
|
During Implementation:
|
||||||
|
With MCPs:
|
||||||
|
- TodoWrite ✅
|
||||||
|
- Serena code understanding ⚡ (optional)
|
||||||
|
- Sequential complex analysis ⚡ (optional)
|
||||||
|
|
||||||
|
Without MCPs:
|
||||||
|
- TodoWrite ✅
|
||||||
|
- Grep + Read code search ✅
|
||||||
|
- Native reasoning ✅
|
||||||
|
|
||||||
|
Result: 完全動作（大規模コードベースで遅い）
|
||||||
|
|
||||||
|
Post-Implementation:
|
||||||
|
With MCPs:
|
||||||
|
- Self-evaluation ✅
|
||||||
|
- docs/patterns/ update ✅
|
||||||
|
- docs/mistakes/ update ✅
|
||||||
|
- Mindbase auto-save ⚡ (optional)
|
||||||
|
|
||||||
|
Without MCPs:
|
||||||
|
- Self-evaluation ✅
|
||||||
|
- docs/patterns/ update ✅
|
||||||
|
- docs/mistakes/ update ✅
|
||||||
|
- Session summary only ✅
|
||||||
|
|
||||||
|
Result: 完全動作（クロスセッション学習以外）
|
||||||
|
```
|
||||||
|
|
||||||
|
## Detection & Auto-Fallback
|
||||||
|
|
||||||
|
### MCP Availability Detection
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Runtime Detection:
|
||||||
|
Method: Try MCP, catch error, fallback
|
||||||
|
|
||||||
|
Example:
|
||||||
|
try:
|
||||||
|
serena.search_symbols("authenticate")
|
||||||
|
except MCPNotAvailable:
|
||||||
|
fallback_to_grep("authenticate")
|
||||||
|
|
||||||
|
User Impact: None (transparent)
|
||||||
|
Performance: Slightly slower on first detection
|
||||||
|
|
||||||
|
Startup Check:
|
||||||
|
Method: List available MCP servers
|
||||||
|
|
||||||
|
Available MCPs: [mindbase, serena, sequential]
|
||||||
|
Missing MCPs: [context7, tavily]
|
||||||
|
|
||||||
|
→ Auto-configure fallbacks
|
||||||
|
→ Log available MCPs
|
||||||
|
→ Proceed normally
|
||||||
|
```
|
||||||
|
|
||||||
|
### Automatic Fallback Logic
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Serena MCP Unavailable:
|
||||||
|
Task: "Refactor auth across 15 files"
|
||||||
|
|
||||||
|
Attempt:
|
||||||
|
1. Try Serena symbol tracking
|
||||||
|
2. MCPNotAvailable error
|
||||||
|
3. Fallback to Grep + Read
|
||||||
|
|
||||||
|
Execution:
|
||||||
|
grep -r "authenticate\|auth\|login" .
|
||||||
|
Read all matched files
|
||||||
|
Manual symbol tracking (slower but works)
|
||||||
|
|
||||||
|
Output: Same result, slower execution
|
||||||
|
|
||||||
|
Sequential MCP Unavailable:
|
||||||
|
Task: "Design microservices architecture"
|
||||||
|
|
||||||
|
Attempt:
|
||||||
|
1. Try Sequential reasoning
|
||||||
|
2. MCPNotAvailable error
|
||||||
|
3. Fallback to native reasoning
|
||||||
|
|
||||||
|
Execution:
|
||||||
|
Use native Claude reasoning
|
||||||
|
Break down problem manually
|
||||||
|
Step-by-step analysis (more tokens)
|
||||||
|
|
||||||
|
Output: Same quality, more tokens
|
||||||
|
|
||||||
|
Context7 MCP Unavailable:
|
||||||
|
Task: "How to use React Server Components"
|
||||||
|
|
||||||
|
Attempt:
|
||||||
|
1. Try Context7 official docs
|
||||||
|
2. MCPNotAvailable error
|
||||||
|
3. Fallback to WebSearch
|
||||||
|
|
||||||
|
Execution:
|
||||||
|
WebSearch "React Server Components official docs"
|
||||||
|
WebFetch relevant URLs
|
||||||
|
Manual filtering
|
||||||
|
|
||||||
|
Output: Same info, less curated
|
||||||
|
|
||||||
|
Mindbase MCP Unavailable:
|
||||||
|
Impact: No cross-session memory
|
||||||
|
|
||||||
|
Fallback:
|
||||||
|
- Use session context only
|
||||||
|
- docs/patterns/ for knowledge
|
||||||
|
- docs/mistakes/ for learnings
|
||||||
|
|
||||||
|
Limitation:
|
||||||
|
- Can't recall previous sessions automatically
|
||||||
|
- User can manually reference past work
|
||||||
|
|
||||||
|
Workaround: "Recall our conversation about X"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
### MCP Enable/Disable
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
User Configuration:
|
||||||
|
Location: ~/.claude/mcp-config.json (optional)
|
||||||
|
|
||||||
|
{
|
||||||
|
"mcps": {
|
||||||
|
"mindbase": "auto", // enabled if available
|
||||||
|
"serena": "auto", // enabled if available
|
||||||
|
"sequential": "auto", // enabled if available
|
||||||
|
"context7": "disabled", // explicitly disabled
|
||||||
|
"tavily": "enabled" // explicitly enabled
|
||||||
|
},
|
||||||
|
"fallback_mode": "graceful" // graceful | aggressive | disabled
|
||||||
|
}
|
||||||
|
|
||||||
|
Fallback Modes:
|
||||||
|
graceful: Try MCP, fallback silently (default)
|
||||||
|
aggressive: Prefer native tools, use MCP only when significantly better
|
||||||
|
disabled: Never fallback, error if MCP unavailable
|
||||||
|
```
|
||||||
|
|
||||||
|
### Performance Comparison
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Task: Refactor 15 files
|
||||||
|
|
||||||
|
With Serena MCP:
|
||||||
|
Time: 30 seconds
|
||||||
|
Tokens: 5,000
|
||||||
|
Accuracy: 95%
|
||||||
|
|
||||||
|
Without Serena (Grep fallback):
|
||||||
|
Time: 90 seconds
|
||||||
|
Tokens: 5,000
|
||||||
|
Accuracy: 95%
|
||||||
|
|
||||||
|
Difference: 3x slower, same quality
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Task: Design architecture
|
||||||
|
|
||||||
|
With Sequential MCP:
|
||||||
|
Time: 60 seconds
|
||||||
|
Tokens: 8,000
|
||||||
|
Accuracy: 90%
|
||||||
|
|
||||||
|
Without Sequential (Native reasoning):
|
||||||
|
Time: 60 seconds
|
||||||
|
Tokens: 15,000
|
||||||
|
Accuracy: 90%
|
||||||
|
|
||||||
|
Difference: Same speed, 2x tokens
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Task: Fetch official docs
|
||||||
|
|
||||||
|
With Context7 MCP:
|
||||||
|
Time: 10 seconds
|
||||||
|
Relevance: 95%
|
||||||
|
Curated: Yes
|
||||||
|
|
||||||
|
Without Context7 (WebSearch):
|
||||||
|
Time: 30 seconds
|
||||||
|
Relevance: 80%
|
||||||
|
Curated: No
|
||||||
|
|
||||||
|
Difference: 3x slower, less relevant
|
||||||
|
```
|
||||||
|
|
||||||
|
## Testing Without MCPs
|
||||||
|
|
||||||
|
### Test Scenarios
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Scenario 1: No MCPs Installed
|
||||||
|
Setup: Fresh Claude Code, no MCP servers
|
||||||
|
|
||||||
|
Test Cases:
|
||||||
|
- [ ] Session start works
|
||||||
|
- [ ] CLAUDE.md loaded
|
||||||
|
- [ ] docs/patterns/ readable
|
||||||
|
- [ ] Code search via Grep
|
||||||
|
- [ ] TodoWrite functional
|
||||||
|
- [ ] Documentation updates work
|
||||||
|
|
||||||
|
Expected: All core functionality works
|
||||||
|
|
||||||
|
Scenario 2: Partial MCPs Available
|
||||||
|
Setup: Only Mindbase installed
|
||||||
|
|
||||||
|
Test Cases:
|
||||||
|
- [ ] Session memory works (Mindbase)
|
||||||
|
- [ ] Code search fallback (Grep)
|
||||||
|
- [ ] Analysis fallback (Native)
|
||||||
|
- [ ] Docs fallback (WebSearch)
|
||||||
|
|
||||||
|
Expected: Memory works, others fallback
|
||||||
|
|
||||||
|
Scenario 3: MCP Becomes Unavailable
|
||||||
|
Setup: Start with MCP, MCP crashes mid-session
|
||||||
|
|
||||||
|
Test Cases:
|
||||||
|
- [ ] Detect MCP failure
|
||||||
|
- [ ] Auto-fallback to native
|
||||||
|
- [ ] Session continues normally
|
||||||
|
- [ ] User not impacted
|
||||||
|
|
||||||
|
Expected: Graceful degradation
|
||||||
|
|
||||||
|
Scenario 4: MCP Performance Issues
|
||||||
|
Setup: MCP slow or timeout
|
||||||
|
|
||||||
|
Test Cases:
|
||||||
|
- [ ] Timeout detection (5 seconds)
|
||||||
|
- [ ] Auto-fallback
|
||||||
|
- [ ] Log performance issue
|
||||||
|
- [ ] Continue with native
|
||||||
|
|
||||||
|
Expected: No blocking, auto-fallback
|
||||||
|
```
|
||||||
|
|
||||||
|
## Documentation Strategy
|
||||||
|
|
||||||
|
### User-Facing Documentation
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Getting Started:
|
||||||
|
"SuperClaude works out of the box without any MCPs"
|
||||||
|
"MCPs are optional performance enhancements"
|
||||||
|
"Install MCPs for better performance, not required"
|
||||||
|
|
||||||
|
Installation Guide:
|
||||||
|
Minimal Setup:
|
||||||
|
- Clone repo
|
||||||
|
- Run installer
|
||||||
|
- Start using (no MCPs)
|
||||||
|
|
||||||
|
Enhanced Setup (Optional):
|
||||||
|
- Install Mindbase (cross-session memory)
|
||||||
|
- Install Serena (faster code understanding)
|
||||||
|
- Install Sequential (token efficiency)
|
||||||
|
- Install Context7 (curated docs)
|
||||||
|
- Install Tavily (better search)
|
||||||
|
|
||||||
|
Performance Comparison:
|
||||||
|
"With MCPs: 2-3x faster, 30-50% fewer tokens"
|
||||||
|
"Without MCPs: Slightly slower, works perfectly"
|
||||||
|
"Recommendation: Start without, add MCPs if needed"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Developer Documentation
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
MCP Integration Guidelines:
|
||||||
|
|
||||||
|
Rule 1: Always provide fallback
|
||||||
|
✅ try_mcp_then_fallback()
|
||||||
|
❌ require_mcp_or_fail()
|
||||||
|
|
||||||
|
Rule 2: Silent degradation
|
||||||
|
✅ Fallback transparently
|
||||||
|
❌ Show errors to user
|
||||||
|
|
||||||
|
Rule 3: Test both paths
|
||||||
|
✅ Test with and without MCPs
|
||||||
|
❌ Only test with MCPs
|
||||||
|
|
||||||
|
Rule 4: Document fallback behavior
|
||||||
|
✅ "Uses Grep if Serena unavailable"
|
||||||
|
❌ "Requires Serena MCP"
|
||||||
|
|
||||||
|
Rule 5: Performance expectations
|
||||||
|
✅ "30% slower without MCP"
|
||||||
|
❌ "Not functional without MCP"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Benefits of Optional Design
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Accessibility:
|
||||||
|
✅ No barriers to entry
|
||||||
|
✅ Works on any system
|
||||||
|
✅ No additional dependencies
|
||||||
|
✅ Easy onboarding
|
||||||
|
|
||||||
|
Reliability:
|
||||||
|
✅ No single point of failure
|
||||||
|
✅ Graceful degradation
|
||||||
|
✅ Always functional baseline
|
||||||
|
✅ MCP issues don't block work
|
||||||
|
|
||||||
|
Flexibility:
|
||||||
|
✅ Users choose their setup
|
||||||
|
✅ Incremental enhancement
|
||||||
|
✅ Mix and match MCPs
|
||||||
|
✅ Easy testing/debugging
|
||||||
|
|
||||||
|
Maintenance:
|
||||||
|
✅ Framework works independently
|
||||||
|
✅ MCP updates don't break framework
|
||||||
|
✅ Easy to add new MCPs
|
||||||
|
✅ Easy to remove problematic MCPs
|
||||||
|
```
|
||||||
|
|
||||||
|
## Migration Path
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Current Users (No MCPs):
|
||||||
|
Status: Already working
|
||||||
|
Action: None required
|
||||||
|
Benefit: Can add MCPs incrementally
|
||||||
|
|
||||||
|
New Users:
|
||||||
|
Step 1: Install framework (works immediately)
|
||||||
|
Step 2: Use without MCPs (full functionality)
|
||||||
|
Step 3: Add MCPs if desired (performance boost)
|
||||||
|
|
||||||
|
MCP Adoption:
|
||||||
|
Mindset: "Nice to have, not must have"
|
||||||
|
Approach: Incremental enhancement
|
||||||
|
Philosophy: Core functionality always works
|
||||||
|
```
|
||||||
|
|
||||||
|
## Conclusion
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
Core Message:
|
||||||
|
"SuperClaude Framework is MCP-optional by design"
|
||||||
|
"MCPs enhance performance, not functionality"
|
||||||
|
"Native tools provide reliable baseline"
|
||||||
|
"Choose your enhancement level"
|
||||||
|
|
||||||
|
User Choice:
|
||||||
|
Minimal: No MCPs, full functionality
|
||||||
|
Standard: Mindbase only, cross-session memory
|
||||||
|
Enhanced: All MCPs, maximum performance
|
||||||
|
Custom: Pick and choose based on needs
|
||||||
|
|
||||||
|
Design Success:
|
||||||
|
✅ Zero dependencies for basic operation
|
||||||
|
✅ Graceful degradation always
|
||||||
|
✅ User empowerment through choice
|
||||||
|
✅ Reliable baseline guaranteed
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user