zioinfo-mail/.claude/skills/workspace-analyzer/SKILL.md

---
name: workspace-analyzer
description: >
  워크스페이스에 소스코드를 넣으면 자동으로 분석·하네스 적용·개발환경 가이드를 제공하는 스킬.
  다음 상황에서 반드시 사용:
  (1) "workspace 폴더에 소스 넣었어", "소스 분석해줘", "하네스 적용해줘" 요청;
  (2) workspace/ 하위 폴더에 새 프로젝트가 있을 때;
  (3) "개발환경 가이드", "이 소스 어떻게 돌려?", "의존성 뭐야?" 질문;
  (4) "프로젝트 분석", "코드베이스 파악", "기술스택 알려줘" 요청;
  (5) 처음 보는 레포지토리를 분석해야 할 때.
  workspace/ 폴더에 소스가 없을 때도 분석 요청이 오면 이 스킬을 먼저 실행하라.
---

# Workspace 소스 자동분석 + 하네스 적용 + 개발환경 가이드

소스코드를 `workspace/<프로젝트명>/` 에 넣으면 자동으로 3단계를 수행한다.

---

## Phase 0: 워크스페이스 탐색

```
1. Glob("workspace/**") 으로 프로젝트 폴더 목록 확인
2. 분석 대상 폴더 결정:
   - 사용자가 폴더명을 명시한 경우 → 해당 폴더
   - 명시 없으면 가장 최근 수정된 폴더 (수정 시간 기준)
   - 폴더가 없으면 → "workspace/<프로젝트명>/ 폴더를 만들고 소스를 넣어주세요." 안내
```

---

## Phase 1: 기술스택 자동 탐지

아래 파일 존재 여부로 스택을 판별한다.

| 파일 | 스택 |
|------|------|
| `pom.xml` / `build.gradle` | Java (Maven/Gradle) |
| `package.json` | Node.js / React / Vue / Next.js |
| `requirements.txt` / `pyproject.toml` / `setup.py` | Python |
| `composer.json` | PHP |
| `Gemfile` | Ruby on Rails |
| `go.mod` | Go |
| `Cargo.toml` | Rust |
| `*.csproj` / `*.sln` | .NET / C# |
| `Dockerfile` / `docker-compose.yml` | 컨테이너 |
| `.env.example` / `application.yml` | 설정 파일 |

**탐지 순서:**
1. Glob으로 루트 파일 목록 확인
2. 없으면 1~2 depth 하위까지 탐색
3. 여러 스택 감지 시 → 멀티스택으로 처리

---

## Phase 2: 심층 분석 (스택별)

### Java 프로젝트
```
필독 파일: pom.xml 또는 build.gradle (의존성), src/main/resources/application*.yml (설정)
분석 항목:
  - Spring Boot 버전, JDK 버전
  - 주요 의존성 (JPA, Security, MyBatis, Redis 등)
  - DB 설정 (datasource)
  - 포트 (server.port, 기본 8080)
  - 프로파일 구조 (dev/stg/prd)
  - 테스트 프레임워크 (JUnit 5, Mockito)
```

### Python 프로젝트
```
필독 파일: requirements.txt 또는 pyproject.toml, .env.example
분석 항목:
  - FastAPI/Django/Flask/Flask 버전
  - Python 버전 (.python-version, runtime.txt)
  - DB ORM (SQLAlchemy, Django ORM, Tortoise)
  - 주요 패키지 (celery, redis, boto3 등)
  - 실행 진입점 (main.py, app.py, manage.py, wsgi.py)
```

### Node.js 프로젝트
```
필독 파일: package.json, .env.example, next.config.js
분석 항목:
  - 프레임워크 (Next.js, Express, Nest.js, React 순수)
  - Node 버전 (.nvmrc, engines 필드)
  - 주요 의존성 (ORM, auth, 상태관리 등)
  - scripts 명령어 (start, build, dev, test)
  - 빌드 도구 (webpack, vite, turbopack)
```

### PHP 프로젝트
```
필독 파일: composer.json, .env.example
분석 항목:
  - 프레임워크 (Laravel, Symfony, CodeIgniter, 순수 PHP)
  - PHP 버전 (require 필드)
  - DB (Eloquent, Doctrine, mysqli)
  - 아티즌 명령어 (Laravel일 때)
```

---

## Phase 3: 분석 결과 리포트

다음 형식으로 사용자에게 보고한다:

```markdown
## 소스 분석 결과: {프로젝트명}

### 기술 스택
- 언어: {언어 및 버전}
- 프레임워크: {프레임워크 및 버전}
- DB: {DB 종류}
- 기타: {주요 라이브러리}

### 프로젝트 구조
{핵심 폴더/파일 트리 — 5~10개}

### 진입점
- 실행 명령: `{실행 명령어}`
- 기본 포트: {포트번호}
- 설정 파일: `{설정 파일 경로}`
```

