# Sub Codebase Explorer

> 다언어 코드베이스 분석 전문가. 프로젝트 구조 발견(Kotlin/Java/Python/Go/TS/Ruby), 모듈 의존성 그래프 + 순환 의존성 탐지, Git hotspot 분석, 데드코드 식별, 도메인 모델 추출, MSA API 호출/이벤트 토폴로지 매핑(개별 md 자동 생성), ARCHITECTURE.md/ONBOARDING.md 자동 생성을 수행한다. Activated by keywords: "explore", "codebase", "legacy", "architecture", "dependency graph", "hotspot", "deadcode", "onboarding", "msa", "microservice", "event flow", "sequence diagram", "코드베이스", "레거시", "온보딩", "의존성", "아키텍처 분석", "마이크로서비스", "이벤트 발행", "시퀀스".

- Skill: `hungrytech/sub-codebase-explorer` (Agent Skill, multi-file: 80 files)
- Install (CLI): `npx skillmds@latest add hungrytech/sub-codebase-explorer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hungrytech/sub-codebase-explorer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: hungrytech (https://skillmd.com/u/hungrytech)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/hungrytech/sub-codebase-explorer

---


# Sub Codebase Explorer — 다언어 코드베이스 분석가

> 기존 프로젝트(레거시 모노리스, 폴리글랏 모노레포, MSA)를 빠르게 이해할 수 있도록 구조를 발견·시각화하고 온보딩 문서를 자동 생성하는 전문가.

## Role

신규 합류 개발자가 "어떤 아키텍처인가? 어느 파일부터 읽어야 하나? 모듈 간 어떻게 통신하는가?" 같은 질문에 즉시 답할 수 있도록, 코드/Git 히스토리를 정적·통계적으로 분석하여 의존성 그래프, hotspot 리포트, MSA 토폴로지, ARCHITECTURE.md, ONBOARDING.md를 만든다.

### Core Principles

1. **언어/프레임워크 무관**: Kotlin/Java/Python/Go/TypeScript/Ruby 모두 1급 시민
2. **결정론적 분석**: 모든 감지는 ast-grep + bash + jq + git만 사용 (LLM 추론 없이 재현 가능)
3. **개별 md 분리**: 각 API 호출/이벤트 토픽마다 1개 md 파일 → diff/PR 리뷰 친화적
4. **두 호출 경로**: `/sub-codebase-explorer` 직접 호출과 `sub-team-lead` 라우팅 모두 1급 지원
5. **캐시 활용**: `~/.claude/cache/sub-codebase-explorer-{hash}-*` (30일 만료, 모노레포 키 분리)

---

## 호출 경로 (Standalone vs Team-Lead)

### ① 직접 호출 (Standalone)

```bash
/sub-codebase-explorer                              # 전체 파이프라인 (현재 디렉토리)
/sub-codebase-explorer msa /path/to/msa-monorepo    # MSA 모드 + 경로
/sub-codebase-explorer hotspot                      # hotspot 분석만
/sub-codebase-explorer graph ./services             # 의존성 그래프만
/sub-codebase-explorer onboard ./legacy-app         # 온보딩 문서 강조
/sub-codebase-explorer "이벤트 흐름 도식화해줘"        # 자연어 (모드 자동 추론)
```

### ② sub-team-lead 라우팅
```bash
"이 코드베이스 구조 분석해줘"  # → team-lead → classify → sub-codebase-explorer 라우팅
```

| 측면 | 직접 호출 | team-lead 라우팅 |
|------|-----------|------------------|
| 진입점 | `/sub-codebase-explorer` | sister-skill XML invoke |
| 인자 파싱 | `[mode] [TARGET_PATH]` | `<targets>` 본문에서 추출 |
| 결과 반환 | 사용자에게 직접 출력 | `<sister-skill-result>` XML |
| 환경변수 힌트 | `CODEBASE_EXPLORER_OUTPUT_MODE=standalone` | `=sister-skill` |

**Phase 0 (Input Routing)**: SKILL.md 진입 시 가장 먼저 `$ARGUMENTS`를 파싱.
- `<sister-skill-invoke>` 태그가 보이면 team-lead 라우팅 → `<targets>` 추출
- 아니면 standalone → 첫 토큰을 mode로, 두 번째를 TARGET_PATH로 해석
- 알 수 없는 첫 토큰이면 `default` 모드 + 자연어 요청으로 처리

---

## Phase Workflow

```
Phase 0: Input Routing  →  Phase 1: Discover  →  Phase 2: Map (+MSA)
                                                        ↓
        Phase 4: Document  ←─  Phase 3: Diagnose  ←────┘
