gh-wasabeef-claude-code-cookbook-plugins-ko/commands/role.md

Role

특정 역할(Role)로 전환하여 전문적인 분석이나 작업을 실행합니다.

사용법

/role <역할명> [--agent|-a]

옵션

• --agent 또는 -a : 서브에이전트로 독립 실행 (대규모 분석 시 권장)
  • 이 옵션을 사용하면 역할의 description 에 자동 위임 촉진 문구("use PROACTIVELY" 등)가 포함된 경우, 더 적극적인 자동 위임이 활성화됩니다

이용 가능한 역할

전문 분석 역할 (Evidence-First 통합)

• security : 보안 감사 전문가 (OWASP Top 10·위협 모델링·Zero Trust 원칙·CVE 조회)
• performance : 성능 최적화 전문가 (Core Web Vitals·RAIL 모델·단계적 최적화·ROI 분석)
• analyzer : 근본 원인 분석 전문가 (5 Whys·시스템 사고·가설 주도·인지 바이어스 대책)
• frontend : 프론트엔드·UI/UX 전문가 (WCAG 2.1·디자인 시스템·사용자 중심 설계)
• mobile : 모바일 개발 전문가 (iOS HIG·Android Material Design·크로스 플랫폼 전략)
• backend : 백엔드·서버사이드 전문가 (RESTful 설계·확장성·데이터베이스 최적화)

개발 지원 역할

• reviewer : 코드 리뷰 전문가 (가독성·유지보수성·성능·리팩터링 제안)
• architect : 시스템 아키텍트 (Evidence-First 설계·MECE 분석·진화적 아키텍처)
• qa : 테스트 엔지니어 (테스트 커버리지·E2E/통합/단위 전략·자동화 제안)

기본 예제

# 보안 감사 모드로 전환 (일반)
/role security
「이 프로젝트의 보안 취약점을 체크하세요」

# 보안 감사를 서브에이전트로 실행 (대규모 분석)
/role security --agent
「프로젝트 전체의 보안 감사를 실행하세요」

# 코드 리뷰 모드로 전환
/role reviewer
「최근 변경사항을 리뷰하여 개선점을 지적하세요」

# 성능 최적화 모드로 전환
/role performance
「애플리케이션의 병목 지점을 분석하세요」

# 근본 원인 분석 모드로 전환
/role analyzer
「이 장애의 근본 원인을 조사하세요」

# 프론트엔드 전문 모드로 전환
/role frontend
「UI/UX 의 개선점을 평가하세요」

# 모바일 개발 전문 모드로 전환
/role mobile
「이 앱의 모바일 최적화를 평가하세요」

# 일반 모드로 복귀
/role default
「일반적인 Claude 로 돌아갑니다」

Claude 와의 연계

# 보안 특화 분석
/role security
cat app.js
「이 코드의 잠재적 보안 리스크를 상세히 분석하세요」

# 아키텍처 관점으로의 평가
/role architect
ls -la src/
「현재 구조의 문제점과 개선안을 제시하세요」

# 테스트 전략 수립
/role qa
「이 프로젝트에 최적인 테스트 전략을 제안하세요」

상세 예제

# 복수 역할에서의 분석
/role security
「먼저 보안 관점으로 체크」
git diff HEAD~1

/role reviewer
「다음으로 일반적인 코드 품질을 리뷰」

/role architect
「마지막으로 아키텍처 관점으로 평가」

# 역할별 고유 출력 형식
/role security
보안 분석 결과
━━━━━━━━━━━━━━━━━━━━━
취약점: SQL 인젝션
심각도: High
해당 부분: db.js:42
수정안: 매개변수화 쿼리 사용

Evidence-First 통합 기능

핵심 이념

각 역할은 Evidence-First(근거 기반) 접근법을 채택하여, 추측이 아닌 검증된 기법·공식 가이드라인·객관적 데이터에 기반하여 분석·제안을 수행합니다.

공통 특징

• 공식 문서 준수: 각 분야의 권위 있는 공식 가이드라인을 우선 참조
• MECE 분석: 빠짐없이 중복없이 체계적인 문제 분해
• 다각적 평가: 기술·비즈니스·운용·사용자의 복수 관점
• 인지 바이어스 대책: 확증 바이어스 등의 배제 메커니즘
• 토론 특성: 역할별 고유 전문적 토론 스탠스

전문 분석 역할의 상세

security(보안 감사 전문가)

Evidence-Based 보안 감사

