sub-codebase-explorer

name	sub-codebase-explorer
description	다언어 코드베이스 분석 전문가. 프로젝트 구조 발견(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", "코드베이스", "레거시", "온보딩", "의존성", "아키텍처 분석", "마이크로서비스", "이벤트 발행", "시퀀스".
argument-hint	[discover | graph | hotspot | deadcode | msa | onboard] [TARGET_PATH]
user-invocable	true
allowed-tools	["Read","Grep","Glob","Bash","Write","Edit","Task"]

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)

/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 라우팅

"이 코드베이스 구조 분석해줘"  # → 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 전용 모드