SuperClaude: 완전 가이드
📌 목차
- SuperClaude의 본질
- 핵심 철학과 규칙
- 9개의 전문 페르소나
- 18개의 강력한 명령어
- MCP 도구
- WSL2 + VS Code 설치 가이드
- 실전 사용 예시
🎯 SuperClaude의 본질
SuperClaude는 단순한 도구 모음이 아닌, 철학적 기반 위에 구축된 시스템입니다. Claude Code를 일반적인 AI 어시스턴트에서 진정한 개발 파트너로 변환합니다.
4가지 핵심 기둥
- 전문화: 9개의 인지 페르소나를 통한 전문가 수준의 지원
- 기억력: Git 기반 메모리로 세션 내 학습 및 체크포인트
- 효율성: 토큰 최적화와 지능적인 모델 라우팅
- 신뢰: 증거 기반 작동과 건설적 반박
핵심 특징
- 100% 로컬 실행: 제3자 서버 없이 완전히 로컬에서 작동
- 제로 의존성: 추가 라이브러리나 외부 도구 불필요
- 오픈소스: MIT 라이선스, GitHub에서 자유롭게 사용 가능
- 프라이버시 중심: 데이터 수집 없음
📜 핵심 철학과 규칙
RULES.md: AI의 가상 헌법
증거 기반 작동 원칙 (CRITICAL 규칙)
- 금지된 절대적 표현: '최고의', '최적의', '항상' 사용 불가
- 권장 확률적 표현: '할 수 있다', '일 수 있다', '일반적으로'
- 필수 증거 제시: 모든 주장은 문서화된 사실로 뒷받침
심각도 시스템
- CRITICAL [10]: 협상 불가능한 차단 요소
- "절대 비밀을 커밋하지 마라"
- "공유 브랜치에 강제 푸시하지 마라"
- 문서 조회 없이 외부 라이브러리 구현 금지
- HIGH [7-9]: 필수 수정 사항 (코드 품질, 성능, Git 워크플로우)
- MEDIUM [4-6]: 경고 사항
- LOW [1-3]: 권장 사항
건설적 반박 원칙
SuperClaude는 수동적 도구가 아닌 능동적 파트너:
- 비효율적 접근 방식 지적
- 보안 위험 경고
- 대안 제시: "위험: SQL 주입. 고려: 매개변수화된 쿼리"
토큰 경제와 효율성
초압축 모드
- 기호 사용: → (이어지다), & (그리고)
- 약어 및 글머리 기호
- 효과: 토큰 사용량 70% 감소
지능적 모델 라우팅
- 간단한 작업 → Sonnet (빠르고 저렴)
- 복잡한 재설계 → Opus (강력하지만 비용 높음)
🎭 9개의 전문 페르소나
각 페르소나는 깊이 있는 프로필을 가집니다:
- Core_Belief: 핵심 신념
- Primary_Question: 주요 질문
- Decision_Pattern: 결정 패턴
- Preferred_Tools: 선호 도구
1. 아키텍트 (/persona:architect)
- 신념: "시스템은 변화를 위해 설계되어야 한다"
- 질문: "이것이 어떻게 확장되고 발전할 것인가?"
- 특징: 장기적 유지보수성 우선, 디자인 패턴 중시
- 도구: Sequential (시스템 매핑), C7 (패턴 연구)
2. 프론트엔드 개발자 (/persona:frontend)
- 신념: "사용자 경험이 제품 성공을 결정한다"
- 질문: "이것이 사용자에게 어떻게 느껴지는가?"
- 특징: 직관적 UI, 모바일 우선
- 도구: Magic (UI 생성), Puppeteer (UX 검증)
3. 보안 전문가 (/persona:security)
- 신념: "위협은 어디에나 존재한다"
- 질문: "무엇이 잘못될 수 있는가?"
- 특징: 설계상 편집증적, 다층 방어
- 도구: Sequential (공격 벡터 분석), C7 (보안 모범 사례)
4. 분석가 (/persona:analyzer)
- 신념: "모든 증상에는 여러 잠재적 원인이 있다"
- 질문: "어떤 증거가 명백한 답변과 모순되는가?"
- 특징: 체계적 가설 설정 및 검증
- 도구: 모든 MCP 도구, 특히 Sequential
5. 멘토 (/persona:mentor)
- 신념: "안내된 발견을 통해 이해가 깊어진다"
- 질문: "이것을 이해하는 데 어떻게 도움을 드릴 수 있을까요?"
- 특징: 비유와 단계별 설명
- 도구: C7 (문서 검색), Sequential (개념 설명)
6-9. 추가 페르소나
- 백엔드 개발자 (/persona:backend)
- QA 엔지니어 (/persona:qa)
- DevOps 전문가 (/persona:devops)
- 데이터 사이언티스트 (/persona:data)
자동 페르소나 활성화
.tsx 파일 편집 → frontend 페르소나 자동 활성화- "버그" 또는 "오류" 언급 → analyzer 페르소나 활성화
🛠️ 18개의 강력한 명령어
구축 및 설계
/user:build - 플래그: --react, --api, --tdd/user:design - 플래그: --ddd (도메인 주도 설계)/user:implement - 기능 구현
분석 및 디버깅
/user:analyze - 성능, 보안, 아키텍처 분석/user:troubleshoot - 버그 조사, 프로덕션 수정/user:explain - 코드 설명
개선 및 유지보수
/user:improve - 리팩토링, 성능 최적화/user:cleanup - 사용되지 않는 코드/종속성 제거/user:test - 테스트 작성
문서화 및 관리
/user:document - 문서화/user:estimate - 작업 추정/user:task - 작업 관리
혁신적 기능
/user:git --checkpoint - 현재 상태 저장/user:git --rollback - 이전 상태로 복원/user:spawn - 병렬 작업을 위한 전문 에이전트 생성/user:index - 코드베이스 인덱싱/user:load - 저장된 컨텍스트 로드
🔧 MCP (Model Context Protocol) 도구
1. Context7 (C7)
- 기능: 문서 연구 도구
- 원칙: "연구 우선" - 외부 라이브러리 사용 전 문서 필수 확인
2. Sequential
- 기능: 심층 사고 및 분석
- 용도: 복잡한 시스템 분해, 논리적 추론
3. Magic
- 기능: UI 생성 및 개선
- 특징: 프로젝트 스타일에 맞는 컴포넌트 자동 생성
4. Puppeteer
- 기능: 브라우저 자동화 및 테스트
- 용도: 실제 사용자 경험 검증
💻 WSL2 + VS Code 설치 가이드
1. 사전 준비사항
Claude Code 설치
bash
# WSL2 터미널에서
npm install -g @anthropic/claude-code
# 또는
yarn global add @anthropic/claude-code
VS Code WSL 확장 설치
- Windows의 VS Code 열기
- Extensions 탭에서 "WSL" 검색
- "WSL" (Microsoft 제공) 확장 설치
2. SuperClaude 설치
bash
# WSL2 터미널에서
cd ~
git clone https://github.com/NomenAK/SuperClaude.git
cd SuperClaude
./install.sh
# 설치 옵션
python3 SuperClaude.py install --minimal # 최소 설치
python3 SuperClaude.py install --profile developer # 전체 설치
3. 환경 변수 설정
bash
# ~/.bashrc 또는 ~/.zshrc에 추가
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.bashrc
echo 'export PATH="$HOME/.claude/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
4. VS Code에서 WSL 프로젝트 열기
bash
# WSL2 터미널에서
cd /path/to/your/project
code .
5. VS Code 설정
json
// .vscode/settings.json
{
"terminal.integrated.defaultProfile.linux": "bash",
"terminal.integrated.env.linux": {
"ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}"
}
}
6. 프로젝트 컨텍스트 설정
bash
# 프로젝트 루트에 CLAUDE.md 생성
cat > CLAUDE.md << 'EOF'
# Project Context for Claude
## Architecture
- Frontend: React with TypeScript
- Backend: Node.js with Express
- Database: PostgreSQL
## Conventions
- Use functional components with hooks
- Follow ESLint rules
- Write tests for all new features
## Commands
- `npm run dev` - Start development server
- `npm test` - Run tests
- `npm run build` - Build for production
EOF
7. 문제 해결
Claude Code 인식 문제
bash
echo $PATH
which claude-code
export PATH="$HOME/.local/bin:$PATH"
API 키 문제
bash
echo $ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY="sk-ant-..."
WSL2 네트워크 문제
bash
sudo echo "nameserver 8.8.8.8" > /etc/resolv.conf
🚀 실전 사용 예시
새 프로젝트 시작
bash
# 아키텍처 설계
/persona:architect
/user:design --api --ddd
/user:estimate --detailed
# 백엔드 구축
/persona:backend
/user:build --api --tdd
# 프론트엔드 구현
/persona:frontend
/user:build --react --component "Dashboard"
복잡한 디버깅
bash
# 체크포인트 생성
/user:git --checkpoint "Before debugging"
# 분석 시작
/persona:analyzer
/user:troubleshoot --production
/user:analyze --performance
# 문제 발생 시 롤백
/user:git --rollback
코드 리뷰 및 개선
bash
# 보안 검토
/persona:security
/user:analyze --security
# 코드 품질 개선
/user:improve --refactor
/user:cleanup --unused
팀 협업 시뮬레이션
bash
# 병렬 작업 생성
/user:spawn --agent frontend --task "Create login UI"
/user:spawn --agent backend --task "Implement auth API"
📈 세션 인식과 적응형 학습
SuperClaude는 단일 세션 내에서:
- 최근 편집 파일 기억
- 수정 사항 추적
- 코딩 스타일 학습
- 반복 패턴 감지 및 단축키 제안
🤝 기여 및 커뮤니티
기여 영역
- 새로운 페르소나 추가
- 명령어 확장
- 버그 수정
- 문서 개선
로드맵
- VS Code 확장 개발
- 커뮤니티 페르소나 마켓플레이스
- 프라이버시 우선 분석 대시보드
🌟 결론
SuperClaude는 AI가 단순한 코드 생성 도구를 넘어 진정한 개발팀 구성원이 되도록 합니다:
- ✅ 컨텍스트를 기억하는 파트너
- ✅ 작업에 맞는 사고방식을 채택하는 전문가
- ✅ 증거와 모범 사례 기반 작동
- ✅ 실수 시 건설적 반박
- ✅ 개인 워크플로우 학습 및 최적화
"SuperClaude는 Claude를 보강하는 것이 아니라, 완성합니다."
📚 추가 리소스