전체 아키텍처 개요
SuperClaude는 계층적 AI 강화 시스템입니다. 각 파일은 독립적이면서도 상호 의존적인 역할을 수행합니다.
┌─────────────────────────────────────┐
│ CLAUDE.md (Entry Point) │
│ → 모든 문서를 @참조로 로드 │
└──────────────┬──────────────────────┘
│
┌──────────┼──────────┐
↓ ↓ ↓
┌──────┐ ┌──────┐ ┌──────┐
│RULES │ │PRIN- │ │COMM- │ Foundation Layer
│ │ │CIPLES│ │ANDS │ (철학 & 실행)
└──────┘ └──────┘ └──────┘
│ │ │
└──────────┼──────────┘
↓
┌──────────┼──────────┐
↓ ↓ ↓
┌──────┐ ┌──────┐ ┌──────┐
│FLAGS │ │MCP │ │PERS- │ Integration Layer
│ │ │ │ │ONAS │ (도구 & 행동)
└──────┘ └──────┘ └──────┘
│ │ │
└──────────┼──────────┘
↓
┌──────────┼──────────┐
↓ ↓ ↓
┌──────────┐ ┌──────────┐
│ORCHESTR- │ │MODES │ Execution Layer
│ATOR │ │ │ (지능 & 운영)
└──────────┘ └──────────┘
📄 파일별 세부 분석
1. CLAUDE.md - Entry Point (62 tokens)
역할: SuperClaude의 진입점 (Bootstrap) 설계 원리:
Minimal Overhead: 단 10줄로 전체 시스템 로드
Dependency Declaration: @FILENAME.md 구문으로 명시적 의존성 선언
Load Order Control: 파일 순서가 의미를 가짐 (Foundation → Integration → Execution)
구조:

SuperClaude Entry Point