---

## Phase 4: 개발환경 가이드 생성

스택에 맞는 설치 명령어와 실행 방법을 단계별로 제공한다.

### Java (Spring Boot)
```bash
# 1. JDK 설치 확인
java -version   # JDK 17+ 필요 (pom.xml java.version 확인)

# 2. 빌드 (Maven)
./mvnw clean package -DskipTests

# 3. DB 설정 (application-local.yml 생성)
# spring.datasource.url, username, password 설정

# 4. 실행
./mvnw spring-boot:run -Dspring-boot.run.profiles=local
# 또는
java -jar target/{artifact}.jar --spring.profiles.active=local
```

### Python (FastAPI/Django)
```bash
# 1. 가상환경
python3.11 -m venv venv && source venv/bin/activate  # Linux/Mac
python -m venv venv && venv\Scripts\activate          # Windows

# 2. 의존성 설치
pip install -r requirements.txt

# 3. 환경변수 설정
cp .env.example .env   # .env 편집 후 DB URL, SECRET_KEY 설정

# 4. DB 초기화 (있으면)
alembic upgrade head   # 또는 python manage.py migrate

# 5. 실행
uvicorn main:app --reload --port 8000   # FastAPI
python manage.py runserver 0:8000       # Django
```

### Node.js
```bash
# 1. Node.js 버전 확인 (.nvmrc 있으면 nvm use)
node --version

# 2. 의존성 설치
npm install   # 또는 yarn install / pnpm install

# 3. 환경변수
cp .env.example .env

# 4. DB 마이그레이션 (있으면)
npx prisma migrate dev   # Prisma
npm run typeorm:migration:run   # TypeORM

# 5. 실행
npm run dev   # 개발
npm run build && npm start   # 빌드 후 실행
```

---

## Phase 5: 하네스 적용

프로젝트 유형에 따라 `.claude/` 하네스를 자동 생성한다.

### 하네스 생성 원칙
- `workspace/{project}/.claude/agents/` 에 에이전트 생성
- `workspace/{project}/.claude/skills/` 에 스킬 생성
- 프레임워크 특성에 맞는 전문 에이전트 구성

### Java Spring Boot 하네스 구성
| 에이전트 | 역할 |
|---------|------|
| `java-dev` | 기능 개발, 테스트 작성 |
| `db-migrator` | 엔티티/마이그레이션 관리 |
| `api-reviewer` | REST API 설계 검토 |

스킬: `run-tests`, `build-check`, `api-spec`

### Python FastAPI 하네스 구성
| 에이전트 | 역할 |
|---------|------|
| `py-dev` | 기능 개발, 의존성 관리 |
| `db-migrator` | Alembic 마이그레이션 |
| `test-runner` | pytest 실행 및 커버리지 |

스킬: `run-tests`, `lint-check`, `type-check`

### Node.js 하네스 구성
| 에이전트 | 역할 |
|---------|------|
| `frontend-dev` | 컴포넌트/페이지 개발 |
| `backend-dev` | API 라우터 개발 |
| `test-runner` | Jest/Vitest 실행 |

스킬: `lint`, `type-check`, `build-check`

### 범용 에이전트 (모든 프로젝트 공통)
| 에이전트 | 역할 |
|---------|------|
| `code-reviewer` | PR 리뷰, 보안 검토 |
| `doc-writer` | README, API 문서 생성 |

---

## Phase 6: CLAUDE.md 자동 생성

`workspace/{project}/CLAUDE.md` 를 자동 생성한다. 포함 내용:
- 프로젝트 개요 및 기술스택
- 디렉토리 구조 (핵심 경로만)
- 실행 명령어 (개발/빌드/테스트)
- 환경변수 목록
- 보안 주의사항 (있으면)
- 하네스 트리거 규칙

---

## 실행 흐름 요약

```
사용자가 소스를 workspace/<proj>/에 넣음
    ↓
Phase 0: workspace/ 탐색
    ↓
Phase 1: 기술스택 파일 탐지 (Glob)
    ↓
Phase 2: 핵심 파일 읽기 (Read)
    ↓
Phase 3: 분석 리포트 출력
    ↓
Phase 4: 개발환경 가이드 출력
    ↓
Phase 5: .claude/ 하네스 생성 (에이전트 + 스킬)
    ↓
Phase 6: CLAUDE.md 생성
    ↓
사용자 확인 → 추가 분석 or 개발 시작
```

---

## 주의사항

- **보안**: 소스 내 `.env`, `secrets.yml`, 비밀번호 패턴 발견 시 즉시 경고
- **외부 API 금지**: 분석 중 외부 서비스 호출 금지 (Ollama만 허용)
- **파일 무결성**: workspace/ 소스를 수정하지 않는다 — 분석과 가이드만
- **대용량 파일**: 10,000줄 이상 파일은 헤더/핵심 섹션만 읽는다