analyze

name	analyze
description	기존 코드베이스(브라운필드)를 탐색·감사하고 외부 리서치를 더해 분석 보고서(MD)를 생성한다. 아키텍처·기술부채·보안·성능·개선 로드맵 도출. '/analyze', '분석해줘', '프로젝트 분석', '코드베이스 분석', '기술부채 점검' 등 기존 코드가 있는 프로젝트 언급 시 호출. 코드가 전무한 그린필드 신규 프로젝트에는 사용하지 않는다.
argument-hint	[프로젝트 경로 또는 분석 관점 설명]

Analyze — 프로젝트 심층 분석 파이프라인

$ARGUMENTS 에 대해 코드베이스를 탐색하고, 외부 리서치를 수행한 뒤, 종합 분석 보고서를 MD 파일로 출력한다.

SCAN → RESEARCH → ANALYZE → REPORT

적용 범위: 기존 코드베이스(브라운필드) 전용. 이 스킬의 SCAN은 package.json·기존 소스·아키텍처·기술부채를 감사한다. 코드가 전무한 그린필드 프로젝트에는 사용하지 않는다 — 그 경우 요구사항·리서치로부터 범위·스택을 확정하는 워크플로우(예: scope 스킬이 설치돼 있으면 활용)를 사용한다.

---

Phase 1: SCAN — 코드베이스 전체 탐색

1-1. 기본 컨텍스트 수집

Read 도구로 아래를 병렬 수집한다:

• CLAUDE.md — 기술 스택, 구조, 규칙
• package.json (또는 해당 언어의 의존성 파일) — 의존성 목록
• 프로젝트 히스토리 문서 — 존재하면 로드 (예: docs/, CHANGELOG.md, ADR 등에 기록된 기술 결정사항·알려진 이슈)
• README.md — 프로젝트 설명, 현재 문서 상태

1-2. 에이전트 병렬 탐색

Task 도구로 아래 3개 에이전트를 동시에 실행한다:

Agent A: 구조 탐색 (Explore, thoroughness: "very thorough")

프롬프트:

프로젝트의 전체 구조를 분석하라:
1. 디렉토리 트리 및 파일 구성
2. 진입점(entry point) 식별
3. 주요 모듈/컴포넌트 목록
4. 설정 파일 (빌드, 린트, 테스트 등) 현황
5. 의존성 패키지 분류 (core / UI / 유틸리티 / dev)
코드를 수정하지 말고 탐색 결과만 반환하라.

Agent B: 아키텍처 분석 (feature-dev:code-explorer)

프롬프트:

프로젝트의 아키텍처를 심층 분석하라:
1. 레이어 구조 (데이터 / 비즈니스 로직 / UI)
2. 상태 관리 패턴
3. 데이터 흐름 (입력 → 처리 → 출력)
4. 사용된 디자인 패턴 식별
5. 모듈 간 의존성 그래프 (주요 import 관계)
6. 추상화 수준 평가
코드를 수정하지 말고 분석 결과만 반환하라.

Agent C: 코드 품질 리뷰 (feature-dev:code-reviewer)

프롬프트:

프로젝트 전체 코드 품질을 리뷰하라:
1. 보안 취약점 (OWASP Top 10 기준)
2. 성능 병목 가능 지점
3. 기술 부채 식별 (하드코딩, 중복 코드, TODO/FIXME 등)
4. 테스트 커버리지 현황
5. 에러 핸들링 패턴 일관성
6. 프로젝트 컨벤션 준수도
confidence HIGH 이슈만 보고하라. 코드를 수정하지 말고 리뷰 결과만 반환하라.

---

Phase 2: RESEARCH — 외부 리서치

2-0. 기존 팀 리서치 결과 확인

docs/research/RESEARCH-*.md 파일이 존재하는지 Glob으로 탐색한다:

