sub-codebase-explorer - SKILL.md Agent Skill

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

언어/프레임워크 무관: Kotlin/Java/Python/Go/TypeScript/Ruby 모두 1급 시민
결정론적 분석: 모든 감지는 ast-grep + bash + jq + git만 사용 (LLM 추론 없이 재현 가능)
개별 md 분리: 각 API 호출/이벤트 토픽마다 1개 md 파일 → diff/PR 리뷰 친화적
두 호출 경로: /sub-codebase-explorer 직접 호출과 sub-team-lead 라우팅 모두 1급 지원
캐시 활용: ~/.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 전용 모드