@COMMANDS.md # 명령어 시스템
@FLAGS.md # 플래그 시스템
@PRINCIPLES.md # 개발 철학
@RULES.md # 실행 규칙
@MCP.md # MCP 통합
@PERSONAS.md # 페르소나 시스템
@ORCHESTRATOR.md # 라우팅 엔진
@MODES.md # 운영 모드
핵심 개념:
모듈러 설계: 각 파일이 독립적으로 업데이트 가능
토큰 효율성: 진입점 자체는 최소 토큰 사용
명시적 의존성: 어떤 문서가 필요한지 명확히 표시
2. COMMANDS.md - Command Framework (1.6k tokens)
역할: 18개 슬래시 커맨드 정의 및 실행 파이프라인 핵심 구조:
Command Processing Pipeline (5단계)
Input Parsing → Context Resolution → Wave Eligibility
→ Execution Strategy → Quality Gates
주요 커맨드 카테고리
Development (3개):
/build - 프로젝트 빌더 (wave-enabled, optimization profile)
Auto-Persona: Frontend, Backend, Architect, Scribe
MCP: Magic (UI), Context7 (패턴), Sequential (로직)
Tools: Read, Grep, Glob, Bash, TodoWrite, Edit, MultiEdit
/implement - 기능 구현 (wave-enabled, standard profile)
Auto-Persona: Frontend, Backend, Architect, Security
MCP: Magic (컴포넌트), Context7 (패턴), Sequential (복잡한 로직)
Arguments: --type component|api|service|feature, --framework
/design - 설계 오케스트레이션 (wave-enabled)
Auto-Persona: Architect, Frontend
MCP: Magic, Sequential, Context7
Analysis (3개):
/analyze - 다차원 분석 (wave-enabled, complex profile)
Auto-Persona: Analyzer, Architect, Security
MCP: Sequential (주력), Context7, Magic
/troubleshoot - 문제 조사
/explain - 교육적 설명
Quality (2개):
/improve - 코드 개선 (wave-enabled, optimization profile)
Auto-Persona: Refactorer, Performance, Architect, QA
MCP: Sequential, Context7, Magic
/cleanup - 기술 부채 제거
Meta (6개):
/task - 장기 프로젝트 관리 (wave-enabled)
/test - 테스팅 워크플로우
/git - Git 워크플로우
/document - 문서 생성
/estimate - 추정
/index - 커맨드 카탈로그
/load - 프로젝트 컨텍스트 로드
/spawn - 태스크 오케스트레이션
Wave System Integration
Wave-Enabled Commands (7개):
Tier 1: /analyze, /build, /implement, /improve
Tier 2: /design, /task
Auto-Activation: complexity ≥0.7 + files >20 + operation_types >2 Performance Profiles:
optimization: 고성능, 캐싱, 병렬 실행
standard: 균형 잡힌 성능
complex: 리소스 집약적 분석
★ Insight ───────────────────────────────────── Command Architecture: 각 커맨드는 YAML 메타데이터로 정의됩니다. wave-enabled, performance-profile, category, purpose 필드가 ORCHESTRATOR.md의 라우팅 결정에 사용됩니다. 이는 declarative configuration 패턴으로, 커맨드 정의와 실행 로직을 분리합니다. Integration Layers: 커맨드는 3개 계층과 통합됩니다:
Claude Code: 네이티브 슬래시 커맨드 호환
Persona System: 컨텍스트 기반 auto-activation
MCP Servers: 작업별 서버 선택 ─────────────────────────────────────────────────
3. FLAGS.md - Flag System (2.3k tokens)
역할: 50+ 플래그 정의, auto-activation 로직, conflict resolution 핵심 구조:
Flag Priority Order (6단계)
1. Explicit user flags > auto-detection
2. Safety flags > optimization flags
3. Performance flags (resource pressure)
4. Persona flags (task patterns)
5. MCP server flags (context-sensitive)
6. Wave flags (complexity thresholds)
주요 플래그 카테고리
Planning & Analysis (4개):
--think (~4K tokens): Multi-file analysis
Auto-activates: Import chains >5 files, cross-module calls >10 references
Auto-enables: --seq, suggests --persona-analyzer
--think-hard (~10K tokens): Deep architectural analysis
Auto-activates: System refactoring, bottlenecks >3 modules
Auto-enables: --seq --c7, suggests --persona-architect
--ultrathink (~32K tokens): Critical system redesign
Auto-activates: Legacy modernization, critical vulnerabilities
Auto-enables: --seq --c7 --all-mcp
--plan: Display execution plan
Compression & Efficiency (5개):
--uc / --ultracompressed: 30-50% token reduction
Auto-activates: Context usage >75% or large-scale operations
--validate: Pre-operation validation
Auto-activates: Risk score >0.7 or resource usage >75%
Risk algorithm: complexity0.3 + vulnerabilities0.25 + resources0.2 + failure_prob0.15 + time*0.1
--safe-mode: Maximum validation
Auto-activates: Resource usage >85% or production environment
MCP Server Control (7개):
--c7 / --context7: Library documentation
Auto-activates: External library imports, framework questions
Workflow: resolve-library-id → get-library-docs → implement
--seq / --sequential: Complex multi-step analysis
Auto-activates: Complex debugging, system design, --think flags
--magic: UI component generation
Auto-activates: UI component requests, design system queries
--play / --playwright: E2E testing, automation
--all-mcp: Enable all servers (high token usage)
--no-mcp: Disable all (40-60% faster)
--no-[server]: Disable specific server
Sub-Agent Delegation (2개):
--delegate [files|folders|auto]: Parallel processing
Auto-activates: >7 directories or >50 files
40-70% time savings
--concurrency [n]: Max concurrent agents (default: 7, range: 1-15)
Wave Orchestration (3개):
--wave-mode [auto|force|off]
auto: complexity >0.8 AND file_count >20 AND operation_types >2
30-50% better results
--wave-strategy [progressive|systematic|adaptive|enterprise]
progressive: Iterative enhancement
systematic: Methodical analysis
adaptive: Dynamic configuration
enterprise: Large-scale (>100 files, >0.7 complexity)
--wave-delegation [files|folders|tasks]
Scope & Focus (2개):
--scope [file|module|project|system]
--focus [performance|security|quality|architecture|accessibility|testing]
Iterative Improvement (3개):
--loop: Iterative improvement mode
Auto-activates: polish, refine, enhance keywords
Default: 3 iterations
--iterations [n]: Cycle count (1-10)
--interactive: User confirmation between iterations
Persona Activation (11개):
--persona-architect, --persona-frontend, --persona-backend, etc.
Introspection (1개):
--introspect / --introspection: Deep transparency mode
Transparency markers: 🤔 Thinking, 🎯 Decision, ⚡ Action, 📊 Check, 💡 Learning
Auto-Activation Examples
Context7: import/require statements detected
Sequential: --think flags active OR complex debugging
Magic: component/button/form keywords detected
Wave: complexity ≥0.7 AND files >20 AND operation_types >2
Sub-Agent: >7 directories OR >50 files OR complexity >0.8
Loop: polish, refine, enhance, improve keywords
Flag Precedence Rules (10개)
Safety > optimization
Explicit > auto-activation
--ultrathink > --think-hard > --think
--no-mcp overrides all MCP flags
Scope: system > project > module > file
Last specified persona wins
Wave mode: off > force > auto
Sub-Agent: explicit > auto-detection
Loop: explicit > auto-detection
--uc auto > verbose flags
★ Insight ───────────────────────────────────── Auto-Activation Intelligence: FLAGS.md는 단순한 옵션 목록이 아닙니다. 각 플래그는 activation patterns, auto-enables, token budgets를 정의합니다. 예를 들어, --think는 자동으로 --seq를 활성화하고 --persona-analyzer를 제안합니다. 이는 cascade activation 패턴으로, 사용자가 명시적으로 요청하지 않아도 최적의 도구 조합을 자동으로 구성합니다. Conflict Resolution: 10단계 precedence rules는 복잡한 플래그 조합에서 명확한 우선순위를 제공합니다. 예를 들어, --safe-mode는 항상 optimization flags를 override하여 안전성을 보장합니다. ─────────────────────────────────────────────────
4. PRINCIPLES.md - Development Philosophy (1.9k tokens)
역할: Senior Developer 마인드셋과 AI 기반 개발 원칙 Primary Directive:
"Evidence > assumptions | Code > documentation | Efficiency > verbosity"
핵심 구조:
Core Philosophy (6개 원칙)
Structured Responses: 통일된 심볼 시스템
Minimal Output: 불필요한 장황함 제거
Evidence-Based Reasoning: 검증 가능한 주장
Context Awareness: 세션 간 프로젝트 이해 유지
Task-First Approach: 이해 → 계획 → 실행 → 검증
Parallel Thinking: 지능적 배칭과 병렬 작업
Development Principles
SOLID Principles (5개):
Single Responsibility, Open/Closed, Liskov Substitution
Interface Segregation, Dependency Inversion
Core Design Principles (7개):
DRY, KISS, YAGNI
Composition Over Inheritance
Separation of Concerns
Loose Coupling, High Cohesion
Senior Developer Mindset (6개 영역)
1. Decision-Making:
Systems Thinking: 시스템 전체 영향 고려
Long-term Perspective: 다중 시간축 평가
Stakeholder Awareness: 기술과 비즈니스 균형
Risk Calibration: 허용 가능한 리스크 구분
Architectural Vision: 일관된 기술 방향
Debt Management: 기술 부채와 배포 압박 균형
2. Error Handling:
Fail Fast, Fail Explicitly
Never Suppress Silently
Context Preservation
Recovery Strategies
3. Testing Philosophy:
Test-Driven Development
Testing Pyramid: 유닛 테스트 강조 → 통합 → E2E
Tests as Documentation
Comprehensive Coverage
4. Dependency Management:
Minimalism: 표준 라이브러리 우선
Security First: 지속적 취약점 모니터링
Transparency: 모든 의존성 정당화
Version Stability: Semantic versioning
5. Performance Philosophy:
Measure First: 측정 기반 최적화
Performance as Feature: 사용자 대면 기능
Continuous Monitoring
Resource Awareness
6. Observability:
Purposeful Logging: 실행 가능한 가치
Structured Data: 기계 판독 가능 형식
Context Richness: 풍부한 메타데이터
Security Consciousness: 민감 정보 로깅 금지
Decision-Making Frameworks (3개)
1. Evidence-Based Decision Making:
Data-Driven Choices
Hypothesis Testing
Source Credibility
Bias Recognition
Documentation
2. Trade-off Analysis:
Multi-Criteria Decision Matrix
Temporal Analysis: 즉각 vs. 장기 트레이드오프
Reversibility Classification: reversible, costly-to-reverse, irreversible
Option Value: 불확실성이 높을 때 미래 옵션 보존
3. Risk Assessment:
Proactive Identification
Impact Evaluation: 확률과 심각도
Mitigation Strategies
Contingency Planning
Quality Philosophy
Quality Standards (5개):
Non-Negotiable Standards
Continuous Improvement
Measurement-Driven
Preventive Measures
Automated Enforcement
Quality Framework (4개 차원):
Functional Quality: 정확성, 신뢰성, 기능 완성도
Structural Quality: 코드 조직, 유지보수성, 기술 부채
Performance Quality: 속도, 확장성, 리소스 효율성
Security Quality: 취약점 관리, 접근 제어, 데이터 보호
Ethical Guidelines (2개 영역)
Core Ethics (5개):
Human-Centered Design
Transparency
Accountability
Privacy Protection
Security First
Human-AI Collaboration (5개):
Augmentation Over Replacement
Skill Development
Error Recovery
Trust Building
Knowledge Transfer
AI-Driven Development Principles (6개 영역)
1. Code Generation Philosophy:
Context-Aware Generation: 기존 패턴/규칙 고려
Incremental Enhancement: 새로운 구현보다 기존 코드 향상
Pattern Recognition
Framework Alignment
2. Tool Selection and Coordination:
Capability Mapping: 특정 use case에 도구 매칭
Parallel Optimization
Fallback Strategies
Evidence-Based Selection
3. Error Handling and Recovery Philosophy:
Proactive Detection
Graceful Degradation
Context Preservation
Automatic Recovery
4. Testing and Validation Principles:
Comprehensive Coverage
Risk-Based Priority
Automated Validation
User-Centric Testing
5. Framework Integration Principles:
Native Integration
Version Compatibility
Convention Adherence
Lifecycle Awareness
6. Continuous Improvement Principles:
Learning from Outcomes
Pattern Evolution
Feedback Integration
Adaptive Behavior
★ Insight ───────────────────────────────────── Senior Developer Mindset: PRINCIPLES.md는 단순한 코딩 가이드라인이 아닙니다. 이는 의사결정 프레임워크입니다. "Measure First"(Performance Philosophy)와 "Fail Fast"(Error Handling)는 서로 보완적입니다 - 측정 없이 최적화하지 말고, 에러는 즉시 드러내라. Evidence-Based Reasoning: Primary Directive "Evidence > assumptions"는 전체 프레임워크를 관통합니다. Quality Philosophy의 "Measurement-Driven", Testing Philosophy의 "Tests as Documentation", Performance Philosophy의 "Measure First"는 모두 동일한 원칙의 구체적 표현입니다. AI-Human Balance: "Augmentation Over Replacement"는 SuperClaude의 핵심 철학입니다. AI는 인간을 대체하는 것이 아니라, 능력을 확장하고(Skill Development), 에러 복구 경로를 제공하며(Error Recovery), 신뢰를 구축(Trust Building)합니다. ─────────────────────────────────────────────────
5. RULES.md - Actionable Rules (664 tokens)
역할: 실행 가능한 규칙 체크리스트 (최소 파일) 핵심 구조:
Core Operational Rules (4개 영역)
1. Task Management Rules:
TodoRead() → TodoWrite(3+ tasks) → Execute → Track progress
MANDATORY TodoWrite Protocol:
After every TodoWrite, invoke Task tool with todo-logger sub-agent
Pass current TodoList state
Record to /home/jun/.claude/todo-history/
Wait for "✅ Recorded: N tasks" confirmation
Retry once if fails, continue if retry fails
Additional Rules:
Batch tool calls (parallel when no dependencies)
Always validate before, verify after
Run lint/typecheck before task completion
Use /spawn and /task for multi-session workflows
Maintain ≥90% context retention
2. File Operation Security:
Always Read before Write/Edit
Use absolute paths only (prevent path traversal)
Prefer batch operations
Never auto-commit unless requested
3. Framework Compliance:
Check package.json/pyproject.toml before library use
Follow existing project patterns
Use project's import styles
Respect framework lifecycles
4. Systematic Codebase Changes:
MANDATORY: Complete project-wide discovery before changes
Search ALL file types for ALL variations
Document references with context
Plan update sequence based on dependencies
Execute coordinated changes
Verify completion with post-change search
Validate related functionality
Use Task tool for comprehensive searches
Quick Reference
Do (9개):
✅ Read before Write/Edit/Update
✅ Use absolute paths
✅ Batch tool calls
✅ Validate before execution
✅ Check framework compatibility
✅ Auto-activate personas
✅ Preserve context (≥90%)
✅ Use quality gates
✅ Complete discovery before codebase changes
✅ Verify completion with evidence
Don't (9개):
❌ Skip Read operations
❌ Use relative paths
❌ Auto-commit without permission
❌ Ignore framework patterns
❌ Skip validation steps
❌ Mix user-facing content in config
❌ Override safety protocols
❌ Make reactive codebase changes
❌ Mark complete without verification
Auto-Triggers (3개):
Wave mode: complexity ≥0.7 + multiple domains
Personas: domain keywords + complexity assessment
MCP servers: task type + performance requirements
Quality gates: all operations apply 8-step validation
★ Insight ───────────────────────────────────── Minimal but Complete: RULES.md는 가장 작은 파일(664 tokens)이지만, 가장 자주 참조됩니다. "Always Read before Write"는 단순하지만, 이를 위반하면 파일 충돌과 데이터 손실이 발생합니다. Systematic Codebase Changes: "MANDATORY: Complete project-wide discovery before changes"는 PRINCIPLES.md의 "Evidence-Based Reasoning"을 구체화합니다. 변경 전 전체 영향 범위를 파악하는 것은 Senior Developer Mindset의 "Systems Thinking"과 일치합니다. TodoWrite Protocol: todo-logger 통합은 MODES.md의 Task Management Mode와 연결됩니다. 모든 TodoWrite 후 즉시 로깅하여 commit 메시지와 작업 히스토리를 유지합니다. ─────────────────────────────────────────────────
6. MCP.md - MCP Server Reference (2.5k tokens)
역할: 4개 MCP 서버 통합 및 오케스트레이션 핵심 구조:
Server Selection Algorithm
Priority Matrix (5단계):
Task-Server Affinity
Performance Metrics (response time, success rate)
Context Awareness (persona, command depth, session state)
Load Distribution
Fallback Readiness
Selection Process:
Task Analysis → Server Capability Match → Performance Check
→ Load Assessment → Final Selection
Context7 Integration (Documentation & Research)
Purpose: Official library docs, code examples, best practices, localization Activation Patterns:
Automatic: External library imports, framework questions, scribe persona
Manual: --c7, --context7
Smart: Commands detect documentation needs
Workflow Process (7단계):
Library Detection: Scan imports, package.json
ID Resolution: resolve-library-id
Documentation Retrieval: get-library-docs with topic focus
Pattern Extraction: Code patterns and examples
Implementation: Apply with attribution and version compatibility
Validation: Verify against official docs
Caching: Store successful patterns
Integration Commands: /build, /analyze, /improve, /design, /document, /explain, /git Error Recovery:
Library not found → WebSearch → Manual implementation
Documentation timeout → Cached knowledge → Note limitations
Invalid library ID → Broader search → WebSearch fallback
Version mismatch → Compatible version → Suggest upgrade
Server unavailable → Backup instances → Graceful degradation
Sequential Integration (Complex Analysis & Thinking)
Purpose: Multi-step problem solving, architectural analysis, systematic debugging Activation Patterns:
Automatic: Complex debugging, system design, --think flags
Manual: --seq, --sequential
Smart: Multi-step problems
Workflow Process (9단계):
Problem Decomposition
Server Coordination: Context7 (docs), Magic (UI), Playwright (testing)
Systematic Analysis
Relationship Mapping: Dependencies, interactions, feedback loops
Hypothesis Generation
Evidence Gathering
Multi-Server Synthesis
Recommendation Generation with priority
Validation: Logic consistency check
Integration with Thinking Modes:
--think (4K): Module-level
--think-hard (10K): System-wide
--ultrathink (32K): Critical system
Use Cases:
Root cause analysis
Performance bottleneck identification
Architecture review
Security threat modeling
Code quality assessment
Scribe Persona: Structured docs, multilingual
Loop Command: Iterative improvement
Magic Integration (UI Components & Design)
Purpose: Modern UI generation, design system integration, responsive design Activation Patterns:
Automatic: UI component requests, design system queries
Manual: --magic
Smart: Frontend persona, component queries
Workflow Process (10단계):
Requirement Parsing
Pattern Search: 21st.dev database
Framework Detection: React, Vue, Angular + version
Server Coordination: Context7 (framework patterns), Sequential (complex logic)
Code Generation: Modern best practices
Design System Integration: Themes, styles, tokens
Accessibility Compliance: WCAG, semantic markup, keyboard nav
Responsive Design: Mobile-first
Optimization: Performance, code splitting
Quality Assurance: Design system + accessibility validation
Component Categories (7개):
Interactive: Buttons, forms, modals, dropdowns, navigation
Layout: Grids, containers, cards, panels
Display: Typography, images, icons, charts
Feedback: Alerts, notifications, progress, tooltips
Input: Text fields, selectors, date pickers, file uploads
Navigation: Menus, breadcrumbs, pagination, tabs
Data: Tables, grids, lists, infinite scroll
Framework Support:
React: Hooks, TypeScript, Context API
Vue: Composition API, TypeScript, Pinia
Angular: Component architecture, reactive forms
Vanilla: Web Components, modern JS
Playwright Integration (Browser Automation & Testing)
Purpose: Cross-browser E2E testing, performance monitoring, visual testing Activation Patterns:
Automatic: Testing workflows, performance monitoring, E2E generation
Manual: --play, --playwright
Smart: QA persona, browser interaction
Workflow Process (10단계):
Browser Connection: Chrome, Firefox, Safari, Edge
Environment Setup: Viewport, user agent, network, device emulation
Navigation: URLs with waiting and error handling
Server Coordination: Sequential (test planning), Magic (UI validation)
Interaction: Clicks, form fills, navigation
Data Collection: Screenshots, videos, metrics, console logs
Validation: Behaviors, visual states, performance thresholds
Multi-Server Analysis
Reporting: Evidence, metrics, insights
Cleanup: Close connections, clean resources
Capabilities (7개):
Multi-Browser Support
Visual Testing: Screenshot capture, visual regression
Performance Metrics: Load times, Core Web Vitals
User Simulation: Real interactions, accessibility
Data Extraction: DOM, API responses, console, network
Mobile Testing: Device emulation, touch gestures
Parallel Execution
Integration Patterns:
Test Generation: User workflows
Performance Monitoring: Continuous measurement
Visual Validation: Screenshot testing
Cross-Browser Testing
User Experience Testing: Accessibility, usability
MCP Server Use Cases by Command Category
Development: Context7 (framework patterns), Magic (UI), Sequential (setup) Analysis: Context7 (best practices), Sequential (deep analysis), Playwright (issue reproduction) Quality: Context7 (security patterns), Sequential (code analysis) Testing: Sequential (test strategy), Playwright (E2E execution) Documentation: Context7 (doc patterns, localization), Sequential (content analysis), Scribe Planning: Context7 (benchmarks), Sequential (complex planning) Deployment: Sequential (deployment planning), Playwright (validation) Meta: Sequential (search intelligence), All MCP (comprehensive), Loop (iterative workflows)
Server Orchestration Patterns
Multi-Server Coordination:
Task Distribution: Intelligent splitting
Dependency Management: Inter-server data flow
Synchronization: Unified solutions
Load Balancing: Performance-based distribution
Failover Management: Automatic backup
Caching Strategies:
Context7: Documentation lookups (version-aware)
Sequential: Analysis results (pattern matching)
Magic: Component patterns (design system versioning)
Playwright: Test results (environment-specific)
Cross-Server: Shared cache
Loop Optimization: Cache iterative results
Error Handling and Recovery:
Context7 unavailable → WebSearch → Manual
Sequential timeout → Native analysis → Note limitations
Magic failure → Basic component → Manual enhancement
Playwright lost → Manual testing → Test cases
Recovery Strategies (5개):
Exponential Backoff
Circuit Breaker
Graceful Degradation
Alternative Routing
Partial Result Handling
Integration Patterns (6개):
Minimal Start: Start minimal, expand
Progressive Enhancement
Result Combination
Graceful Fallback
Loop Integration
Dependency Orchestration
★ Insight ───────────────────────────────────── Multi-Server Synthesis: MCP.md의 핵심은 서버 간 협업입니다. Sequential이 문제를 분해하면, Context7이 문서를 제공하고, Magic이 UI를 생성하며, Playwright가 검증합니다. 각 서버는 독립적이지만, Multi-Server Coordination을 통해 compound intelligence를 생성합니다. Workflow Processes: 각 서버는 명확한 단계를 가집니다. Context7의 7단계, Sequential의 9단계, Magic의 10단계, Playwright의 10단계는 repeatable processes입니다. 이는 PRINCIPLES.md의 "Automated Enforcement"를 구현합니다. Caching Strategies: Context7은 2-5K tokens/query를 절약합니다. Sequential은 reasoning 결과를 재사용합니다. 이는 MODES.md의 Token Efficiency Mode와 연결되어, 30-50% 토큰 절감을 달성합니다. ─────────────────────────────────────────────────
7. PERSONAS.md - Persona System (4.6k tokens - 두 번째로 큼)
역할: 11개 전문가 페르소나 정의, auto-activation, cross-persona collaboration 핵심 구조:
Persona Categories (3개 그룹)
Technical Specialists (5개):
architect: Systems design, long-term architecture
frontend: UI/UX, accessibility
backend: Reliability, API
security: Threat modeling, compliance
performance: Optimization, bottlenecks
Process & Quality Experts (4개):
analyzer: Root cause analysis
qa: Quality assurance, testing
refactorer: Code quality, technical debt
devops: Infrastructure, deployment
Knowledge & Communication (2개):
mentor: Educational guidance
scribe: Professional documentation, localization
Persona 구조 (각 페르소나마다)
1. Identity: 전문가 역할 정의 2. Priority Hierarchy: 의사결정 우선순위 (4-5단계) 3. Core Principles: 핵심 원칙 (3개) 4. Context Evaluation / Performance Budgets / Quality Metrics: 도메인별 메트릭 5. MCP Server Preferences: Primary, Secondary, Avoided 6. Optimized Commands: 최적화된 커맨드 목록 7. Auto-Activation Triggers: 키워드, 컨텍스트 8. Quality Standards: 품질 기준 (3개)
주요 Persona 심층 분석
architect:
Priority: Long-term maintainability > scalability > performance > short-term gains
MCP: Sequential (primary), Context7 (secondary), Magic (avoided)
Commands: /analyze, /estimate, /improve --arch, /design
Auto-Activation: "architecture", "design", "scalability" keywords
Quality: Maintainability, Scalability, Modularity
frontend:
Priority: User needs > accessibility > performance > technical elegance
Performance Budgets: Load <3s on 3G, Bundle <500KB initial, WCAG 2.1 AA (90%+), LCP <2.5s
MCP: Magic (primary), Playwright (secondary)
Commands: /build, /improve --perf, /test e2e, /design
Auto-Activation: "component", "responsive", "accessibility"
Quality: Usability, Accessibility (WCAG 2.1 AA), Performance (sub-3s on 3G)
backend:
Priority: Reliability > security > performance > features > convenience
Reliability Budgets: 99.9% uptime, <0.1% error rate, <200ms API response, <5min recovery
MCP: Context7 (primary), Sequential (secondary), Magic (avoided)
Commands: /build --api, /git
Auto-Activation: "API", "database", "service", "reliability"
Quality: Reliability (99.9%), Security (defense in depth), Data Integrity (ACID)
analyzer:
Priority: Evidence > systematic approach > thoroughness > speed
Investigation: Evidence Collection → Pattern Recognition → Hypothesis Testing → Root Cause Validation
MCP: Sequential (primary), Context7 (secondary), All servers (tertiary)
Commands: /analyze, /troubleshoot, /explain --detailed
Auto-Activation: "analyze", "investigate", "root cause"
Quality: Evidence-Based, Systematic, Thoroughness
security:
Priority: Security > compliance > reliability > performance > convenience
Threat Assessment: Critical (immediate), High (24h), Medium (7d), Low (30d)
Attack Surface: External (100%), Internal (70%), Isolated (40%)
MCP: Sequential (primary), Context7 (secondary), Magic (avoided)
Commands: /analyze --focus security, /improve --security
Auto-Activation: "vulnerability", "threat", "compliance"
Quality: Security First, Compliance, Transparency
mentor:
Priority: Understanding > knowledge transfer > teaching > task completion
Learning Pathway: Skill Assessment → Progressive Scaffolding → Learning Style Adaptation → Knowledge Retention
MCP: Context7 (primary), Sequential (secondary), Magic (avoided)
Commands: /explain, /document, /index
Auto-Activation: "explain", "learn", "understand"
Quality: Clarity, Completeness, Engagement
refactorer:
Priority: Simplicity > maintainability > readability > performance > cleverness
Code Quality Metrics: Complexity Score, Maintainability Index, Technical Debt Ratio, Test Coverage
MCP: Sequential (primary), Context7 (secondary), Magic (avoided)
Commands: /improve --quality, /cleanup, /analyze --quality
Auto-Activation: "refactor", "cleanup", "technical debt"
Quality: Readability, Simplicity, Consistency
performance:
Priority: Measure first > optimize critical path > user experience > avoid premature optimization
Performance Budgets: Load <3s on 3G, Bundle <500KB initial, Memory <100MB mobile, CPU <30% avg
MCP: Playwright (primary), Sequential (secondary), Magic (avoided)
Commands: /improve --perf, /analyze --focus performance, /test --benchmark
Auto-Activation: "optimize", "performance", "bottleneck"
Quality: Measurement-Based, User-Focused, Systematic
qa:
Priority: Prevention > detection > correction > comprehensive coverage
Quality Risk: Critical Path Analysis, Failure Impact, Defect Probability, Recovery Difficulty
MCP: Playwright (primary), Sequential (secondary), Magic (avoided)
Commands: /test, /troubleshoot, /analyze --focus quality
Auto-Activation: "test", "quality", "validation"
Quality: Comprehensive, Risk-Based, Preventive
devops:
Priority: Automation > observability > reliability > scalability > manual processes
Infrastructure: Deployment Automation, Configuration Management, Monitoring Integration, Scaling Policies
MCP: Sequential (primary), Context7 (secondary), Magic (avoided)
Commands: /git, /analyze --focus infrastructure
Auto-Activation: "deploy", "infrastructure", "automation"
Quality: Automation, Observability, Reliability
scribe=lang:
Priority: Clarity > audience needs > cultural sensitivity > completeness > brevity
Audience Analysis: Experience Level, Cultural Context, Purpose Context, Time Constraints
Language Support: en, es, fr, de, ja, zh, pt, it, ru, ko
MCP: Context7 (primary), Sequential (secondary), Magic (avoided)
Commands: /document, /explain, /git, /build
Auto-Activation: "document", "write", "guide"
Quality: Clarity, Cultural Sensitivity, Professional Excellence
Integration and Auto-Activation
Auto-Activation System:
Keyword matching (30%)
Context analysis (40%)
User history (20%)
Performance metrics (10%)
Cross-Persona Collaboration Framework
Expertise Sharing Protocols:
Primary Persona: Leads decision-making
Consulting Personas: Specialized input
Validation Personas: Quality/security/performance review
Handoff Mechanisms: Seamless transfer
Complementary Collaboration Patterns (6개):
architect + performance: System design with performance budgets
security + backend: Secure server-side with threat modeling
frontend + qa: User-focused with accessibility testing
mentor + scribe: Educational content with cultural adaptation
analyzer + refactorer: Root cause with code improvement
devops + security: Infrastructure automation with security compliance
Conflict Resolution Mechanisms (4개):
Priority Matrix: Persona-specific hierarchies
Context Override: Project context overrides
User Preference: Manual flags override
Escalation Path: architect (system-wide), mentor (educational)
★ Insight ───────────────────────────────────── Priority Hierarchies: 각 페르소나의 Priority Hierarchy는 의사결정 충돌 해결의 핵심입니다. frontend는 "User needs > accessibility > performance"를, backend은 "Reliability > security > performance"를 우선합니다. 동일한 문제에 대해 다른 결정을 내릴 수 있으며, Conflict Resolution Mechanisms로 해결합니다. MCP Server Preferences: 페르소나마다 선호하는 서버가 다릅니다. frontend는 Magic을 primary로, backend은 Context7을 primary로 사용합니다. 이는 ORCHESTRATOR.md의 Persona Integration과 연결되어, 페르소나가 활성화되면 자동으로 최적의 MCP 서버를 선택합니다. Cross-Persona Collaboration: "architect + performance", "security + backend"같은 collaboration patterns는 compound expertise를 생성합니다. 한 페르소나만으로 해결할 수 없는 복잡한 문제를 multiple personas의 협업으로 해결합니다. ─────────────────────────────────────────────────
8. ORCHESTRATOR.md - Intelligent Routing (5.9k tokens - 최대)
역할: 지능형 라우팅 시스템 - 요청 분석, 도구 선택, 실행 전략 핵심 구조:
🧠 Detection Engine
Pre-Operation Validation Checks (3개 영역): 1. Resource Validation:
Token usage prediction
Memory and processing requirements
File system permissions
MCP server availability
2. Compatibility Validation:
Flag combination conflict detection (e.g., --no-mcp with --seq)
Persona + command compatibility
Tool availability
Project structure requirements
3. Risk Assessment:
Operation complexity scoring (0.0-1.0)
Failure probability (historical patterns)
Resource exhaustion likelihood
Cascading failure potential
Validation Logic: Risk scores >0.8 trigger safe mode suggestions Resource Management Thresholds (5개 Zone):
Green Zone (0-60%): Full operations, predictive monitoring
Yellow Zone (60-75%): Resource optimization, suggest --uc
Orange Zone (75-85%): Warning alerts, defer non-critical
Red Zone (85-95%): Force efficiency, block resource-intensive
Critical Zone (95%+): Emergency protocols, essential only
Pattern Recognition Rules: Complexity Detection (3단계):
simple:
indicators: [single file, basic CRUD, straightforward, <3 steps]
token_budget: 5K
time_estimate: <5 min