상황	동작
RESEARCH 파일 존재	Read로 로드 → 이미 조사된 항목 확인 → 해당 항목은 2-1, 2-2에서 생략
RESEARCH 파일 없음	2-1, 2-2를 전체 수행

사전 리서치 결과(docs/research/RESEARCH-*.md)가 이미 있으면(예: team-research 스킬이 설치돼 있어 미리 조사를 돌렸다면), 중복 조사를 방지하기 위해 이 단계를 자동 적용한다.

2-1. 기술 스택 리서치

Phase 1에서 파악한 핵심 기술 스택(상위 3~5개) 중 2-0에서 확인되지 않은 항목에 대해:

도구	조회 내용
Context7	각 라이브러리의 최신 버전, 주요 변경사항, 권장 패턴
WebSearch	해당 기술의 트렌드, 커뮤니티 평가, 대안 기술 비교

2-2. 프로젝트 유형 리서치

프로젝트의 도메인/유형에 맞는 리서치 중 2-0에서 확인되지 않은 항목에 대해:

도구	조회 내용
WebSearch	동종 프로젝트의 UX 트렌드, 경쟁 제품 기능 비교
WebSearch	해당 도메인의 모범 사례(best practices)

리서치는 핵심 기술 35개 + 도메인 트렌드 12건으로 제한한다 (과도한 조회 방지). RESEARCH 파일에서 이미 다룬 항목은 카운트에서 제외한다.

---

Phase 3: ANALYZE — 종합 분석

Phase 1~2 결과를 종합해 아래 항목을 도출한다:

3-1. 프로젝트 현황 요약

• 프로젝트 목적 및 핵심 가치
• 현재 완성도 (기능별 구현 상태)
• 기술 스택 적합성 평가

3-2. 아키텍처 평가

• 강점 (잘 설계된 부분)
• 약점 (개선 필요 부분)
• 패턴 일관성 점수 (높음/보통/낮음)

3-3. 기술 부채 & 리스크

• 식별된 기술 부채 목록 (심각도 순)
• 보안 리스크
• 성능 리스크
• 유지보수 리스크

3-4. 개선 로드맵

• 즉시 개선 (Quick Win) — 적은 노력으로 큰 효과
• 단기 개선 (1~2주) — 구조적 개선
• 중장기 개선 (1개월+) — 아키텍처 리팩터링

3-5. 기술 트렌드 대비

• 현재 스택 vs 최신 트렌드 비교
• 마이그레이션/업그레이드 권장 사항
• 대안 기술 검토 결과

---

Phase 4: REPORT — 보고서 출력

4-1. 보고서 생성

Write 도구로 아래 경로에 MD 파일을 생성한다:

1. {프로젝트 루트}/docs/analysis/ 폴더가 없으면 Bash로 mkdir -p 생성
2. 주제 슬러그 결정 — 아래 우선순위로 분석 주제를 추출하여 영문 kebab-case 슬러그로 변환한다:

우선순위	소스	예시
1순위	$ARGUMENTS에 명시된 주제/프로젝트명	/analyze FA 업무지원 앱 → fa-support-app
2순위	RESEARCH 파일의 프로젝트: 필드	프로젝트: 보험설계사 업무지원 웹앱 → fa-support-app
3순위	CLAUDE.md 또는 package.json의 프로젝트명	name: "my-project" → my-project
4순위	현재 디렉토리명	D:\workspace\dev-note → dev-note

슬러그 규칙: 영문 소문자 + 하이픈, 최대 30자, 한글은 의미 번역 (예: 보험설계사 → fa, 업무지원 → support)

3. 아래 경로에 파일 생성:

{프로젝트 루트}/docs/analysis/ANALYSIS-{슬러그}-{YYYY-MM-DD}.md

예시: docs/analysis/ANALYSIS-fa-support-app-2026-03-15.md

4-2. 보고서 포맷

# {주제명} 분석 보고서

> 분석일: {날짜}
> 프로젝트: {4-1에서 결정한 주제명 (한글 원문)}
> 분석 관점: {$ARGUMENTS 또는 "전체 분석"}

