# 1-1. 프로젝트 루트에서 전체 구조 분석
/sc:analyze
# 1-2. 패키지.json 및 설정 파일 분석
/sc:analyze package.json --focus dependencies
# 1-3. 소스 코드 아키텍처 분석
/sc:analyze --focus architecture
1) /sc:analyze
- 요청 및 결과... 가 영문이어서
- 한글로 대답을 요구 하였다.
프로젝트 분석 결과 - 어느정도의 내용만 봐도 폴더 구조, 기술스택, 이 프로젝트에 어떤 기능이 있는지, 배포는 어떻게 하고있는지 등이 요약되어 초기 입사자들이 프로젝트를 파악하는데 도움이 될 것 같다.
Phase 2 : 버그 상황 진단 해보기
이제 실제 문제가 되는 토끼 게임 페이지, 랭킹 페이지를 분석해보자.
스크린샷을 보니 확실히 초록 배경색이 이상하고 랭킹영역은 스크롤도 제대로 작동하지 않는 것 같았다.
난 프론트 엔드 개발자익니 관련 소스 정도는 찾을 수 있을 것 같고, 마침 폴더 구조상 바로 확인하기 쉽게 대상 파일들을 확인 할 수 있었다.
문제 해결을 위해 내 이전 블로그에서의 내용이고, 상기 오류중 첫번째 문제 : 배경 색상 문제 를 해결하기 위해 analyze, troubleshoot 을 진행 해보자.
※ troubleshoot vs analyze 차이점
- analyze: 코드/시스템을 분석해서 상태 파악
- troubleshoot: 구체적인 문제를 해결하는 데 집중
2-1) /sc:analyze
▶ analyze
카테고리: Code Analysis & Review
목적: Code analysis and insight generation (코드 분석 및 인사이트 생성)
자동 페르소나: Analyzer, Code Reviewer
MCP 통합: File System, Sequential
사용법: /sc:analyze [target] [flags]
ex) 사용 예시
ex) 랭킹 페이지 전반적인 분석 예시 (상기 버그만 수정이 목적이라면 패스)
# 1) 랭킹 컴포넌트 코드 분석
/sc:analyze BunnyRanking.tsx --focus quality
# 2) CSS 파일 문제점 진단
/sc:analyze BunnyGame.css --persona-frontend
- 랭킹 컴포넌트만 코드 분석을 살짝 해보겠다. ( 만약 버그만 정말 수정하고 싶다면 해당 내용은 스킵 할 수 있지만. !! ) - 주로 품질 개선에 대한 내용을 말해주었다. ( 자동 페르소나에 의해 하기와 같이 퀄리티 높은 분석을 볼 수 있다. )
> /sc:analyze BunnyRanking.tsx --focus quality
⏺ I'll analyze the BunnyRanking.tsx file with a focus on code quality, identifying issues and improvement opportunities.
⏺ Update Todos
⎿ ☐ Read and analyze BunnyRanking.tsx file
☐ Identify code quality issues
☐ Analyze error handling patterns
☐ Review TypeScript usage and type safety
☐ Assess component architecture and patterns
☐ Provide quality improvement recommendations
⏺ Read(src/components/features/bunny/BunnyRanking.tsx)
⎿ Read 254 lines (ctrl+r to expand)
⏺ Update Todos
⎿ ☒ Read and analyze BunnyRanking.tsx file
☐ Identify code quality issues
☐ Analyze error handling patterns
☐ Review TypeScript usage and type safety
☐ Assess component architecture and patterns
☐ Provide quality improvement recommendations
⎿ Interrupted by user
> 대답은 앞으로 다 한글로 해줘야해
⏺ 네, 앞으로 모든 대답을 한글로 드리겠습니다.
⏺ Update Todos
⎿ ☒ BunnyRanking.tsx 파일 읽기 및 분석
☐ 코드 품질 이슈 식별
☐ 에러 처리 패턴 분석
☐ TypeScript 사용법 및 타입 안전성 검토
☐ 컴포넌트 아키텍처 및 패턴 평가
☐ 품질 개선 권장사항 제공
⏺ Update Todos
⎿ ☒ BunnyRanking.tsx 파일 읽기 및 분석
☒ 코드 품질 이슈 식별
☒ 에러 처리 패턴 분석
☒ TypeScript 사용법 및 타입 안전성 검토
☒ 컴포넌트 아키텍처 및 패턴 평가
☐ 품질 개선 권장사항 제공
⏺ Update Todos
⎿ ☒ BunnyRanking.tsx 파일 읽기 및 분석
☒ 코드 품질 이슈 식별
☒ 에러 처리 패턴 분석
☒ TypeScript 사용법 및 타입 안전성 검토
☒ 컴포넌트 아키텍처 및 패턴 평가
☒ 품질 개선 권장사항 제공
⏺ BunnyRanking.tsx 코드 품질 분석 보고서
🔍 주요 코드 품질 이슈
1. ESLint 경고: 사용하지 않는 변수
// 43번째 줄, 60번째 줄
} catch (err) { // ❌ 'err' 변수가 정의되었지만 사용되지 않음
setError('서버 연결에 실패했습니다.')
}
문제점: catch 블록에서 err 변수를 선언했지만 실제로 사용하지 않아 ESLint 경고 발생
2. 에러 처리 패턴 일관성 부족
// fetchRankings 함수 (43-44번째 줄)
} catch (err) {
setError('서버 연결에 실패했습니다.') // 하드코딩된 메시지
}
// fetchUserRank 함수 (60-61번째 줄)
} catch (err) {
setUserRank(null) // 에러 무시
}
문제점:
- 첫 번째 catch는 에러 메시지를 설정하지만, 두 번째는 조용히 실패
- 일관되지 않은 에러 처리 방식
📊 코드 품질 평가
강점
✅ 타입 안전성: TypeScript 인터페이스 잘 정의됨✅ 컴포넌트 구조: Props와 상태 관리가 명확함✅ 사용자 경험: 로딩, 에러, 빈 상태 모두 처리✅ 성능 최적화:
Framer Motion으로 부드러운 애니메이션✅ 접근성: 의미있는 텍스트와 버튼 라벨
개선 필요 영역
⚠️ 에러 처리: 일관성 없는 에러 처리 패턴⚠️ 로깅: 디버깅을 위한 에러 로깅 부족⚠️ 재시도 로직: 네트워크 실패에 대한 자동 재시도 없음
🛠️ 개선 권장사항
우선순위 높음
1. 사용하지 않는 변수 처리
// 현재 코드
} catch (err) {
setError('서버 연결에 실패했습니다.')
}
// 개선안 1: 언더스코어 사용
} catch (_err) {
setError('서버 연결에 실패했습니다.')
}
// 개선안 2: 에러 활용
} catch (err) {
console.error('랭킹 fetch 실패:', err)
setError('서버 연결에 실패했습니다.')
}
2. 일관된 에러 처리 패턴
const fetchUserRank = async (nickname: string) => {
try {
const response = await fetch(`/api/bunny/rankings/my-rank?nickname=${encodeURIComponent(nickname)}`)
const data = await response.json()
if (data.success) {
setUserRank(data.user_rank)
} else {
setUserRank(null)
}
} catch (err) {
console.error('사용자 랭킹 조회 실패:', err) // 로깅 추가
setUserRank(null)
}
}
우선순위 중간
3. 에러 타입 정의
interface ApiError {
message: string
code?: string
details?: unknown
}
const handleApiError = (err: unknown): string => {
if (err instanceof Error) {
return err.message
}
return '알 수 없는 오류가 발생했습니다.'
}
4. 재시도 로직 개선
const [retryCount, setRetryCount] = useState(0)
const MAX_RETRIES = 3
const fetchWithRetry = async (url: string, retries = 0): Promise<any> => {
try {
const response = await fetch(url)
return await response.json()
} catch (err) {
if (retries < MAX_RETRIES) {
await new Promise(resolve => setTimeout(resolve, 1000 * (retries + 1)))
return fetchWithRetry(url, retries + 1)
}
throw err
}
}
우선순위 낮음
5. 성능 최적화
// useMemo로 계산 최적화
const sortedRankings = useMemo(() => {
return rankings.sort((a, b) => a.rank - b.rank)
}, [rankings])
// useCallback으로 함수 최적화
const handlePeriodChange = useCallback((newPeriod: RankingPeriod) => {
setPeriod(newPeriod)
fetchRankings(newPeriod)
}, [])
📈 종합 평가
| 영역 | 점수 | 평가 |
|--------|-------------|---------------|
| 타입 안전성 | A (90/100) | 인터페이스 잘 정의됨 |
| 에러 처리 | C+ (75/100) | 일관성 부족, 로깅 없음 |
| 코드 구조 | A- (85/100) | 깔끔한 컴포넌트 구조 |
| 사용자 경험 | A (88/100) | 모든 상태 적절히 처리 |
| 성능 | B+ (82/100) | 기본적 최적화 완료 |
| 유지보수성 | B (78/100) | 개선 여지 있음 |
전체 평가: B+ (83/100)
🎯 즉시 수정 가능한 이슈
1. 43, 60번째 줄: err → _err 또는 실제 에러 로깅 사용
2. 에러 처리 일관성: 모든 catch 블록에 적절한 에러 처리 추가
3. 타입 안전성: 에러 객체에 대한 타입 가드 추가
이러한 개선을 통해 코드 품질을 A- (90점) 수준으로 향상시킬 수 있습니다.
- 실제 다음과 같이 요청 해보았다. (영문으로 요청하면 좋지만, 예제이니 이해를 위해 한글로 작성해보았다. )
/sc:troubleshoot "다른 화면들(ex /json-formatter)은 블랙 계통의 색상인데 토끼 게임 화면(경로 : /bunny-run)은 배경색이 녹색으로 되어있어. 다른 화면들처럼 어두운 블랙 색상으로 변경해야될 것 같아. " --think
- TODO List 및 문제 분석과정
- 원인 분석
- 해결방안 3가지 제안
- 난 이정도로 충분하지만, 만약 원인이 불문명하고 애매 하다라고 하면 다음 같은 방식으로 더 자세히 분석도 해볼 수 있을 것 이다.
# 2-1. 배경색 문제 직접 분석 (정상: 블랙/딥블루 vs 비정상: 초록)
/sc:troubleshoot "green background instead of dark theme" --think
/sc:analyze BunnyGame.css --focus "background-color conflicts"
# 2-2. 스크롤 비활성화 문제 타겟팅
/sc:troubleshoot "ranking page no scroll overflow hidden" --c7
/sc:analyze BunnyRanking.tsx --focus "scroll height issues"
# 2-3. 랭킹 아이템 높이 문제 분석
/sc:analyze "ranking item height too tall" --persona-frontend --validate
Phase 3 : troubleshoot 결과를 바탕으로 수정해 보기
troubleshoot에서 이미 구체적인 원인과 해결책이 나왔으니, 별도의 계획 수립은 이번엔 필요 없을 것 같아 바로 구현에 들어가보려 한다.
troubleshoot 결과 요약 1. 원인 파악: BunnyGame.tsx:616의 `bg-green-50 dark:bg-green-900` 클래스 2. 해결책 제시: `bg-white dark:bg-black`으로 변경하여 테마 일관성 확보 3. 즉시 적용 가능: 구체적인 코드 라인과 수정 내용까지 완벽 제공
// Step 3: troubleshoot 결과 즉시 적용
# 3-1. 배경색 테마 통일 (troubleshoot에서 제시한 해결책 적용)
/sc:implement theme-consistency-fix --validate --safe-mode
# 3-2. 적용 결과 즉시 테스트
/sc:test theme-consistency --coverage
- 이전에 제안 해준 해결책 1번 방법으로 진행해보자.
- sc:/implement
▶ implement
카테고리: Development & Execution
목적: Code implementation and modification (코드 구현 및 수정)
자동 페르소나: Developer, Implementer
MCP 통합: File System, Sequential
사용법: /sc:implement [task] [flags]
/sc:implement 너가 제안해준 1번 방법을 적용 해보자(theme-consistency-fix) --validate --safe-mode
- 소스 수정 및 빌드, lint 검사 까지 완료 하였다.
- 완료 보고서
Phase 4: 수정 결과 검증 및 추가 개선
핵심 버그는 troubleshoot 기반으로 해결했고, 이제 사용자 추가 개선사항들이 있을지 점검해 보자.
- sc:test
▶ test
카테고리: Quality Assurance
목적: Testing and validation (테스트 및 검증)
자동 페르소나: QA, Tester
MCP 통합: Sequential, Test Runner
사용법: /sc:test [target] [flags]
// Step 4: 수정 결과 검증
# 4-1. 배경색 테마 통일 결과 확인
/sc:test theme-consistency --coverage --validate
# 4-2. 크로스 브라우저 호환성 검증
/sc:test cross-browser --coverage
- todo 리스트를 작성하여 스스로 점검 및 테스트 진행
- 점검 보고서
Phase 5: 코드 리뷰 및 문서화
버그 수정이 완료되었으니 팀원들이 나중에 이 과정을 이해하고 참고할 수 있도록 문서화하는 예시.
- sc:document
▶ document
카테고리: Documentation & Communication
목적: Documentation generation (문서 생성)
자동 페르소나: Scribe, Technical Writer
MCP 통합: File System, Sequential
사용법: /sc:document [content] [flags]
// Step 5: 문서화 및 팀 공유
# 5-1. 수정 과정 문서화
/sc:document bunny-game-bugfix --type guide --persona-scribe
# 5-2. troubleshoot 활용 가이드 생성
/sc:document troubleshoot-workflow --type workflow --c7
# 5-3. 팀 공유용 간단 요약 생성
/sc:document quick-summary --type summary
팀 공유용 요약 문서
- 문서 내용은.. 너무 자세하고 길어서 패스 하겠다. 팀원들간 공유 하면 좋을 내용들
- 버그2도 동일한 방식으로 진행 하면 된다.
/sc:troubleshoot "(대상 파일 : BunnyRanking.tsx 경로 : /bunny-run 내 주간랭킹,월간랭킹 클릭시 나오는 레이어 팝업) 랭킹 페이지에 스크롤이 없어 스크롤이 되지 않는다. 이 부분을 스크롤을 가능하게 개선하고 랭킹 1개의 높이(height)가 너무 높으므로 개선이 필요해. " --think
ex) troubleshoot만으로 해결까지 해버렸다. 참고차 캡쳐만 남긴다.
Phase 6: 최종 커밋
이 작업들을 그럼 커밋 하면되는데 커밋시에 어떻게 활용하는지 까지 간단히 알라보자.
- /sc:git
▶ git
카테고리: Version Control & Management
목적: Git workflow and version management (Git 작업흐름 및 버전 관리)
자동 페르소나: Git Expert, DevOps
MCP 통합: Git CLI, Sequential
사용법: /sc:git [operation] [flags]
/sc:git 명령어란? SuperClaude의 /sc:git은 Git 작업을 자동화하고 최적화하는 명령어이다. Git Expert와 DevOps 페르소나가 적용되어 전문적인 Git 워크플로우를 제공한다.
# 6-1. 현재 변경사항 분석 및 커밋 전략 수립
/sc:git analyze-changes --think --strategy
- 분리 전략 (게임 수정사항이랑 다른 수정사항이 섞이지 않도록 권장하고 있다.)
# 6-2. 만약 커밋을 안했더라면 / 바로 커밋 및 푸시 실행(safe-mode 추가)
/sc:git commit-and-push --safe-mode --validate
# 6-3. 나의 경우는 이미 커밋이 되었으니 push 처리 하기 방법들 중 1가지를 선택 할수있을것 같다.
# 1) 현재 상태 확인
/sc:git status --detailed
# 2) 푸시 전 최종 검증
/sc:git pre-push-check --validate --safe-mode
# 3) 안전한 푸시 실행
/sc:git push --safe-mode --validate
- 정말 자세히 분석해주니 빠르게 넘겨 보시길 바래본다 ㅠㅠㅠ
- 바로 1번 옵션을 통해 push 요청 진행하도록 하겠다.
마무리
최대한 간단하게 superclaude를 다른 플러그인, mcp등 사용없이 순순하게 사용하는 예시를 다뤄 봤다.
첫번째 글 하나만으로는 충분히 이해되기 어렵고, 마침 댓글도 있기에 최대한 간단한 예시로, 간단하게 활용하는 예제를 작성해보았다. 시간이 된다면.. 이런 예시글도 추가로 보완 작성하면 좋을 것 같다고 생각이 들었다.
SuperClaude 활용 팁
구체적 문제 설명의 위력 1. 애매한 설명: "랭킹 페이지 이상해" ❌ 2. 구체적 설명: "green background instead of dark theme" ✅ 3. 결과: 정확한 파일 위치 + 수정 코드까지 한 번에 제시!
효율적인 troubleshoot 패턴 /sc:troubleshoot "specific problem description" --think → 문제 분석 + 해결책 + 구체적 코드까지 한 번에 → 별도 analyze나 design 단계 없이 바로 implement 가능
실무 최적화 워크플로우 기존: analyze → design → implement → test (4단계) 개선: troubleshoot → implement → test (3단계) **결과: 50% 시간 단축!**
SuperClaude 후기
문제 설명이 90% : 구체적이고 명확한 문제 설명이 해결 속도를 결정한다
troubleshoot 우선 : 명확한 버그가 있다면 analyze보다 troubleshoot이 훨씬 효율적이다
영어 설명의 위력 : 한글보다 영어로 문제를 설명할 때 더 정확한 결과를 얻는다
한 번에 하나씩 : 여러 문제를 한꺼번에 해결하려 하지 말고 우선순위별로 진행
즉시 검증 : 수정 후 바로 테스트해서 예상대로 작동하는지 확인
자주 묻는 질문 ❓
Q: troubleshoot과 analyze 언제 구분해서 써야 하나요?
A: 구체적인 버그나 문제가 있다면 troubleshoot, 전반적인 코드 상태를 파악하고 싶다면 analyze를 사용하세요. troubleshoot이 더 빠른 해결책을 제시합니다.
Q: 문제 설명을 어떻게 구체적으로 써야 하나요?
A: "기대 상태 vs 실제 상태"로 설명하세요. 예: "green background instead of dark theme", "no scroll expected scroll" 처럼 대조적으로 표현하면 더 정확한 결과를 얻습니다.
Q: 한글로 문제를 설명해도 되나요?
A: 가능하지만 영어로 설명할 때 더 정확한 결과를 얻을 수 있습니다. 특히 기술적 용어는 영어가 더 효과적입니다.
Q: 이런 워크플로우를 팀에 어떻게 공유하나요?
A: /sc:document로 과정을 문서화하고, 성공 사례를 공유하세요. "troubleshoot → implement → test" 3단계 워크플로우의 효율성을 보여주면 자연스럽게 확산됩니다.
다음으로 해볼만한 예시들
성능 최적화: /sc:analyze --focus performance --think --seq로 게임 프레임율 개선
PWA 전환: /sc:design pwa-system --type architecture --format spec으로 오프라인 지원
