External/SuperClaude
1
0
Fork 0
mirror of https://github.com/SuperClaude-Org/SuperClaude_Framework.git synced 2025-12-25 13:46:35 +00:00
Code Issues Packages Projects Releases Wiki Activity
SuperClaude/docs/User-Guide-jp/session-management.md
kazuki nakai 050d5ea2ab
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>
2025-10-14 08:47:09 +05:30

18 KiB
Raw Blame History

セッション管理ガイド

SuperClaude は、Serena MCP サーバーを通じて永続的なセッション管理を提供し、Claude Code の会話全体にわたる真のコンテキスト保存と長期的なプロジェクト継続性を実現します。

永続メモリを使用したコアセッションコマンド

/sc:load- 永続メモリによるコンテキストの読み込み

目的: 以前のセッションからのプロジェクトコンテキストと永続メモリを使用してセッションを初期化します。MCP
統合: Serena MCP をトリガーして、保存されたプロジェクトメモリを読み取ります。
構文:/sc:load [project_path]

何が起こるのですか：

  • Serena MCPは以前のセッションから永続メモリファイルを読み取ります
  • プロジェクトのコンテキストは保存されたメモリから復元されます
  • 過去の決定、パターン、進捗状況が読み込まれます
  • セッション状態は履歴コンテキストで初期化されます

ユースケース:

# Load existing project context from persistent memory
/sc:load src/

# Resume specific project work with full history
/sc:load "authentication-system"

# Initialize with codebase analysis and previous insights
/sc:load . --analyze

/sc:save- メモリへのセッションの永続性

目的: 現在のセッション状態と決定を永続メモリ
MCP に保存します。統合: Serena MCP をトリガーしてメモリ ファイルに書き込みます。
構文:/sc:save "session_description"

何が起こるのですか：

  • 現在の状況と決定はセレナのメモリに書き込まれます
  • プロジェクトの状態と進捗は会話を通じて維持されます
  • 重要な洞察とパターンは将来のセッションのために保存されます
  • セッション概要はタイムスタンプ付きで作成され、検索に利用できます

ユースケース:

# Save completed feature work for future reference
/sc:save "user authentication implemented with JWT"

# Checkpoint during complex work
/sc:save "API design phase complete, ready for implementation"

# Store architectural decisions permanently
/sc:save "microservices architecture decided, service boundaries defined"

/sc:reflect- メモリコンテキストによる進捗状況の評価

目的: 保存されたメモリに対して現在の進行状況を分析し、セッションの完全性を検証する
MCP 統合: Serena MCP を使用して、保存されたメモリと現在の状態を比較する
構文:/sc:reflect [--scope project|session]

何が起こるのですか：

  • セレナMCPは過去の記憶と現在の文脈を読み取ります
  • 進捗は保存された目標とマイルストーンに対して評価されます
  • 歴史的背景に基づいてギャップと次のステップが特定される
  • セッションの完全性はプロジェクトメモリに対して検証されます

ユースケース:

# Assess project progress against stored milestones
/sc:reflect --scope project

# Validate current session completeness
/sc:reflect

# Check if ready to move to next phase based on memory
/sc:reflect --scope session

永続メモリアーキテクチャ

Serena MCP が真の永続性を実現する方法

メモリストレージ:

  • 構造化メモリファイルとして保存されるセッションコンテキスト
  • プロジェクトの決定とアーキテクチャパターンは永久に保存されます
  • コード分​​析の結果と洞察は会話を通じて保持されます
  • 進捗状況の追跡とマイルストーンのデータは長期にわたって維持されます

セッション間の継続性:

  • 以前のセッションのコンテキストが新しい会話で自動的に利用可能
  • 決定と根拠は会話を通じて保存され、アクセス可能
  • 過去のパターンと解決策からの学習を維持
  • 一貫したプロジェクト理解が永久に維持される