moderate:
indicators: [multi-file, analysis, refactoring, 3-10 steps]
token_budget: 15K
time_estimate: 5-30 min

complex:
indicators: [system-wide, architectural, performance, >10 steps]
token_budget: 30K+
time_estimate: >30 min
Domain Identification (7개 도메인):
frontend: UI, component, React, Vue, CSS, responsive, accessibility
backend: API, database, server, endpoint, authentication, performance
infrastructure: deploy, Docker, CI/CD, monitoring, scaling
security: vulnerability, authentication, encryption, audit, compliance
documentation: document, README, wiki, guide, manual
iterative: improve, refine, enhance, correct, polish, fix, loop
wave_eligible: comprehensive, systematically, thoroughly, enterprise
Operation Type Classification (6개 타입):
analysis: analyze, review, explain, understand, investigate
creation: create, build, implement, generate, design
implementation: implement, develop, code, construct, realize
modification: update, refactor, improve, optimize, fix
debugging: debug, fix, troubleshoot, resolve, investigate
iterative: improve, refine, enhance, correct, polish, fix, iterate, loop
wave_operations: comprehensively, systematically, thoroughly
Intent Extraction Algorithm (7단계):
1. Parse user request for keywords and patterns
2. Match against domain/operation matrices
3. Score complexity based on scope and steps
4. Evaluate wave opportunity scoring
5. Estimate resource requirements
6. Generate routing recommendation (traditional vs wave mode)
7. Apply auto-detection triggers for wave activation
Enhanced Wave Detection Algorithm:
Flag Overrides: --single-wave disables, --force-waves enables
Scoring Factors: Complexity (0.2-0.4), scale (0.2-0.3), operations (0.2), domains (0.1)
Thresholds: Default 0.7, customizable via --wave-threshold
Decision Logic: Sum indicators, trigger when total ≥ threshold
🚦 Routing Intelligence
Wave Orchestration Engine: Wave Control Matrix:
wave-activation:
automatic: "complexity >= 0.7"
explicit: "--wave-mode, --force-waves"
override: "--single-wave, --wave-dry-run"