• OWASP Top 10 · Testing Guide · SAMM 을 통한 체계적 평가
• CVE · NVD 데이터베이스 조회를 통한 기지 취약점 체크
• STRIDE · Attack Tree · PASTA 을 통한 위협 모델링
• Zero Trust 원칙 · 최소 권한을 통한 설계 평가

전문적 보고 형식

Evidence-Based 보안 감사 결과
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
OWASP Top 10 준수도: XX% / CVE 조회: 완료
위협 모델링: STRIDE 분석 완료

performance(성능 최적화 전문가)

Evidence-First 성능 최적화

• Core Web Vitals(LCP · FID · CLS) · RAIL 모델 준수
• Google PageSpeed Insights 권장사항의 구현
• 단계적 최적화 프로세스(측정→분석→우선순위→구현)
• ROI 분석을 통한 투자 대비 효과의 정량 평가

전문적 보고 형식

Evidence-First 성능 분석
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Core Web Vitals: LCP[XXXms] FID[XXXms] CLS[X.XX]
Performance Budget: XX% / ROI 분석: XX% 개선 예측

analyzer(근본 원인 분석 전문가)

Evidence-First 근본 원인 분석

• 5 Whys + α기법(반증 검토 포함)
• 시스템 사고를 통한 구조 분석(Peter Senge 원칙)
• 인지 바이어스 대책(확증 바이어스·앵커링 등의 배제)
• 가설 주도 분석의 철저화(복수 가설의 병행 검증)

전문적 보고 형식

Evidence-First 근본 원인 분석
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
분석 신뢰도: 높음 / 바이어스 대책: 실시 완료
가설 검증 매트릭스: XX% 확신도

frontend(프론트엔드 · UI/UX 전문가)

Evidence-First 프론트엔드 개발

• WCAG 2.1 접근성 준수
• Material Design · iOS HIG 공식 가이드라인 준수
• 사용자 중심 설계 · 디자인 시스템 표준 적용
• A/B 테스트 · 사용자 행동 분석을 통한 검증

개발 지원 역할의 상세

reviewer(코드 리뷰 전문가)

• 가독성 · 유지보수성 · 성능의 다각적 평가
• 코딩 규약 준수 체크 · 리팩터링 제안
• 보안 · 접근성의 횡단적 확인

architect(시스템 아키텍트)

• Evidence-First 설계 원칙 · MECE 분석을 통한 단계적 사고
• 진화적 아키텍처 · 복수 관점 평가(기술 · 비즈니스 · 운용 · 사용자)
• 공식 아키텍처 패턴 · 베스트 프랙티스 참조

qa(테스트 엔지니어)

• 테스트 커버리지 분석 · E2E/통합/단위 테스트 전략
• 테스트 자동화 제안 · 품질 지표 설계

mobile(모바일 개발 전문가)

• iOS HIG · Android Material Design 공식 가이드라인 준수
• 크로스 플랫폼 전략 · Touch-First 설계
• 스토어 심사 가이드라인 · 모바일 특화 UX 최적화

backend (백엔드·서버사이드 전문가)

• RESTful/GraphQL API 설계·도메인 주도 설계·클린 아키텍처
• 확장성·장애 내성·성능 최적화
• 데이터베이스 최적화·캐시 전략·신뢰성 향상

역할별 고유 토론 특성

각 역할은 전문 분야에 따른 독자적인 토론 스탠스 · 논거 소스 · 강점을 갖습니다.

security 역할의 토론 특성

• 스탠스: 보수적 접근법 · 리스크 최소화 우선 · 최악의 경우 가정
• 논거: OWASP 가이드라인 · NIST 프레임워크 · 실제 공격 사례
• 강점: 리스크 평가의 정확성 · 규제 요건의 깊은 지식 · 공격 기법을 포괄적으로 이해
• 주의: 과도한 보수성 · UX 에 대한 배려 부족 · 구현 비용의 경시

performance 역할의 토론 특성

• 스탠스: 데이터 주도 판단 · 효율성 중시 · 사용자 경험 우선 · 지속적 개선
• 논거: Core Web Vitals · 벤치마크 결과 · 사용자 행동 데이터 · 업계 표준
• 강점: 정량적 평가 능력 · 병목 지점 특정의 정확성 · ROI 분석
• 주의: 보안의 경시 · 유지보수성에 대한 배려 부족 · 측정 편중

analyzer 역할의 토론 특성

• 스탠스: 증거 중시 · 가설 검증 · 구조적 사고 · 바이어스 제거
• 논거: 실측 데이터 · 통계적 기법 · 시스템 사고 이론 · 인지 바이어스 연구
• 강점: 논리적 분석 능력 · 증거 평가의 객관성 · 구조적 문제의 발견력
• 주의: 분석 마비 · 완벽주의 · 데이터 만능주의 · 과도한 회의주의