メモリタイプ:

  • プロジェクトの思い出：長期プロジェクトの文脈とアーキテクチャ
  • セッションの記憶：具体的な会話の結果と決定
  • パターンメモリ：再利用可能なソリューションとアーキテクチャパターン
  • 進捗の思い出：マイルストーンの追跡と完了ステータス

永続性を備えたセッションライフサイクルパターン

新しいプロジェクトの初期化

# 1. Start fresh project
/sc:brainstorm "e-commerce platform requirements"

# 2. Save initial decisions to persistent memory
/sc:save "project scope and requirements defined"

# 3. Begin implementation planning
/sc:workflow "user authentication system"

# 4. Save architectural decisions permanently
/sc:save "auth architecture: JWT + refresh tokens + rate limiting"

既存の作業の再開（クロス会話）

# 1. Load previous context from persistent memory
/sc:load "e-commerce-project"

# 2. Assess current state against stored progress
/sc:reflect --scope project  

# 3. Continue with next phase using stored context
/sc:implement "payment processing integration"

# 4. Save progress checkpoint to memory
/sc:save "payment system integrated with Stripe API"

長期プロジェクト管理

# Weekly checkpoint pattern with persistence
/sc:load project-name
/sc:reflect --scope project
# ... work on features ...
/sc:save "week N progress: features X, Y, Z completed"

# Phase completion pattern with memory
/sc:reflect --scope project
/sc:save "Phase 1 complete: core authentication and user management"
/sc:workflow "Phase 2: payment and order processing"

クロス会話の継続性

粘り強く新しい会話を始める

新しい Claude Code 会話を開始すると、永続メモリ システムによって次のことが可能になります。

  1. 自動コンテキスト復元

    /sc:load project-name
# Automatically restores all previous context, decisions, and progress

  2. 進歩の継続

    • 以前のセッションの決定はすぐに利用可能
    • アーキテクチャパターンとコードの洞察は保存されます
    • プロジェクトの履歴と根拠が維持される

  3. インテリジェントなコンテキスト構築

    • Serena MCPは、現在の作業に基づいて関連するメモリを提供します
    • 過去のソリューションとパターンが新しい実装に影響を与える
    • プロジェクトの進捗状況が追跡され、理解される

メモリ最適化

有効なメモリ使用量:

  • 説明的かつ検索可能なメモリ名を使用する
  • プロジェクトのフェーズとタイムスタンプのコンテキストを含める
  • 特定の機能やアーキテクチャ上の決定を参照する
  • 将来の検索を直感的にする

記憶内容戦略：

  • 結果だけでなく、意思決定と根拠も保存する
  • 検討した代替アプローチを含める
  • 統合パターンと依存関係を文書化する
  • 学習内容と洞察を将来の参考のために保存する

メモリライフサイクル管理:

  • 古くなったメモリの定期的なクリーンアップ
  • 関連するセッション記憶の統合
  • 完了したプロジェクトフェーズのアーカイブ
  • 時代遅れのアーキテクチャ上の決定の削減

永続セッションのベストプラクティス

セッション開始プロトコル

  1. /sc:load既存のプロジェクトの場合は常に
  2. /sc:reflect記憶から現在の状態を理解するために使用する
  3. 永続的なコンテキストと保存されたパターンに基づいて作業を計画する
  4. 過去の決定とアーキテクチャの選択に基づいて構築する

セッション終了プロトコル

  1. /sc:reflect保存された目標に対する完全性を評価するために使用します
  2. 重要な決定を/sc:save将来のセッションのために保存する
  3. 次のステップと未解決の質問を記憶に記録する
  4. 将来のシームレスな継続のためにコンテキストを保存する

記憶品質の維持

  • 簡単に思い出せるように、分かりやすく説明的なメモリ名を使用する
  • 決定事項と代替アプローチに関する背景情報を含める
  • 特定のコードの場所とパターンを参照する
  • セッション間でメモリ構造の一貫性を維持する

他のSuperClaude機能との統合

