PARA/03_Resources/R001_개발_레퍼런스(참고문서)/개발 환경과 도구/슈퍼 클로드코드 사용자 가이드 요약본.md

슈퍼 클로드코드 사용자 가이드 요약본

2025년 7월 22일

빠른 요약

슈퍼 클로드코드를 쓰면 기존 클로드코드보다 더 정교하게 코드를 작성할 수 있다.
특히 거대한 시스템에서 기능 추가 시 여러 사이드이펙트를 고려해주고 기존 코드와 호환성을 고려한 기능추가를 해준다.
또한 시니어 레벨에 근접한 코드 퀄리티를 보여준다.

대신 토큰을 미친듯이 빨아먹는다.

0. 초간단 TL;DR

그냥 써도 된다: /analyze, /build 같은 기본 명령만 던지면, 필요한 도구·페르소나·플래그를 SuperClaude가 알아서 붙인다.
힘의 원천은 조율: 명령어, 페르소나, MCP 서버, 플래그를 오케스트레이터가 상황에 맞게 자동 조합.
원칙은 ‘안전·근거·일관성’: 항상 읽고-쓰고, 검증하고, 증거를 남긴다.

1. 핵심 구성요소 (Core Components)

구분	개수	설명	예시/상세
Commands	15개	개발 상황별 특화 도구	`/analyze`, `/build`, `/improve`, `/workflow`, `/implement` 등
Flags	-	동작/출력/안전/성능 조정 옵션	`--think`, `--uc`, `--safe-mode`, `--validate`, `--persona-*`
Personas	11명	도메인 전문가 AI	`security`, `frontend`, `backend`, `architect`, `performance`, `qa`, `refactorer`, `devops`, `analyzer`, `mentor`, `scribe`
MCP Servers	4개	외부 능력 확장	Context7(문서), Sequential(다단계 분석), Magic(UI 생성), Playwright(테스트)
Modes	3개	운영 모드	Task Management, Introspection, Token Efficiency
Orchestrator	1개	지능형 라우터	요청 → 의도/복잡도 분석 → 조합/실행/검증/최적화

2. 작동 방식 (How It Works)

요청 분석: 의도·복잡도·도메인·작업유형 감지
자동 선택: 적절한 커맨드/플래그/페르소나/MCP 서버 조합
실행 조율: 병렬/단계적 실행, 품질 게이트 적용
검증 & 최적화: 결과 검증, 토큰/성능 최적화, 학습 반영

3. 3가지 운영 모드

Task Management Mode: 세션/프로젝트/복잡 오케스트레이션/반복개선(Loop)까지 4계층 관리
Introspection Mode: 스스로 사고 과정·도구 선택·규칙 준수·학습 포인트를 메타 분석
Token Efficiency Mode: 컨텍스트가 꽉 차면 심볼/압축/구조 최적화로 정보 밀도 ↑

4. 오케스트레이터 (The Orchestrator)

Detection Engine: 패턴, 복잡도(Simple/Moderate/Complex), 도메인(Front/Back/Sec/Perf), 작업 타입(분석/생성/수정/디버깅) 분류
Routing Intelligence: 결정 트리로 최적 조합 매핑
Fallback & Quality Gates(8단계): 문법→타입→린트→보안→테스트→성능→문서→통합
리소스 최적화: 토큰 배분, 병렬/배치 실행, 캐시, 위임(delegate), wave-mode

5. 규칙 & 원칙 (Rules & Principles)

파일 작업 보안: “읽기 후 수정”, 절대경로, 자동커밋 금지, 배치 변경
태스크 관리: 근거 기반 완료, 단일 in_progress, 품질 게이트, 컨텍스트 유지
프레임워크 준수: 의존성 확인, 기존 패턴 존중, 전역 변경 전 탐색, 완료 검증
개발 원칙: Evidence > Assumption, 간결성, 보안 기본값, 유지보수성 우선, SOLID 준수
시니어 개발자 관점: 시스템적 사고, 장기 관점, 리스크 보정, 이해관계자 고려

6. 대표 워크플로 (Getting Started & Patterns)

시작(온보딩)

/sc:load --deep --summary
/sc:analyze --focus architecture
/sc:analyze --focus quality
/sc:document onboarding --type guide

기능 개발 사이클

설계: /sc:design ...
구현: /sc:build ...
테스트: /sc:test ...
문서화: /sc:document ...

디버깅

/sc:troubleshoot "issue" --think
/sc:analyze target/ --focus debugging
/sc:improve ... --safe-mode --validate
/sc:test ... --coverage

성능 최적화 / 레거시 현대화 / 대규모 코드 관리 / 다팀 API 설계

→ 각 시나리오별로 분석→설계→개선→검증 패턴 반복 (문서의 Practical Examples 참고)

7. 팁 & 베스트 프랙티스

단순 시작 → 점진 복잡도: 기본 명령 → --think → --c7 → --seq/--validate
자동 활성화 신뢰 후 필요 시 수동 오버라이드
Preview/Safe-Mode로 위험 완화
플래그 충돌 주의: --no-mcp가 다른 MCP 플래그 무시 등
범위/스코프 적절히: file → module → project → system
Delegation/Compression: 대규모 작업에 필수
증거 관리: 메트릭/커버리지/보안 리포트/인트로스펙션 활용

8. 트러블슈팅 요약 (Quick Fix Table)

문제	빠른 해법	예시 플래그
느림	범위 축소 + 압축	`--scope file --uc`
잘못된 페르소나	명시적 지정	`--persona-security`
출력 과다	압축/포커스 지정	`--uc`, `--focus security`
위험한 변경	안전 기능	`--safe-mode --preview`
MCP 문제	강제/차단	`--all-mcp` / `--no-mcp`
결과 불일치	명시 플래그	`--think --c7 --persona-x`
컨텍스트 부족	컨텍스트 로드	`/load --deep`
토큰 한계	압축 + 위임	`--uc --delegate auto`

9. 핵심 정리(Again) & 다음 단계

핵심: “자동 조율 + 품질 우선 + 근거 기반”
전략: 기본에서 시작 → 자동화 관찰 → 필요 시 명시적 제어 → 고급 기능 실험
바로 할 일
- 초보: 설치 → /help, /analyze README.md → 가이드 읽기
- 숙련자: 자신만의 플래그/페르소나 패턴 정립, 고급 기능 테스트, 피드백 제공

10. 철학 & 로드맵

철학: 인간-친화적 보조자. 맥락/목표는 사람이, 실행/근거는 SuperClaude.
개선 계획:
- 단기: 속도↑, MCP 안정성↑, 품질 게이트 강화, 문서 개선
- 중기: Hooks 재설계, 더 똑똑한 자동 활성화, MCP 생태계 확장, 고급 병렬 오케스트레이션
- 장기: 팀/프로젝트 문맥 심층 이해, 선제적 지원, IDE/CI/CD/클라우드 통합

11. 마무리 🎉

SuperClaude v3.0은 “기존 워크플로를 깨지 않고” 개발 생산성과 학습, 품질을 높이기 위한 기반입니다. 완벽하진 않지만, 당신의 역량을 확장하는 데 초점을 맞춥니다.
문제가 생기면 알려주세요. 그 피드백이 다음 버전을 더 좋게 만듭니다.

Happy coding! 🚀
세부 원칙과 예시가 포함된 전체 가이드는 [[KnowledgeBase/Blog/슈퍼 클로드코드 사용자 가이드]]를 참고한다.