```

| Phase | 입력 | 출력 | 스킵 조건 |
|-------|------|------|-----------|
| **0 Input Routing** | `$ARGUMENTS` | `mode`, `TARGET_PATH`, `output_mode` 결정 | (필수) |
| **1 Discover** | `TARGET_PATH` | `discover-stack.json` (언어/빌드/프레임워크/MSA 시그널) | 사용자가 스택 명시 |
| **2 Map** | Discover 결과 | `dependency-graph.{json,dot,mmd}` + `circular-deps.json` + (MSA 시그널 시) `msa-api-calls.json` + `msa-events.json` | `mode in [discover, hotspot, deadcode]` |
| **3 Diagnose** | Map + git log | `hotspot-report.md` + `deadcode-candidates.json` + `domain-model.json` | `mode in [discover, graph, msa]` |
| **4 Document** | 전 단계 산출물 | `ARCHITECTURE.md` + `ONBOARDING.md` + (MSA 시) `msa/` 디렉토리 | `--no-docs` 또는 `mode in [discover, hotspot, deadcode, graph]` |

## Execution Modes

| Mode | 입력 예시 | 활성 Phase |
|------|----------|-----------|
| **default** | `/sub-codebase-explorer` | 1+2+3+4 (MSA 시그널 시 MSA 매핑 자동 포함) |
| **discover** | `/sub-codebase-explorer discover` | 1만 |
| **graph** | `/sub-codebase-explorer graph ./src` | 1+2 (의존성 그래프) |
| **msa** | `/sub-codebase-explorer msa ./services` | 1+2(MSA만)+4(msa/ 디렉토리만) |
| **hotspot** | `/sub-codebase-explorer hotspot` | 1+3(hotspot만) |
| **deadcode** | `/sub-codebase-explorer deadcode` | 1+3(deadcode만) |
| **onboard** | `/sub-codebase-explorer onboard ./legacy` | 1+2+3+4(ONBOARDING.md 강조) |

---

## MSA 매핑 (Phase 2 + Phase 4)

### MSA 시그널 자동 감지 (Phase 1)
다음 중 2개 이상 발견 시 MSA 모드 자동 활성화:
- 다중 서비스 디렉토리 (`services/*/`, `apps/*/`, `packages/*/` + 각각 독립 빌드 파일)
- 메시지 브로커 의존성 (kafka, rabbitmq, sns, sqs, eventbridge, redis-pubsub)
- HTTP 클라이언트 라이브러리 (resttemplate, webclient, openfeign, axios, requests, httpx)
- gRPC proto 정의 (`*.proto` 파일)
- API Gateway 설정 (kong, traefik, envoy, ambassador)

### 개별 md 생성 규칙 (Phase 4)
모든 호출/이벤트마다 1개 md 파일 생성. 파일명 규칙:
- API 호출: `msa/api-calls/{caller}__to__{callee}__{METHOD}-{path-slug}.md`
- 이벤트: `msa/events/topic__{topic-name}.md` 또는 `msa/events/event__{event-class-name}.md`
- 시퀀스: `msa/sequence-diagrams/flow__{scenario-slug}.mmd`

산출물 디렉토리:
```
msa/
├── 00-overview.md                         # C4 컨테이너 다이어그램 (Mermaid)
├── api-calls/                             # 호출별 1개 md
├── events/                                # 토픽별 1개 md
├── sequence-diagrams/                     # 핵심 시나리오 시퀀스 다이어그램
└── service-dependency-matrix.md           # NxN 매트릭스
```

---

## 스크립트 카탈로그

| 스크립트 | 기능 |
|---------|------|
| `scripts/_common.sh` | 해시/캐시/ast-grep 유틸 (sub-kopring-engineer 패턴 차용) |
| `scripts/discover-stack.sh` | 다언어 스택 + MSA 시그널 감지 |
| `scripts/extract-dependencies.sh` | 모듈 import 그래프 → JSON/DOT |
| `scripts/detect-circular-deps.sh` | Tarjan 알고리즘 순환 탐지 |
| `scripts/analyze-git-hotspot.sh` | git log --numstat × 복잡도 |
| `scripts/detect-deadcode.sh` | export/import 매칭 → 미사용 식별 |
| `scripts/extract-domain-model.sh` | @Entity/class → 엔티티 관계 |
| `scripts/extract-msa-api-calls.sh` | HTTP/gRPC 호출 추출 (다언어) |
| `scripts/extract-msa-events.sh` | 이벤트 발행/구독 추출 |
| `scripts/generate-msa-docs.sh` | msa/ 디렉토리 일괄 생성 |

---

## Sister-Skill 연계

| 후속 전문가 | 트리거 | 핸드오프 |
|-------------|-------|----------|
| `sub-code-reviewer` | hotspot 상위 N개 파일 발견 | 파일 목록 → 심층 리뷰 |
| `sub-kopring-engineer` | Kotlin 모듈 식별 + 리팩토링 요청 | 모듈 구조 → 구현 |
| `sub-api-designer` | MSA API 호출 발견 + 컨트랙트 정리 요청 | 호출 인벤토리 → OpenAPI |
| `sub-devops-engineer` | 컨테이너화 미흡 감지 | 스택 인벤토리 → Dockerfile/CI |

---

## 캐시 정책

- 위치: `~/.claude/cache/sub-codebase-explorer-{project_path_hash}-{artifact}.{ext}`
- 키: 프로젝트 경로 MD5 해시 (모노레포 시 `+서비스명`)
- 만료: 30일 자동 정리
- 무효화: `discover-stack.sh`가 빌드 파일 해시 변경 감지 시

---

## Phase 진입 트리거

상세 절차는 단계별 protocol 문서 참조 (lazy load):
- `resources/discover-protocol.md` — Phase 1
- `resources/map-protocol.md` — Phase 2
- `resources/diagnose-protocol.md` — Phase 3
- `resources/document-protocol.md` — Phase 4
- `resources/msa-mapping-protocol.md` — MSA 전용 모드