mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-23 20:56:59 +00:00
882a0d8356
* refactor: PM Agent complete independence from external MCP servers ## Summary Implement graceful degradation to ensure PM Agent operates fully without any MCP server dependencies. MCP servers now serve as optional enhancements rather than required components. ## Changes ### Responsibility Separation (NEW) - **PM Agent**: Development workflow orchestration (PDCA cycle, task management) - **mindbase**: Memory management (long-term, freshness, error learning) - **Built-in memory**: Session-internal context (volatile) ### 3-Layer Memory Architecture with Fallbacks 1. **Built-in Memory** [OPTIONAL]: Session context via MCP memory server 2. **mindbase** [OPTIONAL]: Long-term semantic search via airis-mcp-gateway 3. **Local Files** [ALWAYS]: Core functionality in docs/memory/ ### Graceful Degradation Implementation - All MCP operations marked with [ALWAYS] or [OPTIONAL] - Explicit IF/ELSE fallback logic for every MCP call - Dual storage: Always write to local files + optionally to mindbase - Smart lookup: Semantic search (if available) → Text search (always works) ### Key Fallback Strategies **Session Start**: - mindbase available: search_conversations() for semantic context - mindbase unavailable: Grep docs/memory/*.jsonl for text-based lookup **Error Detection**: - mindbase available: Semantic search for similar past errors - mindbase unavailable: Grep docs/mistakes/ + solutions_learned.jsonl **Knowledge Capture**: - Always: echo >> docs/memory/patterns_learned.jsonl (persistent) - Optional: mindbase.store() for semantic search enhancement ## Benefits - ✅ Zero external dependencies (100% functionality without MCP) - ✅ Enhanced capabilities when MCPs available (semantic search, freshness) - ✅ No functionality loss, only reduced search intelligence - ✅ Transparent degradation (no error messages, automatic fallback) ## Related Research - Serena MCP investigation: Exposes tools (not resources), memory = markdown files - mindbase superiority: PostgreSQL + pgvector > Serena memory features - Best practices alignment: /Users/kazuki/github/airis-mcp-gateway/docs/mcp-best-practices.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: add PR template and pre-commit config - Add structured PR template with Git workflow checklist - Add pre-commit hooks for secret detection and Conventional Commits - Enforce code quality gates (YAML/JSON/Markdown lint, shellcheck) NOTE: Execute pre-commit inside Docker container to avoid host pollution: docker compose exec workspace uv tool install pre-commit docker compose exec workspace pre-commit run --all-files 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: update PM Agent context with token efficiency architecture - Add Layer 0 Bootstrap (150 tokens, 95% reduction) - Document Intent Classification System (5 complexity levels) - Add Progressive Loading strategy (5-layer) - Document mindbase integration incentive (38% savings) - Update with 2025-10-17 redesign details * refactor: PM Agent command with progressive loading - Replace auto-loading with User Request First philosophy - Add 5-layer progressive context loading - Implement intent classification system - Add workflow metrics collection (.jsonl) - Document graceful degradation strategy * fix: installer improvements Update installer logic for better reliability * docs: add comprehensive development documentation - Add architecture overview - Add PM Agent improvements analysis - Add parallel execution architecture - Add CLI install improvements - Add code style guide - Add project overview - Add install process analysis * docs: add research documentation Add LLM agent token efficiency research and analysis * docs: add suggested commands reference * docs: add session logs and testing documentation - Add session analysis logs - Add testing documentation * feat: migrate CLI to typer + rich for modern UX ## What Changed ### New CLI Architecture (typer + rich) - Created `superclaude/cli/` module with modern typer-based CLI - Replaced custom UI utilities with rich native features - Added type-safe command structure with automatic validation ### Commands Implemented - **install**: Interactive installation with rich UI (progress, panels) - **doctor**: System diagnostics with rich table output - **config**: API key management with format validation ### Technical Improvements - Dependencies: Added typer>=0.9.0, rich>=13.0.0, click>=8.0.0 - Entry Point: Updated pyproject.toml to use `superclaude.cli.app:cli_main` - Tests: Added comprehensive smoke tests (11 passed) ### User Experience Enhancements - Rich formatted help messages with panels and tables - Automatic input validation with retry loops - Clear error messages with actionable suggestions - Non-interactive mode support for CI/CD ## Testing ```bash uv run superclaude --help # ✓ Works uv run superclaude doctor # ✓ Rich table output uv run superclaude config show # ✓ API key management pytest tests/test_cli_smoke.py # ✓ 11 passed, 1 skipped ``` ## Migration Path - ✅ P0: Foundation complete (typer + rich + smoke tests) - 🔜 P1: Pydantic validation models (next sprint) - 🔜 P2: Enhanced error messages (next sprint) - 🔜 P3: API key retry loops (next sprint) ## Performance Impact - **Code Reduction**: Prepared for -300 lines (custom UI → rich) - **Type Safety**: Automatic validation from type hints - **Maintainability**: Framework primitives vs custom code 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: consolidate documentation directories Merged claudedocs/ into docs/research/ for consistent documentation structure. Changes: - Moved all claudedocs/*.md files to docs/research/ - Updated all path references in documentation (EN/KR) - Updated RULES.md and research.md command templates - Removed claudedocs/ directory - Removed ClaudeDocs/ from .gitignore Benefits: - Single source of truth for all research reports - PEP8-compliant lowercase directory naming - Clearer documentation organization - Prevents future claudedocs/ directory creation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * perf: reduce /sc:pm command output from 1652 to 15 lines - Remove 1637 lines of documentation from command file - Keep only minimal bootstrap message - 99% token reduction on command execution - Detailed specs remain in superclaude/agents/pm-agent.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * perf: split PM Agent into execution workflows and guide - Reduce pm-agent.md from 735 to 429 lines (42% reduction) - Move philosophy/examples to docs/agents/pm-agent-guide.md - Execution workflows (PDCA, file ops) stay in pm-agent.md - Guide (examples, quality standards) read once when needed Token savings: - Agent loading: ~6K → ~3.5K tokens (42% reduction) - Total with pm.md: 71% overall reduction 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: consolidate PM Agent optimization and pending changes PM Agent optimization (already committed separately): - superclaude/commands/pm.md: 1652→14 lines - superclaude/agents/pm-agent.md: 735→429 lines - docs/agents/pm-agent-guide.md: new guide file Other pending changes: - setup: framework_docs, mcp, logger, remove ui.py - superclaude: __main__, cli/app, cli/commands/install - tests: test_ui updates - scripts: workflow metrics analysis tools - docs/memory: session state updates 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: simplify MCP installer to unified gateway with legacy mode ## Changes ### MCP Component (setup/components/mcp.py) - Simplified to single airis-mcp-gateway by default - Added legacy mode for individual official servers (sequential-thinking, context7, magic, playwright) - Dynamic prerequisites based on mode: - Default: uv + claude CLI only - Legacy: node (18+) + npm + claude CLI - Removed redundant server definitions ### CLI Integration - Added --legacy flag to setup/cli/commands/install.py - Added --legacy flag to superclaude/cli/commands/install.py - Config passes legacy_mode to component installer ## Benefits - ✅ Simpler: 1 gateway vs 9+ individual servers - ✅ Lighter: No Node.js/npm required (default mode) - ✅ Unified: All tools in one gateway (sequential-thinking, context7, magic, playwright, serena, morphllm, tavily, chrome-devtools, git, puppeteer) - ✅ Flexible: --legacy flag for official servers if needed ## Usage ```bash superclaude install # Default: airis-mcp-gateway (推奨) superclaude install --legacy # Legacy: individual official servers ``` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: rename CoreComponent to FrameworkDocsComponent and add PM token tracking ## Changes ### Component Renaming (setup/components/) - Renamed CoreComponent → FrameworkDocsComponent for clarity - Updated all imports in __init__.py, agents.py, commands.py, mcp_docs.py, modes.py - Better reflects the actual purpose (framework documentation files) ### PM Agent Enhancement (superclaude/commands/pm.md) - Added token usage tracking instructions - PM Agent now reports: 1. Current token usage from system warnings 2. Percentage used (e.g., "27% used" for 54K/200K) 3. Status zone: 🟢 <75% | 🟡 75-85% | 🔴 >85% - Helps prevent token exhaustion during long sessions ### UI Utilities (setup/utils/ui.py) - Added new UI utility module for installer - Provides consistent user interface components ## Benefits - ✅ Clearer component naming (FrameworkDocs vs Core) - ✅ PM Agent token awareness for efficiency - ✅ Better visual feedback with status zones 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor(pm-agent): minimize output verbosity (471→284 lines, 40% reduction) **Problem**: PM Agent generated excessive output with redundant explanations - "System Status Report" with decorative formatting - Repeated "Common Tasks" lists user already knows - Verbose session start/end protocols - Duplicate file operations documentation **Solution**: Compress without losing functionality - Session Start: Reduced to symbol-only status (🟢 branch | nM nD | token%) - Session End: Compressed to essential actions only - File Operations: Consolidated from 2 sections to 1 line reference - Self-Improvement: 5 phases → 1 unified workflow - Output Rules: Explicit constraints to prevent Claude over-explanation **Quality Preservation**: - ✅ All core functions retained (PDCA, memory, patterns, mistakes) - ✅ PARALLEL Read/Write preserved (performance critical) - ✅ Workflow unchanged (session lifecycle intact) - ✅ Added output constraints (prevents verbose generation) **Reduction Method**: - Deleted: Explanatory text, examples, redundant sections - Retained: Action definitions, file paths, core workflows - Added: Explicit output constraints to enforce minimalism **Token Impact**: 40% reduction in agent documentation size **Before**: Verbose multi-section report with task lists **After**: Single line status: 🟢 integration | 15M 17D | 36% 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: consolidate MCP integration to unified gateway **Changes**: - Remove individual MCP server docs (superclaude/mcp/*.md) - Remove MCP server configs (superclaude/mcp/configs/*.json) - Delete MCP docs component (setup/components/mcp_docs.py) - Simplify installer (setup/core/installer.py) - Update components for unified gateway approach **Rationale**: - Unified gateway (airis-mcp-gateway) provides all MCP servers - Individual docs/configs no longer needed (managed centrally) - Reduces maintenance burden and file count - Simplifies installation process **Files Removed**: 17 MCP files (docs + configs) **Installer Changes**: Removed legacy MCP installation logic 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: update version and component metadata - Bump version (pyproject.toml, setup/__init__.py) - Update CLAUDE.md import service references - Reflect component structure changes 🤖 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>
866 lines
42 KiB
Markdown
866 lines
42 KiB
Markdown
# SuperClaude 에이전트 가이드 🤖
|
|
|
|
SuperClaude는 Claude Code가 전문 지식을 위해 호출할 수 있는 15개의 도메인 전문 에이전트를 제공합니다.
|
|
|
|
## 🧪 에이전트 활성화 테스트
|
|
|
|
이 가이드를 사용하기 전에 에이전트 선택이 작동하는지 확인하세요:
|
|
|
|
```bash
|
|
# 수동 에이전트 호출 테스트
|
|
@agent-python-expert "데코레이터 설명해줘"
|
|
# 예상 동작: Python 전문가가 자세한 설명으로 응답
|
|
|
|
# 보안 에이전트 자동 활성화 테스트
|
|
/sc:implement "JWT 인증"
|
|
# 예상 동작: 보안 엔지니어가 자동으로 활성화되어야 함
|
|
|
|
# 프론트엔드 에이전트 자동 활성화 테스트
|
|
/sc:implement "반응형 네비게이션 컴포넌트"
|
|
# 예상 동작: 프론트엔드 아키텍트 + Magic MCP가 활성화되어야 함
|
|
|
|
# 체계적 분석 테스트
|
|
/sc:troubleshoot "느린 API 성능"
|
|
# 예상 동작: 근본 원인 분석가 + 성능 엔지니어 활성화
|
|
|
|
# 수동 및 자동 결합 테스트
|
|
/sc:analyze src/
|
|
@agent-refactoring-expert "개선 사항 제안해줘"
|
|
# 예상 동작: 분석 후 리팩토링 제안
|
|
```
|
|
|
|
**테스트가 실패하면**: `~/.claude/agents/`에 에이전트 파일이 있는지 확인하거나 Claude Code 세션을 재시작하세요
|
|
|
|
## 핵심 개념
|
|
|
|
### SuperClaude 에이전트란?
|
|
|
|
**에이전트**는 Claude Code의 동작을 수정하는 컨텍스트 지시문으로 구현된 전문 AI 도메인 전문가입니다. 각 에이전트는 `superclaude/Agents/` 디렉토리에 있는 신중하게 작성된 `.md` 파일로, 도메인별 전문 지식, 행동 패턴, 문제 해결 접근 방식을 포함합니다.
|
|
|
|
**중요**: 에이전트는 별도의 AI 모델이나 소프트웨어가 아닙니다 - Claude Code가 읽어 전문화된 행동을 채택하는 컨텍스트 구성입니다.
|
|
|
|
### 에이전트 사용 방법 2가지
|
|
|
|
#### 1. @agent- 접두사를 사용한 수동 호출
|
|
```bash
|
|
# 특정 에이전트를 직접 호출
|
|
@agent-security "인증 구현 검토해줘"
|
|
@agent-frontend "반응형 네비게이션 디자인해줘"
|
|
@agent-architect "마이크로서비스 마이그레이션 계획해줘"
|
|
```
|
|
|
|
#### 2. 자동 활성화 (행동 라우팅)
|
|
"자동 활성화"는 Claude Code가 요청의 키워드와 패턴에 따라 적절한 컨텍스트를 참여시키기 위해 행동 지침을 읽는 것을 의미합니다. SuperClaude는 Claude가 가장 적절한 전문가에게 라우팅하기 위해 따르는 행동 가이드라인을 제공합니다.
|
|
|
|
> **📝 에이전트 "자동 활성화" 작동 방식**:
|
|
> 에이전트 활성화는 자동 시스템 로직이 아닙니다 - 컨텍스트 파일의 행동 지침입니다.
|
|
> 문서에서 에이전트가 "자동 활성화"된다고 할 때, Claude Code가 요청의 키워드와 패턴을 기반으로
|
|
> 특정 도메인 전문 지식을 참여시키는 지침을 읽는다는 의미입니다. 이는 기본 메커니즘에 대해
|
|
> 투명하면서도 지능적인 라우팅 경험을 만듭니다.
|
|
|
|
```bash
|
|
# 이러한 명령은 관련 에이전트를 자동 활성화합니다
|
|
/sc:implement "JWT 인증" # → security-engineer 자동 활성화
|
|
/sc:design "React 대시보드" # → frontend-architect 자동 활성화
|
|
/sc:troubleshoot "메모리 누수" # → performance-engineer 자동 활성화
|
|
```
|
|
|
|
**MCP 서버**는 Context7(문서), Sequential(분석), Magic(UI), Playwright(테스팅), Morphllm(코드 변환)과 같은 전문 도구를 통해 향상된 기능을 제공합니다.
|
|
|
|
**도메인 전문가**는 일반적인 접근 방식보다 더 깊고 정확한 솔루션을 제공하기 위해 좁은 전문 영역에 집중합니다.
|
|
|
|
### 에이전트 선택 규칙
|
|
|
|
**우선순위 계층:**
|
|
1. **수동 재정의** - @agent-[name]이 자동 활성화보다 우선합니다
|
|
2. **키워드** - 직접적인 도메인 용어가 주요 에이전트를 트리거합니다
|
|
3. **파일 유형** - 확장자가 언어/프레임워크 전문가를 활성화합니다
|
|
4. **복잡성** - 다단계 작업이 조정 에이전트를 참여시킵니다
|
|
5. **컨텍스트** - 관련 개념이 보완 에이전트를 트리거합니다
|
|
|
|
**충돌 해결:**
|
|
- 수동 호출 → 지정된 에이전트가 우선합니다
|
|
- 여러 일치 → 다중 에이전트 조정
|
|
- 불명확한 컨텍스트 → 요구사항 분석가 활성화
|
|
- 높은 복잡성 → 시스템 아키텍트 감독
|
|
- 품질 우려 → 자동 QA 에이전트 포함
|
|
|
|
**선택 결정 트리:**
|
|
```
|
|
작업 분석 →
|
|
├─ 수동 @agent-? → 지정된 에이전트 사용
|
|
├─ 단일 도메인? → 주요 에이전트 활성화
|
|
├─ 다중 도메인? → 전문 에이전트 조정
|
|
├─ 복잡한 시스템? → system-architect 감독 추가
|
|
├─ 품질 중요? → security + performance + quality 에이전트 포함
|
|
└─ 학습 중심? → learning-guide + technical-writer 추가
|
|
```
|
|
|
|
## 빠른 시작 예제
|
|
|
|
### 수동 에이전트 호출
|
|
```bash
|
|
# @agent- 접두사로 특정 에이전트를 명시적으로 호출
|
|
@agent-python-expert "이 데이터 처리 파이프라인 최적화해줘"
|
|
@agent-quality-engineer "포괄적인 테스트 스위트 만들어줘"
|
|
@agent-technical-writer "이 API를 예제와 함께 문서화해줘"
|
|
@agent-socratic-mentor "이 디자인 패턴 설명해줘"
|
|
```
|
|
|
|
### 자동 에이전트 조정
|
|
```bash
|
|
# 자동 활성화를 트리거하는 명령
|
|
/sc:implement "속도 제한이 있는 JWT 인증"
|
|
# → 트리거: security-engineer + backend-architect + quality-engineer
|
|
|
|
/sc:design "접근 가능한 React 대시보드와 문서"
|
|
# → 트리거: frontend-architect + learning-guide + technical-writer
|
|
|
|
/sc:troubleshoot "간헐적 실패가 있는 느린 배포 파이프라인"
|
|
# → 트리거: devops-architect + performance-engineer + root-cause-analyst
|
|
|
|
/sc:audit "결제 처리 보안 취약점"
|
|
# → 트리거: security-engineer + quality-engineer + refactoring-expert
|
|
```
|
|
|
|
### 수동 및 자동 접근 방식 결합
|
|
```bash
|
|
# 명령으로 시작 (자동 활성화)
|
|
/sc:implement "사용자 프로필 시스템"
|
|
|
|
# 그런 다음 전문가 검토를 명시적으로 추가
|
|
@agent-security "프로필 시스템의 OWASP 규정 준수 검토해줘"
|
|
@agent-performance-engineer "데이터베이스 쿼리 최적화해줘"
|
|
```
|
|
|
|
---
|
|
|
|
## SuperClaude 에이전트 팀 👥
|
|
|
|
### 아키텍처 및 시스템 설계 에이전트 🏗️
|
|
|
|
### system-architect 🏢
|
|
**전문 분야**: 확장성과 서비스 아키텍처에 중점을 둔 대규모 분산 시스템 설계
|
|
|
|
**자동 활성화**:
|
|
- 키워드: "architecture", "microservices", "scalability", "system design", "distributed"
|
|
- 컨텍스트: 다중 서비스 시스템, 아키텍처 결정, 기술 선택
|
|
- 복잡성: >5개 컴포넌트 또는 교차 도메인 통합 요구사항
|
|
|
|
**역량**:
|
|
- 서비스 경계 정의 및 마이크로서비스 분해
|
|
- 기술 스택 선택 및 통합 전략
|
|
- 확장성 계획 및 성능 아키텍처
|
|
- 이벤트 기반 아키텍처 및 메시징 패턴
|
|
- 데이터 흐름 설계 및 시스템 통합
|
|
|
|
**예제**:
|
|
1. **전자상거래 플랫폼**: 이벤트 소싱을 사용한 사용자, 제품, 결제, 알림 서비스를 위한 마이크로서비스 설계
|
|
2. **실시간 분석**: 스트림 처리 및 시계열 저장소를 갖춘 고처리량 데이터 수집 아키텍처
|
|
3. **다중 테넌트 SaaS**: 테넌트 격리, 공유 인프라, 수평 확장 전략을 갖춘 시스템 설계
|
|
|
|
### 성공 기준
|
|
- [ ] 응답에서 시스템 수준 사고가 명확함
|
|
- [ ] 서비스 경계 및 통합 패턴 언급
|
|
- [ ] 확장성 및 신뢰성 고려사항 포함
|
|
- [ ] 기술 스택 권장사항 제공
|
|
|
|
**검증:** `/sc:design "마이크로서비스 플랫폼"`은 system-architect를 활성화해야 함
|
|
**테스트:** 출력에 서비스 분해 및 통합 패턴이 포함되어야 함
|
|
**확인:** 인프라 문제에 대해 devops-architect와 조정해야 함
|
|
|
|
**최적의 협업 대상**: devops-architect(인프라), performance-engineer(최적화), security-engineer(규정 준수)
|
|
|
|
---
|
|
|
|
### backend-architect ⚙️
|
|
**전문 분야**: API 신뢰성과 데이터 무결성을 강조하는 견고한 서버 측 시스템 설계
|
|
|
|
**자동 활성화**:
|
|
- 키워드: "API", "backend", "server", "database", "REST", "GraphQL", "endpoint"
|
|
- 파일 유형: API 스펙, 서버 설정, 데이터베이스 스키마
|
|
- 컨텍스트: 서버 측 로직, 데이터 지속성, API 개발
|
|
|
|
**역량**:
|
|
- RESTful 및 GraphQL API 아키텍처 및 디자인 패턴
|
|
- 데이터베이스 스키마 설계 및 쿼리 최적화 전략
|
|
- 인증, 권한 부여 및 보안 구현
|
|
- 오류 처리, 로깅 및 모니터링 통합
|
|
- 캐싱 전략 및 성능 최적화
|
|
|
|
**예제**:
|
|
1. **사용자 관리 API**: JWT 인증, 역할 기반 액세스 제어 및 속도 제한
|
|
2. **결제 처리**: PCI 규정 준수 트랜잭션 처리, 멱등성 및 감사 추적
|
|
3. **콘텐츠 관리**: 캐싱, 페이지네이션, 실시간 알림을 갖춘 RESTful API
|
|
|
|
**최적의 협업 대상**: security-engineer(인증/보안), performance-engineer(최적화), quality-engineer(테스팅)
|
|
|
|
---
|
|
|
|
### frontend-architect 🎨
|
|
**전문 분야**: 접근성과 사용자 경험에 중점을 둔 현대적인 웹 애플리케이션 아키텍처
|
|
|
|
**자동 활성화**:
|
|
- 키워드: "UI", "frontend", "React", "Vue", "Angular", "component", "accessibility", "responsive"
|
|
- 파일 유형: .jsx, .vue, .ts(프론트엔드), .css, .scss
|
|
- 컨텍스트: 사용자 인터페이스 개발, 컴포넌트 설계, 클라이언트 측 아키텍처
|
|
|
|
**역량**:
|
|
- 컴포넌트 아키텍처 및 디자인 시스템 구현
|
|
- 상태 관리 패턴(Redux, Zustand, Pinia)
|
|
- 접근성 규정 준수(WCAG 2.1) 및 포용적 디자인
|
|
- 성능 최적화 및 번들 분석
|
|
- 프로그레시브 웹 앱 및 모바일 우선 개발
|
|
|
|
**예제**:
|
|
1. **대시보드 인터페이스**: 실시간 업데이트 및 반응형 그리드 레이아웃을 갖춘 접근 가능한 데이터 시각화
|
|
2. **폼 시스템**: 검증, 오류 처리, 접근성 기능을 갖춘 복잡한 다단계 폼
|
|
3. **디자인 시스템**: 일관된 스타일링 및 상호작용 패턴을 갖춘 재사용 가능한 컴포넌트 라이브러리
|
|
|
|
**최적의 협업 대상**: learning-guide(사용자 안내), performance-engineer(최적화), quality-engineer(테스팅)
|
|
|
|
---
|
|
|
|
### devops-architect 🚀
|
|
**전문 분야**: 안정적인 소프트웨어 전달을 위한 인프라 자동화 및 배포 파이프라인 설계
|
|
|
|
**자동 활성화**:
|
|
- 키워드: "deploy", "CI/CD", "Docker", "Kubernetes", "infrastructure", "monitoring", "pipeline"
|
|
- 파일 유형: Dockerfile, docker-compose.yml, k8s 매니페스트, CI 설정
|
|
- 컨텍스트: 배포 프로세스, 인프라 관리, 자동화
|
|
|
|
**역량**:
|
|
- 자동화된 테스팅 및 배포를 갖춘 CI/CD 파이프라인 설계
|
|
- 컨테이너 오케스트레이션 및 Kubernetes 클러스터 관리
|
|
- Terraform 및 클라우드 플랫폼을 사용한 Infrastructure as Code
|
|
- 메트릭, 로그, 추적을 위한 모니터링, 로깅, 관찰성 스택 구현
|
|
- 보안 스캔 및 규정 준수 자동화
|
|
|
|
**예제**:
|
|
1. **마이크로서비스 배포**: 서비스 메시, 자동 확장, blue-green 릴리스를 갖춘 Kubernetes 배포
|
|
2. **다중 환경 파이프라인**: 자동화된 테스팅, 보안 스캔, 단계별 배포를 갖춘 GitOps 워크플로우
|
|
3. **모니터링 스택**: 메트릭, 로그, 추적, 알림 시스템을 갖춘 포괄적인 관찰성
|
|
|
|
**최적의 협업 대상**: system-architect(인프라 계획), security-engineer(규정 준수), performance-engineer(모니터링)
|
|
|
|
---
|
|
|
|
### deep-research-agent 🔬
|
|
**전문 분야**: 적응형 전략과 다중 홉 추론을 사용한 포괄적인 연구
|
|
|
|
**자동 활성화**:
|
|
- 키워드: "research", "investigate", "discover", "explore", "find out", "search for", "latest", "current"
|
|
- 명령어: `/sc:research`가 자동으로 이 에이전트를 활성화
|
|
- 컨텍스트: 철저한 조사가 필요한 복잡한 쿼리, 최신 정보 필요, 사실 확인
|
|
- 복잡성: 여러 도메인에 걸쳐 있거나 반복적 탐색이 필요한 질문
|
|
|
|
**역량**:
|
|
- **적응형 계획 전략**: Planning(직접), Intent(먼저 명확화), Unified(협업)
|
|
- **다중 홉 추론**: 최대 5단계 - 엔티티 확장, 시간적 진행, 개념적 심화, 인과 관계 체인
|
|
- **자기 성찰 메커니즘**: 각 주요 단계 후 진행 상황 평가 및 재계획 트리거
|
|
- **증거 관리**: 명확한 인용, 관련성 점수, 불확실성 인정
|
|
- **도구 오케스트레이션**: Tavily(검색), Playwright(JavaScript 콘텐츠), Sequential(추론)을 사용한 병렬 우선 실행
|
|
- **학습 통합**: Serena 메모리를 통한 패턴 인식 및 전략 재사용
|
|
|
|
**연구 깊이 수준**:
|
|
- **Quick**: 기본 검색, 1홉, 요약 출력
|
|
- **Standard**: 확장 검색, 2-3홉, 구조화된 보고서(기본값)
|
|
- **Deep**: 포괄적 검색, 3-4홉, 상세 분석
|
|
- **Exhaustive**: 최대 깊이, 5홉, 완전한 조사
|
|
|
|
**예제**:
|
|
1. **기술 연구**: `/sc:research "최신 React Server Components 패턴"` → 구현 예제를 포함한 포괄적인 기술 연구
|
|
2. **시장 분석**: `/sc:research "2024년 AI 코딩 어시스턴트 현황" --strategy unified` → 사용자 입력을 포함한 협업 분석
|
|
3. **학술 조사**: `/sc:research "양자 컴퓨팅 돌파구" --depth exhaustive` → 증거 체인을 포함한 포괄적인 문헌 검토
|
|
|
|
**워크플로우 패턴** (6단계):
|
|
1. **이해** (5-10%): 쿼리 복잡성 평가
|
|
2. **계획** (10-15%): 전략 선택 및 병렬 기회 식별
|
|
3. **TodoWrite** (5%): 적응형 작업 계층 구조 생성(3-15개 작업)
|
|
4. **실행** (50-60%): 병렬 검색 및 추출
|
|
5. **추적** (지속적): 진행 상황 및 신뢰도 모니터링
|
|
6. **검증** (10-15%): 증거 체인 확인
|
|
|
|
**출력**: 보고서는 `docs/research/[topic]_[timestamp].md`에 저장됨
|
|
|
|
**최적의 협업 대상**: system-architect(기술 연구), learning-guide(교육 연구), requirements-analyst(시장 연구)
|
|
|
|
### 품질 및 분석 에이전트 🔍
|
|
|
|
### security-engineer 🔒
|
|
**전문 분야**: 위협 모델링 및 취약점 예방에 중점을 둔 애플리케이션 보안 아키텍처
|
|
|
|
**자동 활성화**:
|
|
- 키워드: "security", "auth", "authentication", "vulnerability", "encryption", "compliance", "OWASP"
|
|
- 컨텍스트: 보안 검토, 인증 흐름, 데이터 보호 요구사항
|
|
- 위험 지표: 결제 처리, 사용자 데이터, API 액세스, 규정 준수 필요
|
|
|
|
**역량**:
|
|
- 위협 모델링 및 공격 표면 분석
|
|
- 안전한 인증 및 권한 부여 설계(OAuth, JWT, SAML)
|
|
- 데이터 암호화 전략 및 키 관리
|
|
- 취약점 평가 및 침투 테스트 지침
|
|
- 보안 규정 준수(GDPR, HIPAA, PCI-DSS) 구현
|
|
|
|
**예제**:
|
|
1. **OAuth 구현**: 토큰 새로 고침 및 역할 기반 액세스를 갖춘 안전한 다중 테넌트 인증
|
|
2. **API 보안**: 속도 제한, 입력 검증, SQL 인젝션 방지, 보안 헤더
|
|
3. **데이터 보호**: 저장/전송 중 암호화, 키 순환, 프라이버시 바이 디자인 아키텍처
|
|
|
|
**최적의 협업 대상**: backend-architect(API 보안), quality-engineer(보안 테스팅), root-cause-analyst(사고 대응)
|
|
|
|
---
|
|
|
|
### performance-engineer ⚡
|
|
**전문 분야**: 확장성과 리소스 효율성에 중점을 둔 시스템 성능 최적화
|
|
|
|
**자동 활성화**:
|
|
- 키워드: "performance", "slow", "optimization", "bottleneck", "latency", "memory", "CPU"
|
|
- 컨텍스트: 성능 문제, 확장성 우려, 리소스 제약
|
|
- 메트릭: 응답 시간 >500ms, 높은 메모리 사용량, 낮은 처리량
|
|
|
|
**역량**:
|
|
- 성능 프로파일링 및 병목 현상 식별
|
|
- 데이터베이스 쿼리 최적화 및 인덱싱 전략
|
|
- 캐싱 구현(Redis, CDN, 애플리케이션 레벨)
|
|
- 부하 테스트 및 용량 계획
|
|
- 메모리 관리 및 리소스 최적화
|
|
|
|
**예제**:
|
|
1. **API 최적화**: 캐싱 및 쿼리 최적화를 통해 응답 시간을 2초에서 200ms로 단축
|
|
2. **데이터베이스 확장**: 읽기 복제본, 연결 풀링, 쿼리 결과 캐싱 구현
|
|
3. **프론트엔드 성능**: 번들 최적화, 지연 로딩, CDN 구현으로 <3초 로드 시간 달성
|
|
|
|
**최적의 협업 대상**: system-architect(확장성), devops-architect(인프라), root-cause-analyst(디버깅)
|
|
|
|
---
|
|
|
|
### root-cause-analyst 🔍
|
|
**전문 분야**: 증거 기반 분석 및 가설 테스트를 사용한 체계적인 문제 조사
|
|
|
|
**자동 활성화**:
|
|
- 키워드: "bug", "issue", "problem", "debugging", "investigation", "troubleshoot", "error"
|
|
- 컨텍스트: 시스템 장애, 예상치 못한 동작, 복잡한 다중 컴포넌트 문제
|
|
- 복잡성: 체계적인 조사가 필요한 교차 시스템 문제
|
|
|
|
**역량**:
|
|
- 체계적인 디버깅 방법론 및 근본 원인 분석
|
|
- 시스템 전반의 오류 상관 관계 및 종속성 매핑
|
|
- 실패 조사를 위한 로그 분석 및 패턴 인식
|
|
- 복잡한 문제에 대한 가설 형성 및 테스트
|
|
- 사고 대응 및 사후 분석 절차
|
|
|
|
**예제**:
|
|
1. **데이터베이스 연결 실패**: 연결 풀, 네트워크 타임아웃, 리소스 제한 전반의 간헐적 실패 추적
|
|
2. **결제 처리 오류**: API 로그, 데이터베이스 상태, 외부 서비스 응답을 통한 트랜잭션 실패 조사
|
|
3. **성능 저하**: 메트릭 상관 관계, 리소스 사용량, 코드 변경을 통한 점진적인 둔화 분석
|
|
|
|
**최적의 협업 대상**: performance-engineer(성능 문제), security-engineer(보안 사고), quality-engineer(테스트 실패)
|
|
|
|
---
|
|
|
|
### quality-engineer ✅
|
|
**전문 분야**: 자동화 및 커버리지에 중점을 둔 포괄적인 테스팅 전략 및 품질 보증
|
|
|
|
**자동 활성화**:
|
|
- 키워드: "test", "testing", "quality", "QA", "validation", "coverage", "automation"
|
|
- 컨텍스트: 테스트 계획, 품질 게이트, 검증 요구사항
|
|
- 품질 우려: 코드 커버리지 <80%, 테스트 자동화 부족, 품질 문제
|
|
|
|
**역량**:
|
|
- 테스트 전략 설계(단위, 통합, e2e, 성능 테스팅)
|
|
- 테스트 자동화 프레임워크 구현 및 CI/CD 통합
|
|
- 품질 메트릭 정의 및 모니터링(커버리지, 결함률)
|
|
- 엣지 케이스 식별 및 경계 테스팅 시나리오
|
|
- 접근성 테스팅 및 규정 준수 검증
|
|
|
|
**예제**:
|
|
1. **전자상거래 테스팅**: 사용자 흐름, 결제 처리, 재고 관리를 다루는 포괄적인 테스트 스위트
|
|
2. **API 테스팅**: REST/GraphQL API에 대한 자동화된 계약 테스팅, 부하 테스팅, 보안 테스팅
|
|
3. **접근성 검증**: 자동화 및 수동 접근성 감사를 통한 WCAG 2.1 규정 준수 테스팅
|
|
|
|
**최적의 협업 대상**: security-engineer(보안 테스팅), performance-engineer(부하 테스팅), frontend-architect(UI 테스팅)
|
|
|
|
---
|
|
|
|
### refactoring-expert 🔧
|
|
**전문 분야**: 체계적인 리팩토링 및 기술 부채 관리를 통한 코드 품질 개선
|
|
|
|
**자동 활성화**:
|
|
- 키워드: "refactor", "clean code", "technical debt", "SOLID", "maintainability", "code smell"
|
|
- 컨텍스트: 레거시 코드 개선, 아키텍처 업데이트, 코드 품질 문제
|
|
- 품질 지표: 높은 복잡성, 중복 코드, 낮은 테스트 커버리지
|
|
|
|
**역량**:
|
|
- SOLID 원칙 적용 및 디자인 패턴 구현
|
|
- 코드 냄새 식별 및 체계적인 제거
|
|
- 레거시 코드 현대화 전략 및 마이그레이션 계획
|
|
- 기술 부채 평가 및 우선순위 프레임워크
|
|
- 코드 구조 개선 및 아키텍처 리팩토링
|
|
|
|
**예제**:
|
|
1. **레거시 현대화**: 모놀리식 애플리케이션을 테스트 가능성이 향상된 모듈형 아키텍처로 변환
|
|
2. **디자인 패턴**: 결제 처리에 Strategy 패턴 구현으로 결합도 감소 및 확장성 향상
|
|
3. **코드 정리**: 중복 코드 제거, 명명 규칙 개선, 재사용 가능한 컴포넌트 추출
|
|
|
|
**최적의 협업 대상**: system-architect(아키텍처 개선), quality-engineer(테스팅 전략), python-expert(언어별 패턴)
|
|
|
|
### 전문 개발 에이전트 🎯
|
|
|
|
### python-expert 🐍
|
|
**전문 분야**: 현대적인 프레임워크와 성능을 강조하는 프로덕션급 Python 개발
|
|
|
|
**자동 활성화**:
|
|
- 키워드: "Python", "Django", "FastAPI", "Flask", "asyncio", "pandas", "pytest"
|
|
- 파일 유형: .py, requirements.txt, pyproject.toml, Pipfile
|
|
- 컨텍스트: Python 개발 작업, API 개발, 데이터 처리, 테스팅
|
|
|
|
**역량**:
|
|
- 현대적인 Python 아키텍처 패턴 및 프레임워크 선택
|
|
- asyncio 및 concurrent futures를 사용한 비동기 프로그래밍
|
|
- 프로파일링 및 알고리즘 개선을 통한 성능 최적화
|
|
- pytest, 픽스처, 테스트 자동화를 사용한 테스팅 전략
|
|
- pip, poetry, Docker를 사용한 패키지 관리 및 배포
|
|
|
|
**예제**:
|
|
1. **FastAPI 마이크로서비스**: Pydantic 검증, 의존성 주입, OpenAPI 문서를 갖춘 고성능 비동기 API
|
|
2. **데이터 파이프라인**: 대규모 데이터셋에 대한 오류 처리, 로깅, 병렬 처리를 갖춘 Pandas 기반 ETL
|
|
3. **Django 애플리케이션**: 사용자 정의 사용자 모델, API 엔드포인트, 포괄적인 테스트 커버리지를 갖춘 풀스택 웹 앱
|
|
|
|
**최적의 협업 대상**: backend-architect(API 설계), quality-engineer(테스팅), performance-engineer(최적화)
|
|
|
|
---
|
|
|
|
### requirements-analyst 📝
|
|
**전문 분야**: 체계적인 이해관계자 분석을 통한 요구사항 발견 및 사양 개발
|
|
|
|
**자동 활성화**:
|
|
- 키워드: "requirements", "specification", "PRD", "user story", "functional", "scope", "stakeholder"
|
|
- 컨텍스트: 프로젝트 시작, 불명확한 요구사항, 범위 정의 필요
|
|
- 복잡성: 다중 이해관계자 프로젝트, 불명확한 목표, 상충하는 요구사항
|
|
|
|
**역량**:
|
|
- 이해관계자 인터뷰 및 워크숍을 통한 요구사항 도출
|
|
- 승인 기준 및 완료 정의를 갖춘 사용자 스토리 작성
|
|
- 기능 및 비기능 사양 문서화
|
|
- 이해관계자 분석 및 요구사항 우선순위 프레임워크
|
|
- 범위 관리 및 변경 제어 프로세스
|
|
|
|
**예제**:
|
|
1. **제품 요구사항 문서**: 사용자 페르소나, 기능 사양, 성공 메트릭을 포함한 핀테크 모바일 앱 포괄적 PRD
|
|
2. **API 사양**: 오류 처리, 보안, 성능 기준을 갖춘 결제 처리 API에 대한 상세 요구사항
|
|
3. **마이그레이션 요구사항**: 데이터 마이그레이션, 사용자 교육, 롤백 절차를 갖춘 레거시 시스템 현대화 요구사항
|
|
|
|
**최적의 협업 대상**: system-architect(기술적 실현 가능성), technical-writer(문서화), learning-guide(사용자 안내)
|
|
|
|
### 커뮤니케이션 및 학습 에이전트 📚
|
|
|
|
### technical-writer 📚
|
|
**전문 분야**: 대상 분석 및 명확성에 중점을 둔 기술 문서화 및 커뮤니케이션
|
|
|
|
**자동 활성화**:
|
|
- 키워드: "documentation", "readme", "API docs", "user guide", "technical writing", "manual"
|
|
- 컨텍스트: 문서화 요청, API 문서화, 사용자 가이드, 기술 설명
|
|
- 파일 유형: .md, .rst, API 스펙, 문서 파일
|
|
|
|
**역량**:
|
|
- 기술 문서화 아키텍처 및 정보 설계
|
|
- 다양한 기술 수준에 대한 대상 분석 및 콘텐츠 타겟팅
|
|
- 작동 예제 및 통합 지침을 포함한 API 문서화
|
|
- 단계별 절차 및 문제 해결을 포함한 사용자 가이드 작성
|
|
- 접근성 표준 적용 및 포용적 언어 사용
|
|
|
|
**예제**:
|
|
1. **API 문서화**: 인증, 엔드포인트, 예제, SDK 통합 가이드를 포함한 포괄적인 REST API 문서
|
|
2. **사용자 매뉴얼**: 스크린샷, 문제 해결, FAQ 섹션을 포함한 단계별 설치 및 구성 가이드
|
|
3. **기술 사양**: 다이어그램, 데이터 흐름, 구현 세부사항을 포함한 시스템 아키텍처 문서
|
|
|
|
**최적의 협업 대상**: requirements-analyst(사양 명확성), learning-guide(교육 콘텐츠), frontend-architect(UI 문서화)
|
|
|
|
---
|
|
|
|
### learning-guide 🎓
|
|
**전문 분야**: 기술 개발 및 멘토십에 중점을 둔 교육 콘텐츠 설계 및 점진적 학습
|
|
|
|
**자동 활성화**:
|
|
- 키워드: "explain", "learn", "tutorial", "beginner", "teaching", "education", "training"
|
|
- 컨텍스트: 교육 요청, 개념 설명, 기술 개발, 학습 경로
|
|
- 복잡성: 단계별 분해 및 점진적 이해가 필요한 복잡한 주제
|
|
|
|
**역량**:
|
|
- 점진적 기술 개발을 갖춘 학습 경로 설계
|
|
- 유추 및 예제를 통한 복잡한 개념 설명
|
|
- 실습 연습을 포함한 대화형 튜토리얼 생성
|
|
- 기술 평가 및 역량 평가 프레임워크
|
|
- 멘토십 전략 및 개인화된 학습 접근법
|
|
|
|
**예제**:
|
|
1. **프로그래밍 튜토리얼**: 실습 연습, 코드 예제, 점진적 복잡성을 포함한 대화형 React 튜토리얼
|
|
2. **개념 설명**: 시각적 다이어그램 및 연습 문제를 포함한 실제 예제를 통한 데이터베이스 정규화 설명
|
|
3. **기술 평가**: 실제 프로젝트 및 피드백을 포함한 풀스택 개발을 위한 포괄적인 평가 프레임워크
|
|
|
|
**최적의 협업 대상**: technical-writer(교육 문서화), frontend-architect(대화형 학습), requirements-analyst(학습 목표)
|
|
|
|
---
|
|
|
|
## 에이전트 조정 및 통합 🤝
|
|
|
|
### 조정 패턴
|
|
|
|
**아키텍처 팀**:
|
|
- **풀스택 개발**: frontend-architect + backend-architect + security-engineer + quality-engineer
|
|
- **시스템 설계**: system-architect + devops-architect + performance-engineer + security-engineer
|
|
- **레거시 현대화**: refactoring-expert + system-architect + quality-engineer + technical-writer
|
|
|
|
**품질 팀**:
|
|
- **보안 감사**: security-engineer + quality-engineer + root-cause-analyst + requirements-analyst
|
|
- **성능 최적화**: performance-engineer + system-architect + devops-architect + root-cause-analyst
|
|
- **테스팅 전략**: quality-engineer + security-engineer + performance-engineer + frontend-architect
|
|
|
|
**커뮤니케이션 팀**:
|
|
- **문서화 프로젝트**: technical-writer + requirements-analyst + learning-guide + 도메인 전문가
|
|
- **학습 플랫폼**: learning-guide + frontend-architect + technical-writer + quality-engineer
|
|
- **API 문서화**: backend-architect + technical-writer + security-engineer + quality-engineer
|
|
|
|
### MCP 서버 통합
|
|
|
|
**MCP 서버를 통한 향상된 기능**:
|
|
- **Context7**: 모든 아키텍트 및 전문가를 위한 공식 문서화 패턴
|
|
- **Sequential**: root-cause-analyst, system-architect, performance-engineer를 위한 다단계 분석
|
|
- **Magic**: frontend-architect, learning-guide 대화형 콘텐츠를 위한 UI 생성
|
|
- **Playwright**: quality-engineer를 위한 브라우저 테스팅, frontend-architect를 위한 접근성 검증
|
|
- **Morphllm**: refactoring-expert를 위한 코드 변환, python-expert를 위한 대량 변경
|
|
- **Serena**: 모든 에이전트를 위한 프로젝트 메모리, 세션 전반의 컨텍스트 보존
|
|
|
|
### 에이전트 활성화 문제 해결
|
|
|
|
## 문제 해결
|
|
|
|
문제 해결 도움말은 다음을 참조하세요:
|
|
- [일반적인 문제](../reference/common-issues.md) - 자주 발생하는 문제에 대한 빠른 수정
|
|
- [문제 해결 가이드](../reference/troubleshooting.md) - 포괄적인 문제 해결
|
|
|
|
### 일반적인 문제
|
|
- **에이전트 활성화 없음**: 도메인 키워드 사용: "security", "performance", "frontend"
|
|
- **잘못된 에이전트 선택**: 에이전트 문서의 트리거 키워드 확인
|
|
- **너무 많은 에이전트**: 주요 도메인에 키워드 집중 또는 `/sc:focus [domain]` 사용
|
|
- **에이전트가 조정하지 않음**: 작업 복잡성 증가 또는 다중 도메인 키워드 사용
|
|
- **에이전트 전문 지식 불일치**: 더 구체적인 기술 용어 사용
|
|
|
|
### 즉각적인 수정
|
|
- **에이전트 활성화 강제**: 요청에 명시적 도메인 키워드 사용
|
|
- **에이전트 선택 재설정**: Claude Code 세션을 재시작하여 에이전트 상태 재설정
|
|
- **에이전트 패턴 확인**: 에이전트 문서의 트리거 키워드 검토
|
|
- **기본 활성화 테스트**: `/sc:implement "security auth"`로 security-engineer 테스트
|
|
|
|
### 에이전트별 문제 해결
|
|
|
|
**보안 에이전트 없음:**
|
|
```bash
|
|
# 문제: 보안 우려가 security-engineer를 트리거하지 않음
|
|
# 빠른 수정: 명시적 보안 키워드 사용
|
|
"implement authentication" # 일반적 - 트리거하지 않을 수 있음
|
|
"implement JWT authentication security" # 명시적 - security-engineer 트리거
|
|
"secure user login with encryption" # 보안 중심 - security-engineer 트리거
|
|
```
|
|
|
|
**성능 에이전트 없음:**
|
|
```bash
|
|
# 문제: 성능 문제가 performance-engineer를 트리거하지 않음
|
|
# 빠른 수정: 성능별 용어 사용
|
|
"make it faster" # 모호함 - 트리거하지 않을 수 있음
|
|
"optimize slow database queries" # 구체적 - performance-engineer 트리거
|
|
"reduce API latency and bottlenecks" # 성능 중심 - performance-engineer 트리거
|
|
```
|
|
|
|
**아키텍처 에이전트 없음:**
|
|
```bash
|
|
# 문제: 시스템 설계가 아키텍처 에이전트를 트리거하지 않음
|
|
# 빠른 수정: 아키텍처 키워드 사용
|
|
"build an app" # 일반적 - 기본 에이전트 트리거
|
|
"design microservices architecture" # 구체적 - system-architect 트리거
|
|
"scalable distributed system design" # 아키텍처 중심 - system-architect 트리거
|
|
```
|
|
|
|
**잘못된 에이전트 조합:**
|
|
```bash
|
|
# 문제: 백엔드 작업에 프론트엔드 에이전트 활성화
|
|
# 빠른 수정: 도메인별 용어 사용
|
|
"create user interface" # frontend-architect를 트리거할 수 있음
|
|
"create REST API endpoints" # 구체적 - backend-architect 트리거
|
|
"implement server-side authentication" # 백엔드 중심 - backend-architect 트리거
|
|
```
|
|
|
|
### 지원 수준
|
|
|
|
**빠른 수정:**
|
|
- 에이전트 트리거 테이블의 명시적 도메인 키워드 사용
|
|
- Claude Code 세션 재시작 시도
|
|
- 혼란을 피하기 위해 단일 도메인에 집중
|
|
|
|
**상세 도움말:**
|
|
- 에이전트 설치 문제는 [일반적인 문제 가이드](../reference/common-issues.md) 참조
|
|
- 대상 에이전트의 트리거 키워드 검토
|
|
|
|
**전문가 지원:**
|
|
- `SuperClaude install --diagnose` 사용
|
|
- 조정 분석은 [진단 참조 가이드](../reference/diagnostic-reference.md) 참조
|
|
|
|
**커뮤니티 지원:**
|
|
- [GitHub Issues](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues)에서 문제 보고
|
|
- 예상 대비 실제 에이전트 활성화 예제 포함
|
|
|
|
### 성공 검증
|
|
|
|
에이전트 수정 적용 후 테스트:
|
|
- [ ] 도메인별 요청이 올바른 에이전트 활성화 (security → security-engineer)
|
|
- [ ] 복잡한 작업이 다중 에이전트 조정 트리거 (3개 이상 에이전트)
|
|
- [ ] 에이전트 전문 지식이 작업 요구사항과 일치 (API → backend-architect)
|
|
- [ ] 적절한 경우 품질 에이전트 자동 포함 (security, performance, testing)
|
|
- [ ] 응답에 도메인 전문 지식 및 전문 지식 표시
|
|
|
|
## 빠른 문제 해결 (레거시)
|
|
- **에이전트 활성화 없음** → 도메인 키워드 사용: "security", "performance", "frontend"
|
|
- **잘못된 에이전트** → 에이전트 문서의 트리거 키워드 확인
|
|
- **너무 많은 에이전트** → 주요 도메인에 키워드 집중
|
|
- **에이전트가 조정하지 않음** → 작업 복잡성 증가 또는 다중 도메인 키워드 사용
|
|
|
|
**에이전트가 활성화되지 않나요?**
|
|
1. **키워드 확인**: 도메인별 용어 사용 (예: security-engineer의 경우 "login"이 아닌 "authentication")
|
|
2. **컨텍스트 추가**: 파일 유형, 프레임워크 또는 특정 기술 포함
|
|
3. **복잡성 증가**: 다중 도메인 문제가 더 많은 에이전트 트리거
|
|
4. **예제 사용**: 에이전트 전문 지식과 일치하는 구체적인 시나리오 참조
|
|
|
|
**너무 많은 에이전트?**
|
|
- 주요 도메인 필요에 키워드 집중
|
|
- `/sc:focus [domain]`을 사용하여 범위 제한
|
|
- 특정 에이전트로 시작하고 필요에 따라 확장
|
|
|
|
**잘못된 에이전트?**
|
|
- 에이전트 문서의 트리거 키워드 검토
|
|
- 대상 도메인에 더 구체적인 용어 사용
|
|
- 명시적 요구사항 또는 제약조건 추가
|
|
|
|
## 빠른 참조 📋
|
|
|
|
### 에이전트 트리거 조회
|
|
|
|
| 트리거 유형 | 키워드/패턴 | 활성화된 에이전트 |
|
|
|-------------|-------------------|------------------|
|
|
| **보안** | "auth", "security", "vulnerability", "encryption" | security-engineer |
|
|
| **성능** | "slow", "optimization", "bottleneck", "latency" | performance-engineer |
|
|
| **프론트엔드** | "UI", "React", "Vue", "component", "responsive" | frontend-architect |
|
|
| **백엔드** | "API", "server", "database", "REST", "GraphQL" | backend-architect |
|
|
| **테스팅** | "test", "QA", "validation", "coverage" | quality-engineer |
|
|
| **DevOps** | "deploy", "CI/CD", "Docker", "Kubernetes" | devops-architect |
|
|
| **아키텍처** | "architecture", "microservices", "scalability" | system-architect |
|
|
| **Python** | ".py", "Django", "FastAPI", "asyncio" | python-expert |
|
|
| **문제** | "bug", "issue", "debugging", "troubleshoot" | root-cause-analyst |
|
|
| **코드 품질** | "refactor", "clean code", "technical debt" | refactoring-expert |
|
|
| **문서화** | "documentation", "readme", "API docs" | technical-writer |
|
|
| **학습** | "explain", "tutorial", "beginner", "teaching" | learning-guide |
|
|
| **요구사항** | "requirements", "PRD", "specification" | requirements-analyst |
|
|
| **연구** | "research", "investigate", "latest", "current" | deep-research-agent |
|
|
|
|
### 명령어-에이전트 매핑
|
|
|
|
| 명령어 | 주요 에이전트 | 지원 에이전트 |
|
|
|---------|----------------|-------------------|
|
|
| `/sc:implement` | 도메인 아키텍트 (frontend, backend) | security-engineer, quality-engineer |
|
|
| `/sc:analyze` | quality-engineer, security-engineer | performance-engineer, root-cause-analyst |
|
|
| `/sc:troubleshoot` | root-cause-analyst | 도메인 전문가, performance-engineer |
|
|
| `/sc:improve` | refactoring-expert | quality-engineer, performance-engineer |
|
|
| `/sc:document` | technical-writer | 도메인 전문가, learning-guide |
|
|
| `/sc:design` | system-architect | 도메인 아키텍트, requirements-analyst |
|
|
| `/sc:test` | quality-engineer | security-engineer, performance-engineer |
|
|
| `/sc:explain` | learning-guide | technical-writer, 도메인 전문가 |
|
|
| `/sc:research` | deep-research-agent | 기술 전문가, learning-guide |
|
|
|
|
### 효과적인 에이전트 조합
|
|
|
|
**개발 워크플로우**:
|
|
- 웹 애플리케이션: frontend-architect + backend-architect + security-engineer + quality-engineer + devops-architect
|
|
- API 개발: backend-architect + security-engineer + technical-writer + quality-engineer
|
|
- 데이터 플랫폼: python-expert + performance-engineer + security-engineer + system-architect
|
|
|
|
**분석 워크플로우**:
|
|
- 보안 감사: security-engineer + quality-engineer + root-cause-analyst + technical-writer
|
|
- 성능 조사: performance-engineer + root-cause-analyst + system-architect + devops-architect
|
|
- 레거시 평가: refactoring-expert + system-architect + quality-engineer + security-engineer + technical-writer
|
|
|
|
**커뮤니케이션 워크플로우**:
|
|
- 기술 문서화: technical-writer + requirements-analyst + 도메인 전문가 + learning-guide
|
|
- 교육 콘텐츠: learning-guide + technical-writer + frontend-architect + quality-engineer
|
|
|
|
## 모범 사례 💡
|
|
|
|
### 시작하기 (간단한 접근법)
|
|
|
|
**자연어 우선:**
|
|
1. **목표 설명**: 도메인별 키워드를 사용한 자연어 사용
|
|
2. **자동 활성화 신뢰**: 시스템이 자동으로 적절한 에이전트로 라우팅하도록 허용
|
|
3. **패턴에서 학습**: 다양한 요청 유형에 대해 어떤 에이전트가 활성화되는지 관찰
|
|
4. **반복 및 개선**: 추가 전문 에이전트를 참여시키기 위해 구체성 추가
|
|
|
|
### 에이전트 선택 최적화
|
|
|
|
**효과적인 키워드 사용:**
|
|
- **구체적 > 일반적**: security-engineer를 위해 "login" 대신 "authentication" 사용
|
|
- **기술 용어**: 프레임워크 이름, 기술, 특정 과제 포함
|
|
- **컨텍스트 단서**: 파일 유형, 프로젝트 범위, 복잡성 지표 언급
|
|
- **품질 키워드**: 포괄적인 커버리지를 위해 "security", "performance", "accessibility" 추가
|
|
|
|
**요청 최적화 예제:**
|
|
```bash
|
|
# 일반적 (제한된 에이전트 활성화)
|
|
"로그인 기능 수정"
|
|
|
|
# 최적화됨 (다중 에이전트 조정)
|
|
"속도 제한 및 접근성 규정 준수를 갖춘 안전한 JWT 인증 구현"
|
|
# → 트리거: security-engineer + backend-architect + frontend-architect + quality-engineer
|
|
```
|
|
|
|
### 일반적인 사용 패턴
|
|
|
|
**개발 워크플로우:**
|
|
```bash
|
|
# 풀스택 기능 개발
|
|
/sc:implement "실시간 알림이 있는 반응형 사용자 대시보드"
|
|
# → frontend-architect + backend-architect + performance-engineer
|
|
|
|
# 문서화를 포함한 API 개발
|
|
/sc:create "포괄적인 문서가 있는 결제 처리를 위한 REST API"
|
|
# → backend-architect + security-engineer + technical-writer + quality-engineer
|
|
|
|
# 성능 최적화 조사
|
|
/sc:troubleshoot "사용자 경험에 영향을 미치는 느린 데이터베이스 쿼리"
|
|
# → performance-engineer + root-cause-analyst + backend-architect
|
|
```
|
|
|
|
**분석 워크플로우:**
|
|
```bash
|
|
# 보안 평가
|
|
/sc:analyze "GDPR 규정 준수 취약점에 대한 인증 시스템"
|
|
# → security-engineer + quality-engineer + requirements-analyst
|
|
|
|
# 코드 품질 검토
|
|
/sc:review "현대화 기회를 위한 레거시 코드베이스"
|
|
# → refactoring-expert + system-architect + quality-engineer + technical-writer
|
|
|
|
# 학습 및 설명
|
|
/sc:explain "실습 예제가 있는 마이크로서비스 패턴"
|
|
# → system-architect + learning-guide + technical-writer
|
|
```
|
|
|
|
### 고급 에이전트 조정
|
|
|
|
**다중 도메인 프로젝트:**
|
|
- **광범위하게 시작**: 아키텍처 에이전트를 참여시키기 위해 시스템 수준 키워드로 시작
|
|
- **구체성 추가**: 전문 에이전트를 활성화하기 위해 도메인별 필요 포함
|
|
- **품질 통합**: 보안, 성능, 테스팅 관점 자동 포함
|
|
- **문서화 포함**: 포괄적인 커버리지를 위해 학습 또는 문서화 필요 추가
|
|
|
|
**에이전트 선택 문제 해결:**
|
|
|
|
**문제: 잘못된 에이전트 활성화**
|
|
- 해결책: 더 구체적인 도메인 용어 사용
|
|
- 예제: "database optimization" → performance-engineer + backend-architect
|
|
|
|
**문제: 에이전트가 충분하지 않음**
|
|
- 해결책: 복잡성 지표 및 교차 도메인 키워드 증가
|
|
- 예제: 요청에 "security", "performance", "documentation" 추가
|
|
|
|
**문제: 에이전트가 너무 많음**
|
|
- 해결책: 구체적인 기술 용어로 주요 도메인에 집중
|
|
- 예제: 범위를 제한하기 위해 "/sc:focus backend" 사용
|
|
|
|
### 품질 중심 개발
|
|
|
|
**보안 우선 접근법:**
|
|
도메인 전문가와 함께 security-engineer를 자동으로 참여시키기 위해 개발 요청에 항상 보안 고려사항을 포함하세요.
|
|
|
|
**성능 통합:**
|
|
처음부터 performance-engineer 조정을 보장하기 위해 성능 키워드("빠른", "효율적", "확장 가능")를 포함하세요.
|
|
|
|
**접근성 규정 준수:**
|
|
프론트엔드 개발에서 접근성 검증을 자동으로 포함하기 위해 "accessible", "WCAG" 또는 "inclusive"를 사용하세요.
|
|
|
|
**문서화 문화:**
|
|
자동 technical-writer 포함 및 지식 전달을 위해 요청에 "documented", "explained" 또는 "tutorial"을 추가하세요.
|
|
|
|
---
|
|
|
|
## 에이전트 지능 이해 🧠
|
|
|
|
### 에이전트를 효과적으로 만드는 것
|
|
|
|
**도메인 전문 지식**: 각 에이전트는 도메인별 전문 지식 패턴, 행동 접근법, 문제 해결 방법론을 가지고 있습니다.
|
|
|
|
**컨텍스트 활성화**: 에이전트는 키워드뿐만 아니라 요청 컨텍스트를 분석하여 관련성 및 참여 수준을 결정합니다.
|
|
|
|
**협업 지능**: 다중 에이전트 조정은 개별 에이전트 능력을 초과하는 시너지 효과를 생성합니다.
|
|
|
|
**적응형 학습**: 에이전트 선택은 요청 패턴 및 성공적인 조정 결과를 기반으로 향상됩니다.
|
|
|
|
### 에이전트 vs. 전통적인 AI
|
|
|
|
**전통적인 접근법**: 단일 AI가 다양한 수준의 전문 지식으로 모든 도메인을 처리
|
|
**에이전트 접근법**: 전문가들이 깊은 도메인 지식과 집중된 문제 해결로 협업
|
|
|
|
**이점**:
|
|
- 도메인별 작업에서 더 높은 정확도
|
|
- 더 정교한 문제 해결 방법론
|
|
- 전문가 검토를 통한 더 나은 품질 보증
|
|
- 조정된 다중 관점 분석
|
|
|
|
### 시스템을 신뢰하고 패턴을 이해하세요
|
|
|
|
**기대할 수 있는 것**:
|
|
- 적절한 도메인 전문가에게 자동 라우팅
|
|
- 복잡한 작업에 대한 다중 에이전트 조정
|
|
- 자동 QA 에이전트 포함을 통한 품질 통합
|
|
- 교육 에이전트 활성화를 통한 학습 기회
|
|
|
|
**걱정하지 않아도 되는 것**:
|
|
- 수동 에이전트 선택 또는 구성
|
|
- 복잡한 라우팅 규칙 또는 에이전트 관리
|
|
- 에이전트 구성 또는 조정
|
|
- 에이전트 상호작용 마이크로 관리
|
|
|
|
---
|
|
|
|
## 관련 리소스 📚
|
|
|
|
### 필수 문서
|
|
- **[명령어 가이드](commands.md)** - 최적의 에이전트 조정을 트리거하는 SuperClaude 명령어 마스터
|
|
- **[MCP 서버](mcp-servers.md)** - 전문 도구 통합을 통한 향상된 에이전트 기능
|
|
- **[세션 관리](session-management.md)** - 영구 에이전트 컨텍스트를 사용한 장기 워크플로우
|
|
|
|
### 고급 사용
|
|
- **[행동 모드](modes.md)** - 향상된 에이전트 조정을 위한 컨텍스트 최적화
|
|
- **[시작하기](../getting-started/quick-start.md)** - 에이전트 최적화를 위한 전문가 기법
|
|
- **[예제 모음](../reference/examples-cookbook.md)** - 실제 에이전트 조정 패턴
|
|
|
|
### 개발 리소스
|
|
- **[기술 아키텍처](../developer-guide/technical-architecture.md)** - SuperClaude의 에이전트 시스템 설계 이해
|
|
- **[기여하기](../developer-guide/contributing-code.md)** - 에이전트 기능 및 조정 패턴 확장
|
|
|
|
---
|
|
|
|
## 에이전트 여정 🚀
|
|
|
|
**1주차: 자연스러운 사용**
|
|
자연어 설명으로 시작하세요. 어떤 에이전트가 활성화되는지, 그리고 그 이유를 주목하세요. 프로세스를 과도하게 생각하지 않고 키워드 패턴에 대한 직관을 구축하세요.
|
|
|
|
**2-3주차: 패턴 인식**
|
|
에이전트 조정 패턴을 관찰하세요. 복잡성과 도메인 키워드가 에이전트 선택에 어떻게 영향을 미치는지 이해하세요. 더 나은 조정을 위해 요청 문구를 최적화하기 시작하세요.
|
|
|
|
**2개월 이상: 전문가 조정**
|
|
최적의 에이전트 조합을 트리거하는 다중 도메인 요청을 마스터하세요. 효과적인 에이전트 선택을 위한 문제 해결 기법을 활용하세요. 복잡한 워크플로우를 위한 고급 패턴을 사용하세요.
|
|
|
|
**SuperClaude 이점:**
|
|
간단하고 자연스러운 언어 요청을 통해 조정된 응답으로 작동하는 14명의 전문 AI 전문가의 힘을 경험하세요. 구성도, 관리도 필요 없이, 필요에 따라 확장되는 지능적인 협업만 있습니다.
|
|
|
|
🎯 **지능적인 에이전트 조정을 경험할 준비가 되셨나요? `/sc:implement`로 시작하여 전문 AI 협업의 마법을 발견하세요.**
|
|
|