---

## 1. 프로젝트 개요

### 목적 및 핵심 가치
(프로젝트가 해결하는 문제, 타겟 사용자, 핵심 기능)

### 기술 스택
| 분류 | 기술 | 버전 | 비고 |
|---|---|---|---|
| ... | ... | ... | ... |

### 현재 완성도
(기능별 구현 상태 요약)

---

## 2. 아키텍처 분석

### 구조 개요
(디렉토리 트리 + 레이어 설명)

### 데이터 흐름
(입력 → 처리 → 출력 경로)

### 사용 패턴
(식별된 디자인 패턴 목록 + 설명)

### 평가
| 항목 | 평가 | 근거 |
|---|---|---|
| 레이어 분리 | 높음/보통/낮음 | ... |
| 패턴 일관성 | 높음/보통/낮음 | ... |
| 확장성 | 높음/보통/낮음 | ... |
| 테스트 가능성 | 높음/보통/낮음 | ... |

---

## 3. 코드 품질

### 강점
(잘 작성된 부분, 우수한 패턴)

### 기술 부채
| # | 항목 | 심각도 | 위치 | 설명 |
|---|---|---|---|---|
| 1 | ... | 🔴/🟡/🟢 | 파일:라인 | ... |

### 보안 점검
(OWASP 기준 점검 결과)

### 성능 점검
(병목 가능 지점)

---

## 4. 기술 트렌드 대비

### 스택 최신성
| 기술 | 현재 버전 | 최신 버전 | 상태 |
|---|---|---|---|
| ... | ... | ... | ✅ 최신 / ⚠️ 업데이트 권장 / 🔴 EOL |

### 대안 기술 검토
(현재 스택 vs 대안 비교, 전환 필요성 평가)

---

## 5. 개선 로드맵

### 즉시 개선 (Quick Win)
- [ ] ...

### 단기 개선 (1~2주)
- [ ] ...

### 중장기 개선 (1개월+)
- [ ] ...

---

## 6. 리서치 출처
(WebSearch, Context7에서 참조한 주요 자료)

---

> 이 보고서는 Claude Code `/analyze` 스킬로 자동 생성되었습니다.

4-3. 사용자에게 요약 출력

보고서 생성 후 터미널에 핵심 요약을 출력한다:

📊 프로젝트 분석 완료
──────────────────────────────
프로젝트:    {주제명}
보고서:      {경로}/ANALYSIS-{슬러그}-{날짜}.md
──────────────────────────────
[아키텍처]   {한줄 평가}
[코드 품질]  기술 부채 {N}건 (🔴{n} 🟡{n} 🟢{n})
[최신성]     {N}개 중 {n}개 업데이트 권장
[Quick Win]  {N}건 식별
──────────────────────────────
상세 내용은 보고서를 확인하세요.

---

특수 인자

인자	설명
--arch-only	아키텍처 분석만 수행 (Phase 1-2의 Agent B + Phase 3-2만)
--quality-only	코드 품질 리뷰만 수행 (Phase 1-2의 Agent C + Phase 3-3만)
--no-research	외부 리서치(Phase 2) 생략, 코드베이스 분석만
--stdout	MD 파일 생성 없이 터미널에 전체 보고서 출력

---

주의사항

• 코드 수정 금지 — 이 스킬은 읽기 전용 분석만 수행한다
• 보고서에 민감 정보(API 키, 비밀번호 등)를 포함하지 않는다
• 에이전트 결과가 충돌할 경우, 코드 증거가 있는 쪽을 우선한다
• 리서치는 핵심 기술에 집중하고, 마이너 유틸리티까지 조회하지 않는다
• 기존 ANALYSIS-*.md 파일이 있으면 덮어쓰지 않고 날짜로 구분한다
• 보고서는 반드시 docs/analysis/ 폴더에 저장한다 (프로젝트 루트에 직접 생성 금지)