MCP サーバー調整

  • Serena MCP : 永続メモリインフラストラクチャを提供します
  • シーケンシャルMCP : 保存されたメモリを使用して複雑な分析を強化します
  • Context7 MCP : 保存されたパターンとドキュメント化のアプローチを参照します
  • Morphllm MCP : 保存されたリファクタリングパターンを一貫して適用します

エージェントとメモリの連携

  • エージェントは強化されたコンテキストのために永続的なメモリにアクセスします
  • 以前の専門家の決定は保存され、参照されます
  • 共有メモリを介したセッション間エージェント調整
  • プロジェクトの履歴に基づいた一貫した専門家の推奨

永続性を備えたコマンド統合

  • すべての/sc:コマンドは永続的なコンテキストを参照し、そのコンテキストに基づいて構築できます。
  • 以前のコマンド出力と決定はセッション間で利用可能
  • ワークフローパターンは保存され、再利用できる
  • 実装履歴は将来の指揮決定を導く

永続セッションのトラブルシューティング

よくある問題

メモリが読み込まれません:

  • Serena MCP が正しく構成され、実行されていることを確認します。
  • メモリファイルの権限とアクセス可能性を確認する
  • プロジェクトの命名規則の一貫性を確保する
  • メモリファイルの整合性とフォーマットを検証する

セッション間のコンテキスト損失:

  • /sc:saveセッションを終了する前に必ず使用してください
  • 簡単に検索できるように、わかりやすいメモリ名を使用する
  • メモリの完全性を定期的/sc:reflectに検証する
  • 重要なメモリファイルを定期的にバックアップする

メモリの競合:

  • バージョン管理にはタイムスタンプ付きのメモリ名を使用する
  • 古くなった記憶の定期的なクリーンアップ
  • プロジェクトとセッションのメモリを明確に分離
  • セッション間で一貫したメモリ命名規則

クイックフィックス

セッション状態をリセット:

/sc:load --fresh  # Start without previous context
/sc:reflect       # Assess current state

メモリクリーンアップ:

/sc:reflect --cleanup  # Remove obsolete memories
/sc:save --consolidate # Merge related memories

コンテキスト回復:

/sc:load --recent     # Load most recent memories
/sc:reflect --repair  # Identify and fix context gaps

高度な永続セッションパターン

複数フェーズのプロジェクト

  • 整理のためにフェーズ固有のメモリ命名を使用する
  • フェーズ全体でアーキテクチャ上の決定の継続性を維持する
  • 永続メモリによるクロスフェーズ依存関係の追跡
  • 歴史的背景を考慮した漸進的な複雑性管理

チームコラボレーション

  • 共有メモリの規則と命名規則
  • チームのコンテキストにおける意思決定根拠の保存
  • すべてのチームメンバーがアクセスできる統合パターンのドキュメント
  • メモリを介した一貫したコードスタイルとアーキテクチャの適用

長期メンテナンス

  • 完了したプロジェクトのメモリアーカイブ戦略
  • 蓄積された記憶によるパターンライブラリの開発
  • 時間をかけて構築された再利用可能なソリューションドキュメント
  • 永続的なメモリ蓄積による知識ベースの構築

永続セッション管理の主な利点

プロジェクトの継続性

  • 複数の会話にわたるシームレスな作業継続
  • Claude Codeセッション間でコンテキストが失われることはありません
  • 保存されたアーキテクチャ上の決定と技術的根拠
  • 長期的なプロジェクトの進捗追跡

生産性の向上

  • プロジェクトのコンテキストを再度説明する必要性が減少
  • 起動時間が速く、作業を継続できる
  • 過去の洞察とパターンに基づいて
  • 累積的なプロジェクト知識の成長

品質の一貫性

  • セッション間で一貫したアーキテクチャパターン
  • コード品質の決定と標準の保持
  • 再利用可能なソリューションとベストプラクティス
  • 技術的負債の認識を維持

重要なポイント: Serena MCP によるセッション管理により、SuperClaude は単一の会話の支援から永続的なプロジェクト パートナーシップへと変わり、すべての開発フェーズと Claude Code の会話にわたってコンテキスト、決定、学習が維持されます。