Imported from Leesin0222/claude-skills-for-yongjin (skills/project-analyze/SKILL.md). Install upstream with npx skills add Leesin0222/claude-skills-for-yongjin --skill project-analyze. Copyright stays with the author.

Project Analyze Skill

어떤 프로젝트든 코드베이스를 전체 분석하여, 후임자가 이 문서 하나만 읽고 바로 실무에 투입될 수 있는 수준의 프로젝트 분석 문서를 생성한다.

단순 README(설치/실행 방법)가 아니라, 왜 이렇게 짰는지, 어디를 건드리면 뭐가 깨지는지, 실무에서 자주 하는 작업이 뭔지를 담는 것이 핵심이다.

1. Input

별도 입력 없이도 동작한다. 프로젝트 루트에서 호출하면 자동으로 분석을 시작한다.

선택 입력

• 강조할 영역: "백엔드 중심으로", "프론트 위주로" 등
• 대상 독자 수준: "시니어 개발자", "주니어 개발자", "비개발자" (기본: 중급 개발자)
• 기존 문서 경로: 업데이트할 기존 파일이 있으면 지정

2. 분석 프로세스

Step 1: 프로젝트 메타 정보 수집

1-1. 프로젝트 설정 파일 읽기

우선순위대로 탐색하여 기술 스택과 프로젝트 기본 정보를 파악한다:

1-2. 기존 문서 확인

• .claude/CLAUDE.md — 프로젝트 설정 정보
• README.md — 기존 설명
• CONTRIBUTING.md, ARCHITECTURE.md 등 보조 문서
• docs/ 디렉토리

Step 2: 코드베이스 심층 분석

2-1. 디렉토리 구조 파악

• 프로젝트 루트의 주요 디렉토리를 Glob으로 탐색 (깊이 3 수준)
• .gitignore 대상 제외
• 각 디렉토리의 역할과 책임을 코드를 읽어서 파악

2-2. 아키텍처 패턴 분석

• 아키텍처 스타일 식별 (레이어드 / 헥사고날 / feature-based / 모노리스 / 마이크로서비스 등)
• 주요 컴포넌트 간 의존 관계 파악
• 데이터 흐름 추적 (요청 → 처리 → 응답 경로)

2-3. 핵심 비즈니스 로직 파악

• 엔트리포인트 (main.*, index.*, app.*, server.*) 에서 시작
• 주요 도메인 모델/엔티티 식별
• 핵심 비즈니스 로직이 어느 파일/모듈에 있는지 매핑
• 외부 시스템 연동 지점 (API 호출, DB 접근, 메시지 큐 등)

2-4. 패턴과 컨벤션 추출

• 네이밍 컨벤션 (파일명, 변수명, 함수명)
• import/export 패턴
• 에러 처리 방식
• 상태 관리 방식 (프론트엔드인 경우)
• API 호출 패턴
• 테스트 작성 패턴

2-5. 인프라/배포 구조 파악

• 배포 환경 (Vercel, AWS, GCP, Docker 등)
• CI/CD 파이프라인 워크플로우
• 환경별 설정 (dev / staging / production)
• 모니터링/로깅 구조 (있으면)

Step 3: 문서 생성

아래 포맷으로 초안을 생성하여 대화창에 먼저 보여준다.

Step 4: 사용자 확인 및 저장

• 사용자가 수정 요청하면 반영한다
• 확인 후 프로젝트 루트에 저장한다
• 파일명: PROJECT-ANALYSIS.md (기본) 또는 사용자 지정
• 기존 파일이 있으면 덮어쓸지/백업할지 확인한다

3. 프로젝트 분석 문서 포맷

# {프로젝트명} — 프로젝트 분석

**작성일:** {YYYY-MM-DD}
**분석 기준:** 코드베이스 자동 분석

---

## 한눈에 보기

> 이 프로젝트가 **뭘 하는 건지**, **누가 쓰는 건지**, **핵심이 뭔지** 3~5줄로.