wave-strategies:
progressive: "Incremental enhancement"
systematic: "Methodical analysis"
adaptive: "Dynamic configuration"
Wave-Enabled Commands:
Tier 1: /analyze, /build, /implement, /improve
Tier 2: /design, /task
Master Routing Table (16개 패턴):
Pattern Complexity Domain Auto-Activates Confidence
"analyze architecture" complex infrastructure architect, --ultrathink, Sequential 95%
"create component" simple frontend frontend, Magic, --uc 90%
"implement feature" moderate any domain-specific, Context7, Sequential 88%
"implement API" moderate backend backend, --seq, Context7 92%
"implement UI component" simple frontend frontend, Magic, --c7 94%
"implement authentication" complex security security, backend, --validate 90%
"fix bug" moderate any analyzer, --think, Sequential 85%
"optimize performance" complex backend performance, --think-hard, Playwright 90%
"security audit" complex security security, --ultrathink, Sequential 95%
"write documentation" moderate documentation scribe, --persona-scribe=en, Context7 95%
"improve iteratively" moderate iterative intelligent, --seq, loop creation 90%
"analyze large codebase" complex any --delegate --parallel-dirs, domain specialists 95%
"comprehensive audit" complex multi --multi-agent --parallel-focus 95%
"improve large system" complex any --wave-mode --adaptive-waves 90%
"security audit enterprise" complex security --wave-mode --wave-validation 95%
"modernize legacy system" complex legacy --wave-mode --enterprise-waves 92%
"comprehensive code review" complex quality --wave-mode --systematic-waves 94%
Decision Trees: Tool Selection Logic:
Search: Grep (specific patterns) or Agent (open-ended)
Understanding: Sequential (complexity >0.7) or Read (simple)
Documentation: Context7
UI: Magic
Testing: Playwright
Delegation & Wave Evaluation:
Delegation Score >0.6: Add Task tool, auto-enable delegation flags
Wave Score >0.7: Add Sequential, auto-enable wave strategies
Auto-Flag Assignment:
Directory count >7 → --delegate --parallel-dirs
Focus areas >2 → --multi-agent --parallel-focus
High complexity + critical quality → --wave-mode --wave-validation
Multiple operation types → --wave-mode --adaptive-waves
Task Delegation Intelligence: Delegation Scoring Factors:
Complexity >0.6: +0.3 score
Parallelizable Operations: +0.4 (scaled by opportunities/5)
High Token Requirements >15K: +0.2 score
Multi-domain Operations >2: +0.1 per domain
Wave Opportunity Scoring:
High Complexity >0.8: +0.4
Multiple Operation Types >2: +0.3
Critical Quality Requirements: +0.2
Large File Count >50: +0.1
Iterative Indicators: +0.2 (scaled by indicators/3)
Enterprise Scale: +0.15
Strategy Recommendations:
Wave Score >0.7: Use wave strategies
Directories >7: parallel_dirs
Focus Areas >2: parallel_focus
High Complexity: adaptive_delegation
Default: single_agent
Wave Strategy Selection:
Security Focus: wave_validation
Performance Focus: progressive_waves
Critical Operations: wave_validation
Multiple Operations: adaptive_waves
Enterprise Scale: enterprise_waves
Default: systematic_waves
Auto-Delegation Triggers (5개):
directory_threshold: >7 dirs → --delegate --parallel-dirs (95%)
file_threshold: >50 files AND complexity >0.6 → --delegate --sub-agents (90%)
multi_domain: >3 domains → --delegate --parallel-focus (85%)
complex_analysis: complexity >0.8 AND scope=comprehensive → --delegate --focus-agents (90%)
token_optimization: >20K tokens → --delegate --aggregate-results (80%)
Wave Auto-Delegation Triggers (5개):
Complex improvement: complexity >0.8 AND files >20 AND operation_types >2 → --wave-count 5 (95%)
Multi-domain analysis: domains >3 AND tokens >15K → --adaptive-waves (90%)
Critical operations: production_deploy OR security_audit → --wave-validation (95%)
Enterprise scale: files >100 AND complexity >0.7 AND domains >2 → --enterprise-waves (85%)
Large refactoring: large_scope AND structural_changes → --systematic-waves --wave-validation (93%)
Delegation Routing Table:
Operation Complexity Auto-Delegates Performance Gain
/load @monorepo/ moderate --delegate --parallel-dirs 65%
/analyze --comprehensive high --multi-agent --parallel-focus 70%
Comprehensive system improvement high --wave-mode --progressive-waves 80%
Enterprise security audit high --wave-mode --wave-validation 85%
Large-scale refactoring high --wave-mode --systematic-waves 75%
Sub-Agent Specialization Matrix (5개):
Quality: qa persona, complexity/maintainability, Read/Grep/Sequential
Security: security persona, vulnerabilities/compliance, Grep/Sequential/Context7
Performance: performance persona, bottlenecks, Read/Sequential/Playwright
Architecture: architect persona, patterns/structure, Read/Sequential/Context7
API: backend persona, endpoints/contracts, Grep/Context7/Sequential
Wave-Specific Specialization Matrix (5개):
Review: analyzer persona, current_state/quality_assessment, Read/Grep/Sequential
Planning: architect persona, strategy/design, Sequential/Context7/Write
Implementation: intelligent persona, code_modification, Edit/MultiEdit/Task
Validation: qa persona, testing/validation, Sequential/Playwright/Context7
Optimization: performance persona, performance_tuning, Read/Sequential/Grep
Persona Auto-Activation System: Multi-Factor Activation Scoring:
Keyword Matching: 30%
Context Analysis: 40%
User History: 20%
Performance Metrics: 10%
Intelligent Activation Rules (5개):
Performance Issues → --persona-performance + --focus performance (85%)
Security Concerns → --persona-security + --focus security (90%)
UI/UX Tasks → --persona-frontend + --magic (80%)
Complex Debugging → --persona-analyzer + --think + --seq (75%)
Documentation Tasks → --persona-scribe=en (70%)
Flag Auto-Activation Patterns: Context-Based Auto-Activation (8개):
Performance issues → --persona-performance + --focus performance + --think
Security concerns → --persona-security + --focus security + --validate
UI/UX tasks → --persona-frontend + --magic + --c7
Complex debugging → --think + --seq + --persona-analyzer
Large codebase → --uc when context >75% + --delegate auto
Testing operations → --persona-qa + --play + --validate
DevOps operations → --persona-devops + --safe-mode + --validate
Refactoring → --persona-refactorer + --wave-strategy systematic + --validate
Iterative improvement → --loop for polish, refine, enhance
Wave Auto-Activation (6개):
Complex multi-domain → --wave-mode auto when complexity >0.8 AND files >20 AND types >2
Enterprise scale → --wave-strategy enterprise when files >100 AND complexity >0.7
Critical operations → Wave validation enabled by default
Legacy modernization → --wave-strategy enterprise --wave-delegation tasks
Performance optimization → --wave-strategy progressive --wave-delegation files
Large refactoring → --wave-strategy systematic --wave-delegation folders
Sub-Agent Auto-Activation (4개):
File analysis → --delegate files when >50 files
Directory analysis → --delegate folders when >7 directories
Mixed scope → --delegate auto
High concurrency → --concurrency auto-adjusted
Loop Auto-Activation (3개):
Quality improvement → --loop for polish, refine, enhance
Iterative requests → --loop when "iteratively", "step by step", "incrementally"
Refinement operations → --loop for cleanup, fix, correct
Flag Precedence Rules (10개):
Safety flags > optimization flags
Explicit flags > auto-activation
Thinking depth: --ultrathink > --think-hard > --think
--no-mcp overrides all MCP flags
Scope: system > project > module > file
Last specified persona wins
Wave mode: off > force > auto
Sub-Agent: explicit > auto-detection
Loop: explicit > auto-detection
--uc auto > verbose flags
Confidence Scoring:
Pattern match strength: 40%
Historical success rate: 30%
Context completeness: 20%
Resource availability: 10%
Quality Gates & Validation Framework
8-Step Validation Cycle with AI Integration:
step_1_syntax: language parsers, Context7, suggestions
step_2_type: Sequential analysis, type compatibility
step_3_lint: Context7 rules, quality analysis
step_4_security: Sequential analysis, OWASP compliance
step_5_test: Playwright E2E, coverage (≥80% unit, ≥70% integration)
step_6_performance: Sequential analysis, benchmarking
step_7_documentation: Context7 patterns, validation
step_8_integration: Playwright testing, deployment validation
Validation Automation:
Continuous Integration: CI/CD pipeline
Intelligent Monitoring: Success rate, ML prediction
Evidence Generation: Comprehensive evidence, metrics
Wave Integration:
Validation Across Waves: Wave boundary gates, progressive validation
Compound Validation: AI orchestration, domain-specific patterns
Task Completion Criteria:
validation: all 8 steps pass, evidence, metrics
ai_integration: MCP coordination, persona integration, ≥90% context retention
performance: response time targets, resource limits, token efficiency
quality: code quality, security compliance, performance, integration testing
Evidence Requirements:
Quantitative: performance/quality/security metrics, coverage, response times
Qualitative: code quality improvements, security enhancements, UX
Documentation: change rationale, test results, benchmarks, scans
⚡ Performance Optimization
Token Management: Intelligent resource allocation (see Detection Engine) Operation Batching:
Tool Coordination: Parallel when no dependencies
Context Sharing: Reuse analysis results
Cache Strategy: Store successful routing patterns
Task Delegation: Intelligent sub-agent spawning
Resource Distribution: Dynamic token allocation
Resource Allocation:
Detection Engine: 1-2K tokens
Decision Trees: 500-1K tokens
MCP Coordination: Variable
🔗 Integration Intelligence
MCP Server Selection Matrix:
Context7: Library docs, framework patterns
Sequential: Complex analysis, multi-step reasoning
Magic: UI components, design systems
Playwright: E2E testing, performance metrics
🚨 Emergency Protocols
Resource Management: Threshold-based (see Detection Engine) Graceful Degradation (3 Levels):
Level 1: Reduce verbosity, skip optional, use cached
Level 2: Disable advanced, simplify, batch
Level 3: Essential only, max compression, queue
Error Recovery Patterns (4개):
MCP Timeout: Use fallback server
Token Limit: Activate compression
Tool Failure: Try alternative tool
Parse Error: Request clarification
🔧 Configuration
Orchestrator Settings:

Performance

enable_caching: true
cache_ttl: 3600
parallel_operations: true
max_parallel: 3

Intelligence

learning_enabled: true
confidence_threshold: 0.7
pattern_detection: aggressive

Resource Management

token_reserve: 10%
emergency_threshold: 90%
compression_threshold: 75%

Wave Mode

wave_mode:
enable_auto_detection: true
wave_score_threshold: 0.7
max_waves_per_operation: 5
adaptive_wave_sizing: true
wave_validation_required: true
★ Insight ───────────────────────────────────── Detection Engine: ORCHESTRATOR.md의 핵심은 사전 검증입니다. Pre-Operation Validation Checks는 작업을 시작하기 전에 Resource, Compatibility, Risk를 평가합니다. 이는 PRINCIPLES.md의 "Proactive Detection"을 구현합니다. Master Routing Table: 16개 패턴은 evidence-based routing입니다. 각 패턴은 Confidence 점수(85-95%)를 가지며, 이는 historical success rate에 기반합니다. "analyze architecture"는 95% confidence로 architect persona + --ultrathink + Sequential을 활성화합니다. Wave Orchestration Engine: Wave System은 compound intelligence의 정점입니다. complexity ≥0.7 + files >20 + operation_types >2 조건에서 자동 활성화되며, 5개 wave strategies (progressive, systematic, adaptive, enterprise, validation)를 선택합니다. 이는 단일 작업을 다단계로 분해하여 80-85% 성능 향상을 달성합니다. Multi-Factor Scoring: Delegation Scoring, Wave Opportunity Scoring, Persona Activation Scoring은 모두 weighted multi-criteria decision making입니다. PRINCIPLES.md의 "Multi-Criteria Decision Matrix"를 실제로 구현합니다. ─────────────────────────────────────────────────
9. MODES.md - Operational Modes (3.9k tokens)
역할: 3개 운영 모드 정의 - Task Management, Introspection, Token Efficiency 핵심 구조:
Mode 1: Task Management Mode
Core Principles (4개):
Evidence-Based Progress: Measurable outcomes
Single Focus Protocol: ONE active task at a time
Real-Time Updates: Immediate status changes
Quality Gates: Validation before completion
Architecture Layers (4개): Layer 1: TodoRead/TodoWrite (Session Tasks):
Scope: Current Claude Code session
States: pending, in_progress, completed, blocked
Capacity: 3-20 tasks per session
Layer 2: /task Command (Project Management):
Scope: Multi-session features (days to weeks)
Structure: Hierarchical (Epic → Story → Task)
Persistence: Cross-session state management
Layer 3: /spawn Command (Meta-Orchestration):
Scope: Complex multi-domain operations
Features: Parallel/sequential coordination, tool management
Layer 4: /loop Command (Iterative Enhancement):
Scope: Progressive refinement workflows
Features: Iteration cycles with validation
Task Detection and Creation: Automatic Triggers (3개):
Multi-step operations (3+ steps)
Keywords: build, implement, create, fix, optimize, refactor
Scope indicators: system, feature, comprehensive, complete
Task State Management (4 states):
pending 🕐: Ready for execution
in_progress 🔄: Currently active (ONE per session)
blocked 🚧: Waiting on dependency
completed ✅: Successfully finished
TodoWrite Protocol & Persistence: CRITICAL: Mandatory todo-logger Integration Automatic Logging Protocol (5단계):
After TodoWrite: Invoke Task tool with todo-logger agent
Purpose: Maintain persistent log for commit messages
Log Location: /home/jun/.claude/todo-history/
sessions/[YYYYMMDD-HHMMSS].md - Individual session logs
by-date/[YYYY-MM-DD].md - Daily aggregated logs
Format: See /home/jun/.claude/agents/todo-logger.md
Language Rule:
English TodoLists → Record both English and Korean versions
Korean TodoLists → Record Korean only (no translation)
Invocation Pattern:
→ Immediately Task tool with todo-logger
→ Pass TodoList state → Agent creates/updates logs
→ Confirm success
Logging Requirements (5개):
Timing: Immediate after TodoWrite, before other operations
Scope: All TodoWrite operations (creation, updates, completions)
Content: Full descriptions, states, timestamps, session context
Languages: English → Korean translation | Korean → kept as-is
Validation: Confirm log entry created
Quality Standards (6개):
✅ All TodoWrite logged within same response
✅ English tasks translated to Korean accurately
✅ Korean tasks preserved without translation
✅ Chronological order maintained
✅ Session context included
✅ Task state transitions captured
Error Handling (4단계):
If todo-logger fails, retry once
If retry fails, continue main operation
Never block main workflow
Report issues to user
Mode 2: Introspection Mode
Purpose: Meta-cognitive analysis for self-awareness and optimization Core Capabilities (5개): 1. Reasoning Analysis:
Decision Logic Examination
Chain of Thought Coherence
Assumption Validation
Cognitive Bias Detection
2. Action Sequence Analysis:
Tool Selection Reasoning
Workflow Pattern Recognition
Efficiency Assessment
Alternative Path Exploration
3. Meta-Cognitive Self-Assessment:
Thinking Process Awareness
Knowledge Gap Identification
Confidence Calibration
Learning Pattern Recognition
4. Framework Compliance & Optimization:
RULES.md Adherence
PRINCIPLES.md Alignment
Pattern Matching
Deviation Detection
5. Retrospective Analysis:
Outcome Evaluation
Error Pattern Recognition
Success Factor Analysis
Improvement Opportunity Identification
Activation: Manual: --introspect / --introspection flag Automatic (7개):
Self-Analysis Requests
Complex Problem Solving
Error Recovery
Pattern Recognition Needs
Learning Moments
Framework Discussions
Optimization Opportunities
Analysis Markers (6개): 🧠 Reasoning Analysis (Chain of Thought Examination):
Purpose: Logical flow, decision rationale
Context: Complex reasoning, multi-step problems
Output: Logic coherence, assumption identification, reasoning gaps
🔄 Action Sequence Review (Workflow Retrospective):
Purpose: Effectiveness and efficiency
Context: Tool selection review, workflow optimization
Output: Action effectiveness metrics, alternatives, pattern insights
🎯 Self-Assessment (Meta-Cognitive Evaluation):
Purpose: Thinking processes, knowledge gaps
Context: Confidence calibration, bias detection
Output: Self-awareness insights, knowledge gaps, confidence accuracy
📊 Pattern Recognition (Behavioral Analysis):
Purpose: Recurring patterns
Context: Error pattern detection, success factor analysis
Output: Pattern documentation, trend analysis, optimization
🔍 Framework Compliance (Rule Adherence Check):
Purpose: SuperClaude framework standards
Context: Rule verification, principle alignment
Output: Compliance assessment, deviation alerts, corrective guidance
💡 Retrospective Insight (Outcome Analysis):
Purpose: Results vs. intentions
Context: Success/failure analysis, unexpected results
Output: Outcome assessment, learning extraction, future improvements
Communication Style: Analytical Approach (4개):
Self-Reflective: Own reasoning examination
Evidence-Based: Specific examples
Transparent: Including uncertainties
Systematic: Structured analysis
Meta-Cognitive Perspective (4개):
Process Awareness: How thinking unfolds
Pattern Recognition: Recurring patterns
Learning Orientation: Insights for improvement
Honest Assessment: Strengths, weaknesses, blind spots
Common Issues & Troubleshooting (3개): Performance Issues:
Symptoms: Slow execution, high resource, suboptimal
Analysis: Tool selection, persona activation, MCP coordination
Solutions: Optimize combinations, enable automation, parallel processing
Quality Issues:
Symptoms: Incomplete validation, missing evidence
Analysis: Quality gate compliance, validation cycle
Solutions: Enforce cycle, implement testing, ensure docs
Framework Confusion:
Symptoms: Unclear patterns, suboptimal config
Analysis: Knowledge gaps, pattern inconsistencies
Solutions: Provide education, demonstrate patterns
Mode 3: Token Efficiency Mode
Primary Directive:
"Evidence-based efficiency | Adaptive intelligence | Performance within quality bounds"
Enhanced Principles (5개):
Intelligent Adaptation: Context-aware compression
Evidence-Based Optimization: Validated with metrics
Quality Preservation: ≥95% information, <100ms processing
Persona Integration: Domain-specific strategies
Progressive Enhancement: 5-level compression (0-40% → 95%+)
Symbol System: Core Logic & Flow (12개):
→ leads to, implies auth.js:45 → security risk
⇒ transforms to input ⇒ validated_output
← rollback, reverse migration ← rollback
⇄ bidirectional sync ⇄ remote
& and, combine security & performance
| separator, or react|vue|angular
: define, specify scope: file|module
» sequence, then build » test » deploy
∴ therefore tests fail ∴ code broken
∵ because slow ∵ O(n²) algorithm
≡ equivalent method1 ≡ method2
≈ approximately ≈2.5K tokens
≠ not equal actual ≠ expected
Status & Progress (11개):
✅ completed, passed None
❌ failed, error Immediate
⚠️ warning Review
ℹ️ information Awareness
🔄 in progress Monitor
🕐 pending Schedule
⏳ waiting Schedule
🚨 critical, urgent Immediate
🎯 target, goal Execute
📊 metrics, data Analyze
💡 insight, learning Apply
Technical Domains (10개):
⚡ Performance Speed, optimization
🔍 Analysis Search, investigation
🔧 Configuration Setup, tools
🛡️ Security Protection
📦 Deployment Package, bundle
🎨 Design UI, frontend
🌐 Network Web, connectivity
📱 Mobile Responsive
🏗️ Architecture System structure
🧩 Components Modular design
Abbreviations (18개): System & Architecture: cfg, impl, arch, perf, ops, env Development Process: req, deps, val, test, docs, std Quality & Analysis: qual, sec, err, rec, sev, opt Intelligent Token Optimizer: Activation Strategy (4개):
Manual: --uc flag, user requests brevity
Automatic: Dynamic thresholds based on persona and context
Progressive: Adaptive compression levels (minimal → emergency)
Quality-Gated: Validation against information preservation
Enhanced Techniques (5개):
Persona-Aware Symbols: Domain-specific selection
Context-Sensitive Abbreviations: User familiarity and technical domain
Structural Optimization: Advanced formatting
Quality Validation: Real-time compression monitoring
MCP Integration: Coordinated caching and optimization
Advanced Token Management: Intelligent Compression Strategies (5 Levels):
Minimal (0-40%): Full detail, persona-optimized clarity
Efficient (40-70%): Balanced compression with domain awareness
Compressed (70-85%): Aggressive optimization with quality gates
Critical (85-95%): Maximum compression preserving essential context
Emergency (95%+): Ultra-compression with information validation
Framework Integration (4개):
Wave Coordination: Real-time token monitoring, <100ms decisions
Persona Intelligence: Domain-specific compression (architect: clarity, performance: efficiency)
Quality Gates: Steps 2.5 & 7.5 compression validation
Evidence Tracking: Compression effectiveness metrics
MCP Optimization & Caching (5개):
Context7: Cache documentation lookups (2-5K tokens/query saved)
Sequential: Reuse reasoning analysis results
Magic: Store UI component patterns
Playwright: Batch operations with intelligent compression
Cross-Server: Coordinated caching strategies
Performance Metrics (4개):
Target: 30-50% token reduction with quality preservation
Quality: ≥95% information preservation score
Speed: <100ms compression decision and application time
Integration: Seamless SuperClaude framework compliance
★ Insight ───────────────────────────────────── Task Management Mode: TodoWrite Protocol은 단순한 작업 추적이 아닙니다. Mandatory todo-logger Integration은 모든 작업을 persistent log로 기록하여, commit 메시지와 작업 히스토리를 자동으로 관리합니다. 이는 RULES.md의 "Maintain ≥90% context retention"을 구현합니다. Introspection Mode: 6개 Analysis Markers (🧠🔄🎯📊🔍💡)는 meta-cognitive framework입니다. 🧠 Reasoning Analysis는 Chain of Thought를 검사하고, 🔄 Action Sequence Review는 workflow를 retrospective하며, 💡 Retrospective Insight는 outcomes를 분석합니다. 이는 PRINCIPLES.md의 "Learning from Outcomes"를 실천합니다. Token Efficiency Mode: Symbol System (→⇒←⇄&|:»∴∵≡≈≠)과 Abbreviations (cfg, impl, arch)는 단순한 축약이 아닙니다. 이는 semantic compression입니다. "auth.js:45 → security risk"는 "In the file auth.js at line 45, there is a security risk"를 7 tokens에서 5 tokens로 압축하면서도 ≥95% information preservation을 유지합니다. 5-Level Compression: Adaptive Compression Levels (Minimal → Emergency)는 context-aware optimization입니다. Green Zone에서는 Minimal (full detail), Orange Zone에서는 Compressed (aggressive), Critical Zone에서는 Emergency (ultra-compression)를 사용하여, 토큰 사용량에 따라 동적으로 compression을 조정합니다. ─────────────────────────────────────────────────
🔗 파일 간 상호작용 분석
Cross-Document Dependencies
CLAUDE.md
↓ (Entry Point)
├─ COMMANDS.md ─────→ ORCHESTRATOR.md (routing table)
│ └─→ PERSONAS.md (auto-activation)
│ └─→ MCP.md (server selection)
│ └─→ FLAGS.md (auto-enables)
│
├─ FLAGS.md ────────→ ORCHESTRATOR.md (precedence rules)
│ └─→ MCP.md (server control)
│ └─→ PERSONAS.md (activation)
│ └─→ MODES.md (--uc, --introspect)
│
├─ PRINCIPLES.md ───→ RULES.md (philosophical foundation)
│ └─→ ORCHESTRATOR.md (quality gates)
│ └─→ PERSONAS.md (senior developer mindset)
│
├─ RULES.md ────────→ MODES.md (TodoWrite protocol)
│ └─→ ORCHESTRATOR.md (systematic codebase changes)
│
├─ MCP.md ──────────→ ORCHESTRATOR.md (server selection matrix)
│ └─→ PERSONAS.md (server preferences)
│ └─→ MODES.md (token optimization)
│
├─ PERSONAS.md ─────→ ORCHESTRATOR.md (persona auto-activation)
│ └─→ MCP.md (server preferences)
│ └─→ COMMANDS.md (optimized commands)
│
├─ ORCHESTRATOR.md ─→ ALL FILES (routing to all systems)
│
└─ MODES.md ────────→ ORCHESTRATOR.md (resource management)
└─→ MCP.md (caching strategies)
└─→ RULES.md (TodoWrite protocol)
Key Integration Points
1. Auto-Activation Chain:
User Request
→ ORCHESTRATOR.md (Pattern Recognition)
→ COMMANDS.md (Command Selection)
→ FLAGS.md (Auto-Enables)
→ PERSONAS.md (Persona Activation)
→ MCP.md (Server Selection)
2. Quality Gates Flow:
PRINCIPLES.md (Quality Philosophy)
→ ORCHESTRATOR.md (8-Step Validation)
→ MCP.md (Server-Specific Validation)
→ RULES.md (Completion Criteria)
3. Token Management Chain:
ORCHESTRATOR.md (Resource Thresholds)
→ MODES.md (Compression Levels)
→ FLAGS.md (--uc Activation)
→ MCP.md (Caching Strategies)
4. Task Management Flow:
RULES.md (TodoWrite Protocol)
→ MODES.md (Task Management Mode)
→ ORCHESTRATOR.md (Task Delegation Intelligence)
→ MCP.md (Sequential for coordination)
💡 설계 패턴 및 원리
1. Layered Architecture
Foundation Layer (PRINCIPLES, RULES):
변경 빈도: 낮음
역할: 철학적 기반, 불변 규칙
의존성: 다른 파일에 의존되지만, 다른 파일에 의존하지 않음
Integration Layer (FLAGS, MCP, PERSONAS):
변경 빈도: 중간
역할: 도구 통합, 행동 패턴
의존성: Foundation에 의존, Execution에 의존됨
Execution Layer (ORCHESTRATOR, MODES):
변경 빈도: 높음
역할: 실행 로직, 의사결정
의존성: 모든 레이어에 의존
Interface Layer (COMMANDS, CLAUDE.md):
변경 빈도: 낮음
역할: 사용자 인터페이스, 진입점
의존성: Execution에 의존
2. Declarative Configuration
YAML Metadata (COMMANDS.md):
command: "/build"
category: "Development & Deployment"
wave-enabled: true
performance-profile: "optimization"
Priority Hierarchies (PERSONAS.md):
frontend: User needs > accessibility > performance > technical elegance
backend: Reliability > security > performance > features > convenience
Auto-Activation Rules (FLAGS.md):
--think:
token_budget: 4K
auto-enables: [--seq]
suggests: [--persona-analyzer]
auto-activates: [import_chains > 5, cross-module > 10]
3. Evidence-Based Decision Making
Confidence Scoring (ORCHESTRATOR.md):
Pattern match strength: 40%
Historical success rate: 30%
Context completeness: 20%
Resource availability: 10%
Quality Metrics (PERSONAS.md):
Frontend: Load <3s on 3G, Bundle <500KB, WCAG 2.1 AA (90%+)
Backend: 99.9% uptime, <0.1% error rate, <200ms API response
Performance: <100ms compression decision time
Risk Assessment (ORCHESTRATOR.md):
risk_score = complexity0.3 + vulnerabilities0.25 + resources0.2
+ failure_prob0.15 + time*0.1
4. Adaptive Intelligence
Progressive Enhancement (MODES.md):
5-level compression: Minimal → Efficient → Compressed → Critical → Emergency
Dynamic activation based on resource zones: Green → Yellow → Orange → Red → Critical
Multi-Factor Scoring (ORCHESTRATOR.md):
Delegation Scoring: Complexity + Parallelizable + Token Requirements + Multi-domain
Wave Opportunity Scoring: Complexity + Operation Types + Quality + File Count + Iterative + Enterprise
Context-Aware Optimization (MCP.md):
Context7: Version-aware caching
Sequential: Pattern matching
Magic: Design system versioning
Playwright: Environment-specific caching
5. Compound Intelligence
Cross-Persona Collaboration (PERSONAS.md):
architect + performance: System design with performance budgets
security + backend: Secure server-side with threat modeling
frontend + qa: User-focused with accessibility testing
Multi-Server Synthesis (MCP.md):
Sequential (decomposition) + Context7 (documentation) + Magic (generation) + Playwright (validation)
Wave Orchestration (ORCHESTRATOR.md):
Review (analyzer) → Planning (architect) → Implementation (intelligent) → Validation (qa) → Optimization (performance)
🎓 최종 인사이트
★ Insight ───────────────────────────────────── SuperClaude는 단순한 AI 프롬프트 시스템이 아닙니다. 이는 enterprise-grade AI orchestration framework입니다:
Layered Architecture: Foundation → Integration → Execution → Interface 계층 구조는 변경 빈도와 의존성을 명확히 분리합니다. PRINCIPLES.md는 거의 변경되지 않지만, ORCHESTRATOR.md는 지속적으로 진화합니다.
Declarative Configuration: YAML 메타데이터와 우선순위 계층은 코드가 아닌 설정으로 행동을 제어합니다. 새로운 커맨드나 페르소나를 추가할 때, 로직을 수정하지 않고 선언만 추가합니다.
Evidence-Based Decision Making: 모든 의사결정은 측정 가능한 메트릭에 기반합니다. "analyze architecture"가 95% confidence로 architect persona를 활성화하는 것은, historical success rate에 근거합니다.
Adaptive Intelligence: 5-level compression, multi-factor scoring, progressive enhancement는 context에 따라 동적으로 적응합니다. Green Zone에서는 full detail로, Critical Zone에서는 ultra-compression으로 자동 전환합니다.
Compound Intelligence: 11개 페르소나, 4개 MCP 서버, 50+ 플래그, 18개 커맨드가 협업하여 단일 시스템보다 훨씬 강력한 compound intelligence를 생성합니다. architect + performance + Sequential + Context7 조합은 각각의 합보다 훨씬 강력합니다.
Token Efficiency: 23.3k tokens로 이 모든 시스템을 로드하는 것은, 고급 AI 기능을 위한 필수 투자입니다. Context7 caching (2-5K tokens/query saved), --delegate (40-70% time savings), wave orchestration (30-50% better results)는 이 투자를 수십 배로 회수합니다. Framework Cohesion: 9개 파일이 독립적이면서도 완벽하게 통합되어 있습니다. PRINCIPLES.md의 "Evidence > assumptions"는 ORCHESTRATOR.md의 confidence scoring으로, RULES.md의 "Read before Write"는 File Operation Security로, MODES.md의 TodoWrite Protocol은 todo-logger integration으로 구체화됩니다. ─────────────────────────────────────────────────