mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
refactor: PEP8 compliance - directory rename and code formatting (#425)
* fix(orchestration): add WebFetch auto-trigger for infrastructure configuration Problem: Infrastructure configuration changes (e.g., Traefik port settings) were being made based on assumptions without consulting official documentation, violating the 'Evidence > assumptions' principle in PRINCIPLES.md. Solution: - Added Infrastructure Configuration Validation section to MODE_Orchestration.md - Auto-triggers WebFetch for infrastructure tools (Traefik, nginx, Docker, etc.) - Enforces MODE_DeepResearch activation for investigation - BLOCKS assumption-based configuration changes Testing: Verified WebFetch successfully retrieves Traefik official docs (port 80 default) This prevents production outages from infrastructure misconfiguration by ensuring all technical recommendations are backed by official documentation. * feat: Add PM Agent (Project Manager Agent) for seamless orchestration Introduces PM Agent as the default orchestration layer that coordinates all sub-agents and manages workflows automatically. Key Features: - Default orchestration: All user interactions handled by PM Agent - Auto-delegation: Intelligent sub-agent selection based on task analysis - Docker Gateway integration: Zero-token baseline with dynamic MCP loading - Self-improvement loop: Automatic documentation of patterns and mistakes - Optional override: Users can specify sub-agents explicitly if desired Architecture: - Agent spec: SuperClaude/Agents/pm-agent.md - Command: SuperClaude/Commands/pm.md - Updated docs: README.md (15→16 agents), agents.md (new Orchestration category) User Experience: - Default: PM Agent handles everything (seamless, no manual routing) - Optional: Explicit --agent flag for direct sub-agent access - Both modes available simultaneously (no user downside) Implementation Status: - ✅ Specification complete - ✅ Documentation complete - ⏳ Prototype implementation needed - ⏳ Docker Gateway integration needed - ⏳ Testing and validation needed Refs: kazukinakai/docker-mcp-gateway (IRIS MCP Gateway integration) * feat: Add Agent Orchestration rules for PM Agent default activation Implements PM Agent as the default orchestration layer in RULES.md. Key Changes: - New 'Agent Orchestration' section (CRITICAL priority) - PM Agent receives ALL user requests by default - Manual override with @agent-[name] bypasses PM Agent - Agent Selection Priority clearly defined: 1. Manual override → Direct routing 2. Default → PM Agent → Auto-delegation 3. Delegation based on keywords, file types, complexity, context User Experience: - Default: PM Agent handles everything (seamless) - Override: @agent-[name] for direct specialist access - Transparent: PM Agent reports delegation decisions This establishes PM Agent as the orchestration layer while respecting existing auto-activation patterns and manual overrides. Next Steps: - Local testing in agiletec project - Iteration based on actual behavior - Documentation updates as needed * refactor(pm-agent): redesign as self-improvement meta-layer Problem Resolution: PM Agent's initial design competed with existing auto-activation for task routing, creating confusion about orchestration responsibilities and adding unnecessary complexity. Design Change: Redefined PM Agent as a meta-layer agent that operates AFTER specialist agents complete tasks, focusing on: - Post-implementation documentation and pattern recording - Immediate mistake analysis with prevention checklists - Monthly documentation maintenance and noise reduction - Pattern extraction and knowledge synthesis Two-Layer Orchestration System: 1. Task Execution Layer: Existing auto-activation handles task routing (unchanged) 2. Self-Improvement Layer: PM Agent meta-layer handles documentation (new) Files Modified: - SuperClaude/Agents/pm-agent.md: Complete rewrite with meta-layer design - Category: orchestration → meta - Triggers: All user interactions → Post-implementation, mistakes, monthly - Behavioral Mindset: Continuous learning system - Self-Improvement Workflow: BEFORE/DURING/AFTER/MISTAKE RECOVERY/MAINTENANCE - SuperClaude/Core/RULES.md: Agent Orchestration section updated - Split into Task Execution Layer + Self-Improvement Layer - Added orchestration flow diagram - Clarified PM Agent activates AFTER task completion - README.md: Updated PM Agent description - "orchestrates all interactions" → "ensures continuous learning" - Docs/User-Guide/agents.md: PM Agent section rewritten - Section: Orchestration Agent → Meta-Layer Agent - Expertise: Project orchestration → Self-improvement workflow executor - Examples: Task coordination → Post-implementation documentation - PR_DOCUMENTATION.md: Comprehensive PR documentation added - Summary, motivation, changes, testing, breaking changes - Two-layer orchestration system diagram - Verification checklist Integration Validated: Tested with agiletec project's self-improvement-workflow.md: ✅ PM Agent aligns with existing BEFORE/DURING/AFTER/MISTAKE RECOVERY phases ✅ Complements (not competes with) existing workflow ✅ agiletec workflow defines WHAT, PM Agent defines WHO executes it Breaking Changes: None - Existing auto-activation continues unchanged - Specialist agents unaffected - User workflows remain the same - New capability: Automatic documentation and knowledge maintenance Value Proposition: Transforms SuperClaude into a continuously learning system that accumulates knowledge, prevents recurring mistakes, and maintains fresh documentation without manual intervention. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: add Claude Code conversation history management research Research covering .jsonl file structure, performance impact, and retention policies. Content: - Claude Code .jsonl file format and message types - Performance issues from GitHub (memory leaks, conversation compaction) - Retention policies (consumer vs enterprise) - Rotation recommendations based on actual data - File history snapshot tracking mechanics Source: Moved from agiletec project (research applicable to all Claude Code projects) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: add Development documentation structure Phase 1: Documentation Structure complete - Add Docs/Development/ directory for development documentation - Add ARCHITECTURE.md - System architecture with PM Agent meta-layer - Add ROADMAP.md - 5-phase development plan with checkboxes - Add TASKS.md - Daily task tracking with progress indicators - Add PROJECT_STATUS.md - Current status dashboard and metrics - Add pm-agent-integration.md - Implementation guide for PM Agent mode This establishes comprehensive documentation foundation for: - System architecture understanding - Development planning and tracking - Implementation guidance - Progress visibility Related: #pm-agent-mode #documentation #phase-1 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: PM Agent session lifecycle and PDCA implementation Phase 2: PM Agent Mode Integration (Design Phase) Commands/pm.md updates: - Add "Always-Active Foundation Layer" concept - Add Session Lifecycle (Session Start/During Work/Session End) - Add PDCA Cycle (Plan/Do/Check/Act) automation - Add Serena MCP Memory Integration (list/read/write_memory) - Document auto-activation triggers Agents/pm-agent.md updates: - Add Session Start Protocol (MANDATORY auto-activation) - Add During Work PDCA Cycle with example workflows - Add Session End Protocol with state preservation - Add PDCA Self-Evaluation Pattern - Add Documentation Strategy (temp → patterns/mistakes) - Add Memory Operations Reference Key Features: - Session start auto-activation for context restoration - 30-minute checkpoint saves during work - Self-evaluation with think_about_* operations - Systematic documentation lifecycle - Knowledge evolution to CLAUDE.md Implementation Status: - ✅ Design complete (Commands/pm.md, Agents/pm-agent.md) - ⏳ Implementation pending (Core components) - ⏳ Serena MCP integration pending Salvaged from mistaken development in ~/.claude directory Related: #pm-agent-mode #session-lifecycle #pdca-cycle #phase-2 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: disable Serena MCP auto-browser launch Disable web dashboard and GUI log window auto-launch in Serena MCP server to prevent intrusive browser popups on startup. Users can still manually access the dashboard at http://localhost:24282/dashboard/ if needed. Changes: - Add CLI flags to Serena run command: - --enable-web-dashboard false - --enable-gui-log-window false - Ensures Git-tracked configuration (no reliance on ~/.serena/serena_config.yml) - Aligns with AIRIS MCP Gateway integration approach 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: rename directories to lowercase for PEP8 compliance - Rename superclaude/Agents -> superclaude/agents - Rename superclaude/Commands -> superclaude/commands - Rename superclaude/Core -> superclaude/core - Rename superclaude/Examples -> superclaude/examples - Rename superclaude/MCP -> superclaude/mcp - Rename superclaude/Modes -> superclaude/modes This change follows Python PEP8 naming conventions for package directories. * style: fix PEP8 violations and update package name to lowercase Changes: - Format all Python files with black (43 files reformatted) - Update package name from 'SuperClaude' to 'superclaude' in pyproject.toml - Fix import statements to use lowercase package name - Add missing imports (timedelta, __version__) - Remove old SuperClaude.egg-info directory PEP8 violations reduced from 2672 to 701 (mostly E501 line length due to black's 88 char vs flake8's 79 char limit). * docs: add PM Agent development documentation Add comprehensive PM Agent development documentation: - PM Agent ideal workflow (7-phase autonomous cycle) - Project structure understanding (Git vs installed environment) - Installation flow understanding (CommandsComponent behavior) - Task management system (current-tasks.md) Purpose: Eliminate repeated explanations and enable autonomous PDCA cycles 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat(pm-agent): add self-correcting execution and warning investigation culture ## Changes ### superclaude/commands/pm.md - Add "Self-Correcting Execution" section with root cause analysis protocol - Add "Warning/Error Investigation Culture" section enforcing zero-tolerance for dismissal - Define error detection protocol: STOP → Investigate → Hypothesis → Different Solution → Execute - Document anti-patterns (retry without understanding) and correct patterns (research-first) ### docs/Development/hypothesis-pm-autonomous-enhancement-2025-10-14.md - Add PDCA workflow hypothesis document for PM Agent autonomous enhancement ## Rationale PM Agent must never retry failed operations without understanding root causes. All warnings and errors require investigation via context7/WebFetch/documentation to ensure production-quality code and prevent technical debt accumulation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat(installer): add airis-mcp-gateway MCP server option ## Changes - Add airis-mcp-gateway to MCP server options in installer - Configuration: GitHub-based installation via uvx - Repository: https://github.com/oraios/airis-mcp-gateway - Purpose: Dynamic MCP Gateway for zero-token baseline and on-demand tool loading ## Implementation Added to setup/components/mcp.py self.mcp_servers dictionary with: - install_method: github - install_command: uvx test installation - run_command: uvx runtime execution - required: False (optional server) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: kazuki <kazuki@kazukinoMacBook-Air.local> Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
kazuki nakai
529
docs/Development/ARCHITECTURE.md
Normal file
529
docs/Development/ARCHITECTURE.md
Normal file
@@ -0,0 +1,529 @@
|
||||
# SuperClaude Architecture
|
||||
|
||||
**Last Updated**: 2025-10-14
|
||||
**Version**: 4.1.5
|
||||
|
||||
## 📋 Table of Contents
|
||||
|
||||
1. [System Overview](#system-overview)
|
||||
2. [Core Architecture](#core-architecture)
|
||||
3. [PM Agent Mode: The Meta-Layer](#pm-agent-mode-the-meta-layer)
|
||||
4. [Component Relationships](#component-relationships)
|
||||
5. [Serena MCP Integration](#serena-mcp-integration)
|
||||
6. [PDCA Engine](#pdca-engine)
|
||||
7. [Data Flow](#data-flow)
|
||||
8. [Extension Points](#extension-points)
|
||||
|
||||
---
|
||||
|
||||
## System Overview
|
||||
|
||||
### What is SuperClaude?
|
||||
|
||||
SuperClaude is a **Context-Oriented Configuration Framework** that transforms Claude Code into a structured development platform. It is NOT standalone software with running processes - it is a collection of `.md` instruction files that Claude Code reads to adopt specialized behaviors.
|
||||
|
||||
### Key Components
|
||||
|
||||
```
|
||||
SuperClaude Framework
|
||||
├── Commands (26) → Workflow patterns
|
||||
├── Agents (16) → Domain expertise
|
||||
├── Modes (7) → Behavioral modifiers
|
||||
├── MCP Servers (8) → External tool integrations
|
||||
└── PM Agent Mode → Meta-layer orchestration (Always-Active)
|
||||
```
|
||||
|
||||
### Version Information
|
||||
|
||||
- **Current Version**: 4.1.5
|
||||
- **Commands**: 26 slash commands (`/sc:*`)
|
||||
- **Agents**: 16 specialized domain experts
|
||||
- **Modes**: 7 behavioral modes
|
||||
- **MCP Servers**: 8 integrations (Context7, Sequential, Magic, Playwright, Morphllm, Serena, Tavily, Chrome DevTools)
|
||||
|
||||
---
|
||||
|
||||
## Core Architecture
|
||||
|
||||
### Context-Oriented Configuration
|
||||
|
||||
SuperClaude's architecture is built on a simple principle: **behavioral modification through structured context files**.
|
||||
|
||||
```
|
||||
User Input
|
||||
↓
|
||||
Context Loading (CLAUDE.md imports)
|
||||
↓
|
||||
Command Detection (/sc:* pattern)
|
||||
↓
|
||||
Agent Activation (manual or auto)
|
||||
↓
|
||||
Mode Application (flags or triggers)
|
||||
↓
|
||||
MCP Tool Coordination
|
||||
↓
|
||||
Output Generation
|
||||
```
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
~/.claude/
|
||||
├── CLAUDE.md # Main context with @imports
|
||||
├── FLAGS.md # Flag definitions
|
||||
├── RULES.md # Core behavioral rules
|
||||
├── PRINCIPLES.md # Guiding principles
|
||||
├── MODE_*.md # 7 behavioral modes
|
||||
├── MCP_*.md # 8 MCP server integrations
|
||||
├── agents/ # 16 specialized agents
|
||||
│ ├── pm-agent.md # 🆕 Meta-layer orchestrator
|
||||
│ ├── backend-architect.md
|
||||
│ ├── frontend-architect.md
|
||||
│ ├── security-engineer.md
|
||||
│ └── ... (13 more)
|
||||
└── commands/sc/ # 26 workflow commands
|
||||
├── pm.md # 🆕 PM Agent command
|
||||
├── implement.md
|
||||
├── analyze.md
|
||||
└── ... (23 more)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PM Agent Mode: The Meta-Layer
|
||||
|
||||
### Position in Architecture
|
||||
|
||||
PM Agent operates as a **meta-layer** above all other components:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ PM Agent Mode (Meta-Layer) │
|
||||
│ • Always Active (Session Start) │
|
||||
│ • Context Preservation │
|
||||
│ • PDCA Self-Evaluation │
|
||||
│ • Knowledge Management │
|
||||
└─────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Specialist Agents (16) │
|
||||
│ backend-architect, security-engineer, etc. │
|
||||
└─────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Commands & Modes │
|
||||
│ /sc:implement, /sc:analyze, etc. │
|
||||
└─────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ MCP Tool Layer │
|
||||
│ Context7, Sequential, Magic, etc. │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### PM Agent Responsibilities
|
||||
|
||||
1. **Session Lifecycle Management**
|
||||
- Auto-activation at session start
|
||||
- Context restoration from Serena MCP memory
|
||||
- User report generation (前回/進捗/今回/課題)
|
||||
|
||||
2. **PDCA Cycle Execution**
|
||||
- Plan: Hypothesis generation
|
||||
- Do: Experimentation with checkpoints
|
||||
- Check: Self-evaluation
|
||||
- Act: Knowledge extraction
|
||||
|
||||
3. **Documentation Strategy**
|
||||
- Temporary documentation (`docs/temp/`)
|
||||
- Formal patterns (`docs/patterns/`)
|
||||
- Mistake records (`docs/mistakes/`)
|
||||
- Knowledge evolution to CLAUDE.md
|
||||
|
||||
4. **Sub-Agent Orchestration**
|
||||
- Auto-delegation to specialists
|
||||
- Context coordination
|
||||
- Quality gate validation
|
||||
- Progress monitoring
|
||||
|
||||
---
|
||||
|
||||
## Component Relationships
|
||||
|
||||
### Commands → Agents → Modes → MCP
|
||||
|
||||
```
|
||||
User: "/sc:implement authentication" --security
|
||||
↓
|
||||
[Command Layer]
|
||||
commands/sc/implement.md
|
||||
↓
|
||||
[Agent Auto-Activation]
|
||||
agents/security-engineer.md
|
||||
agents/backend-architect.md
|
||||
↓
|
||||
[Mode Application]
|
||||
MODE_Task_Management.md (TodoWrite)
|
||||
↓
|
||||
[MCP Tool Coordination]
|
||||
Context7 (auth patterns)
|
||||
Sequential (complex analysis)
|
||||
↓
|
||||
[PM Agent Meta-Layer]
|
||||
Document learnings → docs/patterns/
|
||||
```
|
||||
|
||||
### Activation Flow
|
||||
|
||||
1. **Explicit Command**: User types `/sc:implement`
|
||||
- Loads `commands/sc/implement.md`
|
||||
- Activates related agents (backend-architect, etc.)
|
||||
|
||||
2. **Agent Activation**: `@agent-security` or auto-detected
|
||||
- Loads agent expertise context
|
||||
- May activate related MCP servers
|
||||
|
||||
3. **Mode Application**: `--brainstorm` flag or keywords
|
||||
- Modifies interaction style
|
||||
- Enables specific behaviors
|
||||
|
||||
4. **PM Agent Meta-Layer**: Always active
|
||||
- Monitors all interactions
|
||||
- Documents learnings
|
||||
- Preserves context across sessions
|
||||
|
||||
---
|
||||
|
||||
## Serena MCP Integration
|
||||
|
||||
### Memory Operations
|
||||
|
||||
Serena MCP provides semantic code analysis and session persistence through memory operations:
|
||||
|
||||
```
|
||||
Session Start:
|
||||
PM Agent → list_memories()
|
||||
PM Agent → read_memory("pm_context")
|
||||
PM Agent → read_memory("last_session")
|
||||
PM Agent → read_memory("next_actions")
|
||||
PM Agent → Report to User
|
||||
|
||||
During Work (every 30min):
|
||||
PM Agent → write_memory("checkpoint", progress)
|
||||
PM Agent → write_memory("decision", rationale)
|
||||
|
||||
Session End:
|
||||
PM Agent → write_memory("last_session", summary)
|
||||
PM Agent → write_memory("next_actions", todos)
|
||||
PM Agent → write_memory("pm_context", complete_state)
|
||||
```
|
||||
|
||||
### Memory Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"pm_context": {
|
||||
"project": "SuperClaude_Framework",
|
||||
"current_phase": "Phase 1: Documentation",
|
||||
"active_tasks": ["ARCHITECTURE.md", "ROADMAP.md"],
|
||||
"architecture": "Context-Oriented Configuration",
|
||||
"patterns": ["PDCA Cycle", "Session Lifecycle"]
|
||||
},
|
||||
"last_session": {
|
||||
"date": "2025-10-14",
|
||||
"accomplished": ["PM Agent mode design", "Salvaged implementations"],
|
||||
"issues": ["Serena MCP not configured"],
|
||||
"learned": ["Session Lifecycle pattern", "PDCA automation"]
|
||||
},
|
||||
"next_actions": [
|
||||
"Create docs/Development/ structure",
|
||||
"Write ARCHITECTURE.md",
|
||||
"Configure Serena MCP server"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PDCA Engine
|
||||
|
||||
### Continuous Improvement Cycle
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ Plan │ → write_memory("plan", goal)
|
||||
│ (仮説) │ → docs/temp/hypothesis-YYYY-MM-DD.md
|
||||
└──────┬──────┘
|
||||
↓
|
||||
┌─────────────┐
|
||||
│ Do │ → TodoWrite tracking
|
||||
│ (実験) │ → write_memory("checkpoint", progress)
|
||||
└──────┬──────┘ → docs/temp/experiment-YYYY-MM-DD.md
|
||||
↓
|
||||
┌─────────────┐
|
||||
│ Check │ → think_about_task_adherence()
|
||||
│ (評価) │ → think_about_whether_you_are_done()
|
||||
└──────┬──────┘ → docs/temp/lessons-YYYY-MM-DD.md
|
||||
↓
|
||||
┌─────────────┐
|
||||
│ Act │ → Success: docs/patterns/[name].md
|
||||
│ (改善) │ → Failure: docs/mistakes/mistake-*.md
|
||||
└──────┬──────┘ → Update CLAUDE.md
|
||||
↓
|
||||
[Repeat]
|
||||
```
|
||||
|
||||
### Documentation Evolution
|
||||
|
||||
```
|
||||
Trial-and-Error (docs/temp/)
|
||||
↓
|
||||
Success → Formal Pattern (docs/patterns/)
|
||||
↓
|
||||
Accumulate Knowledge
|
||||
↓
|
||||
Extract Best Practices → CLAUDE.md (Global Rules)
|
||||
```
|
||||
|
||||
```
|
||||
Mistake Detection (docs/temp/)
|
||||
↓
|
||||
Root Cause Analysis → docs/mistakes/
|
||||
↓
|
||||
Prevention Checklist
|
||||
↓
|
||||
Update Anti-Patterns → CLAUDE.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Session Lifecycle Data Flow
|
||||
|
||||
```
|
||||
Session Start:
|
||||
┌──────────────┐
|
||||
│ Claude Code │
|
||||
│ Startup │
|
||||
└──────┬───────┘
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ PM Agent │ list_memories()
|
||||
│ Activation │ read_memory("pm_context")
|
||||
└──────┬───────┘
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ Serena │ Return: pm_context,
|
||||
│ MCP │ last_session,
|
||||
└──────┬───────┘ next_actions
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ Context │ Restore project state
|
||||
│ Restoration │ Generate user report
|
||||
└──────┬───────┘
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ User │ 前回: [summary]
|
||||
│ Report │ 進捗: [status]
|
||||
└──────────────┘ 今回: [actions]
|
||||
課題: [blockers]
|
||||
```
|
||||
|
||||
### Implementation Data Flow
|
||||
|
||||
```
|
||||
User Request → PM Agent Analyzes
|
||||
↓
|
||||
PM Agent → Delegate to Specialist Agents
|
||||
↓
|
||||
Specialist Agents → Execute Implementation
|
||||
↓
|
||||
Implementation Complete → PM Agent Documents
|
||||
↓
|
||||
PM Agent → write_memory("checkpoint", progress)
|
||||
PM Agent → docs/temp/experiment-*.md
|
||||
↓
|
||||
Success → docs/patterns/ | Failure → docs/mistakes/
|
||||
↓
|
||||
Update CLAUDE.md (if global pattern)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Extension Points
|
||||
|
||||
### Adding New Components
|
||||
|
||||
#### 1. New Command
|
||||
```markdown
|
||||
File: ~/.claude/commands/sc/new-command.md
|
||||
Structure:
|
||||
- Metadata (name, category, complexity)
|
||||
- Triggers (when to use)
|
||||
- Workflow Pattern (step-by-step)
|
||||
- Examples
|
||||
|
||||
Integration:
|
||||
- Auto-loads when user types /sc:new-command
|
||||
- Can activate related agents
|
||||
- PM Agent automatically documents usage patterns
|
||||
```
|
||||
|
||||
#### 2. New Agent
|
||||
```markdown
|
||||
File: ~/.claude/agents/new-specialist.md
|
||||
Structure:
|
||||
- Metadata (name, category)
|
||||
- Triggers (keywords, file types)
|
||||
- Behavioral Mindset
|
||||
- Focus Areas
|
||||
|
||||
Integration:
|
||||
- Auto-activates on trigger keywords
|
||||
- Manual activation: @agent-new-specialist
|
||||
- PM Agent orchestrates with other agents
|
||||
```
|
||||
|
||||
#### 3. New Mode
|
||||
```markdown
|
||||
File: ~/.claude/MODE_NewMode.md
|
||||
Structure:
|
||||
- Activation Triggers (flags, keywords)
|
||||
- Behavioral Modifications
|
||||
- Interaction Patterns
|
||||
|
||||
Integration:
|
||||
- Flag: --new-mode
|
||||
- Auto-activation on complexity threshold
|
||||
- Modifies all agent behaviors
|
||||
```
|
||||
|
||||
#### 4. New MCP Server
|
||||
```json
|
||||
File: ~/.claude/.claude.json
|
||||
{
|
||||
"mcpServers": {
|
||||
"new-server": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "new-server-mcp@latest"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```markdown
|
||||
File: ~/.claude/MCP_NewServer.md
|
||||
Structure:
|
||||
- Purpose (what this server provides)
|
||||
- Triggers (when to use)
|
||||
- Integration (how to coordinate with other tools)
|
||||
```
|
||||
|
||||
### PM Agent Integration for Extensions
|
||||
|
||||
All new components automatically integrate with PM Agent meta-layer:
|
||||
|
||||
1. **Session Lifecycle**: New components' usage tracked across sessions
|
||||
2. **PDCA Cycle**: Patterns extracted from new component usage
|
||||
3. **Documentation**: Learnings automatically documented
|
||||
4. **Orchestration**: PM Agent coordinates new components with existing ones
|
||||
|
||||
---
|
||||
|
||||
## Architecture Principles
|
||||
|
||||
### 1. Simplicity First
|
||||
- No executing code, only context files
|
||||
- No performance systems, only instructional patterns
|
||||
- No detection engines, Claude Code does pattern matching
|
||||
|
||||
### 2. Context-Oriented
|
||||
- Behavior modification through structured context
|
||||
- Import system for modular context loading
|
||||
- Clear trigger patterns for activation
|
||||
|
||||
### 3. Meta-Layer Design
|
||||
- PM Agent orchestrates without interfering
|
||||
- Specialist agents work transparently
|
||||
- Users interact with cohesive system
|
||||
|
||||
### 4. Knowledge Accumulation
|
||||
- Every experience generates learnings
|
||||
- Mistakes documented with prevention
|
||||
- Patterns extracted to reusable knowledge
|
||||
|
||||
### 5. Session Continuity
|
||||
- Context preserved across sessions
|
||||
- No re-explanation needed
|
||||
- Seamless resumption from last checkpoint
|
||||
|
||||
---
|
||||
|
||||
## Technical Considerations
|
||||
|
||||
### Performance
|
||||
- Framework is pure context (no runtime overhead)
|
||||
- Token efficiency through dynamic MCP loading
|
||||
- Strategic context caching for related phases
|
||||
|
||||
### Scalability
|
||||
- Unlimited commands/agents/modes through context files
|
||||
- Modular architecture supports independent development
|
||||
- PM Agent meta-layer handles coordination complexity
|
||||
|
||||
### Maintainability
|
||||
- Clear separation of concerns (Commands/Agents/Modes)
|
||||
- Self-documenting through PDCA cycle
|
||||
- Living documentation evolves with usage
|
||||
|
||||
### Extensibility
|
||||
- Drop-in new contexts without code changes
|
||||
- MCP servers add capabilities externally
|
||||
- PM Agent auto-integrates new components
|
||||
|
||||
---
|
||||
|
||||
## Future Architecture
|
||||
|
||||
### Planned Enhancements
|
||||
|
||||
1. **Auto-Activation System**
|
||||
- PM Agent activates automatically at session start
|
||||
- No manual invocation needed
|
||||
|
||||
2. **Enhanced Memory Operations**
|
||||
- Full Serena MCP integration
|
||||
- Cross-project knowledge sharing
|
||||
- Pattern recognition across sessions
|
||||
|
||||
3. **PDCA Automation**
|
||||
- Automatic documentation lifecycle
|
||||
- AI-driven pattern extraction
|
||||
- Self-improving knowledge base
|
||||
|
||||
4. **Multi-Project Orchestration**
|
||||
- PM Agent coordinates across projects
|
||||
- Shared learnings and patterns
|
||||
- Unified knowledge management
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
SuperClaude's architecture is elegantly simple: **structured context files** that Claude Code reads to adopt sophisticated behaviors. The addition of PM Agent mode as a meta-layer transforms this from a collection of tools into a **continuously learning, self-improving development platform**.
|
||||
|
||||
**Key Architectural Innovation**: PM Agent meta-layer provides:
|
||||
- Always-active foundation layer
|
||||
- Context preservation across sessions
|
||||
- PDCA self-evaluation and learning
|
||||
- Systematic knowledge management
|
||||
- Seamless orchestration of specialist agents
|
||||
|
||||
This architecture enables SuperClaude to function as a **最高司令官 (Supreme Commander)** that orchestrates all development activities while continuously learning and improving from every interaction.
|
||||
|
||||
---
|
||||
|
||||
**Last Verified**: 2025-10-14
|
||||
**Next Review**: 2025-10-21 (1 week)
|
||||
**Version**: 4.1.5
|
||||
172
docs/Development/PROJECT_STATUS.md
Normal file
172
docs/Development/PROJECT_STATUS.md
Normal file
@@ -0,0 +1,172 @@
|
||||
# SuperClaude Project Status
|
||||
|
||||
**Last Updated**: 2025-10-14
|
||||
**Version**: 4.1.5
|
||||
**Phase**: Phase 1 - Documentation Structure
|
||||
|
||||
---
|
||||
|
||||
## 📊 Quick Overview
|
||||
|
||||
| Metric | Status | Progress |
|
||||
|--------|--------|----------|
|
||||
| **Overall Completion** | 🔄 In Progress | 35% |
|
||||
| **Phase 1 (Documentation)** | 🔄 In Progress | 66% |
|
||||
| **Phase 2 (PM Agent)** | 🔄 In Progress | 30% |
|
||||
| **Phase 3 (Serena MCP)** | ⏳ Not Started | 0% |
|
||||
| **Phase 4 (Doc Strategy)** | ⏳ Not Started | 0% |
|
||||
| **Phase 5 (Auto-Activation)** | 🔬 Research | 0% |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Current Sprint
|
||||
|
||||
**Sprint**: Phase 1 - Documentation Structure
|
||||
**Timeline**: 2025-10-14 ~ 2025-10-20
|
||||
**Status**: 🔄 66% Complete
|
||||
|
||||
### This Week's Focus
|
||||
- [ ] Complete Phase 1 documentation (TASKS.md, PROJECT_STATUS.md, pm-agent-integration.md)
|
||||
- [ ] Commit Phase 1 changes
|
||||
- [ ] Commit PM Agent Mode improvements
|
||||
|
||||
---
|
||||
|
||||
## ✅ Completed Features
|
||||
|
||||
### Core Framework (v4.1.5)
|
||||
- ✅ **26 Commands**: `/sc:*` namespace
|
||||
- ✅ **16 Agents**: Specialized domain experts
|
||||
- ✅ **7 Modes**: Behavioral modifiers
|
||||
- ✅ **8 MCP Servers**: External tool integrations
|
||||
|
||||
### PM Agent Mode (Design Phase)
|
||||
- ✅ Session Lifecycle design
|
||||
- ✅ PDCA Cycle design
|
||||
- ✅ Documentation Strategy design
|
||||
- ✅ Commands/pm.md updated
|
||||
- ✅ Agents/pm-agent.md updated
|
||||
|
||||
### Documentation
|
||||
- ✅ docs/Development/ARCHITECTURE.md
|
||||
- ✅ docs/Development/ROADMAP.md
|
||||
- ✅ docs/Development/TASKS.md
|
||||
- ✅ docs/Development/PROJECT_STATUS.md
|
||||
- ✅ docs/pm-agent-implementation-status.md
|
||||
|
||||
---
|
||||
|
||||
## 🔄 In Progress
|
||||
|
||||
### Phase 1: Documentation Structure (66%)
|
||||
- [x] ARCHITECTURE.md
|
||||
- [x] ROADMAP.md
|
||||
- [x] TASKS.md
|
||||
- [x] PROJECT_STATUS.md
|
||||
- [ ] pm-agent-integration.md
|
||||
|
||||
### Phase 2: PM Agent Mode (30%)
|
||||
- [ ] superclaude/Core/session_lifecycle.py
|
||||
- [ ] superclaude/Core/pdca_engine.py
|
||||
- [ ] superclaude/Core/memory_ops.py
|
||||
- [ ] Unit tests
|
||||
- [ ] Integration tests
|
||||
|
||||
---
|
||||
|
||||
## ⏳ Pending
|
||||
|
||||
### Phase 3: Serena MCP Integration (0%)
|
||||
- Serena MCP server configuration
|
||||
- Memory operations implementation
|
||||
- Think operations implementation
|
||||
- Cross-session persistence testing
|
||||
|
||||
### Phase 4: Documentation Strategy (0%)
|
||||
- Directory templates creation
|
||||
- Lifecycle automation
|
||||
- Migration scripts
|
||||
- Knowledge management
|
||||
|
||||
### Phase 5: Auto-Activation (0%)
|
||||
- Claude Code initialization hooks research
|
||||
- Auto-activation implementation
|
||||
- Context restoration
|
||||
- Performance optimization
|
||||
|
||||
---
|
||||
|
||||
## 🚫 Blockers
|
||||
|
||||
### Critical
|
||||
- **Serena MCP Not Configured**: Blocks Phase 3 (Memory Operations)
|
||||
- **Auto-Activation Hooks Unknown**: Blocks Phase 5 (Research needed)
|
||||
|
||||
### Non-Critical
|
||||
- Documentation directory structure (in progress - Phase 1)
|
||||
|
||||
---
|
||||
|
||||
## 📈 Metrics Dashboard
|
||||
|
||||
### Development Velocity
|
||||
- **Phase 1**: 6 days estimated, on track for 7 days completion
|
||||
- **Phase 2**: 14 days estimated, not yet started full implementation
|
||||
- **Overall**: 35% complete, on schedule for 8-week timeline
|
||||
|
||||
### Code Quality
|
||||
- **Test Coverage**: 0% (implementation not started)
|
||||
- **Documentation Coverage**: 40% (4/10 major docs complete)
|
||||
|
||||
### Component Status
|
||||
- **Commands**: ✅ 26/26 functional
|
||||
- **Agents**: ✅ 16/16 functional, 1 (PM Agent) enhanced
|
||||
- **Modes**: ✅ 7/7 functional
|
||||
- **MCP Servers**: ⚠️ 7/8 functional (Serena pending)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Upcoming Milestones
|
||||
|
||||
### Week 1 (Current)
|
||||
- ✅ Complete Phase 1 documentation
|
||||
- ✅ Commit changes to repository
|
||||
|
||||
### Week 2-3
|
||||
- [ ] Implement PM Agent Core (session_lifecycle, pdca_engine, memory_ops)
|
||||
- [ ] Write unit tests
|
||||
- [ ] Update User-Guide documentation
|
||||
|
||||
### Week 4-5
|
||||
- [ ] Configure Serena MCP server
|
||||
- [ ] Implement memory operations
|
||||
- [ ] Test cross-session persistence
|
||||
|
||||
---
|
||||
|
||||
## 📝 Recent Changes
|
||||
|
||||
### 2025-10-14
|
||||
- Created docs/Development/ structure
|
||||
- Wrote ARCHITECTURE.md (system overview)
|
||||
- Wrote ROADMAP.md (5-phase development plan)
|
||||
- Wrote TASKS.md (task tracking)
|
||||
- Wrote PROJECT_STATUS.md (this file)
|
||||
- Salvaged PM Agent mode changes from ~/.claude
|
||||
- Updated Commands/pm.md and Agents/pm-agent.md
|
||||
|
||||
---
|
||||
|
||||
## 🔮 Next Steps
|
||||
|
||||
1. **Complete pm-agent-integration.md** (Phase 1 final doc)
|
||||
2. **Commit Phase 1 documentation** (establish foundation)
|
||||
3. **Commit PM Agent Mode improvements** (design complete)
|
||||
4. **Begin Phase 2 implementation** (Core components)
|
||||
5. **Configure Serena MCP** (unblock Phase 3)
|
||||
|
||||
---
|
||||
|
||||
**Last Verified**: 2025-10-14
|
||||
**Next Review**: 2025-10-17 (Mid-week check)
|
||||
**Version**: 4.1.5
|
||||
349
docs/Development/ROADMAP.md
Normal file
349
docs/Development/ROADMAP.md
Normal file
@@ -0,0 +1,349 @@
|
||||
# SuperClaude Development Roadmap
|
||||
|
||||
**Last Updated**: 2025-10-14
|
||||
**Version**: 4.1.5
|
||||
|
||||
## 🎯 Vision
|
||||
|
||||
Transform SuperClaude into a self-improving development platform with PM Agent mode as the always-active meta-layer, enabling continuous context preservation, systematic knowledge management, and intelligent orchestration of all development activities.
|
||||
|
||||
---
|
||||
|
||||
## 📊 Phase Overview
|
||||
|
||||
| Phase | Status | Timeline | Focus |
|
||||
|-------|--------|----------|-------|
|
||||
| **Phase 1** | ✅ Completed | Week 1 | Documentation Structure |
|
||||
| **Phase 2** | 🔄 In Progress | Week 2-3 | PM Agent Mode Integration |
|
||||
| **Phase 3** | ⏳ Planned | Week 4-5 | Serena MCP Integration |
|
||||
| **Phase 4** | ⏳ Planned | Week 6-7 | Documentation Strategy |
|
||||
| **Phase 5** | 🔬 Research | Week 8+ | Auto-Activation System |
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Documentation Structure ✅
|
||||
|
||||
**Goal**: Create comprehensive documentation foundation for development
|
||||
|
||||
**Timeline**: Week 1 (2025-10-14 ~ 2025-10-20)
|
||||
|
||||
**Status**: ✅ Completed
|
||||
|
||||
### Tasks
|
||||
|
||||
- [x] Create `docs/Development/` directory structure
|
||||
- [x] Write `ARCHITECTURE.md` - System overview with PM Agent position
|
||||
- [x] Write `ROADMAP.md` - Phase-based development plan with checkboxes
|
||||
- [ ] Write `TASKS.md` - Current task tracking system
|
||||
- [ ] Write `PROJECT_STATUS.md` - Implementation status dashboard
|
||||
- [ ] Write `pm-agent-integration.md` - Integration guide and procedures
|
||||
|
||||
### Deliverables
|
||||
|
||||
- [x] **docs/Development/ARCHITECTURE.md** - Complete system architecture
|
||||
- [x] **docs/Development/ROADMAP.md** - This file (development roadmap)
|
||||
- [ ] **docs/Development/TASKS.md** - Task management with checkboxes
|
||||
- [ ] **docs/Development/PROJECT_STATUS.md** - Current status and metrics
|
||||
- [ ] **docs/Development/pm-agent-integration.md** - Integration procedures
|
||||
|
||||
### Success Criteria
|
||||
|
||||
- [x] Documentation structure established
|
||||
- [x] Architecture clearly documented
|
||||
- [ ] Roadmap with phase breakdown complete
|
||||
- [ ] Task tracking system functional
|
||||
- [ ] Status dashboard provides visibility
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: PM Agent Mode Integration 🔄
|
||||
|
||||
**Goal**: Integrate PM Agent mode as always-active meta-layer
|
||||
|
||||
**Timeline**: Week 2-3 (2025-10-21 ~ 2025-11-03)
|
||||
|
||||
**Status**: 🔄 In Progress (30% complete)
|
||||
|
||||
### Tasks
|
||||
|
||||
#### Documentation Updates
|
||||
- [x] Update `superclaude/Commands/pm.md` with Session Lifecycle
|
||||
- [x] Update `superclaude/Agents/pm-agent.md` with PDCA Cycle
|
||||
- [x] Create `docs/pm-agent-implementation-status.md`
|
||||
- [ ] Update `docs/User-Guide/agents.md` - Add PM Agent section
|
||||
- [ ] Update `docs/User-Guide/commands.md` - Add /sc:pm command
|
||||
|
||||
#### Core Implementation
|
||||
- [ ] Implement `superclaude/Core/session_lifecycle.py`
|
||||
- [ ] Session start hooks
|
||||
- [ ] Context restoration logic
|
||||
- [ ] User report generation
|
||||
- [ ] Error handling and fallback
|
||||
- [ ] Implement `superclaude/Core/pdca_engine.py`
|
||||
- [ ] Plan phase automation
|
||||
- [ ] Do phase tracking
|
||||
- [ ] Check phase self-evaluation
|
||||
- [ ] Act phase documentation
|
||||
- [ ] Implement `superclaude/Core/memory_ops.py`
|
||||
- [ ] Serena MCP wrapper
|
||||
- [ ] Memory operation abstractions
|
||||
- [ ] Checkpoint management
|
||||
- [ ] Session state handling
|
||||
|
||||
#### Testing
|
||||
- [ ] Unit tests for session_lifecycle.py
|
||||
- [ ] Unit tests for pdca_engine.py
|
||||
- [ ] Unit tests for memory_ops.py
|
||||
- [ ] Integration tests for PM Agent flow
|
||||
- [ ] Test auto-activation at session start
|
||||
|
||||
### Deliverables
|
||||
|
||||
- [x] **Updated pm.md and pm-agent.md** - Design documentation
|
||||
- [x] **pm-agent-implementation-status.md** - Status tracking
|
||||
- [ ] **superclaude/Core/session_lifecycle.py** - Session management
|
||||
- [ ] **superclaude/Core/pdca_engine.py** - PDCA automation
|
||||
- [ ] **superclaude/Core/memory_ops.py** - Memory operations
|
||||
- [ ] **tests/test_pm_agent.py** - Comprehensive test suite
|
||||
|
||||
### Success Criteria
|
||||
|
||||
- [ ] PM Agent mode loads at session start
|
||||
- [ ] Session Lifecycle functional
|
||||
- [ ] PDCA Cycle automated
|
||||
- [ ] Memory operations working
|
||||
- [ ] All tests passing (>90% coverage)
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Serena MCP Integration ⏳
|
||||
|
||||
**Goal**: Full Serena MCP integration for session persistence
|
||||
|
||||
**Timeline**: Week 4-5 (2025-11-04 ~ 2025-11-17)
|
||||
|
||||
**Status**: ⏳ Planned
|
||||
|
||||
### Tasks
|
||||
|
||||
#### MCP Configuration
|
||||
- [ ] Install and configure Serena MCP server
|
||||
- [ ] Update `~/.claude/.claude.json` with Serena config
|
||||
- [ ] Test basic Serena operations
|
||||
- [ ] Troubleshoot connection issues
|
||||
|
||||
#### Memory Operations Implementation
|
||||
- [ ] Implement `list_memories()` integration
|
||||
- [ ] Implement `read_memory(key)` integration
|
||||
- [ ] Implement `write_memory(key, value)` integration
|
||||
- [ ] Implement `delete_memory(key)` integration
|
||||
- [ ] Test memory persistence across sessions
|
||||
|
||||
#### Think Operations Implementation
|
||||
- [ ] Implement `think_about_task_adherence()` hook
|
||||
- [ ] Implement `think_about_collected_information()` hook
|
||||
- [ ] Implement `think_about_whether_you_are_done()` hook
|
||||
- [ ] Integrate with TodoWrite completion tracking
|
||||
- [ ] Test self-evaluation triggers
|
||||
|
||||
#### Cross-Session Testing
|
||||
- [ ] Test context restoration after restart
|
||||
- [ ] Test checkpoint save/restore
|
||||
- [ ] Test memory persistence durability
|
||||
- [ ] Test multi-project memory isolation
|
||||
- [ ] Performance testing (memory operations latency)
|
||||
|
||||
### Deliverables
|
||||
|
||||
- [ ] **Serena MCP Server** - Configured and operational
|
||||
- [ ] **superclaude/Core/serena_client.py** - Serena MCP client wrapper
|
||||
- [ ] **superclaude/Core/think_operations.py** - Think hooks implementation
|
||||
- [ ] **docs/troubleshooting/serena-setup.md** - Setup guide
|
||||
- [ ] **tests/test_serena_integration.py** - Integration test suite
|
||||
|
||||
### Success Criteria
|
||||
|
||||
- [ ] Serena MCP server operational
|
||||
- [ ] All memory operations functional
|
||||
- [ ] Think operations trigger correctly
|
||||
- [ ] Cross-session persistence verified
|
||||
- [ ] Performance acceptable (<100ms per operation)
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Documentation Strategy ⏳
|
||||
|
||||
**Goal**: Implement systematic documentation lifecycle
|
||||
|
||||
**Timeline**: Week 6-7 (2025-11-18 ~ 2025-12-01)
|
||||
|
||||
**Status**: ⏳ Planned
|
||||
|
||||
### Tasks
|
||||
|
||||
#### Directory Structure
|
||||
- [ ] Create `docs/temp/` template structure
|
||||
- [ ] Create `docs/patterns/` template structure
|
||||
- [ ] Create `docs/mistakes/` template structure
|
||||
- [ ] Add README.md to each directory explaining purpose
|
||||
- [ ] Create .gitignore for temporary files
|
||||
|
||||
#### File Templates
|
||||
- [ ] Create `hypothesis-template.md` for Plan phase
|
||||
- [ ] Create `experiment-template.md` for Do phase
|
||||
- [ ] Create `lessons-template.md` for Check phase
|
||||
- [ ] Create `pattern-template.md` for successful patterns
|
||||
- [ ] Create `mistake-template.md` for error records
|
||||
|
||||
#### Lifecycle Automation
|
||||
- [ ] Implement 7-day temporary file cleanup
|
||||
- [ ] Create docs/temp → docs/patterns migration script
|
||||
- [ ] Create docs/temp → docs/mistakes migration script
|
||||
- [ ] Automate "Last Verified" date updates
|
||||
- [ ] Implement duplicate pattern detection
|
||||
|
||||
#### Knowledge Management
|
||||
- [ ] Implement pattern extraction logic
|
||||
- [ ] Implement CLAUDE.md auto-update mechanism
|
||||
- [ ] Create knowledge graph visualization
|
||||
- [ ] Implement pattern search functionality
|
||||
- [ ] Create mistake prevention checklist generator
|
||||
|
||||
### Deliverables
|
||||
|
||||
- [ ] **docs/temp/**, **docs/patterns/**, **docs/mistakes/** - Directory templates
|
||||
- [ ] **superclaude/Core/doc_lifecycle.py** - Lifecycle automation
|
||||
- [ ] **superclaude/Core/knowledge_manager.py** - Knowledge extraction
|
||||
- [ ] **scripts/migrate_docs.py** - Migration utilities
|
||||
- [ ] **tests/test_doc_lifecycle.py** - Lifecycle test suite
|
||||
|
||||
### Success Criteria
|
||||
|
||||
- [ ] Directory templates functional
|
||||
- [ ] Lifecycle automation working
|
||||
- [ ] Migration scripts reliable
|
||||
- [ ] Knowledge extraction accurate
|
||||
- [ ] CLAUDE.md auto-updates verified
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Auto-Activation System 🔬
|
||||
|
||||
**Goal**: PM Agent activates automatically at every session start
|
||||
|
||||
**Timeline**: Week 8+ (2025-12-02 onwards)
|
||||
|
||||
**Status**: 🔬 Research Needed
|
||||
|
||||
### Research Phase
|
||||
|
||||
- [ ] Research Claude Code initialization hooks
|
||||
- [ ] Investigate session start event handling
|
||||
- [ ] Study existing auto-activation patterns
|
||||
- [ ] Analyze Claude Code plugin system (if available)
|
||||
- [ ] Review Anthropic documentation on extensibility
|
||||
|
||||
### Tasks
|
||||
|
||||
#### Hook Implementation
|
||||
- [ ] Identify session start hook mechanism
|
||||
- [ ] Implement PM Agent auto-activation hook
|
||||
- [ ] Test activation timing and reliability
|
||||
- [ ] Handle edge cases (crash recovery, etc.)
|
||||
- [ ] Performance optimization (minimize startup delay)
|
||||
|
||||
#### Context Restoration
|
||||
- [ ] Implement automatic context loading
|
||||
- [ ] Test memory restoration at startup
|
||||
- [ ] Verify user report generation
|
||||
- [ ] Handle missing or corrupted memory
|
||||
- [ ] Graceful fallback for new sessions
|
||||
|
||||
#### Integration Testing
|
||||
- [ ] Test across multiple sessions
|
||||
- [ ] Test with different project contexts
|
||||
- [ ] Test memory persistence durability
|
||||
- [ ] Test error recovery mechanisms
|
||||
- [ ] Performance testing (startup time impact)
|
||||
|
||||
### Deliverables
|
||||
|
||||
- [ ] **superclaude/Core/auto_activation.py** - Auto-activation system
|
||||
- [ ] **docs/Developer-Guide/auto-activation.md** - Implementation guide
|
||||
- [ ] **tests/test_auto_activation.py** - Auto-activation tests
|
||||
- [ ] **Performance Report** - Startup time impact analysis
|
||||
|
||||
### Success Criteria
|
||||
|
||||
- [ ] PM Agent activates at every session start
|
||||
- [ ] Context restoration reliable (>99%)
|
||||
- [ ] User report generated consistently
|
||||
- [ ] Startup delay minimal (<500ms)
|
||||
- [ ] Error recovery robust
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Future Enhancements (Post-Phase 5)
|
||||
|
||||
### Multi-Project Orchestration
|
||||
- [ ] Cross-project knowledge sharing
|
||||
- [ ] Unified pattern library
|
||||
- [ ] Multi-project context switching
|
||||
- [ ] Project-specific memory namespaces
|
||||
|
||||
### AI-Driven Pattern Recognition
|
||||
- [ ] Machine learning for pattern extraction
|
||||
- [ ] Automatic best practice identification
|
||||
- [ ] Predictive mistake prevention
|
||||
- [ ] Smart knowledge graph generation
|
||||
|
||||
### Enhanced Self-Evaluation
|
||||
- [ ] Advanced think operations
|
||||
- [ ] Quality scoring automation
|
||||
- [ ] Performance regression detection
|
||||
- [ ] Code quality trend analysis
|
||||
|
||||
### Community Features
|
||||
- [ ] Pattern sharing marketplace
|
||||
- [ ] Community knowledge contributions
|
||||
- [ ] Collaborative PDCA cycles
|
||||
- [ ] Public pattern library
|
||||
|
||||
---
|
||||
|
||||
## 📊 Metrics & KPIs
|
||||
|
||||
### Phase Completion Metrics
|
||||
|
||||
| Metric | Target | Current | Status |
|
||||
|--------|--------|---------|--------|
|
||||
| Documentation Coverage | 100% | 40% | 🔄 In Progress |
|
||||
| PM Agent Integration | 100% | 30% | 🔄 In Progress |
|
||||
| Serena MCP Integration | 100% | 0% | ⏳ Pending |
|
||||
| Documentation Strategy | 100% | 0% | ⏳ Pending |
|
||||
| Auto-Activation | 100% | 0% | 🔬 Research |
|
||||
|
||||
### Quality Metrics
|
||||
|
||||
| Metric | Target | Current | Status |
|
||||
|--------|--------|---------|--------|
|
||||
| Test Coverage | >90% | 0% | ⏳ Pending |
|
||||
| Context Restoration Rate | 100% | N/A | ⏳ Pending |
|
||||
| Session Continuity | >95% | N/A | ⏳ Pending |
|
||||
| Documentation Freshness | <7 days | N/A | ⏳ Pending |
|
||||
| Mistake Prevention | <10% recurring | N/A | ⏳ Pending |
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Update Schedule
|
||||
|
||||
- **Weekly**: Task progress updates
|
||||
- **Bi-weekly**: Phase milestone reviews
|
||||
- **Monthly**: Roadmap revision and priority adjustment
|
||||
- **Quarterly**: Long-term vision alignment
|
||||
|
||||
---
|
||||
|
||||
**Last Verified**: 2025-10-14
|
||||
**Next Review**: 2025-10-21 (1 week)
|
||||
**Version**: 4.1.5
|
||||
151
docs/Development/TASKS.md
Normal file
151
docs/Development/TASKS.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# SuperClaude Development Tasks
|
||||
|
||||
**Last Updated**: 2025-10-14
|
||||
**Current Sprint**: Phase 1 - Documentation Structure
|
||||
|
||||
---
|
||||
|
||||
## 🔥 High Priority (This Week: 2025-10-14 ~ 2025-10-20)
|
||||
|
||||
### Phase 1: Documentation Structure
|
||||
- [x] Create docs/Development/ directory
|
||||
- [x] Write ARCHITECTURE.md
|
||||
- [x] Write ROADMAP.md
|
||||
- [ ] Write TASKS.md (this file)
|
||||
- [ ] Write PROJECT_STATUS.md
|
||||
- [ ] Write pm-agent-integration.md
|
||||
- [ ] Commit Phase 1 changes
|
||||
|
||||
### PM Agent Mode
|
||||
- [x] Design Session Lifecycle
|
||||
- [x] Design PDCA Cycle
|
||||
- [x] Update Commands/pm.md
|
||||
- [x] Update Agents/pm-agent.md
|
||||
- [x] Create pm-agent-implementation-status.md
|
||||
- [ ] Commit PM Agent Mode changes
|
||||
|
||||
---
|
||||
|
||||
## 📋 Medium Priority (This Month: October 2025)
|
||||
|
||||
### Phase 2: Core Implementation
|
||||
- [ ] Implement superclaude/Core/session_lifecycle.py
|
||||
- [ ] Implement superclaude/Core/pdca_engine.py
|
||||
- [ ] Implement superclaude/Core/memory_ops.py
|
||||
- [ ] Write unit tests for PM Agent core
|
||||
- [ ] Update User-Guide documentation
|
||||
|
||||
### Testing & Validation
|
||||
- [ ] Create test suite for session_lifecycle
|
||||
- [ ] Create test suite for pdca_engine
|
||||
- [ ] Create test suite for memory_ops
|
||||
- [ ] Integration testing for PM Agent flow
|
||||
- [ ] Performance benchmarking
|
||||
|
||||
---
|
||||
|
||||
## 💡 Low Priority (Future)
|
||||
|
||||
### Phase 3: Serena MCP Integration
|
||||
- [ ] Configure Serena MCP server
|
||||
- [ ] Test Serena connection
|
||||
- [ ] Implement memory operations
|
||||
- [ ] Test cross-session persistence
|
||||
|
||||
### Phase 4: Documentation Strategy
|
||||
- [ ] Create docs/temp/ template
|
||||
- [ ] Create docs/patterns/ template
|
||||
- [ ] Create docs/mistakes/ template
|
||||
- [ ] Implement 7-day cleanup automation
|
||||
|
||||
### Phase 5: Auto-Activation
|
||||
- [ ] Research Claude Code init hooks
|
||||
- [ ] Implement auto-activation
|
||||
- [ ] Test session start behavior
|
||||
- [ ] Performance optimization
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Bugs & Issues
|
||||
|
||||
### Known Issues
|
||||
- [ ] Serena MCP not configured (blocker for Phase 3)
|
||||
- [ ] Auto-activation hooks unknown (research needed for Phase 5)
|
||||
- [ ] Documentation directory structure missing (in progress)
|
||||
|
||||
### Recent Fixes
|
||||
- [x] PM Agent changes salvaged from ~/.claude directory (2025-10-14)
|
||||
- [x] Git repository cleanup in ~/.claude (2025-10-14)
|
||||
|
||||
---
|
||||
|
||||
## ✅ Completed Tasks
|
||||
|
||||
### 2025-10-14
|
||||
- [x] Salvaged PM Agent mode changes from ~/.claude
|
||||
- [x] Cleaned up ~/.claude git repository
|
||||
- [x] Created pm-agent-implementation-status.md
|
||||
- [x] Created docs/Development/ directory
|
||||
- [x] Wrote ARCHITECTURE.md
|
||||
- [x] Wrote ROADMAP.md
|
||||
- [x] Wrote TASKS.md
|
||||
|
||||
---
|
||||
|
||||
## 📊 Sprint Metrics
|
||||
|
||||
### Current Sprint (Week 1)
|
||||
- **Planned Tasks**: 8
|
||||
- **Completed**: 7
|
||||
- **In Progress**: 1
|
||||
- **Blocked**: 0
|
||||
- **Completion Rate**: 87.5%
|
||||
|
||||
### Overall Progress (Phase 1)
|
||||
- **Total Tasks**: 6
|
||||
- **Completed**: 3
|
||||
- **Remaining**: 3
|
||||
- **On Schedule**: ✅ Yes
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Task Management Process
|
||||
|
||||
### Weekly Cycle
|
||||
1. **Monday**: Review last week, plan this week
|
||||
2. **Mid-week**: Progress check, adjust priorities
|
||||
3. **Friday**: Update task status, prepare next week
|
||||
|
||||
### Task Categories
|
||||
- 🔥 **High Priority**: Must complete this week
|
||||
- 📋 **Medium Priority**: Complete this month
|
||||
- 💡 **Low Priority**: Future enhancements
|
||||
- 🐛 **Bugs**: Critical issues requiring immediate attention
|
||||
|
||||
### Status Markers
|
||||
- ✅ **Completed**: Task finished and verified
|
||||
- 🔄 **In Progress**: Currently working on
|
||||
- ⏳ **Pending**: Waiting for dependencies
|
||||
- 🚫 **Blocked**: Cannot proceed (document blocker)
|
||||
|
||||
---
|
||||
|
||||
## 📝 Task Template
|
||||
|
||||
When adding new tasks, use this format:
|
||||
|
||||
```markdown
|
||||
- [ ] Task description
|
||||
- **Priority**: High/Medium/Low
|
||||
- **Estimate**: 1-2 hours / 1-2 days / 1 week
|
||||
- **Dependencies**: List dependent tasks
|
||||
- **Blocker**: Any blocking issues
|
||||
- **Assigned**: Person/Team
|
||||
- **Due Date**: YYYY-MM-DD
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Verified**: 2025-10-14
|
||||
**Next Update**: 2025-10-17 (Mid-week check)
|
||||
**Version**: 4.1.5
|
||||
@@ -0,0 +1,390 @@
|
||||
# PM Agent Autonomous Enhancement - 改善提案
|
||||
|
||||
> **Date**: 2025-10-14
|
||||
> **Status**: 提案中（ユーザーレビュー待ち）
|
||||
> **Goal**: ユーザーインプット最小化 + 確信を持った先回り提案
|
||||
|
||||
---
|
||||
|
||||
## 🎯 現状の問題点
|
||||
|
||||
### 既存の `superclaude/commands/pm.md`
|
||||
```yaml
|
||||
良い点:
|
||||
✅ PDCAサイクルが定義されている
|
||||
✅ サブエージェント連携が明確
|
||||
✅ ドキュメント記録の仕組みがある
|
||||
|
||||
改善が必要な点:
|
||||
❌ ユーザーインプット依存度が高い
|
||||
❌ 調査フェーズが受動的
|
||||
❌ 提案が「どうしますか？」スタイル
|
||||
❌ 確信を持った提案がない
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 改善提案
|
||||
|
||||
### Phase 0: **自律的調査フェーズ**（新規追加）
|
||||
|
||||
#### ユーザーリクエスト受信時の自動実行
|
||||
```yaml
|
||||
Auto-Investigation (許可不要・自動実行):
|
||||
1. Context Restoration:
|
||||
- Read docs/Development/tasks/current-tasks.md
|
||||
- list_memories() → 前回のセッション確認
|
||||
- read_memory("project_context") → プロジェクト理解
|
||||
- read_memory("past_mistakes") → 過去の失敗確認
|
||||
|
||||
2. Project Analysis:
|
||||
- Read CLAUDE.md → プロジェクト固有ルール
|
||||
- Glob **/*.md → ドキュメント構造把握
|
||||
- mcp__serena__get_symbols_overview → コード構造理解
|
||||
- Grep "TODO\|FIXME\|XXX" → 既知の課題確認
|
||||
|
||||
3. Current State Assessment:
|
||||
- Bash "git status" → 現在の状態
|
||||
- Bash "git log -5 --oneline" → 最近の変更
|
||||
- Read tests/ → テストカバレッジ確認
|
||||
- Security scan → セキュリティリスク確認
|
||||
|
||||
4. Competitive Research (必要時):
|
||||
- tavily search → ベストプラクティス調査
|
||||
- context7 → 公式ドキュメント参照
|
||||
- Deep Research → 競合サービス分析
|
||||
|
||||
5. Architecture Evaluation:
|
||||
- 既存アーキテクチャの強み分析
|
||||
- 技術スタックの特徴把握
|
||||
- 拡張可能性の評価
|
||||
```
|
||||
|
||||
#### 出力形式
|
||||
```markdown
|
||||
📊 自律調査完了
|
||||
|
||||
現状分析:
|
||||
- プロジェクト: [名前]（[技術スタック]）
|
||||
- 進捗: [前回セッションの続き or 新規タスク]
|
||||
- コードベース: [ファイル数]、テストカバレッジ [%]
|
||||
- 既知の課題: [TODO/FIXME数]
|
||||
- 最近の変更: [git log要約]
|
||||
|
||||
アーキテクチャの強み:
|
||||
- [強み1]: [具体的な理由]
|
||||
- [強み2]: [具体的な理由]
|
||||
|
||||
不足している要素:
|
||||
- [不足1]: [影響]
|
||||
- [不足2]: [影響]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 1: **確信を持った提案**（強化）
|
||||
|
||||
#### ❌ 改善前（受動的）
|
||||
```
|
||||
User: "認証機能作って"
|
||||
|
||||
PM Agent: "認証機能を実装しますね。
|
||||
どんな認証方式がいいですか？"
|
||||
|
||||
→ ユーザーに丸投げ
|
||||
```
|
||||
|
||||
#### ✅ 改善後（能動的・確信あり）
|
||||
```
|
||||
User: "認証機能作って"
|
||||
|
||||
PM Agent:
|
||||
📊 自律調査完了（3秒）:
|
||||
- 既存: Supabase統合済み（強み）
|
||||
- 不足: 認証機能なし
|
||||
- テスト: カバレッジ45%（目標80%）
|
||||
- 競合調査: Auth0、Clerk、Supabase Auth比較済み
|
||||
- セキュリティ: OWASP推奨3項目未対応
|
||||
|
||||
💡 確信を持った提案:
|
||||
|
||||
このアーキテクチャはSupabase連携に強みがあるため、
|
||||
**Supabase Auth統合**を推奨します。
|
||||
|
||||
具体的な実装方針:
|
||||
1. Supabase Auth統合（JWT + リフレッシュトークン）
|
||||
2. MFA対応（TOTP実装）
|
||||
3. セキュリティテスト追加（カバレッジ85%目標）
|
||||
4. 既存APIとのシームレス統合
|
||||
|
||||
選択理由:
|
||||
✅ 既存のSupabase接続再利用（実装コスト最小）
|
||||
✅ エンタープライズグレードのセキュリティ
|
||||
✅ 無料枠で十分な機能（コスト効率◎）
|
||||
✅ 将来のスケーラビリティ確保
|
||||
|
||||
代替案との比較:
|
||||
- Auth0: 月$25〜、実装複雑度高
|
||||
- Clerk: 月$25〜、React特化（このプロジェクトはNext.js）
|
||||
- Supabase Auth: 無料、既存統合済み ← 推奨
|
||||
|
||||
この方針で進めてよろしいですか？
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: **自律実行**（既存を強化）
|
||||
|
||||
#### 承認後の自動フロー
|
||||
```yaml
|
||||
User: "OK"
|
||||
|
||||
PM Agent（完全自律実行）:
|
||||
1. Architecture Design:
|
||||
- system-architect: Supabase Auth設計
|
||||
- security-engineer: セキュリティレビュー
|
||||
|
||||
2. Implementation:
|
||||
- backend-architect: API統合実装
|
||||
- frontend-architect: UI実装
|
||||
- Load magic: Login/Register components
|
||||
|
||||
3. Testing:
|
||||
- Write tests/auth/*.test.ts
|
||||
- pytest実行 → 失敗検出
|
||||
|
||||
4. Self-Correction:
|
||||
- context7 → Supabase公式ドキュメント確認
|
||||
- エラー原因特定: "JWTシークレット未設定"
|
||||
- 修正実装
|
||||
- 再テスト → 合格
|
||||
|
||||
5. Documentation:
|
||||
- Update docs/patterns/supabase-auth-integration.md
|
||||
- Update CLAUDE.md（認証パターン追加）
|
||||
- write_memory("success_pattern", 詳細)
|
||||
|
||||
6. Report:
|
||||
✅ 認証機能実装完了
|
||||
|
||||
実装内容:
|
||||
- Supabase Auth統合（JWT + リフレッシュ）
|
||||
- MFA対応（TOTP）
|
||||
- テストカバレッジ: 45% → 87%（目標達成）
|
||||
- セキュリティ: OWASP準拠確認済み
|
||||
|
||||
学習記録:
|
||||
- 成功パターン: docs/patterns/supabase-auth-integration.md
|
||||
- 遭遇したエラー: JWT設定不足（修正済み）
|
||||
- 次回の改善: 環境変数チェックリスト更新
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 実装方針
|
||||
|
||||
### `superclaude/commands/pm.md` への追加セクション
|
||||
|
||||
#### 1. Autonomous Investigation Phase（新規）
|
||||
```markdown
|
||||
## Phase 0: Autonomous Investigation (Auto-Execute)
|
||||
|
||||
**Trigger**: Any user request received
|
||||
|
||||
**Execution**: Automatic, no permission required
|
||||
|
||||
### Investigation Steps:
|
||||
1. **Context Restoration**
|
||||
- Read `docs/Development/tasks/current-tasks.md`
|
||||
- Serena memory restoration
|
||||
- Project context loading
|
||||
|
||||
2. **Project Analysis**
|
||||
- CLAUDE.md → Project rules
|
||||
- Code structure analysis
|
||||
- Test coverage check
|
||||
- Security scan
|
||||
- Known issues detection (TODO/FIXME)
|
||||
|
||||
3. **Competitive Research** (when relevant)
|
||||
- Best practices research (Tavily)
|
||||
- Official documentation (Context7)
|
||||
- Alternative solutions analysis
|
||||
|
||||
4. **Architecture Evaluation**
|
||||
- Identify architectural strengths
|
||||
- Detect technology stack characteristics
|
||||
- Assess extensibility
|
||||
|
||||
### Output Format:
|
||||
```
|
||||
📊 Autonomous Investigation Complete
|
||||
|
||||
Current State:
|
||||
- Project: [name] ([stack])
|
||||
- Progress: [status]
|
||||
- Codebase: [files count], Test Coverage: [%]
|
||||
- Known Issues: [count]
|
||||
- Recent Changes: [git log summary]
|
||||
|
||||
Architectural Strengths:
|
||||
- [strength 1]: [rationale]
|
||||
- [strength 2]: [rationale]
|
||||
|
||||
Missing Elements:
|
||||
- [gap 1]: [impact]
|
||||
- [gap 2]: [impact]
|
||||
```
|
||||
```
|
||||
|
||||
#### 2. Confident Proposal Phase（強化）
|
||||
```markdown
|
||||
## Phase 1: Confident Proposal (Enhanced)
|
||||
|
||||
**Principle**: Never ask "What do you want?" - Always propose with conviction
|
||||
|
||||
### Proposal Format:
|
||||
```
|
||||
💡 Confident Proposal:
|
||||
|
||||
[Implementation approach] is recommended.
|
||||
|
||||
Specific Implementation Plan:
|
||||
1. [Step 1 with rationale]
|
||||
2. [Step 2 with rationale]
|
||||
3. [Step 3 with rationale]
|
||||
|
||||
Selection Rationale:
|
||||
✅ [Reason 1]: [Evidence]
|
||||
✅ [Reason 2]: [Evidence]
|
||||
✅ [Reason 3]: [Evidence]
|
||||
|
||||
Alternatives Considered:
|
||||
- [Alt 1]: [Why not chosen]
|
||||
- [Alt 2]: [Why not chosen]
|
||||
- [Recommended]: [Why chosen] ← Recommended
|
||||
|
||||
Proceed with this approach?
|
||||
```
|
||||
|
||||
### Anti-Patterns (Never Do):
|
||||
❌ "What authentication do you want?" (Passive)
|
||||
❌ "How should we implement this?" (Uncertain)
|
||||
❌ "There are several options..." (Indecisive)
|
||||
|
||||
✅ "Supabase Auth is recommended because..." (Confident)
|
||||
✅ "Based on your architecture's Supabase integration..." (Evidence-based)
|
||||
```
|
||||
|
||||
#### 3. Autonomous Execution Phase（既存を明示化）
|
||||
```markdown
|
||||
## Phase 2: Autonomous Execution
|
||||
|
||||
**Trigger**: User approval ("OK", "Go ahead", "Yes")
|
||||
|
||||
**Execution**: Fully autonomous, systematic PDCA
|
||||
|
||||
### Self-Correction Loop:
|
||||
```yaml
|
||||
Implementation:
|
||||
- Execute with sub-agents
|
||||
- Write comprehensive tests
|
||||
- Run validation
|
||||
|
||||
Error Detected:
|
||||
→ Context7: Check official documentation
|
||||
→ Identify root cause
|
||||
→ Implement fix
|
||||
→ Re-test
|
||||
→ Repeat until passing
|
||||
|
||||
Success:
|
||||
→ Document pattern (docs/patterns/)
|
||||
→ Update learnings (write_memory)
|
||||
→ Report completion with evidence
|
||||
```
|
||||
|
||||
### Quality Gates:
|
||||
- Tests must pass (no exceptions)
|
||||
- Coverage targets must be met
|
||||
- Security checks must pass
|
||||
- Documentation must be updated
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 期待される効果
|
||||
|
||||
### Before (現状)
|
||||
```yaml
|
||||
User Input Required: 高
|
||||
- 認証方式の選択
|
||||
- 実装方針の決定
|
||||
- エラー対応の指示
|
||||
- テスト方針の決定
|
||||
|
||||
Proposal Quality: 受動的
|
||||
- "どうしますか？"スタイル
|
||||
- 選択肢の羅列のみ
|
||||
- ユーザーが決定
|
||||
|
||||
Execution: 半自動
|
||||
- エラー時にユーザーに報告
|
||||
- 修正方針をユーザーが指示
|
||||
```
|
||||
|
||||
### After (改善後)
|
||||
```yaml
|
||||
User Input Required: 最小
|
||||
- "認証機能作って"のみ
|
||||
- 提案への承認/拒否のみ
|
||||
|
||||
Proposal Quality: 能動的・確信あり
|
||||
- 調査済みの根拠提示
|
||||
- 明確な推奨案
|
||||
- 代替案との比較
|
||||
|
||||
Execution: 完全自律
|
||||
- エラー自己修正
|
||||
- 公式ドキュメント自動参照
|
||||
- テスト合格まで自動実行
|
||||
- 学習自動記録
|
||||
```
|
||||
|
||||
### 定量的目標
|
||||
- ユーザーインプット削減: **80%削減**
|
||||
- 提案品質向上: **確信度90%以上**
|
||||
- 自律実行成功率: **95%以上**
|
||||
|
||||
---
|
||||
|
||||
## 🚀 実装ステップ
|
||||
|
||||
### Step 1: pm.md 修正
|
||||
- [ ] Phase 0: Autonomous Investigation 追加
|
||||
- [ ] Phase 1: Confident Proposal 強化
|
||||
- [ ] Phase 2: Autonomous Execution 明示化
|
||||
- [ ] Examples セクションに具体例追加
|
||||
|
||||
### Step 2: テスト作成
|
||||
- [ ] `tests/test_pm_autonomous.py`
|
||||
- [ ] 自律調査フローのテスト
|
||||
- [ ] 確信提案フォーマットのテスト
|
||||
- [ ] 自己修正ループのテスト
|
||||
|
||||
### Step 3: 動作確認
|
||||
- [ ] 開発版インストール
|
||||
- [ ] 実際のワークフローで検証
|
||||
- [ ] フィードバック収集
|
||||
|
||||
### Step 4: 学習記録
|
||||
- [ ] `docs/patterns/pm-autonomous-workflow.md`
|
||||
- [ ] 成功パターンの文書化
|
||||
|
||||
---
|
||||
|
||||
## ✅ ユーザー承認待ち
|
||||
|
||||
**この方針で実装を進めてよろしいですか？**
|
||||
|
||||
承認いただければ、すぐに `superclaude/commands/pm.md` の修正を開始します。
|
||||
378
docs/Development/installation-flow-understanding.md
Normal file
378
docs/Development/installation-flow-understanding.md
Normal file
@@ -0,0 +1,378 @@
|
||||
# SuperClaude Installation Flow - Complete Understanding
|
||||
|
||||
> **学習内容**: インストーラーがどうやって `~/.claude/` にファイルを配置するかの完全理解
|
||||
|
||||
---
|
||||
|
||||
## 🔄 インストールフロー全体像
|
||||
|
||||
### ユーザー操作
|
||||
```bash
|
||||
# Step 1: パッケージインストール
|
||||
pipx install SuperClaude
|
||||
# または
|
||||
npm install -g @bifrost_inc/superclaude
|
||||
|
||||
# Step 2: セットアップ実行
|
||||
SuperClaude install
|
||||
```
|
||||
|
||||
### 内部処理の流れ
|
||||
|
||||
```yaml
|
||||
1. Entry Point:
|
||||
File: superclaude/__main__.py → main()
|
||||
|
||||
2. CLI Parser:
|
||||
File: superclaude/__main__.py → create_parser()
|
||||
Command: "install" サブコマンド登録
|
||||
|
||||
3. Component Manager:
|
||||
File: setup/cli/install.py
|
||||
Role: インストールコンポーネントの調整
|
||||
|
||||
4. Commands Component:
|
||||
File: setup/components/commands.py → CommandsComponent
|
||||
Role: スラッシュコマンドのインストール
|
||||
|
||||
5. Source Files:
|
||||
Location: superclaude/commands/*.md
|
||||
Content: pm.md, implement.md, test.md, etc.
|
||||
|
||||
6. Destination:
|
||||
Location: ~/.claude/commands/sc/*.md
|
||||
Result: ユーザー環境に配置
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 CommandsComponent の詳細
|
||||
|
||||
### クラス構造
|
||||
```python
|
||||
class CommandsComponent(Component):
|
||||
"""
|
||||
Role: スラッシュコマンドのインストール・管理
|
||||
Parent: setup/core/base.py → Component
|
||||
Install Path: ~/.claude/commands/sc/
|
||||
"""
|
||||
```
|
||||
|
||||
### 主要メソッド
|
||||
|
||||
#### 1. `__init__()`
|
||||
```python
|
||||
def __init__(self, install_dir: Optional[Path] = None):
|
||||
super().__init__(install_dir, Path("commands/sc"))
|
||||
```
|
||||
**理解**:
|
||||
- `install_dir`: `~/.claude/` （ユーザー環境）
|
||||
- `Path("commands/sc")`: サブディレクトリ指定
|
||||
- 結果: `~/.claude/commands/sc/` にインストール
|
||||
|
||||
#### 2. `_get_source_dir()`
|
||||
```python
|
||||
def _get_source_dir(self) -> Path:
|
||||
# setup/components/commands.py の位置から計算
|
||||
project_root = Path(__file__).parent.parent.parent
|
||||
# → ~/github/SuperClaude_Framework/
|
||||
|
||||
return project_root / "superclaude" / "commands"
|
||||
# → ~/github/SuperClaude_Framework/superclaude/commands/
|
||||
```
|
||||
|
||||
**理解**:
|
||||
```
|
||||
Source: ~/github/SuperClaude_Framework/superclaude/commands/*.md
|
||||
Target: ~/.claude/commands/sc/*.md
|
||||
|
||||
つまり:
|
||||
superclaude/commands/pm.md
|
||||
↓ コピー
|
||||
~/.claude/commands/sc/pm.md
|
||||
```
|
||||
|
||||
#### 3. `_install()` - インストール実行
|
||||
```python
|
||||
def _install(self, config: Dict[str, Any]) -> bool:
|
||||
self.logger.info("Installing SuperClaude command definitions...")
|
||||
|
||||
# 既存コマンドのマイグレーション
|
||||
self._migrate_existing_commands()
|
||||
|
||||
# 親クラスのインストール実行
|
||||
return super()._install(config)
|
||||
```
|
||||
|
||||
**理解**:
|
||||
1. ログ出力
|
||||
2. 旧バージョンからの移行処理
|
||||
3. 実際のファイルコピー（親クラスで実行）
|
||||
|
||||
#### 4. `_migrate_existing_commands()` - マイグレーション
|
||||
```python
|
||||
def _migrate_existing_commands(self) -> None:
|
||||
"""
|
||||
旧Location: ~/.claude/commands/*.md
|
||||
新Location: ~/.claude/commands/sc/*.md
|
||||
|
||||
V3 → V4 移行時の処理
|
||||
"""
|
||||
old_commands_dir = self.install_dir / "commands"
|
||||
new_commands_dir = self.install_dir / "commands" / "sc"
|
||||
|
||||
# 旧場所からファイル検出
|
||||
# 新場所へコピー
|
||||
# 旧場所から削除
|
||||
```
|
||||
|
||||
**理解**:
|
||||
- V3: `/analyze` → V4: `/sc:analyze`
|
||||
- 名前空間衝突を防ぐため `/sc:` プレフィックス
|
||||
|
||||
#### 5. `_post_install()` - メタデータ更新
|
||||
```python
|
||||
def _post_install(self) -> bool:
|
||||
# メタデータ更新
|
||||
metadata_mods = self.get_metadata_modifications()
|
||||
self.settings_manager.update_metadata(metadata_mods)
|
||||
|
||||
# コンポーネント登録
|
||||
self.settings_manager.add_component_registration(
|
||||
"commands",
|
||||
{
|
||||
"version": __version__,
|
||||
"category": "commands",
|
||||
"files_count": len(self.component_files),
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
**理解**:
|
||||
- `~/.claude/.superclaude.json` 更新
|
||||
- インストール済みコンポーネント記録
|
||||
- バージョン管理
|
||||
|
||||
---
|
||||
|
||||
## 📋 実際のファイルマッピング
|
||||
|
||||
### Source（このプロジェクト）
|
||||
```
|
||||
~/github/SuperClaude_Framework/superclaude/commands/
|
||||
├── pm.md # PM Agent定義
|
||||
├── implement.md # Implement コマンド
|
||||
├── test.md # Test コマンド
|
||||
├── analyze.md # Analyze コマンド
|
||||
├── research.md # Research コマンド
|
||||
├── ...（全26コマンド）
|
||||
```
|
||||
|
||||
### Destination（ユーザー環境）
|
||||
```
|
||||
~/.claude/commands/sc/
|
||||
├── pm.md # → /sc:pm で実行可能
|
||||
├── implement.md # → /sc:implement で実行可能
|
||||
├── test.md # → /sc:test で実行可能
|
||||
├── analyze.md # → /sc:analyze で実行可能
|
||||
├── research.md # → /sc:research で実行可能
|
||||
├── ...（全26コマンド）
|
||||
```
|
||||
|
||||
### Claude Code動作
|
||||
```
|
||||
User: /sc:pm "Build authentication"
|
||||
|
||||
Claude Code:
|
||||
1. ~/.claude/commands/sc/pm.md 読み込み
|
||||
2. YAML frontmatter 解析
|
||||
3. Markdown本文を展開
|
||||
4. PM Agent として実行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 他のコンポーネント
|
||||
|
||||
### Modes Component
|
||||
```python
|
||||
File: setup/components/modes.py
|
||||
Source: superclaude/modes/*.md
|
||||
Target: ~/.claude/*.md
|
||||
|
||||
Example:
|
||||
superclaude/modes/MODE_Brainstorming.md
|
||||
↓
|
||||
~/.claude/MODE_Brainstorming.md
|
||||
```
|
||||
|
||||
### Agents Component
|
||||
```python
|
||||
File: setup/components/agents.py
|
||||
Source: superclaude/agents/*.md
|
||||
Target: ~/.claude/agents/*.md（または統合先）
|
||||
```
|
||||
|
||||
### Core Component
|
||||
```python
|
||||
File: setup/components/core.py
|
||||
Source: superclaude/core/CLAUDE.md
|
||||
Target: ~/.claude/CLAUDE.md
|
||||
|
||||
これがグローバル設定！
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 開発時の注意点
|
||||
|
||||
### ✅ 正しい変更方法
|
||||
```bash
|
||||
# 1. ソースファイルを変更（Git管理）
|
||||
cd ~/github/SuperClaude_Framework
|
||||
vim superclaude/commands/pm.md
|
||||
|
||||
# 2. テスト追加
|
||||
Write tests/test_pm_command.py
|
||||
|
||||
# 3. テスト実行
|
||||
pytest tests/test_pm_command.py -v
|
||||
|
||||
# 4. コミット
|
||||
git add superclaude/commands/pm.md tests/
|
||||
git commit -m "feat: enhance PM command"
|
||||
|
||||
# 5. 開発版インストール
|
||||
pip install -e .
|
||||
# または
|
||||
SuperClaude install --dev
|
||||
|
||||
# 6. 動作確認
|
||||
claude
|
||||
/sc:pm "test"
|
||||
```
|
||||
|
||||
### ❌ 間違った変更方法
|
||||
```bash
|
||||
# ダメ！Git管理外を直接変更
|
||||
vim ~/.claude/commands/sc/pm.md
|
||||
|
||||
# 変更は次回インストール時に上書きされる
|
||||
SuperClaude install # ← 変更が消える！
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 PM Mode改善の正しいフロー
|
||||
|
||||
### Phase 1: 理解（今ここ！）
|
||||
```bash
|
||||
✅ setup/components/commands.py 理解完了
|
||||
✅ superclaude/commands/*.md の存在確認完了
|
||||
✅ インストールフロー理解完了
|
||||
```
|
||||
|
||||
### Phase 2: 現在の仕様確認
|
||||
```bash
|
||||
# ソース確認（Git管理）
|
||||
Read superclaude/commands/pm.md
|
||||
|
||||
# インストール後確認（参考用）
|
||||
Read ~/.claude/commands/sc/pm.md
|
||||
|
||||
# 「なるほど、こういう仕様になってるのか」
|
||||
```
|
||||
|
||||
### Phase 3: 改善案作成
|
||||
```bash
|
||||
# このプロジェクト内で（Git管理）
|
||||
Write docs/Development/hypothesis-pm-enhancement-2025-10-14.md
|
||||
|
||||
内容:
|
||||
- 現状の問題（ドキュメント寄りすぎ、PMO機能不足）
|
||||
- 改善案（自律的PDCA、自己評価）
|
||||
- 実装方針
|
||||
- 期待される効果
|
||||
```
|
||||
|
||||
### Phase 4: 実装
|
||||
```bash
|
||||
# ソースファイル修正
|
||||
Edit superclaude/commands/pm.md
|
||||
|
||||
変更例:
|
||||
- PDCA自動実行の強化
|
||||
- docs/ ディレクトリ活用の明示
|
||||
- 自己評価ステップの追加
|
||||
- エラー時再学習フローの追加
|
||||
```
|
||||
|
||||
### Phase 5: テスト・検証
|
||||
```bash
|
||||
# テスト追加
|
||||
Write tests/test_pm_enhanced.py
|
||||
|
||||
# テスト実行
|
||||
pytest tests/test_pm_enhanced.py -v
|
||||
|
||||
# 開発版インストール
|
||||
SuperClaude install --dev
|
||||
|
||||
# 実際に使ってみる
|
||||
claude
|
||||
/sc:pm "test enhanced workflow"
|
||||
```
|
||||
|
||||
### Phase 6: 学習記録
|
||||
```bash
|
||||
# 成功パターン記録
|
||||
Write docs/patterns/pm-autonomous-workflow.md
|
||||
|
||||
# 失敗があれば記録
|
||||
Write docs/mistakes/mistake-2025-10-14.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Component間の依存関係
|
||||
|
||||
```yaml
|
||||
Commands Component:
|
||||
depends_on: ["core"]
|
||||
|
||||
Core Component:
|
||||
provides:
|
||||
- ~/.claude/CLAUDE.md（グローバル設定）
|
||||
- 基本ディレクトリ構造
|
||||
|
||||
Modes Component:
|
||||
depends_on: ["core"]
|
||||
provides:
|
||||
- ~/.claude/MODE_*.md
|
||||
|
||||
Agents Component:
|
||||
depends_on: ["core"]
|
||||
provides:
|
||||
- エージェント定義
|
||||
|
||||
MCP Component:
|
||||
depends_on: ["core"]
|
||||
provides:
|
||||
- MCPサーバー設定
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 次のアクション
|
||||
|
||||
理解完了！次は：
|
||||
|
||||
1. ✅ `superclaude/commands/pm.md` の現在の仕様確認
|
||||
2. ✅ 改善提案ドキュメント作成
|
||||
3. ✅ 実装修正（PDCA強化、PMO機能追加）
|
||||
4. ✅ テスト追加・実行
|
||||
5. ✅ 動作確認
|
||||
6. ✅ 学習記録
|
||||
|
||||
このドキュメント自体が**インストールフローの完全理解記録**として機能する。
|
||||
次回のセッションで読めば、同じ説明を繰り返さなくて済む。
|
||||
341
docs/Development/pm-agent-ideal-workflow.md
Normal file
341
docs/Development/pm-agent-ideal-workflow.md
Normal file
@@ -0,0 +1,341 @@
|
||||
# PM Agent - Ideal Autonomous Workflow
|
||||
|
||||
> **目的**: 何百回も同じ指示を繰り返さないための自律的オーケストレーションシステム
|
||||
|
||||
## 🎯 解決すべき問題
|
||||
|
||||
### 現状の課題
|
||||
- **繰り返し指示**: 同じことを何百回も説明している
|
||||
- **同じミスの反復**: 一度間違えたことを再度間違える
|
||||
- **知識の喪失**: セッションが途切れると学習内容が失われる
|
||||
- **コンテキスト制限**: 限られたコンテキストで効率的に動作できていない
|
||||
|
||||
### あるべき姿
|
||||
**自律的で賢いPM Agent** - ドキュメントから学び、計画し、実行し、検証し、学習を記録するループ
|
||||
|
||||
---
|
||||
|
||||
## 📋 完璧なワークフロー（理想形）
|
||||
|
||||
### Phase 1: 📖 状況把握（Context Restoration）
|
||||
|
||||
```yaml
|
||||
1. ドキュメント読み込み:
|
||||
優先順位:
|
||||
1. タスク管理ドキュメント → 進捗確認
|
||||
- docs/Development/tasks/current-tasks.md
|
||||
- 前回どこまでやったか
|
||||
- 次に何をすべきか
|
||||
|
||||
2. アーキテクチャドキュメント → 仕組み理解
|
||||
- docs/Development/architecture-*.md
|
||||
- このプロジェクトの構造
|
||||
- インストールフロー
|
||||
- コンポーネント連携
|
||||
|
||||
3. 禁止事項・ルール → 制約確認
|
||||
- CLAUDE.md（グローバル）
|
||||
- PROJECT/CLAUDE.md（プロジェクト固有）
|
||||
- docs/Development/constraints.md
|
||||
|
||||
4. 過去の学び → 同じミスを防ぐ
|
||||
- docs/mistakes/ （失敗記録）
|
||||
- docs/patterns/ （成功パターン）
|
||||
|
||||
2. ユーザーリクエスト理解:
|
||||
- 何をしたいのか
|
||||
- どこまで進んでいるのか
|
||||
- 何が課題なのか
|
||||
```
|
||||
|
||||
### Phase 2: 🔍 調査・分析（Research & Analysis）
|
||||
|
||||
```yaml
|
||||
1. 既存実装の理解:
|
||||
# ソースコード側（Git管理）
|
||||
- setup/components/*.py → インストールロジック
|
||||
- superclaude/ → ランタイムロジック
|
||||
- tests/ → テストパターン
|
||||
|
||||
# インストール後（ユーザー環境・Git管理外）
|
||||
- ~/.claude/commands/sc/ → 実際の配置確認
|
||||
- ~/.claude/*.md → 現在の仕様確認
|
||||
|
||||
理解内容:
|
||||
「なるほど、ここでこう処理されて、
|
||||
こういうファイルが ~/.claude/ に作られるのね」
|
||||
|
||||
2. ベストプラクティス調査:
|
||||
# Deep Research活用
|
||||
- 公式リファレンス確認
|
||||
- 他プロジェクトの実装調査
|
||||
- 最新のベストプラクティス
|
||||
|
||||
気づき:
|
||||
- 「ここ無駄だな」
|
||||
- 「ここ古いな」
|
||||
- 「これはいい実装だな」
|
||||
- 「この共通化できるな」
|
||||
|
||||
3. 重複・改善ポイント発見:
|
||||
- ライブラリの共通化可能性
|
||||
- 重複実装の検出
|
||||
- コード品質向上余地
|
||||
```
|
||||
|
||||
### Phase 3: 📝 計画立案（Planning）
|
||||
|
||||
```yaml
|
||||
1. 改善仮説作成:
|
||||
# このプロジェクト内で（Git管理）
|
||||
File: docs/Development/hypothesis-YYYY-MM-DD.md
|
||||
|
||||
内容:
|
||||
- 現状の問題点
|
||||
- 改善案
|
||||
- 期待される効果（トークン削減、パフォーマンス向上等）
|
||||
- 実装方針
|
||||
- 必要なテスト
|
||||
|
||||
2. ユーザーレビュー:
|
||||
「こういうプランでこんなことをやろうと思っています」
|
||||
|
||||
提示内容:
|
||||
- 調査結果のサマリー
|
||||
- 改善提案（理由付き）
|
||||
- 実装ステップ
|
||||
- 期待される成果
|
||||
|
||||
ユーザー承認待ち → OK出たら実装へ
|
||||
```
|
||||
|
||||
### Phase 4: 🛠️ 実装（Implementation）
|
||||
|
||||
```yaml
|
||||
1. ソースコード修正:
|
||||
# Git管理されているこのプロジェクトで作業
|
||||
cd ~/github/SuperClaude_Framework
|
||||
|
||||
修正対象:
|
||||
- setup/components/*.py → インストールロジック
|
||||
- superclaude/ → ランタイム機能
|
||||
- setup/data/*.json → 設定データ
|
||||
|
||||
# サブエージェント活用
|
||||
- backend-architect: アーキテクチャ実装
|
||||
- refactoring-expert: コード改善
|
||||
- quality-engineer: テスト設計
|
||||
|
||||
2. 実装記録:
|
||||
File: docs/Development/experiment-YYYY-MM-DD.md
|
||||
|
||||
内容:
|
||||
- 試行錯誤の記録
|
||||
- 遭遇したエラー
|
||||
- 解決方法
|
||||
- 気づき
|
||||
```
|
||||
|
||||
### Phase 5: ✅ 検証（Validation）
|
||||
|
||||
```yaml
|
||||
1. テスト作成・実行:
|
||||
# テストを書く
|
||||
Write tests/test_new_feature.py
|
||||
|
||||
# テスト実行
|
||||
pytest tests/test_new_feature.py -v
|
||||
|
||||
# ユーザー要求を満たしているか確認
|
||||
- 期待通りの動作か？
|
||||
- エッジケースは？
|
||||
- パフォーマンスは？
|
||||
|
||||
2. エラー時の対応:
|
||||
エラー発生
|
||||
↓
|
||||
公式リファレンス確認
|
||||
「このエラー何でだろう？」
|
||||
「ここの定義違ってたんだ」
|
||||
↓
|
||||
修正
|
||||
↓
|
||||
再テスト
|
||||
↓
|
||||
合格まで繰り返し
|
||||
|
||||
3. 動作確認:
|
||||
# インストールして実際の環境でテスト
|
||||
SuperClaude install --dev
|
||||
|
||||
# 動作確認
|
||||
claude # 起動して実際に試す
|
||||
```
|
||||
|
||||
### Phase 6: 📚 学習記録（Learning Documentation）
|
||||
|
||||
```yaml
|
||||
1. 成功パターン記録:
|
||||
File: docs/patterns/[pattern-name].md
|
||||
|
||||
内容:
|
||||
- どんな問題を解決したか
|
||||
- どう実装したか
|
||||
- なぜこのアプローチか
|
||||
- 再利用可能なパターン
|
||||
|
||||
2. 失敗・ミス記録:
|
||||
File: docs/mistakes/mistake-YYYY-MM-DD.md
|
||||
|
||||
内容:
|
||||
- どんなミスをしたか
|
||||
- なぜ起きたか
|
||||
- 防止策
|
||||
- チェックリスト
|
||||
|
||||
3. タスク更新:
|
||||
File: docs/Development/tasks/current-tasks.md
|
||||
|
||||
内容:
|
||||
- 完了したタスク
|
||||
- 次のタスク
|
||||
- 進捗状況
|
||||
- ブロッカー
|
||||
|
||||
4. グローバルパターン更新:
|
||||
必要に応じて:
|
||||
- CLAUDE.md更新（グローバルルール）
|
||||
- PROJECT/CLAUDE.md更新（プロジェクト固有）
|
||||
```
|
||||
|
||||
### Phase 7: 🔄 セッション保存（Session Persistence）
|
||||
|
||||
```yaml
|
||||
1. Serenaメモリー保存:
|
||||
write_memory("session_summary", 完了内容)
|
||||
write_memory("next_actions", 次のアクション)
|
||||
write_memory("learnings", 学んだこと)
|
||||
|
||||
2. ドキュメント整理:
|
||||
- docs/temp/ → docs/patterns/ or docs/mistakes/
|
||||
- 一時ファイル削除
|
||||
- 正式ドキュメント更新
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 活用可能なツール・リソース
|
||||
|
||||
### MCPサーバー（フル活用）
|
||||
- **Sequential**: 複雑な分析・推論
|
||||
- **Context7**: 公式ドキュメント参照
|
||||
- **Tavily**: Deep Research（ベストプラクティス調査）
|
||||
- **Serena**: セッション永続化、メモリー管理
|
||||
- **Playwright**: E2Eテスト、動作確認
|
||||
- **Morphllm**: 一括コード変換
|
||||
- **Magic**: UI生成（必要時）
|
||||
- **Chrome DevTools**: パフォーマンス測定
|
||||
|
||||
### サブエージェント（適材適所）
|
||||
- **requirements-analyst**: 要件整理
|
||||
- **system-architect**: アーキテクチャ設計
|
||||
- **backend-architect**: バックエンド実装
|
||||
- **refactoring-expert**: コード改善
|
||||
- **security-engineer**: セキュリティ検証
|
||||
- **quality-engineer**: テスト設計・実行
|
||||
- **performance-engineer**: パフォーマンス最適化
|
||||
- **technical-writer**: ドキュメント執筆
|
||||
|
||||
### 他プロジェクト統合
|
||||
- **makefile-global**: Makefile標準化パターン
|
||||
- **airis-mcp-gateway**: MCPゲートウェイ統合
|
||||
- その他有用なパターンは積極的に取り込む
|
||||
|
||||
---
|
||||
|
||||
## 🎯 重要な原則
|
||||
|
||||
### Git管理の区別
|
||||
```yaml
|
||||
✅ Git管理されている（変更追跡可能）:
|
||||
- ~/github/SuperClaude_Framework/
|
||||
- ここで全ての変更を行う
|
||||
- コミット履歴で追跡
|
||||
- PR提出可能
|
||||
|
||||
❌ Git管理外（変更追跡不可）:
|
||||
- ~/.claude/
|
||||
- 読むだけ、理解のみ
|
||||
- テスト時のみ一時変更（必ず戻す！）
|
||||
```
|
||||
|
||||
### テスト時の注意
|
||||
```bash
|
||||
# テスト前: 必ずバックアップ
|
||||
cp ~/.claude/commands/sc/pm.md ~/.claude/commands/sc/pm.md.backup
|
||||
|
||||
# テスト実行
|
||||
# ... 検証 ...
|
||||
|
||||
# テスト後: 必ず復元！！
|
||||
mv ~/.claude/commands/sc/pm.md.backup ~/.claude/commands/sc/pm.md
|
||||
```
|
||||
|
||||
### ドキュメント構造
|
||||
```
|
||||
docs/
|
||||
├── Development/ # 開発用ドキュメント
|
||||
│ ├── tasks/ # タスク管理
|
||||
│ ├── architecture-*.md # アーキテクチャ
|
||||
│ ├── constraints.md # 制約・禁止事項
|
||||
│ ├── hypothesis-*.md # 改善仮説
|
||||
│ └── experiment-*.md # 実験記録
|
||||
├── patterns/ # 成功パターン（清書後）
|
||||
├── mistakes/ # 失敗記録と防止策
|
||||
└── (既存のUser-Guide等)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 実装優先度
|
||||
|
||||
### Phase 1（必須）
|
||||
1. ドキュメント構造整備
|
||||
2. タスク管理システム
|
||||
3. セッション復元ワークフロー
|
||||
|
||||
### Phase 2（重要）
|
||||
4. 自己評価・検証ループ
|
||||
5. 学習記録自動化
|
||||
6. エラー時再学習フロー
|
||||
|
||||
### Phase 3（強化）
|
||||
7. PMO機能（重複検出、共通化提案）
|
||||
8. パフォーマンス測定・改善
|
||||
9. 他プロジェクト統合
|
||||
|
||||
---
|
||||
|
||||
## 📊 成功指標
|
||||
|
||||
### 定量的指標
|
||||
- **繰り返し指示の削減**: 同じ指示 → 50%削減目標
|
||||
- **ミス再発率**: 同じミス → 80%削減目標
|
||||
- **セッション復元時間**: <30秒で前回の続きから開始
|
||||
|
||||
### 定性的指標
|
||||
- ユーザーが「前回の続きから」と言うだけで再開できる
|
||||
- 過去のミスを自動的に避けられる
|
||||
- 公式ドキュメント参照が自動化されている
|
||||
- 実装→テスト→検証が自律的に回る
|
||||
|
||||
---
|
||||
|
||||
## 💡 次のアクション
|
||||
|
||||
このドキュメント作成後:
|
||||
1. 既存のインストールロジック理解（setup/components/）
|
||||
2. タスク管理ドキュメント作成（docs/Development/tasks/）
|
||||
3. PM Agent実装修正（このワークフローを実際に実装）
|
||||
|
||||
このドキュメント自体が**PM Agentの憲法**となる。
|
||||
477
docs/Development/pm-agent-integration.md
Normal file
477
docs/Development/pm-agent-integration.md
Normal file
@@ -0,0 +1,477 @@
|
||||
# PM Agent Mode Integration Guide
|
||||
|
||||
**Last Updated**: 2025-10-14
|
||||
**Target Version**: 4.2.0
|
||||
**Status**: Implementation Guide
|
||||
|
||||
---
|
||||
|
||||
## 📋 Overview
|
||||
|
||||
This guide provides step-by-step procedures for integrating PM Agent mode as SuperClaude's always-active meta-layer with session lifecycle management, PDCA self-evaluation, and systematic knowledge management.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Integration Goals
|
||||
|
||||
1. **Session Lifecycle**: Auto-activation at session start with context restoration
|
||||
2. **PDCA Engine**: Automated Plan-Do-Check-Act cycle execution
|
||||
3. **Memory Operations**: Serena MCP integration for session persistence
|
||||
4. **Documentation Strategy**: Systematic knowledge evolution
|
||||
|
||||
---
|
||||
|
||||
## 📐 Architecture Integration
|
||||
|
||||
### PM Agent Position
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────┐
|
||||
│ PM Agent Mode (Meta-Layer) │
|
||||
│ • Always Active │
|
||||
│ • Session Management │
|
||||
│ • PDCA Self-Evaluation │
|
||||
└──────────────┬───────────────────────────┘
|
||||
↓
|
||||
[Specialist Agents Layer]
|
||||
↓
|
||||
[Commands & Modes Layer]
|
||||
↓
|
||||
[MCP Tool Layer]
|
||||
```
|
||||
|
||||
See: [ARCHITECTURE.md](./ARCHITECTURE.md) for full system architecture
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Phase 2: Core Implementation
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
superclaude/
|
||||
├── Commands/
|
||||
│ └── pm.md # ✅ Already updated
|
||||
├── Agents/
|
||||
│ └── pm-agent.md # ✅ Already updated
|
||||
└── Core/
|
||||
├── __init__.py # Module initialization
|
||||
├── session_lifecycle.py # 🆕 Session management
|
||||
├── pdca_engine.py # 🆕 PDCA automation
|
||||
└── memory_ops.py # 🆕 Memory operations
|
||||
```
|
||||
|
||||
### Implementation Order
|
||||
|
||||
1. `memory_ops.py` - Serena MCP wrapper (foundation)
|
||||
2. `session_lifecycle.py` - Session management (depends on memory_ops)
|
||||
3. `pdca_engine.py` - PDCA automation (depends on memory_ops)
|
||||
|
||||
---
|
||||
|
||||
## 1️⃣ memory_ops.py Implementation
|
||||
|
||||
### Purpose
|
||||
Wrapper for Serena MCP memory operations with error handling and fallback.
|
||||
|
||||
### Key Functions
|
||||
|
||||
```python
|
||||
# superclaude/Core/memory_ops.py
|
||||
|
||||
class MemoryOperations:
|
||||
"""Serena MCP memory operations wrapper"""
|
||||
|
||||
def list_memories() -> List[str]:
|
||||
"""List all available memories"""
|
||||
|
||||
def read_memory(key: str) -> Optional[Dict]:
|
||||
"""Read memory by key"""
|
||||
|
||||
def write_memory(key: str, value: Dict) -> bool:
|
||||
"""Write memory with key"""
|
||||
|
||||
def delete_memory(key: str) -> bool:
|
||||
"""Delete memory by key"""
|
||||
```
|
||||
|
||||
### Integration Points
|
||||
- Connect to Serena MCP server
|
||||
- Handle connection errors gracefully
|
||||
- Provide fallback for offline mode
|
||||
- Validate memory structure
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
pytest tests/test_memory_ops.py -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2️⃣ session_lifecycle.py Implementation
|
||||
|
||||
### Purpose
|
||||
Auto-activation at session start, context restoration, user report generation.
|
||||
|
||||
### Key Functions
|
||||
|
||||
```python
|
||||
# superclaude/Core/session_lifecycle.py
|
||||
|
||||
class SessionLifecycle:
|
||||
"""Session lifecycle management"""
|
||||
|
||||
def on_session_start():
|
||||
"""Hook for session start (auto-activation)"""
|
||||
# 1. list_memories()
|
||||
# 2. read_memory("pm_context")
|
||||
# 3. read_memory("last_session")
|
||||
# 4. read_memory("next_actions")
|
||||
# 5. generate_user_report()
|
||||
|
||||
def generate_user_report() -> str:
|
||||
"""Generate user report (前回/進捗/今回/課題)"""
|
||||
|
||||
def on_session_end():
|
||||
"""Hook for session end (checkpoint save)"""
|
||||
# 1. write_memory("last_session", summary)
|
||||
# 2. write_memory("next_actions", todos)
|
||||
# 3. write_memory("pm_context", complete_state)
|
||||
```
|
||||
|
||||
### User Report Format
|
||||
```
|
||||
前回: [last session summary]
|
||||
進捗: [current progress status]
|
||||
今回: [planned next actions]
|
||||
課題: [blockers or issues]
|
||||
```
|
||||
|
||||
### Integration Points
|
||||
- Hook into Claude Code session start
|
||||
- Read memories using memory_ops
|
||||
- Generate human-readable report
|
||||
- Handle missing or corrupted memory
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
pytest tests/test_session_lifecycle.py -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3️⃣ pdca_engine.py Implementation
|
||||
|
||||
### Purpose
|
||||
Automate PDCA cycle execution with documentation generation.
|
||||
|
||||
### Key Functions
|
||||
|
||||
```python
|
||||
# superclaude/Core/pdca_engine.py
|
||||
|
||||
class PDCAEngine:
|
||||
"""PDCA cycle automation"""
|
||||
|
||||
def plan_phase(goal: str):
|
||||
"""Generate hypothesis (仮説)"""
|
||||
# 1. write_memory("plan", goal)
|
||||
# 2. Create docs/temp/hypothesis-YYYY-MM-DD.md
|
||||
|
||||
def do_phase():
|
||||
"""Track experimentation (実験)"""
|
||||
# 1. TodoWrite tracking
|
||||
# 2. write_memory("checkpoint", progress) every 30min
|
||||
# 3. Update docs/temp/experiment-YYYY-MM-DD.md
|
||||
|
||||
def check_phase():
|
||||
"""Self-evaluation (評価)"""
|
||||
# 1. think_about_task_adherence()
|
||||
# 2. think_about_whether_you_are_done()
|
||||
# 3. Create docs/temp/lessons-YYYY-MM-DD.md
|
||||
|
||||
def act_phase():
|
||||
"""Knowledge extraction (改善)"""
|
||||
# 1. Success → docs/patterns/[pattern-name].md
|
||||
# 2. Failure → docs/mistakes/mistake-YYYY-MM-DD.md
|
||||
# 3. Update CLAUDE.md if global pattern
|
||||
```
|
||||
|
||||
### Documentation Templates
|
||||
|
||||
**hypothesis-template.md**:
|
||||
```markdown
|
||||
# Hypothesis: [Goal Description]
|
||||
|
||||
Date: YYYY-MM-DD
|
||||
Status: Planning
|
||||
|
||||
## Goal
|
||||
What are we trying to accomplish?
|
||||
|
||||
## Approach
|
||||
How will we implement this?
|
||||
|
||||
## Success Criteria
|
||||
How do we know when we're done?
|
||||
|
||||
## Potential Risks
|
||||
What could go wrong?
|
||||
```
|
||||
|
||||
**experiment-template.md**:
|
||||
```markdown
|
||||
# Experiment Log: [Implementation Name]
|
||||
|
||||
Date: YYYY-MM-DD
|
||||
Status: In Progress
|
||||
|
||||
## Implementation Steps
|
||||
- [ ] Step 1
|
||||
- [ ] Step 2
|
||||
|
||||
## Errors Encountered
|
||||
- Error 1: Description, solution
|
||||
|
||||
## Solutions Applied
|
||||
- Solution 1: Description, result
|
||||
|
||||
## Checkpoint Saves
|
||||
- 10:00: [progress snapshot]
|
||||
- 10:30: [progress snapshot]
|
||||
```
|
||||
|
||||
### Integration Points
|
||||
- Create docs/ directory templates
|
||||
- Integrate with TodoWrite
|
||||
- Call Serena MCP think operations
|
||||
- Generate documentation files
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
pytest tests/test_pdca_engine.py -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔌 Phase 3: Serena MCP Integration
|
||||
|
||||
### Prerequisites
|
||||
```bash
|
||||
# Install Serena MCP server
|
||||
# See: docs/troubleshooting/serena-installation.md
|
||||
```
|
||||
|
||||
### Configuration
|
||||
```json
|
||||
// ~/.claude/.claude.json
|
||||
{
|
||||
"mcpServers": {
|
||||
"serena": {
|
||||
"command": "uv",
|
||||
"args": ["run", "serena-mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Memory Structure
|
||||
```json
|
||||
{
|
||||
"pm_context": {
|
||||
"project": "SuperClaude_Framework",
|
||||
"current_phase": "Phase 2",
|
||||
"architecture": "Context-Oriented Configuration",
|
||||
"patterns": ["PDCA Cycle", "Session Lifecycle"]
|
||||
},
|
||||
"last_session": {
|
||||
"date": "2025-10-14",
|
||||
"accomplished": ["Phase 1 complete"],
|
||||
"issues": ["Serena MCP not configured"],
|
||||
"learned": ["Session Lifecycle pattern"]
|
||||
},
|
||||
"next_actions": [
|
||||
"Implement session_lifecycle.py",
|
||||
"Configure Serena MCP",
|
||||
"Test memory operations"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Testing Serena Connection
|
||||
```bash
|
||||
# Test memory operations
|
||||
python -m SuperClaude.Core.memory_ops --test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 Phase 4: Documentation Strategy
|
||||
|
||||
### Directory Structure
|
||||
```
|
||||
docs/
|
||||
├── temp/ # Temporary (7-day lifecycle)
|
||||
│ ├── hypothesis-YYYY-MM-DD.md
|
||||
│ ├── experiment-YYYY-MM-DD.md
|
||||
│ └── lessons-YYYY-MM-DD.md
|
||||
├── patterns/ # Formal patterns (永久保存)
|
||||
│ └── [pattern-name].md
|
||||
└── mistakes/ # Mistake records (永久保存)
|
||||
└── mistake-YYYY-MM-DD.md
|
||||
```
|
||||
|
||||
### Lifecycle Automation
|
||||
```bash
|
||||
# Create cleanup script
|
||||
scripts/cleanup_temp_docs.sh
|
||||
|
||||
# Run daily via cron
|
||||
0 0 * * * /path/to/scripts/cleanup_temp_docs.sh
|
||||
```
|
||||
|
||||
### Migration Scripts
|
||||
```bash
|
||||
# Migrate successful experiments to patterns
|
||||
python scripts/migrate_to_patterns.py
|
||||
|
||||
# Migrate failures to mistakes
|
||||
python scripts/migrate_to_mistakes.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Phase 5: Auto-Activation (Research Needed)
|
||||
|
||||
### Research Questions
|
||||
1. How does Claude Code handle initialization?
|
||||
2. Are there plugin hooks available?
|
||||
3. Can we intercept session start events?
|
||||
|
||||
### Implementation Plan (TBD)
|
||||
Once research complete, implement auto-activation hooks:
|
||||
|
||||
```python
|
||||
# superclaude/Core/auto_activation.py (future)
|
||||
|
||||
def on_claude_code_start():
|
||||
"""Auto-activate PM Agent at session start"""
|
||||
session_lifecycle.on_session_start()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Implementation Checklist
|
||||
|
||||
### Phase 2: Core Implementation
|
||||
- [ ] Implement `memory_ops.py`
|
||||
- [ ] Write unit tests for memory_ops
|
||||
- [ ] Implement `session_lifecycle.py`
|
||||
- [ ] Write unit tests for session_lifecycle
|
||||
- [ ] Implement `pdca_engine.py`
|
||||
- [ ] Write unit tests for pdca_engine
|
||||
- [ ] Integration testing
|
||||
|
||||
### Phase 3: Serena MCP
|
||||
- [ ] Install Serena MCP server
|
||||
- [ ] Configure `.claude.json`
|
||||
- [ ] Test memory operations
|
||||
- [ ] Test think operations
|
||||
- [ ] Test cross-session persistence
|
||||
|
||||
### Phase 4: Documentation Strategy
|
||||
- [ ] Create `docs/temp/` template
|
||||
- [ ] Create `docs/patterns/` template
|
||||
- [ ] Create `docs/mistakes/` template
|
||||
- [ ] Implement lifecycle automation
|
||||
- [ ] Create migration scripts
|
||||
|
||||
### Phase 5: Auto-Activation
|
||||
- [ ] Research Claude Code hooks
|
||||
- [ ] Design auto-activation system
|
||||
- [ ] Implement auto-activation
|
||||
- [ ] Test session start behavior
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing Strategy
|
||||
|
||||
### Unit Tests
|
||||
```bash
|
||||
tests/
|
||||
├── test_memory_ops.py # Memory operations
|
||||
├── test_session_lifecycle.py # Session management
|
||||
└── test_pdca_engine.py # PDCA automation
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
```bash
|
||||
tests/integration/
|
||||
├── test_pm_agent_flow.py # End-to-end PM Agent
|
||||
├── test_serena_integration.py # Serena MCP integration
|
||||
└── test_cross_session.py # Session persistence
|
||||
```
|
||||
|
||||
### Manual Testing
|
||||
1. Start new session → Verify context restoration
|
||||
2. Work on task → Verify checkpoint saves
|
||||
3. End session → Verify state preservation
|
||||
4. Restart → Verify seamless resumption
|
||||
|
||||
---
|
||||
|
||||
## 📊 Success Criteria
|
||||
|
||||
### Functional
|
||||
- [ ] PM Agent activates at session start
|
||||
- [ ] Context restores from memory
|
||||
- [ ] User report generates correctly
|
||||
- [ ] PDCA cycle executes automatically
|
||||
- [ ] Documentation strategy works
|
||||
|
||||
### Performance
|
||||
- [ ] Session start delay <500ms
|
||||
- [ ] Memory operations <100ms
|
||||
- [ ] Context restoration reliable (>99%)
|
||||
|
||||
### Quality
|
||||
- [ ] Test coverage >90%
|
||||
- [ ] No regression in existing features
|
||||
- [ ] Documentation complete
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**"Serena MCP not connecting"**
|
||||
- Check server installation
|
||||
- Verify `.claude.json` configuration
|
||||
- Test connection: `claude mcp list`
|
||||
|
||||
**"Memory operations failing"**
|
||||
- Check network connection
|
||||
- Verify Serena server running
|
||||
- Check error logs
|
||||
|
||||
**"Context not restoring"**
|
||||
- Verify memory structure
|
||||
- Check `pm_context` exists
|
||||
- Test with fresh memory
|
||||
|
||||
---
|
||||
|
||||
## 📚 References
|
||||
|
||||
- [ARCHITECTURE.md](./ARCHITECTURE.md) - System architecture
|
||||
- [ROADMAP.md](./ROADMAP.md) - Development roadmap
|
||||
- [pm-agent-implementation-status.md](../pm-agent-implementation-status.md) - Status tracking
|
||||
- [Commands/pm.md](../../superclaude/Commands/pm.md) - PM Agent command
|
||||
- [Agents/pm-agent.md](../../superclaude/Agents/pm-agent.md) - PM Agent persona
|
||||
|
||||
---
|
||||
|
||||
**Last Verified**: 2025-10-14
|
||||
**Next Review**: 2025-10-21 (1 week)
|
||||
**Version**: 4.1.5
|
||||
368
docs/Development/project-structure-understanding.md
Normal file
368
docs/Development/project-structure-understanding.md
Normal file
@@ -0,0 +1,368 @@
|
||||
# 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管理下で開発
|
||||
|
||||
これで**何百回も同じ説明をしなくて済む**ようになる。
|
||||
163
docs/Development/tasks/current-tasks.md
Normal file
163
docs/Development/tasks/current-tasks.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# Current Tasks - SuperClaude Framework
|
||||
|
||||
> **Last Updated**: 2025-10-14
|
||||
> **Session**: PM Agent Enhancement & PDCA Integration
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Main Objective
|
||||
|
||||
**PM Agent を完璧な自律的オーケストレーターに進化させる**
|
||||
|
||||
- 繰り返し指示を不要にする
|
||||
- 同じミスを繰り返さない
|
||||
- セッション間で学習内容を保持
|
||||
- 自律的にPDCAサイクルを回す
|
||||
|
||||
---
|
||||
|
||||
## ✅ Completed Tasks
|
||||
|
||||
### Phase 1: ドキュメント基盤整備
|
||||
- [x] **PM Agent理想ワークフローをドキュメント化**
|
||||
- File: `docs/Development/pm-agent-ideal-workflow.md`
|
||||
- Content: 完璧なワークフロー（7フェーズ）
|
||||
- Purpose: 次回セッションで同じ説明を繰り返さない
|
||||
|
||||
- [x] **プロジェクト構造理解をドキュメント化**
|
||||
- File: `docs/Development/project-structure-understanding.md`
|
||||
- Content: Git管理とインストール後環境の区別
|
||||
- Purpose: 何百回も説明した内容を外部化
|
||||
|
||||
- [x] **インストールフロー理解をドキュメント化**
|
||||
- File: `docs/Development/installation-flow-understanding.md`
|
||||
- Content: CommandsComponent動作の完全理解
|
||||
- Source: `superclaude/commands/*.md` → `~/.claude/commands/sc/*.md`
|
||||
|
||||
- [x] **ディレクトリ構造作成**
|
||||
- `docs/Development/tasks/` - タスク管理
|
||||
- `docs/patterns/` - 成功パターン記録
|
||||
- `docs/mistakes/` - 失敗記録と防止策
|
||||
|
||||
---
|
||||
|
||||
## 🔄 In Progress
|
||||
|
||||
### Phase 2: 現状分析と改善提案
|
||||
|
||||
- [ ] **superclaude/commands/pm.md 現在の仕様確認**
|
||||
- Status: Pending
|
||||
- Action: ソースファイルを読んで現在の実装を理解
|
||||
- File: `superclaude/commands/pm.md`
|
||||
|
||||
- [ ] **~/.claude/commands/sc/pm.md 動作確認**
|
||||
- Status: Pending
|
||||
- Action: インストール後の実際の仕様確認（読むだけ）
|
||||
- File: `~/.claude/commands/sc/pm.md`
|
||||
|
||||
- [ ] **改善提案ドキュメント作成**
|
||||
- Status: Pending
|
||||
- Action: 仮説ドキュメント作成
|
||||
- File: `docs/Development/hypothesis-pm-enhancement-2025-10-14.md`
|
||||
- Content:
|
||||
- 現状の問題点（ドキュメント寄り、PMO機能不足）
|
||||
- 改善案（自律的PDCA、自己評価）
|
||||
- 実装方針
|
||||
- 期待される効果
|
||||
|
||||
---
|
||||
|
||||
## 📋 Pending Tasks
|
||||
|
||||
### Phase 3: 実装修正
|
||||
|
||||
- [ ] **superclaude/commands/pm.md 修正**
|
||||
- Content:
|
||||
- PDCA自動実行の強化
|
||||
- docs/ディレクトリ活用の明示
|
||||
- 自己評価ステップの追加
|
||||
- エラー時再学習フローの追加
|
||||
- PMO機能（重複検出、共通化提案）
|
||||
|
||||
- [ ] **MODE_Task_Management.md 修正**
|
||||
- Serenaメモリー → docs/統合
|
||||
- タスク管理ドキュメント連携
|
||||
|
||||
### Phase 4: テスト・検証
|
||||
|
||||
- [ ] **テスト追加**
|
||||
- File: `tests/test_pm_enhanced.py`
|
||||
- Coverage: PDCA実行、自己評価、学習記録
|
||||
|
||||
- [ ] **動作確認**
|
||||
- 開発版インストール: `SuperClaude install --dev`
|
||||
- 実際のワークフロー実行
|
||||
- Before/After比較
|
||||
|
||||
### Phase 5: 学習記録
|
||||
|
||||
- [ ] **成功パターン記録**
|
||||
- File: `docs/patterns/pm-autonomous-workflow.md`
|
||||
- Content: 自律的PDCAパターンの詳細
|
||||
|
||||
- [ ] **失敗記録（必要時）**
|
||||
- File: `docs/mistakes/mistake-2025-10-14.md`
|
||||
- Content: 遭遇したエラーと防止策
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Success Criteria
|
||||
|
||||
### 定量的指標
|
||||
- [ ] 繰り返し指示 50%削減
|
||||
- [ ] 同じミス再発率 80%削減
|
||||
- [ ] セッション復元時間 <30秒
|
||||
|
||||
### 定性的指標
|
||||
- [ ] 「前回の続きから」だけで再開可能
|
||||
- [ ] 過去のミスを自動的に回避
|
||||
- [ ] 公式ドキュメント参照が自動化
|
||||
- [ ] 実装→テスト→検証が自律的に回る
|
||||
|
||||
---
|
||||
|
||||
## 📝 Notes
|
||||
|
||||
### 重要な学び
|
||||
- **Git管理の区別が最重要**
|
||||
- このプロジェクト（Git管理）で変更
|
||||
- `~/.claude/`（Git管理外）は読むだけ
|
||||
- テスト時のバックアップ・復元必須
|
||||
|
||||
- **ドキュメント駆動開発**
|
||||
- 理解 → docs/Development/ に記録
|
||||
- 仮説 → hypothesis-*.md
|
||||
- 実験 → experiment-*.md
|
||||
- 成功 → docs/patterns/
|
||||
- 失敗 → docs/mistakes/
|
||||
|
||||
- **インストールフロー**
|
||||
- Source: `superclaude/commands/*.md`
|
||||
- Installer: `setup/components/commands.py`
|
||||
- Target: `~/.claude/commands/sc/*.md`
|
||||
|
||||
### ブロッカー
|
||||
- なし（現時点）
|
||||
|
||||
### 次回セッション用のメモ
|
||||
1. このファイル（current-tasks.md）を最初に読む
|
||||
2. Completedセクションで進捗確認
|
||||
3. In Progressから再開
|
||||
4. 新しい学びを適切なドキュメントに記録
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Related Documentation
|
||||
|
||||
- [PM Agent理想ワークフロー](../pm-agent-ideal-workflow.md)
|
||||
- [プロジェクト構造理解](../project-structure-understanding.md)
|
||||
- [インストールフロー理解](../installation-flow-understanding.md)
|
||||
|
||||
---
|
||||
|
||||
**次のステップ**: `superclaude/commands/pm.md` を読んで現在の仕様を確認する
|
||||
Reference in New Issue
Block a user