- **한 줄 요약**: ...
- **서비스 대상**: ...
- **핵심 가치**: ...

---

## 기술 스택

| 영역 | 기술 | 버전 | 비고 |
|------|------|------|------|
| 언어 | TypeScript | 5.x | strict 모드 |
| 프레임워크 | Next.js | 14 | App Router 사용 |
| DB | PostgreSQL | 15 | Supabase 경유 |
| 상태관리 | Zustand | | |
| 스타일링 | Tailwind CSS | | |
| 테스트 | Vitest + Playwright | | |
| 배포 | Vercel | | |

---

## 아키텍처 개요

### 전체 구조

> 시스템이 어떻게 구성되어 있는지. 컴포넌트 간 관계.

```mermaid
graph TD
    ...

핵심 설계 결정과 이유

이게 제일 중요하다. 왜 이런 구조를 선택했는지.

프로젝트 구조

{project}/
├── src/
│   ├── app/            # Next.js App Router 페이지
│   ├── features/       # 기능별 모듈 (도메인 로직 집중)
│   │   ├── auth/       # 인증/인가
│   │   └── payment/    # 결제
│   ├── components/     # 공통 UI 컴포넌트
│   ├── lib/            # 외부 서비스 연동 (DB, API 클라이언트)
│   └── utils/          # 순수 유틸리티 함수
├── tests/
├── public/
└── infra/              # IaC, 배포 설정

디렉토리별 상세 설명

핵심 코드 흐름

주요 플로우 1: {예: 사용자 인증}

요청이 들어와서 결과가 나가기까지 코드가 어떤 경로를 타는지.

[사용자 액션] → [어디] → [어디] → [어디] → [결과]

관련 파일:

• src/features/auth/useAuth.ts:L42 — 진입점
• src/lib/supabase/auth.ts:L15 — 실제 인증 처리
• src/app/api/auth/route.ts:L8 — API 엔드포인트

주요 플로우 2: {예: 결제 처리}

...

데이터 모델

주요 엔티티

엔티티 간 관계

erDiagram
    ...

코드 컨벤션과 패턴

이 프로젝트에서 코드를 짤 때 따라야 하는 규칙들.

파일/네이밍

• 컴포넌트: PascalCase (UserProfile.tsx)
• 유틸리티: camelCase (formatDate.ts)
• 타입: types.ts에 모아서 관리
• 테스트: __tests__/ 하위 또는 .test.ts

자주 쓰는 패턴

// 예: API 호출 패턴 — 이 프로젝트에서는 이런 식으로 짠다

피해야 할 패턴 (안티패턴)

• 코드에서 발견된 기술 부채나 "이렇게 하면 안 되는" 패턴
• 레거시 코드가 있으면 어디인지, 왜 남아있는지

외부 시스템 연동

로컬 개발 환경

사전 요구사항

• Node.js >= 18
• pnpm >= 8
• Docker (DB 로컬 실행 시)

셋업

git clone {repo}
cd {project}
pnpm install
cp .env.example .env  # 필요한 값 입력
pnpm dev

환경변수

주요 명령어

배포

환경 구성

CI/CD 파이프라인

push → lint/test → build → deploy (환경별)

배포 시 주의사항

• DB 마이그레이션이 포함된 배포는 ...
• 환경변수 추가 시 ...

자주 하는 작업 가이드

실무에서 매일 하는 작업을 바로 할 수 있게.

새 기능 추가할 때

1. src/features/{feature-name}/ 디렉토리 생성
2. ...
3. ...

API 엔드포인트 추가할 때

1. src/app/api/{endpoint}/route.ts 생성
2. ...

DB 스키마 변경할 때

1. ...

지뢰밭 (주의 영역)

여기 건드리면 이거 깨진다 — 후임자가 가장 알아야 할 것.

알려진 기술 부채

관련 자료

• 기획 문서: {링크}
• 디자인: {링크}
• API 문서: {링크}
• 모니터링 대시보드: {링크}

---

## 4. 섹션별 작성 가이드

### 한눈에 보기
- 비개발자가 읽어도 이해할 수 있는 수준
- "이 프로젝트 뭐 하는 거야?" 에 대한 답

### 아키텍처 개요 — 핵심 설계 결정과 이유
- **이 문서에서 가장 중요한 섹션**
- 코드에서 추론 가능한 설계 결정의 이유를 적는다
- 확실하지 않으면 "[추론] ~로 보임" 형태로 표기
- 왜 이 라이브러리를 쓰는지, 왜 이 구조인지

### 핵심 코드 흐름
- 주요 유저 시나리오 2~5개를 코드 레벨로 추적
- 각 단계에서 **어떤 파일의 어떤 함수**를 거치는지 명시
- 파일 경로와 라인 번호까지 포함하면 이상적

### 코드 컨벤션과 패턴
- 실제 코드에서 반복되는 패턴을 추출
- "이 프로젝트에서는 이런 식으로 짠다"를 보여주는 코드 예시 포함
- 안티패턴이 있으면 함께 기록

### 자주 하는 작업 가이드
- **두 번째로 중요한 섹션**
- 후임자가 첫 주에 할 작업을 기준으로 작성
- "새 기능 추가", "버그 수정", "DB 변경" 등 실무 시나리오별 단계

### 지뢰밭
- **세 번째로 중요한 섹션**
- 건드리면 사이드이펙트가 큰 영역
- 코드에서 복잡도가 높거나, 여러 곳에서 참조되는 모듈
- 프로덕션 데이터에 직접 영향을 주는 로직

### 알려진 기술 부채
- 레거시 코드, TODO/FIXME 주석, deprecated 패턴 등
- 코드에서 발견한 것만 기록 (추측 금지)

---

## 5. 프로젝트 타입별 조정

### 웹 애플리케이션 (프론트엔드)
- 라우팅 구조, 페이지 목록 섹션 추가
- 컴포넌트 계층 구조 설명
- 전역 상태 관리 플로우

### API / 백엔드 서버
- API 엔드포인트 전체 목록 (메서드, 경로, 설명)
- 미들웨어 체인 설명
- DB 스키마 개요

### 모바일 앱
- 화면 플로우 / 네비게이션 구조
- 네이티브 모듈 연동 지점
- 빌드/배포 프로세스 (iOS/Android 분리)

### 모노레포
- 패키지 목록과 각 패키지의 역할
- 패키지 간 의존 관계
- 공통 모듈과 개별 모듈 구분

### 라이브러리 / SDK
- 공개 API 레퍼런스
- 사용 예제 코드
- 버전 호환성

---

## 6. 기존 문서 업데이트 모드

기존 분석 문서가 있는 경우:

1. 기존 파일을 읽어서 구조와 내용을 파악한다
2. 현재 코드베이스와 비교하여 **낡은 정보**를 식별한다
3. 변경된 부분만 업데이트한 초안을 제시한다
4. 기존 문서의 어조와 스타일을 유지한다
5. 사용자가 직접 작성한 내용은 보존한다

---

## 7. 주의사항

- **코드 근거 필수**: 추측하지 않는다. 코드에서 확인할 수 없는 내용은 `[확인 필요]`로 표기한다
- **과대 포장 금지**: 실제 구현된 것만 기술한다
- **비밀 정보 제외**: `.env` 실제 값, API 키, 내부 URL, 인증 정보는 절대 포함하지 않는다
- **언어**: 기존 문서의 언어를 따르고, 새로 만드는 경우 사용자에게 한국어/영어 중 선택을 물어본다
- **분량 조절**: 프로젝트 규모에 비례하되, 핵심 정보 위주로. 작은 프로젝트에 대해 억지로 모든 섹션을 채우지 않는다