docs/user-guide-kr/agents.md
SuperClaude는 Claude Code가 전문 지식을 위해 호출할 수 있는 15개의 도메인 전문 에이전트를 제공합니다.
이 가이드를 사용하기 전에 에이전트 선택이 작동하는지 확인하세요:
# 수동 에이전트 호출 테스트
@agent-python-expert "데코레이터 설명해줘"
# 예상 동작: Python 전문가가 자세한 설명으로 응답
# 보안 에이전트 자동 활성화 테스트
/sc:implement "JWT 인증"
# 예상 동작: 보안 엔지니어가 자동으로 활성화되어야 함
# 프론트엔드 에이전트 자동 활성화 테스트
/sc:implement "반응형 네비게이션 컴포넌트"
# 예상 동작: 프론트엔드 아키텍트 + Magic MCP가 활성화되어야 함
# 체계적 분석 테스트
/sc:troubleshoot "느린 API 성능"
# 예상 동작: 근본 원인 분석가 + 성능 엔지니어 활성화
# 수동 및 자동 결합 테스트
/sc:analyze src/
@agent-refactoring-expert "개선 사항 제안해줘"
# 예상 동작: 분석 후 리팩토링 제안
테스트가 실패하면: ~/.claude/agents/에 에이전트 파일이 있는지 확인하거나 Claude Code 세션을 재시작하세요
에이전트는 Claude Code의 동작을 수정하는 컨텍스트 지시문으로 구현된 전문 AI 도메인 전문가입니다. 각 에이전트는 superclaude/Agents/ 디렉토리에 있는 신중하게 작성된 .md 파일로, 도메인별 전문 지식, 행동 패턴, 문제 해결 접근 방식을 포함합니다.
중요: 에이전트는 별도의 AI 모델이나 소프트웨어가 아닙니다 - Claude Code가 읽어 전문화된 행동을 채택하는 컨텍스트 구성입니다.
# 특정 에이전트를 직접 호출
@agent-security "인증 구현 검토해줘"
@agent-frontend "반응형 네비게이션 디자인해줘"
@agent-architect "마이크로서비스 마이그레이션 계획해줘"
"자동 활성화"는 Claude Code가 요청의 키워드와 패턴에 따라 적절한 컨텍스트를 참여시키기 위해 행동 지침을 읽는 것을 의미합니다. SuperClaude는 Claude가 가장 적절한 전문가에게 라우팅하기 위해 따르는 행동 가이드라인을 제공합니다.
📝 에이전트 "자동 활성화" 작동 방식: 에이전트 활성화는 자동 시스템 로직이 아닙니다 - 컨텍스트 파일의 행동 지침입니다. 문서에서 에이전트가 "자동 활성화"된다고 할 때, Claude Code가 요청의 키워드와 패턴을 기반으로 특정 도메인 전문 지식을 참여시키는 지침을 읽는다는 의미입니다. 이는 기본 메커니즘에 대해 투명하면서도 지능적인 라우팅 경험을 만듭니다.
# 이러한 명령은 관련 에이전트를 자동 활성화합니다
/sc:implement "JWT 인증" # → security-engineer 자동 활성화
/sc:design "React 대시보드" # → frontend-architect 자동 활성화
/sc:troubleshoot "메모리 누수" # → performance-engineer 자동 활성화
MCP 서버는 Context7(문서), Sequential(분석), Magic(UI), Playwright(테스팅), Morphllm(코드 변환)과 같은 전문 도구를 통해 향상된 기능을 제공합니다.
도메인 전문가는 일반적인 접근 방식보다 더 깊고 정확한 솔루션을 제공하기 위해 좁은 전문 영역에 집중합니다.
우선순위 계층:
충돌 해결:
선택 결정 트리:
작업 분석 →
├─ 수동 @agent-? → 지정된 에이전트 사용
├─ 단일 도메인? → 주요 에이전트 활성화
├─ 다중 도메인? → 전문 에이전트 조정
├─ 복잡한 시스템? → system-architect 감독 추가
├─ 품질 중요? → security + performance + quality 에이전트 포함
└─ 학습 중심? → learning-guide + technical-writer 추가
# @agent- 접두사로 특정 에이전트를 명시적으로 호출
@agent-python-expert "이 데이터 처리 파이프라인 최적화해줘"
@agent-quality-engineer "포괄적인 테스트 스위트 만들어줘"
@agent-technical-writer "이 API를 예제와 함께 문서화해줘"
@agent-socratic-mentor "이 디자인 패턴 설명해줘"
# 자동 활성화를 트리거하는 명령
/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
# 명령으로 시작 (자동 활성화)
/sc:implement "사용자 프로필 시스템"
# 그런 다음 전문가 검토를 명시적으로 추가
@agent-security "프로필 시스템의 OWASP 규정 준수 검토해줘"
@agent-performance-engineer "데이터베이스 쿼리 최적화해줘"
전문 분야: 확장성과 서비스 아키텍처에 중점을 둔 대규모 분산 시스템 설계
자동 활성화:
역량:
예제:
검증: /sc:design "마이크로서비스 플랫폼"은 system-architect를 활성화해야 함
테스트: 출력에 서비스 분해 및 통합 패턴이 포함되어야 함
확인: 인프라 문제에 대해 devops-architect와 조정해야 함
최적의 협업 대상: devops-architect(인프라), performance-engineer(최적화), security-engineer(규정 준수)
전문 분야: API 신뢰성과 데이터 무결성을 강조하는 견고한 서버 측 시스템 설계
자동 활성화:
역량:
예제:
최적의 협업 대상: security-engineer(인증/보안), performance-engineer(최적화), quality-engineer(테스팅)
전문 분야: 접근성과 사용자 경험에 중점을 둔 현대적인 웹 애플리케이션 아키텍처
자동 활성화:
역량:
예제:
최적의 협업 대상: learning-guide(사용자 안내), performance-engineer(최적화), quality-engineer(테스팅)
전문 분야: 안정적인 소프트웨어 전달을 위한 인프라 자동화 및 배포 파이프라인 설계
자동 활성화:
역량:
예제:
최적의 협업 대상: system-architect(인프라 계획), security-engineer(규정 준수), performance-engineer(모니터링)
전문 분야: 적응형 전략과 다중 홉 추론을 사용한 포괄적인 연구
자동 활성화:
/sc:research가 자동으로 이 에이전트를 활성화역량:
연구 깊이 수준:
예제:
/sc:research "최신 React Server Components 패턴" → 구현 예제를 포함한 포괄적인 기술 연구/sc:research "2024년 AI 코딩 어시스턴트 현황" --strategy unified → 사용자 입력을 포함한 협업 분석/sc:research "양자 컴퓨팅 돌파구" --depth exhaustive → 증거 체인을 포함한 포괄적인 문헌 검토워크플로우 패턴 (6단계):
출력: 보고서는 docs/research/[topic]_[timestamp].md에 저장됨
최적의 협업 대상: system-architect(기술 연구), learning-guide(교육 연구), requirements-analyst(시장 연구)
전문 분야: 위협 모델링 및 취약점 예방에 중점을 둔 애플리케이션 보안 아키텍처
자동 활성화:
역량:
예제:
최적의 협업 대상: backend-architect(API 보안), quality-engineer(보안 테스팅), root-cause-analyst(사고 대응)
전문 분야: 확장성과 리소스 효율성에 중점을 둔 시스템 성능 최적화
자동 활성화:
역량:
예제:
최적의 협업 대상: system-architect(확장성), devops-architect(인프라), root-cause-analyst(디버깅)
전문 분야: 증거 기반 분석 및 가설 테스트를 사용한 체계적인 문제 조사
자동 활성화:
역량:
예제:
최적의 협업 대상: performance-engineer(성능 문제), security-engineer(보안 사고), quality-engineer(테스트 실패)
전문 분야: 자동화 및 커버리지에 중점을 둔 포괄적인 테스팅 전략 및 품질 보증
자동 활성화:
역량:
예제:
최적의 협업 대상: security-engineer(보안 테스팅), performance-engineer(부하 테스팅), frontend-architect(UI 테스팅)
전문 분야: 체계적인 리팩토링 및 기술 부채 관리를 통한 코드 품질 개선
자동 활성화:
역량:
예제:
최적의 협업 대상: system-architect(아키텍처 개선), quality-engineer(테스팅 전략), python-expert(언어별 패턴)
전문 분야: 현대적인 프레임워크와 성능을 강조하는 프로덕션급 Python 개발
자동 활성화:
역량:
예제:
최적의 협업 대상: backend-architect(API 설계), quality-engineer(테스팅), performance-engineer(최적화)
전문 분야: 체계적인 이해관계자 분석을 통한 요구사항 발견 및 사양 개발
자동 활성화:
역량:
예제:
최적의 협업 대상: system-architect(기술적 실현 가능성), technical-writer(문서화), learning-guide(사용자 안내)
전문 분야: 대상 분석 및 명확성에 중점을 둔 기술 문서화 및 커뮤니케이션
자동 활성화:
역량:
예제:
최적의 협업 대상: requirements-analyst(사양 명확성), learning-guide(교육 콘텐츠), frontend-architect(UI 문서화)
전문 분야: 기술 개발 및 멘토십에 중점을 둔 교육 콘텐츠 설계 및 점진적 학습
자동 활성화:
역량:
예제:
최적의 협업 대상: technical-writer(교육 문서화), frontend-architect(대화형 학습), requirements-analyst(학습 목표)
아키텍처 팀:
품질 팀:
커뮤니케이션 팀:
MCP 서버를 통한 향상된 기능:
문제 해결 도움말은 다음을 참조하세요:
/sc:focus [domain] 사용/sc:implement "security auth"로 security-engineer 테스트보안 에이전트 없음:
# 문제: 보안 우려가 security-engineer를 트리거하지 않음
# 빠른 수정: 명시적 보안 키워드 사용
"implement authentication" # 일반적 - 트리거하지 않을 수 있음
"implement JWT authentication security" # 명시적 - security-engineer 트리거
"secure user login with encryption" # 보안 중심 - security-engineer 트리거
성능 에이전트 없음:
# 문제: 성능 문제가 performance-engineer를 트리거하지 않음
# 빠른 수정: 성능별 용어 사용
"make it faster" # 모호함 - 트리거하지 않을 수 있음
"optimize slow database queries" # 구체적 - performance-engineer 트리거
"reduce API latency and bottlenecks" # 성능 중심 - performance-engineer 트리거
아키텍처 에이전트 없음:
# 문제: 시스템 설계가 아키텍처 에이전트를 트리거하지 않음
# 빠른 수정: 아키텍처 키워드 사용
"build an app" # 일반적 - 기본 에이전트 트리거
"design microservices architecture" # 구체적 - system-architect 트리거
"scalable distributed system design" # 아키텍처 중심 - system-architect 트리거
잘못된 에이전트 조합:
# 문제: 백엔드 작업에 프론트엔드 에이전트 활성화
# 빠른 수정: 도메인별 용어 사용
"create user interface" # frontend-architect를 트리거할 수 있음
"create REST API endpoints" # 구체적 - backend-architect 트리거
"implement server-side authentication" # 백엔드 중심 - backend-architect 트리거
빠른 수정:
상세 도움말:
전문가 지원:
SuperClaude install --diagnose 사용커뮤니티 지원:
에이전트 수정 적용 후 테스트:
에이전트가 활성화되지 않나요?
너무 많은 에이전트?
/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 |
개발 워크플로우:
분석 워크플로우:
커뮤니케이션 워크플로우:
자연어 우선:
효과적인 키워드 사용:
요청 최적화 예제:
# 일반적 (제한된 에이전트 활성화)
"로그인 기능 수정"
# 최적화됨 (다중 에이전트 조정)
"속도 제한 및 접근성 규정 준수를 갖춘 안전한 JWT 인증 구현"
# → 트리거: security-engineer + backend-architect + frontend-architect + quality-engineer
개발 워크플로우:
# 풀스택 기능 개발
/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
분석 워크플로우:
# 보안 평가
/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
다중 도메인 프로젝트:
에이전트 선택 문제 해결:
문제: 잘못된 에이전트 활성화
문제: 에이전트가 충분하지 않음
문제: 에이전트가 너무 많음
보안 우선 접근법: 도메인 전문가와 함께 security-engineer를 자동으로 참여시키기 위해 개발 요청에 항상 보안 고려사항을 포함하세요.
성능 통합: 처음부터 performance-engineer 조정을 보장하기 위해 성능 키워드("빠른", "효율적", "확장 가능")를 포함하세요.
접근성 규정 준수: 프론트엔드 개발에서 접근성 검증을 자동으로 포함하기 위해 "accessible", "WCAG" 또는 "inclusive"를 사용하세요.
문서화 문화: 자동 technical-writer 포함 및 지식 전달을 위해 요청에 "documented", "explained" 또는 "tutorial"을 추가하세요.
도메인 전문 지식: 각 에이전트는 도메인별 전문 지식 패턴, 행동 접근법, 문제 해결 방법론을 가지고 있습니다.
컨텍스트 활성화: 에이전트는 키워드뿐만 아니라 요청 컨텍스트를 분석하여 관련성 및 참여 수준을 결정합니다.
협업 지능: 다중 에이전트 조정은 개별 에이전트 능력을 초과하는 시너지 효과를 생성합니다.
적응형 학습: 에이전트 선택은 요청 패턴 및 성공적인 조정 결과를 기반으로 향상됩니다.
전통적인 접근법: 단일 AI가 다양한 수준의 전문 지식으로 모든 도메인을 처리 에이전트 접근법: 전문가들이 깊은 도메인 지식과 집중된 문제 해결로 협업
이점:
기대할 수 있는 것:
걱정하지 않아도 되는 것:
1주차: 자연스러운 사용 자연어 설명으로 시작하세요. 어떤 에이전트가 활성화되는지, 그리고 그 이유를 주목하세요. 프로세스를 과도하게 생각하지 않고 키워드 패턴에 대한 직관을 구축하세요.
2-3주차: 패턴 인식 에이전트 조정 패턴을 관찰하세요. 복잡성과 도메인 키워드가 에이전트 선택에 어떻게 영향을 미치는지 이해하세요. 더 나은 조정을 위해 요청 문구를 최적화하기 시작하세요.
2개월 이상: 전문가 조정 최적의 에이전트 조합을 트리거하는 다중 도메인 요청을 마스터하세요. 효과적인 에이전트 선택을 위한 문제 해결 기법을 활용하세요. 복잡한 워크플로우를 위한 고급 패턴을 사용하세요.
SuperClaude 이점: 간단하고 자연스러운 언어 요청을 통해 조정된 응답으로 작동하는 14명의 전문 AI 전문가의 힘을 경험하세요. 구성도, 관리도 필요 없이, 필요에 따라 확장되는 지능적인 협업만 있습니다.
🎯 지능적인 에이전트 조정을 경험할 준비가 되셨나요? /sc:implement로 시작하여 전문 AI 협업의 마법을 발견하세요.