aiskillstore 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) |
리서치는 핵심 기술 3
5개 + 도메인 트렌드 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 파일을 생성한다:
{프로젝트 루트}/docs/analysis/폴더가 없으면 Bash로mkdir -p생성- 주제 슬러그 결정 — 아래 우선순위로 분석 주제를 추출하여 영문 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)
- 아래 경로에 파일 생성:
{프로젝트 루트}/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/폴더에 저장한다 (프로젝트 루트에 직접 생성 금지)