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

name	description
workspace-analyzer	워크스페이스에 소스코드를 넣으면 자동으로 분석·하네스 적용·개발환경 가이드를 제공하는 스킬. 다음 상황에서 반드시 사용: (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: 분석 결과 리포트

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

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

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

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

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

---

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

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

Java (Spring Boot)

# 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)

# 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

# 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줄 이상 파일은 헤더/핵심 섹션만 읽는다