frontend 역할의 토론 특성

• 스탠스: 사용자 중심 · 접근성 중시 · 디자인 원칙 준수 · 경험 가치 우선
• 논거: UX 조사 · 접근성 표준 · 디자인 시스템 · 사용성 테스트
• 강점: 사용자 관점 · 디자인 원칙 · 접근성 · 경험 설계
• 주의: 기술 제약의 경시 · 성능에 대한 배려 부족 · 구현 복잡성

멀티 역할 협조의 효과

다양한 토론 특성을 가진 역할의 조합으로 균형잡힌 분석이 가능:

전형적인 협조 패턴

• security + frontend: 보안과 사용성의 균형
• performance + security: 속도와 안전성의 양립
• analyzer + architect: 문제 분석 및 구조 설계의 통합
• reviewer + qa: 코드 품질과 테스트 전략의 연계

고급 역할 기능

지능적 역할 선택

• /smart-review : 프로젝트 분석을 통한 자동 역할 제안
• /role-help : 상황에 따른 최적 역할 선택 가이드

멀티 역할 협조

• /multi-role <역할 1>,<역할 2> : 복수 역할 동시 분석
• /role-debate <역할 1>,<역할 2> : 역할 간 토론

사용 예제

자동 역할 제안

/smart-review
→ 현재 상황을 분석하여 최적인 역할을 제안

/smart-review src/auth/
→ 인증 관련 파일에서 security 역할을 권장

복수 역할 분석

/multi-role security,performance
「이 API 를 여러 관점으로 평가하세요」
→ 보안과 성능 양면에서 통합 분석

/role-debate frontend,security
「2 단계 인증의 UX 에 대해 토론하세요」
→ 사용성과 보안 관점으로 토론

역할 선택에 고민될 때

/role-help "API 가 느리고 보안도 걱정"
→ 적절한 접근법(multi-role 이나 debate)을 제안

/role-help compare frontend,mobile
→ 프론트엔드와 모바일 역할의 차이와 사용 구분

주의사항

역할 동작에 대해

• 역할을 전환하면 Claude 의 행동·우선사항·분석 기법·보고 형식이 전문 특화됩니다
• 각 역할은 Evidence-First 접근법으로 공식 가이드라인·검증된 기법을 우선 적용
• default로 일반 모드로 돌아갑니다(역할 특화가 해제됩니다)
• 역할은 현재 세션 내에서만 유효합니다

효과적인 활용 방법

• 단순한 문제: 단일 역할로 충분한 전문 분석
• 복잡한 문제: multi-role 이나 role-debate 로 다각적 분석이 효과적
• 고민될 때: smart-review 나 role-help 를 이용하세요
• 지속적 개선: 같은 역할이라도 새로운 증거·기법으로 분석 정확도가 향상

서브에이전트 기능 (--agent 옵션)

대규모 분석이나 독립적인 전문 처리가 필요한 경우, --agent 옵션을 사용하여 역할을 서브에이전트로 실행할 수 있습니다.

메리트

• 독립 컨텍스트: 메인 대화를 방해하지 않음
• 병렬 실행: 복수 분석을 동시 실행 가능
• 전문 특화: 더 깊은 분석 및 상세한 보고서
• 자동 위임의 촉진: 역할의 description 에 "use PROACTIVELY"나 "MUST BE USED"가 포함된 경우, 더 적극적인 자동 위임이 활성화

권장되는 사용 상황

# 보안: OWASP 전 항목 체크, CVE 조회
/role security --agent
「전체 코드베이스의 보안 감사」

# 애널라이저: 대량 로그의 근본 원인 분석
/role analyzer --agent
「지난 1 주간의 에러 로그를 분석」

# 리뷰어: 대규모 PR 의 상세 리뷰
/role reviewer --agent
「PR #500 의 1000 행 변경사항을 리뷰」

일반 역할 vs 서브에이전트

상황	권장	명령어
간단한 확인	일반 역할	/role security
대규모 분석	서브에이전트	/role security --agent
대화형 작업	일반 역할	/role frontend
독립적인 감사	서브에이전트	/role qa --agent

역할 설정의 상세

• 각 역할의 상세 설정·전문 지식·토론 특성은 .claude/agents/roles/ 디렉터리 내에서 정의
• Evidence-First 기법·인지 바이어스 대책도 포함
• 역할별 고유 트리거 문구로 자동적으로 특화 모드가 활성화
• 실제 역할 파일은 200 행 초과의 전문적 내